mnote/design/old/07-ai/process/7-63-recycle-page-ai-board-first-productization-v1.md

7-63 [recycle] Page AI Board-first product shell v1

创建时间：2026-06-20

当前状态：RECYCLE

Owner：07-ai / Page AI product shell / Agent Board MNote runtime / session history

上位依据：

• design/07-ai/done/7-62-page-ai-board-first-full-rewrite-v1.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-40-page-ai-context-envelope-and-run-receipt-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. 当前结论

7-62 已经证明 Board-first 主链能跑：MNote Page AI 可以通过 Agent Board 创建 run，可以把 MNote capability/envelope 下发给 worker，mnote-page-ai-zcode 能回复，也能真实编辑当前 Markdown 文件并触发编辑器刷新。

但这还不是合格的页面 AI。当前问题不是“再给用户更多 Board 选择”，而是 MNote 页面 AI 需要自己的产品壳：

MNote Page AI Product Shell
  = 聊天体验 + 当前页上下文 + MNote 白名单 worker/workflow + worker 内模型选择 + session/history + run detail

Agent Board MNote Runtime
  = MNote 专用 worker + MNote 专用 workflow + provider/model 执行 + receipt/event 持久化

Page AI 不是 Agent Board 控制台的缩小版。默认 UI 不应该暴露 Board 全量 worker、全量 workflow、provider adapter 或通用任务报告。用户只需要面对少量 MNote 语义清楚的选择。

2. 要解决的四个问题

2.1 Worker 怎么选

Page AI 只能选择 MNote Page AI 白名单 worker。当前默认只有：

workerPresetId = mnote-page-ai-zcode
name = MNote 页面 AI · ZCode
surface = mnote-page-ai
capabilities = text, repo-edit, terminal, mnote-capability-envelope, local-markdown-edit

不暴露 Board 全量 worker catalog。Reasonix、Codex、ZCode、QA worker 都是 Board 内部 worker 类型，不直接成为 MNote 页面用户的选择项。后续如果需要新增 worker，必须在代码中显式登记为 surface=mnote-page-ai，同时补齐：

• 用户可见名称。
• 适合场景。
• 允许模型档位。
• 权限能力。
• smoke 验收。

当白名单只有一个 worker 时，UI 不显示“可切换 worker”的伪入口，只显示当前 worker 和模型档位。

2.2 模型怎么改

模型选择挂在特定 MNote worker 下，不做 provider picker：

workerPresetId = mnote-page-ai-zcode
modelOverride = zcode-default | zcode-fast | zcode-strong

UI 展示为 worker chip 旁的 model chip，例如：

MNote 页面 AI · ZCode / 默认

用户可以切换模型档位，但不能直接选择 provider。MNote 不重新维护 Hermes/Reasonix/Codex/ZCode provider adapter；provider 和 credential 仍归 Board。

2.3 Workflow 怎么选

Page AI 只能选择 MNote Page AI 白名单 workflow。当前默认只有：

workflowId = builtin-mnote-page-ai-chat
name = MNote 页面 AI
surface = mnote-page-ai

该 workflow 覆盖默认聊天、当前页轻编辑、当前页总结、当前页问答。通用 Board workflow 不出现在 Page AI picker 中。

后续确实需要时，再通过代码加入特定 MNote workflow：

Workflow	加入条件	默认 UI
builtin-mnote-page-ai-chat	已有默认主链	默认启用
builtin-mnote-page-ai-edit	需要更明确的编辑阶段和 diff/receipt	加入白名单后显示
builtin-mnote-page-ai-review	需要当前页审阅、总结、检查	加入白名单后显示

复杂开发、hotfix、QA/browser workflow 不作为默认页面 AI 能力。只有当它们被改造成 MNote 专用 workflow，并明确加入白名单后，才允许显示。

2.4 Session 怎么选、怎么看历史

Page AI session 迁移为 Board-first session。每条 assistant 消息必须知道它来自哪个 Board run，但主聊天只显示用户需要的回答。

{
  "schema": "mnote.page_ai.session.v2",
  "sessionId": "...",
  "workspaceId": "...",
  "documentId": "...",
  "rootUri": "file:///...",
  "messages": [
    { "role": "user", "content": "hi,收到请回复收到。" },
    {
      "role": "assistant",
      "content": "收到。",
      "boardRunId": "...",
      "workflowId": "builtin-mnote-page-ai-chat",
      "workerPresetId": "mnote-page-ai-zcode",
      "modelOverride": "zcode-default",
      "receiptId": "..."
    }
  ]
}

历史 UI 分三层：

1. 会话列表：标题、最后回答摘要、状态、时间。
2. 会话详情：聊天消息、当前页上下文、关联 run。
3. Run detail：worker、model、workflow、timeline、changed files、receipt、失败原因。

短期可继续 localStorage/sessionStorage；产品化阶段必须落到 SQLite control-plane，避免刷新、跨标签和权限变化导致历史丢失。

3. 源头输出合同

