name: 代理上下文隔离 description: 代理上下文隔离 user-invocable: false

代理上下文隔离

防止代理输出污染主上下文窗口。

规则

1. 使用背景代理与基于文件的协调

# 正确 - 背景代理写入文件，主上下文读取文件
Task(subagent_type="...", run_in_background=true, prompt="... Output to: /path/to/file.md")

# 错误 - 前台代理将完整转录转储到主上下文
Task(subagent_type="...", run_in_background=false)

背景代理使用 run_in_background=true 隔离其上下文。让它们将结果写入文件到 .claude/cache/agents/<agent-type>/。

2. 永远不要使用 TaskOutput 来检索结果

# 错误 - 将整个转录（70k+ tokens）转储到上下文
TaskOutput(task_id="<id>")
TaskOutput(task_id="<id>", block=true)

# 正确 - 检查预期的输出文件
Bash("ls -la .claude/cache/agents/<agent-type>/")
Bash("bun test")  # 用测试验证

TaskOutput 返回完整的代理转录。始终使用基于文件的协调。

3. 通过系统提醒监控代理进度

# 系统提醒自动出现：
# "Agent a42a16e progress: 6 new tools used, 88914 new tokens"

# 检测完成：
# - 观察进度提醒是否停止到达
# - 轮询预期的输出文件：find .claude/cache/agents -name "*.md" -mmin -5
# - 检查任务输出文件大小增长：wc -c /tmp/claude/.../tasks/<id>.output

卡住代理检测：

进度提醒停止到达
任务输出文件大小停止增长
预期输出文件在合理时间后未创建

4. 用测试验证，而不是输出

代理工作后：

直接运行测试套件：bun test
报告通过/失败计数
仅当测试失败时调查失败

5. 基于文件的代理管道模式

研究代理 → .claude/cache/agents/oracle/output.md
                          ↓
计划代理 → .claude/cache/agents/plan-agent/output.md (读取研究)
                          ↓
验证代理 → .claude/cache/agents/validate-agent/output.md (读取计划)
                          ↓
实施代理 → src/module.ts (读取验证后的计划)

每个代理读取前一个代理的文件输出，而不是 TaskOutput。

为什么这很重要

代理上下文隔离保留主对话的上下文预算。通过 TaskOutput 读取代理输出会淹没上下文，导致：

对话中途压缩
丢失用户原始请求的上下文
需要重复解释

来源

会话中 TaskOutput 淹没了70k+ tokens到主上下文
会话 2026-01-01：成功使用背景代理与基于文件的协调进行SDK第3阶段