mnote/design/old/07-ai/process/7-phase7-ai-kernel-projection-plan-v3.md

# 7 [process][recycle] mnote Kernel Phase 7 AI 与 CLI 外置 Agent 边界实施方案 v3

> 更新时间：2026-05-05
>
> 上位依据：
> - `/mnt/Data1T/mnote/ARCHITECTURE.md`
> - `/mnt/Data1T/mnote/design/01-05-current-priority-overview.md`
> - `/mnt/Data1T/mnote/design/01-tree-first-graph-kernel/process/1-tree-first-graph-kernel-v1.md`
> - `/mnt/Data1T/mnote/design/03-rust-web/process/3-rust-web-long-term-architecture-v1.md`
> - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-6-tree-command-protocol-cutover-stage2-v1.md`
> - `/mnt/Data1T/mnote/design/05-editor-mainline/process/5-5-page-aggregate-single-truth-alignment-v1.md`
> - `/mnt/Data1T/mnote/design/05-editor-mainline/process/5-6-page-aggregate-alignment-checklist-v1.md`
> - `/mnt/Data1T/mnote/design/07-ai/done/7-1-phase7-document-ai-minimum-loop-checklist-v1.md`
> - `/mnt/Data1T/mnote/design/old/07-ai/process/7-phase7-ai-kernel-projection-plan-v2.md`
>
> 本稿与 `v2` 的关系：
> - `v2` 记录的是文档页 AI 最小闭环与 `openai-agents-python` sidecar 的主线收口
> - 本稿记录的是从“双中心并存”过渡到 `CLI-first` 之前的边界判断，重点保留当时为何要把页面内 AI 与外置 agent 拆层
> - 若未来继续演进，长期口径以 `v4` 为准；本稿不再作为当前长期判断依据
>
> 2026-05-05 追加说明：
> - 本稿已被 `/mnt/Data1T/mnote/design/07-ai/process/7-phase7-ai-kernel-projection-plan-v4.md` 覆盖
> - `v3` 只保留用于记录“双中心并存”的过渡判断
> - 当前长期口径不再采用本稿，而采用 `v4` 的 `CLI-first`
> - 当前统一口径是：`mnote-cli` 是唯一长期 agent 执行面，`openai-agents-python`、Hermes、Codex 都只是可插拔外置 agent

---

## 1. 文档目的

这份稿只回答一个问题：

> **`mnote` 的 AI 能力到底应该以“内置 agent”为中心，还是以“CLI 兼容外置 agent”为中心。**

当前长期结论已被 `v4` 修正为单一执行面：

1. Web 文档页 AI 面板继续保留，但只作为页面内交互壳 / CLI host
2. `mnote-cli` 是唯一长期 agent 执行面
3. Hermes、Codex、`openai-agents-python` 这类外置 agent 不再直接依赖产品内编排细节，而是统一通过 CLI / 稳定工具面进入系统
4. Rust kernel 继续作为唯一事实源与真执行面

一句话收口：

> **本稿原始判断是“不要退回成只有 CLI”；该口径现已被 `v4` 覆盖。当前长期口径是：CLI 作为唯一执行面，Web AI 只保留为页面内交互壳。**

---

## 2. 当前完成情况

### 2.1 文档页 AI 最小闭环已完成

`7-1` 已经完成，说明当前文档页 AI 至少已经跑通：

- 当前页 page aggregate 上下文读取
- `openai-agents-python` sidecar 编排
- 标题改名与正文写回
- `Hermes` fallback / 对照链
- `model_key / profile / tool registry` 的可见配置面

这意味着当前系统已经不是“要不要有 AI”，而是“AI 的长期边界该放在哪一层”。

### 2.2 `mnote-cli` 已经不是空壳

当前 Rust 侧已有 `mnote-cli`，并且已经覆盖：

- `page`
- `block`
- `mindmap`
- `search`
- `sidebar`
- `editor`
- `tool`

同时它已经有较清晰的执行参数面：

- `--json`
- `--execute`
- `--session-id`
- `--reason`
- `--idempotency-key`
- `--validate-only`
- `--dry-run`

这说明 CLI 已经具备成为“外置 agent 统一兼容层”的基础，而不是只做调试壳。

### 2.3 内置 AI 现在的定位已经足够清晰

当前 `wolai-backend/app/services/ai_document_agent.py` 这一层已经把文档页 AI 约束成：

- 只处理当前文档页
- 只使用有限工具面
- 通过 page aggregate 组织上下文
- 通过 `slash_run / doc_insert_blocks / doc_replace_range` 这类写链回写

所以内置 AI 的价值不是“全能 agent 平台”，而是“产品内即时编辑体验”。

---

## 3. 核心判断

### 3.1 `v3` 当时对 CLI-first 的顾虑

本节保留的是 `v3` 当时尚未接受 `CLI-first` 时的顾虑：

1. 担心产品内即时体验变差
2. 担心页面上下文、审核、回写被拆散
3. 担心外置 agent 变强但产品主链变弱

这些顾虑在 `v4` 中的处理方式不是退回“双中心”，而是明确：

- Web AI 面板继续保留
- 但它只作为 `mnote-cli` 的页面内 host / client
- 执行面不再由产品内 AI 单独持有

### 3.2 也不建议把内置 AI 变成唯一中心

相反，如果继续把内置 AI 当唯一中心，另一个问题会变得更严重：

- agent 更新能力受限
- 记忆层容易变成产品私有状态
- 能力面会偏向单一页面操作
- Hermes / CLI 这类外置 agent 很难稳定接入

所以正确做法不是“只保留内置 AI”，而是**把 `mnote-cli` 收口为唯一长期 agent 执行面**。

### 3.3 当前长期分层应理解为三层

1. **Web AI 面板 / 页面内交互壳**
   - 负责文档页内交互、上下文读取、局部回写、审核辅助

2. **`mnote-cli`**
   - 负责唯一长期 agent 执行面，以及外置 agent、脚本、批处理、离线任务、可观测执行

3. **Rust kernel**
   - 负责所有事实源、命令、查询、投影、审计与回放

这三层之间不应该互相抢语义中心。

---

## 4. 架构边界

### 4.1 Rust kernel

负责：

- 页面、树、边、投影、查询、命令
- 结构化写入的最终事实源
- 审计、trace、回放、恢复

不负责：

- 直接承担 UI 体验
- 直接承担通用 agent 编排

### 4.2 Web AI 面板（产品内交互壳）

负责：

- 当前文档页的即时编辑
- 选中上下文的解释与改写
- 通过正式命令面回写
- 审核与继续编辑的体验闭环

不负责：

- 成为全局 agent 平台
- 取代 CLI 的批处理入口
- 持有独立长期记忆真源
- 成为第二个长期执行面

### 4.3 `mnote-cli`

负责：

- 作为唯一长期 agent 执行面与统一命令面
- 作为人类与脚本的可执行入口
- 作为 Hermes、Codex、批处理、定时任务的兼容层

应该提供：

- 稳定的 JSON 输出
- 明确的 plan / execute 分层
- 会话与 trace 参数
- 幂等键
- 校验模式与 dry-run
- 可发现的 capability manifest

### 4.4 Hermes / Codex / `openai-agents-python`

负责：

- 可插拔外置 agent 场景
- 过渡平台
- 回归对照

不负责：

- 成为产品内部独立长期主编排
- 直接绕过 Rust runtime 写业务数据

---

## 5. CLI 应该补什么

### 5.1 统一能力发现

CLI 需要先变成“可发现能力集合”，而不是一堆散命令。

最少要能回答：

- 当前可写什么
- 当前可读什么
- 当前哪些命令是计划态
- 当前哪些命令可直接执行
- 当前命令属于哪个 scope

### 5.2 统一执行元数据

外置 agent 真正缺的不是命令本身，而是执行元数据一致：

- `session_id`
- `actor_id`
- `actor_type`
- `reason`
- `idempotency_key`
- `validate_only`
- `dry_run`
- trace / audit id

这些都应该在 CLI 层成为一等参数。

### 5.3 统一记忆入口

这里的“记忆”不应该是产品壳里的隐式状态，而应该拆成三层：

1. 会话记忆
   - 某次 agent 运行的上下文与结果

2. 配置记忆
   - profile、工具注册、运行时偏好

3. kernel 记忆
   - 真实业务对象、projection、历史变更

CLI 负责把这三层显式化，外置 agent 通过它读取或写入，不再自己猜。

### 5.4 统一机器可读输出

如果 Hermes、Codex、脚本都要接入，CLI 输出必须稳定机器可读。

最低要求：

- `--json` 必须完整
- 错误结构必须稳定
- 成功结构必须能直接喂给上层 agent
- 人类输出和机器输出要分开

---

## 6. Web AI 面板继续保留什么

### 6.1 继续保留

- 当前页正文改写
- 当前页标题改名
- 当前页上下文读取
- 页面内审核与继续编辑
- 与 page aggregate 对齐的最小闭环

### 6.2 不继续扩写

- 通用多 agent 平台壳
- 全局记忆产品壳
- 独立于页面主链的第二份真相
- 把 CLI 功能重复做一遍

### 6.3 设计原则

Web AI 面板只做“最近的一层”，不要做“全部层”。

因为页面内 AI 交互壳的目标是让用户快，不是让系统像一个独立平台那样完整。

---

## 7. 迁移策略

### 阶段 1：收口 CLI 兼容面

- 把 `mnote-cli` 明确成唯一长期 agent 执行面
- 保持现有命令树不乱长
- 先统一 JSON / plan / execute / trace / idempotency

### 阶段 2：补稳定能力发现

- 输出 capability manifest
- 区分 read / write / job
- 区分 document / tree / workspace scope

### 阶段 3：外置 agent 接入

- Hermes 通过 CLI 进入系统
- 后续其他 agent 也通过同一 CLI 进入
- 不再为每个 agent 单独做一套产品内桥接逻辑

### 阶段 4：保留页面内 AI host

- 文档页 AI 继续保留当前页面内主路径
- 只做 UI 内最小闭环
- 不回退到全局壳
- 不再把页面内 host 叙述成独立长期执行面

---

## 8. 非目标

本稿不做：

- 重新实现一个新的通用 AI 平台
- 把 Hermes 直接升级成产品内主编排中心
- 把内置 AI 删除掉
- 把所有页面内交互体验都删除并强制改成手工 CLI 操作
- 在 CLI 里重复一套产品 UI

---

## 9. 完成判定

当下面几项成立时，才算这个方向真正站稳：

- `mnote-cli` 是唯一长期 agent 执行面，而不是纯调试壳
- Web AI 面板只负责页面内最小闭环
- `openai-agents-python`、Hermes、Codex 等外置 agent 通过 CLI 进入系统
- Rust kernel 仍然是唯一事实源
- `model_key / profile / tool registry` 这些产品语义不被页面内 host 私有化

一句话收口：

> **本稿保留的是“产品内 AI + CLI 兼容层”并存的过渡判断；当前长期口径已经改为：`mnote-cli` 是唯一执行面，Web AI 只是页面内交互壳，Rust kernel 继续负责真相。**