@openprd/cli 0.1.11 → 0.1.19

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

@@ -1,88 +1,122 @@
-# OpenPrd loop 隔离 worktree 提交闭环
-> 语言规则：默认用简体中文生成 PRD、spec、tasks 和用户可见说明；除 PRD、OpenPrd、OpenSpec、API、SDK、CLI、TypeScript、JSON、HTTP、WebSocket、字段 key、命令名、品牌名、产品名和协议名等必要专有名词外，其余内容优先写成简体中文。
-- 版本: v0006
-- 负责人: Codex
+# 画布协同闭环：标注改图、双向结构化工具、尺寸契约与唤起机制
+> 语言规则：用户可见说明、PRD、spec 和 tasks 跟随用户当前主语言；无法判断时才使用简体中文兜底。PRD、OpenPrd、OpenSpec、API、SDK、CLI、TypeScript、JSON、HTTP、WebSocket、字段 key、命令名、品牌名、产品名和协议名等必要专有名词保留原文。
+- 版本: v0014
+- 负责人: OpenPrd
 - 产品场景: 以 Agent 为主要使用场景
 - 场景模板: 以 Agent 为主要使用场景
 - 状态: synthesized
-- 生成时间: 2026-06-07 13:07:07
+- 生成时间: 2026-07-06 22:49:20
 ## 元信息
 
-- 标题: OpenPrd loop 隔离 worktree 提交闭环
-- 负责人: Codex
-- 状态: clarifying
-- 版本: v0006
+- 标题: 画布协同闭环：标注改图、双向结构化工具、尺寸契约与唤起机制
+- 负责人: OpenPrd
+- 状态: synthesized
+- 版本: v0014
 - 产品场景: 以 Agent 为主要使用场景
-- 日期: 2026-06-07
+- 日期: 2026-07-06
 
 ## 问题
 
-- 问题陈述: OpenPrd 的 loop 虽然支持逐任务 finish 和可选 commit，但最近没有稳定形成“隔离 worktree + 单任务 commit + 可审查回归”的闭环。当前 loop --run 不会自动切到隔离环境，loop --finish --commit 仍按全仓 git add -A 提交，主工作区一旦有脏改动就容易把无关内容卷进来，导致任务虽然 done 却没有可靠的 commit 留痕。
-- 为什么是现在: 最近一个月里 loop 仍有 finish 通过，但没有稳定产出你期望的逐任务 commit 闭环；当前 openprd 仓库也出现了 done 任务没有 commitSha 的情况。要把 L2 和长程实现真正挂到 loop 上，就需要先把隔离执行、提交流程和状态留痕补齐。
+- 问题陈述: OpenPrd 画布目前只有单向的“发送给 Codex”整体交接：Agent 不能结构化读取用户在画布上的选区与标注，不能把生成图片精准放回画布锚点旁，标注修改意图靠用户口述或手动截图传递，协同链路断在“人标注完之后”这一步。
+- 为什么是现在: 对标 Cowart 已验证“标注改图闭环 + 画布双向结构化工具 + 生图尺寸契约 + 具名 skill 唤起”四件能力能显著降低人机视觉协同成本；OpenPrd 0.1.18 刚落地生图路由，正好把尺寸契约与路由串起来。
 - 证据:
-  - 最近一个月能查到多次 loop finish 通过，但没有对应的 Commit 记录。
-  - 当前 openprd/.openprd/harness/feature-list.json 里 22 个 done 任务的 commitSha 为空。
-  - 现有 loop --run 直接在当前 cwd 执行，未自动创建或切换 worktree。
-  - 现有 loop --finish --commit 仍按 git add -A 提交，提交范围过宽。
-  - 当前隔离副本多为 detached HEAD，缺少稳定的 branch / worktree / commit 绑定。
+  - Cowart 的 get_cowart_selection / insert_cowart_image / annotation-edit 元数据闭环已被 DeepWiki 调研确认
+  - OpenPrd 画布现状只有 placeholderId 回填和整体 handoff，无结构化选区读取
+  - 用户已确认按对标建议落地四项能力
 
 ## 用户与相关方
 
 - 主要用户:
-  - 需要用 OpenPrd loop 执行中等到长程实现的维护者
-  - 希望逐任务 commit、可审查、可回归且不污染主工作区的 Agent 协作者
+  - 使用 OpenPrd 画布做视觉协同的开发者与产品设计协作者
 - 次要用户:
   - 待补充
 - 相关方:
   - OpenPrd 维护者
-  - 在脏仓库或长程任务中依赖 loop 的项目协作者
+  - Codex/Cursor 上的 Vibe Coding 用户
 
 ## 目标与成功标准
 
 - 目标:
-  - 让 loop 在需要时显式进入隔离 worktree / branch 中执行，而不是默认污染主工作区。
-  - 让逐任务 commit 只包含当前任务的改动，便于单独审查和回归。
-  - 让 worktree、branch、commitSha 和 session 形成完整可追踪链路。
+  - 用户在画布上标注后，一句话就能让 Agent 读懂标注并生成修订图放回原图旁
+  - Agent 能结构化读取画布选区并把图片锚定回填
+  - 生图请求自动携带占位卡尺寸契约
+  - 用户能用自然语言稳定唤起画布协同
 - 成功指标:
-  - loop --run 可以显式创建或接入 worktree / branch，或提供等价包装入口。
-  - 主工作区脏时，loop --finish --commit 默认阻断，只有显式豁免才允许继续。
-  - 逐任务 commit 不再使用全仓 git add -A，而是基于 write-scope 或本轮 touched files。
-  - loop-state.json 与 agent-sessions.jsonl 能记录 worktreePath、branch、commitSha。
+  - 标注改图闭环端到端可走通并有测试覆盖
+  - selection/insert-image API 有集成测试
+  - 尺寸契约出现在生图指引与占位卡 handoff 记录中
 - 验收目标:
-  - 在隔离 worktree 中连续完成多个 loop 任务时，每个任务都能生成独立 commit，并把 commitSha 写回状态。
-  - 在脏主工作区直接尝试 finish --commit 时，会收到明确阻断和豁免提示。
-  - 从状态文件和 session 日志可以追溯每个任务对应的 worktree、branch、commit 和测试报告。
-  - 新能力不破坏现有 loop 的 plan、next、run、finish、verify 基本路径。
+  - canvas 服务新增 GET /api/selection 与 POST /api/insert-image 且测试通过
+  - 标注导出带 annotationEdit 元数据并能被 hook 指引消费
+  - hook 对画布协同意图注入引导语
+
+## 验证与创业闭环
+
+- 可触达社区:
+  - 待补充
+- 第一批种子用户:
+  - 待补充
+- 社区契合与触达依据:
+  - 待补充
+- 当前替代方案: 待补充
+- 痛点与替代证据:
+  - 待补充
+- 手工交付路径:
+  - 待补充
+- 手工作战卡:
+  - 待补充
+- 承诺信号:
+  - 待补充
+- 首个低成本验证: 生成 change 与任务拆解后按序实现
+- 先活下来方案:
+  - 待补充
+- 付费验证信号:
+  - 待补充
+- 第一版只做一件事: 待补充
+- 周末级验证: 待补充
+- 最小工具桥接:
+  - 待补充
+- 产品化门槛:
+  - 待补充
+- 第一批客户路径:
+  - 待补充
+- 初始收费假设: 待补充
+- 客户 1 盈利路径: 待补充
+- 销售与增长纪律:
+  - 待补充
+- 可逆性判断: 待补充
+- 客户真问题校验: 待补充
+- 价值观一致性: 待补充
 
 ## 范围与非目标
 
 - 范围内:
-  - 给 openprd loop --run 增加显式 --worktree / --branch，或提供先创建隔离 worktree 再执行的包装入口。
-  - 在 commit 前增加主工作区脏状态门禁和显式 override 机制。
-  - 把提交范围从 git add -A 收窄到 task write-scope 或本轮 touched files。
-  - 把 worktreePath、branch、commitSha 写入 loop-state.json、agent-sessions.jsonl 以及相关状态输出。
+  - 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 同步
 - 范围外:
-  - 不在这次能力里自动 push、开 PR 或发布。
-  - 不做复杂的交互式冲突解决或自动合并策略。
-  - 不强制把每个 task 都拆成独立 worktree；第一版优先支持一个 change / 一段 loop 使用一个隔离 worktree。
-  - 不先重做整套 release / publish 工作流。
+  - 不迁移 tldraw、不做 Codex widget 内嵌
+  - 不新建独立 MCP stdio server，复用画布本地 HTTP 服务
+  - 不改变现有发送给 Codex 的 app-server 桥接协议
 
 ## 场景与流程
 
 - 主流程:
-  - 用户为一个 change 进入 loop 开发时，OpenPrd 可显式创建或接入隔离 worktree 与命名分支，再在其中逐任务运行和提交。
-  - 每个任务验证通过后执行 finish --commit，只提交当前任务 write-scope / touched files，并把 commit 信息写回状态。
-  - 评审或回归时，维护者可从状态文件直接定位 worktree、branch、commitSha 和测试报告。
+  - 用户在画布圈选原图并批注，点“标注修改请求”，Agent 读标注生成修订图并放回原图右侧
+  - Agent 调 GET /api/selection 读取选中图形结构化数据
+  - Agent 调 POST /api/insert-image 把生成图锚定到指定图形旁
+  - 用户说“打开画布一起改图”即唤起画布协同
 - 边界情况:
-  - 用户在脏主工作区里直接尝试 finish --commit。
-  - 当前任务没有可确定的 write-scope，需要回退到 touched files 或明确失败提示。
-  - 已有 worktree 存在但 branch 缺失、处于 detached HEAD 或命名不规范。
-  - 任务验证通过但 commit 写回状态失败，需要保持任务未完全收口并给出修复入口。
+  - 无选区时 selection API 返回空且 Agent 收到明确提示
+  - 锚点图形不存在时 insert-image 报错不写脏数据
+  - 占位卡无宽高时尺寸契约退化为默认比例
 - 失败模式:
-  - 误把主工作区无关改动一起提交。
-  - loop 在 detached HEAD 或错误分支上提交，后续难以审查和回放。
-  - 状态里只标 done 但缺少 commitSha / worktree 信息，导致无法追溯。
-  - 隔离 worktree 创建成功，但后续 run / finish 没有使用同一执行环境。
+  - 画布服务未启动时 API 调用失败要提示先运行 openprd canvas
+  - 回填图片文件缺失时保持画布 scene 不变
 
 ## 可视化图表
 
