mnote/design/03-rust-web/done/3-4-mnote-web-3104-boundary-retirement-plan-v1.md

# 3-4 [done] mnote-web `3104` 边界收口与退役方案 v1

> 更新时间：2026-04-23
>
> 关联文档：
> - `/mnt/Data1T/mnote/ARCHITECTURE.md`
> - `/mnt/Data1T/mnote/design/01-05-current-priority-overview.md`
> - `/mnt/Data1T/mnote/design/03-rust-web/process/3-rust-web-long-term-architecture-v1.md`
> - `/mnt/Data1T/mnote/design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md`
> - `/mnt/Data1T/mnote/design/05-editor-mainline/process/5-5-page-aggregate-single-truth-alignment-v1.md`

## 1. 文档目的

这份文档只回答一个已经进入架构层的问题：

> **当前 `127.0.0.1:3104` 还有没有存在意义，是否应从系统主链中移除。**

先给结论：

> **`3104` 不应该继续作为用户、浏览器、前端 runtime 可感知的端口存在。**
>
> **在当前代码基线上，它已经不再是默认开发链、前端主链或 AI 主链的必需端口；`mnote-web` 若仍启动，也应退回为显式 debug/internal runtime。**

因此当前正确目标不是：

- 继续接受多端口长期并存
- 或者为了“看起来只剩 3000”而直接硬删 `3104`

而是：

> **先把 `3104` 收口为 internal-only 边界，再按依赖拆解顺序逐步退役，最终让前端公开主链只剩 `3000`。**

## 1.1 完成结论

截至 2026-04-23，这份方案针对“`3104` 作为默认/公开边界”的收口已经完成，当前可固定为：

- `3000` 是唯一前端公开入口
- 正式主链已移除 `MNOTE_WEB_BASE_URL`、浏览器侧 `mnoteWebBaseUrl / mnoteWebTreeShellEnabled`
- `mnote-web` 默认监听地址已改为 `127.0.0.1:0`，不再默认绑定 `3104`
- `/tree`、`/document-debug` 等 debug 壳仅在显式环境变量下注册
- legacy smoke 只有在显式设置 `MNOTE_WEB_SMOKE_BASE_URL` 时才会命中 debug runtime

需要额外说明的是：

> **若本机仍看到 `127.0.0.1:3104` 监听，应视为旧 `mnote-web` 进程残留，不代表当前默认启动链。**

---

## 2. 当前真实状态

### 2.1 `3104` 当前是什么

`3104` 曾对应 Rust `mnote-web` 的默认监听地址，而不是首页入口端口。

当前 `mnote-web` crate 仍承载的能力包括：

- `/health`
- `/tree`
- `/document-debug`
- `/api/tree/commands`
- `/api/stream/events`
- `/api/hermes/bridge`
- `/api/compat/next/sidebar`

这说明它不是单纯“没人用的历史残留壳”，而是：

> **一个仍保留 debug / compat / internal transport 能力的 Rust Web 组件。**

### 2.2 当前真正的问题不在“它存在”，而在“它泄漏”

当前最不应该发生的事情，不是 `mnote-web` 作为内部服务存在，而是：

- 浏览器 runtime 直接知道 `mnoteWebBaseUrl`
- 前端页面逻辑直接拼 `3104`
- smoke / 调试脚本把 `3104` 当成正式主入口前提
- 新功能继续优先接到 `mnote-web compat` 路由

换句话说，问题的关键不是：

> “有没有本机内部回源端口”

而是：

> “这个内部回源边界是否继续污染前端主链与长期架构”。

### 2.3 当前已经完成的一次收口

当前已经确认完成的收口包括：

- 浏览器公开 runtime 不再暴露 `mnoteWebBaseUrl`
- Sidebar tree stream 浏览器侧统一走同源 `3000/api/mnote-web/stream`
- `public/mnote-env.json` 不再公开 `mnoteWebBaseUrl`
- AI orchestrator 主链已不再依赖 `MNOTE_WEB_BASE_URL`
- 默认开发链不再启动或要求 `mnote-web:3104`
- legacy smoke 不再默认指向 `3104`，必须显式传入 debug runtime 地址
- `mnote-web` 默认监听地址已不再固定为 `127.0.0.1:3104`

