Agent Cost Report

Agent 成本报告

Claude-Mem / Claude Code 技能。 运行时由 scripts/ 流水线构成（转录记录 → 令牌 → 美元 → Timing 风格的报告），并通过渐进式 Mem Search 复核来确认拟定的标签。Notion 草稿仅用于 SPEC 历史记录——绝不是产品、运行时或发布载体。

解析包含此 SKILL.md 的绝对目录；所有辅助路径均相对于该目录。${CLAUDE_SKILL_DIR} 是快捷方式：python3 "${CLAUDE_SKILL_DIR}/scripts/acr.py" …。仅使用 Python 3.9+ 标准库，以及 America/Los_Angeles 的 IANA 时区数据；无需通过 pip 安装任何内容。tzdata 是无需通过 pip 安装规则的唯一例外，并且只有当 acr.py 退出时提示时区数据不可用（原生 Windows Python 不附带时区数据）才需要安装：向用户显示它打印的行，并在安装前征求用户同意（AskUserQuestion）。用户同意后，运行适用于其 shell 的命令行（Bash 或 cmd 中运行不带前缀的引号命令行；PowerShell 中运行 PowerShell: 行），然后重新运行失败的命令。改为设置 PYTHONTZPATH 则无需安装。外观定义在 scripts/acr/render.py 中，绝不在此处。

目的

将 Claude-Mem 活动转化为一份便于管理者阅读的成本与失败报告。

产品构想：一项可复用的技能，通过 Mem Search 搜索 Claude-Mem，还原实际工作单元，分配成本与失败类别，并生成可打印的报告。

核心洞察

标题数字是美元，精确到小数点后两位，并注明性质。美元金额来自 Claude Code 转录记录（每条回复的令牌用量精确），并按 OpenRouter 公开标价计算，因此属于估算值。只有在经认可的数据源提供数据时，才显示实测的提供商支出。美元金额正下方应展示错误造成的成本、已交付成果，以及两者在同一时间轴上的情况。

报告必须回答的问题

1. 完成了哪些工作？
2. 每项成果的成本是多少？
3. 因循环、犹豫、走错方向、返工或路由不当浪费了多少？
4. 是否尝试过任何未经授权的操作？
5. 管理者接下来应该做什么改变？

主要指标 = 每项已完成成果的成本（而不是每条观察记录的成本）。

适用场景

• “Agent 成本报告” / “每项成果的成本” / “失败经济学” / “这次会话值不值得” / “本周 Agent 花了多少钱”
• 完成一次实际的 Mem 会话深入分析后，管理层需要了解成果的经济效益
• 需要自包含 HTML + JSON + CSV + 证据的示例包 / 发布包

记忆检索机制：claude-mem 的 mem-search 技能（渐进式回忆）。

默认范围（始终适用）

• 除非用户指定特定会话 / 时间范围 / 项目，否则时间窗口为PT 时区内最近 7 个完整日，不含今天：end = 今天开始时的 PT 午夜（不包含），start = end − 7 days。默认时间窗口绝不包含不完整的一天（G3，Alex 2026-09-25）。
• 显式指定时间范围：--start YYYY-MM-DD --end YYYY-MM-DD（PT 日历日，结束日期不包含在内）。显式指定的 --end 晚于今天时，最后一天会标记为“部分日期，生成时间 HH:MM PT”。
• 单个会话：--session <content_session_id>。单个项目加时间范围：--project <name> --start … --end …（包括该项目的工作树）。
• 报告的范围栏显示 PT 时间范围，详情中列出范围内的每个会话 ID。

渐进式记忆搜索（始终执行）

遵循 claude-mem mem-search 的三层流程。尽量减少开销。

1. 搜索 — 获取 ID 索引（标题、类型、Token 提示）。
2. 时间线 — 仅查看你关心的锚点附近内容。
3. 观察记录 — 对筛选出的、将作为证据引用的 ID 调用 get_observations。

操作流程：

