Files
streamline/docs/eddy.md
T
2026-11-16 17:26:44 -08:00

47 lines
6.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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。