mnote/design/old/07-ai/done/7-1-phase7-document-ai-minimum-loop-checklist-v1.md

# [recycle] 7-1 [done] Phase 7 文档页 AI 最小闭环执行清单 v1

> 更新时间：2026-04-22
>
> 上位依据：
> - `/mnt/Data1T/mnote/design/old/07-ai/process/7-phase7-ai-kernel-projection-plan-v2.md`
> - `/mnt/Data1T/mnote/ARCHITECTURE.md`
> - `/mnt/Data1T/mnote/design/05-editor-mainline/done/5-6-page-aggregate-alignment-checklist-v1.md`
>
> 状态说明：
> - 本稿对应 `Phase 7 v2` 的“文档页 AI 最小闭环”已完成，故迁入 `done/`
> - 本稿完成不等于整个 `Phase 7 v2` 已完成；结构化知识写链仍以后续阶段继续推进
> - 2026-05-05 追加说明：本稿记录的是 `openai-agents-python` sidecar 作为过渡主链的完成状态，不代表当前长期方向；当时长期口径曾由 `/mnt/Data1T/mnote/design/old/07-ai/process/7-phase7-ai-kernel-projection-plan-v4.md` 收口为 `mnote-cli` 是唯一长期 agent 执行面
> - 2026-05-13 追加说明：`mnote-cli` 唯一长期 agent 执行面口径已被 `/mnt/Data1T/mnote/design/07-ai/done/7-3-page-ai-hermes-panel-and-mnote-plugin-v1.md` 覆盖；新的长期方向是页面 AI 面板仅作为 Hermes 页面内客户端，Hermes 持有 AI 会话真相，mnote 通过 Hermes skill/plugin 暴露业务工具

---

## 1. 本轮范围

本轮只执行 `Phase 7 v2` 的第一轮最小闭环：

- 文档页 AI 读取当前页 page aggregate 上下文
- 编排层切入 `openai-agents-python`
- 正文插入 / 改写继续沿 `page.body.save` 回写
- 标题改名继续沿 `page.head.updateTitle` 回写
- 前端默认在线主路径先走新 sidecar，失败时 fallback 到 Hermes
- 页面 AI 配置开始收口到 `model_key / profile / tool registry`

本轮明确不做：

- `summary node`
- `ai_note node`
- `reference edge`
- `PDF / Book -> kernel index`
- mindmap / OnlyOffice AI 主链

---

## 2. 当前基线

- [x] 文档页主编辑区已经是页面内 `leptos-tiptap` island
- [x] 文档页 AI 已开始消费 page aggregate snapshot
- [x] 页面写命令面已开始收口到 `page.head.updateTitle` / `page.body.save`
- [x] 前端 `/api/ai-agent/run` 已承载 `online -> sidecar / fallback -> Hermes` 分流
- [x] `openai-agents-python` sidecar 已接入
- [x] 前端在线主路径已切到新 sidecar

---

## 3. 执行项

### A. 语义面冻结

- [x] 第一批正式写动作只覆盖：改标题 / 插入正文 / 改写正文
- [x] 正式命令语义固定为：`page.head.updateTitle` / `page.body.save`
- [x] 过渡工具面固定为：`doc_get` / `doc_find` / `doc_insert_blocks` / `doc_replace_range` / `slash_run`
- [x] 不新增第三套 AI 专用产品命名面

### B. 上下文装配冻结

- [x] sidecar 请求体固定包含：`documentId` / `documentBlocks` / `pageOptions` / `subtree` / `outline` / `evidence`
- [x] 不再新增新的 AI 私有页面 getter
- [x] 会话上下文裁剪规则先冻结到文档页最小字段集

### C. `openai-agents-python` sidecar

- [x] 在 `wolai-backend` 新增文档页 AI sidecar route
- [x] 接入 `openai-agents-python`
- [x] 接入 OpenAI `Responses API`
- [x] 最小 tools 只注册：`doc_get` / `doc_find` / `doc_insert_blocks` / `doc_replace_range` / `slash_run`
- [x] tool 执行统一桥接到 `mnote-web /api/hermes/bridge`
- [x] 建立最小 session / tracing
- [x] 建立最小 guardrail / fallback 边界

### D. 前端主路径接线

- [x] `/api/ai-agent/run` 新增 sidecar adapter
- [x] `online` provider 默认先走 `openai-agents-python`
- [x] 新 sidecar 失败时自动 fallback Hermes
- [x] 继续输出兼容当前 panel 的 SSE 事件：`assistant_message` / `tool_call` / `tool_result` / `completion` / `error`
- [x] 文档页 AI 回写链继续复用 `page.head.updateTitle` / `page.body.save`

### E. 配置真源与可见性

- [x] 页面 AI 模型配置真源切到 `model_key`
- [x] `model_key -> resolved_combo -> resolved_runtime_model` 分层可见
- [x] 页面 AI 不再把 combo 名或 provider model 作为产品主键
- [x] `profile` 前端可设，但由后端 registry 持有真源
- [x] 页面 AI 设置页能显示当前 `profile`
- [x] 后端提供当前 scope 的真实 tool registry
- [x] 页面 AI 设置页能显示当前 scope 的已注册工具

### F. 验证

- [x] route 测试覆盖 sidecar 主路径与 Hermes fallback
- [x] 后端最小 smoke / 单测覆盖文档页 run route
- [x] 验证在线主路径下标题改名与正文改写都能完成结构化回写
  说明：`task111-phase7-document-ai-online-smoke.js` 已验证 `doc_insert_blocks -> slash_run -> doc_replace_range` 在线主路径闭环

---

## 4. 本轮完成判定

当以下条件同时成立，才可以宣称本轮完成：

- [x] 文档页 AI 在线主路径不再默认依赖 Hermes 主编排
- [x] 文档页 AI 仍只围绕当前页主编辑区最小闭环工作
- [x] 标题改名与正文改写仍沿正式页面命令语义回写
- [x] Hermes 已退回 fallback / 对照链
- [x] 页面 AI 的模型 / 设定 / 工具状态已进入正式可见配置面