openprd-harness

OpenPrd Harness

概览

这份 skill 负责主工作流编排。把它当成串起命令和产物的领域 skill；共用守则由 $openprd-shared 提供。

AGENTS.md 只保留轻量合同；入口路由优先看 skills/openprd-router/SKILL.md，具体命令速查看 .openprd/harness/command-catalog.md，更细的工作流步骤、路由边界和 hook 门禁以这份 skill、$openprd-shared 和 $openprd-benchmark-router 为准。

执行时优先继承 $openprd-shared 的用户心智与表达规则：用户懂业务和产品，但不想读技术黑话；默认耐心低、成本敏感，需要 Agent 主动补全遗漏，并用最短路径说明结论和下一步。

Automation-safe mode

识别到 Codex automation、Claude Code headless、cron、scheduled 或 unattended task 时，默认不要要求 openprd dev-check / quality / doctor。按自动化自己的 runbook、日志、测试和通知合同收口；只有 prompt 明确说明这是 OpenPrd 维护任务或显式启用 OpenPrd 时才恢复互动流程。

Agent 自主审查界面

OpenPrd 只通过生成的 AGENTS 与 skills 注入判断原则和质量合同，不提供通用审查 HTML 生成器。Agent 保留当前任务的语义判断、内容组织、页面设计、实现和验证责任。

1. 在任务进入、形成关键证据、完成实现验证，以及准备执行高影响后续动作前，判断聊天是否足以让用户核查依据、比较对象并反馈。
2. 如果存在人类审查节点并命中 references/agent-authored-html-review.md 的任一强制触发条件，除非用户明确不要 HTML，或已有能够完成同等核查、比较与反馈的任务专属审查界面，否则必须在请求用户审查或执行高影响动作前制作并验证任务专属 HTML；不要把“已经有 Markdown/CSV”当成豁免理由。
3. 如果本轮交付包含只有用户或负责人才能完成的选择、批准或纠错，最终交付本身就是人类审查节点。Agent 自己将任务归为“直接分析”、L0/L1/L2 或只读分析不能规避合同；只有用户或宿主明确禁止新增文件时才按无写入豁免处理，并在交付中说明。
4. 未命中强制触发条件，但聊天不足且存在多对象比较、多媒体证据、复杂测试结果、批量审核、方向选择、长期阅读或高影响后续动作时，不要等待用户主动索要 HTML；由 Agent 继续按审查成本决定是否制作。
5. HTML 的生成时机由审查边界决定，不由 L0/L1/L2、固定关键词或“任务是否结束”机械决定。强制触发条件只提供最低可预测边界，不是穷举式关键词分类；一次长任务可以没有 HTML，也可以在分析中、实现后或外部动作前出现不同审查界面。
6. 制作 HTML 前先读取 references/agent-authored-html-review.md，让真实证据、来源、事实/推断/未知边界和本次需要用户判断的内容成为页面主结构；只加入当前审查真正需要的播放、对比、筛选、标注、状态记录或导出能力。
7. 命中强制条件后，最终回复必须给出可点击的任务专属 .html 绝对路径与验证说明；没有这两项、仅生成 starter、仍有无来源占位内容或只验证文件存在时，不得把审查节点标记完成。
8. 不要为了形式生成空洞页面；不要把固定 review.html、质量报告或学习阅读器误当成所有任务的通用替代品；不要用 HTML 代替真机、模拟器、浏览器、生产环境或第三方系统读回。

动手前

1. 读取第一个可用的共用规则文件：skills/openprd-shared/SKILL.md、$HOME/.claude/skills/openprd-shared/SKILL.md 或 $HOME/.codex/skills/openprd-shared/SKILL.md
2. 从 .openprd/ 重建当前工作区状态
3. 如果用户期待自动化 agent 引导，运行 openprd doctor <path>，必要时用 openprd setup <path> 或 openprd update <path> 修复
   • init/setup/update/doctor 可能会在 .openprd/harness/install-manifest.json 的 optionalCapabilities 里记录 Context7、DeepWiki 等非阻断式增强建议。把它当成软提醒：初始化、诊断和当前任务都不因它失败；只有当前任务会明显受益时，才在后续建议里解释能力价值、附官方文档 / GitHub 链接，并视情况提出可代为补配置。