1. 确定范围（默认：最近 7 个完整的 PT 日）。
2. 搜索 → 收集 ID。
3. 仅在上下文不足时查看时间线。
4. 针对意图 / 实际情况 / 结果 / 浪费 / 返工 / 阻塞 / 未授权 / 状态，获取观察记录。
5. 按命名工作项 + 失败事件分组。
6. 计算各明细项成本。
7. 生成 HTML + 可选的 PDF（+ json/csv/evidence）。
8. 在附录中保留证据 ID — 不要将完整时间线倾倒到主报告中。

ADHD 流程要点：

• 先搜索 → 选择 ID → 仅在上下文不足时查看时间线 → 只获取所需的观察记录。
• 工作项标题由你拟定，供管理者阅读（“Chroma 崩溃循环后恢复搜索”）；观察记录标题仅作证据使用。
• 证据附录列出观察记录 ID + 简短标题；主章节应优先呈现结果。

在此技能中，搜索阶段就是审核步骤（参见操作流程第 4 步）：管道根据关键词拟定类别和失败类型（label_source: keyword）；编排器根据引用的证据 ID 确认或修改每个明细项的 category 和 failure_type，并通过 review --apply 应用结果。未审核的项目保留“草拟标签”标记，页脚会统计这些项目。

工作类别（始终执行）

Feature · Bug fix · Incident · Maintenance · Investigation · Experiment

失败 / 浪费类型（始终执行）

Looping · Hedging · Wrong turn · Rework · Regression · Premature completion · Unauthorized action · Suboptimal path · Duplicate work · Blocked work · Missed requirement · Unnecessary escalation · Context re-read · Model thrash · Fan-out waste · Recovery after miss

返工锁定（始终执行）：返工只能归入 failure_type — 绝不能作为工作类别。类别应保持为预期工作类型；发生返工时，设置 failure_type: Rework。

明细项可以同时具有工作类别和失败类型（例如 Maintenance + Looping）。

成本模型

测得的 Token 数来自 Claude Code 记录（~/.claude/projects/**/*.jsonl，按 (message.id, requestId) 对助手回复去重）；Codex 记录也以相同方式读取。价格采用 OpenRouter 公布的每百万 Token 价格，在运行时获取并随报告保存。

agent_cost_i (per reply, micro-dollars) =
      input × price.input + output × price.output
    + cache_write_5m × price.cache_write + cache_write_1h × price.cache_write_1h
    + cache_read × price.cache_read                    # cache_write_1h = listed rate, else 2 × input

agent_estimated_usd        = Σ agent_cost_i over every reply in the window (matched or not)   # ESTIMATED, the headline
extrapolated_unmeasured    = observer tokens of sessions with no transcript here × (measured $ per observer token)
                           # EXTRAPOLATED (low confidence); "all sessions measured" when nothing remains
observer_note_taker_est    = note-taker (observer) tokens, deduped per reply, × its input list price
                           # priced separately, never agent cost, never in the headline
mistakes_estimated_usd     = Σ agent_cost_i over the same-session union of wasted turns, each turn once   # low figure
cost_per_completed_outcome = Σ attributed $ for status ∈ {shipped, completed} / count(those work items)
waste_rate                 = Σ wasted_cost / Σ attributed $     recovery_share = Σ recovery_cost / Σ attributed $

明细项以会话为单位：attributed_usd = 估算值（此设备上有记录）或外推值（无记录）。wasted_cost 和 recovery_cost 来自行为分析阶段（如下），并使用同一并集，适用于横幅、明细项和错误行。上限（重做时间窗口加项目级回退值）保留在 Details 中。

已阻止的未授权操作：direct_cost 为 $0，risk_exposure 为 high，action_status 为 blocked。除非涉及实际现金损失 / 补救成本，否则始终将 risk_exposure 保持为非美元值 — 绝不臆造风险金额。

confidence — Token 数、模型和结果明确时为 high；按观察记录分配时需作判断则为 medium；证据不足时为 low。

未定价的模型（价格列表中没有，或价格为负数的“variable”）会按名称列出并附上其 Token 数，不计入任何费用；绝不会默默按零定价。

行为指标（审核前为启发式）