MNote 专用 worker/workflow 必须从源头产出页面 AI 风格回答，而不是先产出 Board 任务报告再让 MNote 截断。

3.1 用户回答

简单 ask 的 worker 最终回答应直接是：

收到。

当前页编辑任务的最终回答应类似：

已把当前页面中的“A”替换为“B”。

不允许把以下内容作为主回答：

• Completed
• Comments
• Remaining
• Agent Board run 已创建
• 命令日志
• 工具调用过程
• provider 内部推理或计划

3.2 运行记录

Board runtime/workflow 负责旁路写入结构化记录：

{
  "schema": "agent_board.workflow_run_receipt.v2",
  "runId": "...",
  "surface": "mnote-page-ai",
  "workflowId": "builtin-mnote-page-ai-chat",
  "workerPresetId": "mnote-page-ai-zcode",
  "modelOverride": "zcode-default",
  "finalAnswer": "收到。",
  "changedFiles": [],
  "verification": [],
  "remaining": [],
  "eventsUrl": "/api/workflow-runs/:id/events",
  "createdAt": 0,
  "completedAt": 0
}

## FINAL_ANSWER 只作为旧 run 或非专用 workflow 的兼容保护，不是长期主路径。长期主路径是 worker 主回答自然、Board receipt 结构化。

4. Board 和 MNote 的双向接口

4.1 Board route result

Board 提供 MNote surface 的推荐结果：

{
  "schema": "agent_board.page_ai_route.v2",
  "surface": "mnote-page-ai",
  "workflowId": "builtin-mnote-page-ai-chat",
  "workflowName": "MNote 页面 AI",
  "workerPresetId": "mnote-page-ai-zcode",
  "workerName": "MNote 页面 AI · ZCode",
  "modelOverride": "zcode-default",
  "allowedWorkerPresetIds": ["mnote-page-ai-zcode"],
  "allowedWorkflowIds": ["builtin-mnote-page-ai-chat"],
  "modelOptions": [
    { "id": "zcode-default", "label": "默认", "default": true },
    { "id": "zcode-fast", "label": "快速" },
    { "id": "zcode-strong", "label": "强力" }
  ],
  "requiresConfirmation": false,
  "requires": {
    "filesystem": true,
    "write": false,
    "browser": false,
    "vision": false
  },
  "stages": ["answer"]
}

MNote 消费 Board 推荐，但仍按本地白名单过滤。这样 Board 可以逐步提供更多能力，MNote 不会把控制台复杂度泄露给页面用户。

4.2 MNote run request

MNote 创建 run 时必须显式传入：

{
  "surface": "mnote-page-ai",
  "workflowId": "builtin-mnote-page-ai-chat",
  "workerPresetId": "mnote-page-ai-zcode",
  "modelOverride": "zcode-default",
  "capabilityEnvelope": {
    "primaryTarget": { "absolutePath": "/.../current.md" },
    "allowedRoots": ["/..."]
  },
  "sessionId": "..."
}

Board 必须拒绝不匹配 surface=mnote-page-ai 的 worker/workflow 组合，避免前端绕过白名单。

5. 标准页面 AI 最小体验

按 VSCode/Cursor 类页面 AI 衡量，第一阶段只补核心能力，不把 QA/browser/artifact 做成默认入口。

5.1 Chat

• 主聊天只显示用户消息和 assistant 自然回答。
• pending skeleton 或流式 token。
• stop 当前 run。
• retry 同一消息。
• copy 回答。
• Enter 发送，Shift+Enter 换行。

5.2 Context

• composer 上方显示上下文 pills：当前页、选区、打开资源、文件夹、知识库。
• 当前 write target 单独显示。
• 无写权限时，编辑类 prompt 发送前提示授权缺失。
• allowedRoots 与 primaryTarget run 前可预检。

5.3 Worker / Model / Workflow

• 只展示 MNote Page AI 白名单 worker。
• 当只有一个 worker 时，不显示伪切换入口。
• 模型选择挂在当前 worker 下。
• 只展示 MNote Page AI 白名单 workflow。
• 切换 worker/model/workflow 后写入偏好和 session metadata。

5.4 Timeline / Diff / Receipt

• run detail 展示 Board event timeline。
• changed files 从 receipt 读取。
• Markdown 编辑后展示最小 diff 摘要。
• 命令输出默认折叠，失败时展开。
• dirty/stale guard：编辑器未保存或文件外部变化时阻止自动写入。

5.5 Session / History

• 会话列表可见、可搜索、可恢复。
• 每条 assistant 消息关联 run id、worker、model、workflow、receipt。
• 历史详情可查看 final answer、timeline、changed files。
• 支持删除本地 history，不删除 Board 原始 run。

6. 非默认扩展

QA、浏览器截图和 artifact 展示不属于页面 AI 第一阶段核心体验。它们只在用户显式选择已加入白名单的 QA/browser workflow，或 Board route 判断确实需要浏览器验证并得到 UI 提示时出现。

