filesystem-context

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Filesystem-Based Context Engineering

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

The filesystem provides a single interface through which agents can flexibly store, retrieve, and update an effectively unlimited amount of context. This pattern addresses the fundamental constraint that context windows are limited while tasks often require more information than fits in a single window.

The core insight is that files enable dynamic context discovery: agents pull relevant context on demand rather than carrying everything in the context window. This contrasts with static context, which is always included regardless of relevance.

文件系统为Agent提供了一个统一接口，使其能够灵活存储、检索和更新几乎无限量的上下文。该模式解决了上下文窗口有限，但任务往往需要超出单个窗口容量的信息这一核心限制。

核心思路是通过文件实现动态上下文发现：Agent会根据需求提取相关上下文，而非将所有内容都携带在上下文窗口中。这与静态上下文形成对比，静态上下文无论是否相关都会被包含在内。

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

在以下场景中激活此技能：

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

Core Concepts

核心概念

Context engineering can fail in four predictable ways. First, when the context an agent needs is not in the total available context. Second, when retrieved context fails to encapsulate needed context. Third, when retrieved context far exceeds needed context, wasting tokens and degrading performance. Fourth, when agents cannot discover niche information buried in many files.

The filesystem addresses these failures by providing a persistent layer where agents write once and read selectively, offloading bulk content while preserving the ability to retrieve specific information through search tools.

上下文工程可能会出现四种可预见的失败情况。第一，Agent需要的上下文不在可用的总上下文范围内。第二，检索到的上下文无法涵盖所需信息。第三，检索到的上下文远超实际需求，浪费Token并降低性能。第四，Agent无法发现隐藏在大量文件中的小众信息。

文件系统通过提供一个持久化层解决了这些问题：Agent只需写入一次，之后可选择性读取，在卸载大量内容的同时，保留通过搜索工具检索特定信息的能力。

Detailed Topics

详细主题

The Static vs Dynamic Context Trade-off

静态与动态上下文的权衡

Static Context Static context is always included in the prompt: system instructions, tool definitions, and critical rules. Static context consumes tokens regardless of task relevance. As agents accumulate more capabilities (tools, skills, instructions), static context grows and crowds out space for dynamic information.

Dynamic Context Discovery Dynamic context is loaded on-demand when relevant to the current task. The agent receives minimal static pointers (names, descriptions, file paths) and uses search tools to load full content when needed.

Dynamic discovery is more token-efficient because only necessary data enters the context window. It can also improve response quality by reducing potentially confusing or contradictory information.

The trade-off: dynamic discovery requires the model to correctly identify when to load additional context. This works well with current frontier models but may fail with less capable models that do not recognize when they need more information.

静态上下文 静态上下文始终包含在提示词中：系统指令、工具定义和关键规则。无论任务是否相关，静态上下文都会消耗Token。随着Agent积累更多能力（工具、技能、指令），静态上下文会不断膨胀，挤占动态信息的空间。

动态上下文发现 动态上下文仅在与当前任务相关时才会按需加载。Agent会收到最小化的静态指针（名称、描述、文件路径），并在需要时使用搜索工具加载完整内容。

动态发现的Token效率更高，因为只有必要的数据会进入上下文窗口。它还能通过减少潜在的混淆或矛盾信息来提升响应质量。

权衡点：动态发现要求模型能够正确识别何时需要加载额外上下文。这在当前前沿模型上表现良好，但在能力较弱的模型上可能失效，因为这些模型无法识别自己何时需要更多信息。

Pattern 1: Filesystem as Scratch Pad

模式1：文件系统作为草稿本

The Problem Tool calls can return massive outputs. A web search may return 10k tokens of raw content. A database query may return hundreds of rows. If this content enters the message history, it remains for the entire conversation, inflating token costs and potentially degrading attention to more relevant information.

The Solution Write large tool outputs to files instead of returning them directly to the context. The agent then uses targeted retrieval (grep, line-specific reads) to extract only the relevant portions.

Implementation

python

def handle_tool_output(output: str, threshold: int = 2000) -> str:
    if len(output) < threshold:
        return output
    
    # Write to scratch pad
    file_path = f"scratch/{tool_name}_{timestamp}.txt"
    write_file(file_path, output)
    
    # Return reference instead of content
    key_summary = extract_summary(output, max_tokens=200)
    return f"[Output written to {file_path}. Summary: {key_summary}]"