对相同的对话记录进行第二轮分析，将每个用户轮次标记为 human / bot / unknown（转发的 Agent 提示词绝不是 Alex 说的话），找出挫折事件，并运行 Frustration Arc 研究中的模式检测器：捏造人工关卡、破坏原本可用的功能、模型错误或成本过高、过度设计、做了未被要求的事、虚假输出、错误声称“已完成”、工具或联系人错误、错误的外发内容（事件数 × 收件人，绝不以美元计）、记忆或规则丢失、术语难懂、原因不明，以及工具错误和模棱两可（按 Alex 的定义：答案明明已经可用，却仍附带保留意见）。四个摘要磁贴；其他内容都放在 Details 中。所有计数在审核或分类前都标记为 heuristic。可选分类器（--classify）默认关闭，每次运行的上限为 $2.00，仅使用常规推理 OPENROUTER_API_KEY，其花费会单独显示。

费用标注（始终适用）

标签	含义
Measured	来自认可来源的提供商报告花费（目前：OpenRouter 每个密钥的快照，并显示其 UTC 时间桶标签）
Estimated	已测量的对话记录令牌数 × OpenRouter 每百万令牌（MTok）标价（使用上述公式）
Extrapolated	本机上没有对话记录的会话，根据观察者令牌比例推算；始终标记为“低置信度”
Unavailable	没有已测量的值——写作 measured spend unavailable；未知时绝不能写 $0 spent
risk_exposure	严重程度／定性评估，除非涉及实际现金支出（席位、退款、SLA）

每个明细行的 cost_basis：estimated_usage、measured_provider 或 extrapolated。所有金额均显示到小数点后两位（$109.25）；每个数字都带有标签和依据。

明细项架构

line-items.csv / report.json.line_items 中的每一行：

字段	说明
work_item_id	稳定 ID（WI-1 …）
title	人类可读的工作项标题（审核时必须填写；草稿使用会话中的第一条提示词）
scope / project / worktree	周期、会话或项目；主要项目；相关时填写工作树
session_ids / content_session_id	Mem 会话 ID 和对话记录关联键
status	shipped / completed / in_progress / abandoned / blocked
category / work_category	六种工作类别之一
failure_type / failure_signals	空值或失败类型（返工归于此处）
cost_measured	数值或 unavailable
cost_estimated / cost_extrapolated / attributed_usd	标价估算；无对话记录会话的推算值；实际采用的值
wasted_cost / recovery_cost / productive_cost	行为合并数据中的美元金额（若无则为 0）
risk_exposure	none / low / medium / high（除非涉及实际现金，否则不以美元计）
evidence_ids / summary_ids	观察记录和摘要 ID
agent_tokens	{input, output, cache_write_5m, cache_write_1h, cache_read}
observer_tokens	记录者令牌数，仅在 Details 中显示
model / model_prices_usd_per_mtok	主要模型和使用的价格
cost_basis	estimated_usage / measured_provider / extrapolated
label_source	keyword（草稿）/ llm / human，以及 reviewed_by 和 reviewed_at_pt
device	local、remote-N 或 mac 等导出标签
behavior_counts	此会话中的模式命中次数
recommended_action / confidence / date_pt / notes	一项改进措施；高／中／低；PT 日期；一句通俗说明

交付物（始终）

acr.py 会写入一个目录，其中包含：

1. report.html — 独立文件（内联 CSS、无脚本、无外部资源），采用 Timing 风格
2. report.pdf — 使用无头 Chrome 从 report.print.html 生成（PATH 中有 google-chrome 时使用；否则在 macOS 和 Windows 上使用 Chrome 的标准安装位置）；若缺少 Chrome，运行结果会显示“已跳过 PDF，HTML 为权威版本”
3. report.json — window、scope、spend、totals、by_day、by_model、by_device、line_items、wins、behavior、timeline
4. line-items.csv — 每个工作项一行
5. evidence.json — 引用的观察 ID、简短标题、观察者令牌、模型、会话 ID
6. labels.review.json — 为审核阶段草拟的标签

面向管理者的 HTML 版块（顺序必须如下）

