Back to Details

filesystem-context

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Filesystem-Based Context Engineering

基于文件系统的Context Engineering

Use the filesystem as the primary overflow layer for agent context because context windows are limited while tasks often require more information than fits in a single window. Files let agents store, retrieve, and update an effectively unlimited amount of context through a single interface.
Prefer dynamic context discovery -- pulling relevant context on demand -- over static inclusion, because static context consumes tokens regardless of relevance and crowds out space for task-specific information.
由于context window的容量有限，而任务往往需要超出单个窗口承载能力的信息，因此可将文件系统作为Agent上下文的主要溢出层。文件能让Agent通过单一接口存储、检索和更新几乎无限量的上下文。
优先采用动态上下文发现——按需提取相关上下文——而非静态嵌入，因为静态上下文无论是否相关都会消耗Token，挤占任务特定信息的空间。

When to Activate

激活场景

Activate this skill when:
  • Tool outputs are bloating the context window
  • Agents need to persist state across long trajectories
  • Sub-agents must share information without direct message passing
  • Tasks require more context than fits in the window
  • Building agents that learn and update their own instructions
  • Implementing scratch pads for intermediate results
  • Terminal outputs or logs need to be accessible to agents
在以下场景中激活此技能：
  • 工具输出导致context window膨胀
  • Agent需要在长轨迹任务中持久化状态
  • 子Agent无需直接消息传递即可共享信息
  • 任务所需上下文超出context window的承载能力
  • 构建可自主学习并更新自身指令的Agent
  • 为中间结果实现暂存区
  • Agent需要访问终端输出或日志

Core Concepts

核心概念

Diagnose context failures against these four modes, because each requires a different filesystem remedy:
  1. Missing context -- needed information is absent from the total available context. Fix by persisting tool outputs and intermediate results to files so nothing is lost.
  2. Under-retrieved context -- retrieved content fails to encapsulate what the agent needs. Fix by structuring files for targeted retrieval (grep-friendly formats, clear section headers).
  3. Over-retrieved context -- retrieved content far exceeds what is needed, wasting tokens and degrading attention. Fix by offloading bulk content to files and returning compact references.
  4. Buried context -- niche information is hidden across many files. Fix by combining glob and grep for structural search alongside semantic search for conceptual queries.
Use the filesystem as the persistent layer that addresses all four: write once, store durably, retrieve selectively.
针对以下四种上下文失效模式进行诊断，每种模式需要不同的文件系统解决方案：
  1. 缺失上下文——所需信息在全部可用上下文中不存在。解决方法是将工具输出和中间结果持久化到文件中，确保无信息丢失。
  2. 检索不足——检索到的内容无法满足Agent的需求。解决方法是对文件进行结构化处理以支持定向检索（如便于grep的格式、清晰的章节标题）。
  3. 过度检索——检索到的内容远超实际需求，浪费Token并降低注意力效率。解决方法是将大量内容卸载到文件中，仅返回简洁的引用。
  4. 上下文被淹没——特定领域信息分散在多个文件中难以查找。解决方法是结合glob和grep进行结构化搜索，同时配合语义搜索处理概念性查询。
将文件系统作为持久层来应对以上所有问题：一次写入，持久存储，选择性检索。

Detailed Topics

详细主题

The Static vs Dynamic Context Trade-off

静态与动态上下文的权衡

