better-harness

Better Harness

审查编码 Agent 系统：上下文、执行、控制、反馈 和学习；保持 Sessions、项目和 Agent 资产相互独立。

第 1 步：明确范围并收集证据包

路由：

• <better-harness-fix-output>：基于发现的修复。
• 无回调且开头为 fix、repair 或 \u4fee\u590d：手动直接修复。
• 审查／评估／报告，或混合审查与修复：第 1 步。

解析 Skill 路径、<better-harness-root>（即 ../..）、受支持的 <node>， 以及 <cli>（即 <node> <better-harness-root>/scripts/better-harness.mjs）。如果 缺少任何一项所属信息，则停止；绝不要按搜索顺序选择其他缓存或运行时。

确定绝对目标、决策、验收边界、风险、语言区域（默认使用请求语言）、输出模式、提供方和深度。快速模式使用 3 项和 7 天；普通模式使用 5 项和 30 天。Qoder/Cursor 默认使用持久化 Canvas，其他渲染宿主默认使用 HTML。没有 REPORT_RENDERING 的提供方只能采用内联或无文件模式，且不得创建 HTML、Markdown 或 Canvas 输出。 保持提供方彼此独立。使用当前提供方，除非项目级审查明确授权使用多个受支持的提供方。 Qoder 项目 Memory 标题元数据属于选定工作区基线的一部分。Memory 正文、Codex Memory、Qoder 全局 Memory、用户主目录、原始 Session、已安装的插件、市场以及历史见解的访问都需要明确授权范围。

委派前，为每个获授权的提供方收集一个带版本的证据包：

<cli> harness evidence-bundle --platform <provider> --workspace <target> --cwd <effective-cwd> --language <locale> --depth <quick|normal> --since <window-start> --until <window-end> --format json [--include-memories] [--include-user-home] [--canvas-out <run-dir>/canvas.json]

仅将 --canvas-out 用于 Qoder/Cursor 持久化报告。对于 Qoder，保留默认的项目 Memory 标题扫描；--include-user-home 会扩大扫描范围，将获授权的全局 Memory／配置及其他用户资产纳入其中。对于 Codex， Memory 元数据需要 --include-memories；用户／全局或已安装 Plugin 元数据需要 --include-user-home。如果两种范围都获授权，则同时应用这两个选项。两个选项都不授权访问 Memory 正文。

此操作会冻结拓扑、提供方、时间窗口、深度、限制和授权范围。委派前，读取 bundle.context.topology.target；报告 kind、route 和 packageRoute （memberRoute 或 null）。各提供方必须保持一致。它会返回 sessionEvidence、projectHarness、agentCustomize 和主导包络。 Agent Customize 包含来自同一共享资产快照的有界 lint、inventory 和 integrity 包络。保持各通道／阶段状态及提供方彼此独立。 仅在诊断明确指出的不可用阶段或证据丢失阶段时，才使用单独的 session-analysis facts、 core-change-watch evidence-pack、coding-agent-practices asset-baseline 或 harness analyze 命令；不要用诊断输出替代证据包，也不要重新运行所有所属方。Rules、Skills、MCP、Memory、Agents、Hooks、Commands、Workflows 和 Plugins 的数量仅用于引导检查。数量为零或很高都不会产生发现或评分。若 Qoder 普通报告包含项目 Memories，而完整性阶段不可用，则必须阻止报告；不要用 unobserved 处置替代缺失的审查。

如果提供方发现或用户提供了历史见解来源，主导方只能检查少量获授权的架构／历史说明。 绝不要假定或搜索常规路径；说明不能证明当前行为、已配置的能力或有效性。

第 2 步：运行三轮独立证据审查

并行启动恰好 3 个全新、只读 Agent。在 Codex 中使用 spawn_agent 并设置 fork_turns: "none"；否则在本地独立运行相同的任务说明。任何证据 Agent 都不得委派。

2.1 会话证据

主 Agent 获取 bundle.lanes.sessionEvidence.data 中由提供方标注的事实信封；其生产采集器通过 会话诊断 路由， 且仅使用生产 facts 路由。不要向 Agent 1 传递完整 bundle、 采集引用、调试输出或原始会话。

只向 Agent 1 提供由提供方标注的事实信封、用于发现 Skills 数量为零所需的精简 Step 1 资产计数，以及已解析的范围。要求它阅读会话证据，并在重复流程需求属于范围时有条件地阅读 重复工作流发现。它不得检查 项目、已配置资产、原始会话或其他简报。

2.2 项目运行环境证据

只向 Agent 2 提供目标、范围内的历史记录／当前变更边界、 bundle.lanes.projectHarness.data、决策、风险和负责人限制。要求它阅读 项目运行环境证据。不得向它提供 Session 或 Agent Customize 的结论。

2.3 Agent Customize 证据

只向 Agent 3 提供 bundle.lanes.agentCustomize.data 中由提供方标注的 lint、清单和完整性信封；资产权限；决策；风险； 以及负责人限制。要求它阅读 Agent Customize 证据。它使用 确定性信封，不得重新运行其中的命令，也不得接收 Session／Project 的结论。

每个 Agent 都遵循其参考文档中的自由格式返回约定：通常给出 三到五个候选项，快速模式下最多三个，证据稀少时则更少。专用 Agent 不得分配最终严重性或评分。