@@ -90,30 +124,30 @@
 
 ```mermaid
 flowchart LR
-  entry["入口触发<br/>用户为一个 change 进入 loop 开发时，OpenPrd 可显式创建或接入隔离 worktree 与命名分支，再在其中…"]
-  experience["产品内步骤<br/>每个任务验证通过后执行 finish --commit，只提交当前任务 write-scope / touched files…"]
-  decision{"决策点<br/>用户在脏主工作区里直接尝试 finish --commit。"}
-  success(["成功结果<br/>loop --run 可以显式创建或接入 worktree / branch，或提供等价包装入口。"])
-  failure[["失败与恢复<br/>误把主工作区无关改动一起提交。"]]
-  entry -->|"用户为一个 change 进入 loop 开发时，OpenPrd 可显式创建或接入…"| experience
-  experience -->|"每个任务验证通过后执行 finish --commit，只提交当前任务 write…"| decision
-  decision -->|"让 loop 在需要时显式进入隔离 worktree / branch 中执行，而…"| 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/>需要用 OpenPrd loop 执行中等到长程实现的维护者 · 希望逐任务 commit、可审查、可回归且不污染主工作区的 …"]
+  users["主要用户<br/>使用 OpenPrd 画布做视觉协同的开发者与产品设计协作者"]
   subgraph solution["方案边界"]
-    experience["Agent 使用场景层<br/>用户为一个 change 进入 loop 开发时，OpenPrd 可显式创建或接入隔离 worktree 与命名分支，再在其中…"]
-    core["核心产品逻辑<br/>OpenPrd 的 loop 虽然支持逐任务 finish 和可选 commit，但最近没有稳定形成“隔离 worktree …"]
-    integrations["依赖与集成<br/>Git worktree 能力。 · 现有 loop task executionStrategy.writeScope 与 …"]
-    governance[["约束与可靠性<br/>提交与状态写回不能泄露用户本地无关改动或敏感信息。"]]
-    delivery["验证与交接<br/>loop --run 可以显式创建或接入 worktree / branch，或提供等价包装入口。 · 主工作区脏时，loop…"]
+    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 -->|"用户为一个 change 进入 loop 开发时，OpenPrd 可显式创建或…"| experience
+  users -->|"用户在画布圈选原图并批注，点“标注修改请求”，Agent 读标注生成修订图并放…"| experience
   experience -->|"产品动作与编排"| core
   core -->|"依赖与外部服务"| integrations
   core -.->|"策略、可靠性与合规"| governance
@@ -125,76 +159,67 @@ flowchart LR
 ## 需求
 
 - 功能需求:
-  - 支持显式 worktree / branch 配置，或提供隔离运行包装命令。
-  - 支持检测主工作区脏状态，并在 finish --commit 前阻断高风险路径。
-  - 支持基于 write-scope 或 touched files 生成本任务提交集。
-  - 支持在 loop 状态、session 日志和测试报告中记录 commit 关联信息。
-  - 支持为未满足 commit 前置条件的任务给出清晰诊断与恢复指引。
+  - 选区状态随画布保存并可查询
+  - 插图 API 支持 left/right/below 摆放与 holder 替换
+  - 标注导出携带 annotationEdit 与源图形 ID 元数据
+  - 生图占位卡 handoff 记录携带宽高与比例契约
+  - hook 识别画布协同意图并注入闭环指引
 - 非功能需求:
-  - 默认路径必须安全，不能把无关改动静默卷入 commit。
-  - 行为必须可追踪，可从状态文件复原任务执行链路。
-  - 对现有 loop 用户保持兼容，新增能力应尽量显式开启或有明确默认策略。
-  - 失败路径必须可恢复，不能留下半记录状态。
+  - 界面文案面向普通用户
+  - API 只监听本地回环地址
+  - 新增代码有集成测试覆盖
 - 业务规则:
-  - 逐任务 commit 只在任务验证通过后允许执行。
-  - 主工作区脏时默认禁止高风险 commit，除非用户显式豁免。
-  - 状态留痕必须与实际 commit 结果一致，不能先写成功后提交失败。
+  - 只做已确认四项能力，不扩 UI 引擎替换
+  - 生图仍走 0.1.18 生图路由，不擅用付费 API
 
 ## 业务护栏
 
 - 成本来源:
-  - 这次主要要避免无关改动混入 commit、回滚成本升高，以及逐任务审查和回归失去抓手。
+  - 主要成本是生图调用次数与画布服务本地资源
 - 额度与限制:
-  - 默认不允许在脏主工作区直接完成高风险 commit；需要显式进入隔离路径或明确豁免。
+  - 首版按单画布会话协同，不开放批量自动改图
 - 滥用防护:
-  - 不能把未在当前任务范围内的文件静默加入 commit。
-  - 不能把 detached HEAD 上的匿名提交伪装成可回归的标准 loop 结果。
+  - insert-image 校验锚点与文件存在性，避免脏写
+  - API 仅本地回环访问
 - 监控信号:
-  - 需要持续看 loop 任务完成后是否稳定写回 commitSha。
-  - 需要看 worktreePath、branch、commitSha 是否在状态和 session 日志里一致。
-  - 需要看脏主工作区门禁是否挡住了无关改动被带进提交。
+  - ops.json handoff 记录数、回填成功率、API 错误率
 - 报警阈值:
-  - 只要出现用户要求 commit 但任务完成后没有 commitSha，就算这条闭环没有打通。
-  - 只要出现主工作区无关改动被带进 loop commit，就应立即视为高风险回退。
+  - 回填连续失败时提示用户检查画布服务状态
 - 止损动作:
-  - 无法安全判定提交范围时，停止自动 commit，保留任务验证结果并提示人工处理。
-  - worktree / branch 状态异常时，不把任务标记为已完成提交。
+  - 异常时停止自动回填，保留原画布快照并回退到手动流程
 
 ## 约束、依赖与风险
 
 - 技术约束:
-  - 基于现有 openprd loop / git 流程扩展，不重写整套任务调度。
-  - 兼容当前 feature-list、loop-state、agent-sessions 与 test-reports 结构。
-  - 需要同时考虑 worktree、命名分支与 detached HEAD 的兼容行为。
+  - 沿用 Excalidraw embed 与现有 canvas-sessions 文件存储
+  - Node 内置测试框架
+  - 不新增外部依赖
 - 合规要求:
-  - 提交与状态写回不能泄露用户本地无关改动或敏感信息。
+  - 不写入敏感信息
+  - 画布数据留在本地项目目录
 - 依赖:
-  - Git worktree 能力。
-  - 现有 loop task executionStrategy.writeScope 与 finish / verify 流程。
-  - OpenPrd 的状态文件、review / change / tasks 主流程。
+  - 依赖 openprd canvas 本地服务
+  - 依赖 0.1.18 生图路由协议
 - 假设:
-  - 第一版默认以一个 change / 一段 loop 对应一个隔离 worktree 为优先模型，而不是每个 task 一个 worktree。
-  - 已有 task write-scope 在多数实现任务里足够收窄 commit 范围；不足时需要 touched files 补位。
+  - 用户接受标注截图作为修改指令载体
+  - Excalidraw selection 数据足以表达锚定需求
 - 风险:
-  - 如果 worktree / branch 生命周期设计不清，会显著抬高 loop 使用复杂度。
-  - 如果 touched files 收集不稳定，可能出现漏提或误提。
-  - 如果状态写回与 git 操作顺序不当，会出现 done / commitSha 不一致。
+  - Excalidraw 与 tldraw 数据模型差异导致锚定语义需要适配
+  - 标注文字识别依赖 Agent 视觉能力
 - 开放问题:
-  - 第一版是否明确采用一个 change 一个 worktree、一个 task 一个 commit。
-  - worktree / branch 命名规范是否要产品化成 CLI 默认值。
-  - override 脏仓库门禁时，CLI 需要多强的显式确认语义。
+  - 后续是否把画布协同扩展为独立 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
-- 下一步: 完成 review 确认后生成 change 和 tasks，再实现 loop 的隔离 worktree 提交闭环。
-- 目标系统: OpenPrd
+- 负责人: OpenPrd
+- 下一步: 生成 change 与任务拆解后按序实现
+- 目标系统: OpenPrd CLI 画布子系统

package/.openprd/standards/config.json

@@ -54,7 +54,13 @@
         ".md"
       ],
       "exemptPathSegments": [],
-      "exemptFilePatterns": []
+      "exemptFilePatterns": [],
+      "additionalExemptFilePatterns": [
+        "codex-hook-runner-template\\.mjs$"
+      ],
+      "exemptionNotes": {
+        "codex-hook-runner-template.mjs": "单文件 hook runner 模板：被 readFileSync 整体读出并原样安装到用户项目，hook 运行时无法依赖包内其他模块，结构上必须保持单文件；拆分会破坏部署模型，故豁免行数分级。"
+      }
     }
   },
   "growth": {

package/AGENTS.md

@@ -20,32 +20,42 @@
 - `$openprd-benchmark-router`：外部技术、公开 GitHub 仓库、benchmark/对标/最佳实践路由。
 - `$openprd-standards` / `$openprd-quality`：`docs/basic/`、就绪验证、EVO 门禁、知识沉淀。
 - `$openprd-diagram-review` / `$openprd-discovery-loop`：可视评审与长时间只读挖掘。
+- 当前对话环境与平台能力包：优先看 `.openprd/harness/runtime-environment.json`，协议和能力清单看 `.openprd/harness/install-manifest.json` 的 `runtimeDetection` / `platformCapabilityPacks`。
 
 ### 默认行为
 
-1. 动手前先从 `.openprd/` 重建状态，并先运行 `openprd run . --context`；它是建议上下文，不是自动执行指令。
+1. 动手前先判断 executionMode。无人值守自动化（Codex automation、Claude Code headless、cron、scheduled、unattended task）默认不要注入 OpenPrd context，不阻断写入，不要求 `openprd dev-check` / `quality` / `doctor`；除非 automation prompt 明确写明“这是 OpenPrd 维护任务”“显式启用 OpenPrd / enable OpenPrd / openprd-maintenance”。
+1a. 互动或显式启用 OpenPrd 的场景，再从 `.openprd/` 重建状态，并先运行 `openprd run . --context`；它是建议上下文，不是自动执行指令。
+1a. 代码搜索默认从当前任务相关源码、测试和 change/task 文件起步；不要把 `.openprd/quality/reports/`、`.openprd/harness/` 或 `.openprd/learning/` 当源码目录做 repo-wide `rg`。质量报告只在需要审阅就绪证据时按最新报告路径显式读取。
 2. 规划、分析、架构评审、“怎么改”或“会动哪些文件”类请求保持只读；只有用户明确要求实现、继续任务、深度调研、对标复刻或提交时才进入执行。
 3. 先分流再执行：`openprd-requirement-intake` 按影响面、未知数、决策成本和验证成本判断需求类型，并保留内部路由码对照：直接处理=L0，现有功能优化=L1，新功能/新流程方案=L2。用户审查默认把路由码并进“需求类型：直接处理（L0）”这类标签里；只有内部排障确实受益时，才额外附“内部路由码”。直接处理类需求可直接处理并事后说明，不打开正式 PRD/review/change/tasks；现有功能优化先在对话内给 mini-plan 再执行，默认不生成正式 PRD/change/tasks；如果用户刚刚已经确认了 L1 mini-plan、范围边界或正式产品边界，后续承接要写成“已确认，我按这个继续”，不要用“确认，我们就按这个……”这类像再次索取确认的句子。只有新功能/新流程方案才先走 requirement intake、对话内 requirement 摘要确认，再 `review/change/tasks`，最后才实现。L2 的 requirement 摘要默认按“需求判断 / 需求理解 / 功能范围 / 技术方案”来写，其中“功能范围”和“技术方案”优先用 Markdown 表格，帮助用户一眼看清；`需求判断` 和 `需求理解` 先用 1 到 2 句轻量主句说清这次是什么、核心问题和第一版目标，边界、风险、异常例子和技术细节下沉到后面的分项或表格，不要把它们都塞进一整段长话里，也不要把某条示例文案写成固定模板。若当前仍在 0 到 1 探索、脑暴或值不值得做的判断，摘要里还要主动补上“验证与创业闭环”：第一批最容易触达的社区或种子用户、你为什么算这个社区里的自己人、当前替代方案和痛点证据、先怎么手工交付、手工作战卡怎么写、能不能先用 spreadsheet / 表单 / no-code 跑起来、如果必须开始做产品也只自动化最重复的一步并先压成 forms / lists / CRUD 骨架、第一版只做哪一件事、能不能压成周末级 MVP、第一批客户路径、从第一个客户开始怎么收费、客户 1 如何打平成本、有没有 10 个样本和更强付费信号、达到什么条件才允许产品化、增长阶段守什么纪律、这条路是否可逆、是否真在解决客户问题、以及是否符合团队价值观、是不是你愿意长期住进去的业务形态。L2 的首轮澄清只能承诺“我先整理需求摘要给你确认”，不能把 requirement 摘要确认、review 和实现压成一句“你回我一句我就开始实现”。如果 `openprd run . --context` 仍然建议 `clarify-user`，当前这轮回复的目标就只能是 `需求摘要` 或 `1 个最高价值澄清点`，不要写成“我先按默认方案实现”。如果用户的下一条回复只是承接上一轮 requirement 摘要的短跟进，而不是提出新范围、改目标或重新发起分析请求，就把它当成对上一轮摘要、默认方向或选项的继续确认，不要重新开一轮泛化 clarify；应直接按当前对话上下文把已确认事实用 canonical capture 路径、`user-confirmed` 来源写回，而不是继续写 `agent-inferred/project-derived` 的用户澄清字段。单纯的“请帮我实现/继续实现”只表示有执行意图，不表示可以跳过 requirement 摘要确认、`capture/classify/synthesize` 写入路径或 review；只有用户明确表示“不需要进行任何确认”时，才允许静默走完整 requirement write path。`review.html` 是稳定评审 artifact，不再默认等于唯一的人类停顿点；默认按 decision-points approval policy 执行，只有当前 lane 仍要求人类决策时才在 final answer 主体里停下请求确认；当 review 已确认且 tasks 已就绪但还需要执行授权时，先给执行确认清单再请用户确认。
 4. change/tasks 就绪后，用 `openprd-test-strategy` 按风险选择单元、集成、端到端、人工、视觉、小程序、性能或安全验证组合，并在任务或报告中保留 evidence-plan；同时根据任务边界记录 execution strategy：小范围修正保持 `serial`，中等规模 L1/L2 可推荐 `parallel-workers`，高风险或大规模实现再升级到 `parallel-workers-isolated`；70/20/10 只作健康形状参考，不作硬门禁。
-5. 纯图片、封面图、配图、海报、插画、图标、贴纸、mockup 或“先看样子”请求默认直接使用 `imagegen`，也就是 Codex 原生 Image 2；其中 logo、icon、avatar、badge 等开发素材在用户未明确要求场景化展示时，默认按独立素材输出（standalone asset）生成：全画布单主体，不额外添加卡片、设备框或其他展示容器；只有实际发生 `imagegen` 调用后，才能汇报生图结果、失败或限流。生图结果先当候选效果图，不要默认登记到 `.openprd/harness/visual-reviews/`。Agent 要主动确认是否符合预期、是否纳入后续效果图/实现截图对比、以及是否按此继续实现；只有确认后，才把选定方向、整张图或其中子图整理成 reference-set 并进入实现。进入实现阶段时，已有确认参考图用 `openprd visual-compare --reference/--actual`；如果参考图是一张整板、网格图或多对象组合，先运行 `openprd visual-prepare --reference <效果图> --grid <列>x<行>` 或 `--boxes <plan.json>`，确认 contact sheet 后再逐项对比；没有参考图时先判断新建界面还是修改既有界面，新建界面先按用户目标、信息架构变化、视觉决策成本和验证风险完成 3 方向方案评审，修改既有界面用 `openprd visual-compare --before/--after`；局部细节重点则补 `openprd visual-compare --board <focus-board.json>`，多方向实验则补 `openprd visual-compare --board <parallel-board.json>`。用户后续如果说“跟效果图”“不一致”“好丑”“复刻”，不能只口头说对比过了，至少先产出一份视觉证据图。如果用户目标是把工作转成可学习、可复用、可回看、可教学或可沉淀的材料，先按期望产物是否需要章节结构、证据锚点、图文讲解、检索练习、工作示例或长期阅读体验来判断；需要时优先走 `openprd learn .` 生成学习包和阅读器，不要用关键词表触发。
+5. 纯图片、封面图、配图、海报、插画、图标、贴纸、mockup 或“先看样子”请求按生图路由选工具：先判断当前对话工具面，Codex 环境用原生 `imagegen`（Image 2），Cursor 环境用内置 `GenerateImage`，两者都是工具内免费能力；都不可用或无法判断时，先读 `.openprd/harness/image-generation-preference.json` 的用户已确认偏好，没有偏好就先问用户选哪种生图方式，并把答复以 `user-confirmed` 来源写回该文件作为下次默认；绝不擅自调用用户本地或自有付费生图 API。生图工具是工具路径，不是审美豁免，生成前先写清用途、受众、气质、约束和记忆点，并用 anti-slop 避免默认紫白/蓝紫渐变、通用字体、白底卡片堆叠和无语境装饰；其中 logo、icon、avatar、badge 等开发素材在用户未明确要求场景化展示时，默认按独立素材输出（standalone asset）生成：全画布单主体，不额外添加卡片、设备框或其他展示容器；只有实际发生生图工具调用后，才能汇报生图结果、失败或限流。生图结果先当候选效果图，不要默认登记到 `.openprd/harness/visual-reviews/`。Agent 要主动确认是否符合预期、是否纳入后续效果图/实现截图对比、以及是否按此继续实现；只有确认后，才把选定方向、整张图或其中子图整理成 reference-set 并进入实现。进入实现阶段时，已有确认参考图用 `openprd visual-compare --reference/--actual`；如果参考图是一张整板、网格图或多对象组合，先运行 `openprd visual-prepare --reference <效果图> --grid <列>x<行>` 或 `--boxes <plan.json>`，确认 contact sheet 后再逐项对比；没有参考图时先判断新建界面还是修改既有界面，新建界面先按用户目标、信息架构变化、视觉决策成本和验证风险完成 3 方向方案评审，修改既有界面用 `openprd visual-compare --before/--after`；局部细节重点则补 `openprd visual-compare --board <focus-board.json>`，多方向实验则补 `openprd visual-compare --board <parallel-board.json>`；普通截图、Computer/Browser/Playwright 实测截图要作为证据时补 `openprd visual-compare --board <verification-board.json>`；同构列表、卡片、网格、表格或用户反馈没对齐时补 `openprd visual-compare --board <alignment-board.json>`，并同时覆盖容器轨道与内部内容槽位轨道；单个 logo、icon、avatar、badge、按钮图形或图片内部居中/视觉重心/偏心问题补 `openprd visual-compare --board <centering-board.json>`，并同时覆盖画布中心、主体外接框中心和视觉重心偏移。visual evidence 同时检查气质、层级、字体/色彩/表面角色和记忆点，不只检查截图是否存在。用户后续如果说“跟效果图”“不一致”“好丑”“复刻”，不能只口头说对比过了，至少先产出一份视觉证据图。如果用户目标是把工作转成可学习、可复用、可回看、可教学或可沉淀的材料，先按期望产物是否需要章节结构、证据锚点、图文讲解、检索练习、工作示例或长期阅读体验来判断；需要时优先走 `openprd learn .` 生成学习包和阅读器，不要用关键词表触发；“仙侠风格的学习材料”这类短请求也按学习型交付物处理，风格只作为 `--genre` 题材参数。
+5a. 对 logo、icon、avatar、badge、贴纸、空态插画、单物件 UI 位图等开发素材，如果最终要接入 UI 并需要透明背景，默认走“候选评审 -> 资产工程化 -> 接入验证”的图标资产链路：先基于用途、受众、气质、约束和记忆点生成 3 个差异足够大的独立素材候选方向，并保持纯 `#00ff00` 绿幕、无文字、无 UI 容器、主体居中且留足裁切边距；用户选定前不写入项目文件。用户选定后再定位源图或 contact sheet，保留绿幕源图，用 `remove_chroma_key.py` 抠成透明 PNG/WebP，按真实 UI 需要裁切居中并导出 384px 或多尺寸资产；接入时按首页卡片、工具格、吸顶栏、偏好预览等实际场景分别调显示比例，而不是只换图片路径。收口时同步写回 `.openprd/design/active/asset-spec.md` 和 `selected-direction.md`，说明选中的方向、资产路径、透明产物、接入位置和验证结果；最终回复必须区分绿幕源图、透明产物和是否已经接入。
+5b. 卡片宽度、间距、留白、对齐、颜色、圆角、字号、按钮或图标等轻量 UI 可视优化，仍可按 L0/L1 小范围修正推进，不自动升级成大界面 3 方向方案评审；但它是用户可见变化，动手前要有一句审美意图和记忆点，收口必须补 `visual-compare` 修改前后图、局部焦点证据板、截图实测证据板、对齐辅助线证据板或内部居中证据板，并检查气质、层级、颜色、字号、间距和表面角色是否成立。只要界面里有同构列表、卡片、网格或表格，就把容器轨道以及标题、副标题、描述、标签、状态、价格、按钮、图标、操作区等相同文案类型/相同组件槽位的对齐当作默认验收项，不等用户先投诉；只量外框、列宽或行顶不算完整对齐验收。只要任务在判断单个素材/图标/头像/徽标/按钮图形的内部居中、偏心或视觉重心，就把 centering-board 当作默认验收项；单张原始截图或主观“看起来居中”不算完整居中验收。build、package、`openprd dev-check` 和单张原始截图不能替代视觉证据。`visual-compare` 每次都会返回 `chatEmbed` markdown；生成证据板后必须把这行 `![视觉证据: ...](路径)` 直接嵌入最终回复，让证据在对话流里可见，不要只报告文件路径；`openprd dev-check` 在触达界面文件且最近 24 小时没有证据板时也会输出视觉证据提醒，收口前按提醒补齐。
 6. 界面、页面、视觉、样式、信息架构或前端体验任务进入实现前，先读取 `$openprd-frontend-design`，并用 `.openprd/design/active/` 补齐 `facts-sheet / asset-spec / image-preflight / direction-plan / selected-direction`；空白工作区优先从 `.openprd/design/templates/` 选最近模板。若用户已经给了效果图、设计稿、参考截图或其他明确参考图，先把它当成主参考源；只有现有 starter、theme、layout 足够接近时才复用，不接近就允许偏离默认组合，以参考图为准。若当前轮用户已经把页面主题、模块范围或“直接实现”的意图说清，优先运行 `openprd run . --context --message <用户原话>`。若页面主题和模块范围已经明确，优先运行 `openprd design-starter . --starter <starter-id> --out index.html --brief "<页面主题>" --sections "<模块1|模块2|模块3>"` 起第一版真实页面；只有这个页面本来就不依赖外部产品事实、品牌素材或真实图片时，才在 active design artifacts 写清无依赖并补 `--no-external-facts --no-brand-assets --no-real-images`；若题目更像旅游、导览、展览、博物馆、城市、自然观察或案例内容页，先不要带 `--no-real-images`，让 starter 先尝试补首批真实图片；若这类冷启动即使带 message 仍短暂返回 `clarify-user`，把它当成摘要级提醒，先用 3 到 5 行 mini-plan 收口，再继续。starter 落地后默认进入 `Patch Mode`，必须直接在生成的入口文件上补丁修改；即使结构要大改，也是在同一路径内覆盖，不做 delete-first，更不要删除 `index.html` 后另起新稿。如果确实要整页重写，先把完整新稿写到 sibling draft，例如 `index.next.html`，确认内容成形后再覆盖回 `index.html`，不要让正式入口出现空窗；starter 一落地后，只允许做一轮就地对焦：快速读一次生成的入口文件和必要的 active design artifacts；这轮对焦结束后，下一步就必须是真实写入口，不要再回头搜网页、翻 `docs/basic/` 或继续模板漫游；把最后一批必要的查事实、查图、读模板动作放在口头宣布之前做完；一旦已经说“开始覆盖入口文件”或“开始整页重写”，下一步必须出现真实写文件动作，而不是继续只读浏览、压图或停在口头承诺；必要时 hook 会把这类非写入动作挡回去；`Patch Mode` 完成不等于只补合同、只下载素材或只写计划；至少要把入口文件本体改完、主要占位清掉，并把已准备好的真实图片或参考约束真正落进页面；没有明确参考方向时，不要直接落回同一种安全极简解。
