AI 编程成本审计 — Agent Cost Audit

你现在运行 agent-cost-audit 技能。目标：让 coding agent 真的能审清楚这一个月在 AI 编程上烧了多少钱、烧在哪里、下一步怎么省 —— 不是“估”一个数字，而是直接读用户本机磁盘上 Claude Code / Codex / Cursor / OpenCode / Gemini CLI / Copilot 等 25 种主流 AI coding 工具留下的 session 文件，用 LiteLLM 公开 pricing 表算出真账，按 task type / model / tool / project / provider 拆好，再产出一份能直接发给老板或财务的月报。

底层是开源的 codeburn（MIT、npm 包）——课程直接消费上游 CLI。

这门课做什么（边界写在第一屏）

• ✅ 做：在用户本机一行装好 codeburn → 一次跑完 5 件套 → 产出 report.json（结构化数据）+ report.csv（财务能直接做透视）+ dashboard.png（一眼看清的可视化）+ optimize.md（A–F 健康分 + 每条可粘贴修复）+ cost-audit-monthly-report.html（一页式自包含 HTML 月报，发给老板或贴进 docs 都行）。
• ✅ agent-as-LLM：每一步「跑哪个子命令、怎么解读这一行数字、把哪条 optimize 建议落进 CLAUDE.md」由你（用户 session 里的 Claude Code / Cursor / Codex CLI / Continue）自己想。不导入任何商业 LLM 客户端 SDK、不调任何远端推理 API。
• ✅ 完全本地：codeburn 只读取本机磁盘上的 session 文件、用 LiteLLM 内嵌的公开 pricing 表算钱（本地缓存 24h），整个过程不联网到任何推理服务。可选 AI_GATEWAY_API_KEY / VERCEL_OIDC_TOKEN 仅供已经在用 Vercel AI Gateway 的用户对接，本课不要求、不写进默认路径。
• ❌ 不做：在 LLM 调用之前砍上下文（→ shrink-agent-context，本课是事后审账）；AI agent 安全健康分（→ agentguard）；公开网页的性能体检（→ agent-perf-audit）；多源跨平台话题日报（→ agent-reach）。
• 🔒 零 API key、零代理、零远端调用。本课不接 Clawvard 任何后端、不引入 Clawvard 任何 npm SDK。

一句话定位：shrink-agent-context = 调用 LLM 之前砍 token 省钱；agent-cost-audit = 调用 LLM 之后回头审账并告诉你下个月怎么省。两门正交，按用户处在哪个时点选一门。

前置条件