Treat static context (system instructions, tool definitions, critical rules) as expensive real estate -- it consumes tokens on every turn regardless of relevance. As agents accumulate capabilities, static context grows and crowds out dynamic information.
Use dynamic context discovery instead: include only minimal static pointers (names, one-line descriptions, file paths) and load full content with search tools when relevant. This is more token-efficient and often improves response quality by reducing contradictory or irrelevant information in the window.
Accept the trade-off: dynamic discovery requires the model to recognize when it needs more context. Current frontier models handle this well, but less capable models may fail to trigger loads. When in doubt, err toward including critical safety or correctness constraints statically.
将静态上下文（系统指令、工具定义、关键规则）视为昂贵的资源——它在每一轮交互中都会消耗Token，无论是否相关。随着Agent功能的积累，静态上下文会不断膨胀，挤占动态信息的空间。
改用动态上下文发现：仅保留最小化的静态指针（名称、单行描述、文件路径），当需要时再通过搜索工具加载完整内容。这种方式更节省Token，且通过减少窗口中矛盾或无关的信息，通常能提升响应质量。
需接受这一权衡：动态上下文发现要求模型能够识别何时需要更多上下文。当前前沿模型能很好地处理这一点，但能力较弱的模型可能无法触发加载操作。如有疑问，应优先将关键的安全或正确性约束静态嵌入。

Pattern 1: Filesystem as Scratch Pad

模式1：文件系统作为暂存区

Redirect large tool outputs to files instead of returning them directly to context, because a single web search or database query can dump thousands of tokens into message history where they persist for the entire conversation.
Write the output to a scratch file, extract a compact summary, and return a file reference. The agent then uses targeted retrieval (grep for patterns, read with line ranges) to access only what it needs.
python
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}]"
Use grep to search the offloaded file and read_file with line ranges to retrieve targeted sections, because this preserves full output for later reference while keeping only ~100 tokens in the active context.
将大型工具输出重定向到文件，而非直接返回至上下文，因为单次网页搜索或数据库查询可能会向消息历史中注入数千个Token，并在整个对话过程中持续存在。
将输出写入暂存文件，提取简洁摘要，然后返回文件引用。Agent随后使用定向检索（如grep查找模式、按行范围读取）仅访问所需内容。
python
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。

Pattern 2: Plan Persistence

模式2：计划持久化

Write plans to the filesystem because long-horizon tasks lose coherence when plans fall out of attention or get summarized away. The agent re-reads its plan at any point, restoring awareness of the objective and progress.
Store plans in structured format so they are both human-readable and machine-parseable:
yaml
undefined
将计划写入文件系统，因为长周期任务会因计划超出注意力范围或被摘要处理而失去连贯性。Agent可随时重新读取计划，恢复对目标和进度的认知。
采用结构化格式存储计划，使其同时具备人类可读性和机器可解析性：
yaml
undefined

scratch/current_plan.yaml

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

Re-read the plan at the start of each turn or after any context refresh to re-orient, because this acts as "manipulating attention through recitation."
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

在每轮交互开始时或上下文刷新后重新读取计划以重新定位，这相当于“通过复述来引导注意力”。

Pattern 3: Sub-Agent Communication via Filesystem

模式3：通过文件系统实现子Agent通信

Route sub-agent findings through the filesystem instead of message passing, because multi-hop message chains degrade information through summarization at each hop ("game of telephone").
Have each sub-agent write directly to its own workspace directory. The coordinator reads these files directly, preserving full fidelity:
workspace/
  agents/
    research_agent/
      findings.md
      sources.jsonl
    code_agent/
      changes.md
      test_results.txt
  coordinator/
    synthesis.md
Enforce per-agent directory isolation to prevent write conflicts and maintain clear ownership of each output artifact.
通过文件系统传递子Agent的发现结果，而非使用消息传递，因为多跳消息链会在每一跳的摘要处理中导致信息质量下降（类似“传话游戏”）。
让每个子Agent直接写入自己的工作区目录。协调器直接读取这些文件，确保信息完整保真：
workspace/
  agents/
    research_agent/
      findings.md
      sources.jsonl
    code_agent/
      changes.md
      test_results.txt
  coordinator/
    synthesis.md
实施子Agent目录隔离，防止写入冲突，并明确每个输出工件的归属。

Pattern 4: Dynamic Skill Loading

模式4：动态技能加载

