14 KiB
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。
执行和交付约定
- 控制面认证点击者,选定执行导出的卫星机(见下文「哪台卫星机导出」),复用普通接力的报告、反馈历史和执行摘要。共用起点规则:人工复核用任务分支,确认已合入用配置的基线,合入记录未知时先任务分支、明确不存在才退回基线;网络失败不触发回退。Feature 的合入状态通过匹配仓库/源分支的 Bits 只读查询补充。卫星机把所选远端起点解析为完整 SHA,文档记录实际分支和提交。
- 服务端持久化提交、构建说明 hash、任务/MR 和完整接力文档快照。相同 feature、提交、分支、构建说明及上下文的有效作业复用;每个请求者各有通知记录。反馈/报告变化时新建快照,不把旧上下文当作刚生成的接力文档。
- 卫星机在串行 implementation scheduler 内领取作业,先获取与 Asking 共用的 checkout 锁。导出占用节点,不与下一次实现、Asking 代码修改或 Eddy compat 验证并行;控制面热部署等待该作业结束。控制面把构建到上传这几个阶段的导出计入该节点的执行槽(
countSlotsPerNode),所以节点卡片显示「执行 1/1」和「Eddy 导出 · <任务标题>」(GET /api/eddy-exports/running,点开进入该 feature),调度台和导出改派也不会把它当成空闲节点。 - 在独立目录 clone 产品仓,在分支名上检出固定 SHA(
git checkout -B <分支> <提交>,源码包和接力文档从这里出),再把节点的共享检出($AI_WORKSPACE/TikTok)固定到同一提交(先用验证任务同一个checkoutChangeCommitfetch 分支、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)。 - 构建由智能体按 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进包;源码包始终按固定提交切。 - 打包直接调用 Eddy 的
portable/build_app_baseline.build(runtime2026.10.15-eddy-home.12起支持extend):先在作业目录的DEVICESIM_ROOT里装好 DeviceSim(runtime2026.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。 - 在作业自己的 runtime / state 下安装 ZIP、DeviceSim 选
installed(即上一步在作业目录里启用的那份),启动 App 并运行 Eddy smoke。要求原生连接 active、无产品编辑、无 Frida engine attach、产出有效 PNG。此检查证明基线可启动、可截图,不等于 feature 的业务验收。 - 两份 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,校验在后台运行,卫星机继续心跳及查询。 - 只有回读成功才标记 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),下一个任务会检出自己的分支。
验证
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,再运行:
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 的目录):
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 上传/回读和客户端下载安装。