企业官网建设流程全解析

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-offload（task.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_LIMIT=<value>`. 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_LIMIT=<value>` and nothing else important. Do not modify `tool_output.txt`.

这个提示词刻意设计了两个「坑」：

1. 海量噪音数据：tool_output.txt是约 5000 行的合成 agent 追踪日志，格式如[t=2026-05-15T03:00:01Z] orchestrator DEBUG elapsed_ms=380 seq=00001 entropy=0.275029，每行都包含时间戳、模块名、日志级别与性能字段。目标事实API_RATE_LIMIT=8475被埋在第 4321 行（已通过grep -n "API_RATE_LIMIT"在 starting/tool_output.txt 中核实），周围没有任何结构性标记帮助定位。
2. 隐式行为期望：提示词并未显式命令 Agent「把文件写到 scratch 目录」，只以「You may create scratch files if helpful」暗示了外置的可能性，同时要求「respond with a short message」，从措辞上抑制把 5000 行全文塞回上下文的方案。

换句话说，这个任务测试的是 Agent在自由条件下是否自发采用文件系统外置策略，而不是被命令执行某条既定指令。

三、假设与工作区设计

任务 README（README.md）记录了明确的实验假设：一个装备了filesystem-context技能的 Agent 将会：

1. 把模拟工具输出写入scratch/下的文件，而不是内联返回；
2. 使用定向检索（grep + 带行区间的 read）回答后续问题，而不重新加载整个 payload；
3. 相比对照条件显著减少总 token 消耗。

作为对照，没有技能的 Agent 预期会把完整 payload 倾倒回上下文，或以其他方式推高 token 用量。

工作区在每次运行前由 SDK runner 从starting/复制到一个全新临时目录，starting/中只含两个文件（目录列表）：

其中 instructions.md 只有三行实质内容：指出tool_output.txt是需要分析的诊断输出；建议若想外置大内容以便定向重读，可创建scratch/目录；并声明可以使用环境中的任何文件系统工具。它与 task.md 一起构成了对 Agent 的全部引导。

四、评分逻辑：verify.sh 的三重判分

自动判分由 verify.sh 完成，它运行在 SDK runner 构建的临时工作区内，以退出码 0 表示任务通过。三个检查要点如下：

检查 1：最终回复必须包含目标事实（硬性通过条件）

EXPECTED_VALUE="8475" EXPECTED_LINE="API_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 fi

runner 会把 Agent 的最后一条助手消息写入.runner/final.txt，随后grep -q "API_RATE_LIMIT=8475"做精确匹配。注意这里匹配的是整行，即要求 Agent 回复中保留完整的API_RATE_LIMIT=8475文本，而不仅是数值本身。

检查 2：scratch/目录是否存在（技能行为信号）

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 不会因行为差异被误判失败。

检查 3：scratch/中是否存在从 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 fi

grep -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/目录中放置的技能集：

任务 README 给出了四类预期行为画像：

• control：Agent 大概率把完整输出内联返回或找不到事实，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.json，forecastCost按每 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 = 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}]"

而仓库中的真实脚本 scripts/filesystem_context.py 提供了可运行的完整实现，包含三个可组合类：

• ScratchPadManager：以base_path="scratch"、token_threshold=2000为默认值（构造参数见第 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 任务模板，新增任务只需五步：

1. 在tasks/下新建带三位 ID 与 slug 的目录（如002-<slug>）；
2. 从001-filesystem-context-offload/复制目录结构；
3. 编写自包含的task.md，让 Agent 只需参照工作区即可行动；
4. 编写可在任意临时目录运行、成功时 exit 0 的verify.sh；
5. 诚实填写metadata.json——尤其要为负对照选择真正不可能帮助该任务的irrelevant_skill，随后用npm run effectiveness:dry-run（见 sdk-runner/package.json）验证。

若任务为负对照（任何技能都不应帮助），可将target_skill与irrelevant_skill均设为"none"，runner 会跳过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 评测设计经验：

1. 行为信号与任务结果解耦：verify.sh 将「是否外置」与「是否答对」分开记录，前者只写notes.txt不进通过条件，这避免了评测标准与行为偏好互相污染，也让 token 效应量的统计不受行为强制的干扰。
2. 提示词即实验变量：task.md 没有明说「把输出写到文件」，只以「You may create scratch files if helpful」与「short message」做软约束——这正是测量 Agent 是否会自发采用技能所描述行为的正确姿势；如果指令写明步骤，测到的就不再是技能效应而是指令遵循能力。
3. 噪声规模是效应的放大器：把目标事实埋在 5000 行、第 4321 行的位置，使 naive 全量内联方案的 token 代价被放大到肉眼可见，同时把 2000 token 外置阈值、grep 定向检索这类技能细节变成决定性差异。
4. 负对照排除安慰剂效应：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