# 工程路线与验收标准

[English](ENGINEERING_ROADMAP.md) · [首页](../README.zh-CN.md) · [实现记录](P0_P1_DELIVERY.md)

更新于 2026-09-22。本文区分已实现能力、验证范围和待交付工作；路线不代表已完成。

[Agent 执行审查](AGENT_RUNTIME_REVIEW.md)新增可选短调用监督器：只有显式请求时计划才返回 handoff argv，
任务回执可重复查询，完成时独立验收。真实子进程故障对照与不同 `ckrao` 调用已验证
交接机制；前两次安装态 micrograd 的超时仍保留为失败，后续审查验证在相同的 30 秒
目标时限内通过了原始测试和独立验收。
这些结果不改写历史 AUTO 失败，也不是模型 A/B 结论。2026-09-22 的 fresh-client
自然语言 AUTO 已在当前技能上端到端通过，因此后续 A/B 不再被客户端验收门槛阻塞。

## 产品范围

RigorPilot 把研究仓库 README 中的运行目标转化为有界执行和可审计证据。
适用于小型推理/评测、复现前检查、保守训练启动核验和故障分析。
可信执行是默认路径；源码探索需要明确授权。它不替代研究者判断，
也不以自由修改算法或扩大计算预算来换取成功状态。

## 当前工程能力

| 能力 | 已有实现 | 验证边界 |
|---|---|---|
| 安装 | 主技能自包含；全量安装共用 bundled 运行时和参考文件 | 测试安装后目录、公开 CLI 和真实短命令；不等于实时验证第三方安装服务 |
| 可审核计划 | `--plan-only` 暴露 README-backed `cmd-XX` 候选与选择 fingerprint；显式执行把 command ID 绑定到已审核候选集合 | setup/download 命令不进入候选；候选集合变化会在目标执行前阻塞；不等于沙箱或命令真实性证明 |
| 执行 | 真实子进程、超时/取消、事件和日志；明确实际解释器路径 | 本机运行，不是 OS 沙箱；资源采样/准入不是硬配额 |
| 恢复 | 任务检查点、已完成命令复用、不确定派发阻塞 | 不自动重复未知结果的请求；不能恢复模型训练内部 checkpoint |
| 完成判定 | 命令验收与源码完整性分开；稳定机器可读错误码；可选产物大小/哈希与 JSON 指标容差检查，最终重新验收 | 未配置结构化检查时仍只检查退出码/输出字串；不证明产物新生成或论文指标复现 |
| README | 原始字节分块插入；普通入口可选源旁副本，原文和媒体上下文不改 | 同名冲突不覆盖；复制目录后需重新生成证据链接；不承诺浏览器可访问所有外部媒体 |
| 模型 / 客户端 | Codex 真实客户端现已有显式 named-skill Fast Path 与 fresh-client 自然语言 AUTO 两条完整通过记录；两次更早的 AUTO 失败继续保留 | 成功 AUTO 使用同步 orchestrator 且没有等长外层 timeout；该 turn 未选择可选 handoff。尚无 A/B 效果估计；Anthropic 独立 transport 仍是另一条路径 |
| 外部证据 | 固定 commit 的四项历史协议，加同一批固定仓库最新 4/4 plan-only reviewed-selection 验证 | 新结果只证明目标计划；历史用例包括选择阶段和部分训练，不证明四篇论文复现或未知仓库成功率 |
| 完整性性能 | 可重复的合成 tracked-file 基准；当前 Windows 记录覆盖 1k/10k 文件 snapshot/verify | 小型合成文件、单机与 Python 分配测量，不是延迟 SLA；只有更简单的替代方案在同一基准明确更优且不削弱检测时才调整 snapshot 策略 |
| 小型对照准备 | 三个冻结任务、六个 A/B 试验槽位、独立评分器与真实本地校准 | 六个模型试验均未运行；本工具还没有通用真实模型执行器或强制模型预算 |
| 中立试验内核 | 受限工具、独立评分、持久化预留与有界 Messages A/B 命令行入口 | 已验证本地 HTTP 集成；真实服务成功验收、批次计费硬上限、随包脚本执行及 OS 隔离仍未完成 |
| 功能验收 | 安装目录中的真实运行时，正负例精确验收、独立预测/日志与 README 检查；可选固定 micrograd | [四项实测](SKILL_ACCEPTANCE.zh-CN.md)；准备步骤预设、复用依赖，不证明模型增益或冷安装 |

## 验收层次

1. **结构与回归**：`python scripts/run_all_tests.py`。包括完整/单技能/目录安装、
   异常模型响应、恢复、原文完整性和真实虚拟环境内的目标命令。
2. **离线验证示例**：`python scripts/run_harness_lab.py`。固定模拟决策驱动真实
   失败、准备、暂停和跨进程恢复；不代表模型能力，无 API/GPU/下载。
3. **真实仓库协议**：[固定版本用例](../benchmarks/README.md)。明确选择阶段、
   执行成功、部分完成与指标匹配，不能把它们合并成论文复现率。
   reviewed-selection 套件还会在四个固定仓库分别检查 `cmd-XX`、fingerprint 绑定与 plan-only 无副作用。
4. **可选独立执行器验收**：只在服务可用、预算已确认时运行一个
   [micrograd canary](../benchmarks/run_agent_canary.py)。保留实际模型/工具轨迹、
   用量、独立判定和源码哈希后，才进入更大的矩阵。

## 交付优先级

| 优先级 | 交付项 | 完成门槛 |
|---|---|---|
| P0：持续维护 | 安装、跨平台执行、证据发布、问题反馈与安全说明 | 安装后的文件可用；三平台 CI 通过；错误不被包装成成功 |
| P1：已实现、持续回归 | 可审核 README 命令选择 | 执行前暴露候选 ID 与 fingerprint；旧计划、未知 ID、setup/download 目标和未经审核的 shell 语法全部 fail closed |
| P1：默认技能首次使用 | 新目录安装后，在一个固定版本公开仓库完成最小任务 | 实际执行日志、原文件/媒体完整性、可浏览的批注和独立检查；明确安装、显式调用与客户端自动加载分别验证了什么 |
| P1：可选独立执行器 | 一例真实模型执行；无人工替写轨迹 | 模型回复、工具调用、用量和验收结果齐全；服务失败如实保留并停止；不作为默认技能路线的前置条件 |
| P1：普通输出可浏览（已实现，持续回归） | 两个主入口支持 `--source-adjacent-readme` | 嵌套 README、相对图像和证据链接有效；不改原文、不覆盖无关文件；重复运行检查归属 |
| P2：效果评测 | 冻结任务、独立评分器、同条件基线 | 区分业务完成、误报、错误阻塞、成本、干预和证据完整性 |
| P2：执行隔离 | 可选隔离执行后端、网络/文件边界及资源限制 | 威胁模型明确；越界和超限测试通过；未配置时不声称有沙箱 |
| P3：维护与升级 | 模型回归、版本发布、兼容说明、失败分类 | 新版本有回归结果与变更说明，历史证据仍可核查 |

不优先扩展大规模训练、任意源码修补、多代理编排或长期记忆设施。
新增机制应针对已复现的问题，并能通过验收证明必要性。

## 当前交付计划

本轮已完成安装后显式技能试用、报告修正和独立检查；见
[micrograd 真实验收记录](FIRST_USE_ACCEPTANCE.zh-CN.md)。默认编排器现已形成
可审核的 `plan -> command-id/fingerprint -> run -> verify` 路径、稳定错误码，
并在四个固定真实仓库完成最新 4/4 planning 验证。2026-09-20 的
[真实客户端复验](REAL_CLIENT_ACCEPTANCE.zh-CN.md)已让显式 named-skill Fast Path
完整通过，也多次直接观察到 fresh-client 自动加载。2026-09-20 AUTO 因把用户允许的
30 秒缩成 20 秒失败；2026-09-21 AUTO 已保留 30 秒，却给整个 orchestrator 套了等长
30 秒外层 timeout，导致 runtime 未进入终态且没有 `status.json`，随后外层客户端 240 秒超时。
2026-09-22 AUTO 保留这两次失败并端到端通过；模型对照仍未运行。

源码完整性基准在当前 Windows 主机记录：1k 个 128-byte tracked 文件 snapshot/verify
约 `0.705 s / 0.670 s`，10k 个约 `6.054 s / 5.897 s`。当前继续保留直接全内容 hash；
只有更简单的 Git tree/index 方案在同一基准取得明确收益且不削弱 dirty-source 检测时再优化。

[中立控制内核](CONTROLLED_TRIALS.zh-CN.md) 已完成工具与预算边界的离线验证，
没有新增模型调用。其技能文件只读，未来使用它须新建受限工具协议，不能把原来的
完整技能包对照计划悄悄换名。真实试验仍需明确模型与预算、审计传输、批次总账及执行隔离。

按下列门槛推进，不以“文件已经生成”代替任务完成：

| 顺序 | 实施范围 | 验收与停止条件 |
|---|---|---|
| 1 | 固定真实仓库 reviewed planning | `--plan-only` 选择预期 README 目标、暴露 review token 且不写证据；当前四项 4/4 |
| 2 | 显式 named-skill 真实客户端 canary | **2026-09-20 已通过**：任务/运行成功、独立 grader、源码完整性、证据验证与 `turn.completed` 同时满足 |
| 3 | fresh-client 自然语言自动加载 canary | **2026-09-22 已通过**，并永久保留前两次失败：自动加载、审核目标执行、任务/runtime、源码完整性、独立 grader、证据验证与 `turn.completed` 同时通过 |
| 4 | 独立验收与发布证据 | 核查真实日志、原文件 SHA-256、逐节批注还原及本地证据链接；全量回归和 Git 发布检查通过后同步 |
| 5 | 小型对照试验（准备与校准已交付，模型试验待验收） | AUTO gate 已解除；使用[冻结任务与真实评分器校准](PAIRED_PILOT.zh-CN.md)，固定模型/预算/provider 条件，不能把客户端验收通过本身解释为模型增益 |

首次使用有三个不同门槛：安装器把文件放对位置、代理按明确技能名称/路径执行、
新客户端按自然语言任务自动选中技能。前两项不能替代第三项的会话加载证据。
独立子代理会消耗当前宿主模型资源；即使没有额外 API 调用，用量未知也不能记为零。
新客户端会话或独立执行器需要另行确认模型和预算。
可选的只读 [Codex 额度查询](SKILL_ACCEPTANCE.zh-CN.md#可选codex-额度快照)可取得服务返回的用量窗口，
但尚未接入执行器预算控制，也不能保证运行中的请求结束后仍高于指定百分比。

## 长期评测协议（离线基础已交付，模型试验待实现）

[小型评测工具](PAIRED_PILOT.zh-CN.md) 已实现任务、输入和评测实现冻结、新目录、
独立评分器与追加式本地校准。三个真实命令校准不计入六个尚未运行的模型试验。
模型配置只是预检，不代表执行或费用限制生效。下一道验收依次为：隔离客户端、
可计量的用量/时间停止门槛、单个真实试跑、完整保留所有尝试的配对评测。

先用 3 个任务、2 个条件（共 6 次尝试）检查评分器：正常执行、缺少必需资产、
退出码为零但结果不符合要求。缺资源任务应准确定位并采取已授权的安全下一步，
不能通过一律拒绝取得好成绩。注入故障明确标记，单次结果不用于估算泛化成功率。
默认技能路线可先比较 A/B；可选执行器成功验收后再纳入 C。
确认试验有信息价值后，用 6 个任务、3 个条件继续审查，再扩展为 12 个冻结任务、
4–6 个仓库，关键任务重复 3 次。开发集与保留集分开；现有公开案例属于
开发/回归材料，不能冒充未知任务。

A：同模型与通用任务提示；B：A 加技能包及其随包脚本（端到端包比较，非单纯提示词消融）；
C：B 加持久化执行、恢复和证据机制。
固定模型版本、工具权限、审核命令、预算、源代码、环境和评分器。所有组保留
原始轨迹，不能因基线没有漂亮报告就判业务失败。权限或工具不同的比较必须
标为端到端产品对照，不解释为单一机制的收益。预审命令也不证明自主发现目标能力。

任务覆盖正常执行、缺资源准备重试、退出码成功但结果错误、控制器中断、
提前宣告成功、需要未授权的大额下载。真实任务与注入故障分开标记。
评分器应检查实际产物、指标容差和实验条件，并与执行中的 Agent 隔离。

记录 task/split、repo commit、harness/prompt/grader hash、模型请求名/返回名、
参数、依赖与缓存条件、重复编号、人工干预、自报结果、独立判定、轨迹、用量和耗时。
费用未知须标未知；包含失败尝试的成本。provider 故障单列，但不从用户成功率
的分母中删除。同时报告安全阻塞和错误阻塞，防止靠全部拒绝取得虚假的好结果。
小样本先报告逐例结果和不确定性，不作泛化承诺。
参考 [Agent 评测方法](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)。

## 模型与运行时升级

协议/用量契约测试 → 一个真实 canary → 同条件保留集对照 → 发布。
一次只改变模型、提示词或工具中的一个因素；保留旧结果。模型进步后，
通过消融实验决定是否删除旧补救规则，而不是永久积累约束。
借鉴 [长任务 Harness 实践](https://www.anthropic.com/engineering/harness-design-long-running-apps)
中的验收契约与独立检查，以及 [持久化设计](https://docs.langchain.com/oss/python/langgraph/persistence)
对任务检查点和跨任务记忆的区分，不直接复制其架构规模。

## 运行与维护边界

优先单例、串行、有预算的验证。token/时间限制不能读取订阅余额，不能代替
服务端费用上限。默认不下载大型模型，未知请求结果不自动重试。
原始日志和模型轨迹可能包含私有内容，公开前人工脱敏；见 [安全说明](../SECURITY.md)。
变更通过 PR 检查清单、完整回归和发布证据检查；见 [贡献指南](../CONTRIBUTING.md)。
远程分支保护、私密漏洞报告与账户级设置由维护者确认后配置，文件模板不等于
这些服务端设置已经启用。