# 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
```