+6a. 写产品界面上用户能看到的文案时，必须站在当前用户视角写：这句话要说明用户现在能做什么、会发生什么、为什么值得点、下一步怎么走。除非这是面向开发者或专业技术人员的技术型产品，否则默认用普通人能看懂的语言写结果、状态、限制和行动，不要暴露 API、SDK、模型、数据库、缓存、错误码或内部模块。正反例：不要写“适合想保留全部工具入口的用户”，改写成“首页会显示所有工具入口，你可以直接选择需要的功能”；不要写“API 请求失败，错误码 500”，改写成“暂时保存失败，请稍后再试”；技术型产品可以保留必要术语，但仍要写清用户动作、影响和修复路径。
+6b. 开发新功能出现新的入口、按钮、tab、卡片、空态或工具格时，默认自动配图标，不等用户提出：先复用项目已有图标体系；项目没有时按图标最佳实践路由选型（UI 图标 Phosphor，落码 Lucide/Tabler/React Icons，AI 品牌 LobeHub Icons，技术栈 Tech Icons，功能图标/插画 iconfont），把图标名、来源、用途登记到 `.openprd/design/active/asset-spec.md` 的“功能图标”行再接入。只有语义确实不需要图标或用户明确说不要时才跳过，并在收口说明原因。
 7. 用户给出会话 ID 并要求继续时，按工具无关的历史会话续接；不要要求工具专属 ID，也不要用当前 active change 或相似历史替代指定会话。
 8. 单个 task 收尾时只运行本任务最小足够验证，并通过 `--evidence`、测试报告或任务 metadata 留下 task-scoped evidence；代码修改完成后、最终回复前，针对本轮实际 touched code files 运行 `openprd dev-check . <file...>`。阶段收口、全部实现完成、handoff/commit/release/publish 前，再运行 `openprd standards . --verify`、`openprd quality . --verify` 和 `openprd run . --verify`；L2 或跨页面实现的最终回复必须列出最新 HTML 质量报告和 task-scoped Markdown/HTML 测试报告路径。如果还没有 `.openprd/harness/test-reports/` 下的 Markdown / HTML 测试报告，就不要把状态表述成项目级已经闭环。
 9. 微信小程序相关任务默认按“最小足够验证”执行：只有用户明确要求小程序实测、截图、抓日志/网络、复现问题，或当前改动必须依赖运行态证据时，才升级到本地小程序运行态验证；默认沿用当前小程序运行态或开发者工具会话连续验证，不要为了验证自动重开应用；只有用户明确要求从 0 到 1、冷启动或重开时，才从头启动。如果当前客户端没有相应工具，不要假定已经安装，也不要把缺少工具当成阻断。
 10. `openprd init/setup/update/doctor` 记录的 `optionalCapabilities` 是非阻断式增强建议。当前任务明显受益但能力还未配置时，可在后续建议里说明它能帮什么、附官方文档 / GitHub 链接，并询问用户是否需要按当前客户端补配置；不要因为它未配置就阻断当前任务。
