OpenPrd

简体中文 | English

帮团队和 Agent 把需求说清楚、持续做下去并用证据交付的 AI 原生 PRD 工作区与 CLI。

OpenPrd 是一个轻量但结构化的 PRD harness。你只需要先把问题说出来，它会帮团队和 Agent 把需求整理成：

需求澄清
Agent 后台维护的需求事实与决策记录
图形化评审
非阻断式风险提醒与交付检查
面向执行系统的结构化交接

它把需求、决策和验证结果沉淀成稳定的 HTML 产物，而不是把状态散落在聊天记录或终端输出里。OpenPrd 的职责是帮助 Agent 做事：PRD、review、change、tasks、设计合同与测试证据由 Agent 在后台维护，不再要求用户回复指定内容才能继续。

0.2.2：头像像素合同与任务级设计隔离

头像和单物件 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 和实现记录保持原样，不用今天的代码倒推补写当时的需求；旧功能重新开发时，会创建今天的新需求并关联历史。
工作区维护欠账继续可见，但只作为后台提示；当前任务失败、发布目标、权限、制品、测试和回滚等真实条件仍会严格验证。

npm install -g @openprd/cli@0.2.2

0.1.24：工作区欠账不再冒充当前任务失败

taskReady、workspaceAttention、claimReady、actionReady 分层输出：当前任务、全局维护、整体就绪声明和具体动作条件互不污染。
缺少当前 docs/basic/、代码说明书、文件夹 README 或 EVO 证据时，OpenPrd 会提醒 Agent 后台维护，但不阻断当前实现、change apply、freeze/handoff、commit 或 release；历史 requirement/PRD/review/change/tasks 正文不进入待完善清单。
历史 requirement、PRD、review、change 和 tasks 进入 legacy-frozen：保留原文和索引，不反推、不补写；旧功能重开时创建今天的新需求。
research、Patch Mode、设计合同和内部评审统一为 advisory；只有原始凭证读取、目标冲突等真实安全或动作边界可以拒绝执行。

状态	回答的问题	能否阻断当前工作
`taskReady`	当前任务是否实现并完成最小足够验证	只受当前任务失败影响
`workspaceAttention`	当前基础文档、代码说明书和全仓证据还应维护什么	否
`claimReady`	能否声称整个项目 production-ready	只能限制整体声明
`actionReady`	当前 commit/release/handoff 等动作的精确目标、权限、制品、测试、冲突和回滚是否成立	只受当前动作真实条件影响

0.1.23：彻底移除流程确认残留

0.1.23 在 0.1.22 的非阻断 hook 基础上，继续清除了 requirement、harness 与大界面方向规范中的旧确认文案，并增加生成后三端 skill 回归测试。Agent 会后台维护需求、评审、设计和验证材料；用户要求实现或继续时，不再被 OpenPrd 要求批准摘要、选择默认方向或回复执行口令。

0.1.22：不再把流程材料变成用户门禁

OpenPrd 不再因需求摘要、评审稿、设计合同、测试证据或风险分类缺失而阻断实现。
生产、支付、删除、账号切换、兜底与写死等信号只给 Agent 安全建议，不由 OpenPrd 索取用户确认。
Skill / AGENTS 方案图和大界面候选方向用于帮助理解，不再成为写入或实现授权门槛。
Codex、Claude Code、Cursor 共用同一套“Agent 后台维护、用户任务优先”的规则。

适合什么场景

如果你希望：

在写 PRD 前先澄清需求
区分用户原始表达、项目已有事实和 Agent 推断
在 freeze 前插入架构图 / 流程图评审
让 Agent 遵循 repo 内置的协同规则

那么 OpenPrd 就很适合你。

如果你的同事经常会说“我大概想做这个，但还没完全想清楚”，这通常就是 OpenPrd 最能发挥作用的时候。

一句话需求进来，OpenPrd 怎么接住

你不需要先判断自己提的是 L0 / L1 / L2，也不需要先想清楚技术方案。直接用业务语言说明：谁在什么场景下遇到了什么问题、你想先解决哪一块。OpenPrd 会先帮你整理，再选择合适的推进节奏。

直接处理：问题已经很明确，影响小，验收也清楚。通常直接处理，改完告诉你改了什么、怎么验证。
现有功能优化：目标明确，但会牵动几个页面、状态或用户动作。OpenPrd 会先用人话给你一版 mini-plan，方向对了再继续。
新功能 / 新流程方案：范围更大，角色更多，或者业务风险还不清楚。先把用户场景、第一版、先不做什么和主要风险讲清楚，再进入完整方案和任务拆解。

