mikehasa/agentacct

# agentacct [](https://github.com/mikehasa/agentacct/actions/workflows/tests.yml) [](https://pypi.org/project/agentacct/) [](https://pypi.org/project/agentacct/) [](LICENSE) **在一个永远不会离开你本地机器的仪表盘上，看清你的编程 agent 实际做了什么——以及它的成本。** agentacct 是一款本地优先的编程 agent Agent Work Intelligence 工具。它会读取 Claude Code 和 Codex 已经在你机器上写入的会话日志，将它们与每个会话在执行过程中记录的工作相结合，并在本地仪表盘上展示结果——包括 token、估算成本、任务和证据。 **设计上注重隐私。** 所有数据都保留在你的机器上：状态是纯本地文件，仪表盘绑定到 `127.0.0.1`，没有回传式遥测，没有账号，没有云同步。agentacct 永远不会存储或请求提供商的 API key。  _{截图展示的是一个合成的演示工作区；你的仪表盘会渲染你机器上真实的本地数据。} ## 你能获得什么 - **真实的用量与成本。** 基于 agent、模型和每天的 token 统计——数据读取自客户端自身的本地会话文件并标记为 `client_reported`；成本清晰标记为基于价格表的估算值，绝非实际账单。 - **是工作内容，而不仅仅是 token。** 会话会被汇总为包含已记录工作步骤和机器检查的 Tasks：通过的测试是 `Verified` 证据，而 agent 自身的声明依然标记为 `Agent reported`。 - **值得信赖的归因。** 每一次用量与已记录工作之间的关联都带有一个置信度标签（`exact`/`high`/`medium`/`low`）。缺失归因胜过错误归因：当 agentacct 无法证明某项关联时，它会将缺口展示出来，而不是进行猜测。  ## 安装 要求在 macOS 或 Linux 上使用 Python >= 3.11；Windows 仅通过 WSL 支持。 ``` pipx install agentacct agentacct onboard # from your repo root ``` 还没有 `pipx`？请先使用 `brew install pipx` (macOS) 或 `python3 -m pip install --user pipx` 安装它——或者完全跳过 pipx，直接使用 `uv tool install agentacct`。有关使用普通 `venv` 的替代方案，请参阅 [INSTALL.md](INSTALL.md)。 `onboard` 会检测你本地的编程 agent 日志，设置项目本地存储，运行首次用量同步，并启动 `http://127.0.0.1:8765` 上的仪表盘。然后在项目中打开一个**新**的 agent 会话——MCP 服务器和 hooks 会在会话启动时绑定，因此执行了 onboarding 的那个会话无法成为第一个被记录的 Task。 想让 agent 来代劳？将以下内容粘贴到正在你的目标仓库中工作的编程 agent 中： ``` Install and set up agentacct in this repo — a local-first dashboard that reads my coding-agent logs read-only and shows honest token usage and cost. Run `pipx install agentacct` (or `pipx install git+https://github.com/mikehasa/agentacct`), then `agentacct onboard` from this repo root, then tell me the dashboard URL. Observe-only: never store, request, or echo any API key; all state stays local under `.agent-sentinel/`. Don't modify my global client config without showing the exact command first. ``` 随后，该 agent 会遵循 [INSTALL.md](INSTALL.md)（标准的运行手册）进行操作：包括针对每个客户端的手动设置、机器范围的全局安装，以及完整的客户端能力矩阵。`agentacct setup prompt --agent ` 会输出相同的提示指令。 想在接触你的真实数据之前先四处看看？`agentacct demo` 会在一个一次性的临时存储中运行安全的本地演练——不需要提供商密钥，也没有付费 API 调用。 托管运行时由 `agentacct start` / `status` / `stop` / `repair` 控制；所有状态都存放在项目本地的 `.agent-sentinel/` 目录中（已被 gitignore；为了数据兼容性，该目录保留了其重命名前的拼写）。 ### 卸载 ``` agentacct stop # stop the managed sync + dashboard (owned processes only) agentacct uninstall-autostart # only if you installed autostart pipx uninstall agentacct ``` 然后，针对每个已 onboard 的项目：删除 `.agent-sentinel/` 目录（即该项目的本地账本——如果你想保留历史记录则不要删除），并移除 onboarding 添加到客户端配置（`.mcp.json` / `.claude/settings.local.json`，或 `~/.codex/config.toml`）中的 agentacct 条目。如果你安装了常驻指令块，请先使用 `agentacct setup instructions --agent --user --remove` 将其移除。 ## 它在哪些方面保持诚实 agentacct 处于早期 alpha 阶段，它宁愿向你展示缺口也不愿进行猜测： - **没有任何托管服务。** 没有托管的仪表盘，没有回传式遥测，没有自动的云账号同步。当你显式地将 OTLP exporter 指向它时，agentacct 可以在本地*接收*遥测数据。 - **估算值即被标记为估算值。** 没有获取精确 Claude Code/Codex 订阅账单的权限；成本来源于本地价格表，并已作相应标记。关于每条路径能证明和不能证明什么，请参阅 [docs/usage-truth-table.md](docs/usage-truth-table.md)。 - **无静默监控。** agentacct 仅读取已检测到的客户端的本地会话文件，从不监视在 agentacct/集成之外启动的无关进程。硬停止仅适用于由 agentacct 自身启动的运行，或由用户主动选择的代理路径。 - **支持是针对能力的，而不是针对 Logo 的。** Claude Code 和 Codex 目前具备实时观测的用量路径；其他客户端（Hermes、OpenCode、OpenClaw、Cursor）的路径较窄且范围有明确界定。针对各个客户端的具体声明已固定在 [INSTALL.md](INSTALL.md) 和 [docs/reference.md](docs/reference.md) 的能力矩阵中，并且 `agentacct capabilities agents` 会在你的机器上输出相同的真相。 在 agentacct 处于 alpha 阶段期间，接口可能会发生变化。 ## 工作原理 agentacct 将两条证据流保持独立，并通过真实的客户端 ID 将它们关联，而不是靠猜： - **用量真相**来源于客户端自身的本地会话文件：导入的 token 被标记为 `client_reported`，而成本是价格表估算值——绝非提供商账单。 - **工作意义**来源于 agent 在工作时通过 MCP 记录的部分和事件（`sentinel_record_section`、`sentinel_record_machine_check`），以及诸如测试运行之类的机器检查。 - **关联操作**通过会话/记录 ID 将两者联系起来，并将每一次归因标记为 `exact`、`high`、`medium` 或 `low`。对于 Claude Code，已安装的 hook bridge 会在会话启动时以及每次工具调用时捕获真实的会话/记录 ID；对于 Codex，这种关联是在导入时从客户端自身的会话日志中获取证据的。 针对各个客户端的关联机制、置信度标签词汇表、日常工作流、MCP 工具列表以及可选的强制执行附加功能，请详见 [docs/reference.md](docs/reference.md)。 ## 文档 - [参考手册](docs/reference.md) — 日常工作流、置信度标签、MCP 工具、客户端能力矩阵、验证证据、强制执行附加功能、迁移说明 - [安装运行手册](INSTALL.md) — 各客户端设置、全局安装、能力矩阵 - [用量与成本真相表](docs/usage-truth-table.md) - [编程 agent 集成](docs/coding-agent-integrations.md) - [架构](docs/architecture.md) - [Task Intelligence 与本地控制平面](docs/task-control-plane.md) - [多源 Evidence v2 架构](docs/multi-source-evidence-architecture.md) - [多源隐私威胁模型](docs/multi-source-privacy-threat-model.md) - [安全边界](docs/safety-boundaries.md) - [完整流程演示](docs/full-demo.md) - [实时冒烟测试证据](docs/live-smoke-results.md) - [公测 alpha 检查清单](docs/public-alpha-checklist.md) ## 开发 从克隆的代码库中运行测试（上述 pipx 安装不包含测试工具）： ``` python3 -m venv .venv .venv/bin/python -m pip install -e . .venv/bin/python -m pip install pytest .venv/bin/python -m pytest tests/ -q --tb=short ``` ## 反馈 agentacct 处于早期 alpha 阶段。有用的反馈包括： - 你使用的是哪个 agent 或工具？ - 你遇到了什么失控、成本或可观测性方面的问题？ - 哪个关联/归因结果看起来有误或缺失？ - 什么样的报告能帮助你信任某次运行？ - 下一步应该支持哪种集成？ 请提交包含错误报告、功能请求或集成请求的 issue。在分享日志之前，请务必清除其中所有的提供商 API key 或私人路径。

标签：AI编程助手, Python, SOC Prime, 代码示例, 安全规则引擎, 开发工具, 数据分析, 无后门, 本地化部署, 逆向工具