+11. 判断当前用户正在和 Codex、Claude Code 还是 Cursor 对话时，先看 `.openprd/harness/runtime-environment.json` 的 hook/session evidence，再按 install manifest 里的 `platformCapabilityPacks` 启用平台专属能力。Codex 原生 Image 2、Computer Use、Codex-owned browser window、OpenPrd 对话协同画布和 Codex 当前线程桥接属于 surface-dependent 能力，只有当前工具面或 hook/session 证据明确支持时才使用；画布必须绑定当前 thread/session，无法自动识别时用 `openprd canvas . --thread <id> --thread-title <name>` 或 `--session <id> --session-title <name>` 显式隔离，标题只用于当前对话展示；当前线程桥接只在 Codex App 当前 thread binding 明确时使用，浏览器写入 handoff 后由 OpenPrd 服务端默认通过 Codex app-server `thread/resume -> turn/start` 提交到绑定线程，失败或关闭时才进入 `agent-foreground-relay` 兜底队列；不要仅凭 Codex CLI、`.codex/config.toml` 或 `CODEX_HOME` 推断可用。
 
 ### Hook-Enforced Gates
 
+- automation-safe：识别到 Codex automation、Claude Code headless、cron、scheduled 或 unattended task 时，hook 默认不注入 OpenPrd context、不阻断写入、不要求 dev-check / quality / doctor；只有 OpenPrd 维护任务或显式启用 OpenPrd 时才恢复这些门禁。
 - requirement：需求未完成 `clarify/review/change/tasks` 前阻断实现写入；tasks 就绪后，只有用户原始意图已明确要求实现，或后续在看过执行确认清单后明确发出执行指令时才放行。
 - research：公开 GitHub 架构/对标先 DeepWiki；第三方技术用法、配置、限制、版本差异或迁移先查本地证据，不足时再按 `resolve_library_id -> query_docs` 使用 Context7。
 - design：界面、页面、视觉和前端体验任务进入实现前，先读取 `$openprd-frontend-design`，并补齐 `.openprd/design/active/` 下的事实、素材、图片和方向合同。
 - skill-visualization：修改 skill、`SKILL.md`、`AGENTS.md` 或相关 workflow 前，先输出彩色 Mermaid 方案并等待用户确认。
