@openprd/cli 0.1.11 → 0.1.19

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,42 @@ 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` 字段承载。
+
+## 画布协同：标注改图闭环
+
+`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
@@ -482,6 +528,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 +615,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 +676,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 +699,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 +748,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`
 

package/README_EN.md

@@ -130,9 +130,18 @@ one human-readable quality surface before handoff, release, or publish.
 Put the reference and implementation into one side-by-side artifact for staged
 UI review, especially for auth-entry redesign, localized legal pages, and modal
 replication work.
+Visual evidence follows the current task language by default: Chinese requests
+produce Chinese labels, English requests produce English labels, and
+`--locale zh-CN` or `--locale en` can pin the output language for side-by-side labels,
+board titles, summaries, and checks.
 
 ![Auto-optimized reference-to-screenshot comparison](https://raw.githubusercontent.com/mileson/openprd/main/docs/assets/openprd-visual-compare-case-study-en.png)
 
+```bash
+openprd visual-compare . --reference ref.png --actual actual.png --locale zh-CN
+openprd visual-compare . --board verification-board.json --locale en
+```
+
 ## Self-Evolving Collaboration
 
 OpenPrd gets easier to work with over time through two visible loops. One loop
@@ -172,6 +181,7 @@ automatically.
 - **Project-level benchmark registry**: support `benchmark add / observe / approve / verify` so repeatedly adopted external sources can become durable project references
 - **Diagram review artifacts**: generate both architecture and product-flow diagrams
 - **UI visual comparison artifacts**: combine reference images and implementation screenshots into side-by-side JPG reviews for visual replication work
+- **Language-aware visual evidence**: localize comparison labels and board copy from the active request language, with `--locale` / `--lang` overrides when a project needs a fixed output language
 - **Contract-driven diagrams**: render from validated JSON contracts
 - **Review status tracking**: use `pending-confirmation`, `confirmed`, and `needs-revision`
 - **Project release/version ledger**: optionally track project versions such as `0.1.23`, version-scoped change items, and local git tag coordination without mixing them with internal PRD `v000x` versions
@@ -355,16 +365,23 @@ openprd review /path/to/project --mark confirmed --version <id> --digest <sha256
 
 `review.html` is the stable review artifact for the current PRD, but the default
 approval policy is `decision-points`, not “always stop here”. In a normal lane,
-the user reviews that stable artifact first and then the exact copied
-`--version`, `--digest`, and `--work-unit` tuple is recorded. In a
-`silent-record` lane, OpenPrd can record the exact current artifact without an
-extra stop only when the user already made direct execution intent explicit and
-explicitly opted out of additional review confirmation. Do not treat
-implementation approval as permission to mark a different review artifact, and
-do not treat review recording as execution authorization. After the current
-artifact is recorded, generate the OpenPrd change and task breakdown. If the
-user originally asked to implement, execution can continue once tasks are ready;
-otherwise wait for an explicit execution request:
+one plain natural-language confirmation (for example “确认这版，继续”, including
+wording with an inline version id such as “确认 v0276 评审稿”) is enough: the
+hook binds it to the exact current `--version`, `--digest`, and `--work-unit`
+tuple automatically, and the agent must never ask the user to paste a digest,
+work-unit id, or a full command. When that confirmation also carries a
+continue-execution intent, or a requirement summary was already confirmed
+earlier, one confirmation authorizes the whole chain: review recording, change,
+tasks, and implementation proceed without further stops (the one-time
+confirmation contract). In a `silent-record` lane, OpenPrd can record the exact
+current artifact without an extra stop only when the user already made direct
+execution intent explicit and explicitly opted out of additional review
+confirmation. Do not treat implementation approval as permission to mark a
+different review artifact, and do not treat review recording as execution
+authorization. After the current artifact is recorded, generate the OpenPrd
+change and task breakdown. If the user originally asked to implement, execution
+can continue once tasks are ready; otherwise wait for an explicit execution
+request:
 
 ```bash
 openprd change /path/to/project --generate --change <change-id>
