Probe AI provider API credit, spend and quota from C — a C11 library and CLI.
用 C11 写的 AI 厂商 API 额度探测库与命令行工具。查询各厂商 AI API 的 剩余额度、周期花费与配额,并可作为核心库被桌面、网页或服务端项目集成。
仓库还包含一个 Windows 桌面界面(WPF / .NET 10),它调用本项目的 CLI 读取余额,见 gui/README.md。
状态:v0.0.1(2026-10-18 首个公开版本)· 目前仅 1 个厂商(DeepSeek 余额)· 早期项目,公共 API 仍可能变动
下载 v0.0.1 · 文档索引 · 贡献指南 · 安全策略
$ ./build/ninja-debug/bin/tokenprobe.exe --version
tokenprobe 0.0.1
$ ./build/ninja-debug/bin/tokenprobe.exe --list
ID NAME KEY ENV VAR CREDIT SPEND QUOTA NOTES
deepseek DeepSeek DEEPSEEK_API_KEY yes no no Balance only. DeepSeek exposes no usage/cost-report API, so period spend cannot be reported.
$ DEEPSEEK_API_KEY= ./build/ninja-debug/bin/tokenprobe.exe --provider deepseek
deepseek: INVALID_KEY: no API key for DeepSeek — set DEEPSEEK_API_KEY or pass --api-key
hint: set DEEPSEEK_API_KEY or pass --api-key(最后一条命令在未设置 Key 时返回退出码 1,未发起请求;Windows PowerShell 可用 $env:DEEPSEEK_API_KEY='' 清空后再运行。)
真实额度查询需要
DEEPSEEK_API_KEY或--api-key,会向厂商 API 发起真实请求;请自行确认计费与配额,不要在共享环境使用长期密钥。--list、--version与全部测试无需 Key、无需联网。
- C11 + CMake,Windows、Linux 与 macOS 跨平台。
- 依赖尽可能少:Windows 只用系统自带的 WinHTTP,无任何外部依赖; Linux 仅链接 OpenSSL(libc 不含 TLS 实现,无法避免)。
- 公共 ABI 不暴露任何第三方头文件,可被 C、C++、C#、Rust、Python (FFI) 直接嵌入。
- 可离线测试:传输层是可替换接口,完整栈可以对着录制的响应体运行, 不联网、不花钱、不需要密钥。
这是本项目最容易踩的坑,因此 API 把它们分开建模:
| 量 | 含义 | 例子 |
|---|---|---|
| credit | 某个时刻的剩余余额 | DeepSeek GET /user/balance |
| spend | 某段时间内已消耗的金额 | OpenAI organization costs |
| quota | 剩余限流额度,只能从真实推理请求的响应头读到 | x-ratelimit-remaining-tokens |
**厂商不支持的量不会产生 metric。**调用方因此总能区分"不支持"和"等于零",
不会把缺失字段渲染成自信的 0.00。能力在
tokenprobe_provider_t::supports_credit 等字段上预先声明。
金额一律用精确十进制定点数 tokenprobe_decimal_t 表示,绝不用 double:
厂商返回的是 "110.00" 这样的字符串,二进制浮点无法可靠往返。
| ID | 厂商 | 剩余额度 | 周期花费 | 密钥环境变量 |
|---|---|---|---|---|
deepseek |
DeepSeek | 是 | 否(官方无此 API) | DEEPSEEK_API_KEY |
新增厂商需在 src/tokenprobe/ 下加一个驱动文件、在 src/tokenprobe/tp_ctx.c
的注册表里登记、在 cmake/Sources.cmake 中登记源文件,并补一组离线测试,
详见 docs/guides/providers.md。
所需工具: CMake 3.21+、C11 编译器(MSVC、GCC 或 Clang)、Ninja(默认预设)、Python 3(测试门禁脚本需要)、PowerShell 7(Windows 脚本)。Windows 使用 WinHTTP;Linux 还需要 OpenSSL 开发包;macOS 由 CI 验证,本机未验证。
Windows 上 bootstrap.ps1 / check.ps1 需要 PowerShell 7(pwsh);Windows PowerShell 5.1 下实测解析失败。
Windows PowerShell
./scripts/bootstrap.ps1Linux/macOS
./scripts/bootstrap.sh日常检查(格式、构建、测试):
Windows PowerShell
./scripts/check.ps1Linux/macOS
./scripts/check.sh预设、生成器与常见错误见 docs/guides/cmake.md。
gui/ 下是一个 WPF 界面(.NET 10,框架依赖发布):
- 额度页:选择厂商并查询,金额按币种原样显示,绝不跨币种求和。
- 设置页:输入 API Key 后必须点击"校验并保存",只有真实探测成功才会用 DPAPI 加密写入本机;失败不会覆盖旧密钥。
- CLI 随应用分发:固定从
tools\tokenprobe.exe加载,界面不提供路径选择;Release 构建与发布要求先构建 release 版 CLI,否则直接失败。 - 诊断日志按天滚动(最多 5 个文件、单个 512 KB),写入前对
sk-前缀脱敏;设置页可直接打开日志目录或在 GitHub 上提交带环境信息的 issue。
构建、运行、测试与安全模型见 gui/README.md。
以下 --provider / --api-key 示例需要真实 Key,会向厂商 API 发起请求;离线可先运行 tokenprobe --list 与 tokenprobe --version。
# 列出支持的厂商及其能力(不需要 Key)
tokenprobe --list
# 查询余额(需要 Key;会发起真实请求)
tokenprobe --provider deepseek
# 显式传密钥,输出机器可读的 XML
tokenprobe --provider deepseek --api-key sk-... --xml
# 也可以输出 JSON;两种格式字段相同,差别只在编码
tokenprobe --provider deepseek --api-key sk-... --json
# 打印原始响应体以便排查字段变化
tokenprobe --provider deepseek --raw示例中的 sk-... 是占位符,不会被执行;请替换为你自己的 Key,并注意厂商计费。
周期花费、配额探测等需要额外参数的场景使用 tokenprobe_probe_ex(),
可传 tokenprobe_probe_options_t(时间范围、附加请求头、方法与请求体)。
退出码:0 成功,1 探测失败,2 用法错误。机器可读模式下失败也会输出结构化错误文档,
便于被别的程序消费。
两种格式承载同一组字段,共用同一个 schema 号;--xml 与 --json 互斥,
同时给出会以退出码 2 失败,而不是静默采用最后一个。差异只来自编码本身:
| XML | JSON | |
|---|---|---|
| 未上报的字段 | 省略元素/属性 | 写 null(键集合保持稳定) |
| 文本中的 C0 控制符 | 无法表示,替换为 U+FFFD | \uXXXX 转义,原样保留 |
| 数值 | 属性字符串 | 字符串(金额绝不做成 JSON number) |
<?xml version="1.0" encoding="UTF-8"?>
<tokenprobe schema="1" version="0.0.1">
<result provider="deepseek" display-name="DeepSeek" ok="true" http-status="200" latency-ms="12" observed-at="1760790000000" available="true">
<capabilities credit="true" spend="false" quota="false"/>
<metrics>
<metric kind="credit" id="total_balance" label="Total balance">
<amount unit="currency" currency="CNY">110.00</amount>
</metric>
</metrics>
<note>multiple currencies reported; each currency is listed separately and must not be summed</note>
</result>
</tokenprobe>{"schema":1,"version":"0.0.1","result":{"provider":"deepseek","display_name":"DeepSeek","ok":true,"http_status":200,"latency_ms":12,"observed_at":1760790000000,"available":true,"capabilities":{"credit":true,"spend":false,"quota":false},"metrics":[{"kind":"credit","id":"total_balance","label":"Total balance","period_start":null,"period_end":null,"amount":"110.00","unit":"currency","currency":"CNY"}],"note":"…"}}- 金额是字符串,保留厂商返回的精确十进制,不经
double。 - 读取方应忽略不认识的字段;只有重命名、改类型或删除字段才提升
schema。 --raw输出<raw-response>元素 /raw_response键,不会追加在文档之后。- 只有这份出站文档是机器可读格式;厂商响应一律按 JSON 解析, 见 src/tokenprobe/tp_json.c。
find_package(TokenProbe CONFIG REQUIRED)
target_link_libraries(app PRIVATE TokenProbe::tokenprobe_core)#include <tokenprobe/probe.h>
tokenprobe_context_options_t options;
tokenprobe_context_options_init(&options);
tokenprobe_context_t *ctx = tokenprobe_context_create(&options);
tokenprobe_error_t err;
tokenprobe_result_t *result = NULL;
tokenprobe_error_init(&err);
if (tokenprobe_probe(tokenprobe_provider_find("deepseek"), ctx, NULL, NULL,
&result, &err) == TOKENPROBE_OK) {
int i;
for (i = 0; i < tokenprobe_result_metric_count(result); i++) {
const tokenprobe_metric_t *m = tokenprobe_result_metric(result, i);
char amount[40];
tokenprobe_decimal_format(m->amount, amount, sizeof(amount));
printf("%s: %s %s\n", m->id, amount, m->currency ? m->currency : "");
}
}
tokenprobe_result_free(result);
tokenprobe_context_destroy(ctx);结果通过 tokenprobe_result_observed_at_ms() 提供观测时间(Unix 毫秒),
便于 UI 判断数据新鲜度。需要时间范围、附加请求头或请求体时,使用
tokenprobe_probe_ex()。
集成方的两个关键点:
- **无全局可变业务状态。**所有操作经
tokenprobe_context_t句柄,线程间互不干扰, 宿主可以一线程一 context 并发探测。平台传输层是初始化一次后只读的进程级共享实例。 - 可注入传输层。
tp_ctx_options.transport可以指向自定义传输, 包括内置的离线 mock 传输。宿主可以拿它渲染 UI、跑回放测试, 或接入自己的 HTTP 栈。
include/tokenprobe/ 公共头文件(唯一对外 ABI)
src/tokenprobe/ 实现:core、传输后端、厂商驱动
src/main.c 命令行工具
tests/ CTest 测试(vendored Unity)
docs/guides/ 主题指南
docs/adr/ 架构决策记录
scripts/ 引导、检查、格式化与发布脚本
gui/ WPF 桌面应用(.NET 10)及其测试
本仓库文档只维护一种语言:中文。
| 文档 | 说明 |
|---|---|
| docs/requirements.md | 范围、三个量的语义、平台矩阵、ABI 与扩展契约 |
| 文档 | 说明 |
|---|---|
| docs/guides/environment.md | 平台环境与工具安装 |
| docs/guides/cmake.md | CMake 预设、选项与故障排除 |
| docs/guides/coding-style.md | 命名、头文件、格式与 API 文档约定 |
| docs/guides/testing.md | 测试分层、静态分析与冒烟测试 |
| docs/guides/transport.md | 传输层后端、证书校验与已知限制 |
| docs/guides/template.md | 本项目相对标准的来源与裁剪 |
| docs/guides/providers.md | 新增厂商驱动的步骤与契约 |
| docs/guides/release.md | 发布准备与打包 |
| 文档 | 说明 |
|---|---|
| docs/adr/README.md | 架构决策记录(ADR)说明 |
| docs/adr/0001-c11-cmake-toolchain-policy.md | C11 与 CMake 工具链策略 |
| 文档 | 说明 |
|---|---|
| CONTRIBUTING.md | 分支、提交与 PR 工作流 |
| SECURITY.md | 漏洞报告与依赖处理 |
| C_PROJECT_STANDARD.md | 本仓库遵循的 C 工程标准 |
| CHANGELOG.md | 版本变更记录 |
| gui/README.md | WPF 桌面应用的构建、运行、测试与安全模型 |
本项目以 MIT 许可证 发布。