245 lines
8.4 KiB
Markdown
245 lines
8.4 KiB
Markdown
# Phase 001 — 仓库骨架搭建
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| 目标 | 把 reference 源码拷进 hermes-ui，裁成最小可运行骨架 |
|
||
| 前置 | 无 |
|
||
| 产出 | 新项目根目录有完整可 `npm ci && npm run build` 的代码 |
|
||
| 验收命令 | `npm ci --ignore-scripts && npm run build` |
|
||
|
||
---
|
||
|
||
## 0. 铁律：reference 的使用边界
|
||
|
||
```
|
||
reference_code/ekko-studio/ ← 只读参考，不是新项目的一部分
|
||
hermes-ui/ ← 新项目本体
|
||
```
|
||
|
||
**硬约束**：
|
||
|
||
1. `reference_code/` **只在 Phase 001 被读取一次**（用于拷贝与对照）。
|
||
2. **从 Phase 002 起，禁止任何代码、配置、文档、测试引用 `reference_code/` 下的路径。**
|
||
3. 拷贝必须是**复制进新项目**，不是软链、不是 git submodule、不是运行时挂载。
|
||
4. Phase 001 结束时，`hermes-ui/` 内的文件必须自洽——把 `reference_code/` 整个删掉，`npm ci && npm run build && npm run test` 仍应通过。
|
||
|
||
验收方式（Phase 001 收尾自查）：
|
||
|
||
```bash
|
||
cd /Users/jack/source/MyProject/js/hermes-ui
|
||
grep -rn "reference_code" . --include="*.ts" --include="*.vue" --include="*.json" \
|
||
--include="*.mjs" --include="*.md" --include="*.yml" | grep -v "^./docs/phases/"
|
||
# 期望：零命中
|
||
```
|
||
|
||
---
|
||
|
||
## 1. 目录创建
|
||
|
||
```bash
|
||
cd /Users/jack/source/MyProject/js/hermes-ui
|
||
mkdir -p docs/phases
|
||
# docs/ 与 docs/phases/ 已存在
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 拷贝（用 rsync 排除，不做人工挑拣）
|
||
|
||
参考源码：`reference_code/ekko-studio/`
|
||
|
||
### 2.1 拷贝保留项
|
||
|
||
```bash
|
||
REF=reference_code/ekko-studio
|
||
DST=.
|
||
|
||
# 包与测试
|
||
rsync -a $REF/packages/client ./packages/
|
||
rsync -a $REF/packages/server ./packages/
|
||
rsync -a $REF/packages/skills ./packages/
|
||
|
||
rsync -a $REF/tests/ ./tests/
|
||
rsync -a $REF/bin/ ./bin/
|
||
rsync -a $REF/scripts/ ./scripts/
|
||
|
||
# 根配置
|
||
for f in package.json package-lock.json vite.config.ts vitest.config.ts \
|
||
playwright.config.ts tsconfig.json tsconfig.app.json \
|
||
tsconfig.node.json nodemon.json Dockerfile docker-compose.yml \
|
||
.dockerignore .gitignore; do
|
||
cp -p $REF/$f ./$f
|
||
done
|
||
|
||
# 文档（只拷 harness 与 chat-chain-changes 的 README，不拷旧正文）
|
||
mkdir -p docs/harness docs/chat-chain-changes
|
||
rsync -a $REF/docs/harness/ ./docs/harness/
|
||
cp -p $REF/docs/chat-chain-changes/README.md ./docs/chat-chain-changes/
|
||
cp -p $REF/LICENSE ./LICENSE
|
||
```
|
||
|
||
### 2.2 拷贝**后**立即删除（不在新项目存在）
|
||
|
||
```bash
|
||
rm -rf packages/desktop packages/website packages/ekko-agent packages/esp32-c3
|
||
rm -rf tests/ekko-agent
|
||
rm -rf packages/client/public/coding-agents
|
||
rm -f tsconfig.website.json
|
||
rm -rf docs_new
|
||
```
|
||
|
||
### 2.3 同步清理 `.github/workflows`（只留 5 个）
|
||
|
||
```bash
|
||
cd .github/workflows
|
||
rm -f desktop-release.yml desktop-manual-build.yml \
|
||
desktop-mac-update-manifest.yml desktop-runtime.yml website-deploy.yml
|
||
ls # 期望：build.yml docker-publish.yml npm-lockfile-check.yml \
|
||
# playwright.yml webui-release.yml
|
||
```
|
||
|
||
> `webui-release.yml` 先保留，Phase 002 去品牌时改名。
|
||
|
||
### 2.4 不拷的东西（清单）
|
||
|
||
| 不拷 | 原因 |
|
||
|---|---|
|
||
| `packages/desktop/` | 整包砍 |
|
||
| `packages/website/` | 官网砍 |
|
||
| `packages/ekko-agent/` | J 组砍 |
|
||
| `packages/esp32-c3/` | 固件不做（**若要做语音硬件，另开 phase 并从这里恢复**） |
|
||
| `tests/ekko-agent/` | 随 J 组砍 |
|
||
| `docs_new/` | 旧版规划文档，已被 `docs/01~03` 取代 |
|
||
| `docs/planning/` | 上游作者的过程笔记 |
|
||
| `docs/*.md`（顶层散落） | 旧功能文档，本项目另有 `docs/02-功能清单` |
|
||
| `packages/client/public/coding-agents/` | 随 I 组砍 |
|
||
| `agent-bridge/python/__pycache__/` | Python 字节码，见 3.3 |
|
||
|
||
---
|
||
|
||
## 3. 配置文件改造
|
||
|
||
### 3.1 `package.json`（**本 Phase 只做最小改动**）
|
||
|
||
必须改：
|
||
|
||
```jsonc
|
||
{
|
||
"name": "hermes-ui",
|
||
"version": "0.6.29", // 从此版本起自己走
|
||
"bin": {
|
||
"hermes-ui": "./bin/hermes-ui.mjs"
|
||
}
|
||
}
|
||
```
|
||
|
||
**暂时不改**：`scripts` / `dependencies`。
|
||
理由：`build` / `dev` / `test` / `test:e2e` 全部要留，desktop 相关 script 删了但依赖还在，下一个 Phase 再统一清。`npm ci` 依赖 `package.json` 与 `package-lock.json` 一致，任何依赖增删都会让 `npm ci` 失败——所以依赖清理留到 Phase 004 一次性做。
|
||
|
||
**必须摘掉**（否则 `npm ci` 会自动触发 build）：
|
||
|
||
```jsonc
|
||
"scripts": {
|
||
// 删掉 "prepare": "[ -d dist ] || npm run build"
|
||
}
|
||
```
|
||
|
||
Phase 007 收尾时再恢复。
|
||
|
||
### 3.2 `bin/` 重命名
|
||
|
||
```bash
|
||
git mv bin/hermes-web-ui.mjs bin/hermes-ui.mjs # 或 mv
|
||
git mv bin/hermes-web-ui-mcp.mjs bin/hermes-ui-mcp.mjs
|
||
rm -f bin/hermes-studio-mcp.mjs # "studio" 是旧品牌
|
||
```
|
||
|
||
重命名后要改文件内部的自引用（路径、`process.env.npm_package_name` 之类）。Phase 002 会做全量品牌扫描，本 Phase 只需保证文件存在、`npm run build` 不报错。
|
||
|
||
> `package.json` 的 `bin` 若指向 `hermes-ui-mcp` 也一并改名，两边必须一致。
|
||
|
||
### 3.3 `nodemon.json`
|
||
|
||
`watch` 里删掉 `packages/ekko-agent/src`（该包已不存在，留着 dev 会报路径错误）。
|
||
|
||
### 3.4 `vite.config.ts`
|
||
|
||
本 Phase 不动。Phase 005 改 `manualChunks` / `optimizeDeps`。
|
||
|
||
### 3.5 清理 Python 字节码
|
||
|
||
```bash
|
||
find packages/server/src/services/hermes/agent-bridge/python/__pycache__ -type f -delete
|
||
rmdir packages/server/src/services/hermes/agent-bridge/python/__pycache__ 2>/dev/null
|
||
```
|
||
|
||
在 `.gitignore` 加 `__pycache__/`。
|
||
|
||
---
|
||
|
||
## 4. 文档编写（**必须在本 Phase 完成，不能拖**）
|
||
|
||
代码要继承旧版硬规则，但旧版 `AGENTS.md` / `ARCHITECTURE.md` / `DEVELOPMENT.md` 全是旧品牌，必须重写。
|
||
|
||
| 文件 | 内容要求 |
|
||
|---|---|
|
||
| `AGENTS.md` | **≤120 行**。包地图改为 `packages/client` / `packages/server` / `packages/skills` / `tests/*`。保留「Hard Rules」全部 6 条。链接下面 4 个文档。禁止出现 `ekko` / `hermes-web-ui`。 |
|
||
| `ARCHITECTURE.md` | 包边界、数据归属、运行时流。**删掉** "Electron desktop distribution" 段落与 "Desktop Release Flow" 整节。**新增**一句：`HERMES_WEB_UI_HOME` 是有意保留的旧标识（配置层），见 `docs/03-施工蓝图.md` §0。 |
|
||
| `DEVELOPMENT.md` | 命令表 + 编码规则 + 测试规则 + PR 形态。把 L47 "Match existing Naive UI patterns and avoid adding a new UI library" 改为 **Arco Design Vue**。 |
|
||
| `README.md` / `README_zh.md` | 重写。项目简介、装 Python + hermes-agent 的前置步骤（**因为砍了桌面端，不再捆绑**）、启动命令、目录结构。 |
|
||
| `docs/harness/*.md` | 4 个文件直接从 reference 拷贝。但要检查内容里是否引用了 desktop/ekko，有则改。 |
|
||
|
||
`docs/01` / `docs/02` / `docs/03` 已在仓库里，本 Phase 不动。
|
||
|
||
---
|
||
|
||
## 5. 验收
|
||
|
||
### 5.1 命令
|
||
|
||
```bash
|
||
cd /Users/jack/source/MyProject/js/hermes-ui
|
||
npm ci --ignore-scripts
|
||
npm run build
|
||
```
|
||
|
||
`build` 必须零 TS 报错。
|
||
|
||
### 5.2 自查清单
|
||
|
||
- [ ] `ls packages/` 只有 `client` `server` `skills`
|
||
- [ ] `ls tests/` 只有 `client` `server` `e2e` `shared` `fixtures`
|
||
- [ ] `ls .github/workflows/` 只有 5 个文件
|
||
- [ ] `grep -rn "reference_code" .` 零命中（排除 `docs/phases/`）
|
||
- [ ] `package.json` 的 `name` 是 `hermes-ui`，无 `prepare` script
|
||
- [ ] `bin/` 下是 `hermes-ui.mjs` + `hermes-ui-mcp.mjs`
|
||
- [ ] `AGENTS.md` ≤120 行且无旧品牌
|
||
- [ ] `__pycache__` 已清、`.gitignore` 已加规则
|
||
- [ ] `git init` 已执行（若尚未初始化）
|
||
|
||
### 5.3 冒烟（本 Phase 不要求功能正确，只要求不崩）
|
||
|
||
```bash
|
||
npm run dev
|
||
# 打开 http://localhost:5173
|
||
# 登录页能渲染即通过（后端功能此阶段不完整是正常的）
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 风险
|
||
|
||
| # | 风险 | 缓解 |
|
||
|---|---|---|
|
||
| P1-1 | 删 `packages/desktop` 后根 `package.json` 仍有 electron 依赖，`npm ci` 正常但体积浪费 | 故意为之，Phase 004 统一清 |
|
||
| P2-1 | 改 `package.json` 导致 `npm ci` 报 lock 不同步 | **本 Phase 只改 `name` / `bin` / 删 `prepare`，不动 `dependencies`** |
|
||
| P3-1 | `npm ci` 因缺 `prepare` 而不 build，后续 `npm run build` 手动执行 | 正常 |
|
||
| P4-1 | 漏拷隐藏文件（`.dockerignore` 等） | 用显式 `cp -p` 列表，不靠通配 |
|
||
| P5-1 | reference_code 与原仓库有偏差 | 后续 phase 需要对照时，**用 git 提交历史比对而非直接拷**；实在需要可再读 reference，但产物必须写进新项目 |
|
||
|
||
---
|
||
|
||
## 7. 完成标志
|
||
|
||
进入 Phase 002。
|