• Node ≥ 22.13（codeburn@0.9 的 engines.node 要求；node --version 检查）
• 本机至少跑过一种 codeburn 支持的 AI coding 工具并留下了 session 文件：Claude Code（~/.claude/projects/*.jsonl）、Codex CLI（~/.codex/sessions/*.jsonl）、Cursor（~/.cursor/sessions/）、OpenCode、Gemini CLI、Goose、Cline、Continue、Antigravity 等 25+ 种之一。codeburn 启动后会自动扫到。
• 无 GPU 要求；macOS / Linux / WSL 均可（Windows 原生未官方测试）。
• 全程本地、零商业 API key、不调用任何 Clawvard 后端、不需要 clone 任何私有仓库。

一行装好

# 用全局安装（macOS/Linux 同样）
npm install -g codeburn

# 或者 Homebrew（macOS）
brew install codeburn

# 或者每次跑都用 npx（不留本地全局）
npx -y codeburn report --period 30days

# 验装好
codeburn --version       # 应该回显 0.9.x 或更新

如果系统不允许 -g 全局装（PEP 668-style EXTERNALLY-MANAGED），用 user prefix：

mkdir -p ~/.npm-global
npm install --prefix ~/.npm-global codeburn
~/.npm-global/node_modules/.bin/codeburn --version
# 也可以把 ~/.npm-global/node_modules/.bin 加入 PATH 一次到位

工作流程（5 件套月报）

每一步都把产物落进 ./out/，不靠终端滚动。后续用户拿这五件套给老板汇报、复跑、扔进 PR 都不用再翻历史。

mkdir -p out

1. report.json —— 结构化原始数据

codeburn report --period 30days --format json > out/report.json

字段速读（与 dashboard.png 一一对应）：

• overview.cost — 30 天总美金花费
• overview.calls / overview.sessions — 总 API 调用数 / 会话数
• overview.cacheHitPercent — cache-read 占比（越高越说明 prompt 反复在缓存命中）
• overview.tokens.{input,output,cacheRead,cacheWrite} — 四种 token 实数
• daily[] — 每天 {date, cost, calls, turns, editTurns, oneShotTurns, oneShotRate}，画 daily 柱图就用这一组
• models[] — 每个模型的 {cost, calls, editTurns, oneShotRate, costPerEditTurn, ...}，看哪个模型烧得多、哪个一把过（oneShotRate 高 = 不返工）
• projects[] — 按项目目录拆，定位「钱花在哪个仓库上」
• topSessions[] — 单次最贵的会话清单，直接对应「最该回看的几次任务」
• tools[] — Bash / Read / Edit / Write 等工具调用占比

2. report.csv —— 财务能直接做透视的导出

codeburn export -f csv -o out
# 落 6 个文件：summary.csv / daily.csv / models.csv / tools.csv / projects.csv / sessions.csv

summary.csv 是 today / 7 days / 30 days 三段汇总（财务最常看的一张）；daily.csv 每天一行（画趋势图）；models.csv 每模型一行（横向对比；one-shot rate 和 cost/edit 都已经算好）；projects.csv / sessions.csv 用于定位单点。

3. dashboard.png —— 一眼看清的可视化

codeburn 自带交互 TUI dashboard，可用 1/2/3/4/5 切 today / 7 days / 30 days / month / 6 months：

codeburn report --period 30days
# 进 TUI 后按 1/2/3/4/5 切窗口、按 p 切 provider、q 退出；截屏存 out/dashboard.png

没有图形终端、或要在 CI 里跑？用第 1 步的 out/report.json 离线渲染一张 out/dashboard.png（一段 ~80 行的 matplotlib 脚本就够：daily 柱图 + 模型横向条 + 总花费 + 顶部分组数）。本课 showcase 的 dashboard.png 就是用这种方式落的——所有数字 100% 来自 report.json 的真实输出。

4. optimize.md —— 每条带 $ 估算和可粘贴修复

codeburn optimize --period 30days > out/optimize.md

输出结构（按 finding）：

• 顶部 Health 分 — A / B / C / D / F，加一个 0-100 数值分。低于 C 大概率有可省钱的修复点。
• Potential savings — 总可省 token 与美金估算（跨所有 finding 汇总，再按 finding 单独列）。
• 每条 finding：标题 + 严重度（High / Medium / Low）+ 解释 + 可粘贴修复：
  • Suggested CLAUDE.md addition (permanent rule) —— 一行规则，直接复制进 ~/.claude/CLAUDE.md 或仓库根 CLAUDE.md，对所有未来 session 持续生效。
  • One-time session opener (do NOT add to CLAUDE.md) —— 一段开场白，仅在下一次开贵 session 时粘一次，不要写进永久 rule。
  • Suggested env / mv command —— 给一条 shell 命令直接执行（典型：禁用未用的 MCP server、移动一份从未被引用的大文档、清理 cache）。

读法：先看 Health 是不是 F；然后从严重度 High 的 finding 里挑 1–3 条预计 savings ≥ $10 的，把 CLAUDE.md 那条粘进规则、把 mv / env 命令实际跑一遍；下个月再跑一次 codeburn optimize 对比。

5. cost-audit-monthly-report.html —— 一页式月报，发给老板

把前 4 步的产物在一个自包含 HTML 里渲染出来：

• 顶部 hero：本月总花费、总调用、总会话、cache hit 一行。
• 一张内联 SVG 的 daily cost 柱图（数据从 report.json.daily[] 抽出，零外链脚本）。
• model side-by-side 表（数据 report.json.models[]）。
• Top 5 expensive sessions 表（数据 report.json.topSessions[]）。
• Top 3 paste-ready findings（数据 out/optimize.md 的前三条）。
• footer：源命令 + 上游 repo + 课程链接。

参考实现见课程 showcase 的 public/skills/agent-cost-audit/cost-audit-monthly-report.html —— 完全 inline CSS、无外链脚本、无任何凭据，浏览器双击就能看，发链接给同事也能打开。

给老板的「这个月烧哪儿了」三件套

不需要把所有产物全发给非工程人。把这三件挑出来：

1. 数字：out/report.csv 里的 summary.csv（Period × Cost / Calls / Sessions / Projects 三行表）。
2. 趋势：out/dashboard.png（一张图就能告诉非工程「这个月 AI 编程花费走势 + Top 5 项目占了多少」）。
3. 行动：out/optimize.md 的前 3 条 finding（每条带 $ 和可粘贴修复），上面写「下个月按这三条落地，预计省 $X」。

需要换币种给非美元财务看？一次：

codeburn currency CNY    # 之后所有 report / export / optimize 自动按当前汇率切到 CNY

进阶用法

A. 多工具横向对比（task 2 配套）

codeburn compare --period month        # Cost/Edit、One-shot rate、Cache hit
codeburn models --period month --by-task-type   # 按任务类型把模型拆开
codeburn models --period month --details        # 看每个模型完整字段

判定原则：先看 cost/edit（哪个模型「能交付每一次编辑」最便宜）、再看 one-shot rate（高 = 不需要返工）、最后看 cache hit（高 = prompt 设计稳定）。三个都强的模型才值得在该任务类型上推广。

B. AI 写的代码到底有多少进了 main（task 2 主路径）

cd <你的 git repo>            # 必须在 git 仓库里跑
codeburn yield --period week
codeburn yield --period week --format json > out/yield.json

输出三桶：Productive（最后留在 main 的）/ Reverted（被 revert 的）/ Abandoned（写完没 commit 的）。配合 report 的总花费，可以告诉用户「本周 AI 写代码花了 $X，其中只有 Y% 进了 main」。

C. 标记本地模型 = savings

codeburn model-savings "llama3.1:8b" gpt-4o   # 本地模型 → 用 gpt-4o 价当 baseline 做 savings
codeburn model-alias  "my-internal-claude" claude-opus-4-7   # 把内部 alias 映射到 pricing 表

适用于在公司私有部署 / Ollama / vLLM 本地推理上跑的人：实际花 $0，dashboard 仍会显示「按 baseline 模型本来要花 $X，省了 $X」。

D. 自动化 / Cron 月报

# 每月 1 号凌晨 2 点跑一次，落到 ~/cost-audit/<YYYY-MM>/
0 2 1 * * cd $HOME && \
  mkdir -p cost-audit/$(date +\%Y-\%m) && \
  codeburn report --period month --format json > cost-audit/$(date +\%Y-\%m)/report.json && \
  codeburn export -f csv -o cost-audit/$(date +\%Y-\%m) && \
  codeburn optimize --period month > cost-audit/$(date +\%Y-\%m)/optimize.md

codeburn 不上传任何数据，cron 跑完产物仍只在本机。

铁律

• agent-as-LLM：所有「这条 finding 要不要落地」「这一次 session 是不是真的浪费」由你（用户 session 里的 Claude Code / Cursor / Codex CLI / Continue）自己判断。不导入任何商业 LLM 客户端 SDK；不把任何 base URL 切到任何 OpenAI-compatible 转发层、token 中继、远端推理服务。
• 五件套必须真实可复跑：每一个数字（cost、tokens、one-shot rate、cache hit）都能在 out/report.json 找到出处；每一张图都能由 out/report.json 离线重画；每一条 finding 都能在 out/optimize.md 找到原文。任何一项是 hand-typed mock / placeholder = 任务失败。
• 本地 + 隐私：codeburn 只读 session 文件、只写 ./out/；不上传任何数据；不需要任何 API key；产出的月报不要包含真实项目内部路径再发出去（敏感的话，先把 path 字段过一遍替换；本课 showcase 就是这么做的）。
• 不接 Clawvard 一方 service SDK：本课 commercialApi=false / runsLocally=true，不引入 Clawvard 的 npm SDK 包、不调用任何 Clawvard 后端命名空间。Service 化是另一门课的事，不在本课范围。
• 域名：用户可见文案里只允许 clawvard.school，不要写 clawvard.com / clawvard.co / 任何 token 中继域名。

Prompt 模板

启动 agent-cost-audit skill。我用 {Claude Code/Codex/Cursor/...} 几样混着，
请用 codeburn 做这个月的成本月报：
1) npm install -g codeburn（Node ≥ 22.13）；
2) 5 件套全部落到 ./out：report.json / report.csv / dashboard.png / optimize.md / cost-audit-monthly-report.html；
3) 给我一段不超过 200 字的中文总结：本月总花费、Top 3 高耗项目、Top 3 可落地的省钱建议（每条预计省 $）；
4) 把 optimize.md 前 3 条 finding 里的 "Suggested CLAUDE.md addition" 拼成一段给我，
   我自己手动 review 后粘进仓库根 CLAUDE.md；
5) 不要走任何远端推理服务、不要调任何商业 LLM API、不要给我加任何代理或 base URL 改写。

调试 tips

• 没数据 / codeburn 找不到 session：你这台机器可能从没跑过受支持的 AI coding 工具，先用 Claude Code 跑一次任意 session，再回头跑 codeburn。
• 总花费明显偏低：检查 ~/.codeburn/config.json 里 defaultCurrency 是不是被切到非 USD；或者你跑过 codeburn proxy-path <dir> 把一段路径标记成 subscription-backed（这段会被算作「订阅覆盖」而不是 net spend）。
• codeburn yield 报「需要 git repo」：必须 cd 进一个 git 仓库再跑；非 git 目录拿不到 commits / reverts 时间戳。
• 想把 month 改成跨财季：codeburn report --from 2026-04-01 --to 2026-06-30 --format json，导出 / optimize 同支持 --from/--to。
• 想 redact 项目路径再分享：report.json 里的 projects[].name 和 projects[].path、topSessions[].project 都按你自己的规则替换一次（一段 ~30 行 Python 就够）。本课 showcase 用的就是「项目名 → workspace-NNN」alias、session UUID 截前 8 位的同款方法，所有数字保持不动。

与相邻课的边界

• 调用 LLM 之前砍上下文 → shrink-agent-context。
• AI agent 行动安全健康分（不是花钱） → agentguard。
• 公开网页的性能体检 → agent-perf-audit。
• 多源跨平台话题日报 → agent-reach。
• 本课服务：一次性扫一台机器上所有 AI coding 工具的真实 session → 一份带柱图 / 模型对比 / Top 5 高耗 session / 可粘贴省钱清单的 AI 编程成本月报，全部本地、零 API key。

学习完成后

告诉用户：

我已经学会了 agent-cost-audit。一行装好 codeburn（npm install -g codeburn，Node ≥ 22.13），我在本机扫你所有的 Claude Code / Codex / Cursor / OpenCode / Gemini CLI / Copilot 等 session，按 task type / model / tool / project / provider 把这个月的真实花费拆好，落 out/report.json + out/report.csv + out/dashboard.png + out/optimize.md + out/cost-audit-monthly-report.html 五件套：数字真实可复跑、每条 finding 都带 $ 估算 + 可粘贴修复，HTML 月报自包含可直接发链接给同事。全程本地、零商业 API key、零代理、零远端调用。