Shell、Patch 与命令生命周期

1. 为什么这组知识要一起学

本章以 Coding Agent 作为现代 Harness 的高价值案例：workspace 是外部状态，sandbox 是执行边界，外层 Runtime 仍持有审批、trace 和 resume。

这几个知识点处在同一条工程链上。如果只记单个名词，很容易在真实系统里把责任放错层：例如让模型管理程序事实、让数据库 transaction 承担外部 API 原子性，或把一个 provider SDK 的行为误认为 Agent 的通用规律。

2. Mental Model

Coding Agent 的核心外部状态是 Workspace；文件、shell、git、test、artifact 与 sandbox session 构成“hands”，外层 Runtime 仍管理 approvals/tracing/resume。

Manifest/Repo → Sandbox Session → Search/Read → Edit/Patch → Shell/Test → Diff/Verify → Artifact → Snapshot/Resume

3. 核心机制

Shell Tool

命令需要 cwd/env/user、timeout、stdout/stderr limit、exit status 与 cancel；PTY 只在交互程序需要时引入，避免增加状态复杂度。

Apply Patch / File Editing

编辑最好生成可审查 patch，apply 后读取 diff 并运行 targeted test；“工具返回成功”不是修改正确的证据。

Command Lifecycle

命令需要 cwd/env/user、timeout、stdout/stderr limit、exit status 与 cancel；PTY 只在交互程序需要时引入，避免增加状态复杂度。

4. 最小实现 / 伪代码

下面代码只表达边界和生命周期，不要求照抄到项目中：

workspace = await sandbox.open(manifest)
paths = await workspace.search("TODO")
patch = await agent.propose_patch(paths)
await workspace.apply_patch(patch)
result = await workspace.exec(["pytest", "-q"] )

真正实现时应把 I/O、状态持久化、错误翻译和策略注入拆成可测试组件，而不是把示例扩成一个巨型函数。

5. 在 Shadow Harness 中怎么落地

WorkspaceAdapter 抽象 read/search/patch/exec/artifact/snapshot；skills 采用 progressive loading；session 与 workspace snapshot 分开。

建议为本章涉及的行为留下明确的 domain object、interface 和 trace event；只要一个关键行为只能通过读日志猜测，就说明 Runtime contract 仍不够清晰。

6. Production Engineering 检查项

• 命令有 lifecycle/timeout/output limit
• patch 后必须验证
• resume 需要可信 manifest/credential re-injection
• artifact 有输出 contract

7. Failure Modes

7.1 整仓一次塞 context

当出现「整仓一次塞 context」时，检查 workspace diff、command exit/output、sandbox session/snapshot 与 artifact；恢复时从 Git/manifest/checkpoint 重新 grounding。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.2 shell stdout 无上限

当出现「shell stdout 无上限」时，检查 workspace diff、command exit/output、sandbox session/snapshot 与 artifact；恢复时从 Git/manifest/checkpoint 重新 grounding。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.3 patch 成功但未测试

当出现「patch 成功但未测试」时，检查 workspace diff、command exit/output、sandbox session/snapshot 与 artifact；恢复时从 Git/manifest/checkpoint 重新 grounding。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.4 把 serialized state 当新权限来源

当出现「把 serialized state 当新权限来源」时，检查 workspace diff、command exit/output、sandbox session/snapshot 与 artifact；恢复时从 Git/manifest/checkpoint 重新 grounding。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.5 skill/plugin 未建立 trust 就加载

当出现「skill/plugin 未建立 trust 就加载」时，检查 workspace diff、command exit/output、sandbox session/snapshot 与 artifact；恢复时从 Git/manifest/checkpoint 重新 grounding。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

8. Trade-offs

本地 workspace 快但隔离弱；container/hosted sandbox 隔离强但启动/成本更高；按风险和可恢复要求选择。

设计记录最好明确：当前约束是什么、备选方案有哪些、为什么现在选这个、未来什么条件出现时需要重构。 这样 ADR 才能随着模型和基础设施变化被重新审视。

9. Experiment / Evaluation

设计 coding task：搜索→修改→测试→失败→恢复 snapshot，验证 diff、artifact、trace 和 resume。

实验应固定数据集、版本和环境，至少记录 success、latency、token/cost、attempt/step 数以及失败类型；涉及随机模型时需要重复运行而不是只看一次结果。

10. 常见问题

基础：Shell Tool 最容易被误解的点是什么？

命令需要 cwd/env/user、timeout、stdout/stderr limit、exit status 与 cancel；PTY 只在交互程序需要时引入，避免增加状态复杂度。

机制：这些能力在一次 Run 的哪个生命周期阶段生效？

沿着 Manifest/Repo → Sandbox Session → Search/Read → Edit/Patch → Shell/Test → Diff/Verify → Artifact → Snapshot/Resume 找位置，并明确它的输入、输出、持久化事实和失败传播。

工程：如果这一层失败，应该由谁恢复？

先区分 transient failure、invalid input、permission、semantic failure 与 irreversible side effect。恢复策略属于拥有该状态与副作用的 Runtime/adapter，而不是交给模型自由决定。

设计：规模扩大 10 倍后，哪个假设最先失效？

优先检查 context/token、并发/连接池、catalog 大小、持久化吞吐、trace 体积、身份与租户隔离。不要默认“多加机器”能解决语义和一致性问题。

11. Sources

• OpenAI Agents SDK — Sandbox agents concepts
• OpenAI Agents SDK — Sandbox agents quickstart
• Anthropic — Effective harnesses for long-running agents

12. 本文结论

掌握本文的标准不是能背定义，而是能画出数据流、写出最小 contract、解释失败恢复，并用测试或 benchmark 证明设计没有只停留在概念层。