4. Agent 根据当前会话、用户消息和任务相关代码选择执行单元；OpenPrd 不接管上下文
5. 空白前端冷启动且用户目标明确时，先用 3 到 5 行 mini-plan 收口，再按 $openprd-frontend-design 的 design-starter -> Patch Mode 路径继续
   • 执行策略按任务边界判断：L0/小范围修正默认 serial，中等规模 L1/L2 可推荐 parallel-workers，高风险或大规模实现再升级到 parallel-workers-isolated
   • 如果用户给出会话 ID 并要求继续，按工具无关的历史会话精确续接；不要要求或使用工具专属 ID，也不要用当前 active change、相似历史或当前 requirement gate 替代该会话 ID
   • 如果用户没有给 ID，但明确描述了某个已有需求、change、task 或 work unit，按当前会话和 repo-local 材料定位对象，不要先默认拿当前 active change
6. 需求复杂度先交给 $openprd-requirement-intake 分流；不要按固定关键词判断。它会根据影响面、未知数、决策成本和验证成本判断需求类型，并保留内部路由码对照：直接处理=L0、现有功能优化=L1、新功能/新流程方案=L2；默认把路由码并进“需求类型：直接处理（L0）”这类标签里，只有内部排障确实受益时才额外补“内部路由码”
   • 既有 requirement、PRD、review、change、tasks 和实现记录属于冻结历史，不根据当前代码推断、补写或改写。旧功能重新进入需求流程时，为本轮创建新的 current requirement/change 并引用历史；docs/basic/ 与代码说明书是活文档，可随当前实现后台维护。
   • 如果需求涉及界面、页面、视觉、样式或前端体验，判断是否属于“大界面改动”：会改变信息架构、页面布局、主视觉、关键路径或核心组件密度/层级。大界面改动由 Agent 在后台维护视觉方案评审，并选取可逆默认方向继续；用户明确选择时再覆盖默认方向。
   • 如果只是卡片宽度、间距、留白、对齐、颜色、圆角、字号、按钮或图标等轻量 UI 可视优化，仍按 L0/L1 小范围修正推进，不自动升级成大界面方案评审；但它是用户可见变化，动手前要有一句审美意图和记忆点，收口必须补 visual-compare、focus-board、verification-board 或 alignment-board 证据，并检查气质、层级、颜色、字号、间距和表面角色是否成立。只要界面里有同构列表、卡片、网格或表格，就把相同文案类型/相同组件槽位的对齐当作默认验收项，不等用户先投诉。build、package 和 dev-check 不能替代视觉证据。
   • 任何界面、页面、视觉、样式或前端体验任务都要额外读取 $openprd-frontend-design；.openprd/design/active/ 的 facts-sheet / asset-spec / image-preflight / direction-plan / selected-direction 由 Agent 在后台维护，不创建用户确认停顿。
   • 如果用户已经给了效果图、设计稿、参考截图或其他明确参考图，先把它视为主参考源；只有现有 starter、theme、layout 足够接近时才复用，不接近就允许偏离默认组合，不要为了套库把页面做成另一种样式。
   • 如果 design-starter 之后需要整页重写，默认先写 sibling draft，再覆盖回 index.html；不要让入口文件在 rewrite 过程中出现空窗。
   • design-starter 落地后进入 advisory Patch Mode：优先做一轮就地对焦并尽快在入口文件或 sibling draft 形成真实实现；必要的事实、图片或模板读取仍可继续，hook 只记录 allowed-with-patch-mode-attention，不限制当前工具调用。
   • 一旦已经说“开始覆盖入口文件”或“开始整页重写”，把真实页面写入作为近期优先动作；如果尚未写入，最终回复按真实状态标记为 starter 或部分实现，不把提示词当阻断。
   • 如果用户目标是把工作转成可学习、可复用、可回看、可教学或可沉淀的材料，先按期望产物形态判断是否需要 $openprd-learning-review：需要章节结构、证据锚点、图文讲解、检索练习、工作示例或长期阅读体验时，优先用 openprd learn <path> --topic <主题> 生成学习包骨架、阅读器和证据清单；不要用关键词表触发，普通 Markdown 只能作为辅助讲义。
   • 同时记录本阶段是否即将形成用户审查边界；如果聊天不足以承载核查与反馈，按上面的 Agent 自主审查界面合同推进，不要把页面生成推迟到整个任务结束。
