@openprd/cli
Advanced tools
简体中文 | English
帮团队和 Agent 把需求说清楚、持续做下去并用证据交付的 AI 原生 PRD 工作区与 CLI。
OpenPrd 是一个轻量但结构化的 PRD harness。你只需要先把问题说出来，它会帮团队和 Agent 把需求整理成：
它把需求、决策和验证结果沉淀成稳定的 HTML 产物，而不是把状态散落在聊天记录或终端输出里。OpenPrd 的职责是帮助 Agent 做事：PRD、review、change、tasks、设计合同与测试证据由 Agent 在后台维护，不再要求用户回复指定内容才能继续。
npm install -g @openprd/cli@0.2.3
头像和单物件 UI 位图显式区分 transparent-cutout 与 opaque-full-bleed-tile，不再把 UI 容器圆角误画进源图。
参考截图继续优先，但必须结合原始素材或消费组件/CSS 判断像素合同。
.openprd/design/active/ 新增 task scope，旧任务风格不能静默污染当前方向。
Skill、AGENTS、hooks、adapter 生成物与回归测试同步覆盖同一合同。
删除 run --context、--hook-inject、ContextCapsule 和全局 session registry；Agent 直接使用自己的会话上下文。
UserPromptSubmit 只记录提示，不再选择任务或向 Agent 注入下一步建议。
用户已经要求实现、继续或发布时，OpenPrd 不再因为需求、评审、变更、任务、说明书或质量证据尚未补齐而叫停工作。
Codex automation、定时任务和其他无人值守任务只有明确启用 OpenPrd 时才进入维护流程。
历史 requirement、PRD、review、change、tasks 和实现记录保持原样，不用今天的代码倒推补写当时的需求；旧功能重新开发时，会创建今天的新需求并关联历史。
工作区维护欠账继续可见，但只作为后台提示；当前任务失败、发布目标、权限、制品、测试和回滚等真实条件仍会严格验证。
taskReady、workspaceAttention、claimReady、actionReady 分层输出：当前任务、全局维护、整体就绪声明和具体动作条件互不污染。docs/basic/、代码说明书、文件夹 README 或 EVO 证据时，OpenPrd 会提醒 Agent 后台维护，但不阻断当前实现、change apply、freeze/handoff、commit 或 release；历史 requirement/PRD/review/change/tasks 正文不进入待完善清单。legacy-frozen：保留原文和索引，不反推、不补写；旧功能重开时创建今天的新需求。| 状态 | 回答的问题 | 能否阻断当前工作 |
|---|---|---|
taskReady | 当前任务是否实现并完成最小足够验证 | 只受当前任务失败影响 |
workspaceAttention | 当前基础文档、代码说明书和全仓证据还应维护什么 | 否 |
claimReady | 能否声称整个项目 production-ready | 只能限制整体声明 |
actionReady | 当前 commit/release/handoff 等动作的精确目标、权限、制品、测试、冲突和回滚是否成立 | 只受当前动作真实条件影响 |
0.1.23 在 0.1.22 的非阻断 hook 基础上，继续清除了 requirement、harness 与大界面方向规范中的旧确认文案，并增加生成后三端 skill 回归测试。Agent 会后台维护需求、评审、设计和验证材料；用户要求实现或继续时，不再被 OpenPrd 要求批准摘要、选择默认方向或回复执行口令。
如果你希望：
那么 OpenPrd 就很适合你。
如果你的同事经常会说“我大概想做这个，但还没完全想清楚”，这通常就是 OpenPrd 最能发挥作用的时候。
你不需要先判断自己提的是 L0 / L1 / L2，也不需要先想清楚技术方案。直接用业务语言说明：谁在什么场景下遇到了什么问题、你想先解决哪一块。OpenPrd 会先帮你整理，再选择合适的推进节奏。
如果更偏个人用户场景，OpenPrd 会更关注用户在什么时候会用、第一下有没有感受到价值、会不会愿意继续回来；如果更偏团队 / 企业流程，会更关注谁拍板、谁使用、谁要推进上线；如果更偏 Agent 协作，会更关注哪些环节可以自动做、哪里必须人工兜底。整个过程默认先讲结果、场景和风险，不先把内部术语丢给你。
OpenPrd 解决的问题，不只是“把 spec 写出来”，也不只是“把代码跑起来”，而是让 人和 Agent 在需求、评审、执行、交付这些关键节点上始终对齐。
| 工具 | 重心 | 用户主要看到的产物 | 更适合什么 |
|---|---|---|---|
| OpenPrd | 需求澄清、HTML 优先协作、Agent 后台上下文维护 | review.html、学习阅读器、质量报告、图示、结构化 change/task 状态 | 希望用户只说目标、Agent 自动维护上下文并持续推进的团队 |
| OpenSpec | spec / change 生命周期 | Markdown proposal、spec、design、tasks | 更关注 spec 增量治理和变更编排的团队 |
| Superpowers | skill 驱动的编码执行流 | skills、plans、worktree / subagent 流程、代码评审检查点 | 更关注 AI Agent 如何规划、编码、review、收尾的工程团队 |
OpenPrd 最有特色的地方，在于它把“这次到底在做什么、Agent 依据什么继续、最后如何验证” 做成稳定可见的协作面，而不是让用户记住 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 同步 |
OpenPrd 会生成可以直接分享的 HTML 面板，让产品、研发和 Agent 围绕同一份稳定 artifact 协作，而不是各自回放聊天记录或命令输出。
除了下面这些固定流程产物，OpenPrd 还会通过 AGENTS 与 skills 注入一条 Agent 行为规范：当存在人类审查节点，且出现 8 个及以上逐项证据对象、可逆逐项审批、多媒体上下文、用于高影响动作的复杂测试/发布矩阵，或必须导航筛选的长期材料时，除非用户明确不要或已有同等任务专属界面，否则 Agent 必须自行设计、制作并验证当前任务的 HTML 审查页；Markdown/CSV 只作为证据或导出，不能替代。OpenPrd 只提供判断原则和质量合同，不用通用 renderer 代替 Agent 思考；未命中强制边界时仍由 Agent 按审查成本判断，简单结果不会为了形式被强行 HTML 化。
review.html把当前需求版本整理成可评审页面，适合先给产品、研发或负责人确认“这次到底在做什么”。
如果项目已经启用 release 版本轨道，评审页顶部也会直接显示当前 项目版本。
把一次需求、修复或协作方法整理成图文学习资料，方便新成员理解“这套流程为什么这样设计”。
把任务验证、工作区提醒、整体就绪声明和仍需人工判断的点放到一个可读页面里。报告帮助判断和补证据，不替用户决定是否继续当前工作。
把效果图和实现截图放进同一张左右对比图里，适合登录入口改造、条款页本地化、弹窗复刻这类阶段性评审。
视觉证据会跟随当前任务语境选择语言：中文需求默认输出中文标签，英文需求默认输出英文标签；需要固定语言时可显式传入 --locale zh-CN 或 --locale en，证据板里的标题、摘要和检查项也会一起跟随。
openprd visual-compare . --reference ref.png --actual actual.png --locale zh-CN
openprd visual-compare . --board verification-board.json --locale en
OpenPrd 会沿着两条看得见的循环，越用越贴合你们的协作方式。一条循环把真实项目里反复验证过的做法沉淀成可复用的 项目级 Skill；另一条循环把不同场景下更合适的协作设置沉淀成 动态参数配置，让下次启动时直接带上更合适的默认做法。
当团队在真实工作里反复确认同一种判断，OpenPrd 不会让它继续散落在聊天记录里，而是把它留在项目身边。
不是每个项目都该用同一套起手方式。OpenPrd 会把不同场景下更合适的协作设置留住，并在下次自动带回来。
OpenPrd 不只是帮你把协作流程说清楚，也会把“该去哪里找资料、先看什么再继续”这件事提前铺好。对公开仓库、第三方技术文档和图标素材，它会默认走更合适的增强路径，而不是等你每次手动提醒。
DeepWiki 更快看懂架构、关键流程和实现线索。Context7 看最新文档、配置方式、版本差异和迁移说明。这些增强能力默认是“配上更好”，不是硬依赖。没配置也不会影响初始化或当前任务，只会在后续建议里提醒你补上。
clarify -> capture -> classify -> interview -> synthesize -> diagram -> freeze -> handoff项目级 Skill，并按场景沉淀 动态参数配置user-confirmed / project-derived / agent-inferred / agent-normalizedbenchmark add / observe / approve / verify，把被反复采纳的外部来源沉淀成项目自己的长期参考architecture 和 product-flowpending-confirmation / confirmed / needs-revisionloop commit、handoff / 版本说明、review 摘要默认优先使用 新增 / 修复 / 优化 / 调整 / 移除 这类短标签0.1.23 这类项目版本号、版本内变化条目，以及与本地 git tag 的协同，不和内部 PRD v000x 混用docs/basic/、文件说明书模板和文件夹 README 模板npm install -g @openprd/cli
如果你只是想先跑起来，或者 Windows 里刚装完 CLI 但 openprd 还没出现在 PATH，也可以直接用 npx：
npx @openprd/cli@latest --help
npx @openprd/cli@latest init . --template-pack agent
安装后验证：
openprd --help
如果全局安装成功后依然提示找不到 openprd，先检查：
where openprd
npm config get prefix
如果 where openprd 没有结果，把 npm global prefix 加到 PATH 后再重新打开终端。Windows 下这个目录通常是 %AppData%\npm，不是 Unix 常见的 {prefix}/bin。
之后更新 CLI 时先预演，再执行：
openprd self-update --dry-run
openprd self-update
openprd init /path/to/project --template-pack agent
如果 openprd 还没进 PATH，直接把同一条命令前面换成 npx @openprd/cli@latest 即可：
npx @openprd/cli@latest init /path/to/project --template-pack agent
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 做收工回顾。Hook 不选择任务、
不恢复跨项目会话，也不向 Agent 注入任务上下文。
需要让 shell 命令也获得更完整的风险提示时使用 guarded，只有临时深度诊断才使用
full。
如果用户给出报错、日志、复现、根因排查等明确故障证据，并要求直接修复，
hook 会按小型 bugfix 处理，不开启需求入口；“确认修复”这类确认词也会关闭
已打开的需求入口。
init 还会顺手做一层非阻断式可选能力检测，并把结果写进
.openprd/harness/install-manifest.json 的 optionalCapabilities。例如：
Context7：帮助 Agent 获取最新的第三方技术文档、配置、版本差异、迁移路径和高质量实现信息DeepWiki：帮助 Agent 用对话方式理解 GitHub 公开仓库的架构、关键流程和实现线索如果这些能力尚未配置，初始化不会失败；OpenPrd 只会把它记录成后续建议，并附上官方文档、GitHub 地址和 MCP 地址，方便后面按当前客户端补配置。
openprd status /path/to/project
openprd next /path/to/project
如果项目已经启用版本轨道，status 也会直接显示当前项目版本和该版本累计了多少条变化项。
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。
openprd clarify /path/to/project
澄清阶段只在对话里输出提纲或简短清单；正式 HTML 评审统一留给合成后的 review.html。
OpenPrd 会先按用户可见的需求类型接住这句话，而不是先让你填一堆表单：
review、change 和 tasks，不要求用户批准这些内部材料。单条写回：
openprd capture /path/to/project \
--field problem.problemStatement \
--value "移动端缺少高效的 Agent 会话与节点管理入口" \
--source user-confirmed
批量写回：
openprd capture /path/to/project --json-file answers.json
--source agent-normalized 只用于 capture 之后的纯内部措辞整理，
这类没有语义变化的润色不应重开当前 review.html 的确认。
openprd synthesize /path/to/project \
--title "Moticlaw Mobile" \
--owner "Moticlaw" \
--problem "移动端用户缺少直连优先的节点选择与 Agent 会话入口。" \
--why-now "控制面已经具备，当前缺少的是移动端入口。"
openprd review-presentation /path/to/project --template
openprd review-presentation /path/to/project \
--presentation review-presentation.json \
--write \
--fail-on-violation
openprd diagram /path/to/project --type architecture --open
openprd diagram /path/to/project --type product-flow --open
openprd review /path/to/project --open
openprd review /path/to/project --mark confirmed --version <id> --digest <sha256> --work-unit <id>
review.html 是当前 PRD 的稳定评审稿，也是用户随时可以查看的协作结果，但不是
OpenPrd 授权门禁。Agent 自动绑定当前精确的 --version、--digest、--work-unit，
自行记录 review、生成 change、拆解 tasks 并继续用户已经要求的工作；不得反过来要求
用户粘贴 digest、work-unit、完整命令或批准内部材料。信息不完整时，Agent 优先选择
可逆默认方案并说明假设；是否真的需要提问由当前 Agent 根据宿主安全规则与真实上下文判断：
openprd change /path/to/project --generate --change <change-id>
openprd tasks /path/to/project --change <change-id>
openprd freeze /path/to/project
openprd handoff /path/to/project --target openprd
handoff 导出的 handoff.json 和 handoff.md 会同时带上用户视角的变化摘要 / 版本说明片段，默认按 新增 / 修复 / 优化 / 调整 / 移除 组织，方便直接扫读或复用。若项目已启用 release 版本轨道，handoff 会优先导出当前项目版本下累计的变化条目，并额外写出 项目版本: 0.1.23 这类信息。
用户可以直接用自然语言说：
用 OpenPrd 深度补全这个项目。
用 OpenPrd 全面复刻这个参考项目的产品逻辑。
继续深挖这个需求，直到 OpenPrd 覆盖完整。
Discovery 和 loop 执行需要明确的深度或执行意图。用户只是说“看看、规划、 梳理、分析、预计动哪些文件、怎么改”时，Agent 应只读检查状态和代码后回答， 不得推进 coverage，也不得启动 loop 任务。
Agent 会在内部完成路由。底层命令是：
openprd discovery /path/to/project --mode brownfield
openprd discovery /path/to/project --resume
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>
openprd standards /path/to/project --verify
openprd tasks /path/to/project --change <change-id>
openprd tasks /path/to/project --change <change-id> --advance --verify --item T001.01
openprd change /path/to/project --apply --change <change-id>
openprd change /path/to/project --archive --change <change-id>
openprd specs /path/to/project
openprd changes /path/to/project
持续发现的校验也会检查当前 OpenPrd change 结构、spec delta、docs/basic/
标准化文档和长程任务文件。保留 tasks.md 作为第一个入口，每个任务文件最多放
25 个实质 checkbox 任务；超过后继续使用 tasks-002.md、tasks-003.md。
每个非最终任务文件的最后一个 checkbox 应指向下一个任务文件，方便 Agent 按顺序
继续。项目也可以通过 .openprd/discovery/config.json 的
taskSharding.maxItemsPerFile 使用更细的本地限制。
这里的 25 只是分片上限，不是拆解目标。任务标题应优先描述可直接落地的实现单元、 接线边界、页面入口、集成闭环和回归项，而不是把“主流程 / 功能需求 / 验收目标 / 非功能需求”这些 PRD 小节逐条平移成 checkbox。
如果任务需要稳定编号来支撑长程执行，只保留最小元数据：
- [ ] T009.07 Port legacy database import preview
- type: implementation
- deps: T001.14, T007.06
- done: preview shows counts, conflicts, skipped items, warnings
- verify: npm run test -- migration
- test-layer: unit, integration
- test-size: medium
- test-scope: cli-contract
- evidence-plan: 单元测试覆盖导入解析，命令行契约输出留下证据
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 报告。
任务也可以包含测试策略元数据。test-layer、test-size、test-scope
和 evidence-plan 用来帮助 OpenPrd 按风险选择最小足够证据：局部逻辑优先单元测试，
触达 CLI/API/Agent 契约或跨模块状态时使用集成/契约验证，触达用户主路径、视觉、小程序、
性能、安全或成本风险时升级到端到端或专项验证。这些字段是证据分流，不是固定 70/20/10
比例门禁。
tasks 默认列出下一个依赖已满足的任务。--advance 会勾选完成任务；
同时传 --verify 时，会先运行该任务的 verify 命令，通过后再勾选。执行记录
写在任务文件外，避免把 tasks.md 元数据变复杂。
openprd init 会创建项目标准化契约：
docs/basic/file-structure.mddocs/basic/app-flow.mddocs/basic/prd.mddocs/basic/frontend-guidelines.mddocs/basic/backend-structure.mddocs/basic/tech-stack.md.openprd/standards/file-manual-template.md.openprd/standards/folder-readme-template.md当项目已经存在源码文件时，运行 openprd standards --verify 会以非阻断报告展示以下标准化缺口：
docs/basic/ 仍停留在“待补充”等模板占位内容。[项目名]_[文件夹名]_README.md 文件夹说明书。检查命令：
openprd standards /path/to/project --verify
默认命令返回成功，避免文档债截停当前任务；需要在独立治理作业里严格检查时，显式追加 --fail-on-violation。
OpenPrd 生成的 change 会包含标准化维护任务。项目基础文档的唯一标准路径是 docs/basic/。
这些全仓缺口在普通 doctor、change apply、freeze/handoff 和当前任务验证中只作为 workspaceAttention，不会让 taskReady 或 actionReady 变成失败。
实现阶段的标准化维护是明确的影响判定。每次新增或修改源码文件时，Agent 检查
docs/basic/、文件说明书、所在文件夹 README 是否因本次变更过期，并在后台同步
能由当前源码验证的内容。与本任务无关的历史缺口留在工作区提醒中，不为了过门禁而
反推旧需求、旧验收或旧实现理由。
openprd dev-check 同样只检查本轮 touched files 并给出结构建议。默认不会要求超行
文件在当前任务里先重构；显式开启 --auto-refactor on 也只在结构优化与当前目标同范围
时建议顺手处理，不会让规模债变成任务失败或要求用户回复开关口令。
图片、封面图、效果图、图标等生图请求按三层路由自动选工具，不需要用户指定：
imagegen（Image 2），Cursor 环境用内置
GenerateImage——两者都是对话工具内的免费能力，优先直接使用。.openprd/harness/image-generation-preference.json 里用户已确认的偏好，
有就直接用，不再重复询问。user-confirmed 来源
写回该文件，作为下次默认。成本护栏：任何情况下都不允许在用户未明确指定时，擅自调用用户本地或自有的
付费生图 API（例如 OpenAI / Stability key）。路由协议由 install manifest 和
.openprd/harness/runtime-environment.json 的 imageGenerationRouting 字段承载。
openprd canvas . 打开与当前对话绑定的本地 Excalidraw 画布后，AI 生成的图会
直接落到画布上，你可以在图上直接画圈、写字做标注，然后点击“发送给 Codex”，
剩下的交给 Agent：
POST /api/insert-image 用原图作 anchor
把新图放到旁边（右/左/上/下可选），你可以左右对比原图和新版，再继续在新图
上标注，形成多轮迭代闭环。GET /api/selection 读到你正在圈选哪些元素的
ID、坐标、尺寸和文本，不再只靠截图猜。sizeContract 写进生图提示，
生成的图片按占位卡比例出图，回填不变形。唤起方式：在对话里自然地说“打开画布一起看”“我在画布上标注了，按标注改图”
这类话，Agent 会按当前会话判断画布协同意图；也可以直接运行 openprd canvas . --daemon --open。
当界面任务已经有效果图、设计稿、用户给图或 Agent 自己生成的 mock 时，Agent 在阶段性完成后应先截实现图，再生成左右对比图，不能只靠主观印象判断是否一致：
openprd visual-compare /path/to/project \
--reference effect-image.png \
--actual implementation-screenshot.jpg
默认会在 .openprd/harness/visual-reviews/ 下输出体积较小的 JPG。左侧标注
效果图，右侧标注 实现截图。输入可以是 sharp 支持的常见图片格式。
如果只调整按钮、hover、提示框、间距、圆角、字号或颜色等局部 UI，不要用全屏图作为主裁决。直接指定左右有效区域：
openprd visual-compare /path/to/project \
--reference effect-image.png \
--actual implementation-screenshot.jpg \
--reference-box 0,0,516,130 \
--actual-box 1840,238,516,130 \
--presentation local-first
local-first 使用同一像素尺度裁剪两侧，较小区域不会被单独拉伸成同宽。输出先展示局部参考、局部实现和差异图，全屏缩略图只放在底部检查未改区域漂移。修改前后模式使用 --before-box 和 --after-box。坐标默认是像素，也支持 ratio: 或 percent: 前缀。
如果界面任务没有明确效果图，Agent 应先截修改前截图，完成改动后用同一入口、 视口、账号和数据状态再截修改后截图：
openprd visual-compare /path/to/project \
--before before-screenshot.png \
--after after-screenshot.jpg
修改前后模式会把左侧标注为 修改前、右侧标注为 修改后，帮助 Agent 检查
预期变化是否出现，以及未改区域是否有布局、颜色、密度或状态漂移。输出也可以按需要调整：
openprd visual-compare /path/to/project \
--reference effect-image.png \
--actual implementation-screenshot.jpg \
--out review.webp \
--format webp \
--quality 82 \
--max-panel-width 1180
Agent 必须查看生成图并继续对标，直到没有明显视觉差异。最终回复里应给出本次 生成的对比图路径，并说明对比后是否仍有差异。
如果新功能或改动包含同构列表、卡片、网格或表格，或者用户反馈“没对齐”“排版 漂移”，Agent 还要把真实截图、辅助线、容器轨道量测和内部内容槽位量测放到一张对齐证据板里：
openprd visual-compare /path/to/project \
--board alignment-board.json
alignment-board.json 使用 mode: "alignment-board"，记录截图、辅助线、
容器分组和内容槽位分组。容器轨道包括卡片外框、列宽、行顶、间距等；
内容槽位包括标题、副标题、标签、描述、状态、价格、按钮、图标和操作区等
相同文案类型/相同组件槽位的 x/y/宽高/baseline spread。列表卡片、卡片网格和
表格这类重复结构属于默认触发场景，不需要等用户先指出“没有对齐”；只量外框、
列宽或行顶不算完整对齐验收。
网格、基线和对齐辅助线只用于这条布局校验路径。普通 before/after、reference/actual 与 verification-board 不会自动叠加网格；它们默认使用紧凑的暖色结果画布，让截图和结论占据主要空间。
如果要判断单个 logo、icon、avatar、badge、按钮图形或图片裁切内部是否居中， 或者用户反馈“偏心”“视觉重心不对”，Agent 应先裁出目标元素，再生成内部居中证据板：
openprd visual-compare /path/to/project \
--board centering-board.json
最小语法如下：
{
"mode": "centering-board",
"title": "Logo 内部居中检查",
"image": ".openprd/harness/screenshots/logo.png",
"thresholdPx": 8,
"subject": {
"mode": "auto",
"weight": "contrast"
}
}
如果自动 mask 把背景、阴影或透明边缘算进主体，可以显式指定颜色范围：
{
"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 同时会创建质量契约：
.openprd/quality/config.json.openprd/quality/reports/.openprd/knowledge/检查命令：
openprd quality /path/to/project --verify
该命令会在 .openprd/quality/reports/ 下同时写入 JSON 和 HTML。HTML 回归测试报告
是阶段性质量查看的主要产物，优先展示整体回归结果、逐需求模块结果、测试块通过情况、
分层测试策略矩阵、未通过项和需要确认是否属于本期的遗漏。EVO 是 OpenPrd 内部对
“质量评估/验证层”的简称；用户可见报告不要求理解这个缩写。脚本、依赖或 fixture
存在只代表项目具备能力，不能替代本次运行证据。
当需求涉及免费用户、额度、AI 调用、第三方 API、生成、存储、下载或其他消耗型成本时，
quality --verify 会额外检查是否存在成本来源、用户级限制、负向验证、用量/成本监控、
报警阈值和止损动作，避免免费额度或高成本路径在上线后才暴露。
openprd quality --verify 默认把未 production-ready 的本期必测块留在报告中并返回成功，避免
证据债截停当前任务；独立治理作业可显式追加 --fail-on-violation 获得严格退出码。openprd run --verify 把它放入 claimReady 和
workspaceAttention，不会把已经通过本任务验证的实现改成失败，也不会回滚已产生的 commit。
如果界面任务已有参考图，视觉就绪还需要 .openprd/harness/visual-reviews/
下存在本次 openprd visual-compare --reference/--actual 产物；如果没有参考图但改动界面，
还需要存在 openprd visual-compare --before/--after 修改前后产物。普通截图实测需要截图实测证据板；
同构列表、卡片、网格或表格还需要对齐辅助线证据板，并同时覆盖容器轨道和内部内容槽位；
单个素材、图标、头像、徽标、按钮图形或图片内部居中/视觉重心判断需要内部居中证据板。
对比图仍有明显差异、坐标偏差或漂移时，应回到实现继续调整。
当一个问题已经修复并完成验证后，可以把抽象模式沉淀为项目级经验：
openprd quality /path/to/project --learn --review --from .openprd/harness/turn-state.json
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 会先在 .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。
OpenPrd 会把协同规则装进项目，让用户不需要记住具体 skill、命令或 hook：
openprd setup /path/to/project
openprd doctor /path/to/project
openprd self-update --dry-run
openprd self-update
openprd update /path/to/project
openprd update /path/to/project --hook-profile lite
openprd upgrade /path/to/project --dry-run
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 run /path/to/project --verify
openprd loop /path/to/project --plan --change <change-id>
openprd loop /path/to/project --run --agent codex --dry-run
仅安装 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.mjsfeatures.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 分组。
新版本更新会自动识别旧项目遗留的根目录 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/ 的历史项目，并识别只有旧根目录 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 的分层状态，但只由精确目标、权限、冲突、本次制品/测试和回滚条件决定 actionReady；全局文档和 EVO 债只作提醒。
openprd run . --verify 只负责验证当前工作区和激活 change；它不读取用户消息，不选择 Agent 的下一项任务，也不返回上下文胶囊。Hook turn 仍可通过内部 run --record-hook 记录到 .openprd/harness/iterations.jsonl。
如果进入真正的开发落地阶段，建议使用 openprd loop。它会先生成稳定的 feature list，
再为每个任务写出单独提示词，启动一个新的
Codex 或 Claude 会话只处理这一个任务。每个任务完成后必须先自测，失败就修复并
重新自测；前端界面任务在 Codex 客户端优先用 Computer Use，在 Codex CLI 和
Claude Code 中优先用 Playwright、MCP 浏览器自动化或项目已有 e2e 工具。验证
通过后，loop --finish 会写入阶段性测试报告，并可在隔离 worktree 中为该任务生成独立 commit。
界面任务完成前必须运行 openprd visual-compare：已有参考图时截实现图并走
--reference/--actual，没有参考图但改动界面时先留修改前截图、完成后留修改后截图并走
--before/--after，普通截图实测走 --board <verification-board.json>，同构列表、卡片、网格或表格走
--board <alignment-board.json>，单元素内部居中/视觉重心问题走
--board <centering-board.json>，查看证据图后才能完成任务。
只有当用户当前明确要求开发、实现、继续任务、深度调研、深度对标、复刻落地或
提交时，Agent 才能运行 openprd loop --run、openprd tasks --advance、
openprd discovery --advance 或 commit 命令。规划和审查类对话应止步于模块 /
文件清单和证据说明。
Loop 是否使用独立 worktree 由 Agent 根据实质实现任务数、写入范围和并行冲突判断；OpenPrd 不再通过上下文命令替 Agent 做这个选择。
openprd loop . --init
openprd loop . --plan --change <change-id>
openprd loop . --next
openprd loop . --prompt --agent codex
openprd loop . --run --agent codex --dry-run
openprd loop . --run --agent codex --worktree ../openprd-loop-wt --branch loop/feature-x --dry-run
openprd loop . --run --agent claude --dry-run
openprd loop . --verify --item T001.01
openprd loop . --finish --item T001.01 --worktree ../openprd-loop-wt --branch loop/feature-x --commit --message "新增版本说明入口"
如果项目启用了 release 版本轨道，loop --finish --commit 会在成功提交时把当前任务的短文案累计到当前项目版本下，并尝试把同名本地 tag（例如 0.1.23）移动到最新 commit。若远端已存在同名 tag，OpenPrd 会提示风险并跳过本地 tag 改写，不会静默覆盖远端历史。
主工作区已经有未纳入本任务提交的改动时，loop --finish --commit 默认会阻断，提示你改用 --worktree <path> --branch <name>；只有你明确知道要在主工作区做 scoped commit 时，才显式加 --allow-dirty-main。提交范围也不再是 git add -A，而是按任务 write-scope、任务来源文件和本轮新增 touched files 收窄，避免把无关改动卷进单任务 commit。
Loop 状态会沉淀在 .openprd/harness/：
feature-list.json：按依赖排序的执行任务列表feature-list.json：每个任务都会带一个人类可读的 taskHandle，例如
change-id:T001.01:task-title，方便跨对话继续同一任务，而不是只靠聊天 UUIDprogress.md：给人看的进度记录agent-sessions.jsonl：每次 prompt / run / finish 的结构化事件，也会记录任务句柄、任务标题、worktree 路径、分支和 commit shabootstrap.sh：每个新会话启动时执行的检查脚本loop-state.json：当前任务 id、任务句柄、任务标题、baseline 脏文件，以及最近一次 worktree / 分支 / commit 状态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 默认跟随当前输入和 PRD 快照的主语言：中文语境使用简体中文，
英文语境保持英文，无法判断时回退到简体中文。结构字段继续兼容历史英文
结构字段；明确要求 zh-CN 的图示和合同场景仍会强制使用中文。
历史项目不要手写 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 缺口会作为“项目健康需关注”报告，但不阻断生成引导更新。
历史 requirement、PRD、review、change、tasks 和验收结论统一按 legacy-frozen 处理：迁移与 --backfill-work-units 只补文件身份、digest、版本索引和 work-unit 绑定等可验证元数据，不生成缺失正文，也不猜测当时的实现理由。旧功能重新进入开发时，Agent 以今天的目标和验收条件建立新 requirement/change，旧材料只作为 context。当前源码能够验证的代码说明书、文件夹 README 和 docs/basic/ 当前态仍可后台维护。
status / nextopenprd status重点看：
ScenarioUser participation modeCurrent stageUpcoming stageAction ready / Workspace attention项目版本（如果已启用 release 版本轨道）openprd next重点看：
Next actionCurrent stageUpcoming stageSuggested commandSuggested questionsCurrent stage / Upcoming stage 只表示当前建议和后续参考。Workspace attention 只表示 Agent 可以在后台继续完善的材料；只要 Action ready=true，就不得因这些材料缺口阻断用户当下要求的动作。
OpenPrd 支持：
architectureproduct-flow也支持从显式 contract 渲染：
openprd diagram /path/to/project \
--type product-flow \
--input ./product-flow-contract.json
仓库内自带：
skills/openprd-shared/skills/openprd-harness/skills/openprd-standards/skills/openprd-diagram-review/skills/openprd-discovery-loop/配合顶层 AGENTS.md 使用，可以让 Agent 更稳定地按照 OpenPrd 的协同方式工作。
MIT — 见 LICENSE
FAQs
AI-native PRD workspace and lifecycle CLI
The npm package @openprd/cli receives a total of 7 weekly downloads. As such, @openprd/cli popularity was classified as not popular.
We found that @openprd/cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Company News
Socket is joining the OpenJS Security Stewardship Program to fund Node.js vulnerability research, maintainer remediation, and security releases.
Security News
Two compromised GitHub Actions were re-enabled with malicious tags intact, exposing thousands of downstream repositories to Mini Shai-Hulud.
Research
/Security News
A malicious Firefox extension fetches its payload after installation to evade detection, steal Google session cookies, and automate account takeover.