Skip to Content
AI 能力Argus Dev（开发期采集）

Argus Dev（开发期采集）

argus-dev 是开发者本机的轻量 Argus 上报网关（Ingestion）替代品：一条命令启动一个 与云端协议同源（HTTP + HMAC） 的本地 collector，SDK 照常上报，数据落 DuckDB 单文件、不出本机。开发调试时毫秒级写入与查询，AI / 脚本可经本地查询 API 或直接 SQL 读取。

  • 协议同源（Protocol Parity）：请求格式、字段语义、HMAC 验签与云端逐字节一致—— 「本地通过 = 云端通过」；
  • 可选加速器（Optional Accelerator）：它不是必经路径，只是开发态加速器，随时可把 SDK 指回云端；
  • 隐私：数据只写本机 DuckDB（唯一例外：verify 子命令会把核验请求发给 copilot 服务）；
  • 许可：Apache 2.0 全功能，无任何套餐限制。

源码：tools/argus-dev · 产品定义：docs/02-product/33-argus-dev-collector.md · 详细设计：docs/07-design/tool-argus-dev.md

快速开始

构建

当前版本从源码构建（brew / npm / pip 分发在规划中）。它是独立 Go 模块，依赖 DuckDB 的 CGO 绑定，需要 C 编译器（cc / clang）：

cd tools/argus-dev
GOWORK=off CGO_ENABLED=1 go build -o argus-dev .

启动本地 collector

argus-dev start --project demo

前台阻塞运行（Ctrl-C 停止），默认监听：

  • 127.0.0.1:4318 —— 上报接收（collector）
  • 127.0.0.1:4319 —— 本地查询 API

可用 --port / --query-port 改端口、--db 改数据库路径；--project-id 是 --project 的别名。

把 SDK 指向本地

在你的应用里，把 DSN 的 host 指到本地 collector 即可（DSN 概念见 DSN 与 HMAC）：

Argus.init({
  dsn: "argus://demo-public:demo-secret@127.0.0.1:4318/demo",
});

本地默认凭据为 demo-public / demo-secret，可用环境变量 ARGUS_DSN_PUBLIC / ARGUS_DSN_SECRET 覆盖。各端 SDK 的初始化方式见快速开始。

操作应用，实时看数据

argus-dev tail --level ERROR     # 实时尾随最近日志（500ms 轮询）
argus-dev status                 # 运行状态 + 端口 + DB 路径 + 各表数据量
argus-dev query "SELECT level, count(*) FROM logs GROUP BY level"

命令一览

命令用途
argus-dev start [--project <id>] [--port 4318] [--query-port 4319] [--db <path>]启动 collector + 本地查询 API（前台阻塞）
argus-dev stop [--project <id>]停止运行中的实例
argus-dev status [--project <id>]运行状态、端口、DB 路径、各表数据量
argus-dev query "<SQL>" [--project <id>]对 DuckDB 执行只读 SQL 并打印
argus-dev tail [--level <LEVEL>] [--project <id>]实时尾随最近日志
argus-dev verify [--trace <id>] [<要核验的内容>]触发 AI 可信核验（见 AI Verify）
argus-dev doctor [--project <id>] [--port ...]诊断：端口占用 / DuckDB 可用 / HMAC 凭据

接收上报：与云端同源的协议

collector 复刻云端 ingestion 的 JSON + HMAC 端点子集（监听 127.0.0.1:4318）：

POST /v1/backend/logs   后端日志
POST /v1/traces         trace span（OTel 模型）
POST /v1/apm            APM 性能 metric
POST /v1/track          行为埋点
GET  /healthz

HMAC 验签的 canonical 串与云端逐字节一致：

canonical = METHOD\n PATH\n TIMESTAMP\n sha256hex(body)
signature = base64( HMAC-SHA256(secret, canonical) )

请求头：X-Argus-DSN（公钥）、X-Argus-Timestamp（epoch 秒，允许 ±300s 偏移）、 X-Argus-Auth: HMAC-SHA256=<signature>。验签失败的上报直接拒绝——错配的 SDK 或伪造请求 无法把数据塞进本地库。签名细节见 DSN 与 HMAC。