因此现在的架构判断应改写为：

> **`3000` 已经是前端唯一公开主入口，而 `3104` 已从默认边界退回到显式 debug/internal-only。**

---

## 3. 为什么现在还不能直接删除 `3104`

当前已经不再存在正式产品链必须依赖 `3104` 的情况，但仍保留三类遗留能力面需要继续降级：

### 3.1 Tree realtime contract 仍未完全对齐最终主链协议

当前 `3000/api/mnote-web/stream` 已不再回源 `mnote-web /api/stream/events`，但它仍是一个 Next route 级的过渡 transport，而不是最终的统一 realtime 主链。

因此当前现实不是：

- `3000` 已经原生持有 tree realtime transport

而是：

- `3000` 已完成对 `3104` 的切断
- 正式 realtime contract 仍需继续向 `snapshot / delta / resync` 单一主链收口

### 3.2 Hermes / AI tool registry 归属仍需继续收口

2026-05-13 口径更新：本文记录的是 `3104` 退役阶段的历史边界判断，不再代表当前 AI 长期编排主线。当前 AI 长期方向已改为 Hermes 页面内客户端 + mnote Hermes skill/plugin；旧 `openai-agents-python` 编排层与旧 `/api/hermes/bridge` 只作为历史或兼容路径看待。

当前前端 AI route 与后端 `openai-agents-python` 编排层已经不再通过 `MNOTE_WEB_BASE_URL` 回源 `mnote-web /api/hermes/bridge` 获取 runtime tool 结果，而是走后端 orchestration + 本地 `bridge-runtime`。

这意味着：

- `3104` 已不再阻塞 AI 主链
- 但 AI tool registry / tool result contract 的正式归属还需继续明确

### 3.3 仍保留实验 / 调试 / compat 壳

以下链路仍带有明显过渡期性质：

- `/tree`
- `/document-debug`
- `compat/next/sidebar`
- 旧 smoke 脚本仍可在显式传入 runtime 地址后命中 debug runtime
- `/api/auth/mnote-web-token` 仍保留给 legacy debug/runtime smoke

这些路径已不在当前主路径上，但说明：

> **`mnote-web` 仍处于“内核能力 + compat + 调试壳”混杂状态。**

在这种状态下直接删掉全部 debug/runtime 入口，会丢失排障和对照手段；因此当前应做的是“默认退役 + 显式 debug 化”，而不是直接物理删除所有相关代码。

---

## 4. 当前必须立即固定的架构口径

### 4.1 对用户与浏览器的公开口径

当前必须固定为：

- 页面访问入口只有 `3000`
- 浏览器不得显式依赖 `3104`
- 前端公开 runtime / public config 不得再暴露 `mnoteWebBaseUrl`

### 4.2 对系统内部的口径

当前必须固定为：

- `3104` 只允许作为 loopback internal service 存在
- 它不是产品入口
- 它不是长期对外 contract
- 它只是 Rust Web transport 尚未并入最终主链前的内部边界

### 4.3 对未来收口方向的口径

当前必须固定为：

> **长期目标不是保留 `3000 + 3104` 双长期入口，而是把 `3104` 承担的正式能力迁走，最终退役 `3104`。**

---

## 5. 需要立即回退或禁止继续扩散的方向

下面这些方向应该立即视为错误方向：

### 5.1 禁止浏览器继续读取 `mnoteWebBaseUrl`

包括但不限于：

- 浏览器组件中直接构造 `http://127.0.0.1:3104`
- 通过 runtime config 让前端知道 `mnote-web` 基址
- 新页面逻辑绕过同源 `3000`，直接访问 `3104`

### 5.2 禁止把新长期业务继续堆进 `compat`

尤其不能继续把以下长期语义放进 `mnote-web compat`：

- 正式 sidebar 数据 contract
- 正式 page aggregate contract
- 正式 tree realtime contract
- 正式 AI tool orchestration contract

`compat` 只能继续承担：

