# 22 · 预发 Legacy 瘦身清单 v1

> 状态：**process → 执行完成（Wave 0–9 出口已达）**  
> 日期：2026-07-25  
> 目标：云首发前去掉非产品主链代码与叙事，减小二进制/认知负担；**不误伤 Pi Lab / LightRAG / OnlyOffice / Vault**。  
> 控制面云首发：`libsql-local`（独立部署）。  
> 产品 Page AI 唯一主链：**Pi Lab（Rust host `page_ai_pi` + `packages/pi-mnote`）**。  
> 关联：`AGENTS.md`、`ARCHITECTURE.md`、`21-mvp-post-architecture-closure-checklist-v1.md`

## 0. 原则

1. **产品面只保留**：树/文档、Pi Lab、LightRAG、OnlyOffice、Vault、libSQL 控制面。  
2. **文档不再写**「OpenHub / Hermes / ACP / Reasonix / OpenCode 是兼容选项」类历史叙事；清理任务只写在本清单。  
3. **原子删除**：route + `lib.rs`/`mod.rs` 注册 + browser 引用 + 测试 fixture 同批；禁止半删导致编译红。  
4. **先重命名再删依赖名**：`hermes_tools` 是 **Pi 仍在用的 agent tool pack**，不是整包可删垃圾。  
5. **不动**用户进行中的 Vault WIP、无关脏改动。  
6. 影响面用 **CodeGraph** + `rg`；大块删除后 `cargo test -p mnote-web` + 主链 smoke。

## 1. 体量快照（2026-07-25 本机）

| 路径 | 约行数 / 体积 | 处置 |
|------|----------------|------|
| `routes/hermes_client.rs` | ~18.7k 行 / ~688KB | **DELETED** |
| `routes/hermes_tools.rs` | ~6.8k 行 / ~272KB | **RENAMED** → `routes/mnote_tools.rs` |
| `src/hermes_tools/` | ~412KB（tool pack） | **RENAMED** → `src/mnote_agent_tools/` |
| `routes/hermes.rs` | ~297 行 | **DELETED** |
| `acp_*.rs`（5 文件） | ~4.4k 行合计 | **DELETED** |
| `routes/page_ai_opencode.rs` | ~1.1k 行 | **DELETED** |
| `routes/page_ai_pi/` | 主链 | **KEEP** |
| `routes/knowledge_rag.rs` | 主链 | **KEEP** |
| `routes/vault*.rs` | 主链 | **KEEP**（含进行中 extension token） |
| `reference-code/` | ~5GB 级 | **不进部署**；仓库可保留对照 |
| `recycle/` | 历史 | **不进部署** |

## 2. 路由面

### 2.1 正式保留（产品）

| 前缀 / 路径 | 说明 |
|-------------|------|
| `/api/page-ai/pi/*` | Pi Lab |
| `/api/mnote/tools/{manifest,call,audit}` | Agent 工具（中性名） |
| `/api/knowledge-rag/*` | LightRAG |
| `/api/vault/*` | Vault |
| `/api/page-body/*`、`/api/page-aggregate/*`、tree/realtime 等 | 文档与树主链 |
| `/api/onlyoffice/*` | OnlyOffice |

### 2.2 已删除（非首发）

| 前缀 / 路径 | 实现 | 状态 |
|-------------|------|------|
| `/api/hermes/*`（含 client/sessions/runs/…） | `hermes.rs` + `hermes_client.rs` | **DELETED** |
| `/api/hermes/tools/*` | legacy alias | **DELETED**（仅留 `/api/mnote/tools`） |
| `/api/page-ai/opencode/*`、`/page-ai/opencode` | `page_ai_opencode.rs` | **DELETED** |
| hermes_client 独占 page-ai sessions/runs | `hermes_client` | **DELETED**（Pi 自有 session API 保留） |
| debug：`/tree`、`/document-debug`、`/ui-debug/*` | flag `enable_debug_shell_routes` | 云默认 **false**；代码可保留 |

### 2.3 配置 / 状态字段

