filesystem-context

基于文件系统的上下文工程

由于上下文窗口有限，而任务所需信息往往超出单个窗口的容量，因此应将文件系统用作 Agent 上下文的主要溢出层。通过单一接口，文件可让 Agent 存储、检索和更新实际上无限量的上下文。

优先采用动态上下文发现——按需提取相关上下文——而非静态纳入，因为无论是否相关，静态上下文都会消耗令牌，并挤占任务专属信息的空间。

何时启用

在以下情况下启用此技能：

• 工具输出使上下文窗口过度膨胀
• Agent 需要在漫长的执行过程中持久化状态
• 子 Agent 必须在不直接传递消息的情况下共享信息
• 任务所需的上下文超出窗口容量
• 构建能够学习并更新自身指令的 Agent
• 为中间结果实现草稿区
• 终端输出或日志需要能被 Agent 访问

以下相邻工作由其他技能负责，请勿启用此技能：

• 跨会话语义记忆、实体跟踪或时序知识图谱：memory-systems。
• 对话摘要、压缩或持久化交接措辞：context-compression。
• 无需文件存储的令牌效率技巧：context-optimization。
• 多 Agent 拓扑或交接协议设计：multi-agent-patterns。
• 会从实时窗口中逐出内容的模型编辑：self-managed-context。

核心概念

针对以下四种模式诊断上下文问题，因为每种模式都需要不同的文件系统解决方案：

1. 上下文缺失——所需信息不在可用上下文总量中。将工具输出和中间结果持久化到文件中，确保不会丢失任何内容。
2. 上下文检索不足——检索到的内容未能涵盖 Agent 所需信息。通过合理组织文件来支持定向检索（采用便于 grep 的格式，并设置清晰的章节标题）。
3. 上下文检索过量——检索到的内容远超实际所需，浪费令牌并削弱注意力。将大量内容移至文件中，并仅返回精简的引用。
4. 上下文埋藏——零散信息隐藏在许多文件中。结合使用 glob 和 grep 进行结构化搜索，并用语义搜索处理概念性查询。

将文件系统用作持久层，以解决上述所有问题：写入一次、持久存储、按需检索。

详细主题

静态上下文与动态上下文的权衡

将静态上下文（系统指令、工具定义、关键规则）视为昂贵的空间——无论是否相关，它都会在每轮对话中消耗令牌。随着 Agent 能力不断增加，静态上下文也会扩大，并挤占动态信息的空间。

改用动态上下文发现：仅纳入最精简的静态指引（名称、一行描述、文件路径），并在相关时使用搜索工具加载完整内容。这样能提高令牌效率，而且通常还能减少窗口中的矛盾或无关信息，从而改善响应质量。

接受这种权衡：动态发现要求模型能识别何时需要更多上下文。目前的前沿模型在这方面表现良好，但能力较弱的模型可能无法触发加载。如有疑问，应优先将关键安全或正确性约束静态纳入上下文。

模式 1：将文件系统用作临时存储区

将大型工具输出重定向到文件，而不是直接返回到上下文中，因为单次网页搜索或数据库查询就可能向消息历史中写入数千个 token，并在整个对话期间持续保留。

将输出写入临时文件，提取精简摘要，并返回文件引用。随后，Agent 使用定向检索（按模式 grep、按行范围读取）仅访问所需内容。

def handle_tool_output(output: str, threshold: int = 2000) -> str:
    if len(output) < threshold:
        return output

    file_path = f"scratch/{tool_name}_{timestamp}.txt"
    write_file(file_path, output)

    key_summary = extract_summary(output, max_tokens=200)
    return f"[Output written to {file_path}. Summary: {key_summary}]"

使用 grep 搜索转存文件，并使用 read_file 按行范围检索目标片段，因为这样既能保留完整输出供日后参考，又能将活动上下文控制在约 100 个 token。

模式 2：持久化计划

将计划写入文件系统，因为长期任务中的计划一旦淡出注意力或被摘要取代，就会失去连贯性。Agent 可以随时重新读取计划，恢复对目标和进度的认识。

以结构化格式存储计划，使其既便于人类阅读，也可供机器解析：

# scratch/current_plan.yaml
objective: "Refactor authentication module"
status: in_progress
steps:
  - id: 1
    description: "Audit current auth endpoints"
    status: completed
  - id: 2
    description: "Design new token validation flow"
    status: in_progress
  - id: 3
    description: "Implement and test changes"
    status: pending

在每轮开始时或上下文刷新后重新读取计划，以重新明确方向，因为这就像是“通过复述来操控注意力”。

模式 3：通过文件系统进行子 Agent 通信