- 过渡转接
- 旧链路对照
- fixture / smoke 支持

不能继续成为新增长期业务的落点。

### 5.3 禁止把 `/tree` 与 `/document-debug` 当成正式页面主链

它们可以保留为：

- 实验壳
- 调试入口
- 迁移对照入口

但不能继续被当成：

- 首页入口前置条件
- 正式文档页 transport
- 页面内主编辑区 runtime 壳

### 5.4 禁止新 smoke 把 `3104` 当产品主链前提

后续 smoke 要区分两类：

- `3000` 主站 smoke
- `mnote-web` 内部服务 smoke

不能再写成：

> “只要功能涉及 Rust，就默认直接打 `3104`”

---

## 6. `3104` 退役的阶段方案

## 6.1 Phase 0：公开边界收口

目标：

- 前端主链只公开 `3000`
- 浏览器不再感知 `3104`
- `3104` 收回 internal-only

当前状态：

- [x] 已完成

完成定义：

- [x] 浏览器公开 runtime 不再暴露 `mnoteWebBaseUrl`
- [x] Sidebar realtime 浏览器侧走同源 `3000/api/mnote-web/stream`
- [x] `public/mnote-env.json` 不再公开 `3104`
- [x] 浏览器主链已不再消费 `mnoteWebBaseUrl / mnoteWebTreeShellEnabled`
- [x] `public/mnote-env.json` 已去除 `mnoteWebTreeShellEnabled`

说明：

> 这一步解决的是“前端被多端口污染”的问题，不等于 `3104` 已退役。

## 6.2 Phase 1：把正式 sidebar/query 能力移出 `compat`

目标：

- `sidebar` 正式查询链不再依赖 `mnote-web /api/compat/next/sidebar`
- `3000` 直接消费 Rust bridge / kernel projection 正式 contract

当前状态：

- [x] 已完成

已完成：

- [x] `/api/sidebar` 已优先走 Rust bridge query，而不是继续扩 `compat sidebar`
- [x] 正式前端链路已不再调用 `fetchSidebarDatasetFromMnoteWeb`

已完成补充：

- [x] `compat/next/sidebar` 已明确降级为过渡 / 调试用途
- [x] 依赖 `compat sidebar` 的旧链路已收口为 legacy debug smoke，且必须显式传入 `MNOTE_WEB_SMOKE_BASE_URL`

## 6.3 Phase 2：tree realtime transport 正式并入主链

目标：

- `3000` 或其背后的正式服务直接承载 tree realtime contract
- 不再通过 Next route 反代 `3104 /api/stream/events`

当前状态：

- [x] 已完成

完成定义：

- [x] `3000` 的 tree stream 不再依赖 `MNOTE_WEB_BASE_URL`
- [ ] realtime stream contract 与 `3-3` 文档统一
- [ ] snapshot / delta / resync 成为正式主链，而不是代理式过渡链
- [x] `mnote-web /api/stream/events` 不再是前端主站 realtime 前置

备注：

> 这是 `3104` 能否退役的第一硬前提。只要 realtime stream 还在内部回源 `3104`，它就不能删除。

## 6.4 Phase 3：Hermes runtime bridge 从 `mnote-web` 迁出

目标：

- AI runtime tool bridge 不再强依赖 `MNOTE_WEB_BASE_URL`
- 历史 `openai-agents-python` 编排层不再被描述为长期 AI 服务面；新的正式边界是 Hermes client proxy + mnote Hermes plugin

推荐方向：

- 由 Hermes 持有 session / run / tool event / usage / model 编排
- Rust `bridge-runtime` 作为 mnote 业务语义执行层，经 Hermes skill/plugin 暴露
- `3000` 只负责页面与同源 API 边界，不再额外绕回 `3104`

当前状态：

- [x] 已完成

完成定义：

- [x] 前端 AI run route 不再通过 `mnote-web /api/hermes/bridge` 获取 tool 结果
- [x] 后端 `ai_document_agent.py` 不再把 `MNOTE_WEB_BASE_URL` 作为正式硬依赖
- [ ] AI tool registry / tool result contract 有独立正式归属

