lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dabaf03bd7687afe51568e94fa20874a775d6ea2
mnote/design/old/07-ai/process/7-62-recycle-page-ai-board-first-full-rewrite-v1.md
T
Agent Board dabaf03bd7 重构基线
2026-06-25 21:08:17 +08:00

17 KiB
Raw Blame History

7-62 [recycle] Page AI Board-first full rewrite v1

创建时间：2026-06-19

当前状态：RECYCLE

Owner：07-ai / Agent Board bridge / Page AI shell / MNote capability plugins

上位依据：

  • ARCHITECTURE.md
  • CURRENT_ARCHITECTURE.md
  • design/07-ai/process/7-18-local-first-agent-file-editing-control-plane-v1.md
  • design/07-ai/done/7-38-page-ai-sidebar-runtime-owner-split-v1.md
  • design/07-ai/done/7-39-page-ai-agent-selector-context-authorization-settings-v1.md
  • design/07-ai/done/7-40-page-ai-context-envelope-and-run-receipt-v1.md
  • design/07-ai/done/7-50-lightrag-knowledge-rag-provider-v1.md
  • design/07-ai/done/7-60-page-ai-settings-ia-cleanup-v1.md

过时原因：已由 design/07-ai/process/7-65-opencode-webui-embed-page-ai-v1.md 替代；Page AI 新主路径只接入 opencode 官方 runtime + 官方 WebUI。

1. 第一结论

当前 Page AI 继续维护 Hermes / Reasonix / Chat-only / ACP runtime / provider session / skill toggle / tool event 映射，会让 MNote 重复承担 Agent Board 已经承担的中介层职责。后续不应再“小修小补”当前 Page AI，而应完整重构为 Board-first Page AI：

MNote Page AI = 页面入口 + 上下文/权限/目标封装 + 运行态展示
Agent Board   = worker 选择 + provider 适配 + workflow 编排 + QA/review/失败回流
ZCode/Reasonix/Codex/GenericAgent = Board worker，不直接成为 MNote Page AI provider

重构目标不是“把 ZCode 接进 Page AI”，而是“让 Page AI 不再适配 provider”。ZCode 胜出只决定 Board 默认 worker，MNote 只调用 Board。

2. 当前问题

2.1 Page AI 责任过载

当前 Page AI 同时负责：

  • agent/provider selector：Hermes / Reasonix / Chat-only。
  • ACP runtime lifecycle：session、resume、queue、event、permission。
  • provider 特化逻辑：Reasonix native-live、Hermes profile、Chat-only remote conversation。
  • skills/tools UI：MNote skills、Hermes skills、Reasonix skills 混合展示。
  • run history：MNote 本地 session、外部 provider conversation、runtime audit 混合展示。
  • 写入主路径：既有 MNote tool 写入，又有 agent 原生文件编辑。

这导致每新增一个 agent 或 provider 都要重复改 Page AI 前端、Rust route、session store、event parser、设置页和 smoke。

2.2 与 Agent Board 职责重复

Agent Board 已经具备：

  • worker preset 与角色路由。
  • ZCode / Reasonix / Codex / GenericAgent / reviewer / QA browser worker。
  • workflow run、task group、review、QA、git gate。
  • provider event 映射、任务状态、summary、MemPalace 归档。
  • ZCode app-server / CLI fallback 链路。

MNote 再维护一套 provider 层会形成双中介，长期 bug 面大于收益。

3. 新系统边界

3.1 MNote Page AI 只保留四件事

  1. 上下文采集：当前页、选区、打开资源、页面标题、rootUri、workspaceId、sourceKind、Page Aggregate snapshot。
  2. 权限与目标：allowed roots、write/read policy、当前目标文件、是否允许修改真实文件。
  3. 任务入口：选择 worker / workflow / intent，提交 Board run。
  4. 可视化回放：展示 Board run/task/group 状态、事件、summary、文件变更提示、QA 截图链接。

3.2 Agent Board 承担中介层

Board 负责：

  • provider 适配：ZCode / Reasonix / Codex / future agents。
  • worker 选择：developer / reviewer / qa / designer / researcher / workflow。
  • workflow：快速编辑、问答、bug 修复、功能开发、QA 验证、review gate。
  • run 状态：running / blocked / failed / complete。
  • 事件：file_read / file_edit / command / command_output / screenshot / summary。
  • 失败回流与人工介入。

3.3 MNote skills / plugins 重新定义

MNote 的 skill/plugin 不再是 “Hermes/Reasonix profile 内的技能开关”，而是 Board 可消费的 MNote capability manifest：