通过文件系统传递子 Agent 的发现结果，而不是通过消息传递，因为多跳消息链会在每次转述摘要时损失信息（“传话游戏”）。

让每个子 Agent 直接将内容写入自己的工作区目录。协调者直接读取这些文件，从而保留完整信息：

workspace/
  agents/
    research_agent/
      findings.md
      sources.jsonl
    code_agent/
      changes.md
      test_results.txt
  coordinator/
    synthesis.md

为每个 Agent 强制实施目录隔离，以防止写入冲突，并明确每个输出产物的归属。

模式 4：动态加载技能

将技能存储为文件，并仅在静态上下文中列出技能名称和简短说明，因为把所有指令塞进系统提示词会浪费 token，还可能让模型受到相互矛盾的指导。

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

仅在当前任务需要时加载完整的技能文件（例如，skills/database-optimization/SKILL.md）。这会将 O(n) 的静态 token 开销转化为每项任务 O(1) 的开销。

模式 5：持久化终端输出和日志

自动将终端输出保存到文件，并使用 grep 进行选择性检索，因为长时间运行的进程会迅速累积终端输出，手动复制粘贴也容易出错。

terminals/
  1.txt    # Terminal session 1 output
  2.txt    # Terminal session 2 output

使用定向 grep（grep -A 5 "error" terminals/1.txt）进行查询，而不是将完整的终端历史记录加载到上下文中。

模式 6：通过自我修改进行学习

让 Agent 将学到的偏好和模式写入自己的指令文件，以便后续会话自动加载这些上下文，而不必手动更新系统提示词。

def remember_preference(key: str, value: str):
    preferences_file = "agent/user_preferences.yaml"
    prefs = load_yaml(preferences_file)
    prefs[key] = value
    write_yaml(preferences_file, prefs)

对此模式实施验证机制，因为自我修改可能会随着时间推移累积错误或相互矛盾的指令。应将其视为实验性做法，并定期检查已保存的偏好。

文件系统搜索技巧

结合使用 ls/list_dir、glob、grep 和带行范围的 read_file 来发现上下文，因为模型专门针对文件系统遍历进行了训练；对于结构模式清晰的技术内容，这种组合往往优于语义搜索。