7. 如果用户是在规划、分析、架构评审，或问“怎么改”“会动哪些文件”，保持只读并基于证据回答
8. 实现任务完成代码修改后、最终回复前，针对本轮实际 touched code files 运行 openprd dev-check <path> <file...> 或 node scripts/openprd-dev-check.mjs <path> <file...>。它是 task-scoped advisory：只有拆分与当前目标同范围、风险不扩张且能保持行为不变时才可顺手处理；否则保留建议并把工作区规模债归入 workspaceAttention，不得强迫当前任务重构，也不要求用户回复开关确认
9. 执行过程中发现新代码后缀、豁免路径、命令别名、项目约定或用户偏好时，不要中途打断当前任务。工具识别补全和减少重复打扰这类高置信低风险项可自动补齐并记录；用户偏好、项目协作规矩和 OpenPrd 默认行为先沉淀为带来源候选，收工时运行 openprd grow <path> --review 后台复盘，不创建用户确认停顿
10. 维护 OpenPrd 本身时，只要新增或修改配置类能力（阈值、规则、识别、豁免、命令别名、环境差异、用户偏好或策略开关），默认先做 grow-aware 自检：高置信应可成长时直接纳入 openprd grow 体系；不确定时主动询问用户是否做成可成长配置
11. 用户要求生成图片、封面图、配图、海报、插画、图标、贴纸、头像、banner、主视觉/KV、运营图、效果图、视觉稿、mockup 或先看样子时，默认直接调用 imagegen（Codex 原生 Image 2）。生图前写清用途、受众、气质、约束和记忆点并做 anti-slop 自检；只有实际调用后才能汇报结果、失败或限流。结果先当候选效果图，Agent 说明采用的可逆默认方向；用户明确选择时再覆盖默认方向并更新 reference-set
12. 大界面改动由 Agent 按用户目标、信息架构变化、视觉决策成本和验证风险完成视觉方案评审：已有界面时截当前真实界面，冷启动时形成 design brief，再生成至少 3 个不同设计思想方向。候选图展示给用户，同时采用最符合目标且可逆的默认方向继续；OpenPrd 不强制等待确认或阻断大 UI 实现

• 3 个方向不能只是同一种安全解的轻微变化。至少要在 .openprd/design/active/direction-plan.md 里区分不同生成逻辑、适用场景、审美主张、记忆点和主要风险。
• Agent 把可逆默认方向写入 .openprd/design/active/selected-direction.md；用户明确选择时再更新 lens、theme、layout、组件、审美主张和记忆点。

1. 界面、页面、视觉、样式或前端体验任务中，如果已有用户参考图或 Agent 采用的可逆默认参考方向且进入实现阶段，阶段性完成后先截实现图，再运行 openprd visual-compare <path> --reference <效果图> --actual <实现截图> --locale <zh-CN|en>。如果一张参考图里有多个子图、网格或对象，先运行 openprd visual-prepare <path> --reference <效果图> --grid <列>x<行> 或 --boxes <plan.json>，生成 reference-set、contact sheet 和 compare-plan，再逐项对比。如果没有明确参考图，先判断新建界面还是修改既有界面：新建界面由 Agent 在后台完成 3 方向方案评审并采用可逆默认方向，修改既有界面动手前先截修改前截图，完成后用同一入口、视口、账号和数据状态截修改后截图，再运行 openprd visual-compare <path> --before <修改前截图> --after <修改后截图> --locale <zh-CN|en>。需要审局部细节时，再补 openprd visual-compare <path> --board <focus-board.json> --locale <zh-CN|en>；如果局部变化需要放到同一张证据板里审阅，默认优先把局部变化组合成一张 focus-board 再统一验收；并行跑了多个优化方向时，再补 openprd visual-compare <path> --board <parallel-board.json> --locale <zh-CN|en>。如果只是轻量 UI 可视优化，至少留下修改前后自检图、截图实测证据板或对齐辅助线证据板，并检查本轮审美意图和记忆点是否成立；新功能或改动包含同构列表、卡片、网格、表格时，默认补 openprd visual-compare <path> --board <alignment-board.json> --locale <zh-CN|en>，把真实截图、辅助线和相同槽位 spread 放到同一张证据板里；只跑 build、package、dev-check 或只看单张截图，都不能宣称视觉已完成。默认输出 JPG 到 .openprd/harness/visual-reviews/；查看合成图后继续复刻或自检，直到结构、气质、层级、字体/色彩/表面角色和记忆点都没有明显差异或意外漂移；如果用户后续说“跟效果图”“不一致”“好丑”“复刻”，至少先产出一份视觉证据图。对 design-starter -> Patch Mode 的静态首页而言，真正完成还包括：入口文件本体已经改完、主要占位已清掉、已准备好的真实图片或参考约束已经落进页面，不是只补合同或只下载素材。
2. 实现任务新增或修改文件时做文档影响检查：只有本轮代码变化直接让现有 docs/basic/、文件说明书或文件夹 README 失真时才同步相关内容；历史缺失、模板态或全局文档债记入 workspaceAttention，不扩大当前任务。涉及后端、脚本、Agent、工具链、服务或数据处理变更时，同步评估 CLI 与 API 两个接入面

• 如果这轮实现补充了新的前端设计主题、布局骨架、组件 recipe 或 anti-slop 规则，同步更新 .openprd/design/ 与 docs/basic/frontend-guidelines.md，不要只留在代码里。

1. 长时间实现任务使用 openprd loop <path> --plan --change <id>，并且只有当前用户消息明确要求开发、继续任务、深度调研、对标复刻或提交时，才为每个 loop 任务启动一个全新 agent 会话
2. 需要完整工作流细节时，使用 openprd status 和 openprd next
3. 用户要求最佳实践、benchmark、对标、参考产品、prompt engineering、Agent harness、context engineering、图标资源、CLI 或 skill 体系设计时，先路由到 $openprd-benchmark-router
4. 用户要求界面更好看、更稳定、有一致审美、能复用视觉资产或内置模板时，先路由到 $openprd-frontend-design
5. 用户要求基线文档、文件说明书、文件夹 README 标准或实现就绪检查时，路由到 $openprd-standards
6. 用户要求日志、链路追踪、业务成本护栏、免费额度、滥用防护、评估执行环境、冒烟覆盖、性能基线、极端场景、HTML 质量评估报告或项目级经验 Skill 时，路由到 $openprd-quality
7. 用户需要可视化说明，或系统/产品形态仍不清晰时，在进入需求定稿前路由到 $openprd-diagram-review
8. 默认保持 Codex hooks 轻量。除非项目明确需要完整工具级遥测，否则 openprd setup/update 使用 --hook-profile lite；默认 lite 保留 Stop 收工回顾，用于记录 task-scoped 证据与后台维护建议，不制造新的用户确认停顿
9. hook 默认不因 PRD、review、change、tasks、设计合同、测试报告或视觉证据尚未补齐而阻断用户要求的正常实现。缺失材料由 Agent 在后台自动补齐；来不及补齐时继续完成安全范围内的工作，并在收口如实说明证据状态，不把流程作业转嫁给用户。
10. 风险识别只向 Agent 提供提醒和更安全的实现建议，不承担授权审批。命中“兜底、写死、补数据、权益、额度、生产、支付、删除、账号”等词时先看真实动作对象，优先改成配置、迁移、标准状态机、幂等脚本或可回滚发布路径并继续。OpenPrd 不因风险词或动作类型阻断工具调用，也不向用户索取确认、指定句子、摘要、digest、work-unit id 或命令；是否需要确认由当前 Agent 依据宿主安全规则和真实上下文自行判断。
11. 当 doctor 报告生成引导漂移时，读取 .openprd/harness/drift-report.json
12. 先按 .openprd/harness/runtime-environment.json 和 install manifest 的 platformCapabilityPacks 判断当前对话是在 Codex、Claude Code 还是 Cursor，再启用对应能力；Codex Image 2、Computer Use、Codex-owned browser window、对话协同画布和当前线程文本桥接都必须有当前 surface 或 hook/session 证据。当前线程桥接只在 Codex App 明确提供线程发送工具时使用。