| 符号 | 处置 |
|------|------|
| `AppConfig.hermes_base_path` | 已随 hermes 删除 / 测试清理 |
| `AppState.acp_runtime` | **DELETED**（随 ACP） |
| `MNOTE_WEB_ENABLE_LEGACY_NEXT_COMPAT` | 云默认 false |
| `MNOTE_PAGE_AI_PI_LAB` | **保留**，云默认 true |
| `MNOTE_WEB_ACP_*` / `MNOTE_WEB_HERMES_*` / Reasonix wrapper | **DELETED** |

## 3. 源码文件处置

### 3.1 DELETED（整文件）

```text
rust/crates/mnote-web/src/routes/hermes_client.rs
rust/crates/mnote-web/src/routes/hermes.rs
rust/crates/mnote-web/src/routes/page_ai_opencode.rs
rust/crates/mnote-web/src/acp_bridge.rs
rust/crates/mnote-web/src/acp_client.rs
rust/crates/mnote-web/src/acp_runtime.rs
rust/crates/mnote-web/src/acp_session_manager.rs
rust/crates/mnote-web/src/acp_types.rs
scripts/reasonix-acp-wrapper.mjs
```

同步已改：`lib.rs`、`routes/mod.rs`、`app.rs`、相关测试 fixture。

### 3.2 RENAMED（不可整删）

| 现状 | 目标 | 状态 |
|------|------|------|
| `src/hermes_tools/` | `src/mnote_agent_tools/` | **DONE** |
| `routes/hermes_tools.rs` | `routes/mnote_tools.rs` | **DONE** |
| `crate::hermes_tools::` | `crate::mnote_agent_tools::` | **DONE** |

Pi 硬依赖（保留）：

- `page_ai_pi/runtime.rs` → `mnote_agent_tools::knowledge_rag`
- `page_ai_workflow.rs` → `ToolCallInput` + `execute_mnote_tool_call`
- skill pack：`mnote_agent_tools/skill.rs`（`mnote-vault` 等）

### 3.3 KEEP（首发）

```text
routes/page_ai_pi/
routes/knowledge_rag.rs
routes/vault.rs / vault_store.rs / vault_extension_token.rs / …
routes/onlyoffice*.rs
browser/sidebar-page-ai-pi-lab-runtime.js 及 Pi 相关 host
packages/pi-mnote/   （若部署需要）
```

### 3.4 Browser 清理（产品入口）

**产品唯一入口：Pi Lab**

| 路径 | 行为 |
|------|------|
| 浮钮 `data-mnote-action="open-page-ai-pi-lab"` | 只打开 Pi Lab |
| `sidebar-tree-runtime` `open-page-ai` / `open-page-ai-pi-lab` | `mnote:pi-lab-show`，不打开 legacy drawer |
| `openPageAiDrawer()` | **Pi-only stub**：`mnote:pi-lab-show` |
| `sidebar-page-ai-runtime.js` | **已瘦身为 ~100 行 stub** |
| `sidebar-page-ai-{markdown,permission,profile,render,session,skill,target}-runtime.js` | **DELETED** |
| `agent-stream-event-router.js` | **DELETED** |
| page-settings 扩展面板 | Skills/Tools 读 `/api/mnote/tools/manifest`；已移除 MCP / hermes runs 面板与 `/api/hermes/*` fetch |
| document shell Hermes settings inject | **DELETED**（`__mnoteHermesSettingsUrl`） |

合同测试：`page_ai_product_entry_is_pi_lab_only` + 布局无 `open-page-ai` 旧 action。

### 3.5 脚本 / 包装

| 路径 | 处置 |
|------|------|
| `scripts/reasonix-acp-wrapper.mjs` | **DELETED** |
| 仅测 hermes/opencode 的 smoke | **Wave 10**：依赖 `/api/hermes/client` 或 OpenCode host 的 20 个 smoke 已 soft-retire（exit 0 + 注释）；工具类 smoke 改 `/api/mnote/tools/*` |
| OpenHub 负向检查 | 可保留「禁止生成 openhub 目录」类断言 |
| `task126` hermes bridge | 改为负向门禁：`/api/hermes/bridge` 404 + tools manifest 可达 |
| `task116` islands | AI bridge 检查改为 `/api/mnote/tools/manifest` |

## 4. 执行波次（结果）

