ruflo Token Efficiency 实战指南：在 Claude Flow Meta-Harness 中实现缓存、协同与用量度量

ruflo 的 .claude/commands/analysis/ 目录内置了一份名为 token-efficiency 的效率型命令文档，核心目标是"在保持输出质量的前提下，通过智能协调降低 Token 消耗"。本指南以此命令为骨架，结合仓库中 TokenOptimizer 实现（v3/@claude-flow/integration/src/token-optimizer.ts）与 token-optimize 命令行实现（v3/@claude-flow/cli/src/commands/hooks.ts#L4880-L4995），完整讲解缓存、协同、度量三大优化路径，帮助你掌握一套可复制、可验证的 Token 成本治理方案。

命令定位：一条内置在 Agent 工作区里的效率规范

token-efficiency.md（关联文档）遵循 Claude Code 风格的 Slash Command 目录约定：将 Markdown 放入 .claude/commands/<分类>/ 即可注册为 /analysis/token-efficiency 一类可被模型调用的指令。仓库中该命令被同步分发到 v3/@claude-flow/cli/.claude/commands/analysis/ 与 v3/@claude-flow/mcp/.claude/commands/analysis/ 两份副本，说明它面向多个工作区（CLI 与 MCP 服务）中的 Agent 运行。

这份命令文档明确了自己的目的（Purpose）：

Reduce token consumption while maintaining quality through intelligent coordination. （通过智能协调降低 Token 消耗，同时维持输出质量。）

文档主体包含四部分：三条 Optimization Strategies（智能缓存、高效协同、度量跟踪）、一份 MCP 工具 JSON 采样、四条 Best Practices，以及一组成果报告口径。下文按该骨架展开，并在每节补充仓库中的源码级依据。

为什么在 Meta-Harness 中 Token 是核心成本

ruflo 是用于部署多智能体 Swarm、协调自主工作流、构建对话式 AI 系统的 Agent Meta-Harness。多 Agent 场景下，Token 开销主要来自三类放大效应：

• 上下文放大：多个 Agent 各自携带系统提示、工具定义与会话历史，长上下文重复计入每次调用；
• 重复读取放大：多个 Agent 对同一文件、同一搜索结果反复检索与全量读取；
• 失败重试放大：Swarm 任务失败后产生重试轮次，每次重试都重新计费。

TokenOptimizer 源码的类注释印证了这一点——它同时组合了三类能力（token-optimizer.ts#L1-L13）：Agent Booster（WASM 加速编辑）、ReasoningBank（语义检索压缩上下文）、Configuration Tuning（批处理 / 缓存 / 拓扑优化），并在注释中明确"No fabricated metrics are reported——所有统计都反映真实测量值"。这正是 token-efficiency 命令所倡导"减 Token 但不降质"的工程落地。

策略一：智能缓存（Smart Caching）

命令文档给出三个缓存要点：

• 搜索结果缓存 5 分钟；
• 文件内容在会话期间缓存；
• 通过模式识别减少冗余搜索。

源码中的 5 分钟 TTL 与缓存命中统计

TokenOptimizer.cachedLookup()（token-optimizer.ts#L234-L261）正是这条策略的实现：缓存条目过期时间写死为 300000 毫秒（即 5 分钟），命中返回旧值并自增 cacheHits，未命中则调用生成函数并把结果同时写入本地 Map 与可选的外部 configTuning 缓存，同时自增 cacheMisses。命中率最终由 getStats() 按 cacheHits / (cacheHits + cacheMisses) 计算（token-optimizer.ts#L266-L283）。

配套测试 token-optimizer.test.ts#L111-L139 验证了"首次调用为 miss、二次调用命中且生成函数不再执行"的行为，并用唯一 key 验证每次 miss 都会使命中+未命中总数 +1。

缓存的可控开关

并非所有场景都适合命中缓存——当文件已变更、需要最新分析结果时，缓存反而带来"脏读"。hooks.ts 中命令定义提供了一个显式反制项 skip-cache（"Skip cached analysis"，hooks.ts#L1147-L1148），让你在需要新鲜度时绕过缓存分析。仓库同时在 .claude/commands/optimization/cache-manage.md 提供了缓存管理的配套命令入口。

实操建议：对高频、结果稳定的操作（搜索、路由、向量查询）优先开启缓存；对文件刚被修改、强一致性要求高的环节使用 skip-cache。命中率本身应作为可观测指标纳入会话统计。

策略二：高效协同（Efficient Coordination）

