@openprd/cli 0.1.1 → 0.1.8

package/README.md

@@ -1,246 +1,285 @@
 # OpenPrd
 
-[简体中文](./README_CN.md) | English
+简体中文 | [English](./README_EN.md)
 
-> AI-native PRD workspace and lifecycle CLI for requirement clarification, HTML-first review surfaces, diagram confirmation, and handoff.
+> 帮团队先把需求说清楚、确认清楚，再更稳地交付的 AI 原生 PRD 工作区与 CLI。
 
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20.19.0-339933.svg)](https://nodejs.org/)
 [![GitHub stars](https://img.shields.io/github/stars/mileson/openprd?style=social)](https://github.com/mileson/openprd)
 
-OpenPrd is a lightweight **PRD harness** for teams and agents that need more than “write a document”. It gives you a local workspace, a clarification-first workflow, policy-based review gates, diagram artifacts, and a structured change/spec/task workflow.
+OpenPrd 是一个轻量但结构化的 **PRD harness**。你只需要先把问题说出来，它会帮团队和 Agent 把需求整理成：
 
-Instead of hiding key decisions in prompts or terminal logs, OpenPrd keeps people and agents aligned around stable HTML artifacts such as `review.html`, learning readers, and quality reports.
+- 需求澄清
+- 用户确认
+- 图形化评审
+- 冻结前关卡控制
+- 面向执行系统的结构化交接
 
-![OpenPrd capability overview](https://raw.githubusercontent.com/mileson/openprd/main/docs/assets/openprd-capability-overview-en.png)
+它把关键确认点沉淀成稳定的 HTML 产物，而不是把版本状态散落在聊天记录或终端输出里。
 
-## Why OpenPrd
+![OpenPrd 能力总览](https://raw.githubusercontent.com/mileson/openprd/main/docs/assets/openprd-capability-overview-zh.png)
 
-OpenPrd is designed for the gap between:
+## 适合什么场景
 
-- vague product ideas that need clarification
-- agent-assisted requirement drafting
-- human confirmation at the right decision points before implementation
-- structured handoff into execution systems
+如果你希望：
 
-It is especially useful when you want:
+- 在写 PRD 前先澄清需求
+- 区分用户确认、项目已有事实和 Agent 推断
+- 在 freeze 前插入架构图 / 流程图评审
+- 让 Agent 遵循 repo 内置的协同规则
 
-- **clarify before drafting** instead of jumping straight to implementation
-- **source-aware capture** so user-confirmed facts stay separate from repo-derived, agent-inferred, or agent-normalized context
-- **policy-based review gates** that keep stable artifacts without forcing the same stop every time
-- **agent-facing skills** shipped with the tool, not hidden in a local environment
+那么 OpenPrd 就很适合你。
 
-## Where OpenPrd Is Different
+如果你的同事经常会说“我大概想做这个，但还没完全想清楚”，这通常就是 OpenPrd 最能发挥作用的时候。
 
-OpenPrd lives in a different spot than tools that are centered only on spec files
-or only on coding execution.
+## 一句话需求进来，OpenPrd 怎么接住
 
-| Tool | Center of gravity | Main user-facing artifacts | Best fit |
-|------|-------------------|----------------------------|----------|
-| **OpenPrd** | Requirement clarification, HTML-first collaboration, and delivery gates | `review.html`, learning readers, quality reports, diagrams, structured change/task state | Teams that need humans and agents to stay aligned through planning, review, execution, and ship decisions |
-| **OpenSpec** | Spec and change lifecycle | Markdown proposals, specs, design docs, tasks | Teams that want disciplined spec deltas and a clean change-management workflow |
-| **Superpowers** | Skill-driven coding execution | Skills, plans, worktree/subagent flows, code-review checkpoints | Engineering-heavy teams optimizing how AI agents plan, code, review, and finish branches |
+你不需要先判断自己提的是 `L0 / L1 / L2`，也不需要先想清楚技术方案。直接用业务语言说明：谁在什么场景下遇到了什么问题、你想先解决哪一块。OpenPrd 会先帮你整理，再选择合适的推进节奏。
 
-OpenPrd is strongest when the hard part is not just "what code should be written,"
-but "what should people confirm, what should stay visible, and what evidence is
-enough to move forward."
+![OpenPrd 需求分流节奏](https://raw.githubusercontent.com/mileson/openprd/main/docs/assets/openprd-requirement-routing-zh.png)
 
-## Common Real-World Scenarios
+- **快速修正**：问题已经很明确，影响小，验收也清楚。通常直接处理，改完告诉你改了什么、怎么验证。
+- **现有功能优化**：目标明确，但会牵动几个页面、状态或用户动作。OpenPrd 会先用人话给你一版 mini-plan，方向对了再继续。
+- **新功能 / 新流程方案**：范围更大，角色更多，或者业务风险还不清楚。先把用户场景、第一版、先不做什么和主要风险讲清楚，再进入完整方案和任务拆解。
 
-Recent Codex project usage kept clustering around the same kinds of work: fuzzy
-product requests, existing-product redesigns, release/publish flows, production
-incident closure, and reusable learning handoff.
+如果更偏个人用户场景，OpenPrd 会更关注用户在什么时候会用、第一下有没有感受到价值、会不会愿意继续回来；如果更偏团队 / 企业流程，会更关注谁拍板、谁使用、谁要推进上线；如果更偏 Agent 协作，会更关注哪些环节可以自动做、哪里必须人工兜底。整个过程默认先讲结果、场景和风险，不先把内部术语丢给你。
 
-| Scenario | Why OpenPrd stands out here | Main artifacts |
-|----------|-----------------------------|----------------|
-| Fuzzy product request before anyone codes | Clarify first, separate user-confirmed facts from agent inference, then turn the result into a stable review surface. | `clarify`, `capture`, `synthesize`, `review.html` |
-| Existing flow or auth-entry redesign | Reconstruct current behavior from repo and runtime evidence before proposing the next change. | `discovery`, `diagram`, `review.html`, `change` |
-| Visual or product-flow confirmation | Keep architecture, product flow, or UI replication reviewable instead of burying decisions in chat. | `diagram`, `visual-compare`, side-by-side JPG reviews |
-| Long-running agent implementation chain | Turn accepted work into dependency-ready tasks and run one focused agent session per task with verify gates. | `tasks`, `loop`, prompts, progress logs, verification reports |
-| Release, publish, or handoff readiness | Make "ready to ship" a visible decision with standards, regression evidence, abuse/cost guardrails, and workspace health. | `quality`, `run --verify`, `doctor`, `handoff` |
-| Learning handoff after a fix or project | Package the final requirement, reasoning, and outcome into something new collaborators can actually study. | learning reader, `.openprd/knowledge/skills/`, docs sync |
+## OpenPrd 和 OpenSpec / Superpowers 有什么不一样
 
-## HTML-First Collaboration Surfaces
+OpenPrd 解决的问题，不只是“把 spec 写出来”，也不只是“把代码跑起来”，而是让
+人和 Agent 在需求、评审、执行、交付这些关键节点上始终对齐。
 
-OpenPrd produces stable, shareable HTML surfaces so product owners, engineers,
-and agents can look at the same artifact before work moves forward.
+| 工具 | 重心 | 用户主要看到的产物 | 更适合什么 |
+|------|------|--------------------|------------|
+| **OpenPrd** | 需求澄清、HTML 优先协作、交付门禁 | `review.html`、学习阅读器、质量报告、图示、结构化 change/task 状态 | 需要把人机协同、评审确认、执行推进和交付判断串起来的团队 |
+| **OpenSpec** | spec / change 生命周期 | Markdown proposal、spec、design、tasks | 更关注 spec 增量治理和变更编排的团队 |
+| **Superpowers** | skill 驱动的编码执行流 | skills、plans、worktree / subagent 流程、代码评审检查点 | 更关注 AI Agent 如何规划、编码、review、收尾的工程团队 |
+
+OpenPrd 最有特色的地方，在于它把“这次到底在做什么、谁来确认、凭什么继续往下走”
+做成稳定可见的协作面，而不是只留在 spec 文件或 prompt 流程里。
+
+## 典型真实场景
+
+最近 30 天的 Codex 项目记录里，OpenPrd 反复出现在几类连续工作里：模糊需求澄清、
+已有产品流程改造、发布与交付、线上问题闭环，以及把一次完成的工作整理成可复用学习资料。
+
+| 场景 | 为什么这里更像 OpenPrd 的强项 | 主要产物 |
+|------|--------------------------------|----------|
+| 模糊产品需求，先别急着写代码 | 先澄清，再区分用户确认事实与 Agent 推断，最后把结果沉淀成稳定评审页。 | `clarify`、`capture`、`synthesize`、`review.html` |
+| 已有流程或登录入口改造 | 先从仓库与运行态重建当前事实，再决定下一步 change，而不是直接拍脑袋改。 | `discovery`、`diagram`、`review.html`、`change` |
+| 流程图、界面或架构确认 | 把理解差异放到图示和可评审产物里，而不是埋在聊天记录里。 | `diagram`、`visual-compare`、左右对比 JPG |
+| 长程 Agent 执行链路 | 把确认后的工作拆成按依赖可执行的小任务，每次新会话只推进一个任务并带验证门禁。 | `tasks`、`loop`、任务提示词、进度日志、验证报告 |
+| 发布、开源、交接前收口 | 让“现在能不能交付”变成有证据的显式判断，而不是靠感觉。 | `quality`、`run --verify`、`doctor`、`handoff` |
+| 一次需求或修复做完后沉淀学习资料 | 把最终需求、过程判断和结果整理成新成员可以直接学习的资料。 | 学习阅读器、`.openprd/knowledge/skills/`、docs 同步 |
+
+## HTML 优先协作产物
+
+OpenPrd 会生成可以直接分享的 HTML 面板，让产品、研发和 Agent
+围绕同一份稳定 artifact 协作，而不是各自回放聊天记录或命令输出。
 
 ### `review.html`
 
-Use a review-ready PRD surface instead of asking teammates to reconstruct the
-latest requirement state from chat history.
+把当前需求版本整理成可评审页面，适合先给产品、研发或负责人确认“这次到底在做什么”。
+如果项目已经启用 `release` 版本轨道，评审页顶部也会直接显示当前 `项目版本`。
 
 ![OpenPrd review HTML](https://raw.githubusercontent.com/mileson/openprd/main/docs/assets/openprd-review-html.png)
 
-### Learning reader
+### 学习阅读器
 
-Turn a finished requirement, fix, or workflow into a readable learning package
-that new collaborators can study without replaying the whole thread.
+把一次需求、修复或协作方法整理成图文学习资料，方便新成员理解“这套流程为什么这样设计”。
 
 ![OpenPrd learning HTML](https://raw.githubusercontent.com/mileson/openprd/main/docs/assets/openprd-learning-html.png)
 
-### Quality regression report
+### 质量回归报告
 
-Summarize readiness, required gates, evidence coverage, and manual decisions in
-one human-readable quality surface before handoff, release, or publish.
+把准备就绪状态、必需门禁、验证材料和仍需人工判断的点放到一个可读页面里，再决定是否继续交付或发布。
 
 ![OpenPrd quality HTML](https://raw.githubusercontent.com/mileson/openprd/main/docs/assets/openprd-quality-html.png)
 
-### Auto-optimized reference-to-screenshot comparison
-
-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.
+### 效果图与截图拼图对比，自动优化
 
-![Auto-optimized reference-to-screenshot comparison](https://raw.githubusercontent.com/mileson/openprd/main/docs/assets/openprd-visual-compare-case-study-en.png)
+把效果图和实现截图放进同一张左右对比图里，适合登录入口改造、条款页本地化、弹窗复刻这类阶段性评审。
 
-## Self-Evolving Collaboration
+![效果图与截图拼图对比，自动优化](https://raw.githubusercontent.com/mileson/openprd/main/docs/assets/openprd-visual-compare-case-study-zh.png)
 
-OpenPrd gets easier to work with over time through two visible loops. One loop
-keeps proven team habits as reusable `Project-Level Skill`s. The other keeps
-`Dynamic Parameter Config` adaptive, so different project situations start with
-different collaboration defaults instead of the same generic checklist.
+## 自我成长机制
 
-![OpenPrd self-evolving collaboration](https://raw.githubusercontent.com/mileson/openprd/main/docs/assets/openprd-self-evolving-mechanisms-en.png)
+OpenPrd 会沿着两条看得见的循环，越用越贴合你们的协作方式。一条循环把真实项目里反复验证过的做法沉淀成可复用的 `项目级 Skill`；另一条循环把不同场景下更合适的协作设置沉淀成 `动态参数配置`，让下次启动时直接带上更合适的默认做法。
 
-### Scenario 1: Project-Level Skill
+![OpenPrd 自我成长机制](https://raw.githubusercontent.com/mileson/openprd/main/docs/assets/openprd-self-evolving-mechanisms-zh.png)
 
-When a team reaches the same conclusion in real work more than once, OpenPrd
-can keep that conclusion close to the project instead of leaving it buried in
-chat.
+### 场景一：项目级 Skill
 
-- Example: a login-entry redesign confirms that log in, sign up, and password reset should all stay on the official site.
-- What gets reused next time: related page checks, release review points, and the preferred path through similar requests.
-- Why it matters: the next similar request starts from a shared playbook, and new teammates can follow the same steps without retelling the whole history.
+当团队在真实工作里反复确认同一种判断，OpenPrd 不会让它继续散落在聊天记录里，而是把它留在项目身边。
 
-### Scenario 2: Dynamic Parameter Config
+- 例子：一次登录入口改造里，团队确认“登录、注册、找回密码都走官网”。
+- 下次能直接复用什么：相关页面要一起检查、发布前要核对哪些入口和文案、类似需求应该沿着什么路径推进。
+- 为什么有用：下一次类似需求不会再从零开始，新成员接手也能直接照着做。
 
-Not every project should start the same way. OpenPrd can keep different
-collaboration defaults for different situations and bring them back
-automatically.
+### 场景二：动态参数配置
 
-- Example: a greenfield request starts with goal clarification and scope alignment, while an inherited project starts with current-state reconstruction and boundary mapping.
-- What changes automatically: what to ask first, what to inspect first, and what proof to gather before handoff.
-- Why it matters: teams spend less time re-explaining how this kind of project should run and more time moving with the right setup from the start.
+不是每个项目都该用同一套起手方式。OpenPrd 会把不同场景下更合适的协作设置留住，并在下次自动带回来。
 
-## Features
+- 例子：一个新项目会先澄清目标和范围，一个接手中的旧项目会先还原现状和改动边界。
+- 下次会自动带上什么：先问什么、先看什么、交付前先收什么材料。
+- 为什么有用：团队不用每次重新解释“这类项目该怎么开场”，而是直接从更合适的默认方式开始。
 
-- **Clarification-first workflow**: `clarify -> capture -> classify -> interview -> synthesize -> diagram -> freeze -> handoff`
-- **Scenario-aware collaboration**: distinguish greenfield cold start, existing-project cold start, and continuing workspaces
-- **Self-evolving collaboration**: turn confirmed project habits into reusable `Project-Level Skill`s and adapt `Dynamic Parameter Config` by scenario
-- **Source-aware capture**: mark inputs as `user-confirmed`, `project-derived`, `agent-inferred`, or `agent-normalized`
-- **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
-- **Contract-driven diagrams**: render from validated JSON contracts
-- **Review status tracking**: use `pending-confirmation`, `confirmed`, and `needs-revision`
-- **OpenPrd discovery mode**: initialize durable coverage runs for existing projects, reference projects, or unclear requirements
-- **Project standards**: initialize and verify `docs/basic/`, file manual templates, and folder README templates as part of execution quality gates
-- **Quality Regression Reports**: review overall regression status, per-requirement module status, test-block results, observability, business cost and abuse guardrails, smoke coverage, performance baselines, and project knowledge through HTML reports
-- **Project knowledge skills**: turn verified fixes and recurring diagnosis patterns into reusable `.openprd/knowledge/skills/` experience skills
-- **OpenPrd change and task execution**: materialize PRD snapshots into change files, validate them, apply accepted specs, archive changes, and advance structured tasks by dependency order
-- **Long-running agent loop**: turn accepted change tasks into one-task-per-session Codex or Claude execution prompts with verification, progress logs, and optional task commits
-- **Default agent integration**: generate Codex, Claude, and Cursor guidance from one OpenPrd source, including Codex hooks with `codex_hooks = true`
-- **Agent harness skills**: repo-local skills for shared rules, workflow control, and diagram review
+## 功能
 
-## Tech Stack
+- **Clarification-first**：`clarify -> capture -> classify -> interview -> synthesize -> diagram -> freeze -> handoff`
+- **场景感知协同**：区分空项目冷启动、已有项目首次接入、持续推进中的 workspace
+- **自我成长机制**：把真实项目里确认过的做法沉淀成可复用的 `项目级 Skill`，并按场景沉淀 `动态参数配置`
+- **来源感知采集**：支持 `user-confirmed` / `project-derived` / `agent-inferred` / `agent-normalized`
+- **图形评审工件**：支持 `architecture` 和 `product-flow`
+- **界面视觉对比工件**：把效果图与实现截图合成左右对比 JPG，用于阶段性复刻评审
+- **Contract 驱动图渲染**：支持从 JSON contract 显式渲染
+- **Review status**：支持 `pending-confirmation` / `confirmed` / `needs-revision`
+- **用户视角变化摘要**：`loop commit`、`handoff` / 版本说明、`review` 摘要默认优先使用 `新增 / 修复 / 优化 / 调整 / 移除` 这类短标签
+- **项目级版本轨道**：可选维护 `0.1.23` 这类项目版本号、版本内变化条目，以及与本地 git tag 的协同，不和内部 PRD `v000x` 混用
+- **策略化评审门禁**：PRD review 记录和执行意图分离；不能把“可以开做”当成任意评审稿的 `review --mark confirmed`
+- **OpenPrd 发现模式**：为已有项目、参考项目或不清晰需求初始化可持续推进的覆盖状态
+- **项目标准化**：初始化并验证 `docs/basic/`、文件说明书模板和文件夹 README 模板
+- **OpenPrd change 与任务执行**：从 PRD 快照生成 change 文件，校验结构，沉淀 accepted specs，归档变更，并按依赖顺序推进结构化任务
+- **长程 Agent Loop**：把 change 任务转成“一次新会话只做一个任务”的 Codex / Claude 执行提示词，并沉淀验证、进度日志和可选任务 commit
+- **默认 Agent 接入**：从一套 OpenPrd 源生成 Codex、Claude、Cursor 三端规则，并默认开启 Codex hooks
+- **Repo 内置 skills**：工具和 Agent 协同约束一起发布
 
-| Layer | Technology |
-|-------|------------|
-| Runtime | Node.js 20+ |
-| CLI | Native Node ESM |
-| Config / state | JSON + YAML |
-| Diagram renderer | Self-contained HTML + inline SVG |
-| Image processing | `sharp` for JPG / PNG / WebP visual comparison artifacts |
-| Testing | `node --test` |
-| Agent guidance | Repo-local `skills/` + `AGENTS.md` + Codex / Claude / Cursor generated adapters |
+## 一句话安装
 
-## One-line Install
+```bash
+npm install -g @openprd/cli
+```
 
-Install from npm:
+如果你只是想先跑起来，或者 Windows 里刚装完 CLI 但 `openprd` 还没出现在 `PATH`，也可以直接用 `npx`：
 
 ```bash
-npm install -g @openprd/cli
+npx @openprd/cli@latest --help
+npx @openprd/cli@latest init . --template-pack agent
 ```
 
-Then verify:
+安装后验证：
 
 ```bash
 openprd --help
 ```
 
-Update the installed CLI later with a dry-run first:
+### Windows 排查
+
+如果全局安装成功后依然提示找不到 `openprd`，先检查：
+
+```powershell
+where openprd
+npm config get prefix
+```
+
+如果 `where openprd` 没有结果，把 npm global prefix 加到 `PATH` 后再重新打开终端。Windows 下这个目录通常是 `%AppData%\npm`，不是 Unix 常见的 `{prefix}/bin`。
+
+之后更新 CLI 时先预演，再执行：
 
 ```bash
 openprd self-update --dry-run
 openprd self-update
 ```
 
-## Quick Start
+## 快速开始
 
-### 1. Initialize a workspace
+### 1. 初始化
 
 ```bash
 openprd init /path/to/project --template-pack agent
 ```
 
-`init` creates `.openprd/`, `docs/basic/`, `AGENTS.md`, and generated Codex / Claude / Cursor guidance. Codex projects also get `.codex/config.toml`, `.codex/hooks.json`, `.codex/hooks/openprd-hook.mjs`, and user-level Codex `codex_hooks = true`.
+如果 `openprd` 还没进 `PATH`，直接把同一条命令前面换成 `npx @openprd/cli@latest` 即可：
+
+```bash
+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 `codex_hooks = true`。
 
-Codex hooks default to `lite`: `UserPromptSubmit`, a lightweight `PreToolUse`
-write gate, and a lightweight `Stop` end-of-turn review. Context is injected for prompts that explicitly mention OpenPrd,
-PRD, deep research/benchmarking, replication, standards, fleet, documentation
-standards, or look like new product/module/workflow requirements. The lite write
-gate only matches direct editing tools so read-only shell exploration stays
-quiet, while `Stop` reviews whether the current turn produced a reusable project
-pattern; use `guarded` when shell commands should also pass through the write gate,
-and `full` only for temporary deep diagnostics.
-Concrete bugfix prompts with diagnostic evidence such as errors, logs, repro
-steps, or root-cause investigation skip requirement intake when the user asks to
-fix directly; confirmation wording also accepts phrases like "confirm the fix".
+Codex hooks 默认使用 `lite` 模式：安装 `UserPromptSubmit`、轻量
+`PreToolUse` 写入门禁，以及轻量 `Stop` 收工回顾。明确提到 OpenPrd、PRD、深度调研、深度对标、复刻、
+standards、fleet、文档标准化，或看起来像新产品 / 模块 / 流程需求的提示词都会
+注入上下文；`lite` 写入门禁只匹配直接编辑工具，让只读 shell 探查保持安静；`Stop`
+会在本轮结束前回顾是否值得沉淀项目经验。
+需要连 shell 命令也进入写入门禁时使用 `guarded`，只有临时深度诊断才使用
+`full`。
+如果用户给出报错、日志、复现、根因排查等明确故障证据，并要求直接修复，
+hook 会按小型 bugfix 处理，不开启需求入口；“确认修复”这类确认词也会关闭
+已打开的需求入口。
 
-### 2. Check the current collaboration state
+`init` 还会顺手做一层非阻断式可选能力检测，并把结果写进
+`.openprd/harness/install-manifest.json` 的 `optionalCapabilities`。例如：
+
+- `Context7`：帮助 Agent 获取最新的第三方技术文档、配置、版本差异、迁移路径和高质量实现信息
+- `DeepWiki`：帮助 Agent 用对话方式理解 GitHub 公开仓库的架构、关键流程和实现线索
+
+如果这些能力尚未配置，初始化不会失败；OpenPrd 只会把它记录成后续建议，并附上官方文档、GitHub 地址和 MCP 地址，方便后面按当前客户端补配置。
+
+### 2. 查看当前协同节奏
 
 ```bash
 openprd status /path/to/project
 openprd next /path/to/project
 ```
 
-### 3. Clarify with the user
+如果项目已经启用版本轨道，`status` 也会直接显示当前项目版本和该版本累计了多少条变化项。
+
+### 2b. 可选：设置项目版本轨道
+
+```bash
+openprd release /path/to/project --set 0.1.23
+openprd release /path/to/project --notes "新增版本说明入口"
+openprd release /path/to/project
+```
+
+`release` 维护的是项目级版本账本，不是 OpenPrd 内部 PRD 的 `v0004` 这类版本号。启用后，后续 handoff、版本说明和 `loop --finish --commit` 的本地 tag 协同都会优先复用这里的版本信息。
+
+如果 OpenPrd 自身要把新版本发布到 GitHub，默认还要推送匹配的版本 tag，并配套 GitHub Release。可以先用 `node scripts/openprd-github-release-notes.mjs /path/to/project --version 0.1.23 --tag v0.1.23 --out /tmp/openprd-release.md` 预览发布文案；仓库内的 `github-release` workflow 会在 tag push 或手动触发时，基于同一份 `release-ledger` 自动创建或更新 GitHub Release。
+
+### 3. 先向用户澄清
 
 ```bash
 openprd clarify /path/to/project
 ```
 
-Clarification stays in the conversation as an inline outline or short checklist. The formal HTML review surface is `review.html` after synthesis.
+澄清阶段只在对话里输出提纲或简短清单；正式 HTML 评审统一留给合成后的 `review.html`。
 
-### 4. Capture answers back into the workspace
+OpenPrd 会先按用户可见的需求类型接住这句话，而不是先让你填一堆表单：
 
-Single field:
+- **快速修正**：通常直接做，做完告诉你改了什么、怎么验。
+- **现有功能优化**：先给一版 mini-plan，你确认方向后再继续。
+- **新功能 / 新流程方案**：先把场景、范围、第一版和风险说清楚，再进入 `review`、`change` 和 `tasks`。
+
+### 4. 写回答案
+
+单条写回：
 
 ```bash
 openprd capture /path/to/project \
   --field problem.problemStatement \
-  --value "Mobile users cannot efficiently manage agent sessions on the go" \
+  --value "移动端缺少高效的 Agent 会话与节点管理入口" \
   --source user-confirmed
 ```
 
-Batch capture:
+批量写回：
 
 ```bash
 openprd capture /path/to/project --json-file answers.json
 ```
 
-If `openprd synthesize` reports that the generated `spec.md` would still fail the
-Simplified Chinese preflight, normalize the wording with
-`--source agent-normalized` before recording the current `review.html` artifact.
+`--source agent-normalized` 只用于 `capture` 之后的纯内部措辞整理，
+这类没有语义变化的润色不应重开当前 `review.html` 的确认。
 
-### 5. Draft and review
+### 5. 生成草稿与图
 
 ```bash
 openprd synthesize /path/to/project \
   --title "Moticlaw Mobile" \
   --owner "Moticlaw" \
-  --problem "Mobile users lack a direct-first client for node selection and agent interaction." \
-  --why-now "The control plane already exists and the missing piece is a mobile entry point."
+  --problem "移动端用户缺少直连优先的节点选择与 Agent 会话入口。" \
+  --why-now "控制面已经具备，当前缺少的是移动端入口。"
 
 openprd review-presentation /path/to/project --template
 openprd review-presentation /path/to/project \
@@ -254,52 +293,49 @@ openprd review /path/to/project --open
 openprd review /path/to/project --mark confirmed --version <id> --digest <sha256> --work-unit <id>
 ```
 
-`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:
+`review.html` 是当前 PRD 的稳定评审稿，但默认 approval policy 是
+`decision-points`，不是“每次都必须停在这里”。常规 lane 下，用户先看稳定
+artifact，再用页面复制出来的精确 `--version`、`--digest`、`--work-unit`
+记录确认；`silent-record` lane 只有在用户一开始已经明确要求直接做、并显式
+表示不需要额外评审或确认时，才允许直接记录当前这份精确 artifact。不要把
+实现授权当成给任意评审稿补确认，也不要把评审记录当成实现授权。当前 artifact
+记录完成后，再生成 OpenPrd change 和任务拆解；如果用户原始意图已明确要求
+实现，tasks 就绪后即可直接执行，否则等待一句明确的执行指令：
 
 ```bash
 openprd change /path/to/project --generate --change <change-id>
 openprd tasks /path/to/project --change <change-id>
 ```
 
-### 6. Freeze and handoff
+### 6. Freeze 与 handoff
 
 ```bash
 openprd freeze /path/to/project
 openprd handoff /path/to/project --target openprd
 ```
 
-### 7. Start OpenPrd discovery mode
+`handoff` 导出的 `handoff.json` 和 `handoff.md` 会同时带上用户视角的变化摘要 / 版本说明片段，默认按 `新增 / 修复 / 优化 / 调整 / 移除` 组织，方便直接扫读或复用。若项目已启用 `release` 版本轨道，handoff 会优先导出当前项目版本下累计的变化条目，并额外写出 `项目版本: 0.1.23` 这类信息。
+
+### 7. 启动 OpenPrd 发现模式
 
-Users can ask in natural language:
+用户可以直接用自然语言说：
 
 ```text
-Use OpenPrd to deeply complete this project.
-Use OpenPrd to comprehensively mine this reference project into the new project.
-Keep digging into this requirement until OpenPrd coverage is complete.
+用 OpenPrd 深度补全这个项目。
+用 OpenPrd 全面复刻这个参考项目的产品逻辑。
+继续深挖这个需求，直到 OpenPrd 覆盖完整。
 ```
 
-Discovery and loop execution require explicit depth or execution intent. For
-planning, architecture review, impact analysis, or "which files would change?"
-questions, agents should inspect state and answer read-only instead of advancing
-coverage or launching loop tasks.
+Discovery 和 loop 执行需要明确的深度或执行意图。用户只是说“看看、规划、
+梳理、分析、预计动哪些文件、怎么改”时，Agent 应只读检查状态和代码后回答，
+不得推进 coverage，也不得启动 loop 任务。
 
-Agents route those requests internally. The underlying command is:
+Agent 会在内部完成路由。底层命令是：
 
 ```bash
 openprd discovery /path/to/project --mode brownfield
 openprd discovery /path/to/project --resume
-openprd discovery /path/to/project --advance --claim "Users can start a session from the dashboard" --evidence src/app.ts
+openprd discovery /path/to/project --advance --claim "用户可以从工作台发起会话" --evidence src/app.ts
 openprd discovery /path/to/project --verify
 openprd change /path/to/project --generate --change <change-id>
 openprd change /path/to/project --validate --change <change-id>
@@ -312,20 +348,18 @@ openprd specs /path/to/project
 openprd changes /path/to/project
 ```
 
-Discovery verification also checks the active OpenPrd change structure, spec deltas,
-`docs/basic/` standards, and long-running task files. Keep `tasks.md` as the first
-entry, cap each task file at 25 substantive checkbox tasks, and continue with
-`tasks-002.md`, `tasks-003.md`, etc. The final checkbox in every non-final file
-should hand off to the next file so agents can resume in order. A project can use
-a stricter local cap with `.openprd/discovery/config.json` at
-`taskSharding.maxItemsPerFile`.
+持续发现的校验也会检查当前 OpenPrd change 结构、spec delta、`docs/basic/`
+标准化文档和长程任务文件。保留 `tasks.md` 作为第一个入口，每个任务文件最多放
+25 个实质 checkbox 任务；超过后继续使用 `tasks-002.md`、`tasks-003.md`。
+每个非最终任务文件的最后一个 checkbox 应指向下一个任务文件，方便 Agent 按顺序
+继续。项目也可以通过 `.openprd/discovery/config.json` 的
+`taskSharding.maxItemsPerFile` 使用更细的本地限制。
 
-That 25-item limit is only a sharding cap, not a decomposition target. Prefer task
-titles that describe concrete implementation units, wiring boundaries, entry
-surfaces, integration closures, and regression passes instead of mirroring PRD
-section labels like "primary flow", "requirement", or "acceptance goal".
+这里的 25 只是分片上限，不是拆解目标。任务标题应优先描述可直接落地的实现单元、
+接线边界、页面入口、集成闭环和回归项，而不是把“主流程 / 功能需求 / 验收目标 /
+非功能需求”这些 PRD 小节逐条平移成 checkbox。
 
-When a task needs a stable id for long-running execution, keep the metadata small:
+如果任务需要稳定编号来支撑长程执行，只保留最小元数据：
 
 ```md
 - [ ] T009.07 Port legacy database import preview
@@ -333,28 +367,36 @@ When a task needs a stable id for long-running execution, keep the metadata smal
   - deps: T001.14, T007.06
   - done: preview shows counts, conflicts, skipped items, warnings
   - verify: npm run test -- migration
-  - oracle: compare sample import output against the legacy preview and record mismatches
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: cli-contract
+  - evidence-plan: 单元测试覆盖导入解析，命令行契约输出留下证据
 ```
 
-Use `type` to distinguish `implementation`, `verification`, `documentation`, and
-`governance` work. `deps` is only needed when the task depends on earlier task ids.
-`done` is the completion condition, and `verify` is the command or review step
-that proves it. For `implementation`, `verification`, and `documentation` tasks,
-`verify` must exercise the real work, such as `openprd run . --verify`, test
-commands, or an explicit manual review step; do not use `openprd change . --validate`
-as the only proof. Use `oracle` when the task must compare against a reference
-implementation, golden data set, screenshot baseline, or other explicit source
-of truth; `openprd loop --finish` then requires `--notes` or `--evidence` so the
-comparison result is recorded.
+`type` 用来区分 `implementation`、`verification`、`documentation` 和
+`governance`。`deps` 只在依赖前置任务时填写；`done` 写完成条件；`verify`
+写验证命令或审查步骤。生成的 `implementation` 和 `verification` 任务默认使用
+`openprd tasks . --change <id> --item <task-id> --evidence-required`：Agent 先运行本任务最小足够测试或审查，再通过
+`--evidence <路径或摘要>` 传入证据，或在任务 metadata 写入 `evidence:` /
+`waiver-reason:`；文档任务仍使用 standards 校验。`openprd run . --verify`
+保留给阶段或最终门禁，不作为每个任务的默认验证；也不能只用
+`openprd change . --validate` 代替真实落地证据。旧版生成任务如果仍写着
+`verify: openprd run . --verify`，通过 `openprd tasks --verify` 执行时也会
+按本任务 evidence 门处理，不会继续反复生成 workspace quality 报告。
 
-`tasks` lists the next dependency-ready task by default. `--advance` marks
-one task complete, and `--verify` runs that task's `verify` command before marking
-it complete. Execution events are stored outside the task files so the task metadata
-stays small.
+任务也可以包含测试策略元数据。`test-layer`、`test-size`、`test-scope`
+和 `evidence-plan` 用来帮助 OpenPrd 按风险选择最小足够证据：局部逻辑优先单元测试，
+触达 CLI/API/Agent 契约或跨模块状态时使用集成/契约验证，触达用户主路径、视觉、小程序、
+性能、安全或成本风险时升级到端到端或专项验证。这些字段是证据分流，不是固定 70/20/10
+比例门禁。
 
-## Project Standards
+`tasks` 默认列出下一个依赖已满足的任务。`--advance` 会勾选完成任务；
+同时传 `--verify` 时，会先运行该任务的 `verify` 命令，通过后再勾选。执行记录
+写在任务文件外，避免把 `tasks.md` 元数据变复杂。
 
-`openprd init` creates a project standards contract:
+## 项目标准化
+
+`openprd init` 会创建项目标准化契约：
 
 - `docs/basic/file-structure.md`
 - `docs/basic/app-flow.md`
@@ -365,29 +407,31 @@ stays small.
 - `.openprd/standards/file-manual-template.md`
 - `.openprd/standards/folder-readme-template.md`
 
-Use:
+当项目已经存在源码文件时，`openprd standards --verify` 不只检查文件是否存在，还会阻断以下情况：
+
+- `docs/basic/` 仍停留在“待补充”等模板占位内容。
+- 源码文件头部缺少文件说明书。
+- 承载源码的文件夹缺少 `[项目名]_[文件夹名]_README.md` 文件夹说明书。
+
+检查命令：
 
 ```bash
 openprd standards /path/to/project --verify
 ```
 
-OpenPrd generated changes include standards maintenance tasks, and change validation
-checks the standards contract. The canonical project docs path is only
-`docs/basic/`.
+OpenPrd 生成的 change 会包含标准化维护任务，change 校验也会检查这套契约。
+项目基础文档的唯一标准路径是 `docs/basic/`。
 
-During implementation, standards maintenance is an explicit impact check, not a
-best-effort cleanup. For every added or modified source file, agents should check
-whether `docs/basic/`, the file manual, or the containing folder README is missing
-or stale. Missing docs must be created; existing docs should be updated whenever
-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.
+实现阶段的标准化维护是明确的影响判定，不是最后顺手清理。每次新增或修改源码
+文件时，Agent 都要检查 `docs/basic/`、文件说明书、所在文件夹 README 是否缺失
+或已因本次变更过期。缺失的必须补齐；已有文档如果受到职责、流程、结构、依赖
+或产品行为变化影响，也必须同步更新。如果无需更新，应说明已经完成影响判定以及
+为什么现有文档仍然准确。
 
-## Auto-optimized reference-to-screenshot comparison
+## 效果图与截图拼图对比，自动优化
 
-When UI work already has a reference effect image, design image, user-provided
-screenshot, or agent-generated mock, the agent should capture the implemented
-UI and generate a side-by-side review image before claiming visual completion:
+当界面任务已经有效果图、设计稿、用户给图或 Agent 自己生成的 mock 时，Agent
+在阶段性完成后应先截实现图，再生成左右对比图，不能只靠主观印象判断是否一致：
 
 ```bash
 openprd visual-compare /path/to/project \
@@ -395,10 +439,20 @@ openprd visual-compare /path/to/project \
   --actual implementation-screenshot.jpg
 ```
 
-The default output is a compact JPG under
-`.openprd/harness/visual-reviews/`. The left panel is labeled `效果图`; the
-right panel is labeled `实现截图`. Inputs can be common image formats supported
-by `sharp`. The output can be adjusted when needed:
+默认会在 `.openprd/harness/visual-reviews/` 下输出体积较小的 JPG。左侧标注
+`效果图`，右侧标注 `实现截图`。输入可以是 `sharp` 支持的常见图片格式。
+
+如果界面任务没有明确效果图，Agent 应先截修改前截图，完成改动后用同一入口、
+视口、账号和数据状态再截修改后截图：
+
+```bash
+openprd visual-compare /path/to/project \
+  --before before-screenshot.png \
+  --after after-screenshot.jpg
+```
+
+修改前后模式会把左侧标注为 `修改前`、右侧标注为 `修改后`，帮助 Agent 检查
+预期变化是否出现，以及未改区域是否有布局、颜色、密度或状态漂移。输出也可以按需要调整：
 
 ```bash
 openprd visual-compare /path/to/project \
@@ -410,52 +464,40 @@ openprd visual-compare /path/to/project \
   --max-panel-width 1180
 ```
 
-Agents should inspect the generated image and keep iterating until there are no
-obvious visual differences. The final response for reference-driven UI work
-should include the generated review image path and note whether differences
-remain.
+Agent 必须查看生成图并继续对标，直到没有明显视觉差异。最终回复里应给出本次
+生成的对比图路径，并说明对比后是否仍有差异。
 
-## Quality Regression Reports
+## 回归测试与质量评估报告
 
-`openprd init` also creates a quality contract:
+`openprd init` 同时会创建质量契约：
 
 - `.openprd/quality/config.json`
 - `.openprd/quality/reports/`
 - `.openprd/knowledge/`
 
-Use:
+检查命令：
 
 ```bash
 openprd quality /path/to/project --verify
 ```
 
-The command writes both JSON and HTML reports under `.openprd/quality/reports/`.
-The HTML regression report is the human-readable quality surface: overall
-regression status, per-requirement module status, test-block pass/fail results,
-missing items, and the small set of gaps that need a person to decide whether
-they are in scope for the current delivery. EVO is OpenPrd's internal shorthand
-for the evaluation/verification quality layer; the visible report does not ask
-users to know that acronym. A script or fixture being present only proves
-capability; required gates need current evidence or an explicit waiver.
-
-When a requirement involves free users, quotas, AI calls, third-party APIs,
-generation, storage, downloads, or other metered costs, `quality --verify`
-also checks for cost drivers, user-level limits, negative abuse-path
-verification, usage/cost monitoring, alert thresholds, and stop-loss actions.
-
-`openprd quality --verify` is blocking by default when required test blocks are
-not production-ready. `openprd run --verify` repeats that quality gate so final
-readiness cannot ignore the report. Agents should not claim readiness until
-every required test block is either passing with evidence or explicitly out of
-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.
-
-After a fix has been verified and reviewed, promote the abstract pattern into
-project knowledge:
+该命令会在 `.openprd/quality/reports/` 下同时写入 JSON 和 HTML。HTML 回归测试报告
+是阶段性质量查看的主要产物，优先展示整体回归结果、逐需求模块结果、测试块通过情况、
+分层测试策略矩阵、未通过项和需要确认是否属于本期的遗漏。EVO 是 OpenPrd 内部对
+“质量评估/验证层”的简称；用户可见报告不要求理解这个缩写。脚本、依赖或 fixture
+存在只代表项目具备能力，不能替代本次运行证据。
+
+当需求涉及免费用户、额度、AI 调用、第三方 API、生成、存储、下载或其他消耗型成本时，
+`quality --verify` 会额外检查是否存在成本来源、用户级限制、负向验证、用量/成本监控、
+报警阈值和止损动作，避免免费额度或高成本路径在上线后才暴露。
+
+`openprd quality --verify` 默认会在本期必测块未 production-ready 时返回失败；
+`openprd run --verify` 会再次执行这个质量门禁。Agent 不得在本期必测块缺证据或需关注时宣称就绪。
+如果界面任务已有参考图，视觉就绪还需要 `.openprd/harness/visual-reviews/`
+下存在本次 `openprd visual-compare --reference/--actual` 产物；如果没有参考图但改动界面，
+还需要存在 `openprd visual-compare --before/--after` 修改前后产物。对比图仍有明显差异或漂移时，应回到实现继续调整。
+
+当一个问题已经修复并完成验证后，可以把抽象模式沉淀为项目级经验：
 
 ```bash
 openprd quality /path/to/project --learn --review --from .openprd/harness/turn-state.json
@@ -463,21 +505,17 @@ openprd quality /path/to/project --learn --from <report-id-or-json>
 openprd quality /path/to/project --learn --from ./diagnostics/incident-2026-05-24
 ```
 
-`--learn --review` first writes a pending knowledge candidate under
-`.openprd/knowledge/candidates/` plus a draft skill under
-`.openprd/knowledge/drafts/`. Once the draft is worth keeping, `--learn --from`
-promotes it into incident, pattern, and experience skill artifacts under
-`.openprd/knowledge/` so future tasks can retrieve the lesson instead of
-rediscovering it. `--from` now accepts either a quality report JSON or an
-extracted diagnostics directory / evidence file that already contains
-`diagnostic-report`, `runtime-events`, `timeline`, or `root-cause-candidates`
-artifacts, so a verified fix can be promoted directly into a reusable
-troubleshooting skill.
+`--learn --review` 会先在 `.openprd/knowledge/candidates/` 生成待确认
+knowledge candidate，并在 `.openprd/knowledge/drafts/` 生成 draft skill。
+确认值得长期保留后，再用 `--learn --from` promote 为 `.openprd/knowledge/`
+下的 incident、pattern 和经验 Skill，让后续任务能提前触发同类经验，而不是重新排查一遍。`--from`
+现在既可以接质量报告 JSON，也可以直接接已经导出的诊断目录 / 证据文件；
+只要里面已经有 `diagnostic-report`、`runtime-events`、`timeline`、
+`root-cause-candidates` 这些结构化诊断产物，就能直接沉淀成可复用的排查 Skill。
 
-## Agent Setup
+## Agent 自动接入
 
-OpenPrd can install the project harness into the agent environment so users do not
-need to remember which skill, command, or hook to invoke:
+OpenPrd 会把协同规则装进项目，让用户不需要记住具体 skill、命令或 hook：
 
 ```bash
 openprd setup /path/to/project
@@ -491,76 +529,62 @@ openprd upgrade /path/to/project
 openprd upgrade /path/to/projects --fleet --dry-run
 openprd fleet /path/to/projects --dry-run
 openprd fleet /path/to/projects --sync-registry
-openprd fleet /path/to/projects --backfill-work-units
 openprd run /path/to/project --context
 openprd run /path/to/project --verify
 openprd loop /path/to/project --plan --change <change-id>
 openprd loop /path/to/project --run --agent codex --dry-run
 ```
 
-Installing the CLI alone does not mutate a project or user config. The full
-Codex/Claude/Cursor adapter set is installed when the user runs `openprd init`
-or `openprd setup` inside a project.
-
-`setup` and `init` generate:
-
-- `AGENTS.md` managed OpenPrd rules
-- `.codex/skills/`, `.codex/prompts/`, `.codex/config.toml`, `.codex/hooks.json`, and `.codex/hooks/openprd-hook.mjs`
-- user-level Codex config with `features.codex_hooks = true`
-- `.claude/skills/`, `.claude/commands/openprd/`, and `CLAUDE.md`
-- `.cursor/rules/openprd.mdc` and `.cursor/commands/`
-- `.openprd/harness/install-manifest.json`, `hook-state.json`, `events.jsonl`, `drift-report.json`, and `visual-reviews/`
-
-`doctor` verifies that the generated rules, Codex hooks feature flag, standards,
-and workspace validation are healthy. `update` refreshes the generated adapter
-files from the canonical OpenPrd source while preserving unrelated user hook
-groups.
-
-`self-update` updates the OpenPrd CLI itself from the public npm package.
-`upgrade` composes the two update layers: it first runs `self-update`, then
-re-resolves the installed `openprd` executable and runs either `update <project>`
-or, with `--fleet`, `fleet <root> --update-openprd`. Both commands support
-`--dry-run`; dry-run prints the planned install and refresh commands without
-modifying the CLI, project, registry, or harness state.
-
-The harness is stateful, but hooks are proportional to the chosen profile.
-Default `lite` keeps a lightweight `PreToolUse` write gate for requirement
-intake and limits it to direct editing tools, while `Stop` performs a lightweight
-end-of-turn knowledge review instead of full telemetry. This avoids read-only shell hook
-noise while still nudging the agent to capture reusable project patterns. `guarded` also gates shell tools, while
-`full` restores SessionStart/PreToolUse/PostToolUse/Stop telemetry for temporary
-diagnostics. High-risk actions such as freeze, handoff, accepted spec
-apply/archive, commit, push, release, or publish are gated by
-`openprd run . --verify`, which covers standards, workspace validation, active
-change validation, and active discovery verification.
-
-`openprd run . --context` is the Ralph-style loop surface for agents. It selects
-the next executable unit from active change tasks, discovery coverage, or normal
-OpenPrd workflow state, and records hook turns in `.openprd/harness/iterations.jsonl`.
-
-### Long-Running Agent Loop
-
-For implementation work that should behave like the harness pattern described by
-Anthropic's long-running agent guidance, use `openprd loop`. The loop is stricter
-than `run --context`: it creates a durable feature list, writes a single-task
-prompt, starts a fresh Codex or Claude session for exactly one task, verifies the
-task, and can commit that task before moving on.
-
-For reference-driven UI tasks, the loop prompt and generated guidance require the
-agent to capture an implementation screenshot, run `openprd visual-compare`, and
-review the side-by-side JPG before finishing the task.
-
-`openprd run --context` may surface loop commands as execution commands, but they
-are not automatic instructions. Agents should run `openprd loop --run`,
-`openprd tasks --advance`, `openprd discovery --advance`, or commit commands only
-when the current user message explicitly asks for development, implementation,
-task continuation, deep research/benchmarking, replication, or commit. Read-only
-planning and review turns should stop at the module/file plan.
-
-Loop is recommended from the substantive implementation task count, not from every
-checkbox. When a change has 10 or more pending/total `implementation` tasks,
-`run --context` recommends an isolated worktree or equivalent environment plus a
-single-task Loop session.
+仅安装 CLI 不会直接改写项目或用户配置。用户在项目里运行 `openprd init` 或
+`openprd setup` 时，才会安装完整的 Codex / Claude / Cursor 适配配置。
+
+`setup` 与 `init` 会生成：
+
+- `AGENTS.md` 中的 OpenPrd 管理规则
+- `.codex/skills/`、`.codex/prompts/`、`.codex/config.toml`、`.codex/hooks.json` 和 `.codex/hooks/openprd-hook.mjs`
+- 用户级 Codex config 的 `features.codex_hooks = true`
+- `.claude/skills/`、`.claude/commands/openprd/` 和 `CLAUDE.md`
+- `.cursor/rules/openprd.mdc` 和 `.cursor/commands/`
+- `.openprd/harness/install-manifest.json`、`hook-state.json`、`events.jsonl`、`drift-report.json` 和 `visual-reviews/`
+
+`setup`、`init`、`update` 和 `doctor` 还会维护 `.openprd/harness/install-manifest.json`
+里的 `optionalCapabilities` 建议。它们只用于提示“配上会更好”的能力，不会把
+初始化、诊断或当前任务变成失败。
+
+`doctor` 会检查三端引导、Codex hooks 开关、项目标准化和 OpenPrd 工作区验证是否健康，同时展示像 Context7 / DeepWiki 这类可选增强建议。`update` 会从 OpenPrd 的统一源刷新这些生成文件，并保留用户自己已有的 hook 分组。
+
+`self-update` 只更新 OpenPrd CLI 自身，默认使用公开 npm 包。
+`upgrade` 会编排两层更新：先执行 `self-update`，再重新解析安装后的
+`openprd` 可执行文件，然后执行 `update <project>`；加 `--fleet` 时会执行
+`fleet <root> --update-openprd`，只刷新已有 `.openprd/` 的历史项目。两个入口都支持
+`--dry-run`，预演时只打印安装和刷新命令，不修改 CLI、项目、registry 或 harness 状态。
+
+这套 harness 是有状态的，但 hook 重量由 profile 控制。默认 `lite` 保留轻量
+PreToolUse 写入门禁，并把匹配范围限制在直接编辑工具上，同时在 `Stop` 做一轮轻量项目经验回顾，避免只读 shell 噪声和完整工具级遥测；`guarded` 会额外覆盖 shell 工具，`full` 只建议用于临时深度诊断。`freeze`、`handoff`、accepted spec apply/archive、commit、push、release、publish 等高风险动作会先经过 `openprd run . --verify`，覆盖标准化、工作区校验、激活 change 校验和激活 discovery 校验。
+
+`openprd run . --context` 是类似 Ralph 的循环控制面。它会从激活 change 任务、discovery coverage 或普通 OpenPrd 工作流状态里选择下一项可执行单元，并把 hook turn 记录到 `.openprd/harness/iterations.jsonl`。
+
+### 长程 Agent Loop
+
+如果进入真正的开发落地阶段，建议使用 `openprd loop`。它比 `run --context`
+更严格：先生成稳定的 feature list，再为每个任务写出单独提示词，启动一个新的
+Codex 或 Claude 会话只处理这一个任务。每个任务完成后必须先自测，失败就修复并
+重新自测；前端界面任务在 Codex 客户端优先用 Computer Use，在 Codex CLI 和
+Claude Code 中优先用 Playwright、MCP 浏览器自动化或项目已有 e2e 工具。验证
+通过后，`loop --finish` 会写入阶段性测试报告，并可为该任务生成独立 commit。
+界面任务完成前必须运行 `openprd visual-compare`：已有参考图时截实现图并走
+`--reference/--actual`，没有参考图但改动界面时先留修改前截图、完成后留修改后截图并走
+`--before/--after`，查看左右对比 JPG 后才能完成任务。
+
+`openprd run --context` 可能展示 loop 相关执行命令，但它不是自动执行指令。
+只有当用户当前明确要求开发、实现、继续任务、深度调研、深度对标、复刻落地或
+提交时，Agent 才能运行 `openprd loop --run`、`openprd tasks --advance`、
+`openprd discovery --advance` 或 commit 命令。规划和审查类对话应止步于模块 /
+文件清单和证据说明。
+
+Loop 建议按实质实现任务数触发，而不是按所有 checkbox 触发。当一个 change 的
+`implementation` 任务总数或待处理数达到 10 个时，`run --context` 会建议使用
+独立 worktree 或等价隔离环境，并通过单任务 Loop 会话推进。
 
 ```bash
 openprd loop . --init
@@ -570,78 +594,65 @@ openprd loop . --prompt --agent codex
 openprd loop . --run --agent codex --dry-run
 openprd loop . --run --agent claude --dry-run
 openprd loop . --verify --item T001.01
-openprd loop . --finish --item T001.01 --commit --message "Complete T001.01"
+openprd loop . --finish --item T001.01 --commit --message "新增版本说明入口"
 ```
 
-The loop writes its durable state under `.openprd/harness/`:
-
-- `feature-list.json` is the ordered implementation task list.
-- Each loop task carries a human-readable `taskHandle` such as
-  `change-id:T001.01:task-title`, so another conversation can continue the same
-  task without relying on a chat-specific UUID.
-- `progress.md` is the human-readable progress log.
-- `failed-approaches.md` is the dead-end ledger for mismatches, rejected fixes,
-  and why they failed, so the next session does not retry the same path.
-- `agent-sessions.jsonl` records each prompt/run/finish event, including the
-  task handle and task title for cross-session lookup.
-- `bootstrap.sh` is the startup check each fresh agent session runs.
-- `loop-state.json` stores the current task id, task handle, task title, and
-  the last agent session metadata.
-- `loop-prompts/` stores generated single-task prompts for audit and reuse.
-
-Use `--dry-run` first when you want OpenPrd to prepare the prompt and exact command
-without launching an agent. Use `--agent codex` or `--agent claude` for the default
-CLI integrations. Use `--agent-command "<custom command>"` only when you want to
-pipe the OpenPrd prompt into a project-specific wrapper.
-
-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
-the current root. `--sync-registry` backfills initialized `.openprd/`
-workspaces into `~/.openprd/registry/workspaces.jsonl`. `--update-openprd`
-refreshes projects that already contain `.openprd/` and also backfills
-historical PRD work unit bindings. Project standards or validation gaps are
-reported as health items, but they do not block generated guidance updates. Use
-`--backfill-work-units` when you only want to refresh versioned review artifacts
-and identity bindings, while agent-only or plain projects stay untouched unless
-explicitly selected with `--setup-missing`.
-
-## How to Read `status` and `next`
-
-OpenPrd is not just a command runner. It exposes collaboration state.
+如果项目启用了 `release` 版本轨道，`loop --finish --commit` 会在成功提交后把当前任务的短文案累计到当前项目版本下，并尝试把同名本地 tag（例如 `0.1.23`）移动到最新 commit。若远端已存在同名 tag，OpenPrd 会提示风险并跳过本地 tag 改写，不会静默覆盖远端历史。
 
-### `openprd status`
+Loop 状态会沉淀在 `.openprd/harness/`：
+
+- `feature-list.json`：按依赖排序的执行任务列表
+- `feature-list.json`：每个任务都会带一个人类可读的 `taskHandle`，例如
+  `change-id:T001.01:task-title`，方便跨对话继续同一任务，而不是只靠聊天 UUID
+- `progress.md`：给人看的进度记录
+- `agent-sessions.jsonl`：每次 prompt / run / finish 的结构化事件，也会记录任务句柄和任务标题
+- `bootstrap.sh`：每个新会话启动时执行的检查脚本
+- `loop-state.json`：当前任务 id、任务句柄、任务标题，以及最近一次 Agent 会话状态
+- `loop-prompts/`：生成过的单任务提示词，便于审计和复用
+- `test-reports/`：每个任务的阶段性测试报告，会和任务改动一起提交
+
+建议先用 `--dry-run`，让 OpenPrd 生成提示词和准确执行命令，但不直接启动 Agent。
+`--agent codex` / `--agent claude` 会使用默认 CLI 集成；只有需要接入团队自定义
+包装器时，才使用 `--agent-command "<custom command>"`。
+
+OpenPrd 面向用户的时间统一使用上海时区的 `YYYY-MM-DD HH:mm:ss` 格式，不输出
+`T`、`Z` 或毫秒后缀。除命令、字段名、文件路径、API 名称、品牌名和产品名等必要
+专有术语外，生成文档、进度日志、proposal、prompt、测试报告，以及 Agent 产出的
+`spec.md` 与 tasks 默认使用简体中文。结构字段优先使用“新增需求”“需求”“场景”
+“当”“则”等中文表达，同时继续兼容历史 OpenSpec 英文结构字段。
 
-Use it to understand:
+历史项目不要手写 shell 循环批量改。使用 `fleet` 先扫描报告；它现在会顺带提示全局 registry 里已经登记了多少 OpenPrd 工作区、当前 root 外还有多少已知项目。`--sync-registry` 用来把当前 root 下已初始化的 `.openprd/` 工作区回填到 `~/.openprd/registry/workspaces.jsonl`。`--update-openprd` 只刷新已经有 `.openprd/` 的项目，项目自身 standards 或 validate 缺口会作为“项目健康需关注”报告，但不阻断生成引导更新；只有 agent 配置或普通项目默认保持不变，除非显式用 `--setup-missing` 接管。
 
-- current scenario
-- user participation mode
-- current gate
-- upcoming gate
+## 怎么看 `status` / `next`
 
-Example signals:
+### `openprd status`
+
+重点看：
 
-- `Scenario: Cold start (existing project)`
-- `User participation mode: context-plus-confirmation`
-- `Current gate: clarify-user`
-- `Upcoming gate: architecture diagram review`
+- `Scenario`
+- `User participation mode`
+- `Current gate`
+- `Upcoming gate`
+- `项目版本`（如果已启用 release 版本轨道）
 
 ### `openprd next`
 
-Use it to understand:
+重点看：
 
-- what should happen next
-- why that step is recommended
-- which questions should be asked now
+- `Next action`
+- `Current gate`
+- `Upcoming gate`
+- `Suggested command`
+- `Suggested questions`
 
-## Diagram Contracts
+## 图 Contract
 
-OpenPrd supports:
+OpenPrd 支持：
 
 - `architecture`
 - `product-flow`
 
-You can let the tool infer a draft from the current workspace, or supply an explicit contract:
+也支持从显式 contract 渲染：
 
 ```bash
 openprd diagram /path/to/project \
@@ -649,79 +660,29 @@ openprd diagram /path/to/project \
   --input ./product-flow-contract.json
 ```
 
-The diagram contract is validated against built-in schema files in `.openprd/schema/`.
-
 ## Agent Skills
 
-This repository ships a repo-local `skills/` directory modeled after the `lark-shared + domain skills` pattern used by `larksuite/cli`.
-
-- `skills/openprd-shared/` — shared guardrails and language/review rules
-- `skills/openprd-harness/` — main OpenPrd workflow sequencing
-- `skills/openprd-standards/` — project docs, file manual, and folder README standards
-- `skills/openprd-diagram-review/` — diagram generation and review loop guidance
-- `skills/openprd-discovery-loop/` — sustained OpenPrd coverage discovery
-
-Agents entering this repository should read:
-
-- `AGENTS.md`
-
-## Project Structure
-
-```text
-.
-├── AGENTS.md
-├── bin/
-├── src/
-├── skills/
-├── test/
-├── docs/
-│   └── basic/
-├── openprd/
-│   ├── changes/
-│   ├── specs/
-│   └── archive/
-└── .openprd/
-    ├── schema/
-    ├── templates/
-    ├── engagements/
-    ├── state/
-    └── exports/
-```
-
-Key directories:
-
-- `src/` — CLI logic, PRD core, diagram rendering
-- `docs/basic/` — project-level baseline docs maintained by OpenPrd standards
-- `skills/` — repo-local agent skill system
-- `.openprd/` — shipped workspace seed
-- `test/` — regression coverage for clarify / capture / diagram / gate logic
-
-## Agent Prompt Examples
-
-You can steer agents with prompts like:
-
-```text
-Use $openprd-harness to initialize and advance an OpenPrd workspace for this product idea.
-```
-
-```text
-Use $openprd-diagram-review to generate a product-flow review artifact before freeze.
-```
+仓库内自带：
 
-## Contributing
+- `skills/openprd-shared/`
+- `skills/openprd-harness/`
+- `skills/openprd-standards/`
+- `skills/openprd-diagram-review/`
+- `skills/openprd-discovery-loop/`
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md).
+配合顶层 `AGENTS.md` 使用，可以让 Agent 更稳定地按照 OpenPrd 的协同方式工作。
 
-## Security
+## 贡献与安全
 
-See [SECURITY.md](./SECURITY.md).
+- 贡献说明：见 [CONTRIBUTING.md](./CONTRIBUTING.md)
+- 安全披露：见 [SECURITY.md](./SECURITY.md)
 
-## License
+## 许可证
 
-MIT — see [LICENSE](./LICENSE).
+MIT — 见 [LICENSE](./LICENSE)
 
-## Author
+## 作者
 
 - X: [Mileson07](https://x.com/Mileson07)
-- Xiaohongshu: [超级峰](https://xhslink.com/m/4LnJ9aB1f97)
-- Douyin: [超级峰](https://v.douyin.com/rH645q7trd8/)
+- 小红书: [超级峰](https://xhslink.com/m/4LnJ9aB1f97)
+- 抖音: [超级峰](https://v.douyin.com/rH645q7trd8/)