| Wave | 内容 | 出口 |
|------|------|------|
| **0** | 本文清单 + 文档去历史叙事 | ✅ |
| **1** | agent/架构只描述当前主链 | ✅ AGENTS / ARCHITECTURE |
| **2** | RENAME `hermes_tools` → `mnote_agent_tools`；路由只挂 `/api/mnote/tools` | ✅ |
| **3** | DELETE `page_ai_opencode` + 代理 routes | ✅ |
| **4** | DELETE `acp_*` + Reasonix wrapper + env | ✅ |
| **5** | DELETE `hermes_client` + `hermes.rs` + `/api/hermes/*` | ✅ |
| **6** | browser 产品入口 Pi-only + 合同测试 | ✅ |
| **7** | 全量 `cargo test -p mnote-web` | ✅ 见 §5 |
| **8** | page-ai legacy 子模块 + agent-stream 物理删除；page-settings / document shell 去 Hermes | ✅ |
| **9** | agent tool schema / 头 / env / skill `agent_ids` 中性化 | ✅ |
| **10** | 活跃 smoke 去 `/api/hermes`；死 smoke soft-retire；fixture 字面量中性化 | ✅ |

## 5. 验证门禁

- [x] `cargo test -p mnote-web`（lib，含 tools / pi / knowledge_rag / vault / tree；见执行记录）  
- [x] 启动默认：`libsql-local` + Pi Lab on（`MNOTE_PAGE_AI_PI_LAB` 默认 true）+ legacy compat off + debug shell off  
- [x] 手工或 smoke：登录 → whoami → Pi status → tools manifest → LightRAG status → Vault list → hermes/opencode 404（2026-07-25 本机 :3000）  
- [x] `rg` 主链产品入口无「切换到 Hermes/OpenCode」；浮钮 / tree / drawer 均 Pi Lab  
- [x] 源码：`hermes_client` / `AcpRuntimeManager` / `page_ai_opencode` 文件与 route 注册已删除  
- [x] 部署产物约定：不含 `reference-code/`、`recycle/`（仓库可保留对照）  
- [x] Wave 8/9：browser 死代码删除 + schema 中性化（`mnote.agent_tool*.v1`、skill 仅 `pi`/`chat_only`）
- [x] Wave 10：smoke 工具路径 → `/api/mnote/tools`；hermes-client/opencode 死 smoke soft-retire；search/evidence fixture 中性化

### 执行记录（2026-07-25）

- `cargo test -p mnote-web --lib --test-threads=1`：**849+ passed, 0 failed**  
- 含合同 `page_ai_product_entry_is_pi_lab_only`、`mnote_tools_mount_is_current_only`  
- 测试适配：lazy PageTree reveal、`watch_revision` 缓存键 canonicalize、layout `FILETREE_DND_RUNTIME_JS` 常量名  
- 文件门禁：`hermes_client` / `hermes.rs` / `page_ai_opencode` / `acp_*` / `hermes_tools/` / `reasonix-acp-wrapper.mjs` 均已删除；`mnote_agent_tools` + `mnote_tools` 就位  
- **Wave 8**：page-ai 7 子模块 + agent-stream 物理删除；page-settings 去 `/api/hermes`；document shell 去 Hermes settings inject；`sidebar-page-ai-runtime.js` 瘦身为 Pi-only stub  
- **Wave 9（schema 中性化，已完成）**：  
  - `mnote.agent_tool_manifest.v1` / `mnote.agent_tool.v1`  
  - 响应头 `x-mnote-agent-tool-owner: mnote-web-agent-tools`  
  - 审计 env `MNOTE_AGENT_TOOL_AUDIT_LOG`（兼容旧 `MNOTE_HERMES_TOOL_AUDIT_LOG`）  
  - profile home `MNOTE_AGENT_HOME`（兼容 `HERMES_HOME` / `~/.hermes`）  
  - write meta：`channel=agent`、`client=mnote-agent-plugin`、`refs=agent-tool-call`  
  - skill `agent_ids` 仅 `pi` / `chat_only`  
