@openprd/cli 0.1.18 → 0.1.19

package/.openprd/engagements/active/prd.md

@@ -1,48 +1,54 @@
-# Vibe Coding 自动化三连：dev-check 自动重构、图标自动匹配、拼图证据入流
+# 画布协同闭环：标注改图、双向结构化工具、尺寸契约与唤起机制
 > 语言规则：用户可见说明、PRD、spec 和 tasks 跟随用户当前主语言；无法判断时才使用简体中文兜底。PRD、OpenPrd、OpenSpec、API、SDK、CLI、TypeScript、JSON、HTTP、WebSocket、字段 key、命令名、品牌名、产品名和协议名等必要专有名词保留原文。
-- 版本: v0012
-- 负责人: Codex
+- 版本: v0014
+- 负责人: OpenPrd
 - 产品场景: 以 Agent 为主要使用场景
 - 场景模板: 以 Agent 为主要使用场景
 - 状态: synthesized
-- 生成时间: 2026-07-03 18:28:06
+- 生成时间: 2026-07-06 22:49:20
 ## 元信息
 
-- 标题: Vibe Coding 自动化三连：dev-check 自动重构、图标自动匹配、拼图证据入流
-- 负责人: Codex
-- 状态: clarifying
-- 版本: v0012
+- 标题: 画布协同闭环：标注改图、双向结构化工具、尺寸契约与唤起机制
+- 负责人: OpenPrd
+- 状态: synthesized
+- 版本: v0014
 - 产品场景: 以 Agent 为主要使用场景
-- 日期: 2026-07-03
+- 日期: 2026-07-06
 
 ## 问题
 
-- 问题陈述: OpenPrd 三项 Vibe Coding 自动化能力不足：1) dev-check 超行提醒停留在后续建议表格，用户不知如何处理，价值鸡肋；2) 开发新功能时图标最佳实践路由几乎从不自动触发（415 个图标相关会话仅 1 次真实接入图标库）；3) 拼图/网格对齐证据板真实触发率低，证据图不在对话流中可视化，AI 自我审查作用未发挥。
-- 为什么是现在: 用户明确反馈不少人用了 OpenPrd 觉得疑惑它到底是干嘛的，希望有一套软件工程视角的标准流程引导；画布做了一半，需要继续对标白板工具补齐人机协同能力。
+- 问题陈述: OpenPrd 画布目前只有单向的“发送给 Codex”整体交接：Agent 不能结构化读取用户在画布上的选区与标注，不能把生成图片精准放回画布锚点旁，标注修改意图靠用户口述或手动截图传递，协同链路断在“人标注完之后”这一步。
+- 为什么是现在: 对标 Cowart 已验证“标注改图闭环 + 画布双向结构化工具 + 生图尺寸契约 + 具名 skill 唤起”四件能力能显著降低人机视觉协同成本；OpenPrd 0.1.18 刚落地生图路由，正好把尺寸契约与路由串起来。
 - 证据:
-  - moticlaw docs/basic 平均行长 440-477 字符、37 行超 500 字符；.openprd 总 5.8GB，quality/reports 5118 份；artifacts/active 280 个版本目录、archive 为 0；对照组 ClipReady/gifeasy 年轻项目文档健康。
+  - Cowart 的 get_cowart_selection / insert_cowart_image / annotation-edit 元数据闭环已被 DeepWiki 调研确认
+  - OpenPrd 画布现状只有 placeholderId 回填和整体 handoff，无结构化选区读取
+  - 用户已确认按对标建议落地四项能力
 
 ## 用户与相关方
 
 - 主要用户:
-  - 用 Vibe Coding 方式做产品的产品经理
+  - 使用 OpenPrd 画布做视觉协同的开发者与产品设计协作者
 - 次要用户:
   - 待补充
 - 相关方:
   - OpenPrd 维护者
-  - 在脏仓库或长程任务中依赖 loop 的项目协作者
+  - Codex/Cursor 上的 Vibe Coding 用户
 
 ## 目标与成功标准
 
 - 目标:
