17. 当前状态与下一步

本章总结当前 harness 已经真实具备的能力，以及下一阶段最值得推进的方向。它不是路线图承诺，而是从现有边界出发的工程判断。

读完本章后，应该理解：

• 当前项目已经具备哪些 agent 基础能力
• sandbox、shell、approval resume，以及更深层 editing safety 为什么仍然是空缺
• session replay 和 context compaction 为什么会成为后续关键能力
• 新章节应该如何继续保持教程可维护

现在真实存在什么

项目现在已经有真实可检查 agent harness 基础：

• thin Next.js API routes
• schema-first input validation
• OpenAI-compatible chat service
• streaming agent route
• cancellation boundary
• internal runtime events
• provider-neutral model gateway
• OpenAI Chat Completions dialect
• OpenAI Responses dialect
• OpenAI strict tool-schema adapter
• AgentResponseItem model-visible history
• streaming sampling loop
• assistant commit semantics
• deterministic runtime tests
• read-only tools: ls, find, grep, read
• editing tools v1: write, edit
• read-before-edit runtime precondition
• path policy boundary
• tool runtime boundary
• permission skeleton with path-policy hardening
• run policy request contract and frontend controls
• structured tool output contract
• Debug Console with permission audit
• JSONL session store and browser
• tool source/group/path/execution contract
• unlimited loop with repeated-call guard

还缺什么

Sandbox

当前 path policy 不是 OS sandbox。它只是 runtime path boundary。 sandboxMode 现在已经会映射到文件工具使用的 effective path policy： read_only 保持当前项目边界，danger_full_access 允许声明了路径访问的只读工具访问项目外绝对路径。

剩下的生产级步骤是 OS-level enforcement，以及为 write/edit、shell、network-capable tools 设计更完整的模式：

read-only
workspace-write
danger-full-access
external sandbox

Write/Edit

Write/edit 现在已经是第一层真实编辑能力：

• diff-oriented output
• clear failure messages
• 写入前完成 exact replacement validation
• runtime 层强制 read-before-edit

仍然缺的是更深的生产级层：

• 需要人工决策时的 interactive approval/resume
• 文件在 read 和 edit 之间变化时的 richer conflict behavior
• 多个 write-capable calls 之间更强的 concurrency control
• runtime path policy 下面的 OS-level sandbox enforcement

Shell

Shell v1 已经存在（见第 18 章）：command schema、per-call timeout、cancellation、 output truncation、safe-command 分类器和 tool-level permission override。

仍然缺的：

• PTY/交互式 session support
• 后台执行与流式输出
• 中间截断或落盘式的大输出处理
• OS-level sandbox enforcement

Approval Resume

已经实现（见第 19 章）：interactive approval mode 下，ask 决策会挂起对应的 tool-call promise，通过 POST /api/agent/approvals/{runId}/{toolCallId} 批准或 拒绝后恢复执行；拒绝会产出一条 model-visible 的可恢复错误，循环继续而不是失败退出。

Pending 状态目前是进程内存（Map<runId:toolCallId, resolver>），不是磁盘持久化—— 这与 Codex/Claude Code 的行为一致：批准是 turn 内的临时状态，进程重启即视为拒绝。 完整的审计轨迹（谁在什么时候请求/批准/拒绝了什么）通过已有的 JSONL session event 日志留存，approval_requested/approval_resolved 事件本来就会被记录。

仍然缺的：进程重启后的 pending-approval 恢复（如果这变得重要，需要把 pending state 也写入 JSONL 并在 resume 时重建）。

Session Replay

已经实现（见第 20 章）：sessionId 输入字段让同一个 JSONL session 可以被多次 继续，resumeAgentSession 从 response-item 记录重建 model-visible history, normalizeAgentResponseItemHistory 修复 mid-turn crash 留下的孤儿 function_call。resume 只把新增内容(normalize 产生的 synthesized output、新的 user 消息)写回磁盘，不会重写整段历史。

仍然缺的：非流式 /api/agent 路由没有 session 概念；没有从历史中间"分叉"出 新会话的能力(Codex 的 fork);Session 面板还是一条扁平的 JSONL 流，不单独 可视化"第几轮"。

Context Compaction

已经实现（见第 21 章）：token usage 达到阈值时，decideAgentHistoryCompaction 触发压缩，applyAgentHistoryCompaction 用"完全替换"策略保留 system message、 一条模型生成的摘要、以及预算内的最近 user 消息，其余全部吸收进摘要。因为压缩 从不保留部分工具调用，function_call/function_call_output 配对不变量几乎是 自动满足的。

仍然缺的：阈值是固定常量，没有按模型 context window 配置；没有 Claude Code 式不调模型的 microcompact;摘要生成失败没有重试/熔断。

MCP / Dynamic / Hosted Tools

Tool contract 已经有 source categories。当前只有 built-ins active。

未来可以添加：

• dynamic tool registration
• MCP discovery and dispatch
• hosted provider tools
• tool-search/discovery

未来章节怎么加

每个新能力都应该新增或更新教程章节，包含：

why the layer appeared
what boundary was introduced
what data flows through it
what tradeoff was accepted
which tests prove it
what remains deferred

这样教程会和代码一起生长，而不是事后补一份 README。

常见误解

误解一：不到 6000 行后端代码说明能力很少

代码行数不是能力质量的唯一指标。这个项目的价值在于边界清楚：provider dialect、runtime spine、tools、session、debug、streaming 和 tests 已经形成可继续扩展的骨架。

误解二：下一步一定要先做 sandbox

Sandbox 很重要，但“sandbox”本身分层。项目现在已经有 pre-execution permission decisions 和 path-policy hardening。OS sandbox、approval resume、更深层 editing safety、shell、session replay、telemetry 都可能成为下一步，取决于下一阶段最需要验证什么。

误解三：开源教程只需要介绍最终代码

这个项目的价值之一是演化过程。教程应该保留取舍和边界变化，但要用公共读者能理解的方式组织，而不是内部复盘口吻。

本章小结

当前项目已经具备真正 agent harness 的基础：模型循环、流式输出、真实只读工具、editing tools v1、provider dialect、session 记录和 debug surface。下一步应该继续沿着同一原则推进：先定义边界，再实现能力，再用测试和教程固定下来。

本章验证点

本章列出的"现在真实存在什么"可以用两条不需要 key 的命令交叉核对。第一条是全量测试——上面每一项能力都有对应用例在这 103 个里：

npm test

实测尾部输出：

ℹ tests 103
ℹ pass 103
ℹ fail 0

第二条是演化轨迹本身——本章描述的每个"已经实现"都能在提交历史里找到对应落点：

git log --oneline

实测头部输出（截取）：

0581dbf shell 安全收紧:safe 分类加参数级筛查,子进程 env 白名单,workdir realpath 校验
551ce08 新增 context compaction:token 阈值触发历史压缩,复用 model gateway 生成摘要
727f7a6 新增 session replay/resume:sessionId 解耦 session 身份与 run 身份,支持多轮对话续接

如果测试数量或提交内容和你手上的检出对不上，说明代码已经继续演化——以代码为准，这一章描述的是它写下时的边界。