Agent 花了多少钱，不该只剩一张账单：用 Tuneloop 把会话成本归到 PR、功能与返工
AI 编码工具的账单很容易制造一种错觉：本月花了多少、某个模型占多少，看起来已经足够管理成本。但对开发团队来说，真正要回答的并不是“总共烧了多少 token”，而是“哪些已经合并的变更值得这笔钱”“哪些会话只是在反复改提示”“一次复杂排障究竟消耗了多少”。如果成本无法落到交付物和工作方式上，节流通常会退化为统一降模型、压缩上下文，结果可能连有效产出一起压低。
Tuneloop 是一个本地运行的 AI 编码会话分析工具，GitHub 元数据显示其为 TypeScript 项目并采用 MIT 许可证。它读取编程工具已经写在本机的 session transcript，建立本地 SQLite 存储和仪表盘，并将模型、工具调用、文件改动、Git/PR 结果等信息连起来。项目声明支持 Claude Code、Codex、OpenCode 和 Pi；默认的静态分析不需要 API key。需要对工作类型、复杂度、自治程度或会话结果做归类时，才可选择用自己的 LLM provider 做 enrichment。
这使它更像一层“工程成本归因”而不是另一张用量面板：总支出只是入口，重点是把会话拆开后，观察每个 PR、功能和失败路径的成本结构。
先跑一次：不要急着给 transcript 上云
Tuneloop 要求 Node.js 22.19 或更高版本。最小启动命令只有一条：
node -v npx tuneloop analyze
它会扫描常见的会话目录，例如 ~/.claude/projects，并将分析结果存入 ~/.tuneloop/tuneloop.sqlite。首次运行需要处理已有 transcript，耗时取决于存量和是否开启 enrichment；后续运行是增量的，只重新处理发生变化的会话。默认还会启动本地 dashboard；如果只想在 CI、定时任务或预处理步骤中建库，可以关闭服务：
npx tuneloop analyze --no-serve npx tuneloop serve
会话文件不必全放在默认位置。多个路径可以以逗号分隔传给 analyze，这适合把不同工作区或不同机器同步下来的归档统一进入一个分析库：
npx tuneloop analyze ~/.claude/projects,/srv/agent-session-archive
这里的边界值得明确：README 说明 session data 会留在本机；只有启用 enrichment 时，transcript 才会被送往你选定的 LLM provider。因此，对含有代码、命令输出或凭据痕迹的会话，先仅使用静态分析，再决定是否允许某一类会话做外部模型归类，会比默认全量提交更稳妥。
从“每个会话多少钱”走向“这个 PR 值不值”
Tuneloop 的核心不是把一整段长会话视为一个成本桶。它会把会话分成 block，再按 block 归因 token 成本；这样同一段会话同时修改多个任务时，PR 或 feature 不会被粗暴地平摊全部费用。README 中列出的仪表盘指标包括：每个已交付产物的成本、会话成功率、按模型/工作类型/仓库分组的总支出，以及工具和 skill 的调用次数、错误率与错误类别。
PR 关联有两条路径。第一条是显式关联：transcript 中出现 gh pr create、gh pr review 或 GitHub MCP 工具等痕迹。第二条是内容匹配：当 Agent 写完代码、开发者随后自己提交和推送时，Tuneloop 会把 Agent 产出的改动行与本地 PR diff 做匹配。后者尤其适合“Agent 不直接创建 PR”的日常流程。
这带来一个实用的复盘问题：成本高并不天然是坏事。一个高成本会话如果最终完成了高风险迁移、复杂 bug 定位或多文件重构，可能是值得的；反过来，低复杂度任务不断出现 re-steer，哪怕单次很便宜，累计起来也可能是配置、技能说明或项目约束缺失的信号。应当按“交付结果 + 复杂度 + 人工介入”一起看，而不是孤立地按美元排序。
用只读 SQL 让 Agent 参与分析，但不给它改历史
本地 dashboard 是预置视图，而 SQLite 存储允许继续追问。Tuneloop 提供 query 命令，并限制为 SELECT 或 WITH … SELECT，写操作与原始 transcript 都不开放。先查看 schema，再写针对团队约定的查询：
tuneloop query --schema tuneloop query "SELECT model, SUM(cost_usd) FROM usage_facts GROUP BY 1 ORDER BY 2 DESC"
这种只读约束很适合把查询交给编码 Agent：它可以回答“上周哪个模型花得最多”，但不能改动本地分析库。项目也提供可安装的 skill，目的是让 Agent 在生成 SQL 前先理解表、维度和粒度：
npx skills add tuneloop/tuneloop
不过，SQL 的可执行不等于指标必然正确。首先应使用 --schema 验证可用表和字段，避免把示例中的 usage_facts 当成任何版本都不变的契约；其次，向团队公开查询结果前要定义“成功”“已交付”“复杂任务”各自的口径。否则同一个“每个 merged PR 的成本”，可能把自动合并、人工合并和未建 PR 的提交混在一起。
Enrichment 的收益与成本要分账
静态分析可得到成本、工具、文件、Git/PR 结果等事实。若要获得工作类型、复杂度、自治程度、feature 名称与 success/partial/failure 判断，Tuneloop 会对每个会话发起一次结构化 tool call。它的 README 将工作类型列为 plan、implement、debug、research、review、docs 或 other；复杂度为 trivial、routine、substantial、open-ended；自治程度为 autonomous、guided、minimal。
项目支持 Anthropic、OpenAI、AWS Bedrock、OpenRouter、Ollama 及 OpenAI-compatible provider。若目标是“不让 transcript 离开机器”，可以使用本地 Ollama；README 建议为本地模型设置至少 8192 的上下文长度，并选用具备可靠 tool-call 能力的较大模型，例如 qwen2.5:7b：
OLLAMA_CONTEXT_LENGTH=8192 ollama serve npx tuneloop analyze --llm-provider ollama --llm-model qwen2.5:7b
另一个容易忽视的取舍是两层模型。每会话 enrichment 适合较便宜的模型，而跨会话的 recurring-themes detector 更依赖强模型；Tuneloop 可通过 TUNELOOP_DISABLE_DEFAULT_LLM_HEAVY=1 禁用自动选择的 heavy model，也可在配置中关闭 recurring-themes 和 kitchen-sink detector。这样做会减少分析本身的费用，但也会牺牲关于反复返工和实践偏离的自动建议。把“被分析的 Agent 花费”和“为了分析它而发生的 LLM 花费”分开记录，才不会用一个昂贵的治理层掩盖另一个成本问题。
把一次分析纳入例行复盘：一个可执行的最小闭环
不要一上来就围绕全部历史数据制定预算规则。更可靠的做法是选一个仓库和一个两周窗口，先运行静态分析，按模型、工作类型、PR 关联情况查看成本分布；随后抽查成本最高且未产生交付的数个会话，区分它们是探索性工作、真实失败，还是同一需求被反复 re-steer。只有确认 transcript 与 diff 的关联可信，才开启 enrichment，并把它的费用单独列为“分析成本”。
下一轮复盘不必盯着绝对金额，而应比较同一类工作在调整项目说明之后是否减少人工接管、工具错误或无产出会话。比如某仓库的 debug 会话持续昂贵，先检查复现步骤、日志位置和测试命令是否写进项目约定；若大量 implement 会话没有 PR 关联，则检查团队是否普遍绕开 gh 流程，或需要依赖内容匹配路径。指标用于提出可验证假设，而不是直接给人或模型贴效率标签。记录每次规则调整的日期和受影响仓库，避免把不同代码基线、不同模型价格或不同发布节奏造成的波动，误判成治理措施本身的效果。
适用边界：先用它发现问题，再回到工程约束修问题
Tuneloop 最适合已经积累了相当数量本地会话、同时有 Git/PR 工作流的个人或团队。它能把“感觉 Agent 老是跑偏”变成可检查的证据：某类任务是否成功率偏低、哪些工具错误反复发生、哪个仓库的会话总要人工接管。之后的修复通常仍在工具之外：补充 CLAUDE.md 或 AGENTS.md，收紧技能输入，调整上下文管理，或者为高风险工作设置审查门。
它不应被当作人效评分器。LLM 对复杂度、自治和成功的判断属于 enrichment 结果，不是不可争辩的事实；而 PR 内容匹配也需要接受人工抽查。更可靠的使用方式是先用仪表盘找异常群组，再抽取若干 transcript 与对应 diff 复核，最后把共性问题固化为项目规范。这样，账单才会成为改进 Agent 工作流的反馈信号，而不是一次事后的成本审判。