-  - 产品经理任何时刻都能一眼看到自己处在 7 步标准流程的哪一步和下一步动作
-  - 画布接入评审方向导入与流程位置提示，让 PM 在白板上完成方向标注并把结论发回 Agent
+  - 用户在画布上标注后，一句话就能让 Agent 读懂标注并生成修订图放回原图旁
+  - Agent 能结构化读取画布选区并把图片锚定回填
+  - 生图请求自动携带占位卡尺寸契约
+  - 用户能用自然语言稳定唤起画布协同
 - 成功指标:
-  - openprd guide 在需求前/评审中/实现中/收口后各阶段输出正确的当前步骤与下一步
-  - review.html 顶部展示流程位置条
-  - 画布可一键导入当前评审的 designDirections 方向图卡片
+  - 标注改图闭环端到端可走通并有测试覆盖
+  - selection/insert-image API 有集成测试
+  - 尺寸契约出现在生图指引与占位卡 handoff 记录中
 - 验收目标:
-  - 在 openprd 自身仓库通过单元测试与 standards/quality/run verify；用 Codex CLI 在本地跑一个桌面任务实测新流程效果并留下证据。
+  - canvas 服务新增 GET /api/selection 与 POST /api/insert-image 且测试通过
+  - 标注导出带 annotationEdit 元数据并能被 hook 指引消费
+  - hook 对画布协同意图注入引导语
 
 ## 验证与创业闭环
 
@@ -61,7 +67,7 @@
   - 待补充
 - 承诺信号:
   - 待补充
-- 首个低成本验证: synthesize 生成 PRD 与 review.html 后走 change/tasks，再按任务实现并用 Codex CLI 本地桌面任务实测。
+- 首个低成本验证: 生成 change 与任务拆解后按序实现
 - 先活下来方案:
   - 待补充
 - 付费验证信号:
@@ -85,25 +91,32 @@
 ## 范围与非目标
 
 - 范围内:
-  - dev-check 自动重构模式：默认开启，命中 attention/warning 时指示 Agent 本轮直接执行高内聚低耦合拆分（不丢功能），输出改为本次额外处理结果，并支持 --auto-refactor on/off 开关与收口确认话术
-  - 图标最佳实践自动触发：asset-spec 增加功能图标行，design-starter/skills/catalog/hook 把新功能自动配图标写为默认行为
-  - 拼图证据板强化：visual-compare 输出对话流嵌入 markdown，dev-check 对 UI 文件补视觉证据提醒，skills/catalog 把网格对齐证据板写为界面布局场景默认动作
+  - canvas-workspace.js 新增选区状态持久化与查询 API
+  - canvas-workspace.js 新增锚定插图 API（anchorShapeId/placement/replaceHolder）
+  - canvas-app.html.js 标注修改请求导出（带元数据）与选区上报
+  - 生图占位卡尺寸契约写入 handoff 与生图指引
+  - codex-hook-runner-template.mjs 画布协同意图识别与引导注入
+  - agent-canonical-content.js 画布协同指引
+  - docs/basic 与 README 同步
 - 范围外:
-  - 画布实时多人协作
-  - 重写画布为独立前端工程
-  - 改动 Codex 线程桥接协议
+  - 不迁移 tldraw、不做 Codex widget 内嵌
+  - 不新建独立 MCP stdio server，复用画布本地 HTTP 服务
+  - 不改变现有发送给 Codex 的 app-server 桥接协议
 
 ## 场景与流程
 
 - 主流程:
-  - PM 打开终端或让 Agent 运行 openprd guide，看到 7 步流程和当前位置，按提示进入下一步
-  - PM 打开 review.html，顶部流程条显示当前在评审确认步；确认后进入方向选择
-  - PM 打开画布点导入评审方向，3 个方向图变成卡片，圈选标注后用发送给 Codex 把结论发回
+  - 用户在画布圈选原图并批注，点“标注修改请求”，Agent 读标注生成修订图并放回原图右侧
+  - Agent 调 GET /api/selection 读取选中图形结构化数据
+  - Agent 调 POST /api/insert-image 把生成图锚定到指定图形旁
+  - 用户说“打开画布一起改图”即唤起画布协同
 - 边界情况:
-  - 工作区还没有任何需求版本时 guide 显示第 1 步并给出起步动作
-  - 当前评审没有 designDirections 时画布导入按钮提示暂无可导入方向
+  - 无选区时 selection API 返回空且 Agent 收到明确提示
+  - 锚点图形不存在时 insert-image 报错不写脏数据
+  - 占位卡无宽高时尺寸契约退化为默认比例
 - 失败模式:
-  - 方向图片文件缺失时导入跳过该方向并提示，不中断其他方向导入
+  - 画布服务未启动时 API 调用失败要提示先运行 openprd canvas
+  - 回填图片文件缺失时保持画布 scene 不变
 
 ## 可视化图表
 
@@ -111,30 +124,30 @@
 
 ```mermaid
 flowchart LR
-  entry["入口触发<br/>PM 打开终端或让 Agent 运行 openprd guide，看到 7 步流程和当前位置，按提示进入下一步"]
-  experience["产品内步骤<br/>PM 打开 review.html，顶部流程条显示当前在评审确认步；确认后进入方向选择"]
-  decision{"决策点<br/>工作区还没有任何需求版本时 guide 显示第 1 步并给出起步动作"}
-  success(["成功结果<br/>openprd guide 在需求前/评审中/实现中/收口后各阶段输出正确的当前步骤与下一步"])
-  failure[["失败与恢复<br/>方向图片文件缺失时导入跳过该方向并提示，不中断其他方向导入"]]
-  entry -->|"PM 打开终端或让 Agent 运行 openprd guide，看到 7 步流程…"| experience
-  experience -->|"PM 打开 review.html，顶部流程条显示当前在评审确认步；确认后进入方向…"| decision
-  decision -->|"产品经理任何时刻都能一眼看到自己处在 7 步标准流程的哪一步和下一步动作"| success
-  decision -.->|"方向图片文件缺失时导入跳过该方向并提示，不中断其他方向导入"| failure
+  entry["入口触发<br/>用户在画布圈选原图并批注，点“标注修改请求”，Agent 读标注生成修订图并放回原图右侧"]
+  experience["产品内步骤<br/>Agent 调 GET /api/selection 读取选中图形结构化数据"]
+  decision{"决策点<br/>无选区时 selection API 返回空且 Agent 收到明确提示"}
+  success(["成功结果<br/>标注改图闭环端到端可走通并有测试覆盖"])
+  failure[["失败与恢复<br/>画布服务未启动时 API 调用失败要提示先运行 openprd canvas"]]
+  entry -->|"用户在画布圈选原图并批注，点“标注修改请求”，Agent 读标注生成修订图并放回原…"| experience
+  experience -->|"Agent 调 GET /api/selection 读取选中图形结构化数据"| decision
+  decision -->|"用户在画布上标注后，一句话就能让 Agent 读懂标注并生成修订图放回原图旁"| success
+  decision -.->|"画布服务未启动时 API 调用失败要提示先运行 openprd canvas"| failure
 ```
 
 ### 架构
 
 ```mermaid
 flowchart LR
-  users["主要用户<br/>用 Vibe Coding 方式做产品的产品经理"]
+  users["主要用户<br/>使用 OpenPrd 画布做视觉协同的开发者与产品设计协作者"]
   subgraph solution["方案边界"]
-    experience["Agent 使用场景层<br/>PM 打开终端或让 Agent 运行 openprd guide，看到 7 步流程和当前位置，按提示进入下一步 · PM 打开…"]
-    core["核心产品逻辑<br/>OpenPrd 三项 Vibe Coding 自动化能力不足：1) dev-check 超行提醒停留在后续建议表格，用户不知如…"]
-    integrations["依赖与集成<br/>Codex 原生 imagegen（生成 3 方向交互稿图片）；现有 review artifact 渲染与 hash 校验管…"]
-    governance[["约束与可靠性<br/>提交与状态写回不能泄露用户本地无关改动或敏感信息。"]]
-    delivery["验证与交接<br/>openprd guide 在需求前/评审中/实现中/收口后各阶段输出正确的当前步骤与下一步 · review.html 顶部…"]
+    experience["Agent 使用场景层<br/>用户在画布圈选原图并批注，点“标注修改请求”，Agent 读标注生成修订图并放回原图右侧 · Agent 调 GET /api…"]
+    core["核心产品逻辑<br/>OpenPrd 画布目前只有单向的“发送给 Codex”整体交接：Agent 不能结构化读取用户在画布上的选区与标注，不能把生…"]
+    integrations["依赖与集成<br/>依赖 openprd canvas 本地服务 · 依赖 0.1.18 生图路由协议"]
+    governance[["约束与可靠性<br/>不写入敏感信息 · 画布数据留在本地项目目录"]]
+    delivery["验证与交接<br/>标注改图闭环端到端可走通并有测试覆盖 · selection/insert-image API 有集成测试 · 尺寸契约出现在…"]
   end
-  users -->|"PM 打开终端或让 Agent 运行 openprd guide，看到 7 步…"| experience
+  users -->|"用户在画布圈选原图并批注，点“标注修改请求”，Agent 读标注生成修订图并放…"| experience
   experience -->|"产品动作与编排"| core
   core -->|"依赖与外部服务"| integrations
   core -.->|"策略、可靠性与合规"| governance
@@ -146,58 +159,67 @@ flowchart LR
 ## 需求
 
 - 功能需求:
-  - guide 命令基于工作区状态推断 7 步流程位置
-  - review.html 渲染 stepper
-  - canvas /api/review-directions 返回方向元数据与图片
-  - canvas 前端导入方向卡片组
+  - 选区状态随画布保存并可查询
+  - 插图 API 支持 left/right/below 摆放与 holder 替换
+  - 标注导出携带 annotationEdit 与源图形 ID 元数据
+  - 生图占位卡 handoff 记录携带宽高与比例契约
+  - hook 识别画布协同意图并注入闭环指引
 - 非功能需求:
-  - 不新增外部依赖
-  - guide 与画布 API 只读工作区状态，不写状态
-  - 全部文案用 PM 能看懂的普通语言
+  - 界面文案面向普通用户
+  - API 只监听本地回环地址
+  - 新增代码有集成测试覆盖
 - 业务规则:
-  - designDirections 仅在需求被判定涉及界面场景时要求；方向选定必须以 user-confirmed 来源写回；落选方向归档不删除。
+  - 只做已确认四项能力，不扩 UI 引擎替换
+  - 生图仍走 0.1.18 生图路由，不擅用付费 API
 
 ## 业务护栏
 
 - 成本来源:
-  - imagegen 每方向一次调用，共 3 次；报告清理为本地文件操作无外部成本。
+  - 主要成本是生图调用次数与画布服务本地资源
 - 额度与限制:
-  - docs-compact 单次只处理 docs/basic 下的标准文档；retention 默认保留最近 30 份报告可配置。
+  - 首版按单画布会话协同，不开放批量自动改图
 - 滥用防护:
-  - docs-compact 重写稿默认写到 sibling draft 待确认，不直接覆盖原文档；retention 不触碰 evidence 目录中被 latest 报告引用的文件。
+  - insert-image 校验锚点与文件存在性，避免脏写
+  - API 仅本地回环访问
 - 监控信号:
-  - standards verify 输出 docsQuality 结果；doctor 输出 .openprd 体积与报告数量提示。
+  - ops.json handoff 记录数、回填成功率、API 错误率
 - 报警阈值:
-  - 单行超 300 字符 warning；prd.md 落后最新版本超过 20 个版本 warning；quality/reports 超过 200 份提示清理。
+  - 回填连续失败时提示用户检查画布服务状态
 - 止损动作:
-  - 任一清理动作失败即中止并保留原状；归档失败回退为仅提示不移动。
+  - 异常时停止自动回填，保留原画布快照并回退到手动流程
 
 ## 约束、依赖与风险
 
 - 技术约束:
-  - 改动集中在 src/standards.js、src/quality.js、src/openspec/change-lifecycle.js、src/review-presentation.js、src/html-artifacts.js，新增 src/docs-compact.js；skills 生成源同步 openprd-shared / openprd-frontend-design / command-catalog。
+  - 沿用 Excalidraw embed 与现有 canvas-sessions 文件存储
+  - Node 内置测试框架
+  - 不新增外部依赖
 - 合规要求:
-  - 提交与状态写回不能泄露用户本地无关改动或敏感信息。
+  - 不写入敏感信息
+  - 画布数据留在本地项目目录
 - 依赖:
-  - Codex 原生 imagegen（生成 3 方向交互稿图片）；现有 review artifact 渲染与 hash 校验管线。
+  - 依赖 openprd canvas 本地服务
+  - 依赖 0.1.18 生图路由协议
 - 假设:
-  - imagegen 由 Codex 原生 Image 2 提供，OpenPrd 只消费图片路径；review.html 静态打开，选择结果通过现有 canvas/browser handoff 或 review --mark 通道回传；巨行阈值默认 300 字符可配置。
+  - 用户接受标注截图作为修改指令载体
+  - Excalidraw selection 数据足以表达锚定需求
 - 风险:
-  - 流程步骤定义与既有 lane/gate 概念不完全一一对应，guide 只做展示层推断，不改门禁行为
+  - Excalidraw 与 tldraw 数据模型差异导致锚定语义需要适配
+  - 标注文字识别依赖 Agent 视觉能力
 - 开放问题:
-  - 画布方向卡片是否需要内置投票/评分组件，留到下一轮看使用反馈
+  - 后续是否把画布协同扩展为独立 MCP server 另行评估
 
 ## 类型专项模块
 
 - 类型: Agent 使用场景专项
-- humanAgentContract: 用户决定是否进入 loop、是否要求 commit、是否接受 override；Agent 负责在安全前提下创建隔离执行环境，并维护状态与证据闭环。
-- autonomyBoundary: Agent 可以在 loop 运行前准备 worktree、检查脏状态并收集 touched files，但不能在用户未授权 commit 的情况下自动提交，也不能在高风险脏仓库里静默绕过门禁。
-- toolBoundary: 优先使用本地 Git 与 OpenPrd loop 状态完成这次能力，不引入新的远端托管或发布前置依赖。
-- stateModel: change 进入 loop 后，先绑定隔离执行环境，再逐任务 run / verify / finish / commit，并把 worktree、branch、commit 与测试报告写回同一条状态链。
-- evalPlan: 通过 loop 单测、worktree / dirty repo 场景测试、状态持久化测试，以及一次真实隔离 worktree 的串行回归验证这次改动。
+- humanAgentContract: 标注意图由人给出，修订图生成与回填由 Agent 自动完成；替换原图等破坏性动作仍需人确认。
+- autonomyBoundary: Agent 可自动读选区、生成并旁位回填；不得覆盖或删除用户原图与标注。
+- toolBoundary: 使用画布本地 HTTP API、生图路由选定的内置生图工具与 OpenPrd CLI。
+- stateModel: 画布 scene/selection/ops 文件保存在 .openprd/harness/canvas-sessions/<session-key>/。
+- evalPlan: 集成测试覆盖 selection/insert-image/标注导出元数据/hook 引导注入，最终跑 dev-check 与发布前四项验证。
 
 ## 交接
 
-- 负责人: Codex
-- 下一步: synthesize 生成 PRD 与 review.html 后走 change/tasks，再按任务实现并用 Codex CLI 本地桌面任务实测。
-- 目标系统: openprd CLI 自身仓库（harness-engineer/openprd）。
+- 负责人: OpenPrd
+- 下一步: 生成 change 与任务拆解后按序实现
+- 目标系统: OpenPrd CLI 画布子系统

package/README.md

@@ -469,6 +469,26 @@ OpenPrd 生成的 change 会包含标准化维护任务，change 校验也会检
 付费生图 API（例如 OpenAI / Stability key）。路由协议由 install manifest 和
 `.openprd/harness/runtime-environment.json` 的 `imageGenerationRouting` 字段承载。
 
+## 画布协同：标注改图闭环
+
+`openprd canvas .` 打开与当前对话绑定的本地 Excalidraw 画布后，AI 生成的图会
+直接落到画布上，你可以在图上直接画圈、写字做标注，然后点击“发送给 Codex”，
+剩下的交给 Agent：
+
+1. **标注即指令**：画布检测到选区里同时有原图和你的手绘标注时，会把这次交接
+   标记为标注改图请求，把标注截图和结构化元数据（原图 ID、标注 ID）一起交给
+   Agent，Agent 把标注当作修改指令生成新图。
+2. **旁位回填，不覆盖原图**：Agent 通过 `POST /api/insert-image` 用原图作 anchor
+   把新图放到旁边（右/左/上/下可选），你可以左右对比原图和新版，再继续在新图
+   上标注，形成多轮迭代闭环。
+3. **结构化读画布**：Agent 通过 `GET /api/selection` 读到你正在圈选哪些元素的
+   ID、坐标、尺寸和文本，不再只靠截图猜。
+4. **尺寸契约**：AI 生图占位卡的宽高和比例会作为 `sizeContract` 写进生图提示，
+   生成的图片按占位卡比例出图，回填不变形。
+
+唤起方式：在对话里自然地说“打开画布一起看”“我在画布上标注了，按标注改图”
+这类话，hook 会自动注入画布协同指引；也可以直接运行 `openprd canvas . --daemon --open`。
+
 ## 效果图与截图拼图对比，自动优化
 
 当界面任务已经有效果图、设计稿、用户给图或 Agent 自己生成的 mock 时，Agent

package/README_EN.md

@@ -537,6 +537,31 @@ Cost guardrail: OpenPrd never silently calls the user’s own paid image APIs
 The routing contract ships in the install manifest and
 `.openprd/harness/runtime-environment.json` under `imageGenerationRouting`.
 
+## Canvas collaboration: the annotation-to-revision loop
+
+`openprd canvas .` opens a local Excalidraw canvas bound to the current
+conversation. AI-generated images land on the canvas, you draw circles and
+notes directly on top of them, click “Send to Codex”, and the agent takes over:
+
+1. **Annotations become edit instructions**: when a selection contains both an
+   image and hand-drawn annotations, the handoff is tagged as an
+   annotation-edit request with structured metadata (source image IDs,
+   annotation IDs), and the agent treats the marks as revision instructions.
+2. **Side-by-side insertion, never overwriting**: the agent calls
+   `POST /api/insert-image` with the original image as the anchor to place the
+   revised image beside it (right/left/above/below), so you can compare both
+   versions and annotate the new one for another round.
+3. **Structured canvas reads**: `GET /api/selection` gives the agent the IDs,
+   coordinates, sizes, and text of whatever you selected — no more guessing
+   from screenshots.
+4. **Size contract**: placeholder card width/height/aspect ratio travel as a
+   `sizeContract` inside the generation prompt, so images come back at the
+   right ratio without distortion.
+
+To invoke it, just say things like “open the canvas” or “I annotated the image
+on the canvas, revise it accordingly” — the hook injects the collaboration
+guidance automatically. You can also run `openprd canvas . --daemon --open`.
+
 ## Auto-optimized reference-to-screenshot comparison
 
 When UI work already has a reference effect image, design image, user-provided

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openprd/cli",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "AI-native PRD workspace and lifecycle CLI",
   "type": "module",
   "license": "MIT",

package/src/agent-canonical-content.js

@@ -751,6 +751,8 @@ export function renderCommandCatalog() {
     '- `openprd canvas . --thread <id> --thread-title <name> --daemon --open --open-target codex-browser`：持久开启对话协同画布，本地页面按当前 thread/session ID 保存到 `.openprd/harness/canvas-sessions/<session-key>/`，title/name 只用于右侧“当前对话”展示和 daemon 透传，避免多个 Codex / Claude / Cursor 窗口串用同一块画布。若 `runtime-environment.json` 已有当前 hook/session 证据，可省略 `--thread`，若证据里有 `threadTitle/conversationTitle/sessionTitle` 会自动显示；证据不足时必须显式传 `--thread` 或 `--session`，知道标题时同步传 `--thread-title` 或 `--session-title`。`--open-target codex-browser` 表示不要调用系统 `open`，由 Codex Agent 使用右侧 Browser 工具打开返回地址；已验证的 Agent 侧最小路径是 Browser plugin + `node_repl`：`setupBrowserRuntime -> agent.browsers.get("iab") -> visibility.set(true) -> browser.tabs.new() -> tab.goto(url)`。缺少 Codex Browser 证据时 `auto` 会回退系统浏览器。用户点击“发送给 Codex”会在 `ops.json` 里保存 `handoff` 记录，并默认通过本机 Codex app-server `thread/resume -> turn/start` 自动投递到绑定 thread，同时在 `relays/` 留 payload/status/log；只有自动投递被关闭、明确失败或长时间未启动时，才追加 `agent-foreground-relay` 待发送项，由当前 Agent 用 `openprd canvas . --bridge-outbox --claim next` 领取后调用线程工具发送，并用 `--bridge-sent` 或 `--bridge-failed` 回写状态。浏览器网页不能直接调用 Codex Agent 工具；OpenPrd 不提供自己的生图 API，AI 生图仍由 Codex 原生 Image 2/imagegen 完成。不带 `--daemon` 是前台调试模式，会随当前命令结束而停止；停止后台服务使用 `openprd canvas . --thread <id> --stop`。',
     '- Codex 画布协同模式：用户可在画布拖动空白卡片，Agent 可把 Image 2 生成图或本地图片通过本地 canvas service 推入画布并替换选中卡片；用户圈选、标注或选择元素后，可导出图片到该 session 的 `exports/`，并由默认 app-server relay 把文本和本地图片路径提交到绑定线程；Agent 前台接力队列只作为自动投递不可用时的兜底。OpenPrd 不提供自己的生图 API，AI 生图仍由 Codex 原生 `imagegen` / Image 2 完成。',
     '- 画布评审协同：画布右栏顶部“评审协同”区显示当前 7 步流程位置（读取 `/api/guide`），“导入评审方向”按钮会把当前 review 的 designDirections 交互方向连图带说明摆上画布（读取 `/api/review-directions`，已选定方向会标出）；用户可直接在方向图上圈选、批注，再用“发送给 Codex”把反馈回传当前对话。引导用户对交互稿做视觉级反馈时优先走这条路径。',
+    '- 画布结构化协同接口：Agent 不要只靠截图猜画布状态。要知道用户正在圈哪些元素时用 `GET /api/selection` 读取选中元素的 ID、类型、坐标、尺寸、文本和整体 bounds；要把新图放到指定元素旁边时用 `POST /api/insert-image` 带 `anchorElementId` + `placement`（right/left/below/above），不要覆盖原图；回填 AI 生图占位卡仍用 `POST /api/images` 带 `placeholderId`。',
+    '- 画布标注改图闭环：handoff 的 `selection` 为 `annotation-edit` 或带 `sourceImageElementIds` / `annotationElementIds` 时，说明用户在原图上画了标注要求改图。把截图里的标注当修改指令，生成修改后的新图，再用 `POST /api/insert-image` 以原图为 anchor 放到旁边，方便用户对比原图与新版并继续下一轮标注迭代。handoff 或占位卡带 `sizeContract`（width/height/aspectRatio）时，生成图片必须按该宽高比出图，避免回填变形。',
     '- `openprd change . --generate --change <id>`：把 PRD 转成 change。',
     '- `openprd change . --validate --change <id>`：校验 change 结构。',
     '- `openprd tasks . --change <id>`：查看当前 dependency-ready 任务。',