mnote.current_page.read
mnote.selection.read
mnote.open_resources.snapshot
mnote.allowed_roots.describe
mnote.lightrag.query
mnote.reference.open
mnote.page_aggregate.snapshot
mnote.local_file.receipt

这些 capability 由 MNote 生成 manifest/envelope，Board worker 通过任务 prompt、MCP 或后续 bridge tool 使用。MNote 不再为每个 worker 维护单独 skill UI。

4. 新 Page AI 信息架构

4.1 顶层只保留四个页签

页签 作用 Owner
对话/任务 用户输入、当前目标、提交 Board run MNote
工作流 worker / workflow 选择、执行策略 Agent Board
运行 Board run/task/group 状态、事件、summary Agent Board
上下文 当前页、选区、资源、权限、LightRAG capability MNote

删除旧一级页签：

  • Hermes
  • Reasonix
  • Chat-only
  • Runtime
  • 高级
  • provider-specific skills 面板

如确需保留，只能放在 debug/legacy 折叠区，不作为默认主链。

4.2 默认入口

默认按钮不再是“发送给 Reasonix/Hermes”，而是：

交给 Agent Board

默认配置：

projectId = mnote 项目
workflow = builtin-page-ai-developer-direct
worker = Board direct workflow developer（现为 zcode-deepseek-flash）
writePolicy = 按 MNote allowed roots

5. 接口契约

5.1 MNote → Board envelope

新增 MNoteBoardTaskEnvelope：

{
  "schema": "mnote.page_ai.board_task.v1",
  "intent": "ask|edit|fix|feature|qa|review|custom_workflow",
  "message": "用户原始输入",
  "workspaceId": "...",
  "sourceKind": "local-folder",
  "rootUri": "file:///...",
  "documentId": "...",
  "pageTitle": "...",
  "primaryTarget": {
    "kind": "markdown_file",
    "relativePath": "docs/page.md",
    "absolutePath": "/.../docs/page.md"
  },
  "selection": {
    "text": "...",
    "range": null
  },
  "contextRefs": ["current_page", "selection", "active_editor", "folder"],
  "allowedRoots": [
    { "rootUri": "file:///...", "permission": "write" }
  ],
  "capabilities": [
    "mnote.current_page.read",
    "mnote.allowed_roots.describe",
    "mnote.lightrag.query"
  ],
  "writePolicy": {
    "allowFileWrite": true,
    "requireHumanApproval": false,
    "forbidMnoteInternalStateWrite": true
  }
}

5.2 Board API 选择

MNote 服务端先封装 Board API，不让前端直连 3901。

新增 MNote routes：

GET  /api/page-ai/board/status
GET  /api/page-ai/board/workers
GET  /api/page-ai/board/workflows
POST /api/page-ai/board/runs
GET  /api/page-ai/board/runs/:id
POST /api/page-ai/board/runs/:id/cancel

内部对应 Board：

GET  http://127.0.0.1:3901/api/health
GET  http://127.0.0.1:3901/api/workers/catalog?projectId=<mnote>
GET  http://127.0.0.1:3901/api/workflow-presets?projectId=<mnote>
POST http://127.0.0.1:3901/api/workflow-runs
GET  http://127.0.0.1:3901/api/workflow-runs/:id

优先使用 /api/workflow-runs，而不是 /api/controller/message，因为 Page AI 需要可预测的 workflow/worker 选择和 run id。

5.4 Board 需要补给 MNote 的接口

这不是单向的“ MNote 适配 Board ”，而是双向协议。为了让 Page AI 真正瘦身，Board 侧还需要补出一组面向 MNote 的稳定接口：

A. Page AI envelope 预检

POST /api/page-ai/envelopes/validate

作用：在真正创建 run 前，校验 envelope 是否满足 workflow/worker 的最小要求，返回：

  • 缺失的字段。
  • 是否需要 worker 具备 vision / browser / filesystem / multimodal。
  • 是否需要人工确认。
  • 推荐 workflowId / workerPresetId。

这样 MNote 可以在 UI 层先提示“当前上下文不够”或“建议切换到 QA workflow”，避免无效提交。

B. Page AI envelope 到 workflow 的映射

POST /api/page-ai/envelopes/route

作用：Board 根据 envelope 自动选择 workflow / worker / reviewer / QA 路线，返回最终路由结果：

  • workflowId。
  • workerPresetId。
  • groupId 或 runId。
  • 是否需要用户二次确认。
  • 预估阶段序列。

这能让 MNote 不再内置 worker 选择逻辑，只保留“意图 + 上下文”。

C. Run 级事件流

GET /api/workflow-runs/:id/events
GET /api/workflow-runs/:id/node-runs/:nodeRunId/events

