一句话总结
AgentAcct 是你 AI 编程代理的「行车记录仪」：记录每一次会话的 token 消耗、估算费用、完成的任务和产出证据，全程本地运行，数据不离开你的机器。
为什么你需要 AgentAcct？
假设你是一个重度 AI 编程工具用户，每天和 Claude Code、Codex 打交道。你让它们写功能、修 bug、重构代码——但一个月后回头盘算：
- 这个月我到底花了多少 API 费用？
- 那些 AI 生成代码的提交，是「 Agent 声称完成」还是「测试真正通过」？
- 为什么同一个 repo，Codex 消耗的 token 是 Claude Code 的三倍？
没有仪表盘，这些全都是黑盒。 AgentAcct 要解决的就是这个痛点：给 AI 编码代理装上「工作智能」（Agent Work Intelligence）层。
AgentAcct 是怎么工作的？
AgentAcct 的设计哲学很简单：只读、本地、诚实。
┌─────────────────────────────────────────┐
│ 你的编码项目（本地磁盘） │
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │Claude Code│ │ Codex │ ← 写日志 │
│ │ session │ │ session │ │
│ └────┬─────┘ └────┬─────┘ │
│ │ │ │
│ └──────┬───────┘ │
│ ▼ │
│ ┌────────────────┐ │
│ │ agentacct │ ← 只读取日志 │
│ │ 只读解析引擎 │ │
│ └───────┬────────┘ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ http://127.0.0.1:8765│ ← 本地仪表盘 │
│ │ Token · 成本 · 任务 │ │
│ └─────────────────────┘ │
└─────────────────────────────────────────┘
核心流程分三步：
- 收集（Collect）：只读读取 Claude Code 和 Codex 在你机器上已有的会话日志文件，不拦截、不修改。
- 关联（Join）：将 token 消耗数据与每次会话的实际工作产出做关联，并标记置信度（
exact/high/medium/low）。 - 展示（Display）：在
localhost:8765启动一个零 JS 依赖的本地仪表盘，展示用量曲线、成本拆解和任务证据链。
关键设计：AgentAcct 不会存储或请求你的 API Key。它读的是客户端已经写在你机器上的日志，不通过任何代理转发请求。
安装指南
AgentAcct 需要 Python ≥ 3.11，macOS / Linux 原生支持，Windows 需通过 WSL。
# 方式一：pipx（推荐）
pipx install agentacct
# 方式二：uv
uv tool install agentacct
# 在项目根目录初始化
cd your-project
agentacct onboard
onboard 会自动检测你机器上的 AI 编码代理客户端日志，创建项目级本地存储，执行首次用量同步，并启动仪表盘。
验证安装成功——在另一个终端窗口中打开你的编码代理，执行一次对话任务，然后返回仪表盘刷新，应该能看到新会话的 token 数据。
# 如果想先预览效果（不触碰真实数据）
agentacct demo
核心功能解析
1. 诚实的用量与成本
这是 AgentAcct 最基本也最核心的功能。仪表盘会展示：
- 按代理/模型/日期拆分的 token 消耗量
- 成本估算（基于公开定价表计算，标注为
pricing-table estimate，而非实际账单） - 所有数据标记为
client_reported，即来自客户端自报的日志，AgentAcct 不做二次加工
这意味着你得到的是「客户端声称用了多少」+「按公开价格算出来大概多少钱」，做到知情但不误导。
2. 任务级工作追踪
比 token 统计更有价值的是工作成果验证。AgentAcct 把每一次 Agent 会话归类为 Task（任务），并关联产出证据：
| 证据类型 | 说明 |
|---|---|
Verified | 测试通过、lint 零报错——机器验证过的产出 |
Agent reported | Agent 自己声称「完成了」，但无独立验证 |
Gap | 无法建立产出关联——宁可报缺失也不瞎猜 |
这种「宁可缺失也不猜测」的态度，让 AgentAcct 的数据具有可审计性。
3. 隐私优先架构
AgentAcct 是典型的 local-first 应用：
- 所有状态存储在项目下的
.agent-sentinel/目录（纯本地文件） - 仪表盘绑定
127.0.0.1，不接受外部连接 - 无遥测、无账号、无云同步
- 永远不存储或请求 API Key
进阶功能：多项目与团队视角
虽然 AgentAcct 的核心定位是个人开发者工具，但其设计允许扩展到团队场景：
- 多项目聚合：在不同项目根目录分别执行
agentacct onboard，每个项目拥有独立的本地存储和仪表盘实例 - 模块化安装：支持
pipx install和uv tool install，两者都不会污染全局 Python 环境 - Prompt 驱动设置：官方提供了一段标准 prompt，你可以直接粘贴给 AI Agent，让它自动完成安装配置——用 Agent 管理 Agent 的仪表盘
实际使用场景
场景一：个人开发者追踪 API 费用
你同时在用 Claude Code（Claude Opus）和 Codex（GPT-5），月底想知道哪个模型花钱更多。AgentAcct 的 Cost 面板按代理和模型拆解，一眼看清楚。
场景二：团队衡量 AI 编码效率
你的团队有 5 个工程师都在用 AI 编码工具。谁是「prompt 大师」（高产出低 token）、谁是「复制粘贴流」（token 爆炸但 commit 很少）？AgentAcct 的 Task 面板能给出量化依据。
场景三：审计 AI 代码质量
某个功能声称「AI 写的」，但测试覆盖率下降。AgentAcct 的 Verified vs Agent reported 对比能告诉你：那些 AI 产出的代码是否经过了有效的自动验证。
同类工具对比
| 工具 | 定位 | 本地？ | 支持代理 | 工作追踪 |
|---|---|---|---|---|
| AgentAcct | Agent 工作智能 | 是 | Claude Code, Codex | 任务级，带证据链 |
| 各平台 Dashboard | 用量统计 | 否 | 单一平台 | 仅 token 统计 |
| OpenLit | LLM 可观测性 | 部分 | 通用 | 请求级，无工作关联 |
| LangSmith | LLM 应用调试 | 云 | 通用 | Trace 级 |
AgentAcct 的独特价值在于将 API 用量与代码产出关联，而不是单独统计 token 或单独追踪 commit。
常见问题与排错
Q: 我的仪表盘首页没有数据？
A: agentacct onboard 的当前会话不会成为第一个 Task。你需要在新终端新开一个 Agent 会话，让它产生新的日志文件，然后刷新仪表盘。
Q: Windows 可以用吗？ A: 需要 WSL。原生 Windows 支持暂未实现——这是 Python 包在 Windows 上处理进程日志的已知限制。
Q: 支持 Cursor / Windsurf 吗？ A: 目前仅正式支持 Claude Code 和 Codex。其他工具的日志格式不同，社区正在贡献适配器。
Q: 成本估算准确吗？
A: 基于公开定价表估算，标注为 pricing-table estimate。实际费用受 prompt caching、batch 折扣等因素影响，以平台账单为准。
总结
- 填补空白：AI Agent 可观测性一直是被忽视的一环，AgentAcct 是第一个专注此领域的开源工具
- 隐私优先：纯本地运行，无需联网，不接触 API Key
- 诚实设计：宁可报缺失也不做猜测，confidence label 让数据可审计
- 320+ Star / 2 天：上线 48 小时即获社区认可，需求真实存在
- 适用人群：重度 AI 编码用户、关注 API 成本的技术负责人、需要对 AI 代码做质量审计的团队
GitHub 仓库：github.com/mikehasa/agentacct 安装命令：
pipx install agentacct && agentacct onboard状态：MIT 开源，活跃开发中
数据来源：GitHub API（2026-07-26），项目 README 及官方文档。
