ruflo Agent 会话 Token 用量分析实战：token-usage 命令、底层数据链路与效率优化

ruflo 作为一套面向多 Agent 编排与自主工作流的元调度框架，每一次会话都会产生可观的 LLM 调用成本，而 token-usage 分析命令正是针对会话期间 Token 消耗进行体检、拆解与优化的入口。本文以仓库内 token-usage 命令定义 为骨架，结合其同目录优化文档与 ruflo-cost-tracker 插件的真实采集实现，完整讲解命令用法、参数语义、输出形态，并下沉到 "session jsonl → 用量字段 → AgentDB 持久化" 的数据链路。读完你将掌握如何按时间段、按 Agent、按操作类型分析 Token 去向，并据此制定可落地的降本策略。

命令是什么：为多 Agent 工作流做 Token 体检

token-usage 属于 ruflo/.claude 命令体系中 analysis 分析命令族的一员（该族还包含 bottleneck-detect 与 performance-report，家族清单见 analysis/README.md）。它的核心职责在命令文档第一行就写得很明确：

Analyze token usage patterns and optimize for efficiency.

即在一次或一段多 Agent 会话结束后，回溯这段时间内产生的 LLM Token 消耗，识别"谁（哪个 Agent）、做了什么（哪类操作）、花了多少"，为后续的模型降级、缓存开启、操作批量化提供量化依据。与代码语义层面的 claude-flow analyze（见 v3 CLI analyze 命令）不同，本命令关注的是推理调用的成本维度，属于运行经济学而非代码质量分析。

值得注意的是，同样的命令文档也随 V3 CLI 一并分发（见 v3/@claude-flow/cli/.claude/commands/analysis/token-usage.md），说明它是 CLI 工作流中的一等公民能力。

基本用法与参数详解

命令文档给出的统一调用形式如下：

npx claude-flow analysis token-usage [options]

其中 npx claude-flow 指向仓库内 V3 CLI 包（对应 v3/@claude-flow/cli），analysis 是子命令命名空间，token-usage 是具体分析器。

参数语义

命令文档 Options 段 定义了三个核心参数，语义与建议取值如下：

参数	类型	作用	可选值 / 说明
--period <time>	时间窗口	限定统计回溯范围	1h、24h、7d、30d，从短时调试到月度盘点全覆盖
--by-agent	布尔开关	按 Agent 维度拆分汇总	展开后即可定位高消耗 Agent（如 coder / architect / researcher）
--by-operation	布尔开关	按操作类型维度拆分	区分检索、文件读写、工具调用、推理对话等不同类型的消耗

结合仓库内成本分析的真实字段（见下节 数据链路），--by-agent 对应的输出大致等价于 cost report 中 By agent 分组的形态，例如：

By agent:
  coder:      5.20 USD (41.8%) — sonnet
  architect:  3.80 USD (30.5%) — opus
  researcher: 2.00 USD (16.1%) — sonnet
  reviewer:   0.45 USD (3.6%)  — haiku

关于示例中出现的 --export

命令文档的 Examples 段 在第三个示例中使用了 --export tokens.csv，说明该分析器实际还支持结果导出。选项清单未显式列出它，但按惯例 --export <file> 会将统计明细以 CSV 落到指定路径，便于在表格软件或后续脚本中做二次加工。使用前若本地 CLI 版本报未知选项，可先执行 npx claude-flow analysis token-usage --help 确认本版本支持的完整选项集合。

实战示例解析

以下三个命令均直接继承自 命令定义文档，可用于日常定位问题：

1. 查看最近 24 小时的整体用量

npx claude-flow analysis token-usage --period 24h

适用场景：Agent 联调结束后想快速确认今天花了多少 Token。输出通常包含总输入 Token、总输出 Token、消息/操作次数，以及基于价格表折算的成本估算。若数值异常陡增，再叠加下面两种拆分方式定位根因。

2. 按 Agent 拆分定位"大户"

