---

name: filesystem-context description: 用于基于文件的上下文管理、动态上下文发现和减少上下文窗口膨胀。将上下文卸载到文件中以实现按需加载。 risk: unknown source: community

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

文件系统提供了一个统一接口，智能体可以通过它灵活地存储、检索和更新几乎无限量的上下文。这种模式解决了一个根本性约束：上下文窗口有限，而任务通常需要的信息量超出单个窗口的容量。

核心洞察是文件实现了动态上下文发现：智能体按需拉取相关上下文，而不是在上下文窗口中携带所有内容。这与静态上下文形成对比——静态上下文无论是否相关都始终被包含。

何时使用

在以下情况下激活此技能：

• 工具输出正在膨胀上下文窗口
• 智能体需要在长轨迹中持久化状态
• 子智能体必须在没有直接消息传递的情况下共享信息
• 任务需要的上下文超出窗口容量
• 构建能够学习和更新自身指令的智能体
• 实现中间结果的暂存区
• 终端输出或日志需要对智能体可访问

核心概念

上下文工程可能以四种可预测的方式失败。第一，当智能体需要的上下文不在总可用上下文中。第二，当检索到的上下文未能封装所需上下文。第三，当检索到的上下文远超所需上下文，浪费令牌并降低性能。第四，当智能体无法发现埋藏在众多文件中的小众信息。

文件系统通过提供持久层来解决这些失败——智能体写入一次并选择性读取，卸载大量内容的同时保留通过搜索工具检索特定信息的能力。

详细主题

静态与动态上下文的权衡

静态上下文 静态上下文始终包含在提示中：系统指令、工具定义和关键规则。静态上下文无论任务相关性如何都消耗令牌。随着智能体积累更多能力（工具、技能、指令），静态上下文增长并挤占动态信息的空间。

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

动态发现更节省令牌，因为只有必要的数据进入上下文窗口。它还可以通过减少可能令人困惑或矛盾的信息来提高响应质量。

权衡：动态发现要求模型正确识别何时需要加载额外上下文。这在当前前沿模型中效果良好，但在能力较弱的模型中可能失败——它们无法识别何时需要更多信息。

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

问题 工具调用可能返回大量输出。网络搜索可能返回 10k 令牌的原始内容。数据库查询可能返回数百行。如果这些内容进入消息历史，它将在整个对话中保留，增加令牌成本并可能降低对更相关信息的注意力。

解决方案 将大型工具输出写入文件，而不是直接返回到上下文。然后智能体使用定向检索（grep、按行读取）仅提取相关部分。

实现

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}]"

智能体随后可以使用 grep 搜索特定模式，或使用 read_file 配合行范围来检索目标部分。

优势

• 减少长对话中的令牌累积
• 保留完整输出以供后续参考
• 实现定向检索而非携带所有内容

模式 2：计划持久化

问题 长期任务要求智能体制定计划并遵循它们。但随着对话延长，计划可能脱离注意力或因摘要化而丢失。智能体失去了对其应该做什么的追踪。

解决方案 将计划写入文件系统。智能体可以在任何时候重新读取其计划，提醒自己当前目标和进度。这有时被称为"通过复述操纵注意力"。

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

# scratch/current_plan.yaml
objective: "Refactor authentication module"
status: in_progress
steps:
  - id: 1
    description: "Audit current auth endpoints"
    status: completed