命令文档给出的三个协同要点：

• Agent 自动共享上下文；
• 避免重复的文件读取；
• 批量执行相关操作。

从"防失败"到"省重试"：配置调优的源码逻辑

协同不只是通信协议问题，也直接决定 Token 浪费量。TokenOptimizer.getOptimalConfig()（token-optimizer.ts#L199-L228）按 Agent 数量推导出默认规模参数：

// agentCount <= 4  -> batchSize = 2
// agentCount <= 8  -> batchSize = 4
// 其他             -> batchSize = 5
const batchSize = agentCount <= 4 ? 2 : agentCount <= 8 ? 4 : 5;
// 缓存上限 200MB，按 25MB * ceil(agentCount / 2) 递增
const cacheSizeMB = Math.min(200, 25 * Math.ceil(agentCount / 2));
// 默认层级式（hierarchical）拓扑，小规模也可退化为 mesh
const topology = 'hierarchical';
// 预期成功率：<=8 个 Agent 为 0.95，更大规模保守取 0.90

这套参数蕴含一个核心思想：尽可能让 Swarm 一次成功，因为 100% 的成功率意味着没有浪费的重试 Token（源码注释原文：100% success rate = no wasted retry tokens）。

当通过 agentic-flow 获得 Config Tuning 能力时，getOptimalConfig() 会改走 configTuning.getOptimalBatchSize() / getOptimalCacheConfig() / selectTopology(agentCount) 的真实调优路径；未集成时则退回上述"反漂移（anti-drift）"默认值。token-optimize 命令同样内置了反漂移配置：batchSize: 4、cacheSizeMB: 50、拓扑 hierarchical、预期成功率 95%（hooks.ts#L4932-L4938）。

对应测试覆盖了不同 Agent 规模：小团队 batchSize ≤ 5、大集群（15 个 Agent）仍保持 hierarchical 与 batchSize ≤ 5（token-optimizer.test.ts#L87-L109）。

实操建议：以 claude-flow hooks token-optimize -A <agentCount> 获取当前规模下的推荐 batch / 缓存 / 拓扑，再配合"共享上下文 + 去重读取 + 批量操作"的协同习惯，把重试率降下来，Token 消耗自然随成功率一起改善。

度量与跟踪：把优化变成可验证的数字

命令文档的第三部分强调：任何优化都必须被测量。仓库提供了三种互相呼应的度量入口。

方式一：MCP 工具采样（命令文档原版示例）

Tool: mcp__claude-flow__token_usage
Parameters: {"operation": "session", "timeframe": "24h"}

// Result shows:
{
  "metrics": {
    "tokensSaved": 15420,
    "operations": 45,
    "efficiency": "343 tokens/operation"
  }
}

字段含义如下：

字段	含义	用途
operation	统计操作类型，如 session（按会话聚合）	界定统计粒度
timeframe	统计时间窗，如 24h	界定统计范围
metrics.tokensSaved	会话内节省的 Token 总数	量化总收益
metrics.operations	参与统计的操作数	归一化分母
metrics.efficiency	平均每操作节省 Token（tokensSaved / operations）	判断单位操作效率

方式二：analysis token-usage 子命令

同级命令文档 token-usage.md 提供了面向分析期的 CLI 入口：

npx claude-flow analysis token-usage [options]

选项	说明
--period <time>	分析周期：1h / 24h / 7d / 30d
--by-agent	按 Agent 维度拆分
--by-operation	按操作类型维度拆分

实际使用示例：

# 最近 24 小时 Token 用量
npx claude-flow analysis token-usage --period 24h

# 按 Agent 拆分统计
npx claude-flow analysis token-usage --by-agent

# 导出 7 天详细报告到 CSV
npx claude-flow analysis token-usage --period 7d --export tokens.csv

注意 --export tokens.csv 出现在命令文档的导出示例中，适合把明细落盘做进一步分析或归档。

方式三：hooks token-optimize 的即时统计

在运行会话内，token-optimize 命令（hooks.ts#L4880-L4893）可以直接拉取统计快照：

选项	别名	说明	默认值
--query <text>	-q	用 ReasoningBank 检索紧凑上下文	—
--agents <n>	-A	为 n 个 Agent 计算最优配置	6
--report	-r	生成完整优化报告	关闭
--stats	-s	展示 Token 节省统计表	关闭

# 查看 Token 节省统计
claude-flow hooks token-optimize --stats