The agent can then use

grep

to search for specific patterns or

read_file

with line ranges to retrieve targeted sections.

Benefits

Reduces token accumulation over long conversations
Preserves full output for later reference
Enables targeted retrieval instead of carrying everything

问题工具调用可能会返回大量输出。一次网页搜索可能返回8000Token的原始内容，数据库查询可能返回数百行数据。如果将这些内容添加到消息历史中，它们会在整个对话中保留，增加Token成本，还可能降低Agent对更相关信息的关注度。

解决方案 将大型工具输出写入文件，而非直接返回给上下文。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"[输出已写入 {file_path}。摘要：{key_summary}]"

Agent随后可以使用

grep

搜索特定模式，或使用带行范围的

read_file

检索目标段落。

优势

减少长对话中的Token累积
保留完整输出以供后续参考
支持针对性检索，无需携带所有内容

Pattern 2: Plan Persistence

模式2：计划持久化

The Problem Long-horizon tasks require agents to make plans and follow them. But as conversations extend, plans can fall out of attention or be lost to summarization. The agent loses track of what it was supposed to do.

The Solution Write plans to the filesystem. The agent can re-read its plan at any point, reminding itself of the current objective and progress. This is sometimes called "manipulating attention through recitation."

Implementation Store plans in structured format:

yaml

undefined

问题长周期任务要求Agent制定计划并执行。但随着对话延长，计划可能会被遗忘或在摘要中丢失，Agent会忘记自己应该做什么。

解决方案 将计划写入文件系统。Agent可以随时重新读取计划，提醒自己当前目标和进度。这有时被称为“通过复述调整注意力”。

实现代码 以结构化格式存储计划：

yaml

undefined

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


The agent reads this file at the start of each turn or when it needs to re-orient.

objective: "重构认证模块" status: in_progress steps:

id: 1 description: "审计当前认证端点" status: completed
id: 2 description: "设计新的令牌验证流程" status: in_progress
id: 3 description: "实现并测试变更" status: pending


Agent会在每个对话轮次开始时，或需要重新定位时读取此文件。

Pattern 3: Sub-Agent Communication via Filesystem

模式3：基于文件系统的子Agent通信

The Problem In multi-agent systems, sub-agents typically report findings to a coordinator agent through message passing. This creates a "game of telephone" where information degrades through summarization at each hop.

The Solution Sub-agents write their findings directly to the filesystem. The coordinator reads these files directly, bypassing intermediate message passing. This preserves fidelity and reduces context accumulation in the coordinator.

Implementation

workspace/
  agents/
    research_agent/
      findings.md        # Research agent writes here
      sources.jsonl      # Source tracking
    code_agent/
      changes.md         # Code agent writes here
      test_results.txt   # Test output
  coordinator/
    synthesis.md         # Coordinator reads agent outputs, writes synthesis

Each agent operates in relative isolation but shares state through the filesystem.

问题在多Agent系统中，子Agent通常通过消息传递向协调Agent报告结果。这会形成“传话游戏”，信息在每一次传递的摘要过程中都会失真。

解决方案 子Agent直接将发现结果写入文件系统。协调Agent直接读取这些文件，绕过中间消息传递环节。这能保留信息的准确性，减少协调Agent的上下文累积。

实现示例

workspace/
  agents/
    research_agent/
      findings.md        # 研究Agent写入此处
      sources.jsonl      # 来源追踪
    code_agent/
      changes.md         # 代码Agent写入此处
      test_results.txt   # 测试输出
  coordinator/
    synthesis.md         # 协调Agent读取Agent输出，写入综合结果

每个Agent相对独立运行，但通过文件系统共享状态。

Pattern 4: Dynamic Skill Loading

模式4：动态技能加载

The Problem Agents may have many skills or instruction sets, but most are irrelevant to any given task. Stuffing all instructions into the system prompt wastes tokens and can confuse the model with contradictory or irrelevant guidance.

The Solution Store skills as files. Include only skill names and brief descriptions in static context. The agent uses search tools to load relevant skill content when the task requires it.

Implementation Static context includes:

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

Agent loads

skills/database-optimization/SKILL.md

only when working on database tasks.

