toor
1e9ea89d86
Import the client, server, skills, tests, and build scripts as the starting point for the rebuild, then trim the surfaces this project does not ship: Electron desktop packaging, the marketing website, and the ESP32 firmware tree. CI keeps the web build, e2e, lockfile, release, and Docker workflows. Rename the package and CLI entry points to hermes-ui, drop the prepare hook so npm ci no longer triggers a build, and drop the removed tsconfig and nodemon references. Rewrite AGENTS.md, ARCHITECTURE.md, DEVELOPMENT.md, and the READMEs so the documented package map and hard rules match this repository. reference_code/ is ignored: it is a read-only snapshot, not an input to the build.
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 组）。
|