- **static smoke 适配**：`task-pi-lab-static-smoke.js` 读取 `routes/page_ai_pi/{mod,constants,runtime}.rs` 目录模块（不再假定 monofile `page_ai_pi.rs`）；legacy opencode host 断言改为 Pi-only stub  
- **主链 E2E smoke（本机 :3000，2026-07-25）**：  
  - `node scripts/task-pi-lab-static-smoke.js`：**270 checks passed**  
  - `node scripts/task-pi-lab-api-endpoint-smoke.js`：**17/17 passed**  
  - 登录 `POST /api/auth auth:signIn` → whoami `mnote-e2e`  
  - Pi `GET /api/page-ai/pi/status` enabled + `mnote.page_ai_pi.status.v1`  
  - tools `GET /api/mnote/tools/manifest` → `mnote.agent_tool_manifest.v1` + owner `mnote-web-agent-tools`  
  - LightRAG `GET /api/knowledge-rag/status` 路由挂载 200（本机 daemon 9621 未起 → `lightrag_unreachable`，API 面 OK）  
  - Vault `GET /api/vault/list?rootUri=…` 200  
  - 负向：`/api/hermes/status`、`/api/page-ai/opencode/status` → 404  
- **可选清理（本批）**：删除 `page-ai.css` reasonix/opencode 死样式；测试 fixture `reasonix`→`pi`  
- **Wave 10（smoke / fixture 清理，2026-07-25）**：  
  - 13 个工具 smoke：`/api/hermes/tools/mnote/{call,manifest}` → `/api/mnote/tools/{call,manifest}`  
  - `task116`：检查 agent tools manifest（不再打 hermes bridge）  
  - `task126`：`/api/hermes/bridge` 负向 404 + tools 可达  
  - 20 个依赖 hermes client / OpenCode host 的浏览器或静态 smoke：**soft-retire**（保留文件、exit 0）  
  - fixture：search `Hermes`→`SkillGraph`；evidence `@Reasonix`→`@AtlasNote`；ai_settings skill 示例路径 `.hermes`→`.mnote/agent-profiles`  
  - 保留：负向合同（compat hermes provider）、`HERMES_HOME`/`~/.hermes` 兼容读、`.reasonix`/`.opencode` 目录忽略、`mnote-hermes-tool` 历史 source 兼容  
- **Wave 10.1（desktop-hot 去 OpenCode，2026-07-25）**：  
  - `scripts/desktop-hot.js`：删除 `ENABLE_OPENCODE` / `OPENCODE_CMD` / `SKIP_OPENCODE` / `buildDefaultOpencodeCommand` / `shouldStartOpencode` / opencode task / `MNOTE_OPENCODE_BASE_URL`  
  - `scripts/dev-hot.js`：不再注入 `MNOTE_OPENCODE_BASE_URL`  
  - 测试：`desktop-hot.test.js`、`task-dev-hot-plan-test.js` 断言无 OpenCode 分支  

## 6. 明确不在本清单

- Vault 功能增强 / extension（`design/12-vault` 进行中工作保持不动；本批只做可达性 smoke）  
- LightRAG provider 替换  
- Phase C 流式 apply  
- 把 control-plane 强行改成 turso-remote（云首发默认 **libsql-local**）  
- 删除 `design/old` 历史稿（可选后续，非阻塞）  
- 测试函数名仍可带历史前缀（如 `hermes_tools_*`）；**产品 schema 已中性化**，不必再以「schema 可另批」阻塞出口  
- ~~可选清理：`page-ai.css` 内 reasonix/opencode 死样式、测试 fixture 字面量中性化~~ **本批已做**：CSS 删 reasonix/opencode 死块；dev_seed/mod/mnote_tools 测试字面量 `reasonix`→`pi`（`.reasonix` 目录忽略保留）

## 7. CodeGraph / 残留备忘

- `ToolCallInput`：在 `mnote_agent_tools`  
- `page_ai_pi/runtime.rs` 绑定 `mnote_agent_tools::knowledge_rag`  
- 测试函数名仍可带 `hermes_tools_*` 前缀（历史命名，非产品路由）  
- 正式 tools **仅** `/api/mnote/tools`  
- 产品 Page AI：**仅** `/api/page-ai/pi/*` + browser Pi Lab host  

---

**状态**：Wave 0–10 / 10.1 已完成；全量 lib 测试绿；主链 E2E smoke 绿；活跃 smoke 已切到 `/api/mnote/tools`，死 hermes/opencode smoke 已 soft-retire；desktop-hot 不再启动 OpenCode。