8.1 KiB
Phase 004 — 砍桌面端 + 官网 + 清理依赖
| 项 | 值 |
|---|---|
| 目标 | 无 Electron、无官网；hermes CLI 改用户自装；依赖表与 lockfile 一次性收干净 |
| 前置 | Phase 003 通过 |
| 产出 | npm ci && npm run build && npm run test:e2e 全绿；gateway 自启仍工作 |
| 参考 | docs/03-施工蓝图.md §6 |
0. 已核实：gateway 自启零迁移
原蓝图担心的「gateway 自启逻辑一半长在 Electron 里」不存在。
packages/server/src/index.ts 的 startRuntimeServicesBeforeListen() / startRuntimeServicesAfterListen() 已经调用 ensureProfileGatewaysRunning()。
Electron 侧只有两处：
gateway-autostart.ts里shouldRecoverWindowsDesktopGatewayOrphans()依赖HERMES_DESKTOP- 注册在
/api/desktop/shutdown的关闭回调
本 Phase 只删这两处，不做任何迁移。
1. 功能任务 1 — 删除 desktop 与 website
Phase 001 已删掉 packages/desktop / packages/website / 相关 workflow。本 Phase 处理引用方。
1.1 根 package.json scripts
删：
desktop:install
desktop:prepare-runtime
desktop:prepare-python
desktop:dev
build:desktop
build:desktop:mac
build:desktop:win
build:desktop:linux
dev:website
build:website
preview:website
claude # I 组配套：claude --dangerously-skip-permissions
mcu:* 系列：Phase 001 已删 esp32-c3，这些 script 也要删。若你后续要做语音硬件，另开 Phase 恢复。
保留：start dev dev:client dev:server build harness:check preview test test:watch test:coverage test:e2e test:e2e:ui openapi:generate
1.2 server 侧
| 文件 | 改动 |
|---|---|
src/index.ts |
删 registerDesktopShutdownRoute import 与调用、删 desktopShutdownHandler 变量与赋值、删 isDesktopEnv() |
src/index.ts |
注意：bindShutdown 主流程要保留，它也服务正常关停。只删桌面分支 |
services/shutdown.ts |
删 desktop 分支，保留主流程 |
controllers/auth.ts |
requiresCredentialChange: process.env.HERMES_DESKTOP === 'true' → 改常量 false 或删该字段 |
services/hermes/gateway-autostart.ts |
删 shouldRecoverWindowsDesktopGatewayOrphans() 及 index.ts 里对它的调用 |
services/hermes/agent-bridge/manager.ts |
删 isDesktopEnv() 用法 |
services/hermes/studio-mcp-autoinject.ts |
同上 |
1.3 client 侧
| 文件 | 改动 |
|---|---|
src/utils/desktop-bridge.ts |
整个文件删除 |
src/App.vue |
删 desktopBridge import、isDesktopShell / isDesktopPetRoute / hasDesktopTitleBar、DesktopTitleBar 组件、WebPet |
src/main.ts |
删 desktopBridge 调用 |
src/router/index.ts |
删 hermesDesktop 路由注入逻辑 |
src/utils/completion-notification.ts |
删本地 desktopBridge 副本 |
src/api/client.ts |
删对应 import 与分支 |
src/components/layout/AppSidebar.vue |
删对应 import |
src/components/layout/DesktopTitleBar.vue |
整个文件删除 |
src/components/auth/DefaultCredentialPrompt.vue |
删 desktopBridge 相关 |
src/views/hermes/DesktopPetView.vue |
整个文件删除 |
src/components/hermes/pets/WebPet.vue |
若无其他引用则删；有引用先解引用 |
1.4 测试
rm -f tests/client/desktop-titlebar.test.ts
rm -f tests/client/app-web-pet.test.ts
e2e 里的 desktop 用例移除。
2. 功能任务 2 — hermes CLI 改用户自装
砍桌面端后 hermes 不再捆绑。改动全部集中在两个文件。
2.1 hermes-path.ts
resolveHermesBin() 已是 HERMES_BIN → 'hermes' 的优先级链，保持不变。
改 bundledCliPythonForWindows()：删掉「找捆绑运行时」的假设，改为——
HERMES_BIN指向hermes.exe时，在同级 / 上级目录找python.exe- 找不到就用
hermes.exe直调（hermes 官方 Windows 包自带 launcher，不一定需要-m hermes_cli.main）
2.2 hermes-process.ts
- 不新增 shell 拼接。所有调用继续走
execHermesWithBin/spawnHermesWithBin，参数数组 - 加一个
isHermesCliAvailable()探测函数
2.3 引导页（用户可见）
启动时若探测不到 hermes CLI，前端显示引导：
未检测到 hermes CLI
请先安装：
pip install hermes-agent
或设置环境变量指定路径：
HERMES_BIN=/path/to/hermes
安装后重启本服务。
中英双语都要写（zh.ts + en.ts）。
落点建议：新增 packages/client/src/views/hermes/HermesMissingView.vue，在 router/index.ts 里作为前置守卫（与 LoginView 同级，登录前判断）。
3. 功能任务 3 — 依赖与 lockfile 收口
这是本 Phase 最需要小心的部分：npm ci 要求 package.json 与 package-lock.json 严格一致，任何增删都会让它失败。
3.1 删依赖
package.json 的 dependencies / devDependencies 删：
electron
electron-builder
@electron/*
electron-store
electron-updater （若 devDeps 里有）
先跑一次定位：
grep -n "electron" package.json
3.2 重生成 lockfile
# 删旧 lock，用当前 package.json 重装，版本不主动升级
rm -f package-lock.json
npm install --package-lock-only --ignore-scripts
--package-lock-only 只更新 lock 不装包，不会升级已存在的版本（依赖树解析会沿用现有版本范围）。
npm ci --ignore-scripts
npm run build
3.3 校验版本没被偷偷升级
# 对比新旧 lock 里几个关键包的版本
git diff package-lock.json | grep -E "^\+.*\"(vue|koa|socket.io|better-sqlite3|vite|pinia)\""
# 期望：无新增版本行
4. 功能任务 4 — Dockerfile / CI 同步
| 文件 | 改动 |
|---|---|
Dockerfile |
删 electron 相关 build 步骤与产物拷贝 |
docker-compose.yml |
删 electron 挂载 |
.github/workflows/build.yml |
确认无 desktop 步骤 |
.github/workflows/webui-release.yml |
Phase 002 已去品牌，确认打包产物名已改 |
4.1 fetch-depth: 0 必须保留
harness-check.mjs 靠 git diff 判断链路变更。CI 里 actions/checkout 缺 fetch-depth: 0 会让检测失效。
5. 验收
5.1 命令
cd /Users/jack/source/MyProject/js/hermes-ui
grep -rn "desktop\|electron\|Electron" packages/ --include="*.ts" --include="*.vue" \
| grep -v "bridge_runtime.py"
# 期望：零命中（python 的 HERMES_DESKTOP 判断例外，见 §6）
grep -n "electron" package.json
# 期望：零命中
npm ci --ignore-scripts
npm run build
npm run test
npm run test:e2e
5.2 手工
npm run dev正常启动- 启动后 gateway 自动拉起（看日志）
- 聊天正常
- 故意把
HERMES_BIN指向不存在的路径 → 出现引导页而非白屏报错 - Docker 构建成功且容器内聊天正常
6. 红线：这两处 HERMES_DESKTOP 保留不动
packages/server/src/services/hermes/agent-bridge/python/bridge_runtime.py L74 / L119：
这是 Windows 下隐藏子进程控制台窗口的逻辑。删掉会导致 Windows 用户运行 git / 命令时弹黑窗。
虽然新项目是 Web 端、不再有 Electron 壳，但 Windows 用户从命令行起 Node 依然会弹。
判断依据：这两个 env 在新项目里永远为 undefined，条件分支永不进入 → 逻辑上等价于删除，但保留代码不影响正确性，删除则影响。留。
7. 风险
| # | 风险 | 缓解 |
|---|---|---|
| P4-1 | 删 bindShutdown 时误伤正常关停 |
只删桌面分支，主流程保留；手工 Ctrl+C 验证一次 |
| P4-2 | lockfile 重生成时依赖被升级 | git diff package-lock.json 逐项确认，锁版本 |
| P4-3 | Windows 用户失去捆绑 Python | 引导页 + README 显著位置写安装步骤。这是既定决策 |
| P4-4 | e2e 有 desktop 用例残留 | test:e2e 必跑 |
| P4-5 | WebPet.vue 被多处引用 |
删前先 grep -rn "WebPet" |
| P4-6 | DefaultCredentialPrompt 在 auth.ts 有对应字段 |
两边一起改 |
8. 完成标志
项目此时功能完整、界面还是旧的 Naive UI。 进入 Phase 005。
从此开始才允许改样式代码。