mikehasa/agentacct

agentacct – AI 编码代理的诚实工作凭证

是什么 – 一个以本地优先的实用工具，监视 AI 编码助手（Claude Code、Codex、OpenCode、Hermes 等）已在你的机器上生成的日志文件，将这些日志与代理实际执行的命令、文件修改和工具调用拼接起来，为每个任务生成一份单一的 工作凭证。该凭证显示 做了什么、花费了多少，以及 证据的可信度（代理声称、自我检查、钩子观察、CI 验证）。所有数据都保留在你的计算机上；没有云服务、遥测或 API 密钥处理。

---

核心概念

概念	含义
工作凭证	每个任务的审计式记录，列出操作、成本和每项声明的证据层级。
证据层级	四个等级 – 代理声称 < 自我报告检查 < 钩子观察退出码 < CI – 以管道形状可视化。
本地 JSON API	仅限回环的 HTTP 服务器（127.0.0.1:8765），其他脚本可查询凭证。
macOS 应用 / TUI	两个前端（原生 macOS GUI 和终端仪表板），渲染相同的凭证。

---

你能得到什么

• 每个任务一份凭证 – 显示操作（命令、修改的文件、使用的工具）、成本（实际 token 数 + 定价表估算），以及清晰的决策/证据分离。
• 深入查看 – 展开凭证以查看每个会话步骤、其生命周期、退出码检查和来源芯片（钩子、转录、MCP 记录）。
• 以证据为先的仪表板 – 最需要审查的任务会被高亮显示，带有 审查证据 按钮和简洁的“换班简报”。
• 使用情况与计划成本 – 实时提供方配额窗口、记录的 token 使用情况，以及根据你自身限制历史估算的每周 Claude 计划占比。
• 归属置信度 – 每个使用与工作之间的关联标记为 exact、high、medium 或 low；缺失的链接会明确显示，而非猜测。
• 设计即隐私 – 所有状态都存储在本地明文文件中（~/.local/state/agentacct/ 或项目本地的 .agent-sentinel/），唯一的网络监听器是本地 JSON API，且从不存储或传输密钥。

---

安装

平台	步骤
macOS (GUI)	从最新发布版下载经过公证的 .dmg，拖入 Applications，启动。该应用捆绑了 CLI 并自动接入你的代理。
macOS / Linux (CLI)	```bash
pipx install agentacct # 或 uv tool install agentacct
agentacct onboard # 检测代理，创建全局存储，启动同步与 API
agentacct tui # 实时终端仪表板

| **Windows** | 使用 WSL 并遵循 macOS/Linux CLI 步骤。 |

*接入* 不会向你的仓库写入任何文件，仅创建全局存储并在代理配置文件中注册钩子，以便未来会话被捕捉。

---
### 典型工作流程
1. **接入** 每台机器一次（或使用 `--scope project` 每个项目一次）。
2. 运行你常用的 AI 编码代理（Claude Code、Codex 等）。代理自身的日志钩子会写入会话文件。
3. `agentacct tui`（或打开 macOS 应用）—— 仪表板显示最需要审查的高优先级任务。
4. 在凭证上按 **Enter** 以查看完整审计记录，深入会话/步骤，并检查每项声明的证据层级。
5. 如果需要程序化访问，查询 `http://127.0.0.1:8765/receipts`（或 `docs/reference.md` 中记录的类似端点）。
6. 完成后，使用 `agentacct stop` 停止后台同步；通过 README 中显示的命令卸载。

---
### 它如何工作（高层次）
- **使用事实** – 直接从每个代理的本地会话文件中提取（token 数为 `client_reported`；成本基于内置定价表推导）。
- **工作意义** – 从代理发出的 MCP 事件中收集（`agentacct_record_section`、`agentacct_record_machine_check`），加上任何独立检查（测试运行、CI）。
- **关联** – 凭证通过匹配客户端 ID、会话 ID 和转录 ID 构建，并为每个归属标注置信度等级。
- **证据层级管道** – 从底层检查的独立性等级推导出的可视化指标。

---
### 谁应该使用它
- 依赖 AI 编码助手并希望获得 **审计轨迹** 以控制成本和验证信任的开发者。
- 需要 **证明** AI 生成的变更在合并前确实运行并通过测试的团队。
- 任何关心 **隐私** 并希望在不将数据发送到 SaaS 仪表板的情况下，获得完全本地的 token 使用视图的人。

---
### 当前状态
- 早期 alpha – 功能可能变化。
- 支持 Claude Code、Codex、OpenCode（完整凭证）、Hermes（使用情况 + 有限捕获）、OpenClaw（仅使用情况）、Cursor（仅存在性）。
- macOS GUI 和完整终端 TUI 可用；Linux 用户可使用 TUI。

---
### 链接与文档（如仓库中列出）
- **参考** – `docs/reference.md`
- **安装运行手册** – `INSTALL.md`
- **使用与成本事实表** – `docs/usage-truth-table.md`
- **架构与安全** – `docs/architecture.md`、`docs/safety-boundaries.md`
- **完整演示** – `docs/full-demo.md`

---
### 快速入门示例
```bash
# 安装 CLI
pipx install agentacct

# 设置全局存储并启动后台同步
agentacct onboard

# 打开终端 UI
agentacct tui

现在在任意仓库中运行一个 Claude Code 会话；仪表板将立即列出新任务的凭证。

---

总结：agentacct 为你提供了 AI 编码代理实际执行的操作、成本以及证据坚实程度的透明、本地存储的账本——且无需任何云端组件。