@@ -501,6 +518,50 @@ the change affects responsibilities, flows, structure, dependencies, or product
 behavior. If no documentation update is needed, agents should say the check was
 performed and why the existing docs still match the code.
 
+## Image-generation routing: pick the right free tool automatically
+
+Image requests (covers, mockups, icons, effect images) follow a three-layer
+routing protocol, so users never have to specify a provider:
+
+1. **Surface built-ins first**: Codex uses native `imagegen` (Image 2), Cursor
+   uses the built-in `GenerateImage` tool — both are free inside their surfaces.
+2. **Persisted preference**: when no built-in tool is available, OpenPrd reads
+   the user-confirmed preference from
+   `.openprd/harness/image-generation-preference.json` and reuses it silently.
+3. **Ask once, persist**: only when no preference exists does OpenPrd ask the
+   user once, then writes the answer back with a `user-confirmed` source as the
+   future default.
+
+Cost guardrail: OpenPrd never silently calls the user’s own paid image APIs
+(for example OpenAI or Stability keys) unless the user explicitly picked one.
+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
@@ -547,6 +608,71 @@ obvious visual differences. The final response for reference-driven UI work
 should include the generated review image path and note whether differences
 remain.
 
+When a new feature or visible change contains repeated homogeneous lists, cards,
+grids, or tables, or when the user reports misalignment, the agent should also
+capture the real UI, overlay guide lines, and measure both container-track and
+internal content-slot coordinate spread in one alignment evidence board:
+
+```bash
+openprd visual-compare /path/to/project \
+  --board alignment-board.json
+```
+
+Use `mode: "alignment-board"` in the board JSON. Include the screenshot, guide
+lines, container groups, content-slot groups, and x/y/width/height/baseline
+spread. Container tracks include card edges, columns, row tops, and gaps.
+Internal content slots include titles, subtitles, tags, descriptions, status,
+prices, buttons, icons, and action areas. Repeated card lists, card grids, and
+tables are default triggers even when the user did not explicitly complain
+about alignment; measuring only outer frames, columns, or row tops is not enough.
+
+When a single logo, icon, avatar, badge, button graphic, or image crop needs
+internal centering review, or when the user reports that its visual weight feels
+off-center, crop the target if needed and generate a centering evidence board:
+
+```bash
+openprd visual-compare /path/to/project \
+  --board centering-board.json
+```
+
+Minimal syntax:
+
+```json
+{
+  "mode": "centering-board",
+  "title": "Logo internal centering check",
+  "image": ".openprd/harness/screenshots/logo.png",
+  "thresholdPx": 8,
+  "subject": {
+    "mode": "auto",
+    "weight": "contrast"
+  }
+}
+```
+
+If the automatic mask includes background, shadow, or transparent padding, use
+explicit color ranges:
+
+```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` draws the red canvas center, green active subject bounds, and
+yellow visual centroid, then stores bounding-box center offset and
+visual-centroid offset in metadata. A raw screenshot or subjective “looks
+centered” note is not a substitute for this board.
+
 ## Quality Regression Reports
 
 `openprd init` also creates a quality contract:
@@ -584,8 +710,14 @@ scope for the scenario.
 
 For UI work with an existing reference image, visual readiness also requires a
 current `openprd visual-compare` artifact under `.openprd/harness/visual-reviews/`.
-If the combined image still shows obvious differences, the task should return to
-implementation instead of treating the gap as ready.
+Before/after UI changes require a before/after artifact, screenshot-based
+runtime checks require a verification board, and homogeneous lists, cards,
+grids, or tables require an alignment board that covers both container tracks
+and internal content slots. Single-logo, icon, avatar, badge, button graphic, or
+image-crop internal-centering reviews require a centering board. If the combined image still shows
+obvious differences, coordinate drift, or layout spread beyond the intended
+threshold, the task should return to implementation instead of treating the gap
+as ready.
 
 After a fix has been verified and reviewed, promote the abstract pattern into
 project knowledge:
@@ -688,7 +820,11 @@ task, and can commit that task before moving on.
 For UI tasks, the loop prompt and generated guidance require the agent to run
 `openprd visual-compare` before finishing: use `--reference/--actual` when a
 reference image exists, or `--before/--after` when the agent must verify a UI
-change without an explicit reference image.
+change without an explicit reference image. Use `--board <verification-board.json>`
+for screenshot-based runtime evidence, and `--board <alignment-board.json>` for
+homogeneous lists, cards, grids, or tables; the alignment board must cover both
+outer tracks and internal content slots. Use `--board <centering-board.json>` for
+single-element internal-centering or visual-centroid checks.
 
 `openprd run --context` may surface loop commands as execution commands, but they
 are not automatic instructions. Agents should run `openprd loop --run`,
@@ -736,6 +872,13 @@ without launching an agent. Use `--agent codex` or `--agent claude` for the defa
 CLI integrations. Use `--agent-command "<custom command>"` only when you want to
 pipe the OpenPrd prompt into a project-specific wrapper.
 
+User-facing generated docs, progress logs, proposals, prompts, test reports, and
+agent-produced specs/tasks follow the primary language of the current request
+and PRD snapshot. Chinese contexts use Simplified Chinese, English contexts stay
+English, and ambiguous contexts fall back to `zh-CN`; command names, field names,
+paths, APIs, product names, and explicitly `zh-CN` diagram contracts remain
+unchanged.
+
 For historical projects, use `fleet` instead of hand-writing shell loops. By
 default it scans and reports only, while also telling you how many known
 OpenPrd workspaces already exist in the global registry and how many are outside

package/package.json

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

package/scripts/dev-check-wrapup-copy.mjs

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
 
 export const DEV_CHECK_WRAPUP_COPY_LIMIT = 20;
