# Filesystem Context > 用于基于文件的上下文管理、动态上下文发现，减少上下文窗口膨胀。将上下文卸载到文件中以实现即时加载。触发词：文件系统上下文、scratch pad、context 卸载、动态上下文、长期规划、跨 agent 通信。 - Skill: `kscz0000/filesystem-context` (Agent Skill) - Install (CLI): `npx skillmds@latest add kscz0000/filesystem-context` - Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/filesystem-context/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: kscz0000 (https://skillmd.com/u/kscz0000) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/kscz0000/filesystem-context --- # 基于文件系统的上下文工程 文件系统提供了一个统一接口，代理可通过它灵活地存储、检索和更新近乎无限量的上下文。此模式应对了"上下文窗口有限而任务通常需要超出单个窗口容纳的信息"这一根本约束。 核心洞见是：**文件支持动态上下文发现**——代理按需拉取相关上下文，而非在上下文窗口中携带所有内容。这与"无论相关性如何始终包含"的静态上下文形成对比。 ## 何时使用 在以下情况激活本技能： - 工具输出正在膨胀上下文窗口 - 代理需要在长轨迹中持久化状态 - 子代理必须共享信息而无需直接消息传递 - 任务需要的上下文超出窗口容量 - 构建能学习并更新自己指令的代理 - 为中间结果实现草稿区 - 终端输出或日志需要被代理访问 ## 核心概念 上下文工程会以四种可预测方式失败。第一，当代理所需上下文不在总可用上下文中时。第二，当检索到的上下文未能封装所需内容时。第三，当检索到的上下文远超所需，浪费 token 并降低性能。第四，当代理无法发现埋在许多文件中的细分信息时。 文件系统通过提供持久层解决了这些失败：代理写入一次、按需读取，卸载大体量内容的同时保留通过搜索工具检索特定信息的能力。 ## 详细主题 ### 静态 vs 动态上下文的权衡 **静态上下文** 始终包含在 prompt 中：系统指令、工具定义和关键规则。静态上下文无论任务相关性都会消耗 token。随着代理累积更多能力（工具、技能、指令），静态上下文增长并挤占动态信息的空间。 **动态上下文发现** 在相关时按需加载。代理接收最少的静态指针（名称、描述、文件路径），使用搜索工具在需要时加载完整内容。 动态发现更节省 token，因为只有必要的数据进入上下文窗口。它还可以通过减少可能令人困惑或矛盾的信息来提升响应质量。 权衡：动态发现要求模型正确识别何时加载额外上下文。这在当前前沿模型上效果良好，但可能在能力较弱的模型上失败，因为它们无法识别何时需要更多信息。 ### 模式 1：文件系统作为草稿区 **问题** 工具调用可能返回海量输出。一次网页搜索可能返回 10k token 的原始内容。一次数据库查询可能返回数百行。如果此内容进入消息历史，它将持续存在于整个对话，推高 token 成本并可能降低对更相关信息的注意力。 **解决方案** 将大型工具输出写入文件，而非直接返回到上下文。代理然后使用定向检索（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` 检索目标章节。 **优势** - 减少长对话中 token 累积 - 保留完整输出供后续参考 - 支持定向检索而非携带一切 ### 模式 2：计划持久化 **问题** 长时域任务要求代理制定计划并遵循。但随着对话延长，计划可能从注意力中消失或在摘要中丢失。代理失去对原定任务的追踪。 **解决方案** 将计划写入文件系统。代理可在任何时刻重读其计划，提醒自己当前目标和进度。这有时称为"通过复述操纵注意力"。 **实现** 以结构化格式存储计划： ```yaml # scratch/current_plan.yaml objective: "重构认证模块" status: in_progress steps: - id: 1 description: "审计当前 auth 端点" status: completed - id: 2 description: "设计新 token 校验流程" status: in_progress - id: 3 description: "实现并测试改动" status: pending ``` 代理在每个回合开始或需要重新定位时读取此文件。 ### 模式 3：子代理通过文件系统通信 **问题** 在多代理系统中，子代理通常通过消息传递向协调代理报告发现。这创造了"电话游戏"效应——信息在每一跳的摘要中退化。 **解决方案** 子代理将其发现直接写入文件系统。协调代理直接读取这些文件，绕过中间的消息传递。这保真度高，并减少协调代理中的上下文累积。 **实现** ``` workspace/ agents/ research_agent/ findings.md # 研究代理写入此处 sources.jsonl # 来源追踪 code_agent/ changes.md # 代码代理写入此处 test_results.txt # 测试输出 coordinator/ synthesis.md # 协调代理读取代理输出，写入综合 ``` 每个代理相对隔离地工作，但通过文件系统共享状态。 ### 模式 4：动态技能加载 **问题** 代理可能有许多技能或指令集，但大多数与任何给定任务无关。将所有指令塞入系统 prompt 浪费 token，且可能因矛盾或不相关的指导而混淆模型。 **解决方案** 将技能存储为文件。静态上下文中仅包含技能名称和简要描述。代理使用搜索工具在任务需要时加载相关技能内容。 **实现** 静态上下文包含： ``` 可用技能（相关时用 read_file 加载）： - database-optimization: 查询调优与索引策略 - api-design: REST/GraphQL 最佳实践 - testing-strategies: 单元、集成与 e2e 测试模式 ``` 代理仅在处理数据库任务时加载 `skills/database-optimization/SKILL.md`。 ### 模式 5：终端与日志持久化 **问题** 长时间运行进程的终端输出快速累积。将输出复制粘贴到代理输入是手动且低效的。 **解决方案** 自动将终端输出同步到文件。然后代理可 grep 关键片段（错误消息、特定命令），而无需加载整个终端历史。 **实现** 终端会话被持久化为文件： ``` terminals/ 1.txt # 终端会话 1 输出 2.txt # 终端会话 2 输出 ``` 代理使用定向 grep 查询： ```bash grep -A 5 "error" terminals/1.txt ``` ### 模式 6：通过自我修改学习 **问题** 代理通常缺乏用户在交互中隐式或明确提供的上下文。传统上，这需要在会话间手动更新系统 prompt。 **解决方案** 代理将学习到的信息写入自己的指令文件。后续会话加载这些文件，自动整合学到的上下文。 **实现** 用户提供偏好后： ```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) ``` 后续会话包括在文件存在时加载用户偏好的步骤。 **注意** 此模式仍在演进。自我修改需要谨慎的护栏，以防止代理随时间累积不正确或矛盾的指令。 ### 文件系统搜索技术 模型专门经过训练以理解文件系统遍历。`ls`、`glob`、`grep` 和 `read_file`（带行范围）的组合提供了强大的上下文发现： - `ls` / `list_dir`：发现目录结构 - `glob`：查找匹配模式的文件（如 `**/*.py`） - `grep`：搜索文件内容模式，返回匹配行 - `read_file` 带范围：读取特定行范围而不加载整个文件 对于语义稀疏但结构模式清晰的技术内容（代码、API 文档），这种组合通常优于语义搜索。 语义搜索与文件系统搜索很好地协作：语义搜索用于概念查询，文件系统搜索用于结构和精确匹配查询。 ## 实用指导 ### 何时使用文件系统上下文 **以下情况使用文件系统模式：** - 工具输出超过 2000 token - 任务跨越多个对话回合 - 多个代理需要共享状态 - 技能或指令超出系统 prompt 舒适容量 - 日志或终端输出需要选择性查询 **以下情况避免文件系统模式：** - 任务在单回合内完成 - 上下文舒适地适合窗口 - 延迟至关重要（文件 I/O 增加开销） - 简单模型无法使用文件系统工具 ### 文件组织 为可发现性组织文件： ``` project/ scratch/ # 临时工作文件 tool_outputs/ # 大型工具结果 plans/ # 活动计划与清单 memory/ # 持久学习信息 preferences.yaml # 用户偏好 patterns.md # 学到的模式 skills/ # 可加载技能定义 agents/ # 子代理工作区 ``` 使用一致的命名约定。在 scratch 文件中包含时间戳或 ID 以消除歧义。 ### Token 核算 追踪 token 来源： - 衡量静态与动态上下文比率 - 监控工具输出大小（卸载前后） - 追踪动态上下文实际加载频率 基于测量而非假设进行优化。 ## 示例 **示例 1：工具输出卸载** ``` 输入：网页搜索返回 8000 token 之前：8000 token 加入消息历史 之后： - 写入 scratch/search_results_001.txt - 返回："[结果在 scratch/search_results_001.txt。关键发现：API 速率限制 1000 req/min]" - 代理在需要特定细节时 grep 文件 结果：~100 token 在上下文中，8000 token 按需可访问 ``` **示例 2：动态技能加载** ``` 输入：用户询问数据库索引 静态上下文："database-optimization: 查询调优与索引" 代理动作：read_file("skills/database-optimization/SKILL.md") 结果：仅在相关时加载完整技能 ``` **示例 3：聊天历史作为文件引用** ``` 触发：达到上下文窗口限制，需要摘要 动作： 1. 完整历史写入 history/session_001.txt 2. 为新上下文窗口生成摘要 3. 包含引用："完整历史在 history/session_001.txt" 结果：代理可搜索历史文件以恢复摘要中丢失的细节 ``` ## 指南 1. 将大输出写入文件；将摘要和引用返回到上下文 2. 将计划与状态以结构化文件存储以便重读 3. 使用子代理文件工作区而非消息链 4. 动态加载技能，而非全部塞入系统 prompt 5. 将终端与日志输出持久化为可搜索文件 6. 组合 grep/glob 与语义搜索实现综合发现 7. 用清晰的命名组织文件以提升代理可发现性 8. 衡量 token 节省以验证文件系统模式有效 9. 为 scratch 文件实现清理以防止无界增长 10. 为自我修改模式加验证护栏 ## 集成 本技能连接到： - context-optimization - 文件系统卸载是一种观察遮蔽形式 - memory-systems - 文件系统即记忆是简单的记忆层 - multi-agent-patterns - 子代理文件工作区支持隔离 - context-compression - 文件引用支持无损"压缩" - tool-design - 工具应为大输出返回文件引用 ## 参考 内部参考： - Implementation Patterns - 详细模式实现 本集合中的相关技能： - context-optimization - Token 缩减技术 - memory-systems - 持久存储模式 - multi-agent-patterns - 代理协调 外部资源： - LangChain Deep Agents：代理如何使用文件系统进行上下文工程 - Cursor：动态上下文发现模式 - Anthropic：Agent Skills 规范 --- ## 技能元数据 **创建**：2026-01-07 **最后更新**：2026-01-07 **作者**：Agent Skills for Context Engineering 贡献者 **版本**：1.0.0 ## 限制 - 仅当任务明确匹配上述范围时使用本技能。 - 不要将输出视为环境特定验证、测试或专家审查的替代品。 - 如果缺少必需的输入、权限、安全边界或成功标准，请停止并要求澄清。