Initial import of streamline

This commit is contained in:
2026-11-16 17:26:44 -08:00
commit 8e4aec1855
1221 changed files with 274256 additions and 0 deletions
+99
View File
@@ -0,0 +1,99 @@
# Feature 导出到 Eddy
在任务详情的「接力到本地」中选择 Claude Code / Cursor 的 Markdown 文档,或 iOS feature 专属的「准备 Eddy 接力包」。Eddy 由任务卫星机(离线时由同集群的其他 iOS 卫星机)生成临时 App 基线,列表和详情展示进度,成功后飞书通知。用户将 App ZIP 和源码 ZIP 放到同一目录,在 Eddy「基线」安装 App ZIP,再把 RELAY.md 交给本地 Agent。Android 保留普通 Markdown 接力,不显示 Eddy 选项;接口和卫星机解析同样拒绝 Android。
这是 feature 的独立导出作业,不改变 feature 状态、不合并 MR、不发布到 Eddy 官方基线目录。首版支持 `manual_review`、`completed` 且有已推送 MR 分支、已知 `repoKey` 的 iOS feature。
## 执行和交付约定
1. 控制面认证点击者,选定执行导出的卫星机(见下文「哪台卫星机导出」),复用普通接力的报告、反馈历史和执行摘要。共用起点规则:人工复核用任务分支,确认已合入用配置的基线,合入记录未知时先任务分支、明确不存在才退回基线;网络失败不触发回退。Feature 的合入状态通过匹配仓库/源分支的 Bits 只读查询补充。卫星机把所选远端起点解析为完整 SHA,文档记录实际分支和提交。
2. 服务端持久化提交、构建说明 hash、任务/MR 和完整接力文档快照。相同 feature、提交、分支、构建说明及上下文的有效作业复用;每个请求者各有通知记录。反馈/报告变化时新建快照,不把旧上下文当作刚生成的接力文档。
3. 卫星机在串行 implementation scheduler 内领取作业,先获取与 Asking 共用的 checkout 锁。导出占用节点,不与下一次实现、Asking 代码修改或 Eddy compat 验证并行;控制面热部署等待该作业结束。控制面把构建到上传这几个阶段的导出计入该节点的执行槽(`countSlotsPerNode`),所以节点卡片显示「执行 1/1」和「Eddy 导出 · <任务标题>」(`GET /api/eddy-exports/running`,点开进入该 feature),调度台和导出改派也不会把它当成空闲节点。
4. 在独立目录 clone 产品仓,在分支名上检出固定 SHA(`git checkout -B <分支> <提交>`,源码包和接力文档从这里出),再把节点的共享检出(`$AI_WORKSPACE/TikTok`)固定到同一提交(先用验证任务同一个 `checkoutChangeCommit` fetch 分支、`checkout -f --detach`、`clean -fd`,再 `checkout -B <分支> <提交>` 放到分支名上——`airb sync` 按分支名取提交,detached 的需求分支提交远端取不到(`Commit not exist in codebase`);本地分支若有会被丢掉的提交,先存到 `refs/eddy-export/backup/`),并从官方 `eddy/LATEST` 获取 runtime(验证发布 ZIP hash 和分发 MANIFEST;只复制分发清单文件,不复制卫星机 Eddy 的账号、任务、已安装 App)。
5. **构建由智能体按 DeviceSim 的 `Skill(airbuild)` 完成**——和该节点修复/验证任务出包是同一套做法,构建细节只维护在 skill 里(「工程专用」的 TikTok 与 TikTokNotes / Whee 两节)。智能体在共享检出上用它已绑定的 airspace 构建(和修复/验证任务一样;**不 `airb init`、不 `airb release`**——每人只有 2 个空间,原先每次导出新开一个、失败的还保留,配额满后导出全部在 init 失败),把产物 `airb pull` 到作业的 `build/`,并写回执 `airbuild-receipt.json`。随后 worker 只认:独立 clone 与共享检出的 HEAD 都不变且无改动/新文件、`build/` 里恰好是声明的那个 `.app`、回执的产品与提交与作业一致。回执是构建声明,作为 `BUILD.json` 进包;源码包始终按固定提交切。
6. 打包直接调用 Eddy 的 `portable/build_app_baseline.build`(runtime `2026.10.15-eddy-home.12` 起支持 `extend`):先在作业目录的 `DEVICESIM_ROOT` 里装好 DeviceSim(runtime `2026.10.23-eddy-home.18` 及以前用包里随附的;之后的 runtime 不带 DeviceSim,由 Eddy 从 DeviceSim 官方渠道下载最新 stable,所以卫星机要能访问办公网下载入口),用它经 cat-supervisor 完成转换、注入和签名,切源码包、写基线;导出只通过 `extend` 加入任务来源、`BUILD.json`、`RELAY.md`、`INSTALL.md`,产物在作业目录的 `package/artifacts/`。冒烟后由 Eddy 的 `devicesim_install.stop_capture_daemon()` 停掉从作业 DeviceSim 拉起的截图 daemon。`DEVICESIM_ROOT`、`EDDY_STATE_DIR` 和 cat-supervisor 的实例目录都落在作业目录里,不切换、不触碰节点自己的 `/Users/Shared/DeviceSim` 与 `~/iosapp`。
7. 在作业自己的 runtime / state 下安装 ZIP、DeviceSim 选 `installed`(即上一步在作业目录里启用的那份),启动 App 并运行 Eddy smoke。要求原生连接 active、无产品编辑、无 Frida engine attach、产出有效 PNG。此检查证明基线可启动、可截图,不等于 feature 的业务验收。
8. 两份 ZIP 经 SHA-256 和长度检查后,由卫星机直传 TOS。服务端仅签发该作业对象的 PUT 请求,不给卫星机 AK/SK:签的是 **TOS 临时签名**,地址是桶的**内网子域名** `https://<bucket>.tos-cn-north.byted.org/<key>`,2 小时内有效,每次重试重新签发。不能用图片上传那套 S3 签名:卫星机在办公网,办公网 DNS 只解析内网子域名,`tos-s3-cn-north.byted.org`(任何形式)和裸 `tos-cn-north.byted.org` 都解析不了。临时签名是 TOS 文档(「TOS 临时签名」「不同环境如何访问 TOS」)给无 Consul 环境的上传方式,HMAC 的 key 是桶的 access key,签的是方法、路径、签名名称和过期时间,不含内容摘要,所以字节的正确性由卫星机上传前的预检和控制面随后的回读保证。控制面从用户下载地址流式回读两份文件并校验;完成请求立即返回 202,校验在后台运行,卫星机继续心跳及查询。
9. 只有回读成功才标记 ready、开始 7 天有效期并发送飞书卡片。卡片链接回任务详情,避免保存一个即将过期的直接下载地址。
产物:
- `baseline-<baselineId>.zip`:App、DeviceSim、baseline.json、MANIFEST.json、安装说明及 feature 上下文。
- `baseline-<baselineId>-source.zip`:Eddy 标准源码快照,严格对应同一提交。包含受支持的 tracked 文本文件,不是完整 Git 仓或可直接重编译的全量依赖副本。
- 卫星机保留 `build.log`、`result.json`、`verification.json`、`smoke.png` 等诊断材料。作业结束清理源码检出、runtime 副本及大型中间产物;若原生停止失败则保留 runtime/state 供排查。
## 配置与部署
默认 `EDDY_EXPORT_ENABLED=0`。开启前须部署控制面、shared 和卫星机代码,按仓库正常发布流程应用 `drizzle/0033_eddy_feature_exports.sql`。该迁移仅新增两张表和索引,可重复执行;回滚代码时关闭开关即可保留历史记录。
控制面配置:
| 配置 | 用途 |
| --- | --- |
| `EDDY_EXPORT_ENABLED=1` | 启用创建、下载、节点执行及维护 |
| `CLUSTER_SECRET` | 可选,与集群其余接口一致:配置了就校验,控制面和卫星机须相同;留空则不校验 |
| `TOS_ACCESS_KEY`、`TOS_SECRET_KEY`、`TOS_REGION`、`TOS_S3_ENDPOINT`、`TOS_BUCKET` | 导出与图片上传共用同一套配置和 bucket;导出上传用 `TOS_ACCESS_KEY` 签临时签名 |
| `EDDY_EXPORT_TOS_DOMAIN` | 可选,导出上传用的内网子域名根,默认 `tos-cn-north.byted.org`(桶在其他区域时改成对应的内网子域名) |
| `APP_BASE_URL` | 飞书卡片返回任务详情的地址 |
| 现有 Lark 机器人凭据 | 就绪通知;未配置时产物仍可下载,通知保持待发 |
对象固定落在 `eddy/task-exports/<exportId>/<sha256>/<filename>`,下载地址由 `shared/src/protocol.ts` 的 `TOS_DOWNLOAD_BASE` 拼出,与图片上传同源。在 TOS 为该前缀配置 **8 天生命周期**,覆盖上传至校验完成的时间和随后的 7 天下载窗口。API 的过期检查不等于物理删除,已经拿到的直接 URL 在对象删除前仍可能有效。失败产生的对象也由同一生命周期清理。首版单文件上限 4 GiB,使用单次 PUT,不做分片上传。
卫星机需要已解锁的 Apple Silicon macOS 15+ 会话、Xcode 工具、产品仓读取权限、到控制面的网络、能解析并访问 TOS 内网子域名 `<bucket>.tos-cn-north.byted.org`(办公网默认可以),并有足够容纳源码和数份 App 副本的磁盘空间。
**卫星机不需要任何导出专用配置。** 只要具备修复/验证任务出包本来就用的两样——PATH 上的 `airb`(且已登录 Airbuild)和 DeviceSim 的 airbuild skill(`<AI_WORKSPACE>/.claude/skills/airbuild` 或 `~/.claude/skills/airbuild`)——就会领取导出。缺任意一样时,「准备 Eddy 接力包」会直接报出缺的是什么。
接力对话框的导出记录会写明由哪台卫星机执行;排队时说明在等什么(卫星机正忙、已离线、刚等待领取),改派过的会注明接力文档里没有修复报告。
**哪台卫星机导出。** 任务卫星机在线就由它导出,它报的错(缺 airb、查不到远端分支等)原样返回。离线时改派:导出只用远端已推送的提交、独立 clone、Airbuild 远端构建和官方 runtime,不读执行节点磁盘上的任何东西,唯一拿不到的是修复报告(接力文档里会标注未能获取)。候选是在线、iOS、集群标签与该 feature 相交、不是实验机(`manual-only`)的节点,空闲的排前面;控制面同时请它们解析起点,选排名最靠前且解析成功的那台,作业从此只派给它。都不行时报错里列出各节点的原因。改派占用的是那台卫星机的时间和它共享检出已绑定的 Airbuild 空间。
**构建什么由任务决定。** `product` 取自 feature 的 product profile id(无 profile 时回落成 `tiktok`),在 `shared/src/eddy_export.ts` 的 `EDDY_EXPORT_PRODUCTS` 里查到 Eddy 目标名、产物名和启动参数;**怎么构建**只写在 DeviceSim airbuild skill 的「工程专用」里,Streamline 不再维护任何构建脚本或节点配方。目前支持:
| product | skill 一节 | 产物 | Eddy key | 启动参数 |
| --- | --- | --- | --- | --- |
| `tiktok` | TikTok | `TikTokM.app` | `tiktokm` | `-skipForceLogin` |
| `notes` | TikTokNotes | `TikTokNotes.app` | `notes` | 无 |
| `whee` | Whee | `Whee.app` | `whee` | `-skipForceLogin` |
`lemon8` 等表里没有的 product 会干净报错「该产品还不支持导出到 Eddy」,不会误编成别的 App。新增产品 = 先在 skill 里写清它的构建,再在表里加一行。
- `EDDY_EXPORT_ROOT` 默认 `~/.streamline/eddy-exports`;`EDDY_EXPORT_PYTHON` 默认系统 Python。官方 runtime 包缓存固定在 `~/.cache/streamline/eddy`。
- Eddy 更新不会覆盖节点的现有安装。每次作业从最新官方分发生成隔离 runtime,并将实际版本留在回执中。
## 重试与排查
状态为 `queued → building → packaging → verifying → uploading → ready`,中途可失败。执行租约为 120 秒,卫星机每 20 秒续租;失联或进程重启后作业失败,旧 lease 的回报不能覆盖新状态。排队中的作业只派给选定的那台卫星机:它超过 10 分钟没有心跳,作业标为失败,「导出当前提交」会重新选卫星机(短暂离线如部署重启不受影响);排队超过 24 小时同样失败。失败或过期时点「导出当前提交」,会重新解析当时的分支 SHA 并新建作业。
断线后的完成确认可以重复请求;已经 ready 的作业直接返回既有结果。上传清单固定后不能换文件内容。飞书通知单独重试,常规重复点击不重复通知;极端情况下发出成功、落库前进程崩溃,通知可能重发一次。
日志在 `<EDDY_EXPORT_ROOT>/<exportId>/`:`build.log`(worker 各阶段)、`build-agent.log`(构建智能体的会话流)、`airbuild-receipt.json`(构建回执,失败时带 `error`)。UI 错误包含 exportId,构建失败时带回执里的原因。构建、签名、原生 smoke 或校验失败时不发布下载入口,原 feature 的实现结果保持原样。
导出不开也不释放 Airspace:构建用共享检出已绑定的那个,失败后它照常留给下一个修复/验证任务;共享检出停在导出的提交上(分离 HEAD),下一个任务会检出自己的分支。
## 验证
```bash
bun run typecheck
bun run build
bun run build:satellite
bun test control-server/test/eddy_export.test.ts
python3 -m unittest discover -s satellite/eddy-export -v
```
数据库集成测试只接受显式提供的本机 `*_test` 数据库;先在可丢弃数据库加载 schema,再运行:
```bash
TEST_DATABASE_URL=postgres://test@127.0.0.1:5432/streamline_test \
bun test control-server/test/eddy_export.integration.test.ts
```
集成测试使用真实 PostgreSQL,拦截全部 SSO、卫星机和对象下载网络请求,覆盖鉴权、并发幂等、任务变化、固定提交、阶段顺序、过期租约、错误产物、异步完成确认、通知预约、过期重建;不发真实飞书消息。
可选真实工具链测试:编译一个最小扁平 Catalyst App 代替构建智能体,经该 runtime 自带的 cat-supervisor 打包,并从本地 ZIP 安装 App 与源码;不启动原生 App。`EDDY_EXPORT_TEST_RUNTIME` 指向解压后的官方 runtime(含 `MANIFEST.json` 的目录):
```bash
EDDY_EXPORT_TEST_RUNTIME=/path/to/official/eddy-runtime \
python3 -m unittest discover -s satellite/eddy-export -v
```
UI 的本地示例在 `/test/fixtures/eddy-export.html`,可检查初始、构建中、可下载、失败、过期和未启用状态。上线前还需在配置好的卫星机上对真实 feature 跑一次完整构建、原生启动、TOS 上传/回读和客户端下载安装。