hermes-ui/docs/phases/phase_001.md

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 收尾自查）：

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. 目录创建

cd /Users/jack/source/MyProject/js/hermes-ui
mkdir -p docs/phases
# docs/ 与 docs/phases/ 已存在

---

2. 拷贝（用 rsync 排除，不做人工挑拣）

参考源码：reference_code/ekko-studio/

2.1 拷贝保留项

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 拷贝后立即删除（不在新项目存在）

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 个）

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 只做最小改动）

必须改：

{
  "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）：

"scripts": {
  // 删掉 "prepare": "[ -d dist ] || npm run build"
}

Phase 007 收尾时再恢复。

3.2 bin/ 重命名

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 字节码

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 命令

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 不要求功能正确，只要求不崩）

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。