如果更偏个人用户场景，OpenPrd 会更关注用户在什么时候会用、第一下有没有感受到价值、会不会愿意继续回来；如果更偏团队 / 企业流程，会更关注谁拍板、谁使用、谁要推进上线；如果更偏 Agent 协作，会更关注哪些环节可以自动做、哪里必须人工兜底。整个过程默认先讲结果、场景和风险，不先把内部术语丢给你。

OpenPrd 和 OpenSpec / Superpowers 有什么不一样

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

HTML 优先协作产物

OpenPrd 会生成可以直接分享的 HTML 面板，让产品、研发和 Agent 围绕同一份稳定 artifact 协作，而不是各自回放聊天记录或命令输出。

`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；另一条循环把不同场景下更合适的协作设置沉淀成 动态参数配置，让下次启动时直接带上更合适的默认做法。

场景一：项目级 Skill

当团队在真实工作里反复确认同一种判断，OpenPrd 不会让它继续散落在聊天记录里，而是把它留在项目身边。

例子：一次登录入口改造里，团队确认“登录、注册、找回密码都走官网”。
下次能直接复用什么：相关页面要一起检查、发布前要核对哪些入口和文案、类似需求应该沿着什么路径推进。
为什么有用：下一次类似需求不会再从零开始，新成员接手也能直接照着做。

场景二：动态参数配置

不是每个项目都该用同一套起手方式。OpenPrd 会把不同场景下更合适的协作设置留住，并在下次自动带回来。

例子：一个新项目会先澄清目标和范围，一个接手中的旧项目会先还原现状和改动边界。
下次会自动带上什么：先问什么、先看什么、交付前先收什么材料。
为什么有用：团队不用每次重新解释“这类项目该怎么开场”，而是直接从更合适的默认方式开始。

默认带上的增强能力

OpenPrd 不只是帮你把协作流程说清楚，也会把“该去哪里找资料、先看什么再继续”这件事提前铺好。对公开仓库、第三方技术文档和图标素材，它会默认走更合适的增强路径，而不是等你每次手动提醒。

公开仓库 / 对标参考：优先用 DeepWiki 更快看懂架构、关键流程和实现线索。
第三方库 / CLI / SDK / MCP：优先用 Context7 看最新文档、配置方式、版本差异和迁移说明。
图标与视觉素材：按用途分流到更合适的资源站或实现库，不把 UI 图标、AI 品牌、技术栈图标和 3D 素材混着找。
项目自己的做法优先：先看仓库里已经确认过的经验和约定，再补外部最佳实践，不让通用建议盖过项目语境。

这些增强能力默认是“配上更好”，不是硬依赖。没配置也不会影响初始化或当前任务，只会在后续建议里提醒你补上。

功能

Clarification-first：clarify -> capture -> classify -> interview -> synthesize -> diagram -> freeze -> handoff
场景感知协同：区分空项目冷启动、已有项目首次接入、持续推进中的 workspace
自我成长机制：把真实项目里确认过的做法沉淀成可复用的 项目级 Skill，并按场景沉淀 动态参数配置
来源感知采集：支持 user-confirmed / project-derived / agent-inferred / agent-normalized
最佳实践路由：在公开仓库理解、第三方技术文档、图标资源和协作方式优化这类任务里，先把请求路由到更合适的证据源
项目级 benchmark registry：支持 benchmark add / observe / approve / verify，把被反复采纳的外部来源沉淀成项目自己的长期参考
图形评审工件：支持 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 状态只记录 artifact；“可以开做 / 请实现 / 继续”足以表达执行意图，但不会伪造某份评审稿的用户确认
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 协同约束一起发布

一句话安装

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

Windows 排查

如果全局安装成功后依然提示找不到 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

快速开始

1. 初始化

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 地址，方便后面按当前客户端补配置。

2. 查看当前协同节奏

openprd status /path/to/project
openprd next /path/to/project

如果项目已经启用版本轨道，status 也会直接显示当前项目版本和该版本累计了多少条变化项。

2b. 可选：设置项目版本轨道

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. Agent 后台整理需求

openprd clarify /path/to/project

澄清阶段只在对话里输出提纲或简短清单；正式 HTML 评审统一留给合成后的 review.html。

OpenPrd 会先按用户可见的需求类型接住这句话，而不是先让你填一堆表单：

直接处理：通常直接做，做完告诉你改了什么、怎么验。
现有功能优化：Agent 用 mini-plan 收敛范围并继续执行，显式说明采用的假设。
新功能 / 新流程方案：Agent 在后台整理场景、范围、第一版和风险，并持续维护 review、change 和 tasks，不要求用户批准这些内部材料。

4. 写回答案

单条写回：

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 的确认。

5. 生成草稿与图

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>

6. Freeze 与 handoff

openprd freeze /path/to/project
openprd handoff /path/to/project --target openprd

handoff 导出的 handoff.json 和 handoff.md 会同时带上用户视角的变化摘要 / 版本说明片段，默认按 新增 / 修复 / 优化 / 调整 / 移除 组织，方便直接扫读或复用。若项目已启用 release 版本轨道，handoff 会优先导出当前项目版本下累计的变化条目，并额外写出 项目版本: 0.1.23 这类信息。

7. 启动 OpenPrd 发现模式

用户可以直接用自然语言说：

用 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.md
docs/basic/app-flow.md
docs/basic/prd.md
docs/basic/frontend-guidelines.md
docs/basic/backend-structure.md
docs/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 也只在结构优化与当前目标同范围时建议顺手处理，不会让规模债变成任务失败或要求用户回复开关口令。

生图路由：自动选对免费生图工具

图片、封面图、效果图、图标等生图请求按三层路由自动选工具，不需要用户指定：

工具面判定：Codex 环境用原生 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：

标注即指令：画布检测到选区里同时有原图和你的手绘标注时，会把这次交接标记为标注改图请求，把标注截图和结构化元数据（原图 ID、标注 ID）一起交给 Agent，Agent 把标注当作修改指令生成新图。
旁位回填，不覆盖原图：Agent 通过 POST /api/insert-image 用原图作 anchor 把新图放到旁边（右/左/上/下可选），你可以左右对比原图和新版，再继续在新图上标注，形成多轮迭代闭环。
结构化读画布：Agent 通过 GET /api/selection 读到你正在圈选哪些元素的 ID、坐标、尺寸和文本，不再只靠截图猜。
尺寸契约：AI 生图占位卡的宽高和比例会作为 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。

Agent 自动接入

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.mjs
用户级 Codex config 的 features.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。

长程 Agent Loop

如果进入真正的开发落地阶段，建议使用 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，方便跨对话继续同一任务，而不是只靠聊天 UUID
progress.md：给人看的进度记录
agent-sessions.jsonl：每次 prompt / run / finish 的结构化事件，也会记录任务句柄、任务标题、worktree 路径、分支和 commit sha
bootstrap.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` / `next`