-const WRAPUP_FIELDS = ['规模信号', '预警原因', '本次处理结果', '后续建议'];
-const VALIDATE_USAGE = 'Usage: echo \'{"rows":[{"影响对象":"src/example.js","规模信号":"701 行（> 700 行/文件）","预警原因":"文件偏大，维护成本升","本次处理结果":"本轮小改，未扩职责","后续建议":"继续改前先拆小"}]}\' | node scripts/dev-check-wrapup-copy.mjs --validate';
+// 自动优化模式（默认）与仅推荐模式使用不同表头；字段别名成对等价。
+const WRAPUP_FIELD_ALIASES = [
+  ['源文件规模', '规模信号'],
+  ['优化原因', '预警原因'],
+  ['本次处理结果'],
+  ['后续建议'],
+];
+const VALIDATE_USAGE = 'Usage: echo \'{"rows":[{"影响对象":"src/example.js","源文件规模":"701 行（> 700 行/文件）","优化原因":"文件偏大，维护成本升","本次处理结果":"本轮小改，未扩职责","后续建议":"继续改前先拆小"}]}\' | node scripts/dev-check-wrapup-copy.mjs --validate（仅推荐模式对应字段为“规模信号 / 预警原因”）';
 
 function countChars(value) {
   return Array.from(String(value ?? ''));
@@ -11,14 +17,15 @@ function countChars(value) {
 function validateCompactRows(rows = [], limit = DEV_CHECK_WRAPUP_COPY_LIMIT) {
   for (const [index, row] of rows.entries()) {
     const rowLabel = row?.影响对象 ? String(row.影响对象) : (row?.影响位置 ? String(row.影响位置) : `第 ${index + 1} 行`);
-    for (const field of WRAPUP_FIELDS) {
-      const value = row?.[field];
-      if (typeof value !== 'string') {
-        throw new Error(`后续建议校验失败：${rowLabel} 缺少字段“${field}”。${VALIDATE_USAGE}`);
+    for (const aliases of WRAPUP_FIELD_ALIASES) {
+      const field = aliases.find((name) => typeof row?.[name] === 'string');
+      if (!field) {
+        throw new Error(`收口表格校验失败：${rowLabel} 缺少字段“${aliases.join('／')}”。${VALIDATE_USAGE}`);
       }
+      const value = row[field];
       const actual = countChars(value).length;
       if (actual > limit) {
-        throw new Error(`后续建议校验失败：${rowLabel} 的“${field}”有 ${actual} 个字，超过 ${limit} 字上限。当前内容：“${value}”。请缩短后重试。`);
+        throw new Error(`收口表格校验失败：${rowLabel} 的“${field}”有 ${actual} 个字，超过 ${limit} 字上限。当前内容：“${value}”。请缩短后重试。`);
       }
     }
   }
@@ -56,29 +63,45 @@ function reasonText(file) {
   return '待补充';
 }
 
-function currentResultText(file) {
-  if (file.status === 'warning') return '这次先完成需求，暂不拆分';
-  if (file.status === 'attention') return '本轮小改，未扩职责';
+function currentResultText(file, autoRefactor) {
+  if (file.status === 'warning') {
+    return autoRefactor ? '本轮执行拆分后回填' : '这次先完成需求，暂不拆分';
+  }
+  if (file.status === 'attention') {
+    return autoRefactor ? '按需小步拆分后回填' : '本轮小改，未扩职责';
+  }
   if (file.status === 'error') return '本轮失败，未收口';
   if (file.status === 'ok') return '本轮已回顾';
   return '待确认';
 }
 
-function followUpText(file) {
-  if (file.status === 'warning') return '优先拆出独立职责';
-  if (file.status === 'attention') return '继续改前先拆小';
+function followUpText(file, autoRefactor) {
+  if (file.status === 'warning') {
+    return autoRefactor ? '拆完重跑测试验证' : '优先拆出独立职责';
+  }
+  if (file.status === 'attention') {
+    return autoRefactor ? '保持职责边界清晰' : '继续改前先拆小';
+  }
   if (file.status === 'error') return '先修复后重跑';
   if (file.status === 'ok') return '无需额外动作';
   return '待确认';
 }
 
-export function buildCompactDevCheckWrapUpRows(files = []) {
-  return files.map((file) => ({
-    规模信号: thresholdText(file),
-    预警原因: reasonText(file),
-    本次处理结果: currentResultText(file),
-    后续建议: followUpText(file),
-  }));
+export function buildCompactDevCheckWrapUpRows(files = [], options = {}) {
+  const autoRefactor = Boolean(options.autoRefactor);
+  return files.map((file) => (autoRefactor
+    ? {
+      源文件规模: thresholdText(file),
+      优化原因: reasonText(file),
+      本次处理结果: currentResultText(file, autoRefactor),
+      后续建议: followUpText(file, autoRefactor),
+    }
+    : {
+      规模信号: thresholdText(file),
+      预警原因: reasonText(file),
+      本次处理结果: currentResultText(file, autoRefactor),
+      后续建议: followUpText(file, autoRefactor),
+    }));
 }
 
 async function readStdin() {
@@ -95,7 +118,9 @@ async function main() {
   const payload = raw.trim() ? JSON.parse(raw) : {};
   const rows = validateOnly
     ? (Array.isArray(payload.rows) ? payload.rows : [])
-    : buildCompactDevCheckWrapUpRows(Array.isArray(payload.files) ? payload.files : []);
+    : buildCompactDevCheckWrapUpRows(Array.isArray(payload.files) ? payload.files : [], {
+      autoRefactor: Boolean(payload.autoRefactor),
+    });
   validateCompactRows(rows);
   process.stdout.write(JSON.stringify({
     ok: true,

package/skills/openprd-diagram-review/SKILL.md

@@ -1,25 +1,37 @@
 ---
 name: openprd-diagram-review
-description: 生成并迭代 OpenPrd 图示产物，供用户确认。适用于架构图、产品流程图、用户旅程、流程图、系统边界图、依赖图，以及 freeze 前的可视化评审场景。
+description: 生成并迭代 OpenPrd 图示产物，供用户确认或理解。适用于解释型 SVG、架构图、产品流程图、用户旅程、流程图、系统边界图、依赖图，以及 freeze 前的可视化评审场景。
 ---
 
 # OpenPrd Diagram Review
 
 ## 概览
 
-这份 skill 用来判断当前需要哪种图、生成可渲染的 diagram contract、调用 OpenPrd 当前支持的渲染能力，并把结果变成和用户往返确认的评审循环，而不是一次性出图。
+这份 skill 用来判断当前需要哪种图：轻量解释图、正式 diagram contract，或需要用户往返确认的评审循环。不要把所有图都当成 freeze 前评审图；很多时候用户只是需要先看懂问题。
 
 ## 动手前
 
 1. 读取 `skills/openprd-shared/SKILL.md`
 2. 重建当前工作区状态，判断用户究竟想确认什么
 3. 决定用户需要的是：
+   - `explanation-svg` 轻量解释图
    - `architecture` 视图
    - `product-flow` 视图
 4. 不要虚构今天还不存在的 OpenPrd diagram 命令
 
 ## 图示类型选择
 
+当用户在问这些内容时，优先选 `explanation-svg`：
+
+- 为什么会这样
+- 这两个方案差在哪里
+- 当前状态怎么走到目标状态
+- 过去、现在、未来的关系
+- 因果、依赖、边界、风险传播
+- Agent 要向用户解释需求场景、问题结构、决策取舍或下一步路径
+
+`explanation-svg` 是对话辅助。它可以用内联 SVG、HTML 片段或 Markdown 中的 SVG 代码块表达；它不需要写入 `.openprd/engagements/active/`，也不替代 `openprd diagram`、`review.html`、`visual-compare` 或测试证据。
+
 当用户在问这些内容时，选 `architecture`：
 
 - 模块
@@ -41,6 +53,17 @@ description: 生成并迭代 OpenPrd 图示产物，供用户确认。适用于
 
 - 当用户行为和流程仍不清楚时，先做 `product-flow` contract
 - 流程清楚后，再做架构评审
+- 如果只是为了让用户先理解取舍，不进入定稿评审，先给 `explanation-svg`
+
+## 解释型 SVG 规则
+
+- 输出顺序优先是：一句结论、SVG 图、最多 3 条补充说明或开放问题。
+- 图中每个节点只放短标签和 1 行例子；正文解释放到图下，不要把 SVG 变成文字墙截图。
+- 优先使用 2 到 5 个节点、明确箭头、颜色分组、虚线边界、少量图例；避免复杂渐变、装饰背景和难读小字。
+- 适合的图形包括：双栏对比、时间线、状态转移、边界/责任图、决策树、风险传播、因果反推。
+- 图中用户可见文案跟随用户当前主语言；中文语境用简体中文，专有名词可保留，但不要在中文语境下整句英文。
+- 如果没有足够事实支撑图中的节点或箭头，先把缺口写成“待确认”，不要把推测画成事实。
+- 需要模板时读取 `references/explanation-svg-patterns.md`。
 
 ## 当前工具能力
 
@@ -52,6 +75,7 @@ description: 生成并迭代 OpenPrd 图示产物，供用户确认。适用于
 
 因此：
 
+- 对 `explanation-svg`，直接在对话或临时 HTML/SVG artifact 中生成轻量图，不声称已进入正式 diagram 评审
 - 对 `architecture`，直接调用内置命令
 - 对 `product-flow`，即使还没有专门渲染器，也先生成结构化 contract 和评审清单
 - 如果工具还没有专用流程渲染器，就不要假装它已经存在
@@ -87,5 +111,6 @@ description: 生成并迭代 OpenPrd 图示产物，供用户确认。适用于
 ## 需要时阅读这些参考资料
 
 - `references/diagram-contracts.md`：架构图和产品流程图 contract
+- `references/explanation-svg-patterns.md`：解释型 SVG 的触发场景、图形模板和文案边界
 - `references/review-checklist.md`：渲染后应该问用户什么
 - `references/cocoon-patterns.md`：从 `Cocoon-AI/architecture-diagram-generator` 借来的可复用模式