lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
mnote/design/old/07-ai/process/7-phase7-ai-kernel-projection-plan-v3.md
T

9.7 KiB
Raw Permalink Blame History

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 继续负责真相。

Reference in New Issue View Git Blame Copy Permalink