1. 主视觉区 — 金额及其标签（ESTIMATE / MEASURED）、计算依据说明、“完成了 N 项工作，平均每项约 $X”、外推数据行、适用时显示“实测供应商支出：不可用”，以及故事句（通过计算生成，不得手动编写）
2. 成果与错误 — 错误成本行（较低估值）、已交付成果（已合并 PR、已发布版本、表扬；在会话与 PR 建立关联之前，成本标记为“未测量”），以及共用一条 PT 日轴的两条时间线
3. 成本带 — 每项工作显示为按成本调整大小的区块；浪费部分用斜线填充，进行中的部分用条纹填充
4. 资金去向（按工作类型绘制的环形图）· 逐日情况（堆叠条形图；空白日期显示“无 Agent 工作”）· 有效程度（环形图，以及最多包含四个图块的行为条带）
5. 完成的工作 — 每个工作项显示一行可折叠内容，按成本从高到低排列，并标记草拟标签
6. 值得关注的事项 — 最多三项，通过计算生成
7. 详情与证据（可折叠；在 PDF 中展开）— 成果、按日划分的错误、含上限的行为模式表、规则有效性、支出与定价、模型、失败核算、工作项、设备、未匹配的转录、未定价的模型、标签数量、真实性规则，以及 CSV 和 JSON 的链接

真实性规则（始终遵守）

仅适用正向真实性规则：

1. 始终标明估算值还是实测值（cost_basis = estimated_usage 或 measured_provider）。
2. 始终在存在未匹配项时说明实测支出不可用——未知时绝不声称“支出 $0”。
3. 始终以已完成的成果为单位（每项已完成成果的成本）。
4. 始终将 risk_exposure 记为非美元金额，除非涉及真实现金支出或补救成本。
5. 始终为工作项编写虚构的人类可读标题；观察标题仅作证据使用。
6. 始终渐进式使用 Mem Search；证据 ID 放在附录中。
7. 始终只在 failure_type 下归类返工。
8. 默认始终将范围设为最近的会话，除非用户指定其他范围。

重建版本新增的规则，精神相同：记录员的成本单独列出，绝不纳入标题数字；关键词标签在审核前均为草稿；Grok Bot 和 Mac 的数据标记为“不可用”或“外推（低置信度）”，绝不记为 $0，也绝不猜测；实时数据库只能以只读方式打开（每次运行都使用快照）。

操作流程（编排器）

所有命令都从技能目录运行；OUT 是一个运行目录（例如 /tmp/acr-weekly/run）。每个步骤都可幂等执行。

1. 价格 — python3 scripts/acr.py prices --out $OUT（OpenRouter 列表价格；使用 --prices <saved prices.json> 可离线运行；无需密钥）。
2. 收集 — python3 scripts/acr.py collect --out $OUT（默认时间范围），或 … --start YYYY-MM-DD --end YYYY-MM-DD、… --session <id>、… --project <name> --start … --end …。
3. 汇总 — 使用相同的时间范围标记运行 python3 scripts/acr.py rollup --out $OUT。生成 report.json、line-items.csv、evidence.json、labels.review.json。选项：--no-gh（跳过只读的 gh pr view 合并 PR 确认）、--classify（见上文）、--rules-dir <house rules>（规则有效性）。
4. 审核 — 对 labels.review.json 中的每个条目，使用其 evidence_ids（而非完整时间线）调用 get_observations，确认或更改 category、failure_type、status 和标题；在审核后的文件中填写 reviewed_by（模型 ID 或 Alex）；使用 python3 scripts/acr.py review --apply <reviewed.json> --out $OUT 应用。未审核的条目仍会标记为“草稿标签”。
5. 渲染 — python3 scripts/acr.py render --in $OUT/report.json --out $OUT --print。
6. PDF — python3 scripts/acr.py pdf --out $OUT（若缺少 Chrome，则会显示消息并跳过）。
7. 可选，需 Alex 批准 — 实测 OpenRouter 支出：在环境中设置常规推理密钥后，在步骤 3 之前运行 OPENROUTER_API_KEY=… python3 scripts/acr.py measure-openrouter --out $OUT。如果没有密钥，文件会显示 unavailable，其他内容不变。
8. 可选，需 Alex 批准 — Mac 导出合并：python3 scripts/acr.py rollup … --device-usage <device-usage-mac.json>（见“差距和门槛”）。
9. 返回绝对路径、技能标识 agent-cost-report、带标签的主要金额、错误行、成果、PDF 是否生成，以及报告如何回答五个产品问题。