npx claude-flow analysis token-usage --by-agent

适用场景：Swarm 中跑了许多角色（架构师、编码者、评审者），想知道谁在消耗大头。此视图会暴露"某个 agent 长期占用 Sonnet/Opus"这类结构性浪费——这正是降级策略的切入点。参考成本归因部分，评审类低复杂度任务可优先下放到 Haiku 档。

3. 导出 7 天明细用于离线分析

npx claude-flow analysis token-usage --period 7d --export tokens.csv

适用场景：需要跨会话做周级趋势分析、或把数据并入成本仪表盘。导出的 CSV 再配合 --by-agent / --by-operation 的列结构，即可画出每个角色、每类操作的 Token 消耗柱状图。

底层数据链路：Token 用量到底从哪采集

token-usage 分析的结果不会凭空产生，仓库中的 ruflo-cost-tracker 插件提供了可验证的采集实现，让"分析"建立在真实会话记录之上。

第一步：解析 Claude Code 会话 jsonl

插件脚本 track.mjs 展示了完整的抓取逻辑：默认读取 ~/.claude/projects/<encoded-cwd>/ 下最近修改的 session jsonl（编码规则是把路径中的 /、\、Windows 盘符冒号统一替换为 -，见 encodeProjectPath），逐行解析 assistant 类型消息并提取 message.usage 字段：

const u = m.message.usage;
slot.input_tokens += u.input_tokens || 0;
slot.output_tokens += u.output_tokens || 0;
slot.cache_creation_input_tokens += u.cache_creation_input_tokens || 0;
slot.cache_read_input_tokens += u.cache_read_input_tokens || 0;

（对应 track.mjs 的 summarizeSession）这里出现了四类 Token 指标——除了常规的输入/输出，还专门区分了 缓存写入（cache creation） 与 缓存读取（cache read），这是评估 prompt caching 收益的关键。

脚本支持的环境变量（同样来自该文件头注释与 main 实现）：

环境变量	作用
TRACK_CWD=<path>	覆盖要扫描哪个项目的会话
TRACK_SESSION=<file>	固定到某个具体 session jsonl
TRACK_OUT=<path>	额外把 JSON 摘要写到指定路径
TRACK_NAMESPACE=<name>	覆盖记忆命名空间（默认 cost-tracking）
TRACK_DRY_RUN=1	跳过写入，只打印摘要

第二步：统一多厂商 usage 字段

不同模型供应商返回的用量字段名并不一致，agent-execute-core.ts 里的记录器做了归一化：Anthropic 风格（input_tokens / output_tokens，见 L284-L299）被映射为统一的 inputTokens / outputTokens / totalTokens；OpenAI 风格（prompt_tokens / completion_tokens / total_tokens，见 L377-L394）同样被归一。统一的 usage 结构随后随执行结果一并上报给用量记录器，成为分析命令的上游数据源。

第三步：持久化到 cost-tracking 命名空间

采集完成后，track.mjs 通过 memory store --namespace cost-tracking --key session-<id> --value <json> 把结构化摘要写入 AgentDB 记忆命名空间。这意味着 token-usage 类的分析命令可以直接按命名空间、按时间段检索历史会话的成本记录，而不必每次都重新解析庞大的 jsonl。

成本归因模型：从 Token 数到金额

Token 数量本身只是中间量，真正用于决策的是折算后的成本。ruflo-cost-tracker/REFERENCE.md 给出了插件内置的成本归因公式：

task_cost = (input_tokens       / 1_000_000 * input_price)
          + (output_tokens      / 1_000_000 * output_price)
          + (cache_write_tokens / 1_000_000 * cache_write_price)
          + (cache_read_tokens  / 1_000_000 * cache_read_price)

对应插件内置的公开价格表（USD / 每百万 Token，来源）：

模型	Input	Output	Cache write	Cache read
Haiku	$0.25	$1.25	$0.30	$0.03
Sonnet	$3.00	$15.00	$3.75	$0.30
Opus	$15.00	$75.00	$18.75	$1.50