Store skills as files and include only skill names with brief descriptions in static context, because stuffing all instructions into the system prompt wastes tokens and can confuse the model with contradictory guidance.
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
Load the full skill file (e.g., 
skills/database-optimization/SKILL.md
) only when the current task requires it. This converts O(n) static token cost into O(1) per task.
将技能存储为文件，仅在静态上下文中包含技能名称和简短描述，因为将所有指令塞入系统提示会浪费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)的成本。

Pattern 5: Terminal and Log Persistence

模式5：终端与日志持久化

Persist terminal output to files automatically and use grep for selective retrieval, because terminal output from long-running processes accumulates rapidly and manual copy-paste is error-prone.
terminals/
  1.txt    # Terminal session 1 output
  2.txt    # Terminal session 2 output
Query with targeted grep (
grep -A 5 "error" terminals/1.txt
) instead of loading entire terminal histories into context.
自动将终端输出持久化到文件，并使用grep进行选择性检索，因为长期运行的进程产生的终端输出会快速累积，手动复制粘贴容易出错。
terminals/
  1.txt    # Terminal session 1 output
  2.txt    # Terminal session 2 output
使用定向grep查询（如
grep -A 5 "error" terminals/1.txt
），而非将整个终端历史加载到上下文中。

Pattern 6: Learning Through Self-Modification

模式6：通过自我修改实现学习

Have agents write learned preferences and patterns to their own instruction files so subsequent sessions load this context automatically, instead of requiring manual system prompt updates.
python
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)
Guard this pattern with validation because self-modification can accumulate incorrect or contradictory instructions over time. Treat it as experimental -- review persisted preferences periodically.
让Agent将学到的偏好和模式写入自己的指令文件，以便后续会话自动加载这些上下文，无需手动更新系统提示。
python
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)
需为该模式添加验证机制，因为自我修改可能会随着时间积累错误或矛盾的指令。将其视为实验性功能——定期检查持久化的偏好设置。

Filesystem Search Techniques

文件系统搜索技术

