440 lines
17 KiB
Markdown
440 lines
17 KiB
Markdown
# 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**：
|
||
|
||
```text
|
||
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**：
|
||
|
||
```text
|
||
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”，而是：
|
||
|
||
```text
|
||
交给 Agent Board
|
||
```
|
||
|
||
默认配置：
|
||
|
||
```text
|
||
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`：
|
||
|
||
```json
|
||
{
|
||
"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：
|
||
|
||
```text
|
||
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：
|
||
|
||
```text
|
||
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 预检
|
||
|
||
```text
|
||
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 的映射
|
||
|
||
```text
|
||
POST /api/page-ai/envelopes/route
|
||
```
|
||
|
||
作用：Board 根据 envelope 自动选择 workflow / worker / reviewer / QA 路线，返回最终路由结果：
|
||
|
||
- workflowId。
|
||
- workerPresetId。
|
||
- groupId 或 runId。
|
||
- 是否需要用户二次确认。
|
||
- 预估阶段序列。
|
||
|
||
这能让 MNote 不再内置 worker 选择逻辑，只保留“意图 + 上下文”。
|
||
|
||
#### C. Run 级事件流
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
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 侧能力目录
|
||
|
||
```text
|
||
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 侧回写钩子
|
||
|
||
```text
|
||
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 私有事件：
|
||
|
||
```text
|
||
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 并行上线（已完成）
|
||
|
||
- [x] 新增 `page_ai_board.rs`，封装 Board status/workers/workflows/runs。
|
||
- [x] 前端默认路径已切为 Board-first run 提交和状态展示；当前以 `sidebar-page-ai-runtime.js` 内 Board-first 分支承接，后续可继续拆到独立 runtime 文件。
|
||
- [x] Board 侧补齐 `envelopes/validate`、`envelopes/route`、`runs/:id/events`、`runs/:id/receipt`、`projects/:id/capabilities` 稳定接口。
|
||
- [x] 当前 Page AI 默认入口切到 Board shell。
|
||
- [x] 旧 provider 入口默认隐藏，仅通过 legacy/debug 边界保留。
|
||
- [x] smoke：从页面提交任务，Board 创建 workflow run，Page AI 能显示 run id、complete、summary。
|
||
|
||
### Phase B：worker / workflow 选择（已完成默认链路）
|
||
|
||
- [x] MNote bridge 提供 Board workers/workflows catalog API，默认 UI 先收口为 Board direct workflow。
|
||
- [x] 默认选中 Board direct workflow developer：`zcode-deepseek-flash`。
|
||
- [ ] 后续增强：在工作流页开放更多 built-in workflow 选择。
|
||
- [x] smoke：ZCode developer 执行最小文件编辑任务，MNote 页面通过 watcher 刷新。
|
||
|
||
### Phase C：MNote capability manifest（已完成默认 envelope）
|
||
|
||
- [x] 定义并随 `mnote.page_ai.board_task.v1` envelope 下发 MNote capabilities。
|
||
- [x] 把当前页/选区/allowed roots/LightRAG/source registry 统一注入 Board input。
|
||
- [x] 默认路径收口为 capability manifest；旧 provider skill 面板隐藏为 legacy/debug。
|
||
- [x] 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：旧链路下线（默认主链已下线，代码删除后续）
|
||
|
||
- [x] 默认 UI 隐藏 Hermes/Reasonix/Chat-only provider 入口，Board-first shell 成为默认主链。
|
||
- [ ] 后续清理：`hermes_client.rs` 中 Page AI provider-specific run 创建逻辑迁入 legacy/debug 边界。
|
||
- [ ] 后续清理：更新旧设计归档默认主链说明为 legacy。
|
||
- [x] 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 文件、磁盘与编辑器可见内容同步。
|
||
|
||
验证命令：
|
||
|
||
```bash
|
||
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
|
||
```
|