hermes-desktop/docs/phases/phase_002.md

Phase 002 — 去品牌 + i18n 收敛到 zh/en

项	值
目标	全仓无 ekko / hermes-web-ui 字样；i18n 只剩 zh + en
前置	Phase 001 通过
产出	grep -ri "ekko|hermes-web-ui" 在代码范围内零命中
参考	docs/03-施工蓝图.md §4

---

0. 保留白名单（这些必须留着）

以下旧标识是你主动决定保留的，改了会破坏已有部署脚本与数据目录：

HERMES_WEB_UI_*            环境变量前缀
HERMES_WEBUI_STATE_DIR     环境变量
~/.hermes-web-ui/          默认数据目录
hermes_brightness          localStorage key
hermes_style               localStorage key
hermes_locale              localStorage key

判定命令必须带排除：

grep -rn "HERMES_WEB_UI\|hermes_brightness\|hermes_style\|hermes_locale" packages/
# 这些命中是正常的

---

1. 功能任务 1 — 根配置去品牌

文件	改动
package.json	name: hermes-ui（Phase 001 已做）；description / keywords / author / license 去旧品牌；repository / homepage 指向你自己仓库或整项删除
README.md / README_zh.md	Phase 001 已重写，复查一遍 grep
AGENTS.md	复查；确认硬规则 6 条齐全
ARCHITECTURE.md	确认无 "Electron desktop distribution" / "Desktop Release Flow"
DEVELOPMENT.md	确认 L47 那条已改为 Arco
Dockerfile	镜像名、EXPOSE、ENTRYPOINT 里的旧品牌
docker-compose.yml	容器名、volume 名、image 名
.dockerignore / .gitignore	旧品牌路径
LICENSE	上游许可证保留（MIT 或 Apache，看一眼 LICENSE 首行确认）

---

2. 功能任务 2 — server 侧去品牌（本 Phase 最容易漏）

2.1 controllers/update.ts（重点文件，必查）

grep 这个文件会命中几十处，逐个处理：

类别	处理
预览目录名 hermes-web-ui-pereview	改 hermes-ui-preview
hermes-web-ui/bin/hermes-web-ui.mjs	改 hermes-ui/bin/hermes-ui.mjs
pkg?.name !== 'hermes-web-ui' 的版本比对	改 'hermes-ui'
User-Agent 里的旧品牌	改 hermes-ui/<version>
npm 全局安装 hermes-web-ui@latest	见 2.3 的决策
各类提示文案	改用户可见文案，同步写 zh + en

2.2 config.ts

• 检查 https://hermes-studio.ai 相关的默认下载地址
• 保留所有 HERMES_WEB_UI_* 环境变量名

2.3 update.ts 的在线更新：先做决策落地

hermes-ui 未发布 npm，所以"检查更新 / 一键更新"功能上不可用。

本 Phase 采用：保留逻辑、改文案标注。

"title": "检查更新"
"currentIsLatest": "当前为源码运行，在线更新不可用"
"checkFailed": "检查更新失败"

不动 npm i -g 的代码路径。等你决定发布方式（npm / GitHub Release）再接。

2.4 其他 server 文件

文件	改动
services/hermes/agent-bridge/manager.ts	OpenRouter attribution URL（hermes-studio.ai）→ 改成你自己的地址，或删掉 attribution
lib/llm-prompt.ts	grep 到 /Users/ekko/Desktop 是原作者本机路径，直接删该分支逻辑，不改名
services/hermes/studio-mcp-autoinject.ts	文件名含 studio；grep 内容确认是否有旧品牌串。有则改内容；文件名可保留（它指 hermes 的 studio 功能，不是本项目品牌），也可改名 mcp-autoinject.ts

扫法：

cd /Users/jack/source/MyProject/js/hermes-ui
grep -rn "ekko\|Ekko\|EKKO\|hermes-web-ui\|hermes-studio\|Hermes Studio" packages/server/src/

逐个 Read 确认后改。不要盲改——Hermes 字样本身要保留。

---

3. 功能任务 3 — client 侧去品牌

