holistic-ai/surface

GitHub: holistic-ai/surface

Surface 是一款本地 AI 工具使用量与成本扫描器，在单台机器上检测已安装的 AI 工具、统计 token 消耗并折算美元成本。

Stars: 11 | Forks: 2

surface

这里运行的是什么 AI，以及它的成本是多少。

The surface dashboard running in a terminal: four cards reading $1,627 spend, 1.4B tokens, 9 tools and 12 AI sites; a stacked spend-per-day chart; and three ranked panels breaking the total down by model, by tool and by repository.

一个单一二进制程序，它会扫描你自己的机器并告诉你四件事：安装了哪些 AI 工具，你使用了哪些 AI 站点，这些工具消耗了多少 token，以及折合美元是多少。没有账号，没有 daemon，没有遥测——它只读取磁盘上已有的文件，并向你展示其中的内容。 ## 安装 ``` # macOS 和 Linux curl -fsSL https://raw.githubusercontent.com/holistic-ai/surface/main/install.sh | sh ``` ``` # Windows, PowerShell irm https://raw.githubusercontent.com/holistic-ai/surface/main/install.ps1 | iex ``` ``` #Windows, cmd.exe — irm and iex are PowerShell only powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/holistic-ai/surface/main/install.ps1 | iex" ``` ``` # Cargo，在以上三者中任意一个上 cargo install surface-cli # the crate is surface-cli; the binary is surface ``` 安装程序会检测你的平台，根据发布的 `SHA256SUMS` 验证下载内容，并将一个二进制文件放入你的 `PATH` 中——无需 sudo，无需修改配置文件。它就是 [`install.sh`](install.sh)，共 127 行，非常建议你在通过管道传输给 shell 运行之前先阅读一下。所有六个目标的预构建存档位于 [Releases](https://github.com/holistic-ai/surface/releases) 中，每个都带有你可以使用 `gh attestation verify` 检查的构建来源证明；[安装指南](https://holistic-ai.github.io/surface/getting-started/installation/) 涵盖了手动安装，并且 `cargo install` 需要一个 C 工具链来支持内置的 SQLite。 ## 使用 ``` surface # scan, then open the dashboard surface --json # scan, print JSON, exit surface --offline # never touch the network surface --check # show resolved paths and settings, then exit surface --demo # the dashboard on mock data, scanning nothing ``` `tab` 切换视图，`1`–`6` 跳转，`j`/`k` 移动，`w` 按天、周或月重新对图表进行分组，`?` 获取帮助，`q` 退出。配置是可选的：[`surface.example.toml`](surface.example.toml) 记录了每个设置及其默认值，而 `surface --check` 会打印出它查找配置的位置。 ## 读取内容 | | 查找位置 | 记录内容 | |---|---|---| | **工具** | `PATH`、配置目录、编辑器扩展、运行中的进程、已安装的应用 | 存在哪些 18 种 AI 工具，以及哪些可以在你的机器上执行代码 | | **站点** | 10 种浏览器（Chromium 和 Firefox 家族）的浏览器历史记录 | 30 个已知 AI 域名的访问次数——域名、次数、最后访问日期，没有其他内容 | | **使用量** | Claude Code、Codex 和 OpenCode 已经写入的记录 | 每天的 token 数量、工具和模型，归属于工作发生的 git 仓库 | | **成本** | LiteLLM 的公开价格表 | 以上内容的价格——如果你配置了，还会加上订阅比较 | 首次运行会读取所有记录，这在大型语料库上需要一些时间。此后的每次运行只读取新增的字节——通常不到一秒钟。 ### 它能识别的 18 种工具 **Can act** 意味着该工具可以在本机上代替模型执行代码或采取行动——这是 surface 所做的唯一判断。**Tokens** 意味着它还会写入 surface 能够读取的记录，因此它会贡献使用量和成本行；其他十五种工具被检测到，但不贡献任何数字，因为它们没有写入任何可读的内容。 | | 工具 | 厂商 | 类型 | Can act | Tokens | |:-:|---|---|---|:-:|:-:| |

| **OpenCode** | SST | coding agent | ✅ | ✅ | |

| **Amp** | Sourcegraph | coding agent | ✅ | | |