作用：MNote 不只看最终 run summary，而是直接消费 Board 的结构化事件流，渲染：

  • 当前节点。
  • 进度阶段。
  • file_read / file_edit / command / screenshot / artifact。
  • block / retry / resume 原因。

如果 Board 未来提供 WS/SSE，这两条可退化为 snapshot/polling 兼容层，但 MNote 默认应面向事件流抽象，而不是 provider 私有日志。

D. Run receipt / artifact receipt

GET /api/workflow-runs/:id/receipt

作用：返回统一的运行收据，便于 MNote 做历史展示和刷新同步：

  • runId / projectId / workflowId。
  • workerPresetId / workerName。
  • summary / status / completedAt。
  • artifactRefs。
  • targetSnapshot / allowedRoots / capabilities。

这会让 Page AI history 直接依赖 Board receipt，而不是再保留一套 Hermes session 语义。

E. Board 侧能力目录

GET /api/workers/catalog?projectId=<mnote>
GET /api/workflow-presets?projectId=<mnote>
GET /api/projects/:id/capabilities

作用：让 MNote 能展示“Board 当前能做什么”，而不是自己猜 worker。尤其是：

  • 默认 developer 是谁。
  • 哪些 worker 具备 vision/browser。
  • 哪些 workflow 可用于编辑、QA、review、research。

F. Board 侧回写钩子

POST /api/workflow-runs/:id/report
POST /api/workflow-runs/:id/artifacts
POST /api/workflow-runs/:id/feedback

作用：让 MNote 能把 UI 侧额外信息回写给 Board：

  • 浏览器截图。
  • 用户补充说明。
  • 失败后的重新定界信息。
  • 页面刷新后的 targetSnapshot 变化。

这样 Board 的 workflow 才能逐步成为真正的 Page AI 控制面，而不是一次性任务提交器。

5.5 Board → MNote 展示模型

MNote 只归一化 Board 状态，不解析 provider 私有事件：

Board run       -> Page AI run card
Workflow node   -> stage timeline
Task event      -> visible event row
Task summary    -> assistant final message
Artifact refs   -> screenshot/link/file changed chips

MNote 不再关心事件来自 ZCode、Reasonix 还是 Codex。

6. 删除与迁移边界

6.1 默认主链删除

以下能力退出默认主链：

  • Page AI 前端 pageAiAcpRuntime 作为主选择器。
  • Reasonix quick controls 作为默认控件。
  • Hermes profile select 作为默认控件。
  • Chat-only provider conversation 作为默认路径。
  • MNote 内部 provider-specific run resume。
  • provider-specific skill source 切换。

6.2 Legacy 保留原则

旧链路只允许：

  • debug/internal route。
  • 历史 session 读取/导出。
  • 明确 fallback：Board 不可用时提示用户，而不是自动静默切回 Reasonix。

不允许：

  • 新功能继续写进 sidebar-page-ai-runtime.js 的 provider 分支。
  • 新增 Hermes/Reasonix 专属 UI 作为默认交互。
  • 新增 MNote 自己的 provider adapter。

7. 实施计划

Phase A：Board bridge 与新 shell 并行上线（已完成）

  • 新增 page_ai_board.rs，封装 Board status/workers/workflows/runs。
  • 前端默认路径已切为 Board-first run 提交和状态展示；当前以 sidebar-page-ai-runtime.js 内 Board-first 分支承接，后续可继续拆到独立 runtime 文件。
  • Board 侧补齐 envelopes/validate、envelopes/route、runs/:id/events、runs/:id/receipt、projects/:id/capabilities 稳定接口。
  • 当前 Page AI 默认入口切到 Board shell。
  • 旧 provider 入口默认隐藏，仅通过 legacy/debug 边界保留。
  • smoke：从页面提交任务，Board 创建 workflow run，Page AI 能显示 run id、complete、summary。

Phase B：worker / workflow 选择（已完成默认链路）

  • MNote bridge 提供 Board workers/workflows catalog API，默认 UI 先收口为 Board direct workflow。
  • 默认选中 Board direct workflow developer：zcode-deepseek-flash。
  • 后续增强：在工作流页开放更多 built-in workflow 选择。
  • smoke：ZCode developer 执行最小文件编辑任务，MNote 页面通过 watcher 刷新。

Phase C：MNote capability manifest（已完成默认 envelope）

  • 定义并随 mnote.page_ai.board_task.v1 envelope 下发 MNote capabilities。
  • 把当前页/选区/allowed roots/LightRAG/source registry 统一注入 Board input。
  • 默认路径收口为 capability manifest；旧 provider skill 面板隐藏为 legacy/debug。
  • smoke：Board worker 能看到 primary target 与 allowed roots，并只在授权目录内改文件。