读取数据的三种方式

1. CLI（query / tail / status）

最直接。注意 DuckDB 的单写约束：collector 运行期间以读写模式独占数据库文件，此时这些 命令的读取会自动改走 collector 的 HTTP 查询 API（对你透明）；collector 停止后才直接只读 打开文件。

2. 本地查询 API（127.0.0.1:4319，无鉴权，仅本机）

给 AI 助手、脚本、自建面板用：

GET  /api/logs?level=&user_id=&trace_id=&after_seq=&limit=
GET  /api/traces?trace_id=&limit=
POST /api/query        body: {"sql":"SELECT ..."}
GET  /healthz

例如让 Claude Code / Cursor 里的 AI 直接 curl 本地数据：

curl "http://127.0.0.1:4319/api/logs?level=ERROR&limit=20"
curl -X POST http://127.0.0.1:4319/api/query \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT trace_id, count(*) AS spans FROM traces GROUP BY trace_id ORDER BY spans DESC LIMIT 10"}'

3. DuckDB CLI 直查（collector 停止后）

数据库是标准 DuckDB 单文件：~/.argus/dev/{project}/argus.duckdb，表为 logs / crashes / apm / traces / track（云端 ClickHouse 表的简化镜像， attributes / tags / properties 以 JSON 文本存储）：

duckdb ~/.argus/dev/demo/argus.duckdb -c "SELECT * FROM logs LIMIT 10"

配合 AI Verify

本机跑一遍业务流程、trace 落到本地后，可直接在终端核验（需可达 copilot 服务）：

export ARGUS_COPILOT_ENDPOINT=http://localhost:8093   # 默认值
export ARGUS_INTERNAL_SECRET=<内部密钥>
argus-dev verify "我刚才的下单流程是否符合预期"
argus-dev verify --trace abc123

输出带证据链与置信度的核验结论，口径与 Console /verify 页一致，见 AI Verify。

verify 是唯一会把数据发出本机的操作（核验请求发往 copilot / LLM）。纯采集与查询 全程不出网。

规划中

以下能力在产品定义中但当前版本（v0）尚未实现：

  • 本地 MCP server（argus-dev mcp，让 AI 经 MCP 协议直读本地数据——当前 AI 走 127.0.0.1:4319 的 REST / SQL API）；
  • 与云端双写（--dual-write）与 SDK DEV 环境自动路由 / 回落；
  • TTL 自动清理与 clean 子命令；
  • crash / feedback / experiment 上报端点（当前为 logs / traces / apm / track 四个）；
  • share 命令（把本地 trace 上传云端生成团队可见的分享链接）;
  • brew / npm / pip 分发。

常见问题

Q：为什么构建需要 CGO / C 编译器？

DuckDB 以 C 库形式嵌入（go-duckdb 绑定），必须 CGO_ENABLED=1 且本机有 cc / clang。 GOWORK=off 是因为它是刻意独立的 Go 模块，不加入仓库根的 go.work。

Q：collector 运行时用 duckdb CLI 打不开数据库文件？

正常。DuckDB 一个进程以读写持有文件时，其它进程连只读都打不开。collector 运行期间请用 argus-dev query 或 :4319 的 HTTP API（它们经由 collector 读取）；要直连文件，先 argus-dev stop。

Q：端口 4318 / 4319 被占了怎么办？

argus-dev doctor 会检测端口占用并提示；用 --port / --query-port 换端口即可（记得同步 改 SDK 的 DSN host 端口）。

Q：本地数据会保留多久？会同步到云端吗？

v0 不自动清理也不上传：数据一直留在本机 DuckDB 文件里，删除该文件即清空；与云端双写、TTL 清理都在规划中。需要团队可见的数据请让 SDK 直接上报云端 / 自托管栈。

Q：多个项目怎么并存？

每个项目一个实例、各自独立的库文件与端口：argus-dev start --project proj_a --port 4318、 argus-dev start --project proj_b --port 4320 --query-port 4321。

AI Verify概览