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