Phase D：事件与 artifact 回放（后续增强）

  • Page AI 展示 Board node timeline。
  • 展示 task events：file read/edit、command、command output、QA screenshot。
  • 支持打开 Board project/run/task 链接。
  • smoke：功能开发 workflow 完成后，Page AI 能看到 QA 截图 artifact 和 final summary。

Phase E：旧链路下线（默认主链已下线，代码删除后续）

  • 默认 UI 隐藏 Hermes/Reasonix/Chat-only provider 入口，Board-first shell 成为默认主链。
  • 后续清理：hermes_client.rs 中 Page AI provider-specific run 创建逻辑迁入 legacy/debug 边界。
  • 后续清理：更新旧设计归档默认主链说明为 legacy。
  • smoke：默认 Page AI Board-first 代码路径不再依赖 Reasonix/Hermes provider 即可运行。

8. 验收标准

8.1 功能验收

  • Page AI 默认提交创建 Board workflow run。
  • 默认 worker 来自 Board，而不是 MNote 写死 Reasonix/Hermes。
  • ZCode 作为 Board 默认 developer 时，Page AI 不需要任何 ZCode 专属代码即可使用。
  • Board 不可用时，Page AI 明确显示“Agent Board 不可用”，不伪装为 provider 失败。
  • 文件写入通过真实文件编辑完成，MNote watcher/Page Aggregate 刷新页面。

8.2 维护性验收

  • 新 provider 只需要 Agent Board 适配，不改 MNote Page AI provider 分支。
  • Page AI 前端默认路径不再包含 reasonix/hermes/chat_only 三套选择逻辑。
  • MNote skills/plugins 只表达能力，不表达 provider。
  • Rust route 中 Board bridge 与 Hermes legacy route 分离。

8.3 浏览器 smoke

  • 登录 http://localhost:3000/auth 测试账号。
  • 打开 local-folder Markdown 页面。
  • 打开 Page AI。
  • 选择默认 Board workflow。
  • 提交“总结当前页并提出一个最小改进建议”。
  • 页面显示 Board run id、worker、阶段、最终 summary。
  • 再提交“在当前文件末尾追加一行测试内容”，确认真实 .md 文件变化，页面刷新可见。

9. 风险与处理

风险 处理
Board 服务不可用 Page AI 显示 Board health 错误与启动提示，不自动回退旧 provider
Board workflow 太重 默认使用 minimal workflow，完整 QA workflow 由用户选择
Page AI 历史 session 断裂 旧 session 只读保留，新增 run 以 Board run 为历史主键
Board 改文件后页面不同步 依赖现有 watcher/Page Aggregate；缺口作为 05-editor-mainline bug 处理
MNote capability 被 worker 忽略 Board prompt/template 中明确 envelope schema 与 allowed roots，后续再补 MCP bridge

10. 立即决策

本稿确认后，后续实现不再以“接入 ZCode provider”为任务拆分，而以“Page AI Board-first full rewrite”为主线拆分。第一批代码应直接新增 Board bridge 和新 Page AI shell，而不是继续在旧 sidebar-page-ai-runtime.js 中叠加 provider 分支。

11. 完成记录（2026-06-19）

  • MNote 新增 /api/page-ai/board/* bridge，浏览器不直连 Board 3901。
  • Agent Board 新增 Page AI envelope validate/route/events/receipt/capabilities 接口，并新增 builtin-page-ai-developer-direct workflow。
  • Page AI 默认发送 mnote.page_ai.board_task.v1 envelope，默认 workflow 为 builtin-page-ai-developer-direct，worker 为 ZCode developer。
  • MNote capability 默认随 envelope 下发：mnote.current_page.read、mnote.selection.read、mnote.open_resources.snapshot、mnote.allowed_roots.describe、mnote.lightrag.query、mnote.reference.open、mnote.page_aggregate.snapshot、mnote.local_file.receipt。
  • 浏览器 smoke scripts/task762-page-ai-board-first-smoke.js 已验证：Page AI 可创建 Board run、可见 shell 显示 Agent Board、capability 已加载、ZCode 真实编辑当前 Markdown 文件、磁盘与编辑器可见内容同步。

验证命令：

cd /mnt/Data1T/mnote/rust && cargo check -p mnote-web
cd /mnt/Data1T/ai-agent-board && npm run build:server
cd /mnt/Data1T/mnote && node scripts/task762-page-ai-board-first-smoke.js
Reference in New Issue View Git Blame Copy Permalink