TelemetryLite 的 AI 集成玩法
昨天那篇里，我顺嘴提了一句：后台有个「让 AI agent 完成接入」，复制提示词丢给 Claude Code 就行。写完我越想越不对劲——这才解决了一半啊！
数据接进来了，然后呢？我想知道“这周哪个版本的用户最多”“安卓和 iOS 的购买有啥差别”，还得打开页面，选范围、切平台、一张图一张图地看。可我一天到晚泡在 Claude Code 里，凭什么这点事不能直接问它？
于是我把另一半补上了：让 AI 不光能帮你接统计，还能直接读你的统计。这一版（0.2.0）已经发布，值得单独写一篇，分享给有需要的朋友。
接入这半边：提示词里到底写了什么？
在设置页签发一把写入 key，下面的提示词就会自动把服务器地址、App ID 和刚签发的 key 填进去（key 只显示这一次，所以是先签发、后填充）。点「复制提示词」，到 App 的仓库根目录丢给 Claude Code、Codex 或者 Cursor 就行。
这段提示词我写得很啰嗦，因为 agent 最怕的就是自作聪明。它大概要求 agent 做这几件事：
1. 先识别平台和构建系统，改文件之前先说清楚打算走哪条路；
2. 在 App 启动时初始化一次：Swift 就加官方的 TelemetryDeck Swift SDK，把 baseURL 指向 服务器/k/key/；别的平台优先用官方 SDK 改 baseURL，没有这个选项就退到纯 HTTP，已经在用 OpenTelemetry 的就走 OTLP；
3. 编译项目，再用一条 curl 发个测试事件，期望返回 200（401 是 key 错了，503 是服务器忙）；
4. 改动要最小，别顺手加别的埋点、别重构。
第 3 条的检查命令长这样：
|
1 2 |
curl -i -X POST "<SERVER_URL>/k/<WRITE_KEY>/v2/" -H 'content-type: application/json' \ -d '[{"type":"Integration.test","clientUser":"agent-test","sessionID":"s1","isTestMode":"true","payload":{}}]' |
第 4 条是故意写的，不写的话，agent 很容易手痒，把你别的代码也“优化”一遍。😅
说实话，我只拿 Swift SDK 实打实验证过；其他平台服务端说的是同一套 v2 协议，实在不行还有纯 HTTP 和 OTLP 兜底。调试包发的是测试事件，在界面的「测试数据」下面能看到。
读取这半边：给 AI 一把只读的钥匙
这半边是这次新加的。设置页「读取 API key」下面可以签发一把读取 key，前缀是 tlr_（写入 key 是 tl_，一眼能分清）。它有几个特点：
1. 只绑定一个 App，key 在哪个 App 下签发，就只能读哪个 App，连 app id 都不用传；
2. 只读：拿它去上报事件，服务器直接回 403；反过来拿写入 key 去读，也是 403；
3. 进不了管理接口，也不能增删 key；
4. 随时可以吊销，立即生效。
签发之后，下面的「让 AI agent 分析数据」会把服务器地址和这把 key 填好，你只需要在框里把问题写完（这个框是能编辑的），再复制出去。
提示词就这么几行：
|
1 2 3 4 5 6 7 8 |
用我自托管的 TelemetryLite 只读 API 分析我的 App 的使用数据。 - 服务器: <SERVER_URL> - 读取 key: <READ_KEY> (放在请求头 "Authorization: Bearer <READ_KEY>" 里发送) 先从这里开始,并按它返回的说明操作: curl -s -H "Authorization: Bearer <READ_KEY>" <SERVER_URL>/r/v1/ 我的问题: <在这里写你的问题> |
提示词为什么能这么短？
因为该说的话，都让接口自己说了。agent 请求 /r/v1/，拿到的是一份“使用说明书”，顶层字段是这些：
|
1 |
['service', 'version', 'app', 'data', 'platforms', 'event_types', 'custom_parameters', 'guide_for_agents', 'examples', 'fields', 'endpoints', 'conventions'] |
里面有这个 App 的数据起止时间、平台、近 30 天出现过的事件类型、事件里带的自定义参数名，每个接口都有哪些参数，还有两块是专门写给 agent 看的：
guide_for_agents 是 4 条做事指引：先看 overview 再往下钻；出错了读 hint 自己修；结论要附上数字和时间范围，数据太少就直说别猜；别把 key 写进文件或提交到仓库。
examples 是 9 条现成的查询，比如“每日活跃用户”“各版本用户数”“某个事件按自定义参数拆分”“最近的原始事件”。agent 照着改两个名字就能跑。
这样做的好处是：以后想调整指引，改服务端就行，不用让大家重新复制提示词。
还有一点我挺在意的：参数拼错了，不能悄悄忽略。静默忽略的话，agent 会拿着一份错的结果一本正经地分析，那才吓人！所以现在是直接报错，而且告诉你该怎么改：
|
1 2 |
$ curl -s -H "Authorization: Bearer $KEY" "http://127.0.0.1:8899/r/v1/query?metirc=users" {"error":"unknown_parameter","message":"unknown parameter \"metirc\"","hint":"valid parameters here: days, since, until, test, platform, tz, format, type, where, metric, group_by, interval, order, limit"} |
真问一个问题试试
就拿截图里那个问题：“最近 7 天哪个 App 版本的用户最多？iOS 和 Android 的购买情况有什么差别？”agent 会去调 /r/v1/query，加上 format=md 让它直接返回 Markdown 表格（比 JSON 省 token）：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
$ curl -s -H "Authorization: Bearer $KEY" "$B/r/v1/query?metric=users&group_by=app_version&days=7&format=md" | app_version | users | | --- | --- | | 1.1 | 60 | | 1.2 | 49 | | 1.0 | 48 | $ curl -s -H "Authorization: Bearer $KEY" "$B/r/v1/query?type=Purchase.completed&metric=events,users&group_by=platform,payload.plan&days=7&format=md" | platform | payload.plan | events | users | | --- | --- | --- | --- | | iOS | monthly | 28 | 22 | | iOS | yearly | 24 | 19 | | Android | yearly | 13 | 13 | | Android | monthly | 11 | 11 | |
（数据是我灌的随机示例数据，别太认真哈哈。）注意第二条里的 payload.plan——它是我在事件里自己加的一个参数，query 可以直接按它分组，不用事先在后台配置什么。拿到这两张表，剩下的归纳总结就是 agent 的活儿了。
几个取舍和注意事项
1. 读取 key 只放请求头，不放 URL。写入 key 放在路径里，是因为 TelemetryDeck 的 SDK 不发鉴权头，没办法；读取没有这个限制，就别让它进 nginx 的访问日志了。
2. 读取 key 能看到事件里全部的自定义参数。统计事件里别塞手机号、邮箱这类个人信息。这跟用不用 AI 无关，但现在多了一把能读的钥匙，更要注意。
3. 没做原始 SQL 接口。聚合都走 query：指标、最多 3 个分组字段、时间粒度，字段走白名单，自定义参数也能分组。SQL 等以后真不够用了再说。
4. 有限流和超时。每把 key 每分钟 120 次请求，单个查询 5 秒没跑完就直接取消，免得 agent 手滑写个大范围查询，把写入给拖慢了。
5. 暂时没做 MCP。现在就是 curl，任何能跑命令的 agent 都能用，什么都不用装。TelemetryDeck 官方前阵子出了 MCP 服务器，思路是一样的：让 AI 直接读你的统计。我先把 HTTP 这层做扎实，以后要包一层 MCP 也容易。
怎么升级
已有的服务器，重新跑一遍安装命令就能升到 0.2.0，原来的写入 key 照常可用，SDK 那边不用动。唯一要提醒的是：0.2.0 会把数据库升到新版本，这一步不可逆，升级前最好备份一下（SQLite 是 WAL 模式，别直接 cp）：
|
1 2 |
sudo -u telemetrylite sqlite3 /var/lib/telemetrylite/telemetrylite.db ".backup '/var/lib/telemetrylite/backup.db'" curl -fsSL https://github.com/bones7456/telemetrylite/releases/latest/download/install.sh | sh |
更详细的说明在 GitHub 上的 TelemetryLite 仓库，读取 API 的完整参数见 docs/READ_API.zh-CN.md，有问题欢迎提 issue～
最后
不说了，我去把手头几个 App 的读取 key 都发一下。想想也挺有意思的：App 是 AI 写的，统计是 AI 接的，现在连看统计也交给 AI，这下是真闭环了哈哈！以后想看数据，直接问 Claude 就行，省下来的页面不用再一个个点，大概又够我 vibe 出一个新 App 了。。。😅
发表回复