lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5f97800489a2af4e0a5cc5d1ea07a69740f58157
mnote/design/03-rust-web/done/3-4-mnote-web-3104-boundary-retirement-plan-v1.md
T
lix-2026 5f97800489 chore: align local-first control plane and editor fixes 
- wire SQLite control-plane access/session paths into Rust web local-folder routes

- preserve local Markdown attachment semantics across upload, reload, and secondary-pane resource tabs

- refresh design governance docs, Reasonix task templates, and bug records

- retire root .mcp.json local MCP config
2026-05-23 23:38:42 +08:00

446 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/reference/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 迁移为前提，最终退役。**
Reference in New Issue View Git Blame Copy Permalink