@openprd/cli 0.1.11 → 0.1.18

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

@@ -1,36 +1,31 @@
-# OpenPrd loop 隔离 worktree 提交闭环
-> 语言规则：默认用简体中文生成 PRD、spec、tasks 和用户可见说明；除 PRD、OpenPrd、OpenSpec、API、SDK、CLI、TypeScript、JSON、HTTP、WebSocket、字段 key、命令名、品牌名、产品名和协议名等必要专有名词外，其余内容优先写成简体中文。
-- 版本: v0006
+# Vibe Coding 自动化三连：dev-check 自动重构、图标自动匹配、拼图证据入流
+> 语言规则：用户可见说明、PRD、spec 和 tasks 跟随用户当前主语言；无法判断时才使用简体中文兜底。PRD、OpenPrd、OpenSpec、API、SDK、CLI、TypeScript、JSON、HTTP、WebSocket、字段 key、命令名、品牌名、产品名和协议名等必要专有名词保留原文。
+- 版本: v0012
 - 负责人: Codex
 - 产品场景: 以 Agent 为主要使用场景
 - 场景模板: 以 Agent 为主要使用场景
 - 状态: synthesized
-- 生成时间: 2026-06-07 13:07:07
+- 生成时间: 2026-07-03 18:28:06
 ## 元信息
 
-- 标题: OpenPrd loop 隔离 worktree 提交闭环
+- 标题: Vibe Coding 自动化三连：dev-check 自动重构、图标自动匹配、拼图证据入流
 - 负责人: Codex
 - 状态: clarifying
-- 版本: v0006
+- 版本: v0012
 - 产品场景: 以 Agent 为主要使用场景
-- 日期: 2026-06-07
+- 日期: 2026-07-03
 
 ## 问题
 
-- 问题陈述: 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 三项 Vibe Coding 自动化能力不足：1) dev-check 超行提醒停留在后续建议表格，用户不知如何处理，价值鸡肋；2) 开发新功能时图标最佳实践路由几乎从不自动触发（415 个图标相关会话仅 1 次真实接入图标库）；3) 拼图/网格对齐证据板真实触发率低，证据图不在对话流中可视化，AI 自我审查作用未发挥。
+- 为什么是现在: 用户明确反馈不少人用了 OpenPrd 觉得疑惑它到底是干嘛的，希望有一套软件工程视角的标准流程引导；画布做了一半，需要继续对标白板工具补齐人机协同能力。
 - 证据:
-  - 最近一个月能查到多次 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 绑定。
+  - moticlaw docs/basic 平均行长 440-477 字符、37 行超 500 字符；.openprd 总 5.8GB，quality/reports 5118 份；artifacts/active 280 个版本目录、archive 为 0；对照组 ClipReady/gifeasy 年轻项目文档健康。
 
 ## 用户与相关方
 
 - 主要用户:
-  - 需要用 OpenPrd loop 执行中等到长程实现的维护者
-  - 希望逐任务 commit、可审查、可回归且不污染主工作区的 Agent 协作者
+  - 用 Vibe Coding 方式做产品的产品经理
 - 次要用户:
   - 待补充
 - 相关方:
@@ -40,49 +35,75 @@
 ## 目标与成功标准
 
 - 目标:
-  - 让 loop 在需要时显式进入隔离 worktree / branch 中执行，而不是默认污染主工作区。
-  - 让逐任务 commit 只包含当前任务的改动，便于单独审查和回归。
-  - 让 worktree、branch、commitSha 和 session 形成完整可追踪链路。
+  - 产品经理任何时刻都能一眼看到自己处在 7 步标准流程的哪一步和下一步动作
+  - 画布接入评审方向导入与流程位置提示，让 PM 在白板上完成方向标注并把结论发回 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。
+  - openprd guide 在需求前/评审中/实现中/收口后各阶段输出正确的当前步骤与下一步
+  - review.html 顶部展示流程位置条
+  - 画布可一键导入当前评审的 designDirections 方向图卡片
 - 验收目标:
-  - 在隔离 worktree 中连续完成多个 loop 任务时，每个任务都能生成独立 commit，并把 commitSha 写回状态。
-  - 在脏主工作区直接尝试 finish --commit 时，会收到明确阻断和豁免提示。
-  - 从状态文件和 session 日志可以追溯每个任务对应的 worktree、branch、commit 和测试报告。
-  - 新能力不破坏现有 loop 的 plan、next、run、finish、verify 基本路径。
+  - 在 openprd 自身仓库通过单元测试与 standards/quality/run verify；用 Codex CLI 在本地跑一个桌面任务实测新流程效果并留下证据。
+
+## 验证与创业闭环
+
+- 可触达社区:
+  - 待补充
+- 第一批种子用户:
+  - 待补充
+- 社区契合与触达依据:
+  - 待补充
+- 当前替代方案: 待补充
+- 痛点与替代证据:
+  - 待补充
+- 手工交付路径:
+  - 待补充
+- 手工作战卡:
+  - 待补充
+- 承诺信号:
+  - 待补充
+- 首个低成本验证: synthesize 生成 PRD 与 review.html 后走 change/tasks，再按任务实现并用 Codex CLI 本地桌面任务实测。
+- 先活下来方案:
+  - 待补充
+- 付费验证信号:
+  - 待补充
+- 第一版只做一件事: 待补充
+- 周末级验证: 待补充
+- 最小工具桥接:
+  - 待补充
+- 产品化门槛:
+  - 待补充
+- 第一批客户路径:
+  - 待补充
+- 初始收费假设: 待补充
+- 客户 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 以及相关状态输出。
+  - dev-check 自动重构模式：默认开启，命中 attention/warning 时指示 Agent 本轮直接执行高内聚低耦合拆分（不丢功能），输出改为本次额外处理结果，并支持 --auto-refactor on/off 开关与收口确认话术
+  - 图标最佳实践自动触发：asset-spec 增加功能图标行，design-starter/skills/catalog/hook 把新功能自动配图标写为默认行为
+  - 拼图证据板强化：visual-compare 输出对话流嵌入 markdown，dev-check 对 UI 文件补视觉证据提醒，skills/catalog 把网格对齐证据板写为界面布局场景默认动作
 - 范围外:
-  - 不在这次能力里自动 push、开 PR 或发布。
-  - 不做复杂的交互式冲突解决或自动合并策略。
-  - 不强制把每个 task 都拆成独立 worktree；第一版优先支持一个 change / 一段 loop 使用一个隔离 worktree。
-  - 不先重做整套 release / publish 工作流。
+  - 画布实时多人协作
+  - 重写画布为独立前端工程
+  - 改动 Codex 线程桥接协议
 
 ## 场景与流程
 
 - 主流程:
-  - 用户为一个 change 进入 loop 开发时，OpenPrd 可显式创建或接入隔离 worktree 与命名分支，再在其中逐任务运行和提交。
-  - 每个任务验证通过后执行 finish --commit，只提交当前任务 write-scope / touched files，并把 commit 信息写回状态。
-  - 评审或回归时，维护者可从状态文件直接定位 worktree、branch、commitSha 和测试报告。
+  - PM 打开终端或让 Agent 运行 openprd guide，看到 7 步流程和当前位置，按提示进入下一步
+  - PM 打开 review.html，顶部流程条显示当前在评审确认步；确认后进入方向选择
+  - PM 打开画布点导入评审方向，3 个方向图变成卡片，圈选标注后用发送给 Codex 把结论发回
 - 边界情况:
-  - 用户在脏主工作区里直接尝试 finish --commit。
-  - 当前任务没有可确定的 write-scope，需要回退到 touched files 或明确失败提示。
-  - 已有 worktree 存在但 branch 缺失、处于 detached HEAD 或命名不规范。
-  - 任务验证通过但 commit 写回状态失败，需要保持任务未完全收口并给出修复入口。
+  - 工作区还没有任何需求版本时 guide 显示第 1 步并给出起步动作
+  - 当前评审没有 designDirections 时画布导入按钮提示暂无可导入方向
 - 失败模式:
