Filesystem Context Offload 基准任务剖析Agent Skills 上下文外置的可量化验证【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering本篇技术指南以开源仓库 Agent-Skills-for-Context-Engineering 中的有效性基准任务001-filesystem-context-offloadtask.md为分析主体完整拆解其假设、工作区结构、评分脚本与被测行为并结合filesystem-context技能的源码实现说明「将大型工具输出外置到文件系统、再按需精准取回」这一上下文工程手法如何被设计成可自动判分的 Agent 实验。读完本文你将掌握如何读懂一个 effectiveness 基准任务的全部要素、verify.sh的三重判分逻辑、六种技能加载条件的对照实验设计以及如何把 5000 行工具输出压缩为约百 token 的上下文引用而不丢失信息。一、任务背景为什么用文件系统承载上下文本仓库的核心主张之一是上下文窗口是稀缺资源而文件系统是天然的溢出层。filesystem-context/SKILL.md 开篇即指出上下文窗口有限任务常常需要超过单窗口容量的信息因此应把文件系统作为主要的溢出层——通过文件进行存储、取回与更新从而在单一接口下获得近乎无限的上下文容量。同时应优先采用动态上下文发现按需拉取相关内容而不是静态全量注入因为静态上下文无论是否相关都会消耗 token还会挤占任务特定信息的空间。然而这一设计主张是否真的能带来可测量的收益仅靠文档声明不足以回答。仓库为此在researcher/benchmarks/effectiveness/下构建了 Stage 3 有效性基准README通过 Cursor SDK 执行真实 Agent 任务在多种技能加载条件下反复运行用结果质量、token 成本与墙钟时间的差异来量化某个技能带来的效应量effect size。001-filesystem-context-offload就是这个基准中的第一个、也是被官方标注为 canonical 模板的任务。二、任务定义agent 拿到的原始提示词任务的核心输入就是 task.md 本身——运行器会把它直接作为 Agent 的系统提示词。原文极简且自洽全文如下Your task takes place in the current working directory. You are processing the output of a long-running diagnostic tool. The output is in tool_output.txt. Somewhere inside the output there is a line of the form API_RATE_LIMITvalue. Find that value and report it back to the user. You may create scratch files if helpful. When you have the answer, respond with a short message that includes the exact line API_RATE_LIMITvalue and nothing else important. Do not modify tool_output.txt.这个提示词刻意设计了两个「坑」海量噪音数据tool_output.txt是约 5000 行的合成 agent 追踪日志格式如[t2026-05-15T03:00:01Z] orchestrator DEBUG elapsed_ms380 seq00001 entropy0.275029每行都包含时间戳、模块名、日志级别与性能字段。目标事实API_RATE_LIMIT8475被埋在第 4321 行已通过grep -n API_RATE_LIMIT在 starting/tool_output.txt 中核实周围没有任何结构性标记帮助定位。隐式行为期望提示词并未显式命令 Agent「把文件写到 scratch 目录」只以「You may create scratch files if helpful」暗示了外置的可能性同时要求「respond with a short message」从措辞上抑制把 5000 行全文塞回上下文的方案。换句话说这个任务测试的是 Agent在自由条件下是否自发采用文件系统外置策略而不是被命令执行某条既定指令。三、假设与工作区设计任务 READMEREADME.md记录了明确的实验假设一个装备了filesystem-context技能的 Agent 将会把模拟工具输出写入scratch/下的文件而不是内联返回使用定向检索grep 带行区间的 read回答后续问题而不重新加载整个 payload相比对照条件显著减少总 token 消耗。作为对照没有技能的 Agent 预期会把完整 payload 倾倒回上下文或以其他方式推高 token 用量。工作区在每次运行前由 SDK runner 从starting/复制到一个全新临时目录starting/中只含两个文件目录列表文件作用tool_output.txt约 5000 行合成 agent 追踪数据目标事实埋在第 4321 行instructions.md简短的工作区布局提醒其中 instructions.md 只有三行实质内容指出tool_output.txt是需要分析的诊断输出建议若想外置大内容以便定向重读可创建scratch/目录并声明可以使用环境中的任何文件系统工具。它与 task.md 一起构成了对 Agent 的全部引导。四、评分逻辑verify.sh 的三重判分自动判分由 verify.sh 完成它运行在 SDK runner 构建的临时工作区内以退出码 0 表示任务通过。三个检查要点如下检查 1最终回复必须包含目标事实硬性通过条件EXPECTED_VALUE8475 EXPECTED_LINEAPI_RATE_LIMIT${EXPECTED_VALUE} if [ ! -f .runner/final.txt ]; then echo verify: missing .runner/final.txt (runner did not stage final response) 2 exit 11 fi if ! grep -q ${EXPECTED_LINE} .runner/final.txt; then echo verify: final response does not contain ${EXPECTED_LINE} 2 exit 12 firunner 会把 Agent 的最后一条助手消息写入.runner/final.txt随后grep -q API_RATE_LIMIT8475做精确匹配。注意这里匹配的是整行即要求 Agent 回复中保留完整的API_RATE_LIMIT8475文本而不仅是数值本身。检查 2scratch/目录是否存在技能行为信号if [ ! -d scratch ]; then echo verify: no scratch/ directory; agent did not offload (still counts as task pass on response, but logged) 2 echo scratch_dir_missing .runner/notes.txt exit 0 fi这是判分设计上的关键细节即使没有创建scratch/只要最终回复正确任务依然算通过exit 0但会向.runner/notes.txt写入scratch_dir_missing标记。也就是说外置行为本身不构成通过条件而是被单独记录、用于事后分析的行为信号——这保证了「靠聪明检索直接答对」的 Agent 不会因行为差异被误判失败。检查 3scratch/中是否存在从 tool_output.txt 复制的内容技能行为信号shopt -s nullglob if compgen -G scratch/* /dev/null; then if grep -F -l -m 1 -q API_RATE_LIMIT scratch/* 2/dev/null; then echo scratch_used .runner/notes.txt else echo scratch_empty_or_unrelated .runner/notes.txt fi figrep -F -l用字面量非正则模式在 scratch 目录的所有文件中查找API_RATE_LIMIT字样。命中则记录scratch_used未命中则记录scratch_empty_or_unrelated。因为原始日志中该行恰好包含API_RATE_LIMIT前缀这个检查能有效判定 Agent 是否真的把日志内容而非自造文本写入了 scratch。综上verify.sh 的判定矩阵为答对目标值 → 通过创建 scratch 且其中含日志原文 → 记录为典型外置行为两者正交各自独立产生观测值。五、实验条件如何量化技能的效应量任务的 metadata.json 记录了实验设计元数据{ id: 001, slug: filesystem-context-offload, target_skill: filesystem-context, irrelevant_skill: bdi-mental-states, category: context-management, difficulty: easy, notes: Tests whether an agent will offload a large simulated tool output to a file and then retrieve only the specific piece it needs, rather than re-reading the entire payload. The filesystem-context skill should make this behavior the default. }根据 effectiveness/README.md 的条件表每个任务在每个模型下都会评估六种条件差异在于.cursor/skills/目录中放置的技能集条件settingSources装入的技能control[]无不加载任何技能target[project]仅target_skillfilesystem-contextnegative[project]仅irrelevant_skillbdi-mental-states负对照full[project]全部 15 个技能target_plus_one[project]target_skill加一个相关技能交互对照target_plus_unrelated[project]target_skill加一个无关技能交互对照任务 README 给出了四类预期行为画像controlAgent 大概率把完整输出内联返回或找不到事实token 消耗高target装载 filesystem-context应外置并定向检索token 更低且成功negative装载 bdi-mental-states、无 filesystem-context行为应与 control 等价用于排除「任何技能都会提升表现」的混淆full装载全部技能成功率应与 target 持平token 可能因额外上下文而略高。runner 会为每个 (task, condition, model, replication) 组合构建全新工作区复制starting/到临时目录并仅装入范围内技能。在 runEffectiveness.ts 中可见执行框架CONDITIONS常量定义了上述六种条件discoverTasks()扫描任务目录读取 metadata.jsonforecastCost按每 run 约 2 万输入 / 4 千输出 token、约 0.18 美元的估算做预算断言并以--dry-run模式先行校验任务与配置形态当前为 v2.2.x scaffold完整执行器计划在 v2.4.0 落地。运行完成后每条件原始结果 JSON、工作区前后 diff、verify.sh 输出以及按任务按条件的聚合summary.json会被持久化聚合结果以每行一条 benchmark sweep 的格式写入researcher/reports/effectiveness-history.jsonl。六、被测技能的实现支撑filesystem-context 的源码级依据要理解「target 条件为何应当胜出」需要回到技能本身。filesystem-context/SKILL.md 将上下文失效归纳为四种模式并指出本任务对应的正是其中两类over-retrieved context取回内容远超所需浪费 token与buried context小众信息散落在大文件中对应的修复手段分别是「把批量内容外置到文件、返回紧凑引用」与「结合 glob 和 grep 做结构化搜索」。任务期望的具体行为——把工具输出写入 scratch、grep 定位、带行区间 read——与技能中的Pattern 1: Filesystem as Scratch Pad完全对应。技能内给出了如下参考实现SKILL.md 内嵌示例def handle_tool_output(output: str, threshold: int 2000) - str: if len(output) threshold: return output file_path fscratch/{tool_name}_{timestamp}.txt write_file(file_path, output) key_summary extract_summary(output, max_tokens200) return f[Output written to {file_path}. Summary: {key_summary}]而仓库中的真实脚本 scripts/filesystem_context.py 提供了可运行的完整实现包含三个可组合类ScratchPadManager以base_pathscratch、token_threshold2000为默认值构造参数见第 57 行用estimate_tokens按 1 token ≈ 4 字符估算与should_offload决定是否外置offload将内容写入带时间戳的{source}_{YYYYmmdd_HHMMSS_ffff}.txt文件并返回含path、source、tokens_saved、summary的引用字典format_reference将其格式化为[Output from web_search saved to scratch/.... ~N tokens. Summary: ...]形式的紧凑上下文引用cleanup支持按文件年龄做保留期清理。ToolOutputHandler封装「小输出内联、大输出外置」的自动决策process_output(tool_name, output)一行完成判断与引用替换。AgentPlan/PlanStep计划持久化模式支持save/loadJSON 计划文件并在上下文刷新后通过progress_summary()恢复任务感知。对照验证技能中 Pattern 1 的说明第 52-68 行明确给出了handle_tool_output的阈值语义——当输出超过约 2000 token 时写入文件、提取约 200 token 摘要、返回文件引用并在上下文只保留约 100 token 的引用占位。这正是本任务 5000 行tool_output.txt场景的教科书式解法一次grep -n API_RATE_LIMIT即可在第 4321 行命中目标随后一次带行区间的read_file精确取回全程不触碰其余 4999 行。其 token 收益可以量化为~5000 行日志几乎全部驻留磁盘上下文仅保留一行目标事实。更深层的支撑是 references/implementation-patterns.md它给出了 6 个模式的可运行代码与 token 核算建议静态上下文占比 20%、工具密集型工作流外置节省 50%、检索精度 70% 可作为目标基准。这些指标设计恰好回应了任务「report as effect sizes against the control condition」的统计意图。七、任务可复制性如何在自己环境中复现与扩展001-filesystem-context-offload被 effectiveness/README.md 明确指定为 canonical 任务模板新增任务只需五步在tasks/下新建带三位 ID 与 slug 的目录如002-slug从001-filesystem-context-offload/复制目录结构编写自包含的task.md让 Agent 只需参照工作区即可行动编写可在任意临时目录运行、成功时 exit 0 的verify.sh诚实填写metadata.json——尤其要为负对照选择真正不可能帮助该任务的irrelevant_skill随后用npm run effectiveness:dry-run见 sdk-runner/package.json验证。若任务为负对照任何技能都不应帮助可将target_skill与irrelevant_skill均设为nonerunner 会跳过target及两个target_plus_*条件仅运行control、full与一项 sanity check。想要在本任务上做手工复现也可以完全不依赖 SDK在任意临时目录中放置 starting/tool_output.txt 与 starting/instructions.md把 task.md 作为提示词交给 Agent再对照 verify.sh 的三项检查人工核对即可。八、设计启示这个任务教给我们什么把 task.md、verify.sh 与 filesystem-context 技能合在一起读能提炼出四条可迁移的 Agent 评测设计经验行为信号与任务结果解耦verify.sh 将「是否外置」与「是否答对」分开记录前者只写notes.txt不进通过条件这避免了评测标准与行为偏好互相污染也让 token 效应量的统计不受行为强制的干扰。提示词即实验变量task.md 没有明说「把输出写到文件」只以「You may create scratch files if helpful」与「short message」做软约束——这正是测量 Agent 是否会自发采用技能所描述行为的正确姿势如果指令写明步骤测到的就不再是技能效应而是指令遵循能力。噪声规模是效应的放大器把目标事实埋在 5000 行、第 4321 行的位置使 naive 全量内联方案的 token 代价被放大到肉眼可见同时把 2000 token 外置阈值、grep 定向检索这类技能细节变成决定性差异。负对照排除安慰剂效应bdi-mental-states作为irrelevant_skill参与 negative 条件用于验证「加载了技能哪怕是无关技能」本身不会带来提升从而把观察到的差异归因于filesystem-context的内容而非「多装技能就好」的伪相关。对任何正在构建 Agent 上下文管理系统的开发者001-filesystem-context-offload既是一份可运行的评测清单也是一份关于「文件系统作为上下文溢出层」的实证设计模板先定义可判分的任务、再设计行为信号、最后用对照条件量化效应量——这条路同样适用于评测你自己的上下文外置、压缩或检索策略。正文完【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考