247 lines
8.0 KiB
Markdown
247 lines
8.0 KiB
Markdown
# 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 组）。
|