备注：

> 这是 `3104` 能否退役的第二硬前提。只要 AI tool bridge 还依赖它，它就不是可删除端口。

## 6.5 Phase 4：实验壳与调试入口降级

目标：

- `/tree`
- `/document-debug`
- 旧 `tree shell`
- 与 `3104` 直连的实验 host

全部明确降级为：

- debug only
- spike only
- legacy fallback only

当前状态：

- [~] 部分完成

完成定义：

- [x] 正式产品链不再依赖 `/tree`
- [x] 正式文档页不再依赖 `/document-debug`
- [x] 仍保留的实验组件不再混入默认主链
- [x] legacy smoke 已改为显式传入 `MNOTE_WEB_SMOKE_BASE_URL` 才会触发 debug runtime
- [x] `/tree` 与 `/document-debug` 已改成仅在显式 debug 开关下注册

已完成：

- [x] 浏览器侧 runtime config 不再兜底暴露 `mnoteWebBaseUrl`
- [x] `leptos_tiptap_iframe_debug` 不再通过 `mnoteWebBaseUrl` 推导调试 runtime 地址
- [x] `MnoteWebTreeShell` 已从前端正式代码路径移除
- [x] `mnote-web` 默认已不再注册 `/tree`、`/document`、`/document-debug`

## 6.6 Phase 5：正式退役 `3104`

当前状态：

- [x] 已完成

前提必须同时满足：

- [x] Sidebar / tree query 正式主链不再依赖 `compat sidebar`
- [x] tree realtime transport 已从 `3104` 迁出
- [x] Hermes runtime bridge 已从 `3104` 迁出
- [x] `/tree` 与 `/document-debug` 已降为非正式必需
- [x] 开发启动链不再要求单独拉起 `mnote-web:3104`

完成定义：

- [x] 默认开发工作流中不再需要 `3104`
- [x] `MNOTE_WEB_BASE_URL` 从正式主链配置中删除
- [x] `mnote-web` 若仍存在，则只作为显式 debug/internal app 运行，而不是长期内网网关
- [x] 运行态旧 `mnote-web:3104` 残留进程已清理；最新二进制默认启动不再监听 `3104`

说明：

> **`3-4` 的完成定义是退役 `3104` 作为默认/公开边界，不等于 `mnote-web`、tree realtime contract 或 AI tool registry 的所有后续演进已经结束。**
>
> **相关后续工作分别继续由 `3-3-rust-web-tree-realtime-event-stream-v1.md` 与 `07-ai` 主线承接，但它们不再构成 `3104` 退役阻塞。**

---

## 7. 推荐执行顺序

当前建议顺序固定为：

1. 完成 `Phase 2` tree realtime transport 收口
2. 完成 `Phase 3` Hermes runtime bridge 迁移
3. 完成 `Phase 4` 实验 / 调试壳降级
4. 最后执行 `Phase 5` 退役 `3104`

原因很简单：

- realtime 是前端主链的硬依赖
- AI bridge 是在线 AI 的硬依赖
- 调试入口最后再降级，避免迁移过程失去观测手段

---

## 8. 与 `8123` 的关系

`8123` 与 `3104` 不是同一类问题。

`8123` 当前更接近：

- spike runtime
- leptos-tiptap 独立开发端口
- 开发期资产构建 / 调试端口

而 `3104` 当前更接近：

- `mnote-web` 内部 transport 边界
- Rust Web 正式能力尚未完全并入主链前的内网服务

所以当前不应把两者混为一谈。

正确顺序是：

1. 先解决 `3104` 的正式能力迁移与边界退役
2. 再继续压缩 `8123` 这类 spike / dev runtime 端口

---

## 9. 一句话收口

当前关于 `3104` 的正确判断不是：

> “它已经没用了，可以直接删。”

也不是：

> “既然浏览器看不到，就可以长期保留。”

而是：

> **`3104` 现在仍有内部存在意义，但这种意义是过渡性的。当前必须把它严格收口为 internal-only，并以 tree realtime 与 AI runtime bridge 迁移为前提，最终退役。**