47 lines
6.4 KiB
Markdown
47 lines
6.4 KiB
Markdown
# Eddy 兼容知识 API(/api/eddy)
|
||
|
||
Eddy 是本地 Catalyst 原型运行时(源码仓 `tiktok/streamline_playground`)。它把"同一基线 App 上用户撞过的坑与修法"
|
||
共享给所有同基线用户,Streamline 是这条链的**审核、复验、发布与生产化**所在地,不是 Eddy 的控制面。
|
||
契约与 JSON 形状以 `streamline_playground/API.md` 为准;`streamline_playground/stub/control_plane.py` 是 CLI 端到端测试用的
|
||
参考实现(sqlite),改路由时两边同步。
|
||
|
||
## 组成
|
||
|
||
| 位置 | 内容 |
|
||
|---|---|
|
||
| `drizzle/0026_eddy_compat.sql` + `0027_eddy_releases.sql` / `control-server/src/schema.ts` | `eddy_baselines`(身份,客户端层 first-seen 登记,不可变)`eddy_releases`(官方发布:下载地址,只有管理员 / 发布流水线能写,可更新可下架;0028 加 `source` 列 = 可选的源码快照包 `{url,sha256,bytes,commit,repo}`,产品仓在 App 构建 commit 的文本文件,Eddy 侧 `baseline add` 一起下载、Agent 据此把交接里的源码位置标 verified-symbol)`eddy_problems` `eddy_observations` `eddy_installs` `eddy_fixes` `eddy_advisories` `eddy_handoffs`(只用字符串键关联,不加外键:观察可能先于基线登记到达,发布可能早于任何 seen) |
|
||
| `control-server/src/eddy_rules.ts` | 纯规则:signature 校验/别名匹配、候选 → verifying → verified → published → disabled/retired 状态机、自动停用(≥2 台机器回归,或 ≥5 样本中过半仍复现)、候选校验。`bun test control-server/test/eddy_rules.test.ts` |
|
||
| `control-server/src/eddy_db.ts` | 数据访问;`compatIndex()` 装配客户端读的索引;`ingestTelemetry()` 顺带跑自动停用;`searchKb()` 多源检索(advisory / semantic 层 kb_claims / handoffs / features) |
|
||
| `control-server/src/routes_eddy.ts` | 三个信任层:客户端层(内网任意 Mac;`X-Eddy-User` 只做归因,有 SSO cookie 时以 SSO 为准;`baselines/seen` 只收身份,请求里的 `artifact` 一律丢弃)、管理员层(SSO + admin,发布/停用/合并/派发复验;`/admin/releases/*` 和 `/admin/locks/*` 另外接受 `Authorization: Bearer $EDDY_RELEASE_TOKEN`,给发布流水线用)、卫星回调(cluster secret) |
|
||
| `satellite/src/eddy_verify.ts` + `/sat/eddy/verify` | 复验 runner:用节点自己的 Eddy CLI `compat try` 装候选 → 观察事件流 → `EDDY_DISABLE_COMPAT=1` 对照 → 回执 POST 回控制面。节点通过 `EDDY_HOME` 上报 `eddy-runtime` 能力 |
|
||
| `control-web` Management › Eddy 兼容知识 | 审核台:基线(官方发布 / 仅观测到;填下载地址发布、更新、下架)、待审候选(卫星复验 / 发布 / 拒绝)、已发布(停用 / 重新发布)、问题(状态、合并 alias)、最近观察 |
|
||
| `control-server/src/eddy_crashes.ts` | Eddy 崩溃报告(`POST /crashes`,devicesim / eddy / app 三类):存进 `eddy_observations` + `eddy_knowledge_assets`,按问题归并;管理员 `/admin/crashes*` 读取。见 [eddy/crash-reports.md](eddy/crash-reports.md) |
|
||
|
||
## 状态与规则
|
||
|
||
- 候选提交后 `candidate`;`POST /compat/candidates/:id/verify` 派发到在线且有 `eddy-runtime` 的 iOS 卫星 → `verifying`;回执 `passed=true` 时 launch-config 直接 `published`,frida-guard / native-dylib 变 `verified` 等维护者发布;`passed=false` → `rejected`。
|
||
- 遥测里每条 `install/try` 记录回流 `confirmations`;`published` 修法满足自动停用规则时变 `disabled`,下一次 `compat sync` 即从用户端 active 集合消失。
|
||
- 问题按 `(signature, baseline)` 存;维护者可把一个 signature 合并进另一个(`aliases`),客户端 lookup 同时匹配别名。
|
||
- 基线分「仅观测到」(有人 `./eddy up` 过,身份行由客户端登记)和「官方发布」(`eddy_releases` 有 published 记录)。`frida-guard` / `native-dylib` 候选只能提交 / 复验 / 发布到官方基线——卫星要装同一份 App 才能复验,而且发布会把代码放进别人的进程;仅观测到的基线(本地 import-app 的构建)只能挂 advisory / launch-config。
|
||
|
||
## 部署
|
||
|
||
1. 应用 `drizzle/0026_eddy_compat.sql`、`0027_eddy_releases.sql`、`0028_eddy_release_source.sql`(走评审过的迁移流程,不用 `drizzle-kit push` 碰生产库)。
|
||
1. 可选环境变量 `EDDY_RELEASE_TOKEN`:发布流水线(`eddy baseline publish`)用它调 `/api/eddy/admin/releases/*`,不设则只有 SSO 管理员能在审核台发布基线;Eddy 的定时自动发布还用它登记全局租约 `/api/eddy/admin/locks/*`(见 [eddy/locks.md](eddy/locks.md))。
|
||
2. 控制面可选环境变量 `CONTROL_PLANE_PUBLIC_URL`:卫星回调地址的 origin;未设时取请求的 origin。
|
||
3. 要启用卫星复验:在一台 iOS 卫星上安装 Eddy 便携包并设置 `EDDY_HOME=<包目录>`(或放在 `~/Documents/Eddy/current`),
|
||
重启卫星后 Health 面板会显示「Eddy 复验」能力。复验时该卫星会启动/停止基线 App,与正在跑的 feature/bug 任务共享
|
||
同一台机器,建议用专门的复验节点。
|
||
4. `POST /api/eddy/handoffs`(Eddy `task ship`)会调用 `createFeature` 建一个 iOS feature task,描述里带交接包下载链接
|
||
`/api/eddy/handoffs/:id/zip`;zip 以 base64 存在 `eddy_handoffs.zip`(≤ 20 MB),迁到 TOS 是后续优化,不改契约。
|
||
描述同时附人用面板链接和执行节点用的只读内网 API 链接(默认 `https://streamline-internal-api.bytedance.net`,本地部署可用 `EDDY_HANDOFF_AGENT_BASE_URL` 覆盖),以及实际 ZIP 的 SHA256。卫星先下载/解压读全套材料,不能用浏览器 SSO 面板 URL 抓到的 HTML 代替附件。
|
||
建任务要有人认领:只认浏览器 SSO 或 `./eddy auth login` 得到的 Eddy 会话(创建人 = 会话邮箱),API key 与
|
||
`X-Eddy-User` 一律 401。产品配置按基线 id 前缀反查 `EDDY_EXPORT_PRODUCTS`(`tiktokm`→tiktok、`notes`、`whee`),
|
||
查不到或该产品未启用时 400、不落库——不再静默落到 TikTok/develop。
|
||
|
||
## 未做 / 后续
|
||
|
||
- 语义检索目前是词法打分(与 KB 主库同一状态:embedding 列保留给 Phase C)。
|
||
- 跨版本 carry-forward(新基线发布时在卫星上重放上一版 open problems):发布入口已经有了(`/admin/releases/:baseline`),复验作业本身未做。
|
||
- 客户端只在 `origin=central` 的基线上共享;用户 `import-app` 的基线只用本地 advisory。
|