把 Agent 的 I/O 外包：90% Token 节省背后的模型路由机制
一个主 Agent 保留理解、判断与修改；一个低成本工作模型负责大文件阅读和可预测的样板输出。关键价值不是换模型，而是控制“哪些原始内容可以进入昂贵模型的上下文”。
核心结论
让主 Agent 只看“决策所需的信息”，而非整个工作语料。
这是一个上下文路径重构问题：节省的不是仓库里的 Token，而是避免把大量低价值原文带进昂贵模型的输入窗口与推理轨迹。
问题重新定义：Agent 的大头成本常常是 I/O
“读很多、想很少”的任务，不应默认使用最贵的模型。
传统单 Agent 路径
当开发者问“这个服务做什么？”时，编码 Agent 往往先读取多个源文件、测试、配置与文档。即使最后只需要几条结论，原文已经作为输入 Token 进入主模型；如果再生成模板代码，输出 Token 同样昂贵。
路由后成本 ≈ 工作模型处理原文 + 主模型接收摘要/状态
前者把“搬运、扫描与格式匹配”和“推理、决策”绑定在同一个模型上；后者依据任务的推理密度把两者拆开。
总体架构：主 Agent 是决策者，Mode 是可配置的工作单元
路由逻辑与工作模型、提示词、工具解耦。
读文件 / 生成样板
原始文件主要停留在工作模型调用内；主 Agent 获得结构化摘要，或仅知道输出已写入目标文件。
AiKA Mode 是什么
Mode 是声明式、面向单一用途的 Agent 配置：定义指令、模型、参数、可挂接的 MCP 工具与质量控制。它运行于短生命周期环境，调用方只按名称发起请求，不必为每种任务维护独立服务、密钥或长驻进程。
因此，插件只负责回答“何时委派”，Mode 负责回答“怎样完成”。后续替换工作模型、提示词或工具时，无需改动路由拦截器。
三层路由机制：把建议变成可执行策略
从硬约束到软引导，保证 Agent 不会轻易绕过节省策略。
PreToolUse Hook：在昂贵读取发生前阻断
check-file-size 监听 Read：全文件超过阈值（默认 350 行）就阻止读取并指向 /bulk-reader。check-bash-read 同时拦截 cat / head / tail / less / more 对大文件的读取，避免从 Bash 绕过策略。
命名参数脚本：收口传输、清洗与观测
主 Agent 调用 bulk-read 或 code-write，脚本负责封装请求、调用 Portal CLI 的 aika:invoke-chat、处理异常、移除 Markdown 围栏，并将 Token 用量写到 stderr。Agent 不需要从自然语言临时拼接复杂 Bash 管道。
Skill：告诉 Agent 为什么、何时以及如何调用
Skill 给出调用语法和适用条件。即使主 Agent 没有正确阅读 Skill，Hook 仍会拦截大文件读取；Skill 的作用是降低被拒绝后的恢复摩擦，而不是承担策略执行。
为什么三层比把规则写进 CLAUDE.md 更可靠
纯提示词规则是建议，模型可忽略、每个项目也需重复维护。Hook 位于工具调用前，是确定性的执行点；脚本提供稳定接口；Skill 则把正确行为变得容易。这个结构可泛化到安全审批、数据脱敏、运行测试、变更审计等 Agent 治理需求。
两条委派路径
阅读路径压缩信息；写作路径绕开主模型输出。
将多个文件包在带路径的 XML 标签内，与问题一起发送。工作模型返回简洁、结构化的要点。
- 输入：问题 + 多个文件路径
- 输出：只给主 Agent 必要的摘要、类型、名称或行信息
- 适合：服务概览、依赖关系、跨文件模式扫描
发送规格和一个参考文件，让工作模型严格模仿命名、格式与约定；可直接写入目标文件。
- 输入：规格 + 参考文件 + 可选目标路径
- 输出：仅代码，脚本去除 Markdown 围栏
- 适合：测试、配置桩、类型定义、重复性样板
参考文件为什么是必要输入
没有参考文件的代码生成只能依赖通用训练知识，容易得到“语法正确但不属于该仓库”的内容。参考文件把工作模型的任务从“设计一份代码”收窄为“沿用已验证的局部范式”，这正是低成本模型较稳定的工作区间。
# 批量读取：主 Agent 只接收工作模型的结构化答复 bulk-read --question "哪些方法会访问数据库？" \ --paths src/Service.java src/Handler.java # 样板生成：结果可由脚本直接写入，主 Agent 无需消费完整输出 code-write --spec "为 UserService 生成单元测试" \ --reference tests/OrderTest.java \ --target tests/UserTest.java
节省从哪里来
核心杠杆是减少昂贵模型的输入与输出暴露面。
阅读委派的 Token 账本
原始语料仍会被工作模型消费，但它不再占用主 Agent 的上下文。因而系统的总成本是否下降，取决于工作模型价格、摘要压缩比、调用频率与网络延迟；Spotify 展示的指标聚焦于最昂贵的主模型 Token。
| 场景 | 源码行数 | 直接读取 | 委派后主 Agent Token | 节省 |
|---|---|---|---|---|
| 单个大文件 SpotifyUri.java | 4,014 | 33,684 | 5,737 | 82% |
| 源码 + 测试 PromotionRuleRepository | 7,408 | 75,990 | 4,148 | 94% |
| 跨服务多文件 permission handlers | 1,281 | 16,221 | 821 | 94% |
| 生成测试 code-write | 3,667 | 读取参考 + 主模型生成 | 833 行直接落盘 | 不与读取场景直接比较 |
公开资料给出的前三项平均 bulk-read 节省约 90%。代码生成的收益更难用同一公式测量：除了减少参考文件输入，也避免让主模型输出整段样板代码。
路由边界：不是所有任务都应该外包
委派的前提是：损失原文细节后，任务仍能稳定完成。
可迁移实现：为自己的 Agent Harness 建一条路由层
不依赖 Spotify Portal，也能复用同样的职责划分。
最小可行架构
- 给工具调用加前置策略点：在 Read / Bash / Write 前检查文件规模、命令类型、风险等级和任务标签。
- 定义窄任务 Worker：例如 repo-summarizer、test-scaffolder、doc-updater。每个 Worker 固定输入契约与输出格式。
- 用脚本或工具包装请求：不要让 Agent 临时拼接命令；统一处理文件封装、超时、重试、输出清洗、统计和审计。
- 让主 Agent 有受控回退：Worker 不足以回答时，返回建议的文件与区间；主 Agent 只读取必要片段，再做编辑或判断。
- 建立测量闭环：记录路由命中率、原始/摘要 Token、时延、回退率、测试通过率与人工否决率。
# 伪配置：策略必须由工具层执行，而不是仅放在系统提示词里
rules:
- when: tool == "read" && full_file && line_count > 350
action: block_and_redirect
worker: repo-summarizer
allow_fallback: "read with offset + limit"
- when: task == "generate_boilerplate" && has_reference_file
action: delegate
worker: pattern-writer
post_checks: [formatter, typecheck, targeted_test]
- when: task in ["debug", "architecture", "security_review"]
action: keep_with_primary_agent
输出契约比“更长的提示词”更重要
bulk-reader 要求仅输出结构化要点，code-writer 要求仅输出代码，都是为了避免工作模型附带解释、寒暄、Markdown 围栏等无用 Token。更重要的是，输出字段应服务于下游决策：文件路径、符号名、关系、证据片段、置信度与需要精确读取的区间。
限制、风险与治理清单
Token 优化不能削弱正确性、保密性和可观测性。
工程限制
- 时延：公开说明的单次委派通常需要 10–30 秒，且调用有 30 秒上限；大生成任务要分块。低于阈值的文件直接读取更快。
- 请求大小：当前实现经命令行传递输入，受操作系统参数长度限制；插件用 SHUNT_MAX_PAYLOAD_BYTES 设置上限，超出时应分批而非硬塞。
- 无状态调用：每次委派是一次性请求。再次提问会重新发送文件，但原始文件只会送到工作模型，不会累积到主 Agent 上下文。
- 生成不等于已验证：直接写盘可省 Token，却不能跳过 formatter、编译、测试、diff 规则和必要的局部抽查。
企业落地时必须补齐
- 数据边界：按仓库、目录、文件标签、密级与敏感字段决定哪些内容可发送给工作模型；密钥、生产配置、客户数据默认拒绝或脱敏。
- Worker 质量门：对摘要要求引用文件与符号；对生成结果强制执行静态检查与测试；失败时回退主 Agent，而不是静默提交。
- 成本账本：同时记录主模型与工作模型 Token、请求次数、缓存命中、时延和失败率。只看主模型 Token，可能高估总费用收益。
- 策略版本化：阈值、模型、提示词和允许目录应以配置方式版本管理，并做 A/B 基准；350 行只是该插件的默认起点，不是普适最优值。
资料来源
用于核对实现机制、配置与测试数据。
- Spotify Engineering：Portal by Spotify cut my Claude Code token usage by 90%（2026-09-03）
- spotify/portal-ai-plugins · shunt 插件（Hook、脚本、Skill、评测与基准说明）
- Spotify for Backstage：AiKA Modes（声明式 Agent 的配置能力）
阅读建议：先掌握“强制路由 + 窄任务 Worker + 精确回退”这个模式，再选择 Portal、Claude Code、Codex 或自研 Harness 作为具体承载平台。