`openprd status`

重点看：

Scenario
User participation mode
Current stage
Upcoming stage
Action ready / Workspace attention
项目版本（如果已启用 release 版本轨道）

`openprd next`

重点看：

Next action
Current stage
Upcoming stage
Suggested command
Suggested questions

Current stage / Upcoming stage 只表示当前建议和后续参考。Workspace attention 只表示 Agent 可以在后台继续完善的材料；只要 Action ready=true，就不得因这些材料缺口阻断用户当下要求的动作。

图 Contract

OpenPrd 支持：

architecture
product-flow

也支持从显式 contract 渲染：

openprd diagram /path/to/project \
  --type product-flow \
  --input ./product-flow-contract.json

Agent Skills

仓库内自带：

skills/openprd-shared/
skills/openprd-harness/
skills/openprd-standards/
skills/openprd-diagram-review/
skills/openprd-discovery-loop/

配合顶层 AGENTS.md 使用，可以让 Agent 更稳定地按照 OpenPrd 的协同方式工作。

贡献与安全

贡献说明：见 CONTRIBUTING.md
安全披露：见 SECURITY.md

许可证

MIT — 见 LICENSE

作者

X: Mileson07
小红书: 超级峰
抖音: 超级峰

Name		Name	Last commit message	Last commit date
Latest commit History 68 Commits
.github		.github
.openprd		.openprd
bin		bin
docs		docs
scripts		scripts
skills		skills
src		src
test		test
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
README_CN.md		README_CN.md
README_EN.md		README_EN.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

OpenPrd

0.2.2：头像像素合同与任务级设计隔离

0.1.24：工作区欠账不再冒充当前任务失败

0.1.23：彻底移除流程确认残留

0.1.22：不再把流程材料变成用户门禁

适合什么场景

一句话需求进来，OpenPrd 怎么接住

OpenPrd 和 OpenSpec / Superpowers 有什么不一样

典型真实场景

HTML 优先协作产物

review.html

学习阅读器

质量回归报告

效果图与截图拼图对比，自动优化

自我成长机制

场景一：项目级 Skill

场景二：动态参数配置

默认带上的增强能力

功能

一句话安装

Windows 排查

快速开始

1. 初始化

2. 查看当前协同节奏

2b. 可选：设置项目版本轨道

3. Agent 后台整理需求

4. 写回答案

5. 生成草稿与图

6. Freeze 与 handoff

7. 启动 OpenPrd 发现模式

项目标准化

生图路由：自动选对免费生图工具

画布协同：标注改图闭环

效果图与截图拼图对比，自动优化

回归测试与质量评估报告

Agent 自动接入

长程 Agent Loop

怎么看 status / next

openprd status

openprd next

图 Contract

Agent Skills

贡献与安全

许可证

作者

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`review.html`

怎么看 `status` / `next`

`openprd status`

`openprd next`