-  - 误把主工作区无关改动一起提交。
-  - loop 在 detached HEAD 或错误分支上提交，后续难以审查和回放。
-  - 状态里只标 done 但缺少 commitSha / worktree 信息，导致无法追溯。
-  - 隔离 worktree 创建成功，但后续 run / finish 没有使用同一执行环境。
+  - 方向图片文件缺失时导入跳过该方向并提示，不中断其他方向导入
 
 ## 可视化图表
 
@@ -90,30 +111,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/>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
 ```
 
 ### 架构
 
 ```mermaid
 flowchart LR
-  users["主要用户<br/>需要用 OpenPrd loop 执行中等到长程实现的维护者 · 希望逐任务 commit、可审查、可回归且不污染主工作区的 …"]
+  users["主要用户<br/>用 Vibe Coding 方式做产品的产品经理"]
   subgraph solution["方案边界"]
-    experience["Agent 使用场景层<br/>用户为一个 change 进入 loop 开发时，OpenPrd 可显式创建或接入隔离 worktree 与命名分支，再在其中…"]
-    core["核心产品逻辑<br/>OpenPrd 的 loop 虽然支持逐任务 finish 和可选 commit，但最近没有稳定形成“隔离 worktree …"]
-    integrations["依赖与集成<br/>Git worktree 能力。 · 现有 loop task executionStrategy.writeScope 与 …"]
+    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/>loop --run 可以显式创建或接入 worktree / branch，或提供等价包装入口。 · 主工作区脏时，loop…"]
+    delivery["验证与交接<br/>openprd guide 在需求前/评审中/实现中/收口后各阶段输出正确的当前步骤与下一步 · review.html 顶部…"]
   end
-  users -->|"用户为一个 change 进入 loop 开发时，OpenPrd 可显式创建或…"| experience
+  users -->|"PM 打开终端或让 Agent 运行 openprd guide，看到 7 步…"| experience
   experience -->|"产品动作与编排"| core
   core -->|"依赖与外部服务"| integrations
   core -.->|"策略、可靠性与合规"| governance
@@ -125,64 +146,46 @@ flowchart LR
 ## 需求
 
 - 功能需求:
-  - 支持显式 worktree / branch 配置，或提供隔离运行包装命令。
-  - 支持检测主工作区脏状态，并在 finish --commit 前阻断高风险路径。
-  - 支持基于 write-scope 或 touched files 生成本任务提交集。
-  - 支持在 loop 状态、session 日志和测试报告中记录 commit 关联信息。
-  - 支持为未满足 commit 前置条件的任务给出清晰诊断与恢复指引。
+  - guide 命令基于工作区状态推断 7 步流程位置
+  - review.html 渲染 stepper
+  - canvas /api/review-directions 返回方向元数据与图片
+  - canvas 前端导入方向卡片组
 - 非功能需求:
-  - 默认路径必须安全，不能把无关改动静默卷入 commit。
-  - 行为必须可追踪，可从状态文件复原任务执行链路。
-  - 对现有 loop 用户保持兼容，新增能力应尽量显式开启或有明确默认策略。
-  - 失败路径必须可恢复，不能留下半记录状态。
+  - 不新增外部依赖
+  - guide 与画布 API 只读工作区状态，不写状态
+  - 全部文案用 PM 能看懂的普通语言
 - 业务规则:
-  - 逐任务 commit 只在任务验证通过后允许执行。
-  - 主工作区脏时默认禁止高风险 commit，除非用户显式豁免。
-  - 状态留痕必须与实际 commit 结果一致，不能先写成功后提交失败。
+  - designDirections 仅在需求被判定涉及界面场景时要求；方向选定必须以 user-confirmed 来源写回；落选方向归档不删除。
 
 ## 业务护栏
 
 - 成本来源:
-  - 这次主要要避免无关改动混入 commit、回滚成本升高，以及逐任务审查和回归失去抓手。
+  - imagegen 每方向一次调用，共 3 次；报告清理为本地文件操作无外部成本。
 - 额度与限制:
-  - 默认不允许在脏主工作区直接完成高风险 commit；需要显式进入隔离路径或明确豁免。
+  - docs-compact 单次只处理 docs/basic 下的标准文档；retention 默认保留最近 30 份报告可配置。
 - 滥用防护:
-  - 不能把未在当前任务范围内的文件静默加入 commit。
-  - 不能把 detached HEAD 上的匿名提交伪装成可回归的标准 loop 结果。
+  - docs-compact 重写稿默认写到 sibling draft 待确认，不直接覆盖原文档；retention 不触碰 evidence 目录中被 latest 报告引用的文件。
 - 监控信号:
-  - 需要持续看 loop 任务完成后是否稳定写回 commitSha。
-  - 需要看 worktreePath、branch、commitSha 是否在状态和 session 日志里一致。
-  - 需要看脏主工作区门禁是否挡住了无关改动被带进提交。
+  - standards verify 输出 docsQuality 结果；doctor 输出 .openprd 体积与报告数量提示。
 - 报警阈值:
-  - 只要出现用户要求 commit 但任务完成后没有 commitSha，就算这条闭环没有打通。
-  - 只要出现主工作区无关改动被带进 loop commit，就应立即视为高风险回退。
+  - 单行超 300 字符 warning；prd.md 落后最新版本超过 20 个版本 warning；quality/reports 超过 200 份提示清理。
 - 止损动作:
-  - 无法安全判定提交范围时，停止自动 commit，保留任务验证结果并提示人工处理。
-  - worktree / branch 状态异常时，不把任务标记为已完成提交。
+  - 任一清理动作失败即中止并保留原状；归档失败回退为仅提示不移动。
 
 ## 约束、依赖与风险
 
 - 技术约束:
-  - 基于现有 openprd loop / git 流程扩展，不重写整套任务调度。
-  - 兼容当前 feature-list、loop-state、agent-sessions 与 test-reports 结构。
-  - 需要同时考虑 worktree、命名分支与 detached HEAD 的兼容行为。
+  - 改动集中在 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。
 - 合规要求:
   - 提交与状态写回不能泄露用户本地无关改动或敏感信息。
 - 依赖:
-  - Git worktree 能力。
-  - 现有 loop task executionStrategy.writeScope 与 finish / verify 流程。
-  - OpenPrd 的状态文件、review / change / tasks 主流程。
+  - Codex 原生 imagegen（生成 3 方向交互稿图片）；现有 review artifact 渲染与 hash 校验管线。
 - 假设:
-  - 第一版默认以一个 change / 一段 loop 对应一个隔离 worktree 为优先模型，而不是每个 task 一个 worktree。
-  - 已有 task write-scope 在多数实现任务里足够收窄 commit 范围；不足时需要 touched files 补位。
+  - imagegen 由 Codex 原生 Image 2 提供，OpenPrd 只消费图片路径；review.html 静态打开，选择结果通过现有 canvas/browser handoff 或 review --mark 通道回传；巨行阈值默认 300 字符可配置。
 - 风险:
-  - 如果 worktree / branch 生命周期设计不清，会显著抬高 loop 使用复杂度。
-  - 如果 touched files 收集不稳定，可能出现漏提或误提。
-  - 如果状态写回与 git 操作顺序不当，会出现 done / commitSha 不一致。
+  - 流程步骤定义与既有 lane/gate 概念不完全一一对应，guide 只做展示层推断，不改门禁行为
 - 开放问题:
-  - 第一版是否明确采用一个 change 一个 worktree、一个 task 一个 commit。
-  - worktree / branch 命名规范是否要产品化成 CLI 默认值。
-  - override 脏仓库门禁时，CLI 需要多强的显式确认语义。
+  - 画布方向卡片是否需要内置投票/评分组件，留到下一轮看使用反馈
 
 ## 类型专项模块
 