# 为 "auth patterns" 检索紧凑上下文（k=5）
claude-flow hooks token-optimize -q "auth patterns"

# 按 8 个 Agent 计算推荐配置并输出报告
claude-flow hooks token-optimize -A 8 --report

其统计表输出包含 Tokens Saved、Edits Optimized、Cache Hit Rate、Memories Retrieved、Est. Monthly Savings、Agentic-Flow Active 六项（hooks.ts#L4981-L4994）。token-optimize 与 TokenOptimizer.getCompactContext() 共享同一估算口径：按每 Token 约 4 个字符估算，tokensSaved = max(0, ceil(queryLen/4) - ceil(compactPromptLen/4))（token-optimizer.ts#L139-L153）；费用估算按 $0.01 / 1000 tokens 折算。

可复用的报告输出

TokenOptimizer.generateReport()（token-optimizer.ts#L288-L302）会渲染一份可直接附入会话总结的 Markdown 报表：

## Token Optimization Report

| Metric | Value |
|--------|-------|
| Tokens Saved | ... |
| Edits Optimized | ... |
| Cache Hit Rate | ... |
| Memories Retrieved | ... |
| Est. Monthly Savings | ... |
| Agentic-Flow Active | ✓ / ✗ |

命令文档"Review session summaries for insights"的 Best Practice，落地方式就是把这类报表沉淀到会话摘要中，形成跨会话的改进依据。

最佳实践：把四条规范变成默认习惯

命令文档给出了四条 Best Practices，结合源码可进一步明确"何时、为何"：

1. Use Task tool for complex searches（复杂搜索交给任务工具） 把重搜索委派给专门工具/子任务，避免把原始检索过程全量塞回主上下文；复杂搜索命中 ReasoningBank 语义检索后仅回填 compactPrompt，而非整段文件内容。

2. Enable caching in pre-search hooks（在 pre-search 钩子中开启缓存） 仓库配套的 cache-manage 命令（.claude/commands/optimization/cache-manage.md）与 5 分钟 TTL 的 cachedLookup 即是落地载体；需要新鲜数据时显式使用 skip-cache。

3. Batch operations when possible（尽量批量操作） 批量不仅降低往返次数，也直接约束 Swarm 的 batchSize——按 Agent 规模选择 2 / 4 / 5 的批大小，减少半途失败导致的整批重试。

4. Review session summaries for insights（复盘会话摘要） 用 token_usage / token-optimize --stats / generateReport() 生成的结构化报表复盘，让下一轮会话继承上一轮的反漂移配置，形成"测量 → 调优 → 再测量"的闭环。

成果口径与事实边界

命令文档末尾列出其记录的结果口径：

• 📉 32.3% average token reduction（平均 Token 缩减 32.3%）
• 🎯 More focused operations（操作更聚焦）
• 🔄 Intelligent result reuse（智能复用结果）
• 📊 Cumulative improvements（累积式改进）

需要明确两点边界：

1. 该百分比是命令文档记录的报告口径，实际节省幅度强烈依赖运行环境。源码注释明确说明"实际节省取决于 agentic-flow 的可用性与使用模式""不报告虚构指标，全部统计均来自真实测量"（token-optimizer.ts#L9-L10）；当 agentic-flow 未集成、ReasoningBank 不可用时，getCompactContext() 会静默退回空上下文、节省为 0（token-optimizer.ts#L116-L124）。
2. 缓存命中率决定收益上界。tokensSaved 只有在"缓存命中 + 语义检索成功 + 上下文确实被压缩"三种条件同时满足时才会增长，这正是"无虚构指标"设计与 cacheHits/cacheMisses 独立计数的原因。

因此，正确姿势是把文中 JSON、反漂移配置与 32.3% 当作可复现的度量模板与期望区间，在自家工作负载上实测 cacheHitRate 与 tokensSaved 后再下结论。

继续深入：相关文件导航

若想进一步追踪这份命令背后的完整实现链路，可以从以下路径继续：

• 命令本体：token-efficiency.md，副本位于 v3/@claude-flow/cli/.claude/commands/analysis/token-efficiency.md
• 配套分析命令：token-usage.md、analysis 目录说明
• 核心实现：TokenOptimizer（v3/@claude-flow/integration/src/token-optimizer.ts）
• CLI 命令实现：token-optimize（v3/@claude-flow/cli/src/commands/hooks.ts#L4880-L4995）
• 行为验证测试：token-optimizer.test.ts
• 缓存治理配套命令：cache-manage.md