注意两点：其一，cache read 比全新 input 便宜约 90%，因此开启 prompt caching 属于"无痛省钱"；其二，该价格表为公开列表价且需要人工刷新，插件文档建议在季度成本报告时对照官方定价页核对后再用于决策。

在 Agent 分档上，报告期的分层规则（见 REFERENCE 的分层说明）优先读取 [AGENT_BOOSTER_AVAILABLE] 标记，缺省时按模型名回退——haiku 归 Tier 2，sonnet/opus 归 Tier 3（未知模型从保守角度也归 Tier 3）。这样 token-usage 的按 Agent 拆分就能进一步回答"有多少高成本调用其实本可以走低成本通道"。

从分析到行动：效率优化方法论

分析只是手段，token-efficiency 命令文档 系统给出了配套的优化策略，与 token-usage 形成"体检 + 治疗"闭环。

测量：会话结束后的即时核对

文档给出了通过 MCP 工具即时查询的调用方式：

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

对应返回结构（文档示例，具体数值随工作负载变化）：

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

tokensSaved 度量的是通过缓存与复用机制省下的 Token；efficiency 给出每次操作的平均 Token 成本，是衡量协调效率的归一化指标。

三类可落地策略

1. 智能缓存：搜索结果缓存 5 分钟、会话内缓存文件内容、模式识别避免重复检索——直接压低 input_tokens 与 cache_write_tokens；
2. 高效协调：Agent 之间自动共享上下文、避免重复读同一文件、把相关操作批量合并——对应 --by-operation 视图下"操作次数多但每次开销小"的理想形态；
3. 计量与跟踪：会话后即查即改，用 session 摘要持续校准。

结合 REFERENCE 的优化策略表，可进一步按性价比排序决策：任务适配时优先走 Agent Booster（无 LLM 调用，成本趋近于零）；prompt caching 是无损收益永远该开；随后才是对稳定负载做模型降级与批量化。例如 "researcher 任务平均复杂度仅 22%" 这类信号（参考报告示例的 Optimization opportunities 段落）可以直接驱动降档决策。

预算护栏

REFERENCE 同时定义了四级预算告警（原表）：消耗 50% 记 Info、75% 记 Warning 并给出优化建议、90% 进入 Critical 建议模型降级、100% 硬停非必要 Agent 生成。token-usage --period 30d 正是月度预算盘点时核对进度的标准动作。

与相关命令、脚本的协同

要形成完整的成本治理工作流，可将 token-usage 与以下仓库资产配合使用：

• 输出形态参考：cost report 的标准展示模板（含 By tier / By model / By agent / Optimization opportunities 四段）见 REFERENCE.md 的 Cost report shape；
• 会话级摘要脚本：summary.mjs（只读聚合）与 track.mjs（采集并入库）是分析命令的离线等价物；
• Agent 技能封装：cost-report/SKILL.md、cost-track/SKILL.md、cost-optimize/SKILL.md 让 Agent 可以在会话中自主发起同类分析；
• 关联分析命令：performance-report 命令 关注 Swarm 整体性能指标，token-usage 关注 LLM 推理开销，二者一起看才能区分"慢在编排"还是"贵在模型"。

小结

token-usage 是一条把"会话 Token 消耗"从黑盒变成可量化、可拆解、可导出的分析命令：--period 控制观察窗口，--by-agent 与 --by-operation 提供两种归因视角，--export 支持离线深挖。而其背后的数据可信度，来自 cost-tracker 对 session jsonl 中 input_tokens / output_tokens / cache_creation_input_tokens / cache_read_input_tokens 四类字段的真实采集、跨厂商归一化与 AgentDB 持久化。把该命令纳入每个 Swarm 会话的收尾流程，再配合缓存优先、按复杂度降档、批量操作的策略组合，就能在维持输出质量的前提下显著压缩多 Agent 工作流的推理开销。