• ls / list_dir：发现目录结构
• glob：查找符合模式的文件（例如，**/*.py）
• grep：搜索文件内容，并返回匹配行及上下文
• 带范围的 read_file：读取特定片段，而不加载整个文件

对于结构性和精确匹配查询，使用文件系统搜索；对于概念性查询，使用语义搜索。结合两者可进行全面探索。

实用指南

何时使用文件系统上下文

当情况符合以下条件时，应用文件系统模式，因为它们会增加 I/O 开销，只有在节省令牌或需要持久化时才值得采用：

适用情况：

• 工具输出超过约 2000 个令牌
• 任务跨越多轮对话
• 多个 Agent 需要共享状态
• 技能或说明超出系统提示词的舒适长度
• 需要选择性查询日志或终端输出

避免情况：

• 任务在单轮对话中即可完成（不值得承担额外开销）
• 上下文可轻松容纳在窗口中（没有需要解决的问题）
• 延迟至关重要（文件 I/O 会带来明显延迟）
• 模型不具备文件系统工具能力

文件组织

按照便于 Agent 发现的方式组织文件，因为 Agent 会通过列出和读取目录名称来导航：

project/
  scratch/           # Temporary working files
    tool_outputs/    # Large tool results
    plans/           # Active plans and checklists
  memory/            # Persistent learned information
    preferences.yaml # User preferences
    patterns.md      # Learned patterns
  skills/            # Loadable skill definitions
  agents/            # Sub-agent workspaces

使用统一的命名规范，并在临时文件中包含时间戳或 ID，以便区分。

对于自主研究循环，将检索到的原始证据存储在使用它的运行目录下，例如 researcher/runs/<run-id>/sources/evidence/raw/。不要将原始研究内容留在仓库根目录；根目录下的产物难以审计，也容易在引用时缺少来源信息。

令牌核算

应用文件系统模式前后，衡量令牌的来源，因为未经衡量就优化会造成无谓的投入：

• 跟踪静态上下文与动态上下文的比例
• 监控卸载前后的工具输出大小
• 衡量动态加载的上下文实际被使用的频率

示例

示例 1：卸载工具输出

Input: Web search returns 8000 tokens
Before: 8000 tokens added to message history
After:
  - Write to scratch/search_results_001.txt
  - Return: "[Results in scratch/search_results_001.txt. Key finding: API rate limit is 1000 req/min]"
  - Agent greps file when needing specific details
Result: ~100 tokens in context, 8000 tokens accessible on demand

示例 2：动态加载技能

Input: User asks about database indexing
Static context: "database-optimization: Query tuning and indexing"
Agent action: read_file("skills/database-optimization/SKILL.md")
Result: Full skill loaded only when relevant

示例 3：将聊天历史作为文件引用

Trigger: Context window limit reached, summarization required
Action:
  1. Write full history to history/session_001.txt
  2. Generate summary for new context window
  3. Include reference: "Full history in history/session_001.txt"
Result: Agent can search history file to recover details lost in summarization

指南

1. 将大型输出写入文件；返回摘要和上下文引用
2. 将计划和状态存储在结构化文件中，以便重新读取
3. 使用子 Agent 文件工作区，而非消息链
4. 动态加载技能，不要将所有内容塞进系统提示词
5. 将终端和日志输出持久化为可搜索文件
6. 将 grep/glob 与语义搜索结合，实现全面发现
7. 使用清晰的命名来组织文件，便于 Agent 发现
8. 衡量令牌节省情况，验证文件系统模式是否有效
9. 实施临时文件清理，防止文件无限增长
10. 使用验证机制防护自我修改模式
11. 将原始证据与使用它的运行、评估和提案放在一起

注意事项

1. 暂存目录无限增长：Agent 会创建临时文件却不清理，最终耗尽磁盘空间，并使目录列表变得杂乱。实施保留策略（基于文件年龄或数量），并在会话边界执行清理。
2. 多 Agent 文件访问中的竞态条件：同时写入同一文件会悄无声息地破坏状态。为每个 Agent 设置独立目录，或使用仅追加文件，并在条目中添加 Agent 前缀。
3. 移动或重命名后文件引用过时：重构或重新组织文件后，Agent 仍持有前几轮中的路径，这些路径已不再有效。读取缓存路径前，务必验证文件是否存在；若检查失败，则使用 glob 重新查找。
4. Glob 模式误匹配：过于宽泛的模式（例如 **/*）会将无关文件纳入上下文，浪费令牌并使模型困惑。将 glob 限定到特定目录和扩展名。
5. 文件大小假设：读取文件前不检查大小，一次工具调用就可能将 100K+ 个令牌载入上下文。读取前检查文件大小；对于大型文件，使用按行范围读取。
6. 缺少文件存在性检查：Agent 假定文件在之前的轮次中存在，但文件可能已被删除或移动。读取前务必检查文件是否存在，并妥善处理文件缺失错误。
7. 暂存便笺格式漂移：多次写入后，由于格式约定逐渐失效，缺乏结构的暂存便笺会变得无法解析。从首次写入开始就定义并强制执行一种架构（YAML、JSON 或结构化 Markdown）。
8. 硬编码绝对路径：当仓库在不同位置检出或在容器中运行时，这些路径会失效。使用相对于项目根目录的路径，或动态解析路径。

集成

此技能负责基于文件的上下文存储和检索。相邻技能负责语义记忆、摘要和拓扑：

• context-optimization：当完整输出仍可检索时，文件系统卸载是实现观测屏蔽的一种方式。
• memory-systems：当基于文件的笔记已不足以满足需求，且需要语义、实体或时间检索时使用。
• multi-agent-patterns：子 Agent 文件工作区可实现上下文隔离和直接交接。
• context-compression：文件引用可作为摘要的锚点，并保留压缩上下文中省略的细节。
• tool-design：工具应为大型输出返回文件引用，并提供安全的读取和搜索操作。
• self-managed-context：卸载会使原始内容保留在实时窗口中；若要将其移除，需要模型自行编辑上下文。

参考资料

内部参考：

• 实现模式 - 阅读时机：实现暂存便笺、计划持久化或工具输出卸载，并且需要超出行内示例的具体代码时

本集合中的相关技能：

• context-optimization - 阅读时机：在文件系统卸载之外应用令牌缩减技术时
• memory-systems - 阅读时机：构建生命周期超出单次会话的持久化存储时
• multi-agent-patterns - 阅读时机：设计使用共享文件工作区的 Agent 协作时

外部资源：

• LangChain Deep Agents — 阅读时机：在 LangChain/LangGraph 流水线中实现基于文件系统的上下文模式时
• Cursor context discovery — 阅读时机：研究生产级 IDE 如何实现动态上下文加载时
• Anthropic Agent Skills specification — 阅读时机：构建利用文件系统渐进式披露的技能时

---

技能元数据

创建时间：2026-01-07 最后更新：2026-05-15 作者：Agent Skills for Context Engineering Contributors 版本：1.2.0