文件	改动
index.html	<title>（原 Hermes Studio）、apple-mobile-web-app-title
public/manifest.webmanifest	name / short_name / description
i18n/locales/zh.ts en.ts	所有旧品牌文案
data/changelog.ts	建议整体清空，从 0.6.29 重新起
public/notification-sw.js	检查缓存名
components/hermes/chat/*.vue	grep 命中的显示文案
App.vue / main.ts / router/index.ts	grep 复查

grep -rn "ekko\|hermes-web-ui\|Hermes Studio" packages/client/

---

4. 功能任务 4 — 测试同步

文件	改动
tests/client/pwa-metadata.test.ts	断言的 title / manifest 名同步改
tests/client/style-system.test.ts	断言的 Naive key 暂不动（Phase 007 重写为 Arco）

---

5. 功能任务 5 — i18n 收敛到 zh + en

5.1 删 8 个 locale

cd packages/client/src/i18n/locales
rm -f zh-TW.ts ja.ts ko.ts fr.ts es.ts de.ts pt.ts ru.ts
ls   # 期望：en.ts  zh.ts

5.2 messages.ts

supportedLocales 从 10 项改为：

export const supportedLocales = ['en', 'zh'] as const

逐条检查 messages 里是否有依赖被删语言的映射（如 localeNames 字典），删干净。

5.3 i18n/index.ts

normalize() 简化为：

zh / zh-CN / zh-Hans / zh-*  → zh
其余一律 → en

删掉对 zh-TW / 其他语种的手写分支。

5.4 tests/client/i18n-coverage.test.ts

rawMessages 改为两项：

const rawMessages = [enMessages, zhMessages]

该测试的断言逻辑（key 集合一致、中文值非空）保留不动——这是「新增字符串必须同时写两语言」这条硬规则的机械保障。

---

6. 功能任务 6 — 新增机械化保障（本 Phase 加上，防止后续回流）

6.1 tests/client/no-naive-ui.test.ts

Phase 001 还没换库，先建文件占位也行，但去品牌的这个必须现在就加：

新建 tests/server/no-legacy-brand.test.ts：

// 扫描 packages/{client,server}/src、tests/、scripts/、bin/
// 命中 'ekko' | 'hermes-web-ui'（排除白名单）即 fail

白名单（这些允许出现）：

HERMES_WEB_UI_*, HERMES_WEBUI_STATE_DIR,
hermes-web-ui 作为数据目录名出现在 config 默认值里 —— 例外，
需要单独加白名单项或改成不出现字面量

注意：config.ts 里如果有 ~/.hermes-web-ui 字面量，它既是保留项又是命中项。处理方式二选一：

• 在测试里对 config.ts 单文件加白名单
• 或把默认目录名改成拼接（如 ['hermes', 'web-ui'].join('-')）—— 不推荐，太丑

建议前者，白名单写清楚原因。

6.2 同步加进 harness-check

Phase 007 会重写 scripts/harness-check.mjs，但品牌扫描这一条现在就要加进去，这样后续每个 Phase 都有机械保障。

---

7. 验收

cd /Users/jack/source/MyProject/js/hermes-ui

# 零命中
grep -rni "ekko" packages/ tests/ scripts/ bin/ .github/ *.json *.md Dockerfile* docker-compose.yml
grep -rni "hermes-web-ui" packages/ tests/ scripts/ bin/ .github/ *.json Dockerfile* docker-compose.yml

# 白名单仍存在
grep -rn "HERMES_WEB_UI" packages/server/src/config.ts | head -5

# 构建与测试
npm run build
npm run test

手工验收

• 浏览器标签页标题是 hermes-ui
• PWA manifest 名已更新
• 语言切换只有 中文 / English 两项
• 切到 English，界面全英文无残留中文
• 设置页「检查更新」文案显示"源码运行"

---

8. 风险

#	风险	缓解
P2-1	update.ts 品牌串极多，漏改会导致 npm run harness:check 红	该文件单独 grep -c 计数，改完归零
P2-2	i18n 删除导致某语言下界面显示 key 本身	en 是 fallback，只删非 en/zh 的，不影响
P2-3	白名单与扫描规则互相打架（~/.hermes-web-ui）	测试里显式白名单 + 注释说明原因
P2-4	changelog 清空后 VersionPreviewView 空白	清空 data/changelog.ts 的同时把该视图的入口隐藏，或留一条 0.6.29 说明
P2-5	误删 Hermes 字样	判定用 ekko 与 hermes-web-ui，不用 hermes

---

9. 完成标志

进入 Phase 003（砍 I/J 组）。