它们运行期间，只使用 bundle.lead.data 作为主分析器结果。bundle 会将 --include-user-home 映射到分析器的全局能力边界； 这会保留经过授权的 MCP、Plugin、Skill、Hook 和 Memory 计数，但不会授权读取内容，也不能证明实际使用情况。

如果 bundle 状态为 failed、主分析通道不可用，或其数据缺少 evidence 或 summaryFacts，则停止。在快速模式下，partial bundle 会降低置信度，并且每个不可用的专用 Agent 都必须明确标出；在普通模式下，任何不可用或部分可用的专用通道都会阻止生成报告。此证据收集环节最多委派三个 Agent。

第 3 步：线索核对与重新分级

阅读 Harness Findings Input， 了解字段角色；并阅读 Agent Work Loop，了解五个维度、检查项、证据状态、评分和 Learning Capture 规则。 替换所有示例内容。切勿依据以往报告、Memory、建议文件或验证器推导约定。

执行一次核对。先保留每个专业人员候选项。 只有当目标、观察到的后果、负责人和修复路径都相同时，才合并候选项；即使多个后果属于同一更广泛主题，也要保留彼此独立的后果。对每个缺乏支持或暂缓处理的候选项，都保留一条工作理由。绝不要为了凑够五行、缩短报告、简化评分或匹配三个优先事项而删除符合条件的发现。随后仅由负责人：

• 验证后果、因果链、最小负责人范围、证据边界、置信度和验证者；
• 确定最终严重程度和一项主要 Agent Work Loop 检查项；
• 独立于发现数量，推导保守的维度评分；
• 对存在分歧和无法获取的证据保持低置信度；
• 写入每项有独立依据的发现，并在拟定优先事项、修复提示词或读者文案之前，冻结最终严重程度和维度评分。

起草前，阅读 Findings Quality Gates， 并直接应用其中有关资格、一致性、隐私、资产、候选项升级和修复提示词的检查。对于反复出现的流程或知识需求，还要阅读 Asset Demand Reconciliation。

不要在新报告中编写 summary.suggestions。只有当建议候选项通过与每项发现相同的后果、负责人、证据、输出、验证者和修复提示词检查时，才将其升级为普通的 Low 级发现；否则，在工作核对中将其保留为暂缓项。

冻结发现和维度评分后，根据证据和请求的结果，恰好选择一条支持路径。括号中的范围是用户旅程标签，绝不是评分门槛：

• Bootstrap（0 -> 1）： 明确请求初始指导，或保留的发现表明缺少基础导航、验证或风险处理路径。
• Operationalize（1 -> 60）： 相关机制已经存在，但保留的发现表明这些机制尚未融入日常工作，或尚未通过实际结果得到运用。
• Optimize（60 -> 100）： 充分完整的 Session 证据中，针对重复目标或摩擦点，至少包含两个彼此独立且可比较的 Task Episode。
• Undetermined： 选择支持路径所需的证据不可用。

只阅读所选路径：Bootstrap Support、 Operationalize Support 或 Optimize Support。一条路径最多只能为已有依据的发现拟定三个优先事项、修复提示词和读者文案。不得新增发现、更改严重程度、重新评估维度、添加报告字段，也不得扩大证据和修改权限。

对于持久化报告，只有在三个证据 Agent 完成后，才能起草 findings.json。不要启动第四个审核 Agent。负责人只应用一次质量门槛，保留所有符合条件的发现，并在渲染前修复所有机器验证失败。

报告输出 — 步骤 4：生成授权报告

内联分析不会写入任何内容。线索检查通过后，将草稿视为唯一的最终 findings.json，然后只渲染并验证一次：

Qoder/Cursor: <mode>=<provider>-canvas; <host-root>=<target>/.<provider>/better-harness
Other providers: <mode>=html; <host-root>=<target>/.<provider>/better-harness
<cli> harness render --findings <run-dir>/findings.json --mode <mode> --out <host-root> --run-dir <run-dir> --target <target> --validate --json

Qoder/Cursor 分析负责相邻的 canvas.json；不要将其 summaryFacts 复制到 findings 中。HTML 会原样保留分析器的 summaryFacts。只有在 status: pass 时才算成功，并返回 render 报告中的确切路径。切勿手动编写 Canvas、Markdown 或 HTML。

最后用一句简短的话收尾：<count> 条发现。[打开报告](<renderer-path>)。 链接到 renderer 报告的主报告；切勿返回行内代码路径、单独的目录或输出文件清单。

步骤 5：后续跟进

• 基于发现项的修复使用 Finding-bound Fix；单独的独立修复后 Agent 可以更新已验证的发现项状态和修复进度；循环有效性需等待可比较的后续任务阶段。
• 使用情况或模型问题只需运行一次 session-analysis usage-summary。
• 重复工作通过 循环发现 继续。
• 路由：Agent 自定义、核心变更监控、报告路由、源代码审查。

持久路由仅授权在其宿主根目录中由 renderer 管理的产物。其他创建、激活、修改、清理、调度、外部写入和高风险访问均需任务本地授权。如果所有者或值尚未确定，请说明恢复所需的条件后停止；不要擅自创建替代产物，也不要检查内部验证器。