当智能体上下文窗口受限、工具输出膨胀或需跨会话/子智能体共享…

适用于需要文件支撑的智能体上下文：工具输出卸载、草稿本、计划持久化、子智能体交接、动态技能加载、终端/日志检索、文件系统记忆与清理。

适用场景

解决思路

1. 缺失上下文：将工具输出和中间结果持久化到文件，确保信息不丢失。
2. 检索不足：将文件组织成 grep 友好格式并设置清晰章节标题，以支持定向检索。
3. 检索过度：将批量内容卸载到文件，只向上下文返回紧凑引用。
4. 上下文被埋没：结合 glob 和 grep 做结构搜索，并结合语义搜索处理概念查询。
5. 将静态上下文（系统指令、工具定义、关键规则）视为昂贵空间；只包含最小静态指针（名称、一句话描述、文件路径），需要时用搜索工具加载完整内容。
6. 接受动态发现的权衡：它要求模型能识别何时需要更多上下文；不确定时，关键安全或正确性约束仍应静态包含。
7. Pattern 1：把大工具输出重定向到文件而非直接返回上下文；写输出到 scratch 文件，提取紧凑摘要，返回文件引用。
8. 实现 handle_tool_output(output, threshold=2000)：长度小于 threshold 直接返回；否则 file_path = f"scratch/{tool_name}_{timestamp}.txt"，write_file(file_path, output)，key_summary = extract_summary(output, max_tokens=200)，返回 f"[Output written to {file_path}. Summary: {key_summary}]"。
9. 使用 grep 搜索卸载后的文件，并用 read_file 带行范围读取目标片段，从而在活跃上下文中只保留约 100 tokens，同时保留完整输出供后续参考。
10. Pattern 2：把计划写入文件系统，因为长期任务会因计划淡出注意力或被摘要掉而失去连贯性；agent 可随时重读计划恢复目标与进度。
11. 用结构化格式存储计划，如 scratch/current_plan.yaml，包含 objective、status、steps（每步 id、description、status），使其既可读又可机器解析。
12. 每个回合开始或任何上下文刷新后重读计划，以重新定向；这相当于通过复述操纵注意力。
13. Pattern 3：子智能体发现通过文件系统路由，而不是消息传递，因为多跳消息链会经过每跳摘要而降质。
14. 让每个子智能体直接写入自己的工作区目录；协调者直接读取这些文件以保持完整保真。目录如 workspace/agents/research_agent/findings.md、sources.jsonl；workspace/agents/code_agent/changes.md、test_results.txt；workspace/coordinator/synthesis.md。
15. 强制每个 agent 目录隔离，防止写冲突并保持每个输出工件的清晰所有权。
16. Pattern 4：把技能存为文件，静态上下文中只放技能名和简短描述，例如：Available skills (load with read_file when relevant): - database-optimization: Query tuning and indexing strategies - api-design: REST/GraphQL best practices - testing-strategies: Unit, integration, and e2e testing patterns。
17. 仅当当前任务需要时加载完整技能文件，例如 skills/database-optimization/SKILL.md；这把 O(n) 静态 token 成本转为每任务 O(1)。
18. Pattern 5：自动把终端输出持久化到文件，并用 grep 选择性检索，例如 terminals/1.txt、terminals/2.txt。
19. 用定向 grep 查询，如 grep -A 5 "error" terminals/1.txt，而不是把整个终端历史加载进上下文。
20. Pattern 6：让 agent 将学到的偏好和模式写入自己的指令文件，使后续会话自动加载该上下文，而不必手动更新系统提示。
21. 实现 remember_preference(key, value)：preferences_file = "agent/user_preferences.yaml"，prefs = load_yaml(preferences_file)，prefs[key] = value，write_yaml(preferences_file, prefs)。
22. 用验证保护自我修改，因为自我修改会随时间累积错误或矛盾指令；把它当作实验，并定期审查持久化偏好。
23. 结合 ls/list_dir、glob、grep、read_file 带行范围进行上下文发现；模型专门训练过文件系统遍历，对结构模式清晰的技术内容，这常优于语义搜索。
24. 用 ls/list_dir 发现目录结构。
25. 用 glob 查找匹配模式的文件，如 **/*.py。
26. 用 grep 搜索文件内容，返回匹配行及上下文。
27. 用 read_file 带范围读取特定章节，而不加载整个文件。
28. 结构性和精确匹配查询用文件系统搜索，概念查询用语义搜索；组合两者进行全面发现。
29. 按 agent 可发现性组织文件：project/scratch/ 放临时工作文件，其中 tool_outputs/ 放大工具结果、plans/ 放活动计划和清单；project/memory/ 放持久学习信息，其中 preferences.yaml 放用户偏好、patterns.md 放学到的模式；project/skills/ 放可加载技能定义；project/agents/ 放子智能体工作区。
30. 使用一致命名约定，并在 scratch 文件名中包含时间戳或 ID 以消除歧义。
31. 对于自主研究循环，把原始检索证据存放在消费它的运行下，例如 researcher/runs/<run-id>/sources/evidence/raw/；不要把原始研究转储留在仓库根目录，因为根级工件难以审计且容易被无出处引用。
32. 在应用文件系统模式前后测量 token 来源：跟踪静态 vs 动态上下文比例；监控卸载前后工具输出大小；测量动态加载的上下文实际被使用频率。
33. 将大输出写入文件；向上下文返回摘要和引用。
34. 将计划和状态存储到结构化文件以便重读。
35. 用子智能体文件工作区代替消息链。
36. 动态加载技能，而不是全部塞进系统提示。
37. 将终端和日志输出持久化为可搜索文件。
38. 结合 grep/glob 与语义搜索进行全面发现。
39. 用清晰命名组织文件，方便 agent 发现。
40. 测量 token 节省，验证文件系统模式有效。
41. 实现 scratch 文件清理，防止无限增长。
42. 用验证保护自我修改模式。
43. 将原始证据放在使用它的运行、评估和提案旁边。
44. Example 3：上下文窗口达限需摘要时，把完整历史写入 history/session_001.txt，为新上下文窗口生成摘要，并包含引用「Full history in history/session_001.txt」，使 agent 可搜索历史文件恢复摘要中丢失的细节。
45. 防止 scratch 目录无限增长：实现保留策略（按年龄或数量）并在会话边界运行清理。
46. 防止多 agent 文件访问竞态：强制每 agent 目录隔离，或使用仅追加文件并在条目中加 agent 前缀。
47. 防止移动/重命名后文件引用过期：读取缓存路径前验证文件存在，检查失败时用 glob 重新发现。
48. 防止 glob 模式误匹配：把 glob 范围限定到特定目录和扩展名，避免 **/* 这类过宽模式把无关文件拉入上下文。
49. 防止文件大小假设：读取前检查文件大小，大文件使用行范围读取，避免一次 tool call 倾倒 100K+ tokens。
50. 防止缺少文件存在检查：始终用存在检查保护读取，并优雅处理缺失文件错误。
51. 防止草稿本格式漂移：从首次写入起定义并强制 schema（YAML、JSON 或结构化 markdown），避免多次追加后不可解析。
52. 防止硬编码绝对路径：使用相对项目根的路径或动态解析路径，以适应不同检出位置或容器。

适用边界 · 注意事项

• 不要用于相邻技能负责的工作：语义跨会话记忆、实体跟踪或时间知识图谱用 memory-systems；对话摘要、压缩或持久交接措辞用 context-compression；不需要文件存储的 token 效率策略用 context-optimization；多智能体拓扑或交接协议设计用 multi-agent-patterns。
• 当任务可在单轮完成、上下文能舒适放入窗口、延迟关键（文件 I/O 增加可测量延迟）、或模型缺少文件系统工具能力时，避免使用文件系统上下文模式。