WebUI 脱 Electron 执行阻碍清单

• 日期: 2026-05-07
• 目的: 从真正开始执行这条迁移链的角度，列出会阻碍推进、放大返工成本或降低自动化可靠性的主要因素

结论

即使文档方向已经比较清楚，真正执行这条迁移链时，仍然有一批现实层面的阻碍点。

这些阻碍大多不是“不会做”，而是:

• 会迫使执行者在实现中自行补判断
• 会让本地验证和 CI 验证出现断层
• 会让高风险里程碑背上原本不该背的工作

下面 6 项是我认为最可能实际阻碍推进的点。

1. 契约虽然大体清楚，但仍需要一个明确的权威来源

问题

这组文档现在已经包含:

• 设计文档
• team playbook
• M1 详细 plan
• M2-M9 requirements
• handoff 约束

当同一件事在多个文件里同时出现时，如果没有一个明确的“最终权威来源”，执行者还是可能在落地时自行判断。

具体表现

• 接口签名到底以设计文档 UC 为准，还是以某个 milestone requirement 为准
• 文件结构到底以“做什么”章节为准，还是以“文件清单”/“验收标准”为准
• 某个细节冲突时，plan-writer 到底应该改哪份文档引用哪份文档

影响

• 容易引发“改一处、漏一处”
• 不同 executor 会按不同页面做出不同实现
• 高风险里程碑会被迫临场消化早期契约漂移

建议

在设计文档或 playbook 开头明确写一条:

• 公共规则与公共接口 以设计文档 UC 节为权威
• 单里程碑范围与验收 以对应 requirement 为权威
• 执行步骤 以 detailed plan 为权威

2. CI / Release 才能完整闭环的步骤，本地很难完全复现

问题

这条迁移链里有多处关键验证并不是“本地跑通命令”就够:

• M7 的 backend 打包接入
• M8 的 tarball + .sha256 + release asset
• M9 的 install 脚本消费 release asset

这些步骤天然依赖:

• GitHub Actions
• release job
• artifact 上传下载
• 真实 tag / release 页面

影响

• executor 在本地只能做部分 smoke，不能完整验证最终分发链路
• 如果 CI 工作流有权限、路径、命名上的偏差，本地不会提前暴露
• 文档即使写得清楚，也可能在 release 阶段才第一次发现问题

建议

把这类步骤明确区分成两层:

1. 本地强制验证
2. CI / release 强制验证

并且在每个相关里程碑里直接写明“哪一层才是最终放行门禁”。

3. aionui-backend 的外部依赖会放大整条链的不确定性

问题

这条链虽然发生在 AionUi 仓库里，但多个关键步骤都依赖外部的 aionui-backend 二进制可用性。

依赖内容包括:

• release 是否存在
• 命名规则是否稳定
• 各平台 artifact 是否齐全
• 下载地址是否与脚本/CI 中写死的一致

影响

• 文档上看似闭环，执行时却可能被外部 release 状态卡住
• M7/M8/M9 的问题不一定是本仓库逻辑错，也可能是外部产物没准备好
• 即使代码已经完成，也可能因为 backend release 暂时不可用而无法验证通过

建议

在执行前单独做一轮外部依赖预检:

1. backend release 命名规则
2. 平台覆盖情况
3. 下载 URL
4. .sha256 是否存在
5. 本地或 CI 的回退验证路径

4. M6 的 E2E 成本高，而且对环境非常敏感

问题

M6 需要同时覆盖:

• Electron 桌面进程
• 浏览器端
• backend
• web-host
• Playwright
• 多路径切换

这种测试天然受下面这些因素影响:

• 端口时序
• 日志时序
• GUI 启动速度
• Electron 与浏览器的双端同步
• 本地桌面环境是否可用

影响

• 失败时难以快速判断是产品逻辑问题还是环境问题
• 文档如果没把等待条件、日志路径、端口读取方式写死，执行会很脆
• 高风险切换节点会变成调试耗时黑洞

建议

对 M6 单独强化执行前置条件:

• 明确日志文件位置
• 明确端口来源
• 明确等待条件
• 明确失败时先看哪份日志
• 明确哪些 case 必须串行跑

5. team-mode 协作流程本身依赖特定工具环境

问题

playbook 已经说明它只适用于 Claude Code team-mode，但这本身就是一个现实阻碍点。

因为只要执行环境不具备:

• TeamCreate
• Agent(team_name=...)
• SendMessage

整套自动调度方式就不能原样执行。

影响

• 文档中的协作流程不能直接移植到普通本地开发或普通 CI 机器人
• 如果实际执行人不是 team-mode 环境，必须人工翻译流程
• 翻译过程里容易丢掉里程碑边界、handoff 约束、基线同步要求

建议

最好补一份轻量的“非 team-mode 执行映射”说明，例如:

• team-lead → 人类协调者
• plan-writer → 单独会话或人工写 plan
• handoff → 固定 markdown 模板

这样即使不在 team-mode 环境里，也能按同一套约束推进。

6. 少数验证虽然已经改善，但仍然容易退化成“人工判断”

问题

这批文档已经在强调“机械化验证”，但现实里最容易退化的地方仍然是:

• 产物路径和命名核对
• release asset 是否完整
• 安装脚本是否真的消费了对的 artifact
• GUI / 浏览器联动是否真的是同一个 backend

一旦这些地方没有被命令行明确判定，执行者就会自然地回到“我看起来差不多对了”的人工判断模式。

影响

• 同一份文档，不同执行者会得到不同的“已完成”标准
• handoff 里的 PASS 证据会变得不稳定
• 后续里程碑会建立在不够扎实的基线上

建议

继续坚持一个原则:

• 能用脚本判定的，不要留给肉眼
• 能从日志 grep 的，不要写成“确认服务启动”
• 能从 artifact list 验证的，不要写成“检查 release 页面”

对少数暂时无法机械化的点，也要明确写出:

• 这是人工检查
• 为什么目前无法机械化
• 后续应由哪个里程碑补强

优先级建议

P1

• 阻碍 1: 权威来源定义
• 阻碍 2: 本地验证 vs CI/release 验证分层
• 阻碍 4: M6 E2E 环境敏感性

P2

• 阻碍 3: 外部 backend release 预检
• 阻碍 5: 非 team-mode 执行映射
• 阻碍 6: 剩余人工判断点继续机械化

最小应对方案

如果只想用最小成本降低执行阻力，我会优先做下面几件事:

1. 在设计文档或 playbook 里补一条“权威来源说明”
2. 在 M7/M8/M9 中显式区分“本地门禁”和“CI/release 门禁”
3. 给 M6 补一份更具体的失败诊断路径
4. 在真正开始执行前，先单独做一次 backend release 预检

这几步做完后，整条迁移链的执行阻力会明显下降。