# hermes-ui 开工提示词

> 用法：新会话里把下面「提示词正文」整段发给 agent。
> 每次只开一个 Phase。完成并验收后再开下一个。

---

## 提示词正文（以下整段复制）

````
项目：hermes-ui（个人版 Hermes Web UI 复刻/魔改）

## 项目位置
- 工作区（就是你的根目录）：/Users/jack/source/MyProject/js/hermes-ui
- 旧版只读参考：/Users/jack/source/MyProject/js/hermes-ui/reference_code/ekko-studio

**重要**：`reference_code/` 只是 0.6.29 的只读快照，用于对照。
新项目的任何文件都不得引用它。项目全部完成后我会删掉它，删掉后项目必须仍能独立构建和运行。

## 第一步（必做，不要跳）
按顺序读完这 4 个文件，它们是决策基线：
1. /Users/jack/source/MyProject/js/hermes-ui/docs/01-技术选型推荐.md
2. /Users/jack/source/MyProject/js/hermes-ui/docs/02-功能清单-0.6.29.md
3. /Users/jack/source/MyProject/js/hermes-ui/docs/03-施工蓝图.md
4. /Users/jack/source/MyProject/js/hermes-ui/docs/phases/README.md

然后读本阶段的任务书：/Users/jack/source/MyProject/js/hermes-ui/docs/phases/phase_00X.md
（X 替换成我要做的阶段号，例如 phase_001.md）

## 已确认的技术选型（不要推翻、不要重新讨论）
| 项 | 结论 |
|---|---|
| 前端 | Vue 3 + `<script setup>` TypeScript + Vite + Pinia + Vue Router(hash)，全部沿用 |
| 后端 | Koa 2 + TypeScript + Socket.IO + SQLite(better-sqlite3)，全部沿用 |
| 实时通信 | Socket.IO 的 `/chat-run` 命名空间协议保持不变 |
| UI 组件库 | **弃用 Naive UI，全量换 Arco Design Vue**，不双库共存 |
| 特效层 | **ArkScope** vendor 源码进项目，只做装饰性位面（登录页标题、Journey 图谱背景等），聊天页/表单页/表格页不用 |
| 桌面端 | **砍掉** packages/desktop 整包（托盘、自动更新、开机自启、捆绑运行时、独立桌宠窗口） |
| 官网 | **砍掉** packages/website |
| 内置 skills | **保留** packages/skills |
| IM 频道 | **保留**（多平台频道 + gateway 守护进程管理） |
| i18n | 只保留 zh + en，新增用户可见字符串必须同时写两个 locale |
| 品牌 | 新版本中不得出现 `ekko` 和 `hermes-web-ui` 字样；`Hermes` 字样保留（指被对接的 Agent 本体，技术上无法回避） |
| 配置层旧标识 | **有意保留**：`HERMES_WEB_UI_*` 环境变量前缀、`HERMES_WEBUI_STATE_DIR`、`~/.hermes-web-ui` 数据目录、localStorage key `hermes_brightness`/`hermes_style`/`hermes_locale`。改名会破坏已有部署脚本与数据目录 |
| 依赖 | 锁定 lockfile 不升级（版本不升，只做增删） |

## 已确认砍掉的功能组
- I 组：Claude Code / Codex 编程代理（含 stream-tee 网关）——各有官方 UI，不需要
- J 组：内置自有 Agent（ekko-agent）——只要 hermes
- P 组：桌宠系统 Petdex——浪费资源
- 桌面端 Electron

其余 B~H、K~O、Q 组全部沿用（详见 02 文档的 A~Q 分组与筛选统计表）。

## Hermes 对接（最核心的红线，我本人不熟悉这块，你必须把关）
唯一正道是 **Agent Bridge**：Node 侧客户端 → JSON over Unix socket
（`ipc:///tmp/hermes-agent-bridge.sock`，Windows 用 TCP 18765）→ Python 子进程内化
hermes-agent 的 `run_agent.AIAgent`。

