# 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
```

判定命令必须带排除：

```bash
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` |

**扫法**：

```bash
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 复查 |

```bash
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

```bash
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 项改为：

```ts
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` 改为两项：

```ts
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`：

```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. 验收

```bash
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 组）。