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.
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。
|