• 默认 Page AI 不显示 QA/browser 入口。
• artifact screenshot 只从 run detail 打开，不进入主聊天。
• QA run 失败时主聊天只显示一句可理解失败原因，详情里展示日志。

7. 实施计划

Phase A：源头回答收敛

• Board 默认 worker 已改为 mnote-page-ai-zcode。
• Board 默认 workflow 已改为 builtin-mnote-page-ai-chat。
• MNote UI 已能只展示 final answer，不展示 Board run 创建日志。
• smoke：hi,收到请回复收到。 最终 assistant 气泡只显示 收到。。
• mnote-page-ai-zcode / builtin-mnote-page-ai-chat 源头默认输出自然语言 final answer。
• 结构化记录写入 receipt.finalAnswer / changedFiles / verification / remaining。

Phase B：白名单选择壳

• MNote 定义 Page AI worker 白名单。
• MNote 定义 Page AI workflow 白名单。
• Worker picker 只展示白名单 worker。
• Workflow picker 只展示白名单 workflow。
• 当白名单只有一个 worker/workflow 时，不显示伪切换。

Phase C：worker 内模型选择

• Board route 返回 modelOptions。
• MNote 显示当前 model chip。
• Model picker 只展示当前 worker 允许的模型档位。
• run payload 包含 modelOverride。
• session metadata 记录 modelOverride。

Phase D：Board-first session/history

• 定义并落地 mnote.page_ai.session.v2。
• assistant message 记录 boardRunId/workflowId/workerPresetId/modelOverride/receiptId。
• 历史列表展示 Board-first session。
• Run detail 可从历史打开。
• 刷新页面后仍能恢复会话和 run 详情。

Phase E：timeline / changed files / diff

• 从 Board events 生成 timeline。
• 从 receipt 提取 changed files。
• Markdown 文件编辑后展示最小 diff / changed files 摘要。
• 命令输出和日志折叠。
• smoke：编辑当前页面后，主聊天是自然回复，详情里能看到 changed file 和验证命令。

Phase F：标准页面 AI 体验补齐

• 上下文 pills 完整可交互。
• pending skeleton / streaming 状态。
• stop / retry / copy。
• dirty/stale guard。

8. 验收标准

8.1 简单问答

• 输入：hi,收到请回复收到。
• 主聊天最新 assistant 气泡：收到。
• worker 源头最终回答就是自然语言，不依赖 MNote 截断通用任务报告。
• run detail 可查看 worker、model、workflow、run id、receipt。

8.2 Worker 与模型

• UI 只展示 MNote Page AI 白名单 worker。
• 白名单只有一个 worker 时，不显示 worker 切换列表。
• UI 能切换当前 worker 允许的模型档位。
• 发送后 payload 包含 workerPresetId 和 modelOverride。
• 不在白名单内的 worker 不显示。

8.3 Workflow

• UI 只展示 MNote Page AI 白名单 workflow。
• 默认 workflow 为 builtin-mnote-page-ai-chat。
• 不在白名单内的 Board workflow 不显示。
• 发送后 payload 包含 workflowId。

8.4 Session/history

• 新建会话、恢复会话、搜索历史可用。
• 历史项显示 final answer preview、状态、时间。
• 点击历史项恢复聊天消息。
• 点击 run detail 可查看 Board receipt。

8.5 页面编辑

• 输入“把当前页面中的 A 替换为 B”。
• worker 只修改 primaryTarget.absolutePath。
• 磁盘文件变化。
• 编辑器 watcher 刷新可见。
• 主聊天显示自然结果。
• 详情显示 changed files / verification。

9. 非目标

• 不重新实现 provider adapter；provider/model 执行仍归 Board。
• 不暴露 Board 全量 worker/workflow catalog。
• 不把复杂开发、hotfix、QA/browser workflow 默认化。
• 不删除 Hermes/Reasonix legacy 代码，只隐藏默认入口并防止污染默认主链。
• 不实现完整撤销系统，只保留 diff/receipt 所需数据结构。

10. 风险与处理

风险	处理
MNote 专用 worker 仍输出任务报告	从 worker/workflow prompt 和 receipt API 源头修正，MNote 截取只做兼容保护
Board 选择太多	MNote 只展示白名单 worker/workflow，新增项必须代码登记
模型选择重新变成 provider picker	模型挂在特定 worker 下，只展示该 worker 允许的档位
Workflow 太重影响简单问答	默认只启用 builtin-mnote-page-ai-chat，复杂 workflow 需 MNote 白名单
历史数据分裂	新 session v2 记录 Board run，旧 session 只读兼容
文件编辑误伤	primaryTarget + allowedRoots + dirty/stale guard + receipt

11. 最小落地顺序

1. 先把 MNote 专用 worker/workflow 的源头输出改成自然回答。
2. 再把 Page AI UI 收敛为白名单 worker/workflow，不显示 Board 全量选择。
3. 然后补 worker 内模型选择。
4. 再补 Board-first session/history。
5. 最后补 timeline、diff、dirty/stale guard 和可选扩展。