SuperAPI AI 工具集

plan-canvas

办公与效率

查看项目

更新于 11-10 16:20

技能介绍

Plan Canvas 用于计划与可视化产物的审阅反馈闭环:代理写入产物,人类在浏览器中审阅——对具体元素添加批注、聊天,并给出“批准计划”或“请求修改”的结论;代理则通过单次 CLI 调用阻塞等待,将反馈以 JSON 形式取回。

用途与适用场景 刚写好计划产物(例如 /plan 生成的 .claude/plans/*.plan.md),需要 CONFIRM/批准决定时,画布结论可以替代手打“yes/proceed”。当用户应明确指出要改哪里(设计、对比、报告,或任意本地 .md / .html 产物)时,或用户要求 /plan-canvas、可视化审阅、“在浏览器中打开”时也适用。不适用于:diff 代码审查(/code-review)、运行 Web 应用、远程 URL;画布只提供本地产物文件。

使用方式 通过 ecc-plan-canvas 命令调用(该命令由 ecc-universal 包提供,全局/插件安装后在 PATH 中;插件安装也可用 node "$CLAUDE_PLUGIN_ROOT/scripts/plan-canvas.js")。在被审阅的项目中运行,任意工作目录均可。它管理一个由所有会话共享的分离式回环服务器(127.0.0.1:4517),以产物路径为键,无需跟踪会话 ID。工作流是纯 CLI 加 JSON 循环,与模型和运行框架无关:任何能执行 shell 命令并读取 stdout 的代理都可用同样方式驱动(Claude Code、Codex、Cursor、Gemini、OpenCode、Copilot)。触发方式取决于框架暴露技能的方式,例如 Claude Code 中 /plan-canvas、Codex 中 $plan-canvas,或直接运行 ecc-plan-canvas 命令。

典型流程:\n1. 打开产物(立即返回):ecc-plan-canvas open .claude/plans/feature.plan.md\n2. 阻塞等待人类响应,保持运行,若被中断可重新运行,排队反馈不会丢失:ecc-plan-canvas await .claude/plans/feature.plan.md\n只有在 await 实际挂起于该会话时,反馈才会到达代理;若回合结束时无监听,消息会留在队列中,人类侧看起来像是发送无反应。因此在框架支持后台任务时应将 await 作为后台任务运行(Claude Code 中用 run_in_background: true 的 Bash 调用)。反馈到达时它会退出,框架将 JSON 交给代理,从而让循环跨回合存活。前台 await 也可用,但仅在框架超时限制之前有效。有两个兜底手段:ecc-plan-canvas pending 列出无监听者时排队的反馈;stop:plan-canvas-pending 钩子在画布反馈未送达时阻止回合结束并交出消息。\n\nawait 在人类操作时输出 JSON,包含 status: "feedback" 及 items:kind 为 "chat" 的自由文本消息;kind 为 "annotation" 的锚定到元素的反馈(anchor.selector、anchor.snippet 指向位置,anchor.textRange.text 为高亮段落);kind 为 "verdict" 的结论——approve 表示计划已 CONFIRMED,停止轮询、结束会话并开始实施;request-changes 表示修改产物(画布实时重载)并继续循环。\n\n3. 始终在画布中回应,然后继续监听,一条命令即可完成两件事:ecc-plan-canvas await <file> --reply "Split Phase 2 as requested. Take a look."。每条人类消息都应在画布中得到回复,哪怕只是一句“正在重写风险表”。工作中可用活动指示器保持聊天状态真实:ecc-plan-canvas typing <file> --state thinking(动画“agent is thinking...”气泡,长时间工作时刷新)与 --state typing(回复落地前切换为“agent is typing...”)。await 在交出一批反馈时会自动设为 thinking,--reply 会清除它;两种状态都会自动过期。\n\n4. 审阅结束时:ecc-plan-canvas end <file>。\n\n图表(Mermaid)\n当计划涉及流程、架构、时序、状态机、ER 模型或依赖图时,用围栏 ```mermaid 代码块编写而非 ASCII 图或大段文字,画布会将其渲染为可指向的带主题图表。图表使用 ECC 深色主题与强调色板。Mermaid 从固定 CDN 在浏览器中加载;若不可用(离线),代码块退化为显示源码,审阅不被阻塞。可通过 ECC_PLAN_CANVAS_MERMAID_URL 指向本地镜像以供隔离网络使用。\n\n规则\nMarkdown 产物按 ECC 计划模板渲染(包括 Mermaid 块);.html 产物按原样渲染并注入批注层。HTML 编写指导可参考 frontend-design-direction 与 artifact-design 技能。修改时编辑产物文件,画布保存后实时重载,切勿重新运行 open 刷新。返回 {"status": "ended", "endedBy": "user"}(或反馈批次中的 sessionEnded: true)表示用户关闭了审阅:停止轮询,在聊天中交付剩余更新,不要重开;对该会话普通 open 会被拒绝,仅在用户要求恢复时使用 --reopen。同目录资源(图片、CSS)须与产物并排放置并以相对路径引用。服务器仅限回环,空闲 30 分钟后退出(ECC_PLAN_CANVAS_IDLE_MS),stop 可显式关闭。状态存放于 ~/.claude/plan-canvas/(ECC_PLAN_CANVAS_STATE_DIR)。\n\n示例\n计划批准流程:open .claude/plans/notifications.plan.md → await 同文件 → 收到 approve 结论 → end,计划确认后开始实施。修改循环:await 返回批注 → 编辑 .plan.md(画布实时重载)→ 用 --reply 回应 → 继续阻塞等待下一次响应。\n\n反模式\n在循环中用 --timeout-ms 轮询(仅用于测试),应保持普通 await 运行;审阅仍开放时回合结束却无 await 监听(人类会体验为“发了消息没反应”);读取反馈却只在终端回答(人类看的是画布);用户主动结束后仍重开;把整个计划粘贴进聊天又打开画布(应选画布,终端摘要保持一行);从状态文件解析画布聊天(所需内容都通过 await 到达)。