- 禁止改成"每条消息 fork 一个 `hermes chat` CLI 进程"（冷启动、无法流式、无法审批）
- 禁止用 hermes 的 HTTP gateway 替代桥做聊天（gateway 是给 IM 频道用的，聊天语义对不上）
- 只允许在桥的 JSON 协议上**加字段**，不得改动既有事件语义
- `agent-bridge/python/` 视为只读 vendored 代码，动之前必须先看懂 `bridge_pool.py`
  （重点：`SessionDbHolder` 的进程内单例复用、`_bind_session_workspace_cwd` 会写
  `register_task_env_overrides`，改错会让所有工具在错误目录执行）
- 数据归属：hermes 的 `state.db` **只读**，新项目自己的 SQLite 是会话/消息/用量唯一
  可写存储，不做启动时导入同步，profile 隔离靠注入 `HERMES_HOME`
- 管理面操作（sessions/profile/logs/gateway/curator/setup）走 `execFile` + 参数数组，
  统一经 `hermes-process.ts` 的 `execHermesWithBin`，禁止 shell 拼字符串
- 砍掉桌面端后：hermes CLI 不再捆绑，改为用户自装 Python + hermes-agent，通过
  `HERMES_BIN` 指定；保留缺失时的引导提示

## 代码硬规则（继承旧版 AGENTS.md）
- 路由保持薄：请求处理进 controllers，可复用逻辑进 services
- 新增/改动的用户可见字符串必须同时写入 zh 与 en
- 结构化 API + 参数数组，禁止 shell 字符串拼接
- 不把无关重构混进修复里

## 绝对不能动（红线）
1. `packages/server/src/services/hermes/agent-bridge/python/` — 只读 vendored。
   唯一例外：`bridge_runtime.py` 里两处 `HERMES_DESKTOP` 判断**保留**
   （Windows 隐藏子进程控制台窗口，删掉会弹黑窗）
2. `/chat-run` Socket.IO 事件契约 — 不得改事件名、字段名、字段类型、
   以及 `run.started`/`run.output`/`run.completed`/`run.failed`/
   `approval.request`/`clarify.request` 的触发时机。只能加可选新字段
3. hermes `state.db` 只读 — Node 侧任何代码不得 open 它。读会话历史走桥的
   `getHistory`/`getOutput`
4. `services/hermes/group-chat/`、`lib/context-compressor/`、
   `services/hermes/context-engine/` 同属聊天链路，改动需附
   `docs/chat-chain-changes/<date>-<slug>.md` 片段
5. 本地 API 路由必须注册在 proxy 兜底路由之前

## 工作方式
- 中文沟通，简洁直接
- 动手前必须先读真实源码，不要凭文档臆测。文档里若有与源码冲突的结论，
  以源码为准，并立刻指出来问我
- 发现我给的信息与源码冲突时，立刻指出，不要默默按自己的理解走
- 每个 Phase 完成后先跑该阶段的验收命令 + 手工清单，全绿再进下一个
- 一次只做一个 Phase。不要提前做后面的

## 本次任务
执行 docs/phases/phase_00X.md（X = 我指定的阶段）。

开工前先告诉我：
- 这个 Phase 的改动落点（具体文件/目录）
- 你识别到的风险点
- 验收清单

确认后开工。
````

---

## 分阶段追加指令（做完一个 Phase 后发下一条）

````
Phase_00X 已完成并验收通过。
读 /Users/jack/source/MyProject/js/hermes-ui/docs/phases/phase_00Y.md，
按同样方式开工（先报落点、风险、验收清单，再动手）。
````

## 中途卡住时

````
当前 Phase_00X 卡住了。不要自己拍板决定。
请说明：
1. 阻塞点具体在哪（文件 + 行号 + 现象）
2. 你已经尝试过什么
3. 有哪几种可选方案，各自的代价
````