缺口与门槛

以下每项都需要 Alex 明确批准；在此之前，报告会显示真实的备用结果。

• OpenRouter 密钥（需要 Alex 批准） — 通过团队的安全密钥流程，以环境变量形式提供常规推理用的 OPENROUTER_API_KEY；绝不使用管理或配置密钥，绝不从设置文件读取，也绝不打印或写入任何输出。每密钥端点提供 UTC 日／周／月快照，因此图表会显示其时间桶标签；只有当时间桶完全覆盖报告时间范围时，才会将主视图切换为 MEASURED。按天提供范围数据的来源（/api/v1/activity）确实存在，但需要管理密钥，因此不会实现（G5）。
• Mac 转录记录（需要 Alex 批准） — Alex 的 Mac 上没有会话转录记录，因此在合并设备导出数据之前，这些会话的费用为 EXTRAPOLATED（置信度低）。Alex 可以在 Mac 上从此技能的普通检出目录运行以下命令（系统 python3 3.9+），并分享 ~/acr-export/device-usage-mac.json（包含 ID、时间戳、Token 数量、模型名称；不含提示词或观察文本、设置或路径）；或者，仅在 Alex 明确批准该次运行（指定时间范围、机器和目标位置）后，由协调 Agent 通过团队的注册机器工具在已注册的 Mac 上运行同一命令，并仅将 device-usage-mac.json 复制到此机器。一次运行的批准不代表批准下一次（G6 仅覆盖 Sep 18–26）。使用 --device-usage 合并；关联的会话会变为 estimated_usage，并标记 device: mac。
• Grok Bot（始终不可用，不统计席位数） — Grok Bot 是 Cursor 的云端 Agent。Cursor 仅在方案页面显示其每周用量；没有 API 或导出功能，团队也没有用于它的 xAI 密钥。报告会准确显示“Grok Bot usage: unavailable”（G4）：不显示金额、不猜测每席价格，也不统计席位数。Alex 手动提供的数字会以 measured_manual 录入，并标记 entered_by: Alex 及日期，不会推断得出；这需要另行决策。
• 来自 GitHub 的成果（只读） — 除了此机器上的转录记录和发布观察结果，rollup 还会通过 gh pr list --state merged 列出 --wins-repo 指定仓库（默认为 thedotmack/claude-mem）中已合并的 PR，按 PT 时间范围内的合并时间筛选，并根据仓库和 PR 编号去重。如果缺少 gh、未通过身份验证或受到速率限制，该来源会在 Details 中显示“unavailable”，但报告仍会完成；绝不会显示为零。--no-gh 会关闭所有 gh 调用。
• 成果费用（在 R4 前未测量） — 目前会话尚未关联到 PR，因此每项成果都会显示“unmeasured (session not linked to PR)”。当提交附带 Claude-Session: <content_session_id> 标记（G13：仅限标记行，不带其他内容的 ID）后，PR 和发布成果将显示费用 ESTIMATED · session-linked。没有备用估算值（G11）。
• 合并到 main、发布 npm、/version-bump — 每项都需要 Alex 单独批准。推送工作分支和开启 PR 属于常规操作。

同步副本

插件目录是事实来源。python3 scripts/acr.py sync-check 会将 SKILL.md、CHECKSUMS.txt 和 scripts/** 与团队副本（~/agent-data/workflows/agent-cost-report/）以及四个镜像插件（claude-mem-cursor、claude-mem-grok-bot、cowork、openclaw，每个都位于 skills/agent-cost-report/ 下）进行比较；如果存在差异，则以状态码 1 退出。--write 会将插件内容复制到目标位置并重新检查（G2）。CHECKSUMS.txt 兼容 sha256sum -c。

相关内容

• claude-mem mem-search 技能 — 渐进式回忆
• plans/2026-09-25-agent-cost-report-weekly.md — 重建计划、G1–G16 决策及验证目标

信条

Claude-Mem 技能 · 结果优先 · 明确标注估算 · 默认显示最近内容 · 在 failure_type 下记录返工 · 渐进式回忆 · HTML 为权威版本 · 让人们看到 Agent 做了什么，以及为何产生费用。