Gajae-Code隐私与可观测性：遥测白名单模型与本地Stats仪表盘完全指南-开发者社区

Gajae-Code隐私与可观测性：遥测白名单模型与本地Stats仪表盘完全指南

【免费下载链接】gajae-codeGajae Code MVP项目地址: https://gitcode.com/gh_mirrors/ga/gajae-code

Gajae-Code 的隐私与可观测性设计非常克制：内置遥测采用白名单模型且默认关闭，AI 用量数据则由本地stats 仪表盘统计展示。本文面向新手，带你快速搞懂 Gajae-Code 到底收集什么、如何一键关闭遥测，以及如何用本地 stats 仪表盘查看 Token、成本与工具调用趋势。

一、遥测白名单模型：默认关闭，只发固定事件

Gajae-Code 内置了一条最小化的更新与采用情况遥测通道，核心原则是：

🔒默认关闭：不显式开启，任何数据都不会发送；
📋固定事件白名单：目前仅允许 5 种事件名（update_check_started、update_check_completed、update_install_started、update_install_completed、update_install_failed）；
🚫未知字段直接丢弃，白名单外的取值在传输前即被拒绝。

每个事件只能包含：schema 版本号、固定的事件名、本地随机生成的 UUIDv4 安装 ID、ISO 时间戳、更新通道（stable/nightly）、固定结果值（available / up_to_date / installed / failed / skipped）以及固定更新方式（bun / npm / binary / migrate）。

永远不会被收集的内容

官方在 docs/telemetry.md 中明确列出了"永不采集"清单：提示词、命令行参数、路径、环境变量、密钥、账号身份、模型或服务商身份、仓库身份、错误文本、主机名、用户名、机器 ID、IP 派生身份。安装 ID 是纯随机生成，与设备、网络、账号、仓库数据无关，并以私有文件权限保存在本地用户目录的telemetry-install-id文件中。

白名单校验的实现可以直接在源码中阅读，序列化函数会在任何含"禁用键"（如 prompt、path、secret、hostname 等）的数据出现时直接失败：events.ts。

二、一键开关：如何控制遥测（含紧急杀开关）

遥测通过常规配置项控制，默认为false：

gjc config set telemetry.enabled true # 开启（可选） gjc config set telemetry.enabled false # 关闭（默认） gjc config get telemetry.enabled # 查看当前状态

此外还有一个进程级紧急杀开关，优先级高于一切配置，在事件被调度之前即被评估：

GJC_DISABLE_TELEMETRY=1 gjc update

该开关接受1、true、yes、on四种取值。

传输行为：不阻塞、不留存

事件通过 HTTPS POST 发送，采用"尽力而为"策略：调用不阻塞更新命令、最多 2 个请求在途、单请求 1500ms 超时。离线、超时、队列饱和等失败不影响 GJC 的正常行为，也不保留任何本地事件队列或日志。

三、本地 Stats 仪表盘：AI 用量可观测性

与"上报到云端"的遥测相反，Gajae-Code 的可观测性能力全部留在本地——由@gajae-code/stats包提供：解析~/.gjc/agent/sessions/下的 JSONL 会话日志，用 SQLite（~/.gjc/stats.db）增量聚合，再渲染成 Web 仪表盘。

核心指标一览

指标	计算方式
Tokens/s	`output_tokens / (duration / 1000)`
缓存命中率	`cache_read / (input + cache_read) * 100`
错误率	`count(stopReason=error) / total_calls * 100`
总成本	`usage.cost.total`求和
平均延迟 / TTFT	`duration`/`ttft`均值

快速启动本地统计仪表盘

gjc stats # 启动仪表盘，默认 http://localhost:3847 gjc stats --port 8080 # 自定义端口 gjc stats --summary # 控制台打印摘要（按角色拆分用量） gjc stats --json # 输出 JSON，方便脚本处理

仪表盘提供：总体指标卡片（请求数、成本、缓存命中率、错误率、Tokens/s 等）、时间序列图、按模型/按文件夹/按智能体（executor、planner、architect、critic 等）的拆分表格，并每 30 秒自动刷新。服务端 API 也全部本地可用（/api/stats、/api/stats/costs等，支持?range=1h|24h|7d|30d|90d|all），详见 packages/stats/README.md 与 server.ts。

💡 隐私要点：仪表盘只绑定 127.0.0.1，不支持跨域请求，也不信任转发的主机头——它天生就是一个纯本地工具。

四、深入分析：会话语料的 SQLite 分析流

如果你想在仪表盘之上做更细的挖掘，仓库内置了session-stats分析工具链：先把会话语料增量同步进同一个~/.gjc/stats.db（带ss_前缀的表），再用短小的 Python 脚本做按工具/按天/按会话的查询，重跑只需亚秒级。常用命令如bun run stats:tools（按工具统计 Token 总量）、stats:edits（编辑工具可靠性审计）等，完整说明见 scripts/session-stats/README.md。

下图展示的是分析流产出的"Top 10 工具 Token 用量趋势"六宫格图：日 Token 量、日调用数、每次调用均值、累计 Token、周中位数与单次调用直方图，可以直观看出read、search、task等工具在整体用量中的占比与演化。