Combine 
ls
/
list_dir
, 
glob
, 
grep
, and 
read_file
with line ranges for context discovery, because models are specifically trained on filesystem traversal and this combination often outperforms semantic search for technical content where structural patterns are clear.
  • ls
    / 
    list_dir
    : Discover directory structure
  • glob
    : Find files matching patterns (e.g., 
    **/*.py
    )
  • grep
    : Search file contents, returns matching lines with context
  • read_file
    with ranges: Read specific sections without loading entire files
Use filesystem search for structural and exact-match queries, and semantic search for conceptual queries. Combine both for comprehensive discovery.
结合
ls
/
list_dir
、
glob
、
grep
和带行范围的
read_file
进行上下文发现，因为模型经过专门的文件系统遍历训练，对于结构模式清晰的技术内容，这种组合的表现往往优于语义搜索。
  • ls
    / 
    list_dir
    ：发现目录结构
  • glob
    ：查找匹配模式的文件（例如
    **/*.py
    ）
  • grep
    ：搜索文件内容，返回匹配行及上下文
  • read_file
    （带行范围）：读取特定章节，无需加载整个文件
对结构化和精确匹配查询使用文件系统搜索，对概念性查询使用语义搜索。结合两者实现全面的上下文发现。

Practical Guidance

实践指南

When to Use Filesystem Context

何时使用文件系统上下文

Apply filesystem patterns when the situation matches these criteria, because they add I/O overhead that is only justified by token savings or persistence needs:
Use when:
  • Tool outputs exceed ~2000 tokens
  • Tasks span multiple conversation turns
  • Multiple agents need shared state
  • Skills or instructions exceed comfortable system prompt size
  • Logs or terminal output need selective querying
Avoid when:
  • Tasks complete in single turns (overhead not justified)
  • Context fits comfortably in window (no problem to solve)
  • Latency is critical (file I/O adds measurable delay)
  • Model lacks filesystem tool capabilities
当场景符合以下条件时应用文件系统模式，因为它们会带来I/O开销，只有在能节省Token或满足持久化需求时才具有合理性：
适用场景：
  • 工具输出超过约2000个Token
  • 任务跨越多轮对话
  • 多个Agent需要共享状态
  • 技能或指令超出系统提示的合理容量
  • 需要对日志或终端输出进行选择性查询
避免场景：
  • 任务在单轮对话中完成（开销得不偿失）
  • 上下文可轻松容纳在window中（无问题需要解决）
  • 延迟要求严格（文件I/O会带来可测量的延迟）
  • 模型不具备文件系统工具能力

File Organization

文件组织

Structure files for agent discoverability, because agents navigate by listing and reading directory names:
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
Use consistent naming conventions and include timestamps or IDs in scratch files for disambiguation.
为便于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以避免歧义。

Token Accounting

Token核算

Measure where tokens originate before and after applying filesystem patterns, because optimizing without measurement leads to wasted effort:
  • Track static vs dynamic context ratio
  • Monitor tool output sizes before and after offloading
  • Measure how often dynamically-loaded context is actually used
在应用文件系统模式前后测量Token的来源，因为无依据的优化只会白费力气：
  • 跟踪静态与动态上下文的比例
  • 监控卸载前后的工具输出大小
  • 测量动态加载的上下文实际被使用的频率

Examples

示例

Example 1: Tool Output Offloading
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
Example 2: Dynamic Skill Loading
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
Example 3: Chat History as File Reference
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：工具输出卸载
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

Guidelines

准则

  1. Write large outputs to files; return summaries and references to context
  2. Store plans and state in structured files for re-reading
  3. Use sub-agent file workspaces instead of message chains
  4. Load skills dynamically rather than stuffing all into system prompt
  5. Persist terminal and log output as searchable files
  6. Combine grep/glob with semantic search for comprehensive discovery
  7. Organize files for agent discoverability with clear naming
  8. Measure token savings to validate filesystem patterns are effective
  9. Implement cleanup for scratch files to prevent unbounded growth
  10. Guard self-modification patterns with validation
  1. 将大型输出写入文件；向上下文返回摘要和引用
  2. 将计划和状态存储在结构化文件中以便重新读取
  3. 使用子Agent文件工作区而非消息链
  4. 动态加载技能，而非将所有技能塞入系统提示
  5. 将终端和日志输出持久化为可搜索的文件
  6. 结合grep/glob与语义搜索实现全面发现
  7. 以清晰的命名组织文件，便于Agent发现
  8. 测量Token节省量以验证文件系统模式的有效性
  9. 实现暂存文件清理机制，防止无限制增长
  10. 为自我修改模式添加验证机制

Gotchas

注意事项

  1. Scratch directory unbounded growth: Agents create temp files without cleanup, eventually consuming disk and making directory listings noisy. Implement a retention policy (age-based or count-based) and run cleanup at session boundaries.
  2. Race conditions in multi-agent file access: Concurrent writes to the same file corrupt state silently. Enforce per-agent directory isolation or use append-only files with agent-prefixed entries.
  3. Stale file references after moves/renames: Agents hold paths from prior turns that no longer exist after refactors or file reorganization. Always verify file existence before reading a cached path; re-discover with glob if the check fails.
  4. Glob pattern false matches: Overly broad patterns (e.g., 
    **/*
    ) pull irrelevant files into context, wasting tokens and confusing the model. Scope globs to specific directories and extensions.
  5. File size assumptions: Reading a file without checking size can dump 100K+ tokens into context in a single tool call. Check file size before reading; use line-range reads for large files.
  6. Missing file existence checks: Agents assume files exist from prior turns, but they may have been deleted or moved. Always guard reads with existence checks and handle missing-file errors gracefully.
  7. Scratch pad format drift: Unstructured scratch pads become unparseable after many writes because format conventions erode over successive appends. Define and enforce a schema (YAML, JSON, or structured markdown) from the first write.
  8. Hardcoded absolute paths: Break when repositories are checked out at different locations or when running in containers. Use relative paths from the project root or resolve paths dynamically.
  1. 暂存目录无限制增长：Agent创建临时文件但不清理，最终会占用磁盘空间并使目录列表变得杂乱。实施保留策略（基于时间或数量），并在会话边界执行清理。
  2. 多Agent文件访问的竞态条件：对同一文件的并发写入会静默破坏状态。实施子Agent目录隔离，或使用带有Agent前缀条目的追加式文件。
  3. 文件移动/重命名后引用失效：Agent保留的前几轮交互中的路径在重构或文件重组后可能不再存在。读取缓存路径前始终验证文件是否存在；如果检查失败，使用glob重新发现。
  4. Glob模式误匹配：过于宽泛的模式（如
    **/*
    ）会将无关文件拉入上下文，浪费Token并混淆模型。将glob限定在特定目录和扩展名。
  5. 文件大小假设：不检查文件大小就读取可能会在单次工具调用中向上下文注入10万+个Token。读取前检查文件大小；对大文件使用行范围读取。
  6. 缺少文件存在性检查：Agent假设前几轮交互中的文件仍然存在，但它们可能已被删除或移动。读取前始终检查文件是否存在，并优雅处理文件不存在的错误。
  7. 暂存区格式漂移：无结构的暂存区在多次写入后会变得无法解析，因为格式约定会在连续追加中逐渐失效。从第一次写入开始就定义并强制使用Schema（YAML、JSON或结构化Markdown）。
  8. 硬编码绝对路径：在不同位置检出仓库或在容器中运行时会失效。使用相对于项目根目录的路径，或动态解析路径。

Integration

集成

This skill connects to:
  • context-optimization - Filesystem offloading is a form of observation masking
  • memory-systems - Filesystem-as-memory is a simple memory layer
  • multi-agent-patterns - Sub-agent file workspaces enable isolation
  • context-compression - File references enable lossless "compression"
  • tool-design - Tools should return file references for large outputs
此技能与以下内容相关：
  • context-optimization - 文件系统卸载是观察掩码的一种形式
  • memory-systems - 文件系统作为内存是一种简单的内存层
  • multi-agent-patterns - 子Agent文件工作区支持隔离
  • context-compression - 文件引用实现无损“压缩”
  • tool-design - 工具应为大型输出返回文件引用

References

参考资料

Internal reference:
  • Implementation Patterns - Read when: implementing scratch pad, plan persistence, or tool output offloading and need concrete code beyond the inline examples
Related skills in this collection:
  • context-optimization - Read when: applying token reduction techniques alongside filesystem offloading
  • memory-systems - Read when: building persistent storage that outlasts a single session
  • multi-agent-patterns - Read when: designing agent coordination with shared file workspaces
External resources:
  • LangChain Deep Agents — Read when: implementing filesystem-based context patterns in LangChain/LangGraph pipelines
  • Cursor context discovery — Read when: studying how production IDEs implement dynamic context loading
  • Anthropic Agent Skills specification — Read when: building skills that leverage filesystem progressive disclosure
内部参考：
  • Implementation Patterns - 当实现暂存区、计划持久化或工具输出卸载，并需要除内联示例之外的具体代码时阅读
本集合中的相关技能：
  • context-optimization - 当结合文件系统卸载应用Token减少技术时阅读
  • memory-systems - 当构建跨会话持久化存储时阅读
  • multi-agent-patterns - 当设计带有共享文件工作区的Agent协调机制时阅读
外部资源：
  • LangChain Deep Agents — 当在LangChain/LangGraph管道中实现基于文件系统的上下文模式时阅读
  • Cursor context discovery — 当研究生产级IDE如何实现动态上下文加载时阅读
  • Anthropic Agent Skills specification — 当构建利用文件系统渐进式披露的技能时阅读

Skill Metadata

技能元数据

Created: 2026-01-07 Last Updated: 2026-03-17 Author: Agent Skills for Context Engineering Contributors Version: 1.1.0
创建时间：2026-01-07 最后更新：2026-03-17 作者：Agent Skills for Context Engineering Contributors 版本：1.1.0