@@ -196,5 +199,5 @@ flowchart LR
 ## 交接
 
 - 负责人: Codex
-- 下一步: 完成 review 确认后生成 change 和 tasks，再实现 loop 的隔离 worktree 提交闭环。
-- 目标系统: OpenPrd
+- 下一步: synthesize 生成 PRD 与 review.html 后走 change/tasks，再按任务实现并用 Codex CLI 本地桌面任务实测。
+- 目标系统: openprd CLI 自身仓库（harness-engineer/openprd）。

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 -->

package/README.md

@@ -100,9 +100,15 @@ OpenPrd 会生成可以直接分享的 HTML 面板，让产品、研发和 Agent
 ### 效果图与截图拼图对比，自动优化
 
 把效果图和实现截图放进同一张左右对比图里，适合登录入口改造、条款页本地化、弹窗复刻这类阶段性评审。
+视觉证据会跟随当前任务语境选择语言：中文需求默认输出中文标签，英文需求默认输出英文标签；需要固定语言时可显式传入 `--locale zh-CN` 或 `--locale en`，证据板里的标题、摘要和检查项也会一起跟随。
 
 ![效果图与截图拼图对比，自动优化](https://raw.githubusercontent.com/mileson/openprd/main/docs/assets/openprd-visual-compare-case-study-zh.png)
 
+```bash
+openprd visual-compare . --reference ref.png --actual actual.png --locale zh-CN
+openprd visual-compare . --board verification-board.json --locale en
+```
+
 ## 自我成长机制
 
 OpenPrd 会沿着两条看得见的循环，越用越贴合你们的协作方式。一条循环把真实项目里反复验证过的做法沉淀成可复用的 `项目级 Skill`；另一条循环把不同场景下更合适的协作设置沉淀成 `动态参数配置`，让下次启动时直接带上更合适的默认做法。
@@ -211,7 +217,7 @@ openprd init /path/to/project --template-pack agent
 npx @openprd/cli@latest init /path/to/project --template-pack agent
 ```
 
-`init` 会创建 `.openprd/`、`docs/basic/`、`AGENTS.md`，并生成 Codex / Claude / Cursor 三端引导。Codex 项目会同时写入 `.codex/config.toml`、`.codex/hooks.json`、`.codex/hooks/openprd-hook.mjs`，并开启用户级 Codex `hooks = true`。
+`init` 会创建 `.openprd/`、`docs/basic/`、`AGENTS.md`，并生成 Codex / Claude / Cursor 三端引导。`.openprd/` 是项目内唯一的 OpenPrd 工作区；change、spec、task 和 archive 产物都会收敛到 `.openprd/changes/`、`.openprd/specs/` 和 `.openprd/archive/changes/`，不再在仓库根目录生成单独的 `openprd/` 目录。Codex 项目会同时写入 `.codex/config.toml`、`.codex/hooks.json`、`.codex/hooks/openprd-hook.mjs`，并开启用户级 Codex `hooks = true`。
 
 Codex hooks 默认使用 `lite` 模式：安装 `UserPromptSubmit`、轻量
 `PreToolUse` 写入门禁，以及轻量 `Stop` 收工回顾。明确提到 OpenPrd、PRD、深度调研、深度对标、复刻、
@@ -309,13 +315,17 @@ openprd review /path/to/project --mark confirmed --version <id> --digest <sha256
 ```
 
 `review.html` 是当前 PRD 的稳定评审稿，但默认 approval policy 是
-`decision-points`，不是“每次都必须停在这里”。常规 lane 下，用户先看稳定
-artifact，再用页面复制出来的精确 `--version`、`--digest`、`--work-unit`
-记录确认；`silent-record` lane 只有在用户一开始已经明确要求直接做、并显式
-表示不需要额外评审或确认时，才允许直接记录当前这份精确 artifact。不要把
-实现授权当成给任意评审稿补确认，也不要把评审记录当成实现授权。当前 artifact
-记录完成后，再生成 OpenPrd change 和任务拆解；如果用户原始意图已明确要求
-实现，tasks 就绪后即可直接执行，否则等待一句明确的执行指令：
+`decision-points`，不是“每次都必须停在这里”。常规 lane 下，一句自然语言
+确认（例如“确认这版，继续”，容忍“确认 v0276 评审稿”这类版本号插写）就足够：
+hook 会自动把确认绑定到当前精确的 `--version`、`--digest`、`--work-unit`，
+Agent 不允许反过来向用户索要 digest、work-unit 或完整命令。当这句确认同时
+带有“继续执行”意图，或此前已确认过需求摘要时，一次确认会解锁整条链：评审
+记录、change、tasks 与实现全程直通，不再逐环节停下（一次确认合同）。
+`silent-record` lane 只有在用户一开始已经明确要求直接做、并显式表示不需要
+额外评审或确认时，才允许直接记录当前这份精确 artifact。不要把实现授权当成
+给任意评审稿补确认，也不要把评审记录当成实现授权。当前 artifact 记录完成后，
+再生成 OpenPrd change 和任务拆解；如果用户原始意图已明确要求实现，tasks
+就绪后即可直接执行，否则等待一句明确的执行指令：
 
 ```bash
 openprd change /path/to/project --generate --change <change-id>
@@ -443,6 +453,22 @@ OpenPrd 生成的 change 会包含标准化维护任务，change 校验也会检
 或产品行为变化影响，也必须同步更新。如果无需更新，应说明已经完成影响判定以及
 为什么现有文档仍然准确。
 
+## 生图路由：自动选对免费生图工具
+
+图片、封面图、效果图、图标等生图请求按三层路由自动选工具，不需要用户指定：
+
+1. **工具面判定**：Codex 环境用原生 `imagegen`（Image 2），Cursor 环境用内置
+   `GenerateImage`——两者都是对话工具内的免费能力，优先直接使用。
+2. **已存偏好**：都不可用或无法判断时，先读
+   `.openprd/harness/image-generation-preference.json` 里用户已确认的偏好，
+   有就直接用，不再重复询问。
+3. **询问并持久化**：没有偏好时才问用户一次，答复以 `user-confirmed` 来源
+   写回该文件，作为下次默认。
+
+成本护栏：任何情况下都不允许在用户未明确指定时，擅自调用用户本地或自有的
+付费生图 API（例如 OpenAI / Stability key）。路由协议由 install manifest 和
+`.openprd/harness/runtime-environment.json` 的 `imageGenerationRouting` 字段承载。
+
 ## 效果图与截图拼图对比，自动优化
 
 当界面任务已经有效果图、设计稿、用户给图或 Agent 自己生成的 mock 时，Agent
@@ -482,6 +508,65 @@ openprd visual-compare /path/to/project \
 Agent 必须查看生成图并继续对标，直到没有明显视觉差异。最终回复里应给出本次
 生成的对比图路径，并说明对比后是否仍有差异。
 
+如果新功能或改动包含同构列表、卡片、网格或表格，或者用户反馈“没对齐”“排版
+漂移”，Agent 还要把真实截图、辅助线、容器轨道量测和内部内容槽位量测放到一张对齐证据板里：
+
+```bash
+openprd visual-compare /path/to/project \
+  --board alignment-board.json
+```
+
+`alignment-board.json` 使用 `mode: "alignment-board"`，记录截图、辅助线、
+容器分组和内容槽位分组。容器轨道包括卡片外框、列宽、行顶、间距等；
+内容槽位包括标题、副标题、标签、描述、状态、价格、按钮、图标和操作区等
+相同文案类型/相同组件槽位的 x/y/宽高/baseline spread。列表卡片、卡片网格和
+表格这类重复结构属于默认触发场景，不需要等用户先指出“没有对齐”；只量外框、
+列宽或行顶不算完整对齐验收。
+
+如果要判断单个 logo、icon、avatar、badge、按钮图形或图片裁切内部是否居中，
+或者用户反馈“偏心”“视觉重心不对”，Agent 应先裁出目标元素，再生成内部居中证据板：
+
+```bash
+openprd visual-compare /path/to/project \
+  --board centering-board.json
+```
+
+最小语法如下：
+
+```json
+{
+  "mode": "centering-board",
+  "title": "Logo 内部居中检查",
+  "image": ".openprd/harness/screenshots/logo.png",
+  "thresholdPx": 8,
+  "subject": {
+    "mode": "auto",
+    "weight": "contrast"
+  }
+}
+```
+
+如果自动 mask 把背景、阴影或透明边缘算进主体，可以显式指定颜色范围：
+
+```json
+{
+  "mode": "centering-board",
+  "image": ".openprd/harness/screenshots/logo.png",
+  "subject": {
+    "mode": "range",
+    "ranges": [
+      { "r": [180, 255], "g": [140, 255], "b": [0, 120] },
+      { "r": [210, 255], "g": [210, 255], "b": [200, 255] }
+    ],
+    "weight": "luma"
+  }
+}
+```
+
+`centering-board` 会输出红色画布中心线、绿色主体外接框、黄色视觉重心点，
+并在 metadata 里记录主体外接框中心偏移和视觉重心偏移。单张原始截图或
+“看起来居中”的主观判断不能替代这张证据板。
+
 ## 回归测试与质量评估报告
 
 `openprd init` 同时会创建质量契约：
@@ -510,7 +595,10 @@ openprd quality /path/to/project --verify
 `openprd run --verify` 会再次执行这个质量门禁。Agent 不得在本期必测块缺证据或需关注时宣称就绪。
 如果界面任务已有参考图，视觉就绪还需要 `.openprd/harness/visual-reviews/`
 下存在本次 `openprd visual-compare --reference/--actual` 产物；如果没有参考图但改动界面，
-还需要存在 `openprd visual-compare --before/--after` 修改前后产物。对比图仍有明显差异或漂移时，应回到实现继续调整。
+还需要存在 `openprd visual-compare --before/--after` 修改前后产物。普通截图实测需要截图实测证据板；
+同构列表、卡片、网格或表格还需要对齐辅助线证据板，并同时覆盖容器轨道和内部内容槽位；
+单个素材、图标、头像、徽标、按钮图形或图片内部居中/视觉重心判断需要内部居中证据板。
+对比图仍有明显差异、坐标偏差或漂移时，应回到实现继续调整。
 
 当一个问题已经修复并完成验证后，可以把抽象模式沉淀为项目级经验：
 
@@ -568,10 +656,12 @@ openprd loop /path/to/project --run --agent codex --dry-run
 
 `doctor` 会检查三端引导、Codex hooks 开关、项目标准化和 OpenPrd 工作区验证是否健康，同时展示像 Context7 / DeepWiki 这类可选增强建议。`update` 会从 OpenPrd 的统一源刷新这些生成文件，并保留用户自己已有的 hook 分组。
 
+新版本更新会自动识别旧项目遗留的根目录 `openprd/changes/`、`openprd/specs/` 和 `openprd/archive/changes/`，并把内容迁移到 `.openprd/` 对应位置；无冲突时会删除空的旧 `openprd/` 目录。若同名文件内容不同，旧文件会保留在原处并让本次更新失败，避免静默覆盖用户数据。
+
 `self-update` 只更新 OpenPrd CLI 自身，默认使用公开 npm 包。
 `upgrade` 会编排两层更新：先执行 `self-update`，再重新解析安装后的
 `openprd` 可执行文件，然后执行 `update <project>`；加 `--fleet` 时会执行
-`fleet <root> --update-openprd`，只刷新已有 `.openprd/` 的历史项目。两个入口都支持
+`fleet <root> --update-openprd`，刷新已有 `.openprd/` 的历史项目，并识别只有旧根目录 `openprd/` 工作产物的项目完成迁移。两个入口都支持
 `--dry-run`，预演时只打印安装和刷新命令，不修改 CLI、项目、registry 或 harness 状态。
 
 这套 harness 是有状态的，但 hook 重量由 profile 控制。默认 `lite` 保留轻量
@@ -589,7 +679,9 @@ Claude Code 中优先用 Playwright、MCP 浏览器自动化或项目已有 e2e
 通过后，`loop --finish` 会写入阶段性测试报告，并可在隔离 worktree 中为该任务生成独立 commit。
 界面任务完成前必须运行 `openprd visual-compare`：已有参考图时截实现图并走
 `--reference/--actual`，没有参考图但改动界面时先留修改前截图、完成后留修改后截图并走
-`--before/--after`，查看左右对比 JPG 后才能完成任务。
+`--before/--after`，普通截图实测走 `--board <verification-board.json>`，同构列表、卡片、网格或表格走
+`--board <alignment-board.json>`，单元素内部居中/视觉重心问题走
+`--board <centering-board.json>`，查看证据图后才能完成任务。
 
 `openprd run --context` 可能展示 loop 相关执行命令，但它不是自动执行指令。
 只有当用户当前明确要求开发、实现、继续任务、深度调研、深度对标、复刻落地或
@@ -636,10 +728,11 @@ Loop 状态会沉淀在 `.openprd/harness/`：
 OpenPrd 面向用户的时间统一使用上海时区的 `YYYY-MM-DD HH:mm:ss` 格式，不输出
 `T`、`Z` 或毫秒后缀。除命令、字段名、文件路径、API 名称、品牌名和产品名等必要
 专有术语外，生成文档、进度日志、proposal、prompt、测试报告，以及 Agent 产出的
-`spec.md` 与 tasks 默认使用简体中文。结构字段优先使用“新增需求”“需求”“场景”
-“当”“则”等中文表达，同时继续兼容历史 OpenSpec 英文结构字段。
+`spec.md` 与 tasks 默认跟随当前输入和 PRD 快照的主语言：中文语境使用简体中文，
+英文语境保持英文，无法判断时回退到简体中文。结构字段继续兼容历史英文
+结构字段；明确要求 `zh-CN` 的图示和合同场景仍会强制使用中文。
 
-历史项目不要手写 shell 循环批量改。使用 `fleet` 先扫描报告；它现在会顺带提示全局 registry 里已经登记了多少 OpenPrd 工作区、当前 root 外还有多少已知项目。`--sync-registry` 用来把当前 root 下已初始化的 `.openprd/` 工作区回填到 `~/.openprd/registry/workspaces.jsonl`。`--update-openprd` 只刷新已经有 `.openprd/` 的项目，项目自身 standards 或 validate 缺口会作为“项目健康需关注”报告，但不阻断生成引导更新；只有 agent 配置或普通项目默认保持不变，除非显式用 `--setup-missing` 接管。
+历史项目不要手写 shell 循环批量改。使用 `fleet` 先扫描报告；它现在会顺带提示全局 registry 里已经登记了多少 OpenPrd 工作区、当前 root 外还有多少已知项目。`--sync-registry` 用来把当前 root 下已初始化的 `.openprd/` 工作区回填到 `~/.openprd/registry/workspaces.jsonl`。`--update-openprd` 会刷新已有 `.openprd/` 的项目，也会把只包含旧根目录 `openprd/changes/`、`openprd/specs/` 或 `openprd/archive/changes/` 的历史项目识别为 OpenPrd 工作区并迁移到 `.openprd/`；项目自身 standards 或 validate 缺口会作为“项目健康需关注”报告，但不阻断生成引导更新。只有 agent 配置或普通项目默认保持不变，除非显式用 `--setup-missing` 接管。
 
 ## 怎么看 `status` / `next`