hermes-ui/docs/phases/phase_004.md

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 侧只有两处：

1. gateway-autostart.ts 里 shouldRecoverWindowsDesktopGatewayOrphans() 依赖 HERMES_DESKTOP
2. 注册在 /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。

从此开始才允许改样式代码。