代理上下文隔离
- 作者仓库星标 3,783
- 作者仓库 Continuous-Claude-v3
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @parcadei · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# WRONG - dumps entire transcript (70k+ tokens) into context
TaskOutput(task_id="<id>")
TaskOutput(task_id="<id>", block=true)
# RIGHT - check expected output files
Bash("ls -la .claude/cache/agents/<agent-type>/")
Bash("bun test") # verify with tests
# Agent Context Isolation
Prevent agent output from polluting the main context window.
## Rules
### 1. Use Background Agents with File-Based Coordination
```
# RIGHT - background agent writes to file, main reads file
Task(subagent_type="...", run_in_background=true, prompt="... Output to: /path/to/file.md")
# WRONG - foreground agent dumps full transcript into main context
Task(subagent_type="...", run_in_background=false)
```
Background agents with `run_in_background=true` isolate their context. Have them write results to files in `.claude/cache/agents/<agent-type>/`.
### 2. Never Use TaskOutput to Retrieve Results
```
# WRONG - dumps entire transcript (70k+ tokens) into context
TaskOutput(task_id="<id>")
TaskOutput(task_id="<id>", block=true)
# RIGHT - check expected output files
Bash("ls -la .claude/cache/agents/<agent-type>/")
Bash("bun test") # verify with tests
```
TaskOutput returns the full agent transcript. Always use file-based coordination instead.
### 3. Monitor Agent Progress via System Reminders
```
# System reminders come automatically:
# "Agent a42a16e progress: 6 new tools used, 88914 new tokens"
# To detect completion:
# - Watch for progress reminders to stop arriving
# - Poll for expected output files: find .claude/cache/agents -name "*.md" -mmin -5
# - Check task output file size growth: wc -c /tmp/claude/.../tasks/<id>.output
```
**Stuck agent detection:**
1. Progress reminders stop arriving
2. Task output file size stops growing
3. Expected output file not created after reasonable time
### 4. Verify with Tests, Not Output
After agent work:
1. Run the test suite directly: `bun test`
2. Report pass/fail counts
3. Only investigate failures if tests fail
### 5. File-Based Agent Pipeline Pattern
```
Research agent → .claude/cache/agents/oracle/output.md
↓
Plan agent → .claude/cache/agents/plan-agent/output.md (reads research)
↓
Validate agent → .claude/cache/agents/validate-agent/output.md (reads plan)
↓
Implement agent → src/module.ts (reads validated plan)
```
Each agent reads the previous agent's file output, not TaskOutput.
## Why This Matters
Agent context isolation preserves the main conversation's context budget. Reading agent outputs via TaskOutput floods context, causing:
- Mid-conversation compaction
- Lost context about user's original request
- Repeated explanations needed
## Source
- Session where TaskOutput flooded 70k+ tokens into main context
- Session 2026-01-01: Successfully used background agents with file-based coordination for SDK Phase 3
章节与文件索引
按说明文件中的顺序排列。
1.使用后台代理和基于文件的协调
2. 切勿使用 TaskOutput 检索结果
3. 通过系统提醒监控座席进度
4. 通过测试验证,而不是输出
5. 基于文件的代理管道模式
文件/命令 -> run_in_background=true · .claude/cache/agents/<agent-type>/ · bun test · path/to/file.md · .claude/cache/agents · tmp/claude/.../tasks · pass/fail · .claude/cache/agents/oracle/output.md
内容校验值 -> 0a563b12cba7
当前原文的自动摘译,尚未人工审校。
1.使用后台代理和基于文件的协调
带有
run_in_background=true的后台代理隔离他们的上下文。让他们将结果写入.claude/cache/agents/<agent-type>/中的文件。2. 切勿使用 TaskOutput 检索结果
TaskOutput 返回完整的代理记录。始终使用基于文件的协调。
3. 通过系统提醒监控座席进度
卡住代理检测:进度提醒停止到达 任务输出文件大小停止增长 预期输出文件在合理时间后未创建
4. 通过测试验证,而不是输出
代理工作后:直接运行测试套件:
bun test报告通过/失败计数 仅在测试失败时调查失败5. 基于文件的代理管道模式
每个代理读取前一个代理的文件输出,而不是 TaskOutput。