+- autonomy-risk：即使已经授权实现，也默认阻断未经当前用户明确批准的云端热修复、生产远端写入、业务兜底、写死逻辑、客户端/服务端补业务数据或缓存补行。
 - secrets / weapp / browser / copy：分别处理 `secrets-vault`、按需的小程序运行态验证、窗口归属与 i18n/普通用户文案提醒。
 - 需要细节时，读 router 指向的 skill 和 command catalog，而不是继续扩写 `AGENTS.md`。
 
 ### High-Risk Gate
 
-Before freeze, handoff, accepted spec apply/archive, commit, push, release, or publish, ensure `openprd standards . --verify`, `openprd quality . --verify`, `openprd run . --verify`, and `openprd doctor .` are healthy.
+For interactive OpenPrd flows, before freeze, handoff, accepted spec apply/archive, commit, push, release, or publish, ensure `openprd standards . --verify`, `openprd quality . --verify`, `openprd run . --verify`, and `openprd doctor .` are healthy. Unattended automation uses its own runbook, logs, tests, publish checks, and notification contract unless it explicitly opts into OpenPrd.
 If the quality report says `productionReady=false`, do not claim overall readiness. Reuse `openprd run . --verify` to separate current-task status from workspace-level debt, list the missing evidence or gates, and when only `feature-coverage` is pending describe it as task-ledger or evidence debt rather than a failed implementation.
 The only baseline documentation path is `docs/basic/`.
 <!-- OPENPRD:AGENTS:END -->