| **LM Studio** | LM Studio | local runtime | | | 每个 logo 都是工具自己的标志，设置在统一的背景块上，使该列呈现为一个整体集合，并在 GitHub 的浅色和深色主题中保持清晰可读。它们被提交在 [`docs/assets/tools/`](docs/assets/tools/) 中，而不是使用外链，因此 README 不需要任何第三方请求；每个文件的来源都记录在 [`SOURCES.md`](docs/assets/tools/SOURCES.md) 中。每个标志仍归其所有者所有的商标，此处使用仅用于标识 surface 检测到的工具。除了这些工具：跨 **10 种浏览器** 的 **30 个 AI 域名**，以及 **3 个 token 来源**。完整的表格，包括检测每个工具的确切可执行文件、配置路径、应用名称和进程，都在[覆盖范围](https://holistic-ai.github.io/surface/reference/coverage/) 中。每个表格都是尽力而为的，预计会过时——不在其中的工具只是未被报告，并没有被悄无声息地错误归因。 | | | |---|---| | **二进制文件** | 2.06 MB，静态，无运行时依赖 | | **热启动扫描** | ~400 ms — 工具 6 ms，浏览器历史 330 ms，记录 50 ms | | **冷启动扫描** | 一次 ~19 s，读取 900 MB 记录；此后 ~50 ms | | **依赖项** | 12 个直接依赖，依赖树中 99 个 | | **测试** | 246 个，没有 fixture 文件，也没有网络 | | **平台** | macOS, Linux, Windows — x86-64 和 arm64 | | **MSRV** | 1.88（由 ratatui 的 proc-macro 链设定，在 CI 中测试） | | **权限** | 无特权运行。从不提权，从不提示 | | **网络** | 一个可选请求，用于获取模型价格。`--offline` 可跳过 | 在安装了 8 个 AI 工具和拥有 900 MB 记录的 M 系列 Mac 上测量。浏览器扫描占据了热启动运行的大部分时间，因为域名 `LIKE` 过滤器无法使用索引；热启动读取记录只需 50 ms，因为它只读取新增的字节。 ## 隐私 - **不传输任何内容。** 没有服务器，没有账号，没有遥测。唯一的对外请求是获取价格表，使用 `--offline` 可跳过。 - **无消息内容**，在任何设置下都没有。解析记录仅用于获取 token 计数和模型名称。 - 浏览器历史记录中**没有 URL、路径、查询字符串或页面标题**。AI 域名过滤器在 SQLite *内部* 运行，因此你的其他浏览记录根本不会被加载——我们有一个测试，如果对话 ID 出现在结果中，该测试就会失败。 - **账本中没有路径。** 在扫描期间，工作目录会变为 git 远程仓库别名（`owner/name`），路径连同分支名称和会话 ID 一起被丢弃。这一点很重要，因为账本会被写入磁盘。 - **只读且无特权。** 从不提权，从不向其自身状态目录之外写入内容，以只读和不可变方式打开浏览器数据库。它*无法*看到的内容会被报告而不是被隐藏：Safari 的历史记录需要完全磁盘访问权限，因此它显示为不可读的浏览器，而不是悄悄地算作零 AI 使用量。详细信息请参见[隐私](https://holistic-ai.github.io/surface/guide/privacy/)。 ## 成本及其不准确之处 - **未标价不是免费的。** 价格表中缺失的模型显示为 `▲ unpriced`，永远不会是 `$0.00`，并且包含未标价模型在内的总额会标记为 `≥`，因为它只是一个底线。 - **本地模型是免费的**，显示为 `local` 而不是 `$0.00`，因为这两者含义不同。 - **这些是 API 目录费率。** 将你实际支付的费用放在 `[cost.subscriptions]` 中，Cost 视图会对两者进行比较。如果没有配置，surface 不会猜测你的套餐——它不读取任何账号状态。 - **缓存读取按缓存费率计费**，推理 token 按输出费率计费，这正是对它们加以区分的提供商所采用的方式。 ## 开发 ``` git clone https://github.com/holistic-ai/surface cd surface cargo run # scan this machine, open the dashboard ``` 四个命令，CI 全都会运行。在提交 pull request 之前请确保它们能通过： ``` cargo fmt --all cargo clippy --workspace --all-targets -- -D warnings cargo test # 246 tests, no fixtures and no network cargo run -- --json --offline # the scan must degrade, never fail ``` 需要 Rust 1.88 或更高版本。没有其他要求——不需要任务运行器，不需要代码生成，不需要子模块。测试位于它们所测试的代码旁边，并将 `SURFACE_STATE_DIR` 指向一个临时目录，因此测试运行永远不会触及你真实的配置文件。 **一个依赖项需要 C 工具链**：SQLite，通过 `rusqlite` 的 `bundled` feature 从源代码编译。浏览器历史记录和 OpenCode 的 token 存储都需要它，因此默认开启——但可以手动禁用： ``` cargo build --no-default-features # pure Rust, no C compiler needed ``` 该构建为 1.20 MB 而不是 2.06 MB，并且去除了 Sites 视图和 OpenCode token 计数，保留工具检测以及 Claude Code 和 Codex 的使用量——并且它会明确告知这一点，显示空视图。发布的二进制文件启用了此 feature，因此安装它们时永远不需要编译 C。 **文档**是使用 Material for MkDocs 构建的，rustdoc 参考文档由 `scripts/rustdoc_hook.py` 折叠集成进来： ``` uv venv && uv pip install -r docs/requirements.txt uv run mkdocs serve # http://127.0.0.1:8000/surface/ ``` 贡献者详细信息——每个 CI 作业检查什么，三类测试，为什么 release profile 省略了 `panic = "abort"`——在[从源码构建](https://holistic-ai.github.io/surface/guide/building/) 中。 ## 贡献者

## 支持

## 许可证 Apache License 2.0 — 见 [LICENSE](LICENSE)。

标签：Rust, 人工智能, 动态分析, 占用监测, 可视化界面, 成本管理, 用户模式Hook绕过, 网络流量审计, 资产管理, 通知系统