问题 Agent可能拥有许多技能或指令集，但大多数与特定任务无关。将所有指令都塞进系统提示词会浪费Token，还可能让模型因矛盾或无关的指导而产生混淆。

解决方案 将技能存储为文件。仅在静态上下文中包含技能名称和简短描述。Agent会在任务需要时使用搜索工具加载相关技能内容。

实现示例 静态上下文包含：

可用技能（相关时使用read_file加载）：
- database-optimization: 查询调优和索引策略
- api-design: REST/GraphQL最佳实践
- testing-strategies: 单元测试、集成测试和端到端测试模式

仅当处理数据库任务时，Agent才会加载

skills/database-optimization/SKILL.md

。

Pattern 5: Terminal and Log Persistence

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

The Problem Terminal output from long-running processes accumulates rapidly. Copying and pasting output into agent input is manual and inefficient.

The Solution Sync terminal output to files automatically. The agent can then grep for relevant sections (error messages, specific commands) without loading entire terminal histories.

Implementation Terminal sessions are persisted as files:

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

Agents query with targeted grep:

bash

grep -A 5 "error" terminals/1.txt

问题长时间运行的进程的终端输出会快速累积。将输出复制粘贴到Agent输入中是手动且低效的操作。

解决方案 自动将终端输出同步到文件。Agent随后可以grep相关段落（错误消息、特定命令），无需加载整个终端历史。

实现示例 终端会话会被持久化为文件：

terminals/
  1.txt    # 终端会话1的输出
  2.txt    # 终端会话2的输出

Agent使用针对性的grep查询：

bash

grep -A 5 "error" terminals/1.txt

Pattern 6: Learning Through Self-Modification

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

The Problem Agents often lack context that users provide implicitly or explicitly during interactions. Traditionally, this requires manual system prompt updates between sessions.

The Solution Agents write learned information to their own instruction files. Subsequent sessions load these files, incorporating learned context automatically.

Implementation After user provides preference:

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)

Subsequent sessions include a step to load user preferences if the file exists.

Caution This pattern is still emerging. Self-modification requires careful guardrails to prevent agents from accumulating incorrect or contradictory instructions over time.

问题 Agent通常缺少用户在交互过程中隐式或显式提供的上下文。传统上，这需要在会话之间手动更新系统提示词。

解决方案 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)

后续会话会包含一个步骤：如果偏好文件存在，则加载用户偏好。

注意事项 该模式仍在发展中。自我修改需要谨慎的防护措施，以防止Agent随着时间推移累积错误或矛盾的指令。

Filesystem Search Techniques

文件系统搜索技术

Models are specifically trained to understand filesystem traversal. The combination of

ls

glob

grep

, and

read_file

with line ranges provides powerful context discovery:

```
ls
```
/
```
list_dir
```
: Discover directory structure
```
glob
```
: Find files matching patterns (e.g.,
```
**/*.py
```
)
```
grep
```
: Search file contents for patterns, returns matching lines
```
read_file
```
with ranges: Read specific line ranges without loading entire files

This combination often outperforms semantic search for technical content (code, API docs) where semantic meaning is sparse but structural patterns are clear.

Semantic search and filesystem search work well together: semantic search for conceptual queries, filesystem search for structural and exact-match queries.

模型经过专门训练，能够理解文件系统遍历。

ls

、

glob

、

grep

和带行范围的

read_file

组合提供了强大的上下文发现能力：

```
ls
```
/
```
list_dir
```
: 发现目录结构
```
glob
```
: 查找匹配模式的文件（例如：
```
**/*.py
```
）
```
grep
```
: 搜索文件内容中的模式，返回匹配行
带范围的
```
read_file
```
: 读取特定行范围，无需加载整个文件

对于技术内容（代码、API文档），这种组合的表现通常优于语义搜索，因为此类内容的语义信息稀疏，但结构模式清晰。

语义搜索和文件系统搜索可以很好地结合使用：语义搜索用于概念查询，文件系统搜索用于结构和精确匹配查询。

Practical Guidance

实践指导

When to Use Filesystem Context

何时使用文件系统上下文

Use filesystem patterns when:

Tool outputs exceed 2000 tokens
Tasks span multiple conversation turns
Multiple agents need to share state
Skills or instructions exceed what fits comfortably in system prompt
Logs or terminal output need selective querying

Avoid filesystem patterns when:

Tasks complete in single turns
Context fits comfortably in window
Latency is critical (file I/O adds overhead)
Simple model incapable of filesystem tool use

在以下场景使用文件系统模式：

工具输出超过2000Token
任务跨越多个对话轮次
多个Agent需要共享状态
技能或指令超出系统提示词的舒适容量
需要选择性查询日志或终端输出

避免使用文件系统模式的场景：

任务在单个轮次内完成
上下文能够舒适地容纳在窗口中
延迟要求严格（文件I/O会增加开销）
简单模型无法使用文件系统工具

File Organization

文件组织

Structure files for discoverability:

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. Include timestamps or IDs in scratch files for disambiguation.

为可发现性设计文件结构：

project/
  scratch/           # 临时工作文件
    tool_outputs/    # 大型工具结果
    plans/           # 活跃计划和检查清单
  memory/            # 持久化学习信息
    preferences.yaml # 用户偏好
    patterns.md      # 已学习的模式
  skills/            # 可加载的技能定义
  agents/            # 子Agent工作区

使用一致的命名约定。在草稿文件中包含时间戳或ID以消除歧义。

Token Accounting

Token统计

Track where tokens originate:

Measure static vs dynamic context ratio
Monitor tool output sizes before and after offloading
Track how often dynamic context is actually loaded

Optimize based on measurements, not assumptions.

追踪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：工具输出卸载

输入：网页搜索返回8000Token
优化前：8000Token被添加到消息历史
优化后：
  - 写入到scratch/search_results_001.txt
  - 返回："[结果已保存到scratch/search_results_001.txt。关键发现：API速率限制为1000次请求/分钟]"
  - Agent在需要特定细节时grep该文件
结果：上下文仅占用约100Token，8000Token可按需访问

示例2：动态技能加载

输入：用户询问数据库索引相关问题
静态上下文："database-optimization: 查询调优和索引策略"
Agent操作：read_file("skills/database-optimization/SKILL.md")
结果：仅在相关时加载完整技能

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

触发条件：达到上下文窗口限制，需要摘要
操作：
  1. 将完整历史写入history/session_001.txt
  2. 为新上下文窗口生成摘要
  3. 包含引用："完整历史记录在history/session_001.txt"
结果：Agent可以搜索历史文件，恢复摘要中丢失的细节

Guidelines

指导原则

Write large outputs to files; return summaries and references to context
Store plans and state in structured files for re-reading
Use sub-agent file workspaces instead of message chains
Load skills dynamically rather than stuffing all into system prompt
Persist terminal and log output as searchable files
Combine grep/glob with semantic search for comprehensive discovery
Organize files for agent discoverability with clear naming
Measure token savings to validate filesystem patterns are effective
Implement cleanup for scratch files to prevent unbounded growth
Guard self-modification patterns with validation

将大型输出写入文件；返回摘要和上下文引用
将计划和状态存储在结构化文件中，以便重新读取
使用子Agent文件工作区替代消息链
动态加载技能，而非将所有技能塞进系统提示词
将终端和日志输出持久化为可搜索的文件
结合grep/glob与语义搜索实现全面发现
为Agent的可发现性组织文件，使用清晰的命名
测量Token节省量，验证文件系统模式的有效性
实现草稿文件清理机制，防止无限制增长
为自我修改模式添加验证防护措施

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 - Detailed pattern implementations

Related skills in this collection:

context-optimization - Token reduction techniques
memory-systems - Persistent storage patterns
multi-agent-patterns - Agent coordination

External resources:

LangChain Deep Agents: How agents can use filesystems for context engineering
Cursor: Dynamic context discovery patterns
Anthropic: Agent Skills specification

内部参考：

实现模式 - 详细的模式实现

本集合中的相关技能：

context-optimization - Token减少技术
memory-systems - 持久化存储模式
multi-agent-patterns - Agent协调

外部资源：

LangChain Deep Agents: 如何让Agent使用文件系统进行上下文工程
Cursor: 动态上下文发现模式
Anthropic: Agent技能规范

Skill Metadata

技能元数据

Created: 2026-01-07 Last Updated: 2026-01-07 Author: Agent Skills for Context Engineering Contributors Version: 1.0.0

创建时间: 2026-01-07 最后更新时间: 2026-01-07 作者: 上下文工程Agent技能贡献者版本: 1.0.0