用途:该技能管理 Dreamina Canvas 的身份标识,负责画布的创建、列出与选择,核心是让生成的 projectId 在多个进程间被复用,因为 projectId 是生成调用具备幂等性的唯一依据。详细参考见 references/canvas-context.md。
适用时机:在必须指向特定画布的工作流中,首次执行节点创建、节点编辑或节点运行之前;需要为后续运行选择已有画布时;两个并发脚本需要安全共享同一画布时。不适用于生成节点(由领域技能负责),也不应在无明确用户请求时改动 --use 上下文。
创建规则:调用方需自行生成幂等键,不要让 CLI 生成,例如 PROJECT_ID=$(uuidgen | tr 'A-Z' 'a-z'),并在任何生成调用前持久化,如 echo "$PROJECT_ID" > .state/project-id;随后执行 dreamina-canvas --format json canvas create "我的画布" --project-id "$PROJECT_ID" --use。使用相同 --project-id 重复创建是空操作,会返回已有画布;换用新 --project-id 则每次都会新建画布。
--use 与本地上下文:canvas create --use 会在 dreamina-canvas/contexts/<profile-and-environment>.json 写入所选 projectId,后续省略 --project-id 的命令会回退到该文件。--use 仅在单用户、单进程、顺序流程且调用方愿意丢弃错误默认上下文时安全;当多进程可能并发写入该文件、跨进程重试需复用原始 projectId、或并发自动化需要确定性身份时,应在每次调用显式传入 --project-id <uuid>。
列出:dreamina-canvas --format json canvas ls --limit 20,--limit 与 --offset 用于分页;返回的 projectId 应原样管道传递,不要重新输入。
失败恢复:若 canvas create 返回的 projectId 与传入不一致,视为契约违规,上报用户且不要覆盖已持久化的 id;canvas ls 返回退出码 11 表示需登录,重新认证后再列出;若并发进程报告同一 projectId 被自动创建,应停止,由一个进程持有该 id,其余进程显式传入。
限制:不会在缺少调用方提供的 --project-id 时创建画布;不持久化 OAuth 令牌、cookie、签名 URL 或额度审批令牌;不在显式 --use 请求之外改动上下文文件;付费调用前不会跳过对实时 --project-id 的重新校验。调用前提是已确认安装 dreamina-canvas,且创建时由调用方提供小写 UUID。