本页目录
Harness v5 架构：执行骨架与上下文工程
一句话：v5 给 research-assistant 装上窗口管理系统——8k 假 token 窗口跑完 30 源深度研究：不溢出（账本+外置）、不失忆（登记压缩+工作区）、中途可改道（安全点协商）、跨会话记得住人（记忆文件）。全部机制默认关，纯净跑与 v4 逐字节一致。
来源课程：harness-lessons（课程十一，10 课）。
1. 问题：窗口是物理约束
前十门课的能力都建立在「一次运行的上下文总是够用」的隐含假设上（FakeLLM 无限窗口 + 任务够短）。长途任务（30 源、22,831 token 语料、8k 窗口）撞墙的四种死法：
| 死法 | 机制 | v5 的解 |
|---|---|---|
| 硬溢出 | 超窗被 API 拒（裸奔死于 S11） | 账本水位预警 + 外置让主窗峰值 837 |
| 截断失忆 | 静默丢内容（在场率 8/20） | 登记契约 + 省略必须显式 |
| 迷航 | lost in the middle + 目标漂移 | recitation 现读 plan.md（认知收益，mock 不可测——诚实边界） |
| 中毒 | 错误内容占窗自我强化 | 隔离（过程不回传）+ 防污染召回提示 |
2. 八机制在窗口生命周期上的位置
┌──────────── 一次长程运行 ────────────┐
组装 system ──► L08 三层指令架构（核心/索引/按需——省 58%）
│
每次调用前 ──► L01 上下文账本（四桶计量+水位三区，纯测量）
│
工具结果进门 ─► L04 整形三板斧（截断显式/分页/引用——控源）
│
过程干活 ────► L05 子代理隔离（独立子窗+结论回传+结构化失败）
│
工作集存放 ──► L06 文件工作区（指针协议+recitation+崩溃续跑）
│
装不下时 ────► L02 压缩（登记-摘要-验证+审计——外置后全程失业，兜底待命）
│
人要说话 ────► L07 改道（安全点协商合并）+ 权限门（三红线 100% 拦截）
│
会话之间 ────► L03 记忆文件（写入纪律 gate+索引常驻正文按需）
治理顺序（账本给的证据链）：先记账（量出工具结果占 75-95%）→ 先控源（整形）→ 能外置的外置（子代理+工作区）→ 剩下的压缩 → 指令懒加载。
3. 开关矩阵（九开关默认全关，纯净跑零税）
| 开关 | 默认 | 开启后 | 关闭即 |
|---|---|---|---|
enable_context_ledger |
off | 主链路五节点六调用四桶记账（纯测量不拦截） | 现状 |
enable_compaction |
off | 压缩器可用（运行时消费方=长程模式） | 现状 |
enable_memory_files |
off | writer 按 trigger 召回操作记忆 | 现状 |
enable_tool_shaping |
off | researcher 检索结果超预算截断+显式标记 | 现状 |
enable_subagent_isolation |
off | SubagentRunner 可用（长程模式） | 现状 |
enable_workspace |
off | 工作区可用（长程模式） | 现状 |
enable_steering / enable_tool_gate |
off | 改道队列/权限门可用 | 现状 |
enable_layered_system |
off | 三层 system 组装（长程模式；writer 单点保持 frontier-L03 现状） | 现状 |
4. 与既有资产的边界（复用不重写）
| 资产 | 它管的 | v5 新增的 | 关系 |
|---|---|---|---|
| memory.py（frontier） | 任务经验向量召回 | 操作记忆文件（用户偏好/约束） | L03 三种记忆分家 |
| task_ledger.py | 任务进度语义 | 认知外置（自由文本工作集） | L06 互补 |
| cost_budget / period_budget | 钱（轨迹/时段） | 空间（窗口占位）——第四种预算 | L01 并行不悖 |
| checkpoint（agent-ops L06） | 图状态快照 | 工作区（人机共读写） | L06 双恢复各管一段 |
| HITL + inbox | 审批与通知 | 改道通道 + 权限门（审批点推广） | L07 复用 interrupt/inbox |
| skill_loader（frontier-L03） | writer 单点渐进加载 | 三层全链路组装 + 计量 | L08 扩展不新建 |
5. 收益矩阵（确定性可复现）
| 配置 | 完成源数 | 主窗峰值 | 在场率 | 计费token | 改道 | 跨会话 |
|---|---|---|---|---|---|---|
| A baseline·长程裸奔 | 10/30 | 越限即死 | 0/20 | 44,203 | — | — |
| B 只硬截断 | 30/30 | 4,292 | 8/20 | 74,981 | — | — |
| C +会计与压缩 | 30/30 | 5,272 | 20/20 | 106,844 | — | — |
| D +外置 | 30/30 | 718 | 20/20 | 39,708 | — | — |
| E 全套 v5 | 26/30(+4跳过) | 837 | 20/20 | 39,294 | ✅ | ✅ |
killer row：「截断买到活着，买不到记得」（B 档）。复现：python eval_agent/run_harness_eval.py（零 API 零联网零等待，双跑逐字节一致）。完整报告见 eval_agent/HARNESS_REPORT.md。
6. 诚实边界
- FakeTokenizer 为 len//4 字符近似（与 cost_budget 估算同口径）；绝对数字非真实 API，五档相对结构与真实一致。
- mock 层验收机械纪律：窗口算术、省略显式、登记 100% 存活、隔离零泄漏、偏好跨会话在场。认知收益（迷航改善、摘要语义保真）mock 测不了——引证据陈述 + L09 可选真模型章抽查（需 ZHIPUAI_API_KEY，主验收不依赖）。
- 两条诚实纪律贯穿：省略必须显式（静默截断=谎报全文）、压缩必须留审计（无痕压缩=篡史）——与课程十「没能看到 ≠ 没有变化」同宗。