From c8472bb8983bcbfd7be6d3b7c04c051822f50a75 Mon Sep 17 00:00:00 2001 From: Agent Board Date: Sat, 4 Jul 2026 21:47:42 +0800 Subject: [PATCH] feat: add pi lab ai management integration --- .gitignore | 11 +- AGENTS.md | 4 + .../7-69-page-ai-pi-first-lab-checklist-v1.md | 90 + ...69-page-ai-pi-first-lab-spike-record-v1.md | 94 + ...lab-native-openhub-like-ui-checklist-v1.md | 51 + ...pi-lab-native-openhub-like-ui-record-v1.md | 93 + ...age-ai-pi-lab-native-openhub-like-ui-v2.md | 499 +++ ...ane-and-pi-lab-integration-checklist-v1.md | 141 + .../process/7-69-page-ai-pi-first-lab-v1.md | 39 +- ...control-plane-and-pi-lab-integration-v1.md | 562 ++++ rust/Cargo.lock | 606 ++-- .../009-ai-tool-events-file-patches.sql | 56 + .../src/bin/control-plane-admin.rs | 56 + rust/crates/control-plane/src/migrations.rs | 8 + rust/crates/control-plane/src/model.rs | 82 + rust/crates/control-plane/src/sqlite.rs | 408 ++- rust/crates/control-plane/src/store.rs | 58 +- rust/crates/control-plane/src/turso.rs | 401 ++- .../crates/control-plane/tests/turso_store.rs | 9 +- .../browser/sidebar-page-ai-pi-lab-runtime.js | 1528 +++++++++ .../browser/sidebar-workspace-runtime.js | 15 + rust/crates/mnote-web/src/app.rs | 3 + .../mnote-web/src/routes/ai_settings.rs | 2298 +++++++++++++ rust/crates/mnote-web/src/routes/bridge.rs | 1 + rust/crates/mnote-web/src/routes/compat.rs | 4 + rust/crates/mnote-web/src/routes/dev_seed.rs | 11 +- rust/crates/mnote-web/src/routes/documents.rs | 1 + rust/crates/mnote-web/src/routes/editor.rs | 1 + rust/crates/mnote-web/src/routes/evidence.rs | 1 + rust/crates/mnote-web/src/routes/gateway.rs | 115 + rust/crates/mnote-web/src/routes/hermes.rs | 1 + .../mnote-web/src/routes/hermes_client.rs | 17 +- .../mnote-web/src/routes/hermes_tools.rs | 2 + rust/crates/mnote-web/src/routes/kernel.rs | 1 + .../src/routes/local_folder_events.rs | 1 + .../src/routes/local_folder_source.rs | 1 + .../src/routes/local_search_index.rs | 5 +- .../mnote-web/src/routes/mindmap_api.rs | 1 + .../mnote-web/src/routes/mindmap_shell.rs | 2 + rust/crates/mnote-web/src/routes/mod.rs | 58 +- .../mnote-web/src/routes/navigation_recent.rs | 1 + .../crates/mnote-web/src/routes/onlyoffice.rs | 1 + .../crates/mnote-web/src/routes/page_ai_pi.rs | 2869 +++++++++++++++++ .../mnote-web/src/routes/page_ai_workflow.rs | 1 + .../mnote-web/src/routes/resource_trash.rs | 1 + rust/crates/mnote-web/src/routes/search.rs | 3 + rust/crates/mnote-web/src/routes/session.rs | 4 + rust/crates/mnote-web/src/routes/sse.rs | 1 + rust/crates/mnote-web/src/routes/tree.rs | 3 + rust/crates/mnote-web/src/routes/web_shell.rs | 46 +- .../mnote-web/src/ssr/pages/ai_admin.rs | 2738 ++++++++++++++++ rust/crates/mnote-web/src/ssr/pages/mod.rs | 1 + scripts/desktop-hot.js | 112 + scripts/desktop-hot.test.js | 12 + scripts/task-ai-management-browser-smoke.js | 281 ++ ...i-management-control-plane-static-smoke.js | 517 +++ scripts/task-pi-lab-api-endpoint-smoke.js | 167 + scripts/task-pi-lab-browser-smoke.js | 261 ++ scripts/task-pi-lab-mock-api-smoke.js | 178 + scripts/task-pi-lab-rpc-api-smoke.js | 485 +++ scripts/task-pi-lab-rpc-browser-smoke.js | 307 ++ scripts/task-pi-lab-static-smoke.js | 196 ++ 62 files changed, 15077 insertions(+), 443 deletions(-) create mode 100644 design/07-ai/done/7-69-page-ai-pi-first-lab-checklist-v1.md create mode 100644 design/07-ai/done/7-69-page-ai-pi-first-lab-spike-record-v1.md create mode 100644 design/07-ai/done/7-70-page-ai-pi-lab-native-openhub-like-ui-checklist-v1.md create mode 100644 design/07-ai/done/7-70-page-ai-pi-lab-native-openhub-like-ui-record-v1.md create mode 100644 design/07-ai/done/7-70-page-ai-pi-lab-native-openhub-like-ui-v2.md create mode 100644 design/07-ai/done/7-71-unified-ai-management-control-plane-and-pi-lab-integration-checklist-v1.md create mode 100644 design/07-ai/process/7-71-unified-ai-management-control-plane-and-pi-lab-integration-v1.md create mode 100644 rust/crates/control-plane/migrations/009-ai-tool-events-file-patches.sql create mode 100644 rust/crates/mnote-web/browser/sidebar-page-ai-pi-lab-runtime.js create mode 100644 rust/crates/mnote-web/src/routes/ai_settings.rs create mode 100644 rust/crates/mnote-web/src/routes/page_ai_pi.rs create mode 100644 rust/crates/mnote-web/src/ssr/pages/ai_admin.rs create mode 100644 scripts/task-ai-management-browser-smoke.js create mode 100644 scripts/task-ai-management-control-plane-static-smoke.js create mode 100644 scripts/task-pi-lab-api-endpoint-smoke.js create mode 100644 scripts/task-pi-lab-browser-smoke.js create mode 100644 scripts/task-pi-lab-mock-api-smoke.js create mode 100644 scripts/task-pi-lab-rpc-api-smoke.js create mode 100644 scripts/task-pi-lab-rpc-browser-smoke.js create mode 100644 scripts/task-pi-lab-static-smoke.js diff --git a/.gitignore b/.gitignore index 890bdd12..06a60002 100644 --- a/.gitignore +++ b/.gitignore @@ -7,11 +7,12 @@ dist/ build/ **/build/ .turbo/ -pnpm-debug.log* -npm-debug.log* -yarn-debug.log* -yarn-error.log* -*.log +pnpm-debug.log* +npm-debug.log* +yarn-debug.log* +yarn-error.log* +*.tgz +*.log .DS_Store .env .env.* diff --git a/AGENTS.md b/AGENTS.md index 6552a174..1e324b12 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -129,6 +129,10 @@ - 若当前问题只是 UI 表现异常，先确认是否是实验性 tree shell、compat 路径、轮询或 fallback 混入首屏主链，而不是直接怀疑 Convex 本身。 - 若发现现有轮询或定时刷新链路，不要直接在其上继续叠加补丁；先确认是否能改成事件驱动、watcher/realtime 推送或命令结果定点刷新，再决定是否保留临时 fallback。 - 子 agent 只能作为受控叶子 worker：任务书必须限定读写范围、验证命令、交付文件和禁止项；不得自行再启动 runner、subagent、额外 worktree 或修改任务书。Codex 主控必须复核 diff、handoff/result、验证证据和 git 状态后才能采纳；Reasonix/Hermes 只属于历史 provider 边界。 +- 主控必须维护当前 subagent 的任务书、写入范围和采纳状态。任何 `worker` 启动后到完成/取消前，都视为可能写入；主控不得同时手工修改同一文件范围，也不得再派第二个 worker 修改同一范围。 +- 主控不得因为自己已经手工完成同一范围就提前关闭仍在运行的实现型 subagent；若该 worker 的写入范围已失效，必须先 interrupt/send_input 明确取消并说明其结果不再采纳，随后等待 shutdown/完成通知。只有已完成、已取消且确认不会再写入、或用户明确要求停止时，才 close_agent。 +- 使用 subagent 的目标是缩短关键路径。委派前必须确认子任务不会阻塞主控下一步、不会与主控或其它 worker 写同一文件、且主控有明确的结果采纳点；否则主控直接做。若 subagent 结果晚到，主控必须标记“未采纳”或复核后合并，不能让后台结果与主线程补丁并存成冲突。 +- 进入最终测试或最终回复前，主控必须确认本轮仍在运行的实现型 subagent 已完成、已明确取消并停止，或其输出已被标记为不采纳；不得在后台 worker 仍可能写入时声称已完成。 ## CodeGraph 使用 diff --git a/design/07-ai/done/7-69-page-ai-pi-first-lab-checklist-v1.md b/design/07-ai/done/7-69-page-ai-pi-first-lab-checklist-v1.md new file mode 100644 index 00000000..62aae554 --- /dev/null +++ b/design/07-ai/done/7-69-page-ai-pi-first-lab-checklist-v1.md @@ -0,0 +1,90 @@ +# 7-69 Page AI Pi-first Lab Spike Checklist v1 + +状态：done（最小可验证 spike） +Owner：07-ai / mnote-web / control-plane +日期：2026-07-04 + +## 1. 结论 + +7-69 的最小可验证 spike 已完成：OpenHub 继续作为默认 Page AI 主线，Pi Lab 仅在 `MNOTE_PAGE_AI_PI_LAB=1` 下启用，运行时默认禁用 Pi 原始 `bash/read/write/edit`，文件读写只走 MNote-owned tool facade 与 allowed roots。 + +Pi 可以进入下一阶段受控验证，但不能进入生产默认路径。下一阶段的门槛是 Turso/libSQL 正式 receipt 表、登录态 watcher -> tiptap 端到端验证、selection snapshot 注入和 UI 产品化。 + +## 2. Phase Checklist + +### Phase A：源码与包可运行性 + +- [x] 重新拉取并核验当前 Pi 源码：`tmp/pi-research-20260703/pi-mono`，commit `23d14626 fix(ai): rotate stale Codex websocket sessions`。 +- [x] 核验当前 npm 包：`@earendil-works/pi-coding-agent@0.80.3`，并通过 `MNOTE_PAGE_AI_PI_BIN` wrapper 跑通真实 RPC。 +- [x] 跑通 `pi --mode rpc` 最小托管路径。 +- [x] 记录 RPC event schema 到 MNote SSE `pi_rpc_event` 映射。 +- [x] 验证 `abort`：MNote 可向 Pi RPC 发送 abort 并清理子进程。 +- [ ] `steer` / `follow_up` 行为未纳入本轮 spike，留到下一阶段真实 agent turn 验收。 + +### Phase B：MNote scoped Pi runtime + +- [x] 新增内部 runtime manager，不替换 OpenHub 默认入口。 +- [x] `sessionDir` 派生到 MNote 管控目录：`/.mnote/ai/pi-sessions//`。 +- [x] 禁止全局 `~/.pi/agent/sessions` 作为默认 MNote session 落点。 +- [x] 只开放 MNote-owned tools，默认不开放 Pi builtin `bash/read/write/edit`。 +- [x] 路径越界读写被拒绝，并写入 provider-neutral receipt。 + +### Phase C：LightRAG tool + +- [x] 实现 `mnote.knowledge_rag.query` facade。 +- [x] 通过现有 `knowledge_rag::query_rag` 调用 LightRAG provider facade，不引入第二套 RAG。 +- [x] tool envelope 保留 citation/open-reference 所需字段。 +- [x] UI 支持 citation 展示。 +- [x] 实现 `mnote.reference.open` facade，支持 citation 回跳入口。 + +### Phase D：文件 patch 闭环 + +- [x] 当前页面可通过 `rootUri + pagePath` 解析到真实 `.md`。 +- [x] `mnote.local_file.patch` 支持 content 或 text operations patch 当前文件。 +- [x] patch 写入前后记录 file version 与 diff summary。 +- [x] patch 响应声明 watcher/document-session refresh，并显式 `polling=false`。 +- [ ] 登录态浏览器中验证 watcher 实际刷新 tiptap 当前页仍未完成，是下一阶段阻塞项。 +- [ ] changed file chip 打开对应资源未纳入本轮 spike，是下一阶段 UI 验收项。 + +### Phase E：UI 对照 + +- [x] 新增 MNote-native Pi Lab internal UI，支持 start/send/events/abort，并集成到当前 MNote Page AI 抽屉。 +- [x] Pi RPC stream 的 `thinking_*` 事件不进入可见 assistant bubble；截图验证 Omniroute/freefirst 最终可见回复为 `OK`。 +- [x] UI 支持 SSE stream、tool card、citation、diff summary、receipt 诊断。 +- [x] 重新拉取并评估 `@earendil-works/pi-web-ui@0.75.3`；确认其 UI 成熟，但默认 browser Agent/IndexedDB/API key/tools/artifacts 边界不适合直接承接 MNote 托管 Pi RPC/SSE。 +- [x] 采用参考官方 `ChatPanel/AgentInterface` 形态的 MNote-native adapter，并保留后续 remote-session adapter 接官方组件的迁移条件。 +- [ ] 与 OpenHub 当前面板并排截图对照未纳入本轮 spike。 +- [ ] 移动端 / 窄 sidebar 布局未纳入本轮 spike。 +- [ ] retry / session resume 仍是下一阶段 UI 产品化项。 + +## 3. 验收结果 + +- [x] `pi --mode rpc` 能由 MNote 托管启动，并返回 `runtimePid`。 +- [x] 当前页读取、LightRAG facade、文件 patch、receipt adapter、SSE UI 已形成最小闭环。 +- [x] 所有文件读写受 allowed roots 控制。 +- [x] 所有 tool call 均写 provider-neutral JSONL receipt。 +- [x] Pi 原始 `bash/read/write/edit` 默认不可用。 +- [x] citation/open-reference facade 已接入 MNote knowledge_rag 路径。 +- [x] Pi Lab 与 OpenHub 并存，OpenHub 仍为默认 Page AI。 +- [ ] Turso/libSQL 正式 receipt 表未完成。 +- [ ] watcher -> tiptap 真实端到端刷新未完成。 +- [ ] UI 尚未达到可替代 OpenHub 的生产级体验。 + +## 4. 验证命令 + +- `node scripts/task-pi-lab-static-smoke.js`：通过，78 checks。 +- `node scripts/task-pi-lab-api-endpoint-smoke.js`：通过，10/10。 +- `node scripts/task-pi-lab-mock-api-smoke.js`：通过。 +- `node scripts/task-pi-lab-browser-smoke.js`：通过。 +- `node scripts/task-pi-lab-rpc-api-smoke.js`：新增固化 RPC smoke；需以 `MNOTE_PAGE_AI_PI_LAB_RUNTIME=rpc` 和 `MNOTE_PAGE_AI_PI_BIN` 启动服务后运行。 +- `cd rust && cargo check -p mnote-web`：通过。 + +## 5. 下一阶段条件 + +进入下一阶段前必须补齐： + +- Turso/libSQL control-plane 表：`ai_provider_sessions`、`ai_tool_events`、`ai_file_patches`。 +- 登录态浏览器 smoke：Pi patch 当前 `.md` 后，watcher 驱动 tiptap 当前页刷新，不允许高频轮询。 +- sidebar host 注入真实 selection snapshot。 +- Pi RPC send 的真实 agent turn 自动化验证，固定兼容版本范围或安装方式。 +- UI 与 OpenHub baseline 的截图/交互对照。 diff --git a/design/07-ai/done/7-69-page-ai-pi-first-lab-spike-record-v1.md b/design/07-ai/done/7-69-page-ai-pi-first-lab-spike-record-v1.md new file mode 100644 index 00000000..91b939fd --- /dev/null +++ b/design/07-ai/done/7-69-page-ai-pi-first-lab-spike-record-v1.md @@ -0,0 +1,94 @@ +# 7-69 Page AI Pi-first Lab Spike 验收记录 v1 + +状态：done（最小可验证 spike） +Owner：07-ai / mnote-web / control-plane +日期：2026-07-03 + +## 1. 本轮结论 + +7-69 已完成 MNote 侧最小可验证 Pi-first Page AI Lab spike：OpenHub 仍是默认 Page AI 主线，Pi Lab 仅在 `MNOTE_PAGE_AI_PI_LAB=1` 下作为 dev-only/internal 入口启用。 + +当前结论不是“替换 OpenHub”，而是：Pi 值得进入下一阶段受控验证；扩大前必须补真实 Pi CLI/RPC、Turso/libSQL receipt 表、auth 下浏览器 smoke 和 watcher 端到端证据。 + +## 2. 已实现内容 + +- 新增 Pi Lab 后端路由：`/api/page-ai/pi/status`、`bootstrap`、`start`、`send`、`abort`、`events`、`tool-call`、`/page-ai/pi`。 +- 新增 MNote 托管 runtime：`pi --mode rpc` subprocess 或 `MNOTE_PAGE_AI_PI_LAB_RUNTIME=mock`，sessionDir 派生到 MNote 管控目录。 +- 默认禁用 Pi builtin tools：启动参数包含 `--no-builtin-tools`，状态响应显式标注 `bash/read/write/edit` 不开放。 +- 实现 MNote-owned tool facade：`mnote.current_page.read`、`mnote.selection.read`、`mnote.allowed_roots.describe`、`mnote.local_file.read`、`mnote.local_file.patch`、`mnote.knowledge_rag.query`、`mnote.reference.open`、`mnote.tool_receipt.write`。 +- 文件读写受 allowed roots 限制，越界读写返回 deny reason 且写 receipt。 +- LightRAG 保持唯一默认知识 provider；Pi 只通过 `knowledge_rag` facade 查询和 open-reference。 +- receipt 先落 `provider_neutral_jsonl_adapter_v1`，字段含 session binding、tool event、deny reason、diff summary、file version、allowed roots snapshot，并写明迁移到 Turso/libSQL `ai_provider_sessions` / `ai_tool_events` / `ai_file_patches` 的条件。 +- 文件 patch 响应声明 `mnote local-folder watcher / document-session external refresh`，并显式 `polling=false`，不新增高频轮询。 +- 新增 Pi Lab runtime UI：状态机、SSE/EventSource、stream、tool card、citation、diff、abort、receipt 诊断。 +- Pi Lab 已从简陋独立 debug 页改为当前 MNote Page AI 抽屉内的 dev-only provider 面板，并保留悬浮 `π` 入口；切回 OpenHub 时复用原抽屉与 iframe，OpenHub 仍是默认入口。 +- Pi RPC stream 中 `thinking_*` 事件默认不进入可见 assistant bubble；可见回复只渲染 `text_*` / assistant final text，避免 Omniroute/freefirst 的 reasoning_content 泄漏到页面。 +- gateway 仅在 `enable_page_ai_pi_lab` 开启时注入 Pi Lab runtime，默认 body 标记为 hidden，不改变 OpenHub 默认入口。 +- 新增 smoke：静态结构、禁用态 API endpoint、mock-mode API 验证脚本、浏览器 smoke 脚本。 +- 新增 spike checklist：`design/07-ai/done/7-69-page-ai-pi-first-lab-checklist-v1.md`，逐项标注 Phase A-E 已完成项与下一阶段 gap。 + +## 3. 未完成内容 + +- 系统 PATH 仍未安装全局 `pi`，但已通过 `npx -y @earendil-works/pi-coding-agent@0.80.3` 包装器完成真实 `pi --mode rpc` 端到端 smoke；后续需决定是否固定安装方式或配置 `MNOTE_PAGE_AI_PI_BIN`。 +- receipt 尚未写入 Turso/libSQL 正式表，仍为 provider-neutral JSONL adapter。 +- `mnote.tool_receipt.write` 当前仍是最小 tool envelope 路径，未作为独立持久化入口深化。 +- watcher 刷新已按 MNote 文件写入链路声明和返回 metadata，但还需登录态浏览器端 smoke 证明 tiptap 当前页被 watcher 刷新。 +- 已基于最新 `@earendil-works/pi-web-ui@0.75.3` 源码重新评估，而不是使用 recycle 旧源码。其 `ChatPanel` / `AgentInterface` / `MessageEditor` / message-tool renderer 是成熟 UI 参考，但直接接入会同时引入浏览器端 `pi-agent-core`、IndexedDB session/provider key、API key prompt、proxy、attachments、artifacts 和 `Agent.state.tools` 事实源，与 MNote 托管 Pi RPC/SSE、AiAccessScope 和 MNote-owned tools 边界冲突。 +- 本轮采用 MNote-native adapter：视觉与交互参考官方 `ChatPanel/AgentInterface` 的消息流、composer、tool timeline、model/runtime controls 和 artifacts-style rail；session、API key、模型、工具权限、receipt 仍由 MNote 后端托管。若下一阶段要直接复用官方组件，迁移条件是先提供不依赖浏览器 API key/IndexedDB/Agent tools 的 remote-session adapter。 +- API endpoint smoke 当前覆盖禁用态 3000；完整 mock-mode smoke 需要用 `MNOTE_PAGE_AI_PI_LAB=1 MNOTE_PAGE_AI_PI_LAB_RUNTIME=mock` 启动独立服务后运行。 + +## 4. Pi 是否进入下一阶段 + +建议进入下一阶段，但仍保持 internal/lab： + +- 通过：MNote 侧最小 runtime manager、tool facade、allowed roots、LightRAG facade、file patch、receipt adapter、SSE UI 已形成闭环。 +- 未通过生产门槛：Turso receipt 表、正式登录态 browser smoke、watcher tiptap 刷新截图/断言仍未完整。 + +下一阶段应聚焦真实 runtime 和验收，不扩大默认入口。 + +## 5. OpenHub 状态 + +OpenHub 继续保持默认 Page AI 主线。Pi Lab 未替换、未破坏 OpenHub / LightRAG / Turso 路径；相关路由和 UI 均受 `MNOTE_PAGE_AI_PI_LAB=1` / `enable_page_ai_pi_lab` 控制。 + +## 6. 验证记录 + +- `node scripts/task-pi-lab-static-smoke.js`：通过，78 项。 +- `node scripts/task-pi-lab-api-endpoint-smoke.js`：通过，10/10；当前 3000 服务未启用 Pi Lab，验证禁用态和 asset。 +- `node scripts/task-pi-lab-mock-api-smoke.js`：通过；覆盖 mock runtime start、SSE events、allowed roots、当前页读取、越界拒绝、当前 `.md` patch、watcher refresh metadata、LightRAG facade、citation/open-reference facade、send、abort。 +- `node scripts/task-pi-lab-browser-smoke.js`：通过；覆盖当前 MNote Page AI 抽屉、dev-only 悬浮 `π` 入口、Pi/OpenHub 切换、`omniroute/freefirst`、MNote tool rail、composer、status API 和截图；不再把独立 `/page-ai/pi` 当作主要 UI 验收面。 +- Pi + Omniroute/freefirst 浏览器实测截图：`tmp/page-ai-pi-omniroute-freefirst-final-ok-20260704-v3.png`；证据 JSON：`tmp/page-ai-pi-omniroute-freefirst-final-ok-20260704-v3.json`。最终 assistant 可见文本为 `OK`，`assistantStreaming=false`，`inDrawer=true`，模型为 `omniroute/freefirst`，runtime 为 `rpc`。 +- `node scripts/task-pi-lab-mock-api-smoke.js`：通过；使用 mock mode 独立 3332 服务与 `MNOTE_PI_LAB_SMOKE_ROOT=/tmp/mnote-pi-lab-smoke`，覆盖 start/send/abort/events、allowed roots、越界拒绝、当前页 read、文件 patch、receipt。 +- `node scripts/task-pi-lab-api-endpoint-smoke.js`：通过，10/10；支持启用态 + Bearer smoke auth，验证 status schema、disabled builtins、runtime asset 和端点存在。 +- `codegraph sync . && codegraph status .`：通过；索引 up to date。 +- 真实 Pi RPC smoke：通过；使用 `/tmp/mnote-pi-cli-wrapper.sh` 调用 `npx -y @earendil-works/pi-coding-agent@0.80.3`，MNote 以 `MNOTE_PAGE_AI_PI_LAB_RUNTIME=rpc` / `MNOTE_PAGE_AI_PI_BIN=/tmp/mnote-pi-cli-wrapper.sh` 启动，验证 `start` 返回 `runtimePid`、当前页读取、越界拒绝、当前 `.md` patch、`send` accepted、`abort` 成功。 +- `node scripts/task-pi-lab-rpc-api-smoke.js`：新增 RPC API smoke 固化脚本（2026-07-04 7-69 收尾），覆盖 runtimeMode=rpc status、runtimePid 真实子进程验证、start/send/abort 端点、tool-call MNote facades（allowed roots、越界拒绝、.md patch 含 watcher refresh/version change、LightRAG、citation）、SSE 事件流（runtime_started 含 pid/mode/disabledBuiltinTools）、多会话生命周期、Pi 进程清理。需要真实 Pi CLI + API key 完整测试 send 实际 AI 调用。 +- `cd rust && cargo check -p mnote-web`：通过。 +- `which pi`：无输出；本轮通过 `MNOTE_PAGE_AI_PI_BIN` 指向 wrapper 完成真实 RPC smoke。 + +## RPC 验证命令 + +```bash +# 启动 mnote-web（真实 Pi RPC 模式） +MNOTE_PAGE_AI_PI_LAB=1 \ +MNOTE_PAGE_AI_PI_LAB_RUNTIME=rpc \ +MNOTE_PAGE_AI_PI_BIN=/tmp/mnote-pi-cli-wrapper.sh \ +MNOTE_PI_LAB_ALLOWED_ROOTS=/tmp/mnote-pi-rpc-smoke \ +npm run desktop:hot + +# 另一个终端运行 smoke +MNOTE_PI_LAB_BASE=http://127.0.0.1:3000 \ +MNOTE_PI_LAB_AUTH="Bearer pi-lab-smoke" \ +MNOTE_PAGE_AI_PI_BIN=/tmp/mnote-pi-cli-wrapper.sh \ +MNOTE_PI_LAB_ALLOWED_ROOTS=/tmp/mnote-pi-rpc-smoke \ +node scripts/task-pi-lab-rpc-api-smoke.js +``` + +mock 验证命令： + +```bash +MNOTE_PAGE_AI_PI_LAB=1 \ +MNOTE_PAGE_AI_PI_LAB_RUNTIME=mock \ +MNOTE_PI_LAB_ALLOWED_ROOTS=/tmp/mnote-pi-lab-smoke \ +MNOTE_PI_LAB_BASE=http://127.0.0.1:3000 \ +node scripts/task-pi-lab-mock-api-smoke.js +``` diff --git a/design/07-ai/done/7-70-page-ai-pi-lab-native-openhub-like-ui-checklist-v1.md b/design/07-ai/done/7-70-page-ai-pi-lab-native-openhub-like-ui-checklist-v1.md new file mode 100644 index 00000000..9ddaa3a8 --- /dev/null +++ b/design/07-ai/done/7-70-page-ai-pi-lab-native-openhub-like-ui-checklist-v1.md @@ -0,0 +1,51 @@ +# 7-70 Page AI Pi Lab 原生 OpenHub-like UI Checklist v1 + +状态：done（UI spike + P2 Pi tool bridge 回归） +Owner：07-ai / mnote-web / page-ai-runtime +日期：2026-07-04 + +## 1. 验收项 + +- [x] OpenHub 继续保持默认 Page AI 主线。 +- [x] Pi Lab 默认显示独立 `π` 悬浮按钮，不以 `MNOTE_PAGE_AI_PI_LAB=1` 作为显示前置条件。 +- [x] `MNOTE_PAGE_AI_PI_LAB` 保留为强制关闭开关，默认值为开启。 +- [x] Pi Lab 点击后打开独立 MNote-native drawer。 +- [x] Pi Lab 不挂载到 `[data-testid="wolai-page-ai-drawer"]`。 +- [x] Pi Lab 不 iframe 第二个完整应用。 +- [x] Pi Lab 不复用 OpenHub provider tab、按钮或 iframe 页面。 +- [x] topbar 显示 Pi Lab、session/runtime status、model、close/minimize。 +- [x] context strip 显示当前页、选区、allowed roots、LightRAG、changed files。 +- [x] message timeline 显示 user / assistant / system、streaming、aborted。 +- [x] provider thinking 不进入 visible final answer；reasoning 仍默认隐藏。 +- [x] tool/receipt rail 显示 tool status、deny reason、receipt、file version、diff summary、citation count。 +- [x] composer 支持多行输入、当前页/选区/LightRAG 快捷按钮、send、abort。 +- [x] diagnostics 默认折叠，不挤占首屏。 +- [x] MNote-owned tools 保留，不开放 Pi 原始 `bash/read/write/edit`。 +- [x] allowed roots 越界读写在 UI 中显示 denied 和 deny reason，并写 receipt。 +- [x] LightRAG 仍是唯一默认 knowledge provider；Pi 只通过 MNote facade 查询。 +- [x] patch 响应保持 watcher refresh / `polling=false` contract。 +- [x] Pi 默认模型继续为 Omniroute `freefirst`。 +- [x] static smoke（119 checks）、api endpoint smoke、mock/API smoke、RPC API smoke、browser smoke、cargo check、CodeGraph sync/status 已运行。 +- [x] 真实 Pi RPC + Omniroute/freefirst UI 截图回归已补：`tmp/page-ai-pi-lab-rpc-browser-real-7-71.png`。 +- [x] 真实 `/documents/local-md:*` 文档页默认注入独立 Pi Lab `π` 入口：`tmp/page-ai-pi-lab-rpc-browser-p1-7-71c.png`。 +- [x] Pi Lab start session 绑定当前 root/page/title。 +- [x] “当前页”快捷按钮调用 `mnote.current_page.read` 并读取当前 Markdown。 +- [x] “选区”快捷按钮读取 tiptap live selection snapshot 并注入 composer。 +- [x] `.md` patch 后通过 local-folder event bus / document refresh 更新当前 `.ProseMirror`，未新增高频轮询。 +- [x] 修复 P1 审查发现的任意 Cookie 认证绕过、跨用户 session 查询、selection tool host snapshot 标识、`tool_receipt.write` 空操作和 pagePath smoke 误报。 +- [x] Pi RPC subprocess 通过 per-session extension 注册 MNote-owned custom tools。 +- [x] 真实 Pi 主动调用 `mnote_current_page_read`，并经 `/api/page-ai/pi/tool-call-bridge` 回到 MNote `mnote.current_page.read` 的 API smoke 已通过。 +- [x] bridge token 使用 OS 随机源生成，不序列化到 session JSON，不写入 extension 文件。 +- [x] bridge endpoint 拒绝非 running session，aborted/error session 不能继续通过 bridge 调 tool。 +- [x] session TTL、最大 session 数、start/send/tool rate limit 和过期 session 目录清理已补。 +- [x] P2 真实浏览器截图已补：`tmp/page-ai-pi-lab-rpc-browser-p2-visible-reply-7-70.png`，并断言 assistant bubble 本身包含真实 Pi 回复。 +- [x] Pi Lab UI 已按 OpenHub-like 方向收敛：设置、上下文、tools、receipts 默认折叠，主对话区优先，模型选择入口保留。 +- [x] OpenHub-like 折叠 UI 截图已补：`tmp/page-ai-pi-lab-openhub-like-ui-collapsed-v2-7-70.png`。 +- [x] Pi Lab UI 已按 OpenHub 平台式首屏二次收敛：大标题、水平工具栏、白色对话卡片、居中空状态示例、底部大输入框与 Build/Plan/model/budget 控制条；截图：`tmp/page-ai-pi-lab-openhub-platform-empty-v4-7-70.png`。 + +## 2. 下一阶段 + +- [ ] Turso/libSQL 正式 receipt 表。 +- [ ] in-process `AgentSession` / Node sidecar SDK 方案评估，用于替代当前 RPC subprocess + extension bridge spike。 +- [ ] production Pi binary 显式配置和版本锁定。 +- [ ] session resume / retry / history drawer 产品化。 diff --git a/design/07-ai/done/7-70-page-ai-pi-lab-native-openhub-like-ui-record-v1.md b/design/07-ai/done/7-70-page-ai-pi-lab-native-openhub-like-ui-record-v1.md new file mode 100644 index 00000000..a52cb1e2 --- /dev/null +++ b/design/07-ai/done/7-70-page-ai-pi-lab-native-openhub-like-ui-record-v1.md @@ -0,0 +1,93 @@ +# 7-70 Page AI Pi Lab 原生 OpenHub-like UI 验收记录 v1 + +状态：done（UI spike + P2 Pi tool bridge 回归） +Owner：07-ai / mnote-web / page-ai-runtime +日期：2026-07-04 + +## 1. 结论 + +7-70 已完成 Pi Lab 从 7-69 的“OpenHub 抽屉内 provider 面板”到“默认显示的独立 `π` 悬浮入口 + MNote-native 抽屉”的切换。OpenHub 继续作为默认 Page AI 主线，Pi Lab 不复用 OpenHub 按钮、iframe 页面、provider tab 或抽屉容器。 + +Pi Lab 可以进入下一阶段受控验证，但仍不替换 OpenHub。2026-07-04 已补跑真实 Pi RPC + Omniroute/freefirst 的浏览器回归，证明真实 Pi text stream 能进入 MNote-native timeline 且 provider thinking 不进入 visible final answer。随后补齐了文档页 `/documents/local-md:*` 默认注入独立 Pi Lab、当前页读取、tiptap live selection snapshot、allowed roots deny、`.md` patch 后 watcher/refresh 刷新当前 tiptap 页的浏览器回归。 + +P2 已补齐真实 Pi 主动调用 MNote-owned tools 的最小链路：由于 Pi RPC 协议没有 host 回写 `tool_result` 的 stdin command，当前 spike 采用 per-session Pi extension bridge 注册 `mnote_*` custom tools。Pi 子进程仍使用 `--no-builtin-tools` 禁用原始 `bash/read/write/edit`，只允许 `mnote_current_page_read` 等 MNote 工具名；extension execute 通过内部 `/api/page-ai/pi/tool-call-bridge` 回到 MNote `execute_tool`，由 MNote 执行 allowed roots / LightRAG facade / receipt 写入。真实 Omniroute/freefirst API smoke 已观察到 Pi 发出 `tool_execution_start: mnote_current_page_read`，MNote bridge 执行 `mnote.current_page.read`，并返回最终 marker。 + +## 2. 已实现内容 + +- `sidebar-page-ai-pi-lab-runtime.js` 改为独立 drawer：`[data-page-ai-pi-lab-launcher]` 默认显示，点击打开 `[data-page-ai-pi-lab="drawer"]`，不再调用 `attachPanelToDrawer` / `setOpenHubVisible`，不再出现 `data-page-ai-pi-lab-openhub-tab`。 +- UI 补齐 topbar、session/runtime/model/status、context strip、message timeline、composer、right rail receipts/tools、默认折叠 diagnostics；2026-07-04 二次收敛为 OpenHub 平台式首屏：大标题、水平工具栏、白色对话卡片、居中空状态示例、底部大输入框与 Build/Plan/model/budget 控制条。 +- `MNOTE_PAGE_AI_PI_LAB` 改为默认开启，保留为 `0/false` 强制关闭开关；后端 `status` 返回 `uiMode=independent_mnote_native_drawer`。 +- 保留 MNote-owned tool set 和 Pi builtin 禁用策略：`bash/read/write/edit` 仍默认不可用。 +- tool event UI 补充 deny reason、diff summary、file version、citation count、changed files chip。 +- mock runtime send 事件补充 LightRAG mock citation 与 diff event，用于浏览器截图验证 stream/citation/diff 的 UI 形态。 +- OpenHub 回归通过浏览器 smoke 验证：OpenHub drawer API 仍存在，OpenHub iframe host 仍独立打开，Pi drawer 不在 OpenHub drawer 内。 +- 文档页 shell 现在在 `enable_page_ai_pi_lab` 开启时注入 Pi Lab runtime，因此真实 `/documents/local-md:*` 页面默认也显示独立 `π` 入口。 +- Pi Lab start session 会绑定当前 `rootUri / workspaceId / pagePath / pageTitle`。 +- “当前页”快捷按钮实际调用 `mnote.current_page.read`，并把当前 Markdown 内容注入 composer / system timeline。 +- “选区”快捷按钮消费 `window.getSelection()` 与 `mnote:leptos-tiptap-spike:selection` 快照，已在真实 tiptap 页面验证选中文本注入 composer。 +- `mnote.local_file.patch` tool event 后会走 local-folder event bus + document pane refresh，不新增轮询；真实浏览器截图已验证当前 `.md` patch 后 `.ProseMirror` 显示新内容。 +- 每个 Pi session 生成独立 tool bridge extension，注册 `mnote_current_page_read / mnote_selection_read / mnote_allowed_roots_describe / mnote_local_file_read / mnote_local_file_patch / mnote_knowledge_rag_query / mnote_reference_open / mnote_tool_receipt_write`。 +- bridge token 使用 `/dev/urandom` 生成，不随 session JSON 序列化，不写入 extension 文件；token 通过子进程 env 注入。 +- `/api/page-ai/pi/tool-call-bridge` 只接受匹配 bridge token 且仍处于 `RuntimeRunning/TurnRunning` 的 session。 +- session TTL、最大 session 数、start/send/tool 简单 rate limit 已补；过期 session 目录和空 rate bucket 会清理。 + +## 3. 第三方 UI 复用决策 + +- `@earendil-works/pi-web-ui` 继续作为 ChatPanel / AgentInterface / ThinkingBlock / tool renderer / artifacts rail 的交互参考，不直接引入 MNote 主链。 +- `@assistant-ui/react-pi` 继续作为 HTTP/SSE thread contract 参考，不让其接管 MNote provider key、IndexedDB session、Pi browser Agent 或 tool 权限。 +- `ai-elements` 继续作为 message / reasoning / tool / source / prompt input 形态参考，不引入 React/Tailwind/shadcn 依赖。 + +## 4. 验证记录 + +- `node scripts/task-pi-lab-static-smoke.js`：通过，119 checks。 +- `MNOTE_PI_LAB_BASE=http://127.0.0.1:33170 MNOTE_PI_LAB_AUTH='Bearer pi-lab-smoke' node scripts/task-pi-lab-api-endpoint-smoke.js`：通过，10/10。 +- `MNOTE_PI_LAB_BASE=http://127.0.0.1:33170 MNOTE_PI_LAB_AUTH='Bearer pi-lab-smoke' MNOTE_PI_LAB_SMOKE_ROOT=/tmp/mnote-pi-lab-smoke node scripts/task-pi-lab-mock-api-smoke.js`：通过。 +- `MNOTE_PI_LAB_BASE=http://127.0.0.1:33170 MNOTE_PI_LAB_AUTH_HEADER='Bearer pi-lab-smoke' MNOTE_PI_LAB_BROWSER_ROOT=/tmp/mnote-pi-lab-browser-smoke MNOTE_PI_LAB_SCREENSHOT=/mnt/Data1T/mnote/tmp/page-ai-pi-lab-native-drawer-7-70.png node scripts/task-pi-lab-browser-smoke.js`：通过。 +- `MNOTE_PI_LAB_BASE=http://127.0.0.1:33172 MNOTE_PI_LAB_AUTH='Bearer pi-lab-smoke' MNOTE_PI_LAB_BROWSER_ROOT=/tmp/mnote-pi-real-rpc-smoke-1783130268 MNOTE_PI_LAB_SCREENSHOT=/mnt/Data1T/mnote/tmp/page-ai-pi-lab-rpc-browser-real-7-71.png node scripts/task-pi-lab-rpc-browser-smoke.js`：通过；使用 `MNOTE_PAGE_AI_PI_LAB_RUNTIME=rpc`、`MNOTE_PAGE_AI_PI_BIN=/tmp/mnote-pi-cli-wrapper.sh` 和 Omniroute `freefirst`。 +- `MNOTE_PI_LAB_BASE=http://127.0.0.1:33172 MNOTE_PI_LAB_AUTH='Bearer pi-lab-smoke' MNOTE_PI_LAB_BROWSER_ROOT=/tmp/mnote-pi-p1-rpc-smoke-1783133999 MNOTE_PI_LAB_SCREENSHOT=/mnt/Data1T/mnote/tmp/page-ai-pi-lab-rpc-browser-p1-7-71c.png node scripts/task-pi-lab-rpc-browser-smoke.js`：通过；覆盖真实文档页 Pi Lab 默认入口、当前页读取、tiptap selection、allowed roots deny、`.md` patch、watcher/refresh 到 `.ProseMirror`、真实 Pi stream、abort、非 iframe；同时收紧 pagePath 绑定断言。 +- `MNOTE_PI_LAB_BASE=http://127.0.0.1:33172 MNOTE_PI_LAB_AUTH='Bearer pi-lab-smoke' MNOTE_PI_LAB_SMOKE_ROOT=/tmp/mnote-pi-real-rpc-smoke-1783130268 MNOTE_PAGE_AI_PI_BIN=/tmp/mnote-pi-cli-wrapper.sh node scripts/task-pi-lab-rpc-api-smoke.js`：通过；覆盖真实 Pi RPC subprocess、send、SSE、abort、allowed roots deny、`.md` patch、receipt。 +- `MNOTE_PI_LAB_BASE=http://127.0.0.1:33172 MNOTE_PI_LAB_AUTH='Bearer pi-lab-smoke' OPENAI_API_KEY= node scripts/task-pi-lab-rpc-api-smoke.js`：通过；覆盖真实 Pi custom tool 主动调用 `mnote_current_page_read`、MNote bridge 执行 `mnote.current_page.read`、marker 返回、send、SSE、abort、allowed roots deny、`.md` patch、receipt。 +- `MNOTE_PI_LAB_BASE=http://127.0.0.1:33172 MNOTE_PI_LAB_AUTH='Bearer pi-lab-smoke' MNOTE_PI_LAB_SCREENSHOT=/mnt/Data1T/mnote/tmp/page-ai-pi-lab-rpc-browser-p2-visible-reply-7-70.png node scripts/task-pi-lab-rpc-browser-smoke.js`：通过；覆盖真实浏览器 Pi Lab 默认入口、原生 drawer、当前页/选区、allowed roots deny、`.md` patch watcher refresh、真实 Pi stream、assistant bubble 可见回复、abort、非 iframe。该 smoke 已修正为断言 assistant bubble 本身包含 marker，而不是误用 drawer 全文里的用户 prompt。 +- `MNOTE_PI_LAB_BASE=http://127.0.0.1:33172 MNOTE_PI_LAB_AUTH='Bearer pi-lab-smoke' MNOTE_PI_LAB_SCREENSHOT=/mnt/Data1T/mnote/tmp/page-ai-pi-lab-openhub-like-ui-collapsed-v2-7-70.png node scripts/task-pi-lab-rpc-browser-smoke.js`：通过；覆盖 OpenHub-like 折叠 UI，设置/上下文/右侧 tools/receipts 默认收起，主对话区成为视觉重点，同时保留模型选择入口和真实 Pi 可见回复。 +- `curl -H 'Cookie: foo=bar' http://127.0.0.1:33172/api/page-ai/pi/status`：返回 401 `page_ai_pi_lab_invalid_session_cookie`，验证任意 Cookie 不能绕过 Pi Lab API 认证。 +- `cd rust && cargo check -p mnote-web`：通过。 +- `codegraph sync . && codegraph status .`：通过，index up to date；CodeGraph 提示索引由旧 engine 构建，可后续择机 full re-index。 + +## 5. 截图证据 + +- Pi Lab 原生抽屉：`tmp/page-ai-pi-lab-native-drawer-7-70.png` + - 显示独立 `π` 悬浮按钮。 + - 显示独立 Pi Lab drawer，不是 iframe。 + - 显示 `omniroute/freefirst`、runtime `mock`、aborted、context strip、tool rail、receipt rail。 + - 显示 prompt、mock stream、abort、LightRAG mock citation、patch/diff、changed files、allowed roots deny receipt。 +- OpenHub 默认入口回归：`tmp/page-ai-pi-lab-openhub-default-7-70.png` + - 显示 OpenHub drawer 仍可独立打开。 + - 同屏保留独立 `π` 入口，说明 Pi Lab 未复用 OpenHub 抽屉容器。 +- 真实 Pi RPC 浏览器回归：`tmp/page-ai-pi-lab-rpc-browser-real-7-71.png` + - 显示 runtime `rpc`、模型 `omniroute/freefirst`。 + - 显示真实 Pi RPC text stream 返回 `REAL_PI_BROWSER_OK_*` 标记。 + - provider thinking 事件仅进入 diagnostics，不进入 visible final answer。 + - 同时验证 allowed roots deny、markdown patch receipt、abort UI 状态和非 iframe 独立 drawer。 +- P1 文档页功能回归：`tmp/page-ai-pi-lab-rpc-browser-p1-7-71c.png` + - 显示真实 `/documents/local-md:*` 页面默认存在独立 `π` 入口。 + - 显示 Pi Lab drawer 内绑定当前页、选区、runtime `rpc`、模型 `omniroute/freefirst`。 + - 显示当前页已由 patch 从 `Browser RPC Original` 刷新为 `Browser RPC Patched`。 + - 显示 allowed roots deny receipt、patch diff receipt、changed files chip。 +- P2 真实 Pi RPC 浏览器回归：`tmp/page-ai-pi-lab-rpc-browser-p2-visible-reply-7-70.png` + - 显示真实 MNote 文档页默认独立 `π` 入口与独立 Pi Lab drawer。 + - 显示 runtime `rpc`、模型 `omniroute/freefirst`、Pi builtin `bash/read/write/edit` disabled。 + - 显示当前页读取、选区、allowed roots deny receipt、patch diff receipt、changed files chip、assistant 可见回复。 +- OpenHub-like 折叠 UI 回归：`tmp/page-ai-pi-lab-openhub-like-ui-collapsed-v2-7-70.png` + - 显示设置、上下文、MNote tools、Receipts 默认折叠。 + - 显示模型选择入口 `omniroute/freefirst`，主 timeline 和 composer 保持首屏重点。 +- OpenHub 平台式空状态回归：`tmp/page-ai-pi-lab-openhub-platform-empty-v4-7-70.png` + - 显示独立 Pi Lab 抽屉使用 OpenHub 平台式标题、顶部工具栏、白色对话卡片、居中问号空状态和五个示例。 + - 设置、上下文、诊断默认不占首屏；通过齿轮展开。 + - 底部保留大输入框、发送按钮、Build/Plan、`omniroute/freefirst` 模型选择、预算和当前页/选区快捷入口。 + +## 6. 未完成内容与风险 + +- receipt 仍落 `provider_neutral_jsonl_adapter_v1`，尚未迁移到 Turso/libSQL 正式 `ai_provider_sessions` / `ai_tool_events` / `ai_file_patches` 表。 +- 真实 Pi RPC + Omniroute/freefirst 已补浏览器回归；真实 Pi 主动调用 MNote tools 的最小 bridge 链路已在 API smoke 中通过。长期更正统方向仍是 in-process `AgentSession` / Node sidecar SDK，避免依赖 RPC subprocess + extension bridge。 +- watcher refresh 已通过真实文档页 `.md` patch 后 `.ProseMirror` 更新验证；仍需在后续产品化中补更细的 file version 冲突与多 pane 场景。 +- P1/P2 审查后已修复任意 Cookie 认证绕过、跨用户 session 查询、selection tool 缺少 host snapshot 标识、`tool_receipt.write` 空操作、browser smoke pagePath 误报、bridge token 可预测、aborted session bridge 调用、rate bucket 增长和 token 落盘风险。 diff --git a/design/07-ai/done/7-70-page-ai-pi-lab-native-openhub-like-ui-v2.md b/design/07-ai/done/7-70-page-ai-pi-lab-native-openhub-like-ui-v2.md new file mode 100644 index 00000000..49fb8526 --- /dev/null +++ b/design/07-ai/done/7-70-page-ai-pi-lab-native-openhub-like-ui-v2.md @@ -0,0 +1,499 @@ +# 7-70 Page AI Pi Lab 原生 OpenHub-like UI 设计 v1 + +状态：done +Owner：07-ai / mnote-web / page-ai-runtime +日期：2026-07-04 + +## 1. 结论 + +Pi Lab 下一阶段不做第二个 iframe，也不把 `@earendil-works/pi-web-ui` 或 LibreChat / Open WebUI 这类完整应用直接嵌入 MNote。正确方向是： + +```text +MNote Page AI 独立 Pi Lab 浮动入口 + 原生抽屉 UI + -> 体验参考当前 OpenHub AI 面板，但入口和容器不依赖 OpenHub + -> 运行协议参考 @assistant-ui/react-pi 的 PiClient / HTTP SSE thread contract + -> 消息、composer、tool、artifact 形态参考 Pi 官方 web-ui 与 ai-elements + -> 权限、知识库、receipt、watcher refresh 继续由 MNote 托管 +``` + +OpenHub 继续作为默认 Page AI 主线。Pi Lab 使用独立浮动按钮与独立抽屉容器，默认在 MNote 页面中显示；目标是把 7-69 的 debug spike UI 升级成可验证的 MNote-native Page AI 体验，而不是替代或复用 OpenHub 的入口。若后续确认不需要 Pi Lab，直接退役这一独立入口和 runtime 即可，不需要先用 feature flag 隔离。 + +## 2. 原则 + +- **独立入口默认显示**：Pi Lab 新增自己的悬浮按钮和抽屉容器，默认显示，不复用当前 OpenHub 的按钮、iframe 页面或 provider tab 容器；以后退役 OpenHub 或 Pi Lab 任一侧，都不影响另一侧。 +- **原生承载**：Pi Lab UI 渲染在 MNote 自有 DOM 中，不新增独立产品页作为主验收面，不 iframe 第二个完整 AI 应用。 +- **优先参考和复用**：能复用当前 OpenHub 已证明的交互、Pi 官方 UI 的事件语义、assistant-ui 的 runtime contract、ai-elements 的组件形态，就不要自造一套孤立协议。 +- **MNote 拥有真相**：session binding、allowed roots、LightRAG facade、tool receipt、file patch、citation/open-reference、watcher refresh 仍归 MNote；第三方 UI 不能接管这些事实源。 +- **Debug 后置**：Page AI 首屏必须是对话、输入、上下文和变更结果；runtime health、scope JSON、receipt 原文只进折叠诊断区或开发态右栏。 +- **不破坏 OpenHub**：OpenHub 仍是默认入口和默认 Page AI 主线；Pi Lab 作为独立入口与 OpenHub 并列但互不依赖，不出现普通用户可见的 fallback/迁移暗示。 + +## 3. 参考资源取证 + +### 3.1 当前 OpenHub UI + +本地 OpenHub 是当前最接近目标体验的产品基线： + +- `/mnt/Data1T/Mnote_data/openhub/OpenHub/smart-query-frontend/src/pages/SmartQueryPage.jsx` +- `/mnt/Data1T/Mnote_data/openhub/OpenHub/smart-query-frontend/src/components/ChatInput.jsx` +- `/mnt/Data1T/Mnote_data/openhub/OpenHub/smart-query-frontend/src/components/AssistantMessage.jsx` +- `/mnt/Data1T/Mnote_data/openhub/OpenHub/smart-query-frontend/src/components/ToolCall.jsx` +- `/mnt/Data1T/Mnote_data/openhub/OpenHub/smart-query-frontend/src/components/HistoryDrawer.jsx` +- `/mnt/Data1T/Mnote_data/openhub/OpenHub/smart-query-frontend/src/components/DiffViewer.jsx` +- `/mnt/Data1T/Mnote_data/openhub/OpenHub/smart-query-frontend/src/components/KnowledgeManager.jsx` + +可参考能力： + +- 顶部/底部紧凑控制区：agent mode、model select、当前页面/当前文件夹按钮。 +- 主消息流：user / assistant bubble、streaming、retry / undo、idle state。 +- assistant message：reasoning 折叠、tool summary、tool cards、citation chips。 +- session/history：历史抽屉、恢复会话、归档。 +- changed files / diff：隐藏索引桥接 MNote，用户侧展示 changed files / diff 入口。 +- knowledge：知识库入口和 citation 回跳模式。 + +不直接复用方式： + +- 不把 OpenHub React/AntD 组件直接搬进 `mnote-web` 主运行时。 +- 不复制 OpenHub session/message 全文存储作为 Pi Lab 真相。 +- 不复用 OpenHub iframe shell 实现 Pi Lab，因为用户目标是 MNote-native。 + +### 3.2 Pi 官方 web-ui + +`@earendil-works/pi-web-ui@0.75.3` 已核验为 MIT 包，描述为 “Reusable web UI components for AI chat interfaces powered by @earendil-works/pi-ai”。包内包含： + +- `ChatPanel` +- `AgentInterface` +- `MessageList` / `Messages` +- `MessageEditor` +- `StreamingMessageContainer` +- `ThinkingBlock` +- tool renderers +- artifacts runtime / sandbox +- `ModelSelector` +- IndexedDB storage stores + +可参考能力： + +- Pi 消息流与工具流的视觉分层。 +- thinking / tool / artifact 的独立组件边界。 +- composer 与 model/thinking selector 的组合方式。 +- artifacts-style 侧栏。 + +不直接整包接入原因： + +- 默认假设 browser 侧持有 `Agent`、provider keys、IndexedDB session/settings。 +- 默认可暴露 Pi 自带 tools / attachments / artifacts 事实源。 +- 与 MNote 后端托管 Pi RPC/SSE、AiAccessScope、MNote-owned tools 的边界冲突。 + +迁移条件： + +- 先提供 remote-session adapter，使 `ChatPanel` / `AgentInterface` 不直接管理 provider key、IndexedDB 和 `Agent.state.tools`。 +- 所有 tool call、file read/write、knowledge query、receipt 仍必须走 MNote facade。 + +### 3.3 assistant-ui / react-pi + +`@assistant-ui/react-pi@0.0.5` 已核验为 MIT，说明其 browser entry 是 RPC-isomorphic `PiClient`，通过 HTTP/SSE 驱动 Pi-backed threads。其 contract 包含： + +```text +GET /threads +POST /threads +GET /threads/:id +PATCH /threads/:id +POST /threads/:id/messages +POST /threads/:id/cancel +GET /models +POST /threads/:id/model +POST /threads/:id/thinking +GET /threads/:id/events +``` + +可参考能力： + +- thread / message / composer / queue / cancel 的协议边界。 +- snapshot-first SSE reconnect 语义。 +- model / thinking controls。 +- host UI approval requests。 +- tool-associated approval / interrupt 的 UI 映射。 + +当前不直接引 React UI 的原因： + +- `mnote-web` 当前主路径是 Rust SSR + browser JS，不是 React app。 +- 直接引入 React island、Tailwind/shadcn 体系会扩大构建和运行时边界。 +- 当前优先目标是把 MNote-owned Pi adapter 做完整，而不是重开前端框架主线。 + +设计决策：**先对齐 contract，不先引 UI 框架**。后续如果 MNote 需要 React island，再以该 contract 为迁移桥。 + +### 3.4 ai-elements + +`ai-elements@1.9.0` 已核验为 Apache-2.0，定位是基于 shadcn/ui 的 AI-native component registry。 + +可参考能力： + +- message / conversation / prompt input / reasoning / tool / source / response card 的组件形态。 +- 更现代的 AI chat 视觉密度和状态表达。 + +当前不直接接入原因： + +- 依赖 React、Tailwind、shadcn registry 和 CSS variables。 +- 对当前 MNote Rust SSR + browser JS 主路径引入成本偏高。 + +设计决策：作为视觉和组件拆分参考，不作为 7-70 第一阶段依赖。 + +### 3.5 完整应用类参考 + +LibreChat、Open WebUI、AnythingLLM、Continue、Cline、Roo Code 只作为交互模式参考： + +- LibreChat / Open WebUI / AnythingLLM：参考历史会话、多模型、RAG、文件区、设置入口。 +- Continue / Cline / Roo Code：参考 agent tool timeline、审批、diff、changed files、任务状态。 + +不作为直接依赖或嵌入目标。 + +## 4. UI 目标结构 + +### 4.1 独立入口与抽屉整体 + +```text +MNote page + Pi Lab floating button（default visible） + -> Pi Lab native drawer（independent from OpenHub iframe/page） + topbar + Pi Lab title + session title + runtime status + close / minimize + context strip + current page chip + selection chip + allowed roots chip + LightRAG chip + model / thinking selector + body + message timeline + optional right rail + composer + prompt input + context buttons + send / abort / queue state + folded diagnostics +``` + +桌面端允许右侧 rail；移动端不显示右 rail，改为底部 sheet 或折叠 section。 + +入口规则： + +- Pi Lab 使用独立悬浮按钮，例如右下角 `π`，默认渲染。 +- Pi Lab 点击后打开独立抽屉，不借用 OpenHub 当前按钮、OpenHub iframe 页或 OpenHub provider tab。 +- Pi Lab 抽屉可以视觉参考 OpenHub，但 DOM、状态、session、事件订阅、关闭/最小化都独立。 +- OpenHub 的现有按钮和页面保持不变；Pi Lab 不在 OpenHub 面板内新增 tab 作为主入口。 +- 若未来退役 OpenHub，Pi Lab 浮动入口仍可保留；若退役 Pi Lab，OpenHub 入口不受影响。 +- `MNOTE_PAGE_AI_PI_LAB` 可保留为临时开发/强制关闭开关，但不是产品入口显示的前置条件。 + +### 4.2 Topbar + +目标是接近 OpenHub 的 AI 面板，而不是 debug 工具页。 + +必须包含： + +- Pi Lab 标题与实验标记；不放 OpenHub/Pi provider tabs 作为主导航。 +- session label：`Pi Lab · 当前页面标题`，恢复会话后显示短 session id。 +- runtime status：idle / starting / streaming / error。 +- model label：默认 `omniroute/freefirst`，可后续扩展 selector。 +- close/minimize。 + +不要在 topbar 放大段 `scope`、`disabled builtins`、raw env 等诊断文案。 + +### 4.3 Context Strip + +替代当前偏 debug 的工具列表，参考 OpenHub `ChatInput` 中当前页面/文件夹按钮： + +- 当前页：真实 `.md` 路径或页面标题，点击在 MNote 中定位。 +- 选区：无选区时 disabled，有选区时显示字符数。 +- allowed roots：显示 root 名称和数量，点击展开只读详情。 +- LightRAG：显示 provider 状态；query citation 走 `mnote.reference.open`。 +- 文件变更：当前 session 有 patch 后显示 changed files chip。 + +Context strip 是用户可理解的任务上下文，不展示 JSON。 + +### 4.4 Message Timeline + +消息模型要吸收 OpenHub `AssistantMessage` 与 Pi/assistant-ui 的 part 语义： + +```text +MNotePiUiMessage + id + role = user | assistant | system + status = queued | streaming | done | error | aborted + createdAt + model + parts[] + +MNotePiUiPart + text + reasoning + toolCall + toolResult + citation + diff + fileChange + approval + error +``` + +展示规则： + +- user message 右侧气泡。 +- assistant message 左侧主体块，正文优先。 +- reasoning 默认折叠，严禁把 provider `reasoning_content` 混入 final answer。 +- tool timeline 默认折叠成 summary，运行中自动展开当前 tool。 +- tool 输入/输出长 JSON 默认收起，显示摘要和 deny reason。 +- citation 显示为来源 chip，点击走 MNote open-reference。 +- diff / fileChange 显示为 changed file chips + diff summary，点击走 MNote document pane / diff view。 +- error 明确显示 provider/runtime/tool deny，不伪装成功。 + +### 4.5 Tool Timeline + +参考 OpenHub `ToolCall.jsx`、Pi official tool renderers、Cline/Roo 的工具审批流。 + +第一阶段必须覆盖： + +- `mnote.current_page.read` +- `mnote.selection.read` +- `mnote.allowed_roots.describe` +- `mnote.local_file.read` +- `mnote.local_file.patch` +- `mnote.knowledge_rag.query` +- `mnote.reference.open` +- `mnote.tool_receipt.write` + +每个 tool card 至少显示： + +- tool name +- state：pending / running / allowed / denied / error / done +- compact params summary +- deny reason +- receipt id +- file version before / after +- diff summary +- citation count + +默认禁用 Pi 原始 `bash/read/write/edit` 的状态可以放在折叠详情里，不占据首屏。 + +### 4.6 Composer + +参考 OpenHub `ChatInput`、Pi `MessageEditor`、assistant-ui composer queue 语义。 + +第一阶段： + +- 多行输入。 +- icon-only 当前页、选区、文件夹/allowed roots、LightRAG 按钮，带 tooltip 和 aria-label。 +- send 按钮。 +- streaming 时显示 abort；若后端支持 queue，再允许 follow-up queue。 +- 发送前自动附带 MNote context envelope，不把上下文 URL 或 JSON 写入 textarea。 +- 禁用态要有明确原因：未启动 runtime、missing model、missing auth、scope denied。 + +后续阶段： + +- model selector。 +- thinking level selector。 +- thread queue / steer。 +- prompt template / skill picker。 + +### 4.7 Right Rail / Drawer + +桌面端右侧 rail 承接“有用但不该挤占主对话”的信息： + +- session/history：当前只显示当前 session 与最近 session，完整历史后续做抽屉。 +- changed files：变更文件列表、patch count、打开按钮。 +- citations：本轮 citation 列表。 +- receipts：最近 tool receipts，默认摘要。 +- runtime：Pi PID / provider session id / runtime mode，只在 dev mode 显示。 + +移动端右 rail 不常驻，改为按钮展开底部 sheet。 + +### 4.8 Diagnostics + +折叠 diagnostics 只面向开发： + +- raw SSE events tail。 +- allowed roots raw snapshot。 +- receipt raw JSON。 +- runtime command / pid / session dir。 +- disabled builtin tools。 + +默认折叠，不参与普通用户验收截图。 + +## 5. 后端与协议设计 + +### 5.1 保留现有 7-69 endpoint + +当前 7-69 已有： + +- `/api/page-ai/pi/status` +- `/api/page-ai/pi/bootstrap` +- `/api/page-ai/pi/start` +- `/api/page-ai/pi/send` +- `/api/page-ai/pi/abort` +- `/api/page-ai/pi/events` +- `/api/page-ai/pi/tool-call` +- `/page-ai/pi` + +7-70 不要求立即破坏这些 endpoint。 + +但前端入口要调整为默认显示的独立浮动按钮与独立 drawer host；`/page-ai/pi` 可保留为 debug/internal 直达页，不作为产品主验收入口。 + +### 5.2 新增 PiClient-aligned adapter 层 + +为了后续能接 `@assistant-ui/react-pi` 或复用其 reducer 语义，新增 provider-neutral adapter contract： + +```text +GET /api/page-ai/pi/threads +POST /api/page-ai/pi/threads +GET /api/page-ai/pi/threads/:id +POST /api/page-ai/pi/threads/:id/messages +POST /api/page-ai/pi/threads/:id/cancel +GET /api/page-ai/pi/threads/:id/events +GET /api/page-ai/pi/models +POST /api/page-ai/pi/threads/:id/model +POST /api/page-ai/pi/threads/:id/thinking +``` + +兼容策略： + +- 第一阶段可在前端 adapter 中把旧 endpoint 映射为 thread contract。 +- 后端可逐步增加新 endpoint；旧 smoke 不被破坏。 +- SSE 必须 snapshot-first：重连先发当前 thread snapshot，再发 live events。 +- browser disconnect 不等于 abort；只有 cancel/abort 明确停止 runtime。 + +### 5.3 UI event normalization + +Pi RPC / mock / future SDK event 统一归一为： + +```text +thread_snapshot +message_created +message_delta +message_completed +reasoning_delta +tool_call_started +tool_call_updated +tool_call_completed +tool_call_denied +citation_added +file_patch_applied +receipt_written +runtime_status_changed +thread_error +``` + +所有 UI 只消费 normalized events，不直接依赖 Pi JSONL 原始字段。 + +## 6. 数据与权限边界 + +- `AiAccessScope` / allowed roots 是所有 file tool 的唯一授权来源。 +- Pi Lab UI 只显示 allowed roots 摘要，不允许用户从 UI 临时扩大 root。 +- `mnote.local_file.read` / `patch` 必须返回 normalized path、root id、deny reason、file version。 +- LightRAG 继续是唯一默认 knowledge provider；Pi 只能通过 `mnote.knowledge_rag.query` 查询。 +- citation 点击必须走 `mnote.reference.open` / MNote open-reference，不直接让 Pi 打开文件。 +- receipt 当前仍可落 provider-neutral adapter，但 UI v2 必须按 Turso/libSQL 迁移目标设计字段。 +- 文件 patch 后必须通过 MNote watcher / document refresh 链路更新 tiptap；禁止新增轮询刷新。 + +## 7. 实施阶段 + +### Phase A：Native UI v2 骨架 + +修改范围： + +- `rust/crates/mnote-web/browser/sidebar-page-ai-pi-lab-runtime.js` +- `scripts/task-pi-lab-static-smoke.js` +- `scripts/task-pi-lab-browser-smoke.js` +- 必要时补 `rust/crates/mnote-web/src/ssr/styles/components/page-ai.css` + +目标： + +- 当前 Pi Lab 从 debug shell 升级为 OpenHub-like 抽屉。 +- Pi Lab 使用独立悬浮按钮打开独立抽屉，不复用 OpenHub 按钮、OpenHub iframe 页面或 provider tab。 +- 首屏只保留对话、context strip、composer。 +- tool receipts / diagnostics 默认后置。 +- 截图必须显示：在 MNote 当前页面中通过独立 `π` 浮动按钮打开 Pi Lab 原生抽屉，非 OpenHub iframe、非独立页、非 OpenHub provider tab。 + +### Phase B：Event / message model 收口 + +修改范围： + +- `sidebar-page-ai-pi-lab-runtime.js` +- `rust/crates/mnote-web/src/routes/page_ai_pi.rs` +- smoke 脚本 + +目标： + +- 新增 normalized event reducer。 +- reasoning、tool、citation、diff、receipt 不再混杂在一条 debug 文本里。 +- SSE reconnect snapshot-first。 +- abort/cancel 明确区分 browser disconnect。 + +### Phase C：PiClient-aligned adapter + +目标： + +- 增加或前端模拟 `/threads` contract。 +- `send` / `cancel` / `events` 对齐 `@assistant-ui/react-pi` 的语义。 +- 保持旧 endpoint 兼容，直到 smoke 全部迁移。 + +### Phase D：OpenHub-like 功能补齐 + +目标： + +- session history 抽屉。 +- changed files rail。 +- citation list。 +- diff preview。 +- model / thinking selector。 +- tool approval / host UI requests。 + +### Phase E：第三方组件复用决策 + +进入条件： + +- Phase A-D 浏览器截图和 smoke 通过。 +- 当前 MNote native UI 已形成稳定 message/event model。 + +决策： + +- 若 MNote 仍保持非 React 主路径：继续原生实现，只参考 Pi web-ui / ai-elements。 +- 若引入 React island：优先评估 `assistant-ui + @assistant-ui/react-pi`，并复用 Phase C contract。 +- 若官方 Pi web-ui 提供 remote-session adapter：评估局部复用 `AgentInterface` / `Messages` / `MessageEditor`，不得引入 browser provider key 和 IndexedDB 作为 MNote 真相。 + +## 8. 验收标准 + +- OpenHub 默认入口不变。 +- MNote 默认显示独立 Pi Lab 浮动按钮；点击后打开独立 Pi Lab 原生抽屉。 +- Pi Lab 不复用 OpenHub 按钮、OpenHub 页面或 OpenHub iframe 容器。 +- UI 首屏接近 OpenHub：消息流、上下文、输入框、模型/状态、tool/citation/diff 摘要齐全。 +- 不出现第二个 iframe AI 应用。 +- 可发送 prompt、接收 stream、abort。 +- reasoning 折叠且不泄漏到 final answer。 +- tool call 显示状态、deny reason、receipt id。 +- allowed roots 越界读写在 UI 中显示 denied。 +- LightRAG citation 可点击回跳。 +- 当前 `.md` patch 后显示 changed file，并通过 watcher refresh 当前 tiptap 页。 +- diagnostics 默认折叠。 +- browser smoke 输出截图。 + +## 9. 明确非目标 + +- 不替换 OpenHub。 +- 不把 Pi Lab 做成普通用户默认入口。 +- 不 iframe LibreChat / Open WebUI / AnythingLLM / Pi web-ui demo app。 +- 不把 Pi Lab 做成 OpenHub 面板内部的 provider tab 或复用 OpenHub 页面容器。 +- 不把 React / shadcn / Tailwind 作为 7-70 Phase A 必需依赖。 +- 不开放 Pi 原始 bash、无约束 read/write/edit。 +- 不新增第二套 RAG。 +- 不把 OpenHub 或 Pi 的 session JSONL 作为 MNote control-plane 长期真相。 + +## 10. 当前后续任务 + +- [ ] Phase A：重做 `sidebar-page-ai-pi-lab-runtime.js` 信息架构、独立浮动入口与视觉层级。 +- [ ] Phase A：更新 browser smoke，截图验证独立 `π` 浮动按钮打开 OpenHub-like Pi Lab 抽屉。 +- [ ] Phase B：抽出 normalized event reducer。 +- [ ] Phase C：补 PiClient-aligned thread adapter。 +- [ ] Phase D：补 changed files / diff / citation rail。 +- [ ] Phase E：重新评估是否引入 `assistant-ui` 或 Pi official remote-session adapter。 diff --git a/design/07-ai/done/7-71-unified-ai-management-control-plane-and-pi-lab-integration-checklist-v1.md b/design/07-ai/done/7-71-unified-ai-management-control-plane-and-pi-lab-integration-checklist-v1.md new file mode 100644 index 00000000..3e12507d --- /dev/null +++ b/design/07-ai/done/7-71-unified-ai-management-control-plane-and-pi-lab-integration-checklist-v1.md @@ -0,0 +1,141 @@ +# 7-71 统一 AI 管理面板与 Pi Lab 功能接入 — 实施检查清单 + +状态：partial — P0/P1/P2 完成；P3/P4/P5 管理员侧 OpenHub-like AI 管理与逐用户配置完成，用户自助偏好与 LightRAG 写管理待后续 +日期：2026-07-04 + +> 本清单与 `design/07-ai/process/7-71-unified-ai-management-control-plane-and-pi-lab-integration-v1.md` 的 §11 进度表保持同步。 +> process 文档保留架构结论；本文件记录已完成的检查项供快速验证。 + +## 已通过验收项 + +### P0 — 合同与只读聚合 ✅ + +| 检查项 | 通过 | +|---|---| +| `/api/ai-settings/effective` GET 端点已注册 | ✅ | +| `/api/ai-settings/access-scopes` GET 端点已注册 | ✅ | +| `/api/ai-admin/access-scopes` GET 端点已注册 | ✅ | +| 所有 AI settings/scopes 端点无 POST/PUT/DELETE | ✅ | +| `effective_settings` 使用 `load_active_directory_grants` 生成 allowed roots | ✅ | +| `load_model_policy_and_quota` 不读取 `allowed_roots_json` | ✅ | +| `source_of_truth` 声明为 `"directory_grants"` | ✅ | +| 静态 smoke 27/27 通过 | ✅ | + +### P1 — Pi Lab history 入库 ✅ + +| 检查项 | 通过 | +|---|---| +| `persist_upsert_run` 写入 `ai_runtime_runs` | ✅ | +| `persist_append_event` 写入 `ai_runtime_events` | ✅ | +| `GET /api/page-ai/pi/sessions` 路由注册 | ✅ | +| `GET /api/page-ai/pi/sessions/{id}` 路由注册 | ✅ | +| `GET /api/page-ai/pi/sessions/{id}/events` 路由注册 | ✅ | +| list_sessions 按 pi_lab profile + pi acp_runtime 过滤 | ✅ | + +### P2 — Receipt 与 patch 入库 ✅ + +| 检查项 | 通过 | +|---|---| +| migration v9 新增 `ai_tool_events / ai_file_patches` | ✅ | +| SQLite 与 Turso/libSQL store 均实现 append/list | ✅ | +| Pi tool receipt 默认写 control-plane | ✅ | +| 成功 patch 关联写入 `ai_file_patches` | ✅ | +| JSONL 仅在 control-plane 写失败时作为 debug fallback | ✅ | +| deny reason、diff summary、file version、citation count 可查询 | ✅ | +| receipt 与 patch 按当前用户隔离 | ✅ | + +### P3 — AI 管理中心与管理员模型写管理 ✅ + +| 检查项 | 通过 | +|---|---| +| `/admin/ai` 路由与管理员鉴权 | ✅ | +| `/user/ai` 路由与用户鉴权 | ✅ | +| 账户菜单有独立 AI 管理入口 → `/admin/ai` 或 `/user/ai` | ✅ | +| AI 管理页面 SSR 渲染 OpenHub-like 左侧分页与多 section | ✅ | +| Access Scopes 只读展示（无 POST/PUT/DELETE、无写表单） | ✅ | +| Sessions & Receipts 显示真实 Pi session、receipt、patch 数量 | ✅ | +| Providers & Models 管理写操作 | ✅ | +| `/user/ai` 用户可操作设置 | ❌ | + +### 独立入口保留检查 + +| 检查项 | 通过 | +|---|---| +| OpenHub `/page-ai/openhub/ai` | ✅ | +| OpenHub admin guard 路由 | ✅ | +| OpenHub status API | ✅ | +| Pi Lab shell `/page-ai/pi` | ✅ | +| Pi Lab event stream `GET /api/page-ai/pi/events` | ✅ | +| Pi Lab start/send/abort 路由 | ✅ | + +### P4 — 工具、Skills/MCP 管理 ✅ + +| 检查项 | 通过 | +|---|---|---| +| `GET/PUT /api/ai-admin/settings` 原子策略端点 | ✅ | +| 模型 provider、allowed models、角色模型与 failover 写入 | ✅ | +| MNote-owned tools allow/ask/deny 写入 | ✅ | +| Skill 添加、描述、启停、删除 | ✅ | +| MCP transport/command/url/network/secret refs 写入 | ✅ | +| MCP 强制 facade-only 与 sandbox | ✅ | +| 刷新后配置持久存在 | ✅ | +| effective API 投影模型、Skills、MCP | ✅ | + +### P5 — 逐用户 AI 配置 ✅ + +| 检查项 | 通过 | +|---|---| +| OpenHub `UserManagement`、模型/工具/Skill 权限实现已核验 | ✅ | +| `GET /api/ai-admin/users` 用户列表 | ✅ | +| `GET/PUT /api/ai-admin/users/{user_id}/settings` | ✅ | +| 用户可独立选择管理员允许的模型和默认模型 | ✅ | +| 用户工具策略只能相对全局降权 | ✅ | +| 用户 Skill/MCP 只能在全局启用目录中开关 | ✅ | +| 普通用户登录后的 effective API 应用 override | ✅ | +| allowed roots 仍只来自 `directory_grants` | ✅ | +| 用户抽屉采用 OpenHub-like 分组：模型按 provider、工具按 risk、Skill/MCP 开关、目录只读跳统一授权页 | ✅ | + +## 后续项 + +| 项 | 状态 | 说明 | +|---|---|---| +| `/user/ai` 用户可操作偏好 | 未实现 | 当前只读 effective config，不能提升管理员权限 | +| LightRAG source/index/status 写管理 | 未实现 | 继续使用唯一 knowledge provider 与现有 facade | +| provider/skill/MCP 专用规范化表 | 未实现 | 当前原子策略存入 `ai_policies.model_policy_json`；出现独立查询、授权或生命周期需求时迁移 | + +## 浏览器证据 + +- Pi Lab 原生抽屉：`tmp/7-71-pi-lab-browser-final.png` +- AI 管理页：`tmp/7-71-ai-admin-final.png` +- 模型写管理：`tmp/7-71-ai-admin-openhub-like-ui-final/models.png` +- Skills/MCP 写管理：`tmp/7-71-ai-admin-openhub-like-ui-final/skills-mcp.png` +- 逐用户 AI 配置：`tmp/7-71-ai-admin-openhub-like-ui-final/users.png` +- 管理页运行时摘要：会话 1、回执 3、文件补丁 1 +- Pi Lab 截图可见真实 mock 回复、citation、diff、abort，且 OpenHub 默认入口仍独立存在 +- `mnote-e2e` 通过 control-plane `role=admin` 进入管理员模式；浏览器验收用 dev seed 临时确保测试账号为 admin +- OpenHub 的 MCP 实际为用户工作区 `.opencode/mcp` 文件展示，并非 Admin per-user override；MNote 采用更严格的管理员注册 + 用户启停 + facade/sandbox 模型 + +## 验证命令 + +```bash +# 静态 smoke（只读代码审计，无需启动服务器） +node scripts/task-ai-management-control-plane-static-smoke.js +MNOTE_AI_ADMIN_OUTPUT_DIR=tmp/7-71-ai-admin-openhub-like-ui-final \ + node scripts/task-ai-management-browser-smoke.js +node scripts/task-pi-lab-static-smoke.js + +CARGO_TARGET_DIR=/tmp/mnote-7-71-target cargo check -p mnote-web +CARGO_TARGET_DIR=/tmp/mnote-7-71-target cargo test -p control-plane ai_tool_events +CARGO_TARGET_DIR=/tmp/mnote-7-71-target cargo test -p control-plane ai_file_patches +CARGO_TARGET_DIR=/tmp/mnote-7-71-target cargo test -p control-plane migrations +CARGO_TARGET_DIR=/tmp/mnote-7-71-target cargo test -p mnote-web ai_settings +CARGO_TARGET_DIR=/tmp/mnote-7-71-target cargo test -p mnote-web page_ai_pi +CARGO_TARGET_DIR=/tmp/mnote-7-71-target cargo test -p mnote-web ai_admin + +# 运行时验证（需要 mnote-web 运行于 localhost:3000） +# curl -s http://localhost:3000/api/ai-settings/effective | jq '{source: .sourceOfTruth, models: [.models[].id], rootsCount: (.allowedRoots | length)}' +# curl -s http://localhost:3000/api/ai-settings/access-scopes | jq '.sourceOfTruth' +# curl -s http://localhost:3000/api/ai-admin/access-scopes | jq '.sourceOfTruth' +# curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/admin/ai +# curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/user/ai +``` diff --git a/design/07-ai/process/7-69-page-ai-pi-first-lab-v1.md b/design/07-ai/process/7-69-page-ai-pi-first-lab-v1.md index f6221bb1..49ef986d 100644 --- a/design/07-ai/process/7-69-page-ai-pi-first-lab-v1.md +++ b/design/07-ai/process/7-69-page-ai-pi-first-lab-v1.md @@ -449,8 +449,8 @@ assistant-ui / CopilotKit / AG-UI 进入 UI 备选评估 本稿通过后新增： -- `7-69-page-ai-pi-first-lab-checklist-v1.md` -- `scripts/task*-page-ai-pi-rpc-smoke.js` +- `design/07-ai/done/7-69-page-ai-pi-first-lab-checklist-v1.md` +- `scripts/task-pi-lab-rpc-api-smoke.js` - `scripts/task*-page-ai-pi-lightrag-smoke.js` - `scripts/task*-page-ai-pi-file-patch-smoke.js` @@ -472,3 +472,38 @@ assistant-ui / CopilotKit / AG-UI 进入 UI 备选评估 Pi 不应被过早否定；它已经有足够多的 runtime 与生态基础，值得作为首选实验底座。 Pi 也不应被过早宣布替换 OpenHub；MNote 需要自己补齐多用户控制面、Turso 审计、LightRAG tool、allowed roots 和 UI 产品化边界。 + +## 13. Spike 执行记录（2026-07-03） + +本稿对应的最小可验证 spike 已落地到代码，验收记录见： + +- `design/07-ai/done/7-69-page-ai-pi-first-lab-spike-record-v1.md` +- `design/07-ai/done/7-69-page-ai-pi-first-lab-checklist-v1.md` + +当前完成范围： + +- `/api/page-ai/pi/*` 与 `/page-ai/pi` dev-only 入口。 +- Pi RPC/mock runtime manager 与 MNote 管控 sessionDir。 +- 8 个 MNote-owned tool facade。 +- allowed roots 越界拒绝、file version、diff summary、deny reason、receipt JSONL adapter。 +- LightRAG 仍通过 `knowledge_rag` facade 暴露给 Pi，不引入第二套 RAG。 +- 文件 patch 返回 watcher refresh metadata，且 `polling=false`。 +- MNote-native Pi Lab UI 支持 start/send/events/abort、SSE stream、tool/citation/diff/receipt 显示。 +- OpenHub 仍保持默认 Page AI 主线。 + +当前未完成范围： + +- 全局 `pi` CLI 仍未进入 PATH；但已通过 `MNOTE_PAGE_AI_PI_BIN=/tmp/mnote-pi-cli-wrapper.sh` 包装 `npx -y @earendil-works/pi-coding-agent@0.80.3` 跑通真实 `pi --mode rpc` 端到端 smoke。 +- Turso/libSQL 正式 receipt 表迁移；当前仍为 `provider_neutral_jsonl_adapter_v1`。 +- 登录态浏览器中验证 watcher 刷新 tiptap 当前页。 +- `@earendil-works/pi-web-ui` 未成为长期 UI 基座，本轮由 MNote-native debug UI 承接。 + +验证结果： + +- `node scripts/task-pi-lab-static-smoke.js`：通过。 +- `node scripts/task-pi-lab-api-endpoint-smoke.js`：通过。 +- `node scripts/task-pi-lab-mock-api-smoke.js`：通过，覆盖 mock runtime、SSE、allowed roots、越界拒绝、当前页读取、当前 `.md` patch、watcher refresh metadata、LightRAG facade、citation/open-reference facade、send、abort。 +- `node scripts/task-pi-lab-browser-smoke.js`：通过，覆盖 `/page-ai/pi` 独立页、Pi Lab 面板、输入框、启动/发送/清空按钮、runtime asset、status API。 +- 真实 Pi RPC smoke：通过，覆盖 MNote 托管启动 `pi --mode rpc`、`runtimePid`、当前页读取、越界拒绝、当前 `.md` patch、send accepted、abort。 +- `node scripts/task-pi-lab-rpc-api-smoke.js`：新增，覆盖 runtimeMode=rpc 下 status、runtimePid 真实子进程、start/send/abort 端点、tool-call MNote facades（allowed roots、越界拒绝、.md patch、watcher refresh、LightRAG、citation）、SSE 事件流、多会话生命周期、Pi 进程清理。需要真实 Pi CLI（MNOTE_PAGE_AI_PI_BIN）与可选 API key 验证 send。 +- `cd rust && cargo check -p mnote-web`：通过。 diff --git a/design/07-ai/process/7-71-unified-ai-management-control-plane-and-pi-lab-integration-v1.md b/design/07-ai/process/7-71-unified-ai-management-control-plane-and-pi-lab-integration-v1.md new file mode 100644 index 00000000..2f7b1d5c --- /dev/null +++ b/design/07-ai/process/7-71-unified-ai-management-control-plane-and-pi-lab-integration-v1.md @@ -0,0 +1,562 @@ +# 7-71 MNote 统一 AI 管理面板与 Pi Lab 功能接入设计 v1 + +状态：process +Owner：07-ai / mnote-web / control-plane / Page AI +日期：2026-07-04 + +## 1. 结论 + +应该做 MNote 原生统一 AI 管理面板，但顺序不是先堆 UI，而是先把 control-plane 合同、持久化和 effective config API 做成唯一真相，再让 Pi Lab / OpenHub / LightRAG 消费同一套配置。 + +文件夹授权必须只有一套：当前 `/admin/access-policy` 与 `/user/access-policy` 管理的 `directory_grants` 同时就是 MNote 工作区访问授权和 AI `allowed roots` 的事实源。AI 管理面板可以把它纳入同一个信息架构，但不能再维护第二套 AI-only allowed roots。 + +OpenHub 的 admin 面板证明了正确产品结构：provider/model、skills、tools、MCP、目录权限、知识库、历史、用量、健康状态必须先有管理面，聊天 UI 只展示用户可用的有效配置。MNote 不能把 OpenHub admin 作为 MNote AI 的长期真相，因为 OpenHub 仍是独立默认 Page AI 主线，Pi Lab 是 MNote-native 新入口，二者后续可能任意退役。MNote AI 管理中心应落在 Turso/libSQL control-plane。 + +## 2. 调研依据 + +### 2.1 OpenHub + +源码： + +- `/mnt/Data1T/Mnote_data/openhub/OpenHub/smart-query-frontend/src/pages/AdminPage.jsx` +- `/mnt/Data1T/Mnote_data/openhub/OpenHub/smart-query-frontend/src/components/UserSettingsDrawer.jsx` +- `/mnt/Data1T/Mnote_data/openhub/OpenHub/smart-query-frontend/src/components/HistoryDrawer.jsx` +- `/mnt/Data1T/Mnote_data/openhub/OpenHub/smart-query-frontend/src/services/api.js` +- `/mnt/Data1T/Mnote_data/openhub/OpenHub/smart-query-backend/app/api/admin.py` + +可复用的产品模型： + +- 管理后台按区段管理：用户、模型配置、工具权限、技能、目录权限、知识库、用量、系统健康。 +- 用户设置抽屉只显示管理员已允许的有效配置：模型、技能、MCP、目录、工具、用量。 +- 权限是三层：admin global policy -> user override -> effective policy。 +- 历史记录是左侧抽屉，支持新建、刷新、归档、分页/滚动。 + +不应直接搬的部分： + +- opencode 服务管理、飞书渠道、WeKnora 配置导出。 +- React/AntD 组件主链。 +- OpenHub SQLite 表作为 MNote 真相层。 + +### 2.2 Pi / Pi Web UI + +源码： + +- `earendil-works-pi-web-ui-0.75.3.tgz` +- `/mnt/Data1T/tmp/pi-web-ui-shot/node_modules/@earendil-works/pi-web-ui/src/` +- `/mnt/Data1T/tmp/pi-web-ui-shot/node_modules/@earendil-works/pi-agent-core/dist/` +- `rust/crates/mnote-web/src/routes/page_ai_pi.rs` +- `rust/crates/mnote-web/browser/sidebar-page-ai-pi-lab-runtime.js` + +可复用的合同： + +- `SessionData`: `id/title/model/thinkingLevel/messages/createdAt/lastModified` +- `SessionMetadata`: `id/title/lastModified/messageCount/usage/thinkingLevel/preview` +- `AgentEvent`: `agent_start/end`、`message_update/end`、`tool_execution_start/update/end` +- `ThinkingLevel`: `off/minimal/low/medium/high/xhigh` +- Provider/model 设置形态：SettingsDialog、ModelSelector、ProvidersModelsTab、CustomProvider。 + +不能照搬的部分： + +- IndexedDB 是 Pi standalone browser app 的存储，不是 MNote 真相层。 +- Pi 原始 `bash/read/write/edit` 仍必须禁用。 +- Pi web-ui 是 Lit Web Components；MNote 当前 Pi Lab 保持原生 runtime，不 iframe、不让 Pi UI 接管 provider key 或工具权限。 + +### 2.3 MNote 当前底座 + +已有： + +- `directory_grants`：当前文件夹授权事实。 +- `ai_policies`：已有 `allowed_roots_json / model_policy_json / quota_json`，但无 HTTP 管理 API 和 UI。 +- `ai_runtime_runs / ai_runtime_events`：已有跨 provider run/event journal。 +- `ai_external_conversation_bindings`：已有 MNote session 与外部 provider conversation 绑定。 +- `/admin/access-policy` 与 `/user/access-policy`：已有文件夹授权面板。 + +缺口： + +- Pi Lab session 仍在内存 HashMap，重启丢失。 +- Pi Lab receipt 仍在内存 + JSONL adapter，无法按用户/工作区查询。 +- provider/model/skills/MCP/tools 的 MNote-native 管理 API 和 UI 不存在。 +- Pi Lab UI 的历史、设置、模型选择还没有接入真实配置源。 + +## 3. 目标架构 + +```text +MNote AI 管理中心 + /admin/ai admin global policy + /user/ai user effective settings + | + v +Turso/libSQL control-plane + directory_grants + ai_policies + ai_runtime_runs / ai_runtime_events + ai_external_conversation_bindings + ai_provider_configs / ai_model_catalog / ai_model_grants + ai_tool_policies / ai_skill_registry / ai_mcp_servers + ai_tool_events / ai_file_patches + | + v +MNote AI Facade APIs + effective config + allowed roots + model/provider catalog + skills/tools/MCP policy + LightRAG facade + session history / receipts + | + +--> OpenHub iframe/default Page AI + +--> Pi Lab native drawer + +--> future native agents +``` + +OpenHub 继续保持默认 Page AI 入口。MNote 管理中心不替换 OpenHub admin，而是成为 MNote 侧 AI 权限和配置的真相层；需要同步给 OpenHub 时，通过 provider identity sync / OpenHub admin API 做下游同步。 + +## 4. 管理面板信息架构 + +### 4.1 Admin：`/admin/ai` + +沿用现有 `/admin/access-policy` 的 SSR 页面方式，新增 AI 管理中心。左侧区段建议： + +1. `Overview` + - AI runtime 状态、OpenHub 状态、Pi Lab 状态、LightRAG 状态、最近错误。 +2. `Providers & Models` + - Omniroute/OpenAI/Anthropic/Google/local providers。 + - API key/base URL/认证状态。 + - 模型可见性、默认 Build/Plan/Task 模型、failover chain。 + - 默认保留 `omniroute/freefirst` 作为 Pi Lab dev/default model。 +3. `Access Scopes` + - 直接复用当前 `/admin/access-policy`、`/user/access-policy` 文件夹授权 UI 和既有授权 API，不新增 AI-only 授权目录。 + - `directory_grants` 是 MNote 与 AI 共用的 allowed roots 事实源。 + - `AiAccessScope.allowed_roots`、OpenHub allowedRoots、Pi Lab allowed roots 都从 `directory_grants` 派生。 + - 支持 read/write、recursive、capabilities、workspace/user 维度。 + - 该区段只提供授权摘要、effective scope 预览和进入现有授权页的入口；若后续内嵌编辑，也必须调用同一套 `directory_grants` command/API。 +4. `Tools` + - MNote-owned tools 全局策略：allow/ask/deny。 + - 默认 deny raw bash/read/write/edit。 + - Pi 只显示并使用 MNote facade tools。 +5. `Skills` + - MNote builtin skills、Codex/Acontext skills、OpenHub/opencode skills 的 registry。 + - 全局启停，用户可在授权范围内开关。 +6. `MCP` + - MCP server registry、启动命令、allowed roots、network policy、env/secret 引用。 + - 默认不让 Pi 直接接管 raw MCP；Pi 通过 MNote facade 调用。 +7. `Knowledge` + - LightRAG 是唯一默认 provider。 + - 管理 source registry、index 状态、citation/open-reference 映射。 +8. `Sessions & Receipts` + - Page AI / OpenHub / Pi Lab / native agent 历史。 + - tool events、deny reason、diff summary、file version、citation count。 +9. `Usage & Quota` + - 按用户、workspace、provider、model 统计。 + - token、cost、request count、失败率。 + +### 4.2 User：`/user/ai` + +用户设置只显示 effective config： + +- 可用模型：来自 admin allowed models；用户只能隐藏或选择默认，不提升权限。 +- 可用 skills/tools/MCP：只能在 admin 允许范围内开关或降级。 +- 目录权限：查看由 `directory_grants` 派生的 allowed roots，并进入 `/user/access-policy` 请求或调整授权；不保存 AI 私有目录配置。 +- 历史记录：自己的 Page AI / Pi Lab sessions。 +- 用量：自己的 quota 与调用统计。 + +### 4.3 Pi Lab 抽屉接入 + +Pi Lab 顶部工具栏： + +- 历史按钮：打开 Pi Lab history drawer，数据来自 MNote `/api/page-ai/pi/sessions` 或统一 `/api/page-ai/sessions?provider=pi`。 +- 设置按钮：打开 MNote-native user AI settings overlay；管理员可跳到 `/admin/ai`。 +- 模型选择：读取 effective model options，不再硬编码单个 select。 +- Build/Plan：读取 agent mode policy，决定可用模型、thinkingLevel、tool policy。 +- 工具/引用/diff：继续只显示 MNote facade 返回的 receipt 和 citation。 + +## 5. 数据合同 + +### 5.1 复用现有表 + +- `directory_grants`：MNote 与 AI 共用的唯一文件夹授权事实源，也是 allowed roots 派生源。 +- `ai_policies`：workspace/user 的模型、配额、工具、skills/MCP 策略汇总层；不得作为第二套 allowed roots 真相。历史字段 `allowed_roots_json` 只能视为缓存/兼容快照，写入时必须由 `directory_grants` 派生。 +- `ai_runtime_runs`：统一 AI session/run 元数据。Pi Lab 不新建独立 session 真相表，先复用它。 +- `ai_runtime_events`：统一 message/tool/runtime event journal。 +- `ai_external_conversation_bindings`：OpenHub remote conversation / future external provider binding。 +- `user_ui_preferences`：前端折叠状态、默认 tab 等低风险 UI preference。 + +### 5.2 授权目录单一真相规则 + +- 不新增 `ai_allowed_roots`、`pi_allowed_roots`、`openhub_allowed_roots` 或任何同义表。 +- 不允许 Pi Lab、OpenHub、AI 管理页或 session 设置单独写一份目录授权 JSON。 +- 所有目录授权变更统一写入 `directory_grants`，沿用现有管理员/用户权限边界、审计和路径校验。 +- AI effective config 按 user/workspace 读取 `directory_grants`，生成 `AiAccessScope.allowed_roots`。 +- Pi Lab 创建 session/run 时记录 effective scope 快照，但每次工具执行仍按当前 `directory_grants` 重新校验。 +- OpenHub `allowedRoots` 是 MNote 下发的下游投影，不能反向成为授权真相。 +- `ai_policies.allowed_roots_json` 只能作为不可独立编辑的兼容快照、迁移输入或缓存；满足迁移条件后应删除或改名，避免误用和双写。 + +### 5.3 新增或规范化表 + +第一阶段优先最小新增： + +```sql +ai_tool_events( + id, + user_id, + workspace_id, + session_id, + run_id, + provider, + provider_session_id, + tool_name, + allowed, + deny_reason, + root_uri, + page_path, + normalized_file_path, + diff_summary, + citation_count, + before_file_version, + after_file_version, + payload_json, + created_at, + deleted_at +) +``` + +```sql +ai_file_patches( + id, + user_id, + workspace_id, + session_id, + run_id, + tool_event_id, + root_uri, + relative_path, + before_file_version, + after_file_version, + patch_summary_json, + created_at +) +``` + +第二阶段再规范化： + +- `ai_provider_configs` +- `ai_model_catalog` +- `ai_model_grants` +- `ai_tool_policies` +- `ai_skill_registry` +- `ai_skill_grants` +- `ai_mcp_servers` +- `ai_mcp_grants` +- `ai_usage_logs` +- `ai_model_failover_chains` + +说明：不要急着新增 `ai_provider_sessions`。MNote 已有 `ai_runtime_runs / ai_runtime_events`，Pi Lab history 可以先落这里；只有当 provider 原生 thread 与 MNote run/event journal 差异太大时，再加 provider-specific session detail 表。 + +## 6. API 合同 + +### 6.1 管理 API + +```text +GET /api/ai-admin/overview +GET /api/ai-admin/providers +PUT /api/ai-admin/providers/{provider_id} +GET /api/ai-admin/models +PUT /api/ai-admin/models/{provider_id}/{model_id}/policy +GET /api/ai-admin/access-scopes +GET /api/ai-admin/tools +PUT /api/ai-admin/tools/{tool_name}/policy +GET /api/ai-admin/skills +PUT /api/ai-admin/skills/{skill_id}/policy +GET /api/ai-admin/mcp +PUT /api/ai-admin/mcp/{server_id}/policy +GET /api/ai-admin/knowledge +GET /api/ai-admin/sessions +GET /api/ai-admin/receipts +GET /api/ai-admin/usage +``` + +### 6.2 用户有效配置 API + +```text +GET /api/ai-settings/effective +GET /api/ai-settings/models +PUT /api/ai-settings/models/{provider_id}/{model_id} +GET /api/ai-settings/tools +PUT /api/ai-settings/tools/{tool_name} +GET /api/ai-settings/skills +PUT /api/ai-settings/skills/{skill_id} +GET /api/ai-settings/mcp +GET /api/ai-settings/access-scopes +GET /api/ai-settings/usage +``` + +`GET /api/ai-admin/access-scopes` 与 `GET /api/ai-settings/access-scopes` 只读返回由 `directory_grants` 计算的 effective scope，并返回现有授权管理页入口。授权写入继续使用现有 access-policy / `directory_grants` command/API；不在 AI admin route 中定义第二套 grants 写语义。 + +### 6.3 Pi Lab history API + +可以做成 Pi-specific facade，但底层写 `ai_runtime_runs/events`： + +```text +GET /api/page-ai/pi/sessions +GET /api/page-ai/pi/sessions/{session_id} +PUT /api/page-ai/pi/sessions/{session_id}/title +DELETE /api/page-ai/pi/sessions/{session_id} +GET /api/page-ai/pi/sessions/{session_id}/events +``` + +响应参考 Pi `SessionMetadata`： + +```json +{ + "id": "pi_lab_...", + "title": "当前页解释", + "model": "omniroute/freefirst", + "thinkingLevel": "medium", + "lastModified": "2026-07-04T14:20:00Z", + "messageCount": 8, + "usage": {"input": 1200, "output": 400, "totalTokens": 1600}, + "preview": "帮我解释当前页面的逻辑..." +} +``` + +## 7. 实施顺序 + +### P0：合同与只读聚合 + +- 新增设计和 smoke baseline。 +- 增加 `/api/ai-settings/effective` 只读 API。 +- 聚合已有 `directory_grants`、`ai_policies`、agent descriptors、Pi defaults。 +- 明确 `effective.allowedRoots` 只从 `directory_grants` 派生；若 `ai_policies.allowed_roots_json` 存在，只作为兼容只读快照或迁移源，不参与新增写入。 +- Pi Lab model selector 改为消费 effective models，但仍保留 `omniroute/freefirst` fallback。 + +验收： + +- OpenHub 默认入口不变。 +- Pi Lab 打开后能显示来自 MNote effective config 的模型、allowed roots、tool policy。 + +### P1：Pi Lab history 入库 + +- Pi Lab start/send/end 写 `ai_runtime_runs / ai_runtime_events`。 +- 历史 drawer 读 MNote DB，不读 IndexedDB、不读内存 HashMap。 +- 现有 JSONL receipt 保留为 debug fallback。 + +验收： + +- 重启 mnote-web 后 Pi Lab 历史仍可见。 +- 同一 user/workspace 隔离生效。 + +### P2：Receipt 与 patch 入库 + +- 新增 `ai_tool_events / ai_file_patches`。 +- `mnote.local_file.read/patch`、LightRAG query、reference.open、tool_receipt.write 全部写入。 +- Pi Lab receipt rail 改读 DB event stream。 + +验收： + +- allowed roots deny、diff summary、file version、citation count 可在管理面板查询。 +- patch 后 watcher refresh 仍不新增轮询。 + +### P3：MNote AI 管理中心首版 + +- `/admin/ai` 先做四个可用 tab：Overview、Providers & Models、Access Scopes、Sessions & Receipts。 +- `/user/ai` 做 Models、Access、History、Usage。 +- 复用 `/admin/access-policy` / `/user/access-policy` 逻辑，不拆第二套授权事实；AI 面板里的 Access Scopes 本质上是该授权页面的 AI 视角入口。 + +验收： + +- 管理员可设置 Pi Lab 默认模型和可见模型。 +- 用户只能选择管理员允许的模型。 +- 文件夹授权仍同步 OpenHub，不破坏 OpenHub。 + +### P4：Skills / MCP / Tools / LightRAG 管理 + +- Skills registry 与 grants。 +- MCP registry 与 sandbox policy。 +- MNote-owned tools allow/ask/deny。 +- LightRAG source/index/status 管理。 + +验收： + +- Pi Lab settings 能显示 skills/MCP/tools effective 状态。 +- Pi 仍不能直接启用 raw bash/read/write/edit。 +- LightRAG 仍是唯一默认 knowledge provider。 + +## 8. 关键决策 + +1. **MNote 管理中心是必需的**，但第一步是 control-plane + effective API，不是先做完整 UI。 +2. **OpenHub admin 只作为参考和下游同步对象**，不作为 MNote AI 真相层。 +3. **文件夹授权只保留一套**：`directory_grants` 同时服务 MNote 工作区访问、OpenHub `allowedRoots` 和 Pi Lab `AiAccessScope.allowed_roots`；AI 管理页只提供同源视图和现有授权入口。 +4. **Pi IndexedDB schema 可参考，不能作为 MNote 持久化方案**。 +5. **Pi Lab history 先复用 `ai_runtime_runs/events`**，避免新增重复 session 表。 +6. **receipt/patch 必须入 Turso/libSQL**，JSONL 只保留 debug/crash recovery。 +7. **skills/MCP/tools 先管权限，再接 UI**；否则会把未受控工具暴露给 Pi。 +8. **secrets 不进前端、不硬编码**；provider API key 应只存 secret reference/env key，后续再接正式 secret store。 + +## 9. 风险 + +- 直接把 OpenHub admin 嵌进 MNote 会形成第二个 iframe 管理系统，和 Pi Lab 原生化目标冲突。 +- 先做 Pi UI settings 会把配置写进临时 DOM/内存，后续仍要重接 Turso。 +- 如果不先统一 history，Pi Lab 与 OpenHub 会话会分裂，用户无法判断哪个入口产生了修改。 +- MCP 管理若过早放开，容易绕过 AiAccessScope；必须默认只注册、只显示，不默认启用。 +- Model/provider secret 管理不能复用 Codex auth 作为产品实现；Codex auth 只可作为 dev smoke 输入。 + +## 10. 下一步最小可执行设计稿 + +建议下一张执行稿拆成： + +`7-72-page-ai-pi-lab-history-and-effective-config-control-plane-v1` + +范围只做： + +- `/api/ai-settings/effective` +- Pi Lab model options 读取 effective config +- Pi Lab session 写入 `ai_runtime_runs/events` +- Pi Lab history drawer 读 DB +- receipt 仍保留 JSONL，但设计 migration 到 `ai_tool_events` +- smoke 覆盖重启后历史存在、用户隔离、OpenHub 默认入口不变 + +做完 7-72 后，再做 `/admin/ai` 首版 UI。这样不会在 UI 上先行制造第二套事实源。 + +--- + +## 11. 实施进度（2026-07-04） + +### P0: 合同与只读聚合 — 进度 + +| 项 | 状态 | 证据 | +|---|---|---| +| 新增设计和 smoke baseline | ✅ 已完成 | `design/07-ai/process/7-71-*` 设计文档、`scripts/task-ai-management-control-plane-static-smoke.js` 静态 smoke（27/27 通过） | +| `/api/ai-settings/effective` 只读 API | ✅ 已实现 | `routes/ai_settings.rs::effective_settings` — GET-only，读 `directory_grants` 和 `ai_policies.model_policy_json/quota_json` | +| `/api/ai-settings/access-scopes` 用户只读 API | ✅ 已实现 | `routes/ai_settings.rs::user_access_scopes` — GET-only | +| `/api/ai-admin/access-scopes` 管理员只读 API | ✅ 已实现 | `routes/ai_settings.rs::admin_access_scopes` — GET-only，管理员鉴权 | +| 聚合 `directory_grants`、`ai_policies`、agent descriptors、Pi defaults | ✅ 已实现 | effective 响应聚合 providers、models、tool_catalog、lightrag_provider、access_policy_links | +| `effective.allowedRoots` 只从 `directory_grants` 派生 | ✅ 已验证 | `load_active_directory_grants` 读取 `list_directory_grants_for_actor`；`ai_policies.allowed_roots_json` 不被读取 | +| Pi Lab model selector 消费 effective models | ✅ 已实现 | `effective_settings` 响应含 models、default_model；Pi Lab 前端消费 | +| 静态 smoke 覆盖：路由注册、source of truth、无写操作 | ✅ 27/27 通过 | `scripts/task-ai-management-control-plane-static-smoke.js` | + +### P1: Pi Lab history 入库 — 进度 + +| 项 | 状态 | 证据 | +|---|---|---| +| Pi Lab start/send/end 写 `ai_runtime_runs / ai_runtime_events` | ✅ 已实现 | `page_ai_pi.rs::persist_upsert_run` / `persist_append_event` | +| 历史 drawer 读 MNote DB | ✅ 已实现 | `list_sessions` 读 `control_plane.list_ai_runtime_runs`；`get_session_history` / `get_session_events` 分别读 run 和 events | +| 现有 JSONL receipt 保留为 debug fallback | ✅ 已保留 | `PI_LAB_RECEIPT_STORE` JSONL 静态存储仍在 | +| Pi Lab session 路由注册 | ✅ 已验证 | `GET /api/page-ai/pi/sessions`、`GET .../{session_id}`、`GET .../{session_id}/events` | +| Pi Lab session 按 pi_lab/pi profile/acp_runtime 过滤 | ✅ 已验证 | `list_sessions` 过滤 `r.profile == PI_LAB_PROFILE && r.acp_runtime == PI_LAB_ACP_RUNTIME` | + +### P2: Receipt 与 patch 入库 — 已完成 + +| 项 | 状态 | 证据 | +|---|---|---| +| `ai_tool_events / ai_file_patches` migration | ✅ | `control-plane/migrations/009-ai-tool-events-file-patches.sql` | +| SQLite 与 Turso/libSQL store | ✅ | `append/list_ai_tool_event`、`append/list_ai_file_patch` | +| Pi tool receipt 入 control-plane | ✅ | `page_ai_pi.rs::write_receipt` | +| patch 关联写入 file patch journal | ✅ | receipt id 作为 `tool_event_id` | +| JSONL 降级为 debug fallback | ✅ | 仅 control-plane 写失败后追加 | +| 管理 API 查询 receipts / patches | ✅ | `/api/ai-settings/receipts`、`/api/ai-admin/receipts` | + +### P3: MNote AI 管理中心首版 — 管理员写管理完成 + +| 项 | 状态 | 证据 | +|---|---|---| +| `/admin/ai` 路由与入口 | ✅ 已实现 | `gateway.rs::admin_ai_entry`，鉴权后跳转，管理员模式 | +| `/user/ai` 路由与入口 | ✅ 已实现 | `gateway.rs::user_ai_entry`，鉴权后跳转，用户模式 | +| 账户菜单独立 AI 管理入口 | ✅ 已实现 | `sidebar-workspace-runtime.js` `mnote-account-ai-management`，按角色跳 `/admin/ai` 或 `/user/ai` | +| AI 管理页面 SSR | ✅ 已实现 | `ssr/pages/ai_admin.rs::AiManagementPage` — 对齐 OpenHub Admin 左侧分页、白色 Card 壳、表格、抽屉与分组权限面板；管理 Overview、模型、服务、用量、工具、Skills/MCP、目录、知识库、会话与监控 | +| Access Scopes 只读展示 | ✅ 已验证 | 页面脚本只 GET access-scopes 数据，无 POST/PUT/DELETE，无写表单 | +| Sessions & Receipts 区域 | ✅ 已接真实数据 | 展示 Pi session、tool receipt、deny reason、diff summary、patch 数量 | +| `/admin/ai` 管理写操作（provider/model 编辑等） | ✅ 已实现 | `GET/PUT /api/ai-admin/settings`；模型配置浏览器保存与刷新持久化通过 | +| `/user/ai` 用户设置 | ❌ 未实现 | 当前 `/user/ai` 复用 `AiManagementPage` 用户模式，仅有只读视图；逐用户模型/工具/Skill/MCP override 已在管理员用户抽屉完成 | + +### P4: Skills / MCP / Tools / LightRAG 管理 — 部分完成 + +- Skills、MCP 与工具策略已通过原子管理 API 和 SSR 管理 UI 写入 `ai_policies.model_policy_json` +- MCP 强制 `facadeOnly=true`、`sandbox=true`，secret 仅接受 `env://` / `secret://` +- MNote-owned tools 已支持 allow/ask/deny +- LightRAG source/index/status 管理 UI 未实现 +- provider/skill/MCP 专用规范化表未实现；出现独立查询、授权或生命周期需求时再迁移 + +### OpenHub / Pi Lab 独立入口状态 + +| 项 | 状态 | +|---|---| +| OpenHub `/page-ai/openhub/ai` 未删除 | ✅ | +| OpenHub `/page-ai/openhub/admin` 未删除 | ✅ | +| OpenHub status API 未删除 | ✅ | +| Pi Lab shell `/page-ai/pi` 未删除 | ✅ | +| Pi Lab start/send/abort/events 路由未删除 | ✅ | + +### 验证命令占位 + +```bash +# 静态 smoke（只读代码审计） +node scripts/task-ai-management-control-plane-static-smoke.js + +# 运行时 smoke（需要 mnote-web 运行中） +# curl -s http://localhost:3000/api/ai-settings/effective | jq '.sourceOfTruth' +# curl -s http://localhost:3000/api/ai-settings/access-scopes | jq '.sourceOfTruth' +# curl -s http://localhost:3000/api/ai-admin/access-scopes | jq '.sourceOfTruth' +# curl -s -o /dev/null -w '%{http_code}' http://localhost:3000/admin/ai +# curl -s -o /dev/null -w '%{http_code}' http://localhost:3000/user/ai +# curl -s http://localhost:3000/api/page-ai/pi/sessions | jq '.schema' +# curl -s http://localhost:3000/api/ai-settings/receipts | jq '{receiptCount, patchCount}' +``` + +### 运行时与浏览器证据 + +- 隔离运行端口：`127.0.0.1:33171` +- `task-pi-lab-mock-api-smoke.js`：通过 +- `task-pi-lab-browser-smoke.js`：通过 +- Pi Lab 截图：`tmp/7-71-pi-lab-browser-final.png` +- AI 管理页截图：`tmp/7-71-ai-admin-final.png` +- 模型写管理截图：`tmp/7-71-ai-admin-openhub-like-ui-final/models.png` +- Skills/MCP 写管理截图：`tmp/7-71-ai-admin-openhub-like-ui-final/skills-mcp.png` +- OpenHub-like 逐用户配置抽屉截图：`tmp/7-71-ai-admin-openhub-like-ui-final/users.png` +- 管理页实测摘要：会话 1、回执 3、文件补丁 1 +- OpenHub 仍为默认 Page AI，Pi Lab 继续使用独立按钮、独立抽屉与独立 session +- `mnote-e2e` 已通过 control-plane `role=admin` 验证管理员访问和写入；浏览器 smoke 使用 dev seed 仅为临时验收账号准备，不写第二套授权目录 + + +### P4: Skills / MCP / Tools 管理 — 验收结果 + +| 项 | 状态 | 证据 | +|---|---|---| +| admin 原子策略 GET/PUT | ✅ 通过 | `/api/ai-admin/settings`，统一保存模型、工具、Skills、MCP | +| 浏览器保存与刷新持久化 | ✅ 通过 | `scripts/task-ai-management-browser-smoke.js` | +| secretRef-only 检查 | ✅ 通过 (3 项) | Section 9: 无硬编码 api_key/secret，仅 env 引用 | +| allowed roots 不可写检查 | ✅ 通过 (4 项) | Section 10: 无写路由、无写函数、无写表单 | +| MCP facade-only 检查 | ✅ 通过 (3 项) | Section 11: Pi 仅暴露 mnote. 工具，MCP 经 facade 管控 | + +### P5: OpenHub 式逐用户 AI 配置 — 已完成 + +- OpenHub Admin 的真实用户管理入口为用户表格 + 模型/工具/Skill/目录权限操作；MCP 仅展示用户工作区 `.opencode/mcp` 文件，不存在 Admin per-user MCP 策略。 +- MNote 新增用户列表与逐用户 AI 策略 API，用户 override 继续落 `ai_policies(user_id, workspace_id=NULL)`。 +- 当前 `ai_policies` 没有系统全局行，因此暂以 `MNOTE_ADMIN_USER_IDS` 首个用户作为全局策略 owner；迁移到规范化 policy 表时移除此兼容约定。 +- 本轮已把 MNote `/admin/ai` 用户配置抽屉改成 OpenHub-like 体验：模型按 provider 分组、工具按 risk level 分组、Skill/MCP 使用启停开关、目录权限只读并跳转统一授权管理页。 +- effective 合并规则： + - 模型只能从管理员 allowed models 中选择； + - 工具只能降权，不能从 deny/ask 提升到 allow； + - Skill/MCP 只能关闭或启用全局已允许项； + - MCP 始终保持 facade-only + sandbox； + - allowed roots 完全不参与该合并，继续只读 `directory_grants`。 +- 浏览器截图：`tmp/7-71-ai-admin-openhub-like-ui-final/users.png`。 +- 浏览器 smoke 同时以普通用户 `ai-user` 登录，确认 effective API 不返回被禁用模型和 Skill。 + +### 本轮 smoke 结果 + +静态 smoke：**47 通过，0 失败**。浏览器 smoke 验证模型、工具、Skills/MCP 保存、OpenHub Admin 独立入口保留、OpenHub-like 用户抽屉、逐用户 override、刷新持久化及 effective 投影全部通过。 + +``` +$ node scripts/task-ai-management-control-plane-static-smoke.js +通过: 47 失败: 0 跳过: 0 + +$ MNOTE_AI_ADMIN_OUTPUT_DIR=tmp/7-71-ai-admin-openhub-like-ui-final \ + node scripts/task-ai-management-browser-smoke.js +ok: true +``` + +### 后续范围 + +- `/user/ai` 用户模型/Skills/MCP 偏好 +- LightRAG source/index/status 写管理 +- provider/skill/MCP 专用规范化表迁移 diff --git a/rust/Cargo.lock b/rust/Cargo.lock index cc052849..1529d88b 100644 --- a/rust/Cargo.lock +++ b/rust/Cargo.lock @@ -40,7 +40,7 @@ dependencies = [ "cfg-if", "once_cell", "version_check", - "zerocopy 0.8.48", + "zerocopy 0.8.52", ] [[package]] @@ -130,9 +130,9 @@ dependencies = [ [[package]] name = "anyhow" -version = "1.0.102" +version = "1.0.103" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c" +checksum = "2a4385e2e34eb35d6b3efe798b9eb88096925d87726c0798709bf56d9ed84af3" [[package]] name = "arbitrary" @@ -231,9 +231,9 @@ dependencies = [ [[package]] name = "autocfg" -version = "1.5.0" +version = "1.5.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8" +checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53" [[package]] name = "axum" @@ -274,10 +274,10 @@ dependencies = [ "bytes", "form_urlencoded", "futures-util", - "http 1.4.0", + "http 1.4.2", "http-body 1.0.1", "http-body-util", - "hyper 1.9.0", + "hyper 1.10.1", "hyper-util", "itoa", "matchit 0.8.4", @@ -325,7 +325,7 @@ checksum = "08c78f31d7b1291f7ee735c1c6780ccde7785daae9a9206026862dab7d8792d1" dependencies = [ "bytes", "futures-core", - "http 1.4.0", + "http 1.4.2", "http-body 1.0.1", "http-body-util", "mime", @@ -369,7 +369,7 @@ version = "0.66.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f2b84e06fc203107bfbad243f4aba2af864eb7db3b1cf46ea0a023b0b433d2a7" dependencies = [ - "bitflags 2.11.1", + "bitflags 2.13.0", "cexpr", "clang-sys", "lazy_static", @@ -381,7 +381,7 @@ dependencies = [ "quote", "regex", "rustc-hash 1.1.0", - "shlex", + "shlex 1.3.0", "syn", "which", ] @@ -394,9 +394,9 @@ checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a" [[package]] name = "bitflags" -version = "2.11.1" +version = "2.13.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3" +checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8" [[package]] name = "block-buffer" @@ -433,9 +433,9 @@ dependencies = [ [[package]] name = "bumpalo" -version = "3.20.2" +version = "3.20.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5d20789868f4b01b2f2caec9f5c4e0213b41e3e5702a50157d699ae31ced2fcb" +checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649" [[package]] name = "byteorder" @@ -445,9 +445,9 @@ checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b" [[package]] name = "bytes" -version = "1.11.1" +version = "1.12.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33" +checksum = "8ae3f5d315924270530207e2a68396c3cc547f6dca3fbdca317cfb1a51edb593" dependencies = [ "serde", ] @@ -473,9 +473,9 @@ dependencies = [ [[package]] name = "camino" -version = "1.2.2" +version = "1.2.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e629a66d692cb9ff1a1c664e41771b3dcaf961985a9774c0eb0bd1b51cf60a48" +checksum = "5f2d30e4173c4026932d51d31d6b0613b1fd3014bf3f9f8943d4ba139c437ba0" [[package]] name = "caseless" @@ -497,14 +497,14 @@ dependencies = [ [[package]] name = "cc" -version = "1.2.60" +version = "1.2.65" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "43c5703da9466b66a946814e1adf53ea2c90f10063b86290cc9eb67ce3478a20" +checksum = "e228eec9be7c17ccb640b59b36a5cd805ea2a564a4c5e162c2f659fea30d3b96" dependencies = [ "find-msvc-tools", "jobserver", "libc", - "shlex", + "shlex 2.0.1", ] [[package]] @@ -530,9 +530,9 @@ checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724" [[package]] name = "chrono" -version = "0.4.44" +version = "0.4.45" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c673075a2e0e5f4a1dde27ce9dee1ea4558c7ffe648f576438a20ca1d2acc4b0" +checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327" dependencies = [ "iana-time-zone", "js-sys", @@ -565,9 +565,9 @@ dependencies = [ [[package]] name = "clap" -version = "4.6.0" +version = "4.6.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b193af5b67834b676abd72466a96c1024e6a6ad978a1f484bd90b85c94041351" +checksum = "1ddb117e43bbf7dacf0a4190fef4d345b9bad68dfc649cb349e7d17d28428e51" dependencies = [ "clap_builder", "clap_derive", @@ -587,9 +587,9 @@ dependencies = [ [[package]] name = "clap_derive" -version = "4.6.0" +version = "4.6.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "1110bd8a634a1ab8cb04345d8d878267d57c3cf1b38d91b71af6686408bbca6a" +checksum = "f2ce8604710f6733aa641a2b3731eaa1e8b3d9973d5e3565da11800813f997a9" dependencies = [ "heck", "proc-macro2", @@ -647,7 +647,7 @@ dependencies = [ "jetscii", "phf 0.13.1", "phf_codegen 0.13.1", - "rustc-hash 2.1.2", + "rustc-hash 2.1.3", "smallvec", "typed-arena", ] @@ -663,9 +663,9 @@ dependencies = [ [[package]] name = "config" -version = "0.15.22" +version = "0.15.25" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8e68cfe19cd7d23ffde002c24ffa5cda73931913ef394d5eaaa32037dc940c0c" +checksum = "b85f248a4de22d204ceabc6299d89d2c70fbd7f09fea53c06c852369652d8139" dependencies = [ "convert_case 0.6.0", "pathdiff", @@ -845,9 +845,9 @@ dependencies = [ [[package]] name = "data-encoding" -version = "2.10.0" +version = "2.11.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d7a1e2f27636f116493b8b860f5546edb47c8d8f8ea73e1d2a20be88e28d1fea" +checksum = "a4ae5f15dda3c708c0ade84bfee31ccab44a3da4f88015ed22f63732abe300c8" [[package]] name = "deflate64" @@ -860,9 +860,6 @@ name = "deranged" version = "0.5.8" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c" -dependencies = [ - "powerfmt", -] [[package]] name = "derive-where" @@ -899,9 +896,9 @@ dependencies = [ [[package]] name = "displaydoc" -version = "0.2.5" +version = "0.2.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "97369cbbc041bc366949bc74d34658d6cda5621039731c6310521892a3a20ae0" +checksum = "1ac70aa55017e108007fbaf5aa0f54b021c98f92ff8af59d42eda9da96e3dd4f" dependencies = [ "proc-macro2", "quote", @@ -916,9 +913,9 @@ checksum = "669a445ee724c5c69b1b06fe0b63e70a1c84bc9bb7d9696cd4f4e3ec45050408" [[package]] name = "either" -version = "1.15.0" +version = "1.16.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719" +checksum = "91622ff5e7162018101f2fea40d6ebf4a78bbe5a49736a2020649edf9693679e" [[package]] name = "either_of" @@ -1198,15 +1195,13 @@ dependencies = [ [[package]] name = "getrandom" -version = "0.4.2" +version = "0.4.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0de51e6874e94e7bf76d726fc5d13ba782deca734ff60d5bb2fb2607c7406555" +checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099" dependencies = [ "cfg-if", "libc", "r-efi 6.0.0", - "wasip2", - "wasip3", ] [[package]] @@ -1225,7 +1220,7 @@ dependencies = [ "futures-core", "futures-sink", "gloo-utils", - "http 1.4.0", + "http 1.4.2", "js-sys", "pin-project", "serde", @@ -1301,9 +1296,9 @@ dependencies = [ [[package]] name = "hashbrown" -version = "0.17.0" +version = "0.17.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4f467dd6dccf739c208452f8014c75c18bb8301b050ad1cfb27153803edb0f51" +checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a" [[package]] name = "hashlink" @@ -1375,9 +1370,9 @@ dependencies = [ [[package]] name = "http" -version = "1.4.0" +version = "1.4.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e3ba2a386d7f85a81f119ad7498ebe444d2e22c2af0b86b069416ace48b3311a" +checksum = "6970f50e31d6fc17d3fa27329444bfa74e196cf62e95052a3f6fee181dba6425" dependencies = [ "bytes", "itoa", @@ -1401,7 +1396,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1efedce1fb8e6913f23e0c92de8e62cd5b772a67e7b3946df930a62566c93184" dependencies = [ "bytes", - "http 1.4.0", + "http 1.4.2", ] [[package]] @@ -1412,7 +1407,7 @@ checksum = "b021d93e26becf5dc7e1b75b1bed1fd93124b374ceb73f43d4d4eafec896a64a" dependencies = [ "bytes", "futures-core", - "http 1.4.0", + "http 1.4.2", "http-body 1.0.1", "pin-project-lite", ] @@ -1437,13 +1432,12 @@ checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9" [[package]] name = "hydration_context" -version = "0.3.0" +version = "0.3.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e8714ae4adeaa846d838f380fbd72f049197de629948f91bf045329e0cf0a283" +checksum = "7bbbeb23ee808258cef2c5585ff0dc8e41da21a8dde943f6b290da153a042a96" dependencies = [ "futures", "js-sys", - "once_cell", "or_poisoned", "pin-project-lite", "serde", @@ -1477,15 +1471,15 @@ dependencies = [ [[package]] name = "hyper" -version = "1.9.0" +version = "1.10.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "6299f016b246a94207e63da54dbe807655bf9e00044f73ded42c3ac5305fbcca" +checksum = "55281c53a1894c864990125767da440a4e630446785086f52523b20033b74498" dependencies = [ "atomic-waker", "bytes", "futures-channel", "futures-core", - "http 1.4.0", + "http 1.4.2", "http-body 1.0.1", "httparse", "httpdate", @@ -1520,14 +1514,14 @@ version = "0.27.9" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "33ca68d021ef39cf6463ab54c1d0f5daf03377b70561305bb89a8f83aab66e0f" dependencies = [ - "http 1.4.0", - "hyper 1.9.0", + "http 1.4.2", + "hyper 1.10.1", "hyper-util", - "rustls 0.23.38", + "rustls 0.23.41", "tokio", "tokio-rustls 0.26.4", "tower-service", - "webpki-roots 1.0.6", + "webpki-roots 1.0.8", ] [[package]] @@ -1552,14 +1546,14 @@ dependencies = [ "bytes", "futures-channel", "futures-util", - "http 1.4.0", + "http 1.4.2", "http-body 1.0.1", - "hyper 1.9.0", + "hyper 1.10.1", "ipnet", "libc", "percent-encoding", "pin-project-lite", - "socket2 0.6.3", + "socket2 0.6.4", "tokio", "tower-service", "tracing", @@ -1671,12 +1665,6 @@ dependencies = [ "zerovec", ] -[[package]] -name = "id-arena" -version = "2.3.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3d3067d79b975e8844ca9eb072e16b31c3c1c36928edf9c6789548c524d0d954" - [[package]] name = "idna" version = "1.1.0" @@ -1690,9 +1678,9 @@ dependencies = [ [[package]] name = "idna_adapter" -version = "1.2.1" +version = "1.2.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3acae9609540aa318d1bc588455225fb2085b9ed0c4f6bd0d9d5bcd86f1a0344" +checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714" dependencies = [ "icu_normalizer", "icu_properties", @@ -1726,27 +1714,25 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9" dependencies = [ "equivalent", - "hashbrown 0.17.0", - "serde", - "serde_core", + "hashbrown 0.17.1", ] [[package]] name = "inotify" -version = "0.11.1" +version = "0.11.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "bd5b3eaf1a28b758ac0faa5a4254e8ab2705605496f1b1f3fbbc3988ad73d199" +checksum = "533e68a5842e734946fe159fb03fc9bbbb254f590dd0d8ad321ae5ff7beca2c1" dependencies = [ - "bitflags 2.11.1", + "bitflags 2.13.0", "inotify-sys", "libc", ] [[package]] name = "inotify-sys" -version = "0.1.5" +version = "0.1.7" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e05c02b5e89bff3b946cedeca278abc628fe811e604f027c45a8aa3cf793d0eb" +checksum = "9ea94e891b3606826e9c998be69ddca42247dad8ad50b1649a5cb7e1c9ae06fd" dependencies = [ "libc", ] @@ -1782,16 +1768,6 @@ version = "2.12.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d98f6fed1fde3f8c21bc40a1abb88dd75e67924f9cffc3ef95607bad8017f8e2" -[[package]] -name = "iri-string" -version = "0.7.12" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "25e659a4bb38e810ebc252e53b5814ff908a8c58c2a9ce2fae1bbec24cbf4e20" -dependencies = [ - "memchr", - "serde", -] - [[package]] name = "is_terminal_polyfill" version = "1.70.2" @@ -1840,13 +1816,12 @@ dependencies = [ [[package]] name = "js-sys" -version = "0.3.95" +version = "0.3.103" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2964e92d1d9dc3364cae4d718d93f227e3abb088e747d92e0395bfdedf1c12ca" +checksum = "53b44bfcdb3f8d5837a46dae1ca9660a837176eee74a28b229bc626816589102" dependencies = [ "cfg-if", "futures-util", - "once_cell", "wasm-bindgen", ] @@ -1867,9 +1842,9 @@ checksum = "a4933f3f57a8e9d9da04db23fb153356ecaf00cbd14aee46279c33dc80925c37" [[package]] name = "kqueue" -version = "1.1.1" +version = "1.2.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "eac30106d7dce88daf4a3fcb4879ea939476d5074a9b7ddd0fb97fa4bed5596a" +checksum = "273c0752728918e0ac4976f2b275b6fefb9ecd400585dec929419f3844cd87b5" dependencies = [ "kqueue-sys", "libc", @@ -1877,11 +1852,11 @@ dependencies = [ [[package]] name = "kqueue-sys" -version = "1.1.0" +version = "1.1.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a7b65860415f949f23fa882e669f2dbd4a0f0eeb1acdd56790b30494afd7da2f" +checksum = "07293a4e297ac234359b510362495713f75ea345d5307140414f20c69ffeb087" dependencies = [ - "bitflags 2.11.1", + "bitflags 2.13.0", "libc", ] @@ -1897,17 +1872,11 @@ version = "1.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "830d08ce1d1d941e6b30645f1a0eb5643013d835ce3779a5fc208261dbe10f55" -[[package]] -name = "leb128fmt" -version = "0.1.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2" - [[package]] name = "leptos" -version = "0.8.19" +version = "0.8.20" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "efa3982e7fe36c1de68f91f3c9083124f389a975523881f3d7e3363362feda41" +checksum = "705e2951f3688e0c4f66bbb7a2702282782dcee716971dbd6209c2619d272479" dependencies = [ "any_spawner", "cfg-if", @@ -1923,7 +1892,7 @@ dependencies = [ "or_poisoned", "paste", "reactive_graph", - "rustc-hash 2.1.2", + "rustc-hash 2.1.3", "rustc_version", "send_wrapper", "serde", @@ -1990,9 +1959,9 @@ dependencies = [ [[package]] name = "leptos_macro" -version = "0.8.16" +version = "0.8.17" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9360df573fb57582384a8b7640a3de94ce6501d49be3b69f637cf11a42da484b" +checksum = "96de6e8da9d4f1a7b74b447b317d590ebabb38709f588f7ee20564b773ccbcce" dependencies = [ "attribute-derive", "cfg-if", @@ -2034,9 +2003,9 @@ dependencies = [ [[package]] name = "libc" -version = "0.2.185" +version = "0.2.186" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "52ff2c0fe9bc6cb6b14a0592c2ff4fa9ceb83eea9db979b0487cd054946a2b8f" +checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66" [[package]] name = "libloading" @@ -2059,7 +2028,7 @@ dependencies = [ "async-trait", "base64 0.21.7", "bincode", - "bitflags 2.11.1", + "bitflags 2.13.0", "bytes", "chrono", "crc32fast", @@ -2118,7 +2087,7 @@ version = "0.10.0-pre.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "685f4a6f05002d892150c73f4f3d0b3ad346d0bbf44f5b6f55a8ea94b0cd4477" dependencies = [ - "bitflags 2.11.1", + "bitflags 2.13.0", "fallible-iterator 0.2.0", "fallible-streaming-iterator", "hashlink 0.8.4", @@ -2132,7 +2101,7 @@ version = "0.13.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "15a90128c708356af8f7d767c9ac2946692c9112b4f74f07b99a01a60680e413" dependencies = [ - "bitflags 2.11.1", + "bitflags 2.13.0", "cc", "fallible-iterator 0.3.0", "indexmap 2.14.0", @@ -2218,9 +2187,9 @@ dependencies = [ [[package]] name = "log" -version = "0.4.29" +version = "0.4.33" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897" +checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad" [[package]] name = "lru-slab" @@ -2286,9 +2255,9 @@ checksum = "47e1ffaa40ddd1f3ed91f717a33c8c0ee23fff369e3aa8772b9605cc1d22f4c3" [[package]] name = "memchr" -version = "2.8.0" +version = "2.8.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79" +checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4" [[package]] name = "mime" @@ -2324,9 +2293,9 @@ dependencies = [ [[package]] name = "mio" -version = "1.2.0" +version = "1.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "50b7e5b27aa02a74bac8c3f23f448f8d87ff11f92d3aac1a6ed369ee08cc56c1" +checksum = "02bd0af71c67b473010cbbc60715ee815645a4dc942899111f494b4b737d6fda" dependencies = [ "libc", "log", @@ -2365,7 +2334,7 @@ dependencies = [ "control-plane", "core-protocol", "futures-util", - "hyper 1.9.0", + "hyper 1.10.1", "hyper-util", "leptos", "mnote-editor-core", @@ -2379,7 +2348,7 @@ dependencies = [ "tokio-stream", "tokio-tungstenite", "tower 0.5.3", - "tower-http 0.6.8", + "tower-http 0.6.11", "tracing", "tracing-subscriber", "uuid", @@ -2395,7 +2364,7 @@ dependencies = [ "bytes", "encoding_rs", "futures-util", - "http 1.4.0", + "http 1.4.2", "httparse", "memchr", "mime", @@ -2425,7 +2394,7 @@ version = "8.2.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "4d3d07927151ff8575b7087f245456e549fea62edf0ec4e565a5ee50c8402bc3" dependencies = [ - "bitflags 2.11.1", + "bitflags 2.13.0", "fsevent-sys", "inotify", "kqueue", @@ -2443,7 +2412,7 @@ version = "2.1.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "42b8cfee0e339a0337359f3c88165702ac6e600dc01c0cc9579a92d62b08477a" dependencies = [ - "bitflags 2.11.1", + "bitflags 2.13.0", ] [[package]] @@ -2457,9 +2426,9 @@ dependencies = [ [[package]] name = "num-conv" -version = "0.2.1" +version = "0.2.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c6673768db2d862beb9b39a78fdcb1a69439615d5794a1be50caa9bc92c81967" +checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441" [[package]] name = "num-traits" @@ -2656,18 +2625,18 @@ dependencies = [ [[package]] name = "pin-project" -version = "1.1.11" +version = "1.1.13" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f1749c7ed4bcaf4c3d0a3efc28538844fb29bcdd7d2b67b2be7e20ba861ff517" +checksum = "2466b2336ed02bcdca6b294417127b90ec92038d1d5c4fbeac971a922e0e0924" dependencies = [ "pin-project-internal", ] [[package]] name = "pin-project-internal" -version = "1.1.11" +version = "1.1.13" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d9b20ed30f105399776b9c883e68e536ef602a16ae6f596d2c473591d6ad64c6" +checksum = "c96395f0a926bc13b1c17622aaddda1ecb55d49c8f1bf9777e4d877800a43f8b" dependencies = [ "proc-macro2", "quote", @@ -2707,7 +2676,7 @@ version = "0.2.21" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9" dependencies = [ - "zerocopy 0.8.48", + "zerocopy 0.8.52", ] [[package]] @@ -2800,18 +2769,18 @@ dependencies = [ [[package]] name = "quinn" -version = "0.11.9" +version = "0.11.11" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b9e20a958963c291dc322d98411f541009df2ced7b5a4f2bd52337638cfccf20" +checksum = "0c1a41e437b6bbd489372cd4971de128e85c855f56c57f283d20ff016cf7c0a8" dependencies = [ "bytes", "cfg_aliases", "pin-project-lite", "quinn-proto", "quinn-udp", - "rustc-hash 2.1.2", - "rustls 0.23.38", - "socket2 0.6.3", + "rustc-hash 2.1.3", + "rustls 0.23.41", + "socket2 0.6.4", "thiserror 2.0.18", "tokio", "tracing", @@ -2820,17 +2789,17 @@ dependencies = [ [[package]] name = "quinn-proto" -version = "0.11.14" +version = "0.11.15" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "434b42fec591c96ef50e21e886936e66d3cc3f737104fdb9b737c40ffb94c098" +checksum = "4fcb935c5bec503c2f0e306bdd3e58bb9029dcb14fa8d9ac76e3a5256ac0763e" dependencies = [ "bytes", "getrandom 0.3.4", "lru-slab", "rand 0.9.4", "ring", - "rustc-hash 2.1.2", - "rustls 0.23.38", + "rustc-hash 2.1.3", + "rustls 0.23.41", "rustls-pki-types", "slab", "thiserror 2.0.18", @@ -2848,16 +2817,16 @@ dependencies = [ "cfg_aliases", "libc", "once_cell", - "socket2 0.6.3", + "socket2 0.6.4", "tracing", "windows-sys 0.60.2", ] [[package]] name = "quote" -version = "1.0.45" +version = "1.0.46" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924" +checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368" dependencies = [ "proc-macro2", ] @@ -2970,7 +2939,7 @@ dependencies = [ "or_poisoned", "paste", "pin-project-lite", - "rustc-hash 2.1.2", + "rustc-hash 2.1.3", "rustc_version", "send_wrapper", "serde", @@ -2992,15 +2961,15 @@ dependencies = [ "paste", "reactive_graph", "reactive_stores_macro", - "rustc-hash 2.1.2", + "rustc-hash 2.1.3", "send_wrapper", ] [[package]] name = "reactive_stores_macro" -version = "0.4.2" +version = "0.4.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e5d8e790a5ae5ddf9b7fa380c728375b06858e0cca7d063a73b3408320c523e1" +checksum = "68072edd607edd30b9ebf57d984ba45d8ab8809e598d0f6046278373fb76a5a0" dependencies = [ "convert_case 0.11.0", "proc-macro-error2", @@ -3015,14 +2984,14 @@ version = "0.5.18" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d" dependencies = [ - "bitflags 2.11.1", + "bitflags 2.13.0", ] [[package]] name = "regex" -version = "1.12.3" +version = "1.12.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e10754a14b9137dd7b1e3e5b0493cc9171fdd105e0ab477f51b72e7f3ac0e276" +checksum = "f1292b7759ae1cb9ec195452d1390a074f0cd8541ab7a5a8c31cd6db45d4a6ba" dependencies = [ "aho-corasick", "memchr", @@ -3043,9 +3012,9 @@ dependencies = [ [[package]] name = "regex-syntax" -version = "0.8.10" +version = "0.8.11" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "dc897dd8d9e8bd1ed8cdad82b5966c3e0ecae09fb1907d58efaa013543185d0a" +checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4" [[package]] name = "reqwest" @@ -3058,10 +3027,10 @@ dependencies = [ "futures-channel", "futures-core", "futures-util", - "http 1.4.0", + "http 1.4.2", "http-body 1.0.1", "http-body-util", - "hyper 1.9.0", + "hyper 1.10.1", "hyper-rustls 0.27.9", "hyper-util", "js-sys", @@ -3070,7 +3039,7 @@ dependencies = [ "percent-encoding", "pin-project-lite", "quinn", - "rustls 0.23.38", + "rustls 0.23.41", "rustls-pki-types", "serde", "serde_json", @@ -3080,14 +3049,14 @@ dependencies = [ "tokio-rustls 0.26.4", "tokio-util", "tower 0.5.3", - "tower-http 0.6.8", + "tower-http 0.6.11", "tower-service", "url", "wasm-bindgen", "wasm-bindgen-futures", "wasm-streams 0.4.2", "web-sys", - "webpki-roots 1.0.6", + "webpki-roots 1.0.8", ] [[package]] @@ -3125,7 +3094,7 @@ version = "0.34.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "37e34486da88d8e051c7c0e23c3f15fd806ea8546260aa2fec247e97242ec143" dependencies = [ - "bitflags 2.11.1", + "bitflags 2.13.0", "fallible-iterator 0.3.0", "fallible-streaming-iterator", "hashlink 0.10.0", @@ -3141,9 +3110,9 @@ checksum = "08d43f7aa6b08d49f382cde6a7982047c3426db949b1424bc4b7ec9ae12c6ce2" [[package]] name = "rustc-hash" -version = "2.1.2" +version = "2.1.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "94300abf3f1ae2e2b8ffb7b58043de3d399c73fa6f4b73826402a5c457614dbe" +checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d" [[package]] name = "rustc_version" @@ -3160,11 +3129,11 @@ version = "0.38.44" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "fdb5bc1ae2baa591800df16c9ca78619bf65c0488b41b96ccec5d11220d8c154" dependencies = [ - "bitflags 2.11.1", + "bitflags 2.13.0", "errno", "libc", "linux-raw-sys", - "windows-sys 0.52.0", + "windows-sys 0.59.0", ] [[package]] @@ -3183,14 +3152,14 @@ dependencies = [ [[package]] name = "rustls" -version = "0.23.38" +version = "0.23.41" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "69f9466fb2c14ea04357e91413efb882e2a6d4a406e625449bc0a5d360d53a21" +checksum = "6b92b125634d9b795e7beca796cc790df15a7fb38323bf3196fda83292d06b1f" dependencies = [ "once_cell", "ring", "rustls-pki-types", - "rustls-webpki 0.103.12", + "rustls-webpki 0.103.13", "subtle", "zeroize", ] @@ -3219,9 +3188,9 @@ dependencies = [ [[package]] name = "rustls-pki-types" -version = "1.14.0" +version = "1.15.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "be040f8b0a225e40375822a563fa9524378b9d63112f53e19ffff34df5d33fdd" +checksum = "764899a24af3980067ee14bc143654f297b22eaebfe3c7b6b211920a5a59b046" dependencies = [ "web-time", "zeroize", @@ -3240,9 +3209,9 @@ dependencies = [ [[package]] name = "rustls-webpki" -version = "0.103.12" +version = "0.103.13" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8279bb85272c9f10811ae6a6c547ff594d6a7f3c6c6b02ee9726d1d0dcfcdd06" +checksum = "61c429a8649f110dddef65e2a5ad240f747e85f7758a6bccc7e5777bd33f756e" dependencies = [ "ring", "rustls-pki-types", @@ -3291,7 +3260,7 @@ version = "2.11.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "897b2245f0b511c87893af39b033e5ca9cce68824c4d7e7630b5a1d339658d02" dependencies = [ - "bitflags 2.11.1", + "bitflags 2.13.0", "core-foundation", "core-foundation-sys", "libc", @@ -3366,9 +3335,9 @@ dependencies = [ [[package]] name = "serde_json" -version = "1.0.149" +version = "1.0.150" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86" +checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9" dependencies = [ "itoa", "memchr", @@ -3422,9 +3391,9 @@ dependencies = [ [[package]] name = "server_fn" -version = "0.8.12" +version = "0.8.13" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5d60e4c1dfccd91fe0990141f69f1d5cf5679797ad53aa1b45e5bd658eb119f0" +checksum = "be8559dd05af1b5b7e363a150616589d5a88af5187273f7f331ba0dae8922812" dependencies = [ "base64 0.22.1", "bytes", @@ -3432,7 +3401,7 @@ dependencies = [ "const_format", "futures", "gloo-net", - "http 1.4.0", + "http 1.4.2", "inventory", "js-sys", "or_poisoned", @@ -3516,6 +3485,12 @@ version = "1.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64" +[[package]] +name = "shlex" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba" + [[package]] name = "signal-hook-registry" version = "1.4.8" @@ -3555,9 +3530,9 @@ dependencies = [ [[package]] name = "smallvec" -version = "1.15.1" +version = "1.15.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03" +checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90" [[package]] name = "socket2" @@ -3571,9 +3546,9 @@ dependencies = [ [[package]] name = "socket2" -version = "0.6.3" +version = "0.6.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3a766e1110788c36f4fa1c2b71b387a7815aa65f88ce0229841826633d93723e" +checksum = "52d1cfed4120b4d927bf7c0f86d2087a4a7d6027c906d9f9d525a80573b9be51" dependencies = [ "libc", "windows-sys 0.61.2", @@ -3605,9 +3580,9 @@ checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292" [[package]] name = "syn" -version = "2.0.117" +version = "2.0.118" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99" +checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422" dependencies = [ "proc-macro2", "quote", @@ -3654,9 +3629,9 @@ dependencies = [ [[package]] name = "tachys" -version = "0.2.15" +version = "0.2.18" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2989c94c59db8497727875aa561d4d0daa3cc79b5774d5ced48263f7091beff1" +checksum = "a92ba81187437cc5df4281f2326a2e13cc81e8f96448292d1112388e2025ca66" dependencies = [ "any_spawner", "async-trait", @@ -3675,7 +3650,7 @@ dependencies = [ "paste", "reactive_graph", "reactive_stores", - "rustc-hash 2.1.2", + "rustc-hash 2.1.3", "rustc_version", "send_wrapper", "slotmap", @@ -3744,12 +3719,11 @@ dependencies = [ [[package]] name = "time" -version = "0.3.47" +version = "0.3.53" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "743bd48c283afc0388f9b8827b976905fb217ad9e647fae3a379a9283c4def2c" +checksum = "18dfaaeddcb932337b5e7866ee7d0ce9b76d2fd092997146f187ec09b4558a50" dependencies = [ "deranged", - "itoa", "libc", "num-conv", "num_threads", @@ -3761,15 +3735,15 @@ dependencies = [ [[package]] name = "time-core" -version = "0.1.8" +version = "0.1.9" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7694e1cfe791f8d31026952abf09c69ca6f6fa4e1a1229e18988f06a04a12dca" +checksum = "9e1c906769ad99c88eaa54e728060edef082f8e358ff32030cb7c7d315e81109" [[package]] name = "time-macros" -version = "0.2.27" +version = "0.2.31" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2e70e4c5a0e0a8a4823ad65dfe1a6930e4f4d756dcd9dd7939022b5e8c501215" +checksum = "c431b87111666e491a90baa837f914fb45cd5dc3c268591b0220ff5057f2085f" dependencies = [ "num-conv", "time-core", @@ -3802,9 +3776,9 @@ checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20" [[package]] name = "tokio" -version = "1.52.0" +version = "1.52.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a91135f59b1cbf38c91e73cf3386fca9bb77915c45ce2771460c9d92f0f3d776" +checksum = "8fc7f01b389ac15039e4dc9531aa973a135d7a4135281b12d7c1bc79fd57fffe" dependencies = [ "bytes", "libc", @@ -3812,7 +3786,7 @@ dependencies = [ "parking_lot", "pin-project-lite", "signal-hook-registry", - "socket2 0.6.3", + "socket2 0.6.4", "tokio-macros", "windows-sys 0.61.2", ] @@ -3855,7 +3829,7 @@ version = "0.26.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1729aa945f29d91ba541258c8df89027d5792d85a8841fb65e8bf0f4ede4ef61" dependencies = [ - "rustls 0.23.38", + "rustls 0.23.41", "tokio", ] @@ -4016,7 +3990,7 @@ version = "0.4.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "61c5bb1d698276a2443e5ecfabc1008bf15a36c12e6a7176e7bf089ea9131140" dependencies = [ - "bitflags 2.11.1", + "bitflags 2.13.0", "bytes", "futures-core", "futures-util", @@ -4032,21 +4006,21 @@ dependencies = [ [[package]] name = "tower-http" -version = "0.6.8" +version = "0.6.11" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d4e6559d53cc268e5031cd8429d05415bc4cb4aefc4aa5d6cc35fbf5b924a1f8" +checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840" dependencies = [ - "bitflags 2.11.1", + "bitflags 2.13.0", "bytes", "futures-util", - "http 1.4.0", + "http 1.4.2", "http-body 1.0.1", - "iri-string", "pin-project-lite", "tower 0.5.3", "tower-layer", "tower-service", "tracing", + "url", ] [[package]] @@ -4144,7 +4118,7 @@ checksum = "6c01152af293afb9c7c2a57e4b559c5620b421f6d133261c60dd2d0cdb38e6b8" dependencies = [ "bytes", "data-encoding", - "http 1.4.0", + "http 1.4.2", "httparse", "log", "rand 0.9.4", @@ -4180,9 +4154,9 @@ dependencies = [ [[package]] name = "typenum" -version = "1.19.0" +version = "1.20.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "562d481066bde0658276a35467c4af00bdc6ee726305698a55b86e61d7ad82bb" +checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20" [[package]] name = "uncased" @@ -4216,9 +4190,9 @@ dependencies = [ [[package]] name = "unicode-segmentation" -version = "1.13.2" +version = "1.13.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9629274872b2bfaf8d66f5f15725007f635594914870f65218920345aa11aa8c" +checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8" [[package]] name = "unicode-xid" @@ -4270,11 +4244,11 @@ checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821" [[package]] name = "uuid" -version = "1.23.1" +version = "1.23.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ddd74a9687298c6858e9b88ec8935ec45d22e8fd5e6394fa1bd4e99a87789c76" +checksum = "bf80a72845275afea99e7f2b434723d3bc7e38470fcd1c7ed39a599c73319a53" dependencies = [ - "getrandom 0.4.2", + "getrandom 0.4.3", "js-sys", "serde_core", "wasm-bindgen", @@ -4325,27 +4299,18 @@ checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b" [[package]] name = "wasip2" -version = "1.0.2+wasi-0.2.9" +version = "1.0.4+wasi-0.2.12" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9517f9239f02c069db75e65f174b3da828fe5f5b945c4dd26bd25d89c03ebcf5" -dependencies = [ - "wit-bindgen", -] - -[[package]] -name = "wasip3" -version = "0.4.0+wasi-0.3.0-rc-2026-01-06" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5428f8bf88ea5ddc08faddef2ac4a67e390b88186c703ce6dbd955e1c145aca5" +checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487" dependencies = [ "wit-bindgen", ] [[package]] name = "wasm-bindgen" -version = "0.2.118" +version = "0.2.126" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0bf938a0bacb0469e83c1e148908bd7d5a6010354cf4fb73279b7447422e3a89" +checksum = "4b067c0c11094aef6b7a801c1e34a26affafdf3d051dba08456b868789aaf9a4" dependencies = [ "cfg-if", "once_cell", @@ -4356,9 +4321,9 @@ dependencies = [ [[package]] name = "wasm-bindgen-futures" -version = "0.4.68" +version = "0.4.76" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f371d383f2fb139252e0bfac3b81b265689bf45b6874af544ffa4c975ac1ebf8" +checksum = "c62df1340f32221cb9c54d6a27b030e3dba64361d4a95bed55f9aacb44da291d" dependencies = [ "js-sys", "wasm-bindgen", @@ -4366,9 +4331,9 @@ dependencies = [ [[package]] name = "wasm-bindgen-macro" -version = "0.2.118" +version = "0.2.126" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "eeff24f84126c0ec2db7a449f0c2ec963c6a49efe0698c4242929da037ca28ed" +checksum = "167ce5e579f6bcf889c4f7175a8a5a585de84e8ff93976ce393efa5f2837aab1" dependencies = [ "quote", "wasm-bindgen-macro-support", @@ -4376,9 +4341,9 @@ dependencies = [ [[package]] name = "wasm-bindgen-macro-support" -version = "0.2.118" +version = "0.2.126" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9d08065faf983b2b80a79fd87d8254c409281cf7de75fc4b773019824196c904" +checksum = "f3997c7839262f4ef12cf90b818d6340c18e80f263f1a94bf157d0ec4420380e" dependencies = [ "bumpalo", "proc-macro2", @@ -4389,35 +4354,13 @@ dependencies = [ [[package]] name = "wasm-bindgen-shared" -version = "0.2.118" +version = "0.2.126" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5fd04d9e306f1907bd13c6361b5c6bfc7b3b3c095ed3f8a9246390f8dbdee129" +checksum = "dc1b4cb0cc549fcf58d7dfc081778139b3d283a081644e833e84682ad71cea24" dependencies = [ "unicode-ident", ] -[[package]] -name = "wasm-encoder" -version = "0.244.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "990065f2fe63003fe337b932cfb5e3b80e0b4d0f5ff650e6985b1048f62c8319" -dependencies = [ - "leb128fmt", - "wasmparser", -] - -[[package]] -name = "wasm-metadata" -version = "0.244.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "bb0e353e6a2fbdc176932bbaab493762eb1255a7900fe0fea1a2f96c296cc909" -dependencies = [ - "anyhow", - "indexmap 2.14.0", - "wasm-encoder", - "wasmparser", -] - [[package]] name = "wasm-streams" version = "0.4.2" @@ -4446,9 +4389,9 @@ dependencies = [ [[package]] name = "wasm_split_helpers" -version = "0.2.1" +version = "0.2.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d0cb6d1008be3c4c5abc31a407bfb8c8449ae14efc8561c1db821f79b9614b0a" +checksum = "ab578aae2fe2916edaea06843187d50f87b0965622da0ceef648edca27b385ba" dependencies = [ "async-once-cell", "wasm_split_macros", @@ -4456,9 +4399,9 @@ dependencies = [ [[package]] name = "wasm_split_macros" -version = "0.2.1" +version = "0.2.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d0a659ffe5c7f4538aa6357c07e3d73221cc61eba03bd9a081e14bc91ed09b8c" +checksum = "3e653af7ee4a9ef0fce481a9ec6f43cb78de20d0cdb4f4f5862e1dc6e407e6c8" dependencies = [ "base16", "quote", @@ -4466,23 +4409,11 @@ dependencies = [ "syn", ] -[[package]] -name = "wasmparser" -version = "0.244.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "47b807c72e1bac69382b3a6fb3dbe8ea4c0ed87ff5629b8685ae6b9a611028fe" -dependencies = [ - "bitflags 2.11.1", - "hashbrown 0.15.5", - "indexmap 2.14.0", - "semver", -] - [[package]] name = "web-sys" -version = "0.3.95" +version = "0.3.103" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4f2dfbb17949fa2088e5d39408c48368947b86f7834484e87b73de55bc14d97d" +checksum = "8622dcb61c0bcc9fffa6938bed81210af2da9a7e4a1a834b2e37a59b6dfb6141" dependencies = [ "js-sys", "wasm-bindgen", @@ -4504,14 +4435,14 @@ version = "0.26.11" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "521bc38abb08001b01866da9f51eb7c5d647a19260e00054a8c7fd5f9e57f7a9" dependencies = [ - "webpki-roots 1.0.6", + "webpki-roots 1.0.8", ] [[package]] name = "webpki-roots" -version = "1.0.6" +version = "1.0.8" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "22cfaf3c063993ff62e73cb4311efde4db1efb31ab78a3e5c457939ad5cc0bed" +checksum = "bf85cb06032201fa7c6f829d7db5a7e5aa45bcc0655327713065f6f0576731bf" dependencies = [ "rustls-pki-types", ] @@ -4605,6 +4536,15 @@ dependencies = [ "windows-targets 0.52.6", ] +[[package]] +name = "windows-sys" +version = "0.59.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b" +dependencies = [ + "windows-targets 0.52.6", +] + [[package]] name = "windows-sys" version = "0.60.2" @@ -4754,100 +4694,18 @@ checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650" [[package]] name = "winnow" -version = "1.0.1" +version = "1.0.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "09dac053f1cd375980747450bfc7250c264eaae0583872e845c0c7cd578872b5" +checksum = "0592e1c9d151f854e6fd382574c3a0855250e1d9b2f99d9281c6e6391af352f1" dependencies = [ "memchr", ] [[package]] name = "wit-bindgen" -version = "0.51.0" +version = "0.57.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d7249219f66ced02969388cf2bb044a09756a083d0fab1e566056b04d9fbcaa5" -dependencies = [ - "wit-bindgen-rust-macro", -] - -[[package]] -name = "wit-bindgen-core" -version = "0.51.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ea61de684c3ea68cb082b7a88508a8b27fcc8b797d738bfc99a82facf1d752dc" -dependencies = [ - "anyhow", - "heck", - "wit-parser", -] - -[[package]] -name = "wit-bindgen-rust" -version = "0.51.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b7c566e0f4b284dd6561c786d9cb0142da491f46a9fbed79ea69cdad5db17f21" -dependencies = [ - "anyhow", - "heck", - "indexmap 2.14.0", - "prettyplease", - "syn", - "wasm-metadata", - "wit-bindgen-core", - "wit-component", -] - -[[package]] -name = "wit-bindgen-rust-macro" -version = "0.51.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0c0f9bfd77e6a48eccf51359e3ae77140a7f50b1e2ebfe62422d8afdaffab17a" -dependencies = [ - "anyhow", - "prettyplease", - "proc-macro2", - "quote", - "syn", - "wit-bindgen-core", - "wit-bindgen-rust", -] - -[[package]] -name = "wit-component" -version = "0.244.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9d66ea20e9553b30172b5e831994e35fbde2d165325bec84fc43dbf6f4eb9cb2" -dependencies = [ - "anyhow", - "bitflags 2.11.1", - "indexmap 2.14.0", - "log", - "serde", - "serde_derive", - "serde_json", - "wasm-encoder", - "wasm-metadata", - "wasmparser", - "wit-parser", -] - -[[package]] -name = "wit-parser" -version = "0.244.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ecc8ac4bc1dc3381b7f59c34f00b67e18f910c2c0f50015669dde7def656a736" -dependencies = [ - "anyhow", - "id-arena", - "indexmap 2.14.0", - "log", - "semver", - "serde", - "serde_derive", - "serde_json", - "unicode-xid", - "wasmparser", -] +checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e" [[package]] name = "writeable" @@ -4857,9 +4715,9 @@ checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4" [[package]] name = "xxhash-rust" -version = "0.8.15" +version = "0.8.16" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "fdd20c5420375476fbd4394763288da7eb0cc0b8c11deed431a91562af7335d3" +checksum = "4d93c89cdc2d3a63c3ec48ffe926931bdc069eafa8e4402fe6d8f790c9d1e576" [[package]] name = "xz2" @@ -4878,9 +4736,9 @@ checksum = "cfe53a6657fd280eaa890a3bc59152892ffa3e30101319d168b781ed6529b049" [[package]] name = "yoke" -version = "0.8.2" +version = "0.8.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "abe8c5fda708d9ca3df187cae8bfb9ceda00dd96231bed36e445a1a48e66f9ca" +checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5" dependencies = [ "stable_deref_trait", "yoke-derive", @@ -4911,11 +4769,11 @@ dependencies = [ [[package]] name = "zerocopy" -version = "0.8.48" +version = "0.8.52" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "eed437bf9d6692032087e337407a86f04cd8d6a16a37199ed57949d415bd68e9" +checksum = "ce1022995ff5ff5d841ad7d994facc23098cd40152f2c1d11cd607c6f530653f" dependencies = [ - "zerocopy-derive 0.8.48", + "zerocopy-derive 0.8.52", ] [[package]] @@ -4931,9 +4789,9 @@ dependencies = [ [[package]] name = "zerocopy-derive" -version = "0.8.48" +version = "0.8.52" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "70e3cd084b1788766f53af483dd21f93881ff30d7320490ec3ef7526d203bad4" +checksum = "1ae7f38b72ec2a254e2b87ef277cf2cd4fb97cbebf944faa6f33354da0867930" dependencies = [ "proc-macro2", "quote", @@ -4942,9 +4800,9 @@ dependencies = [ [[package]] name = "zerofrom" -version = "0.1.7" +version = "0.1.8" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "69faa1f2a1ea75661980b013019ed6687ed0e83d069bc1114e2cc74c6c04c4df" +checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272" dependencies = [ "zerofrom-derive", ] @@ -4963,18 +4821,18 @@ dependencies = [ [[package]] name = "zeroize" -version = "1.8.2" +version = "1.9.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b97154e67e32c85465826e8bcc1c59429aaaf107c1e4a9e53c8d8ccd5eff88d0" +checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e" dependencies = [ "zeroize_derive", ] [[package]] name = "zeroize_derive" -version = "1.4.3" +version = "1.5.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "85a5b4158499876c763cb03bc4e49185d3cccbabb15b33c627f7884f43db852e" +checksum = "3c50655cbb0fe3fc43170059e702f1ce5e19b84cec58dc87b037a09935c2f328" dependencies = [ "proc-macro2", "quote", diff --git a/rust/crates/control-plane/migrations/009-ai-tool-events-file-patches.sql b/rust/crates/control-plane/migrations/009-ai-tool-events-file-patches.sql new file mode 100644 index 00000000..9eeebe84 --- /dev/null +++ b/rust/crates/control-plane/migrations/009-ai-tool-events-file-patches.sql @@ -0,0 +1,56 @@ +-- P2: AI tool events (receipts) and file patches for per-user/per-session query. +-- See design/07-ai/process/7-71-unified-ai-management-control-plane-and-pi-lab-integration-v1.md + +CREATE TABLE IF NOT EXISTS ai_tool_events ( + id TEXT PRIMARY KEY, + user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE, + workspace_id TEXT, + session_id TEXT NOT NULL, + run_id TEXT, + provider TEXT NOT NULL, + provider_session_id TEXT, + tool_name TEXT NOT NULL, + allowed INTEGER NOT NULL DEFAULT 1, + deny_reason TEXT, + root_uri TEXT NOT NULL, + page_path TEXT, + normalized_file_path TEXT, + diff_summary TEXT, + citation_count INTEGER NOT NULL DEFAULT 0, + before_file_version TEXT, + after_file_version TEXT, + payload_json TEXT NOT NULL DEFAULT '{}', + created_at TEXT NOT NULL DEFAULT (datetime('now')), + deleted_at TEXT +); + +CREATE INDEX IF NOT EXISTS idx_ai_tool_events_user_session +ON ai_tool_events(user_id, session_id, created_at); + +CREATE INDEX IF NOT EXISTS idx_ai_tool_events_user_run +ON ai_tool_events(user_id, run_id, created_at); + +CREATE TABLE IF NOT EXISTS ai_file_patches ( + id TEXT PRIMARY KEY, + user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE, + workspace_id TEXT, + session_id TEXT NOT NULL, + run_id TEXT, + tool_event_id TEXT NOT NULL REFERENCES ai_tool_events(id) ON DELETE CASCADE, + root_uri TEXT NOT NULL DEFAULT '', + relative_path TEXT NOT NULL, + before_file_version TEXT, + after_file_version TEXT, + patch_summary_json TEXT NOT NULL DEFAULT '{}', + created_at TEXT NOT NULL DEFAULT (datetime('now')), + deleted_at TEXT +); + +CREATE INDEX IF NOT EXISTS idx_ai_file_patches_user_session +ON ai_file_patches(user_id, session_id, created_at); + +CREATE INDEX IF NOT EXISTS idx_ai_file_patches_user_run +ON ai_file_patches(user_id, run_id, created_at); + +CREATE INDEX IF NOT EXISTS idx_ai_file_patches_tool_event +ON ai_file_patches(tool_event_id); diff --git a/rust/crates/control-plane/src/bin/control-plane-admin.rs b/rust/crates/control-plane/src/bin/control-plane-admin.rs index 11f468f9..b28a787f 100644 --- a/rust/crates/control-plane/src/bin/control-plane-admin.rs +++ b/rust/crates/control-plane/src/bin/control-plane-admin.rs @@ -33,6 +33,8 @@ const TABLE_ORDER: &[&str] = &[ "ai_agent_profiles", "ai_agent_profile_grants", "ai_external_conversation_bindings", + "ai_tool_events", + "ai_file_patches", ]; #[derive(Debug, Clone, PartialEq, Eq)] @@ -78,6 +80,16 @@ impl ControlPlaneStore for StoreHandle { } } + fn list_users( + &self, + limit: usize, + ) -> Result, ControlPlaneError> { + match self { + StoreHandle::Sqlite(store) => store.list_users(limit), + StoreHandle::Turso(store) => store.list_users(limit), + } + } + fn create_password_identity( &self, input: control_plane::CreatePasswordIdentityInput, @@ -702,6 +714,50 @@ impl ControlPlaneStore for StoreHandle { } } } + + fn append_ai_tool_event( + &self, + input: control_plane::AppendAiToolEventInput, + ) -> Result { + match self { + StoreHandle::Sqlite(store) => store.append_ai_tool_event(input), + StoreHandle::Turso(store) => store.append_ai_tool_event(input), + } + } + + fn list_ai_tool_events( + &self, + user_id: &str, + session_id: Option<&str>, + limit: usize, + ) -> Result, ControlPlaneError> { + match self { + StoreHandle::Sqlite(store) => store.list_ai_tool_events(user_id, session_id, limit), + StoreHandle::Turso(store) => store.list_ai_tool_events(user_id, session_id, limit), + } + } + + fn append_ai_file_patch( + &self, + input: control_plane::AppendAiFilePatchInput, + ) -> Result { + match self { + StoreHandle::Sqlite(store) => store.append_ai_file_patch(input), + StoreHandle::Turso(store) => store.append_ai_file_patch(input), + } + } + + fn list_ai_file_patches( + &self, + user_id: &str, + session_id: Option<&str>, + limit: usize, + ) -> Result, ControlPlaneError> { + match self { + StoreHandle::Sqlite(store) => store.list_ai_file_patches(user_id, session_id, limit), + StoreHandle::Turso(store) => store.list_ai_file_patches(user_id, session_id, limit), + } + } } #[derive(Debug)] diff --git a/rust/crates/control-plane/src/migrations.rs b/rust/crates/control-plane/src/migrations.rs index 3c735d31..255dbe84 100644 --- a/rust/crates/control-plane/src/migrations.rs +++ b/rust/crates/control-plane/src/migrations.rs @@ -39,6 +39,10 @@ const MIGRATIONS: &[(&str, &str)] = &[ "v8-ai-external-conversation-bindings", include_str!("../migrations/008-ai-external-conversation-bindings.sql"), ), + ( + "v9-ai-tool-events-file-patches", + include_str!("../migrations/009-ai-tool-events-file-patches.sql"), + ), ]; /// Create the `_migrations` meta-table if it does not exist. @@ -169,6 +173,8 @@ mod tests { "ai_agent_profiles", "ai_agent_profile_grants", "ai_external_conversation_bindings", + "ai_tool_events", + "ai_file_patches", ] { assert!(table_exists(&conn, table), "table {table} should exist"); } @@ -224,6 +230,8 @@ mod tests { "ai_agent_profiles", "ai_agent_profile_grants", "ai_external_conversation_bindings", + "ai_tool_events", + "ai_file_patches", ]; for table in tables { let exists = rt.block_on(async { libsql_table_exists(&conn, table).await }); diff --git a/rust/crates/control-plane/src/model.rs b/rust/crates/control-plane/src/model.rs index 281f4bbe..413890da 100644 --- a/rust/crates/control-plane/src/model.rs +++ b/rust/crates/control-plane/src/model.rs @@ -534,3 +534,85 @@ pub struct AppendAuditInput { pub target_id: Option, pub metadata_json: String, } + +// --------------------------------------------------------------------------- +// P2: AI tool events (receipts) and file patches — 7-71 +// --------------------------------------------------------------------------- + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct AiToolEventRecord { + pub id: EntityId, + pub user_id: EntityId, + pub workspace_id: Option, + pub session_id: EntityId, + pub run_id: Option, + pub provider: String, + pub provider_session_id: Option, + pub tool_name: String, + pub allowed: bool, + pub deny_reason: Option, + pub root_uri: String, + pub page_path: Option, + pub normalized_file_path: Option, + pub diff_summary: Option, + pub citation_count: i64, + pub before_file_version: Option, + pub after_file_version: Option, + pub payload_json: String, + pub created_at: Timestamp, + pub deleted_at: Option, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct AppendAiToolEventInput { + pub id: Option, + pub user_id: EntityId, + pub workspace_id: Option, + pub session_id: EntityId, + pub run_id: Option, + pub provider: String, + pub provider_session_id: Option, + pub tool_name: String, + pub allowed: bool, + pub deny_reason: Option, + pub root_uri: String, + pub page_path: Option, + pub normalized_file_path: Option, + pub diff_summary: Option, + pub citation_count: i64, + pub before_file_version: Option, + pub after_file_version: Option, + pub payload_json: String, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct AiFilePatchRecord { + pub id: EntityId, + pub user_id: EntityId, + pub workspace_id: Option, + pub session_id: EntityId, + pub run_id: Option, + pub tool_event_id: EntityId, + pub root_uri: String, + pub relative_path: String, + pub before_file_version: Option, + pub after_file_version: Option, + pub patch_summary_json: String, + pub created_at: Timestamp, + pub deleted_at: Option, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct AppendAiFilePatchInput { + pub id: Option, + pub user_id: EntityId, + pub workspace_id: Option, + pub session_id: EntityId, + pub run_id: Option, + pub tool_event_id: EntityId, + pub root_uri: String, + pub relative_path: String, + pub before_file_version: Option, + pub after_file_version: Option, + pub patch_summary_json: String, +} diff --git a/rust/crates/control-plane/src/sqlite.rs b/rust/crates/control-plane/src/sqlite.rs index f79ac5cf..655dd559 100644 --- a/rust/crates/control-plane/src/sqlite.rs +++ b/rust/crates/control-plane/src/sqlite.rs @@ -9,17 +9,17 @@ use crate::error::ControlPlaneError; use crate::migrations; use crate::model::{ password_hash_v1, share_token_hash_v1, AiAgentProfileAccessRecord, AiAgentProfileGrantRecord, - AiAgentProfileRecord, AiExternalConversationBindingRecord, AiPolicyRecord, - AiRuntimeEventRecord, AiRuntimeJournalEventRecord, AiRuntimeRunRecord, - AppendAiRuntimeEventInput, AppendAuditInput, AuditLogRecord, AuthSessionRecord, - AuthenticatePasswordInput, CreatePasswordIdentityInput, CreateSessionInput, - CreateShareLinkInput, CreatedShareLink, DirectoryGrantInput, DirectoryGrantLookup, - DirectoryGrantRecord, NavigationRecentRecord, OutboxEventInput, OutboxEventRecord, - ResolvedAccess, ResolvedAuthSession, ShareLinkRecord, SidebarShortcutRecord, SyncStateRecord, - UpsertAiExternalConversationBindingInput, UpsertAiPolicyInput, UpsertAiRuntimeRunInput, - UpsertNavigationRecentInput, UpsertSidebarShortcutInput, UpsertSyncStateInput, UpsertUserInput, - UpsertUserUiPreferenceInput, UpsertWorkspaceInput, UserRecord, UserUiPreferenceRecord, - WorkspaceRecord, + AiAgentProfileRecord, AiExternalConversationBindingRecord, AiFilePatchRecord, AiPolicyRecord, + AiRuntimeEventRecord, AiRuntimeJournalEventRecord, AiRuntimeRunRecord, AiToolEventRecord, + AppendAiFilePatchInput, AppendAiRuntimeEventInput, AppendAiToolEventInput, AppendAuditInput, + AuditLogRecord, AuthSessionRecord, AuthenticatePasswordInput, CreatePasswordIdentityInput, + CreateSessionInput, CreateShareLinkInput, CreatedShareLink, DirectoryGrantInput, + DirectoryGrantLookup, DirectoryGrantRecord, NavigationRecentRecord, OutboxEventInput, + OutboxEventRecord, ResolvedAccess, ResolvedAuthSession, ShareLinkRecord, SidebarShortcutRecord, + SyncStateRecord, UpsertAiExternalConversationBindingInput, UpsertAiPolicyInput, + UpsertAiRuntimeRunInput, UpsertNavigationRecentInput, UpsertSidebarShortcutInput, + UpsertSyncStateInput, UpsertUserInput, UpsertUserUiPreferenceInput, UpsertWorkspaceInput, + UserRecord, UserUiPreferenceRecord, WorkspaceRecord, }; use crate::store::ControlPlaneStore; @@ -469,6 +469,49 @@ fn row_to_ai_external_conversation_binding( }) } +fn row_to_ai_tool_event(row: &rusqlite::Row<'_>) -> rusqlite::Result { + Ok(AiToolEventRecord { + id: row.get(0)?, + user_id: row.get(1)?, + workspace_id: row.get(2)?, + session_id: row.get(3)?, + run_id: row.get(4)?, + provider: row.get(5)?, + provider_session_id: row.get(6)?, + tool_name: row.get(7)?, + allowed: row.get(8)?, + deny_reason: row.get(9)?, + root_uri: row.get(10)?, + page_path: row.get(11)?, + normalized_file_path: row.get(12)?, + diff_summary: row.get(13)?, + citation_count: row.get(14)?, + before_file_version: row.get(15)?, + after_file_version: row.get(16)?, + payload_json: row.get(17)?, + created_at: row.get(18)?, + deleted_at: row.get(19)?, + }) +} + +fn row_to_ai_file_patch(row: &rusqlite::Row<'_>) -> rusqlite::Result { + Ok(AiFilePatchRecord { + id: row.get(0)?, + user_id: row.get(1)?, + workspace_id: row.get(2)?, + session_id: row.get(3)?, + run_id: row.get(4)?, + tool_event_id: row.get(5)?, + root_uri: row.get(6)?, + relative_path: row.get(7)?, + before_file_version: row.get(8)?, + after_file_version: row.get(9)?, + patch_summary_json: row.get(10)?, + created_at: row.get(11)?, + deleted_at: row.get(12)?, + }) +} + fn derive_ai_runtime_title(payload_json: &str, fallback: &str) -> String { let title = serde_json::from_str::(payload_json) .ok() @@ -557,7 +600,9 @@ fn list_ai_agent_profile_access_rows( } impl SqliteControlPlaneStore { - fn lock_conn(&self) -> Result, ControlPlaneError> { + fn lock_conn( + &self, + ) -> Result, ControlPlaneError> { self.conn .lock() .map_err(|e| ControlPlaneError::Storage(format!("sqlite lock poisoned: {e}"))) @@ -639,6 +684,22 @@ impl ControlPlaneStore for SqliteControlPlaneStore { }) } + fn list_users(&self, limit: usize) -> Result, ControlPlaneError> { + let conn = self.lock_conn()?; + let limit = limit.min(1000).max(1); + let mut stmt = conn.prepare( + "SELECT id, email, username, display_name, role, status, created_at, updated_at, revision + FROM users + ORDER BY created_at ASC, id ASC + LIMIT ?1", + )?; + let rows = stmt + .query_map(params![limit as i64], row_to_user)? + .collect::, _>>() + .map_err(ControlPlaneError::from)?; + Ok(rows) + } + fn create_password_identity( &self, input: CreatePasswordIdentityInput, @@ -950,7 +1011,10 @@ impl ControlPlaneStore for SqliteControlPlaneStore { let name = input.name.trim().to_string(); let root_uri = input.root_uri.trim().to_string(); let root_path = input.root_path.trim().to_string(); - if owner_user_id.is_empty() || name.is_empty() || root_uri.is_empty() || root_path.is_empty() + if owner_user_id.is_empty() + || name.is_empty() + || root_uri.is_empty() + || root_path.is_empty() { return Err(ControlPlaneError::InvalidInput( "workspace owner/name/root 不能为空".to_string(), @@ -2964,6 +3028,154 @@ impl ControlPlaneStore for SqliteControlPlaneStore { )?; Ok(changed) } + + // ----------------------------------------------------------------------- + // P2: AI tool events (receipts) — 7-71 + // ----------------------------------------------------------------------- + + fn append_ai_tool_event( + &self, + input: AppendAiToolEventInput, + ) -> Result { + if input.user_id.trim().is_empty() || input.session_id.trim().is_empty() { + return Err(ControlPlaneError::InvalidInput( + "ai tool event user_id/session_id 不能为空".to_string(), + )); + } + serde_json::from_str::(&input.payload_json)?; + + let conn = self.lock_conn()?; + let record = AiToolEventRecord { + id: input.id.unwrap_or_else(|| new_id("ate")), + user_id: input.user_id, + workspace_id: input.workspace_id, + session_id: input.session_id, + run_id: input.run_id, + provider: input.provider, + provider_session_id: input.provider_session_id, + tool_name: input.tool_name, + allowed: input.allowed, + deny_reason: input.deny_reason, + root_uri: input.root_uri, + page_path: input.page_path, + normalized_file_path: input.normalized_file_path, + diff_summary: input.diff_summary, + citation_count: input.citation_count, + before_file_version: input.before_file_version, + after_file_version: input.after_file_version, + payload_json: input.payload_json, + created_at: now_text(), + deleted_at: None, + }; + conn.execute( + "INSERT INTO ai_tool_events (id, user_id, workspace_id, session_id, run_id, provider, provider_session_id, tool_name, allowed, deny_reason, root_uri, page_path, normalized_file_path, diff_summary, citation_count, before_file_version, after_file_version, payload_json, created_at) + VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?15, ?16, ?17, ?18, ?19)", + params![ + record.id, record.user_id, record.workspace_id, record.session_id, record.run_id, + record.provider, record.provider_session_id, record.tool_name, record.allowed, record.deny_reason, + record.root_uri, record.page_path, record.normalized_file_path, record.diff_summary, record.citation_count, + record.before_file_version, record.after_file_version, record.payload_json, record.created_at + ], + )?; + Ok(record) + } + + fn list_ai_tool_events( + &self, + user_id: &str, + session_id: Option<&str>, + limit: usize, + ) -> Result, ControlPlaneError> { + let conn = self.lock_conn()?; + let mut stmt = conn.prepare( + "SELECT id, user_id, workspace_id, session_id, run_id, provider, provider_session_id, tool_name, allowed, deny_reason, root_uri, page_path, normalized_file_path, diff_summary, citation_count, before_file_version, after_file_version, payload_json, created_at, deleted_at + FROM ai_tool_events + WHERE user_id = ?1 AND deleted_at IS NULL + AND (?2 IS NULL OR session_id = ?2) + ORDER BY created_at DESC + LIMIT ?3", + )?; + let rows = stmt + .query_map( + params![user_id, session_id, limit as i64], + row_to_ai_tool_event, + )? + .collect::, _>>() + .map_err(ControlPlaneError::from)?; + Ok(rows) + } + + // ----------------------------------------------------------------------- + // P2: AI file patches — 7-71 + // ----------------------------------------------------------------------- + + fn append_ai_file_patch( + &self, + input: AppendAiFilePatchInput, + ) -> Result { + if input.user_id.trim().is_empty() + || input.session_id.trim().is_empty() + || input.tool_event_id.trim().is_empty() + { + return Err(ControlPlaneError::InvalidInput( + "ai file patch user_id/session_id/tool_event_id 不能为空".to_string(), + )); + } + serde_json::from_str::(&input.patch_summary_json)?; + + let conn = self.lock_conn()?; + let record = AiFilePatchRecord { + id: input.id.unwrap_or_else(|| new_id("afp")), + user_id: input.user_id, + workspace_id: input.workspace_id, + session_id: input.session_id, + run_id: input.run_id, + tool_event_id: input.tool_event_id, + root_uri: input.root_uri, + relative_path: input.relative_path, + before_file_version: input.before_file_version, + after_file_version: input.after_file_version, + patch_summary_json: input.patch_summary_json, + created_at: now_text(), + deleted_at: None, + }; + conn.execute( + "INSERT INTO ai_file_patches (id, user_id, workspace_id, session_id, run_id, tool_event_id, root_uri, relative_path, before_file_version, after_file_version, patch_summary_json, created_at) + VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12)", + params![ + record.id, record.user_id, record.workspace_id, record.session_id, record.run_id, + record.tool_event_id, record.root_uri, record.relative_path, + record.before_file_version, record.after_file_version, record.patch_summary_json, record.created_at + ], + )?; + Ok(record) + } + + fn list_ai_file_patches( + &self, + user_id: &str, + session_id: Option<&str>, + limit: usize, + ) -> Result, ControlPlaneError> { + let conn = self.lock_conn()?; + let mut stmt = conn.prepare( + "SELECT id, user_id, workspace_id, session_id, run_id, tool_event_id, root_uri, relative_path, before_file_version, after_file_version, patch_summary_json, created_at, deleted_at + FROM ai_file_patches + WHERE user_id = ?1 + AND deleted_at IS NULL + AND (?2 IS NULL OR session_id = ?2) + ORDER BY created_at DESC + LIMIT ?3", + )?; + let rows = stmt + .query_map( + params![user_id, session_id, limit as i64], + row_to_ai_file_patch, + )? + .collect::, _>>() + .map_err(ControlPlaneError::from)?; + Ok(rows) + } } fn max_permission<'a>(left: &'a str, right: &'a str) -> &'a str { @@ -3050,6 +3262,48 @@ mod tests { assert_eq!(updated.revision, 2); } + #[test] + fn list_users_returns_stable_ordering() { + let store = store(); + + // Create 3 users in known order + let u1 = create_user(&store, "bravo"); + let u2 = create_user(&store, "alpha"); + let u3 = create_user(&store, "charlie"); + + let users = store.list_users(10).expect("list users"); + assert_eq!(users.len(), 3, "should return all three users"); + + // Order must be by created_at ASC, id ASC + // u1 (bravo) created first, u2 (alpha) second, u3 (charlie) third + assert_eq!(users[0].id, u1.id, "first created should be first"); + assert_eq!(users[1].id, u2.id, "second created should be second"); + assert_eq!(users[2].id, u3.id, "third created should be third"); + } + + #[test] + fn list_users_respects_limit() { + let store = store(); + for i in 0..5usize { + create_user(&store, &format!("user{i}")); + } + + let users = store.list_users(3).expect("list users with limit"); + assert_eq!(users.len(), 3, "should respect limit=3"); + } + + #[test] + fn list_users_excludes_password_data() { + let store = store(); + create_user(&store, "nopassword"); + + let users = store.list_users(10).expect("list users"); + assert_eq!(users.len(), 1); + // UserRecord has no password_hash field — this is a compile-time + // guarantee that list_users cannot leak password data. + assert!(users[0].email.is_some()); + } + #[test] fn ensure_default_workspace_creates_owner_grant() { let store = store(); @@ -4224,4 +4478,132 @@ mod tests { .expect("lookup failed session") .is_none()); } + + #[test] + fn ai_tool_events_append_and_list() { + let store = store(); + create_user(&store, "tool_user"); + + let event = store + .append_ai_tool_event(AppendAiToolEventInput { + id: None, + user_id: "tool_user".to_string(), + workspace_id: Some("ws_1".to_string()), + session_id: "sess_1".to_string(), + run_id: Some("run_1".to_string()), + provider: "doubao-web".to_string(), + provider_session_id: Some("ps_1".to_string()), + tool_name: "mnote.local_file.read".to_string(), + allowed: true, + deny_reason: None, + root_uri: "file:///tmp".to_string(), + page_path: Some("page.md".to_string()), + normalized_file_path: Some("/tmp/page.md".to_string()), + diff_summary: Some("read file".to_string()), + citation_count: 0, + before_file_version: None, + after_file_version: None, + payload_json: "{}".to_string(), + }) + .expect("append tool event"); + assert_eq!(event.tool_name, "mnote.local_file.read"); + assert!(event.allowed); + assert_eq!(event.citation_count, 0); + + // Append a denied event + store + .append_ai_tool_event(AppendAiToolEventInput { + id: None, + user_id: "tool_user".to_string(), + workspace_id: Some("ws_1".to_string()), + session_id: "sess_1".to_string(), + run_id: Some("run_2".to_string()), + provider: "reasonix".to_string(), + provider_session_id: None, + tool_name: "fs.write".to_string(), + allowed: false, + deny_reason: Some("path not in allowed roots".to_string()), + root_uri: "file:///etc".to_string(), + page_path: None, + normalized_file_path: Some("/etc/passwd".to_string()), + diff_summary: None, + citation_count: 0, + before_file_version: None, + after_file_version: None, + payload_json: "{}".to_string(), + }) + .expect("append denied event"); + + let events = store + .list_ai_tool_events("tool_user", Some("sess_1"), 10) + .expect("list events"); + assert_eq!(events.len(), 2); + assert_eq!(events[0].tool_name, "fs.write"); + assert!(!events[0].allowed); + + let all_events = store + .list_ai_tool_events("tool_user", None, 10) + .expect("list all events"); + assert_eq!(all_events.len(), 2); + } + + #[test] + fn ai_file_patches_append_and_list() { + let store = store(); + create_user(&store, "patch_user"); + + // First create a tool event to reference + let event = store + .append_ai_tool_event(AppendAiToolEventInput { + id: Some("ate_patch_ref".to_string()), + user_id: "patch_user".to_string(), + workspace_id: None, + session_id: "sess_p1".to_string(), + run_id: None, + provider: "openclaw".to_string(), + provider_session_id: None, + tool_name: "mnote.local_file.patch".to_string(), + allowed: true, + deny_reason: None, + root_uri: "file:///tmp".to_string(), + page_path: Some("test.md".to_string()), + normalized_file_path: Some("/tmp/test.md".to_string()), + diff_summary: Some("edit file".to_string()), + citation_count: 0, + before_file_version: Some("v1".to_string()), + after_file_version: Some("v2".to_string()), + payload_json: "{}".to_string(), + }) + .expect("append reference tool event"); + + let patch = store + .append_ai_file_patch(AppendAiFilePatchInput { + id: None, + user_id: "patch_user".to_string(), + workspace_id: None, + session_id: "sess_p1".to_string(), + run_id: None, + tool_event_id: event.id.clone(), + root_uri: "file:///tmp".to_string(), + relative_path: "test.md".to_string(), + before_file_version: Some("v1".to_string()), + after_file_version: Some("v2".to_string()), + patch_summary_json: r#"{"insertions":5,"deletions":2}"#.to_string(), + }) + .expect("append file patch"); + assert_eq!(patch.tool_event_id, event.id); + assert_eq!(patch.relative_path, "test.md"); + assert!(patch.deleted_at.is_none()); + + let patches = store + .list_ai_file_patches("patch_user", Some("sess_p1"), 10) + .expect("list patches"); + assert_eq!(patches.len(), 1); + assert_eq!(patches[0].tool_event_id, event.id); + + let all_patches = store + .list_ai_file_patches("patch_user", None, 10) + .expect("list all patches"); + assert_eq!(all_patches.len(), 1); + } } diff --git a/rust/crates/control-plane/src/store.rs b/rust/crates/control-plane/src/store.rs index 11ada567..b18249b8 100644 --- a/rust/crates/control-plane/src/store.rs +++ b/rust/crates/control-plane/src/store.rs @@ -2,22 +2,26 @@ use crate::error::ControlPlaneError; use crate::model::{ - AiAgentProfileAccessRecord, AiExternalConversationBindingRecord, AiPolicyRecord, - AiRuntimeEventRecord, AiRuntimeJournalEventRecord, AiRuntimeRunRecord, - AppendAiRuntimeEventInput, AppendAuditInput, AuditLogRecord, AuthSessionRecord, - AuthenticatePasswordInput, CreatePasswordIdentityInput, CreateSessionInput, - CreateShareLinkInput, CreatedShareLink, DirectoryGrantInput, DirectoryGrantLookup, - DirectoryGrantRecord, NavigationRecentRecord, OutboxEventInput, OutboxEventRecord, - ResolvedAccess, ResolvedAuthSession, ShareLinkRecord, SidebarShortcutRecord, SyncStateRecord, - UpsertAiExternalConversationBindingInput, UpsertAiPolicyInput, UpsertAiRuntimeRunInput, - UpsertNavigationRecentInput, UpsertSidebarShortcutInput, UpsertSyncStateInput, UpsertUserInput, - UpsertUserUiPreferenceInput, UpsertWorkspaceInput, UserRecord, UserUiPreferenceRecord, - WorkspaceRecord, + AiAgentProfileAccessRecord, AiExternalConversationBindingRecord, AiFilePatchRecord, + AiPolicyRecord, AiRuntimeEventRecord, AiRuntimeJournalEventRecord, AiRuntimeRunRecord, + AiToolEventRecord, AppendAiFilePatchInput, AppendAiRuntimeEventInput, AppendAiToolEventInput, + AppendAuditInput, AuditLogRecord, AuthSessionRecord, AuthenticatePasswordInput, + CreatePasswordIdentityInput, CreateSessionInput, CreateShareLinkInput, CreatedShareLink, + DirectoryGrantInput, DirectoryGrantLookup, DirectoryGrantRecord, NavigationRecentRecord, + OutboxEventInput, OutboxEventRecord, ResolvedAccess, ResolvedAuthSession, ShareLinkRecord, + SidebarShortcutRecord, SyncStateRecord, UpsertAiExternalConversationBindingInput, + UpsertAiPolicyInput, UpsertAiRuntimeRunInput, UpsertNavigationRecentInput, + UpsertSidebarShortcutInput, UpsertSyncStateInput, UpsertUserInput, UpsertUserUiPreferenceInput, + UpsertWorkspaceInput, UserRecord, UserUiPreferenceRecord, WorkspaceRecord, }; pub trait ControlPlaneStore: Send + Sync { fn upsert_user(&self, input: UpsertUserInput) -> Result; + /// List users with stable ordering by created_at (ASC), id (ASC) as tiebreaker. + /// Returns at most `limit` records. Passwords are never included. + fn list_users(&self, limit: usize) -> Result, ControlPlaneError>; + fn create_password_identity( &self, input: CreatePasswordIdentityInput, @@ -308,4 +312,36 @@ pub trait ControlPlaneStore: Send + Sync { session_id: &str, workspace_id: Option<&str>, ) -> Result; + + // ----------------------------------------------------------------------- + // P2: AI tool events (receipts) — 7-71 + // ----------------------------------------------------------------------- + + fn append_ai_tool_event( + &self, + input: AppendAiToolEventInput, + ) -> Result; + + fn list_ai_tool_events( + &self, + user_id: &str, + session_id: Option<&str>, + limit: usize, + ) -> Result, ControlPlaneError>; + + // ----------------------------------------------------------------------- + // P2: AI file patches — 7-71 + // ----------------------------------------------------------------------- + + fn append_ai_file_patch( + &self, + input: AppendAiFilePatchInput, + ) -> Result; + + fn list_ai_file_patches( + &self, + user_id: &str, + session_id: Option<&str>, + limit: usize, + ) -> Result, ControlPlaneError>; } diff --git a/rust/crates/control-plane/src/turso.rs b/rust/crates/control-plane/src/turso.rs index daed2c10..702a2013 100644 --- a/rust/crates/control-plane/src/turso.rs +++ b/rust/crates/control-plane/src/turso.rs @@ -15,17 +15,17 @@ use crate::error::ControlPlaneError; use crate::migrations; use crate::model::{ password_hash_v1, share_token_hash_v1, AiAgentProfileAccessRecord, AiAgentProfileGrantRecord, - AiAgentProfileRecord, AiExternalConversationBindingRecord, AiPolicyRecord, - AiRuntimeEventRecord, AiRuntimeJournalEventRecord, AiRuntimeRunRecord, - AppendAiRuntimeEventInput, AppendAuditInput, AuditLogRecord, AuthSessionRecord, - AuthenticatePasswordInput, CreatePasswordIdentityInput, CreateSessionInput, - CreateShareLinkInput, CreatedShareLink, DirectoryGrantInput, DirectoryGrantLookup, - DirectoryGrantRecord, NavigationRecentRecord, OutboxEventInput, OutboxEventRecord, - ResolvedAccess, ResolvedAuthSession, ShareLinkRecord, SidebarShortcutRecord, SyncStateRecord, - UpsertAiExternalConversationBindingInput, UpsertAiPolicyInput, UpsertAiRuntimeRunInput, - UpsertNavigationRecentInput, UpsertSidebarShortcutInput, UpsertSyncStateInput, UpsertUserInput, - UpsertUserUiPreferenceInput, UpsertWorkspaceInput, UserRecord, UserUiPreferenceRecord, - WorkspaceRecord, + AiAgentProfileRecord, AiExternalConversationBindingRecord, AiFilePatchRecord, AiPolicyRecord, + AiRuntimeEventRecord, AiRuntimeJournalEventRecord, AiRuntimeRunRecord, AiToolEventRecord, + AppendAiFilePatchInput, AppendAiRuntimeEventInput, AppendAiToolEventInput, AppendAuditInput, + AuditLogRecord, AuthSessionRecord, AuthenticatePasswordInput, CreatePasswordIdentityInput, + CreateSessionInput, CreateShareLinkInput, CreatedShareLink, DirectoryGrantInput, + DirectoryGrantLookup, DirectoryGrantRecord, NavigationRecentRecord, OutboxEventInput, + OutboxEventRecord, ResolvedAccess, ResolvedAuthSession, ShareLinkRecord, SidebarShortcutRecord, + SyncStateRecord, UpsertAiExternalConversationBindingInput, UpsertAiPolicyInput, + UpsertAiRuntimeRunInput, UpsertNavigationRecentInput, UpsertSidebarShortcutInput, + UpsertSyncStateInput, UpsertUserInput, UpsertUserUiPreferenceInput, UpsertWorkspaceInput, + UserRecord, UserUiPreferenceRecord, WorkspaceRecord, }; use crate::store::ControlPlaneStore; @@ -486,9 +486,9 @@ impl TursoControlPlaneStore { } fn lock_conn(&self) -> Result, ControlPlaneError> { - self.conn - .lock() - .map_err(|error| ControlPlaneError::Storage(format!("libSQL control-plane lock poisoned: {error}"))) + self.conn.lock().map_err(|error| { + ControlPlaneError::Storage(format!("libSQL control-plane lock poisoned: {error}")) + }) } } @@ -1003,6 +1003,49 @@ fn row_to_ai_external_conversation_binding( }) } +fn row_to_ai_tool_event(row: &libsql::Row) -> libsql::Result { + Ok(AiToolEventRecord { + id: row.get(0)?, + user_id: row.get(1)?, + workspace_id: row.get(2)?, + session_id: row.get(3)?, + run_id: row.get(4)?, + provider: row.get(5)?, + provider_session_id: row.get(6)?, + tool_name: row.get(7)?, + allowed: row.get(8)?, + deny_reason: row.get(9)?, + root_uri: row.get(10)?, + page_path: row.get(11)?, + normalized_file_path: row.get(12)?, + diff_summary: row.get(13)?, + citation_count: row.get(14)?, + before_file_version: row.get(15)?, + after_file_version: row.get(16)?, + payload_json: row.get(17)?, + created_at: row.get(18)?, + deleted_at: row.get(19)?, + }) +} + +fn row_to_ai_file_patch(row: &libsql::Row) -> libsql::Result { + Ok(AiFilePatchRecord { + id: row.get(0)?, + user_id: row.get(1)?, + workspace_id: row.get(2)?, + session_id: row.get(3)?, + run_id: row.get(4)?, + tool_event_id: row.get(5)?, + root_uri: row.get(6)?, + relative_path: row.get(7)?, + before_file_version: row.get(8)?, + after_file_version: row.get(9)?, + patch_summary_json: row.get(10)?, + created_at: row.get(11)?, + deleted_at: row.get(12)?, + }) +} + fn derive_ai_runtime_title(payload_json: &str, fallback: &str) -> String { let title = serde_json::from_str::(payload_json) .ok() @@ -1165,6 +1208,22 @@ impl ControlPlaneStore for TursoControlPlaneStore { }) } + fn list_users(&self, limit: usize) -> Result, ControlPlaneError> { + let conn = self.lock_conn()?; + let limit = limit.min(1000).max(1); + let mut stmt = conn.prepare( + "SELECT id, email, username, display_name, role, status, created_at, updated_at, revision + FROM users + ORDER BY created_at ASC, id ASC + LIMIT ?1", + )?; + let rows = stmt + .query_map(params![limit as i64], row_to_user)? + .collect::, _>>() + .map_err(ControlPlaneError::from)?; + Ok(rows) + } + fn create_password_identity( &self, input: CreatePasswordIdentityInput, @@ -3493,6 +3552,153 @@ impl ControlPlaneStore for TursoControlPlaneStore { )?; Ok(changed) } + // ----------------------------------------------------------------------- + // P2: AI tool events (receipts) — 7-71 + // ----------------------------------------------------------------------- + + fn append_ai_tool_event( + &self, + input: AppendAiToolEventInput, + ) -> Result { + if input.user_id.trim().is_empty() || input.session_id.trim().is_empty() { + return Err(ControlPlaneError::InvalidInput( + "ai tool event user_id/session_id 不能为空".to_string(), + )); + } + serde_json::from_str::(&input.payload_json)?; + + let conn = self.lock_conn()?; + let record = AiToolEventRecord { + id: input.id.unwrap_or_else(|| new_id("ate")), + user_id: input.user_id, + workspace_id: input.workspace_id, + session_id: input.session_id, + run_id: input.run_id, + provider: input.provider, + provider_session_id: input.provider_session_id, + tool_name: input.tool_name, + allowed: input.allowed, + deny_reason: input.deny_reason, + root_uri: input.root_uri, + page_path: input.page_path, + normalized_file_path: input.normalized_file_path, + diff_summary: input.diff_summary, + citation_count: input.citation_count, + before_file_version: input.before_file_version, + after_file_version: input.after_file_version, + payload_json: input.payload_json, + created_at: now_text(), + deleted_at: None, + }; + conn.execute( + "INSERT INTO ai_tool_events (id, user_id, workspace_id, session_id, run_id, provider, provider_session_id, tool_name, allowed, deny_reason, root_uri, page_path, normalized_file_path, diff_summary, citation_count, before_file_version, after_file_version, payload_json, created_at) + VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?15, ?16, ?17, ?18, ?19)", + params![ + record.id, record.user_id, record.workspace_id, record.session_id, record.run_id, + record.provider, record.provider_session_id, record.tool_name, record.allowed, record.deny_reason, + record.root_uri, record.page_path, record.normalized_file_path, record.diff_summary, record.citation_count, + record.before_file_version, record.after_file_version, record.payload_json, record.created_at + ], + )?; + Ok(record) + } + + fn list_ai_tool_events( + &self, + user_id: &str, + session_id: Option<&str>, + limit: usize, + ) -> Result, ControlPlaneError> { + let conn = self.lock_conn()?; + let mut stmt = conn.prepare( + "SELECT id, user_id, workspace_id, session_id, run_id, provider, provider_session_id, tool_name, allowed, deny_reason, root_uri, page_path, normalized_file_path, diff_summary, citation_count, before_file_version, after_file_version, payload_json, created_at, deleted_at + FROM ai_tool_events + WHERE user_id = ?1 AND deleted_at IS NULL + AND (?2 IS NULL OR session_id = ?2) + ORDER BY created_at DESC + LIMIT ?3", + )?; + let rows = stmt + .query_map( + params![user_id, session_id, limit as i64], + row_to_ai_tool_event, + )? + .collect::, _>>() + .map_err(ControlPlaneError::from)?; + Ok(rows) + } + + // ----------------------------------------------------------------------- + // P2: AI file patches — 7-71 + // ----------------------------------------------------------------------- + + fn append_ai_file_patch( + &self, + input: AppendAiFilePatchInput, + ) -> Result { + if input.user_id.trim().is_empty() + || input.session_id.trim().is_empty() + || input.tool_event_id.trim().is_empty() + { + return Err(ControlPlaneError::InvalidInput( + "ai file patch user_id/session_id/tool_event_id 不能为空".to_string(), + )); + } + serde_json::from_str::(&input.patch_summary_json)?; + + let conn = self.lock_conn()?; + let record = AiFilePatchRecord { + id: input.id.unwrap_or_else(|| new_id("afp")), + user_id: input.user_id, + workspace_id: input.workspace_id, + session_id: input.session_id, + run_id: input.run_id, + tool_event_id: input.tool_event_id, + root_uri: input.root_uri, + relative_path: input.relative_path, + before_file_version: input.before_file_version, + after_file_version: input.after_file_version, + patch_summary_json: input.patch_summary_json, + created_at: now_text(), + deleted_at: None, + }; + conn.execute( + "INSERT INTO ai_file_patches (id, user_id, workspace_id, session_id, run_id, tool_event_id, root_uri, relative_path, before_file_version, after_file_version, patch_summary_json, created_at) + VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12)", + params![ + record.id, record.user_id, record.workspace_id, record.session_id, record.run_id, + record.tool_event_id, record.root_uri, record.relative_path, + record.before_file_version, record.after_file_version, record.patch_summary_json, record.created_at + ], + )?; + Ok(record) + } + + fn list_ai_file_patches( + &self, + user_id: &str, + session_id: Option<&str>, + limit: usize, + ) -> Result, ControlPlaneError> { + let conn = self.lock_conn()?; + let mut stmt = conn.prepare( + "SELECT id, user_id, workspace_id, session_id, run_id, tool_event_id, root_uri, relative_path, before_file_version, after_file_version, patch_summary_json, created_at, deleted_at + FROM ai_file_patches + WHERE user_id = ?1 + AND deleted_at IS NULL + AND (?2 IS NULL OR session_id = ?2) + ORDER BY created_at DESC + LIMIT ?3", + )?; + let rows = stmt + .query_map( + params![user_id, session_id, limit as i64], + row_to_ai_file_patch, + )? + .collect::, _>>() + .map_err(ControlPlaneError::from)?; + Ok(rows) + } } fn max_permission<'a>(left: &'a str, right: &'a str) -> &'a str { @@ -3582,6 +3788,48 @@ mod tests { assert_eq!(updated.revision, 2); } + #[test] + fn list_users_returns_stable_ordering() { + let store = store(); + + // Create 3 users in known order + let u1 = create_user(&store, "bravo"); + let u2 = create_user(&store, "alpha"); + let u3 = create_user(&store, "charlie"); + + let users = store.list_users(10).expect("list users"); + assert_eq!(users.len(), 3, "should return all three users"); + + // Order must be by created_at ASC, id ASC + // u1 (bravo) created first, u2 (alpha) second, u3 (charlie) third + assert_eq!(users[0].id, u1.id, "first created should be first"); + assert_eq!(users[1].id, u2.id, "second created should be second"); + assert_eq!(users[2].id, u3.id, "third created should be third"); + } + + #[test] + fn list_users_respects_limit() { + let store = store(); + for i in 0..5usize { + create_user(&store, &format!("user{i}")); + } + + let users = store.list_users(3).expect("list users with limit"); + assert_eq!(users.len(), 3, "should respect limit=3"); + } + + #[test] + fn list_users_excludes_password_data() { + let store = store(); + create_user(&store, "nopassword"); + + let users = store.list_users(10).expect("list users"); + assert_eq!(users.len(), 1); + // UserRecord has no password_hash field — this is a compile-time + // guarantee that list_users cannot leak password data. + assert!(users[0].email.is_some()); + } + #[test] fn ensure_default_workspace_creates_owner_grant() { let store = store(); @@ -4757,7 +5005,6 @@ mod tests { .is_none()); } - // --- Fault injection tests --- #[test] @@ -4900,4 +5147,128 @@ mod tests { "expected RateLimit: prefix, got {display}" ); } + + #[test] + fn ai_tool_events_append_and_list() { + let store = store(); + create_user(&store, "tool_user"); + + let event = store + .append_ai_tool_event(AppendAiToolEventInput { + id: None, + user_id: "tool_user".to_string(), + workspace_id: Some("ws_1".to_string()), + session_id: "sess_1".to_string(), + run_id: Some("run_1".to_string()), + provider: "doubao-web".to_string(), + provider_session_id: Some("ps_1".to_string()), + tool_name: "mnote.local_file.read".to_string(), + allowed: true, + deny_reason: None, + root_uri: "file:///tmp".to_string(), + page_path: Some("page.md".to_string()), + normalized_file_path: Some("/tmp/page.md".to_string()), + diff_summary: Some("read file".to_string()), + citation_count: 0, + before_file_version: None, + after_file_version: None, + payload_json: "{}".to_string(), + }) + .expect("append tool event"); + assert_eq!(event.tool_name, "mnote.local_file.read"); + assert!(event.allowed); + assert_eq!(event.citation_count, 0); + + store + .append_ai_tool_event(AppendAiToolEventInput { + id: None, + user_id: "tool_user".to_string(), + workspace_id: Some("ws_1".to_string()), + session_id: "sess_1".to_string(), + run_id: Some("run_2".to_string()), + provider: "reasonix".to_string(), + provider_session_id: None, + tool_name: "fs.write".to_string(), + allowed: false, + deny_reason: Some("path not in allowed roots".to_string()), + root_uri: "file:///etc".to_string(), + page_path: None, + normalized_file_path: Some("/etc/passwd".to_string()), + diff_summary: None, + citation_count: 0, + before_file_version: None, + after_file_version: None, + payload_json: "{}".to_string(), + }) + .expect("append denied event"); + + let events = store + .list_ai_tool_events("tool_user", Some("sess_1"), 10) + .expect("list events"); + assert_eq!(events.len(), 2); + assert_eq!(events[0].tool_name, "fs.write"); + assert!(!events[0].allowed); + + let all_events = store + .list_ai_tool_events("tool_user", None, 10) + .expect("list all"); + assert_eq!(all_events.len(), 2); + } + + #[test] + fn ai_file_patches_append_and_list() { + let store = store(); + create_user(&store, "patch_user"); + + let event = store + .append_ai_tool_event(AppendAiToolEventInput { + id: Some("ate_turso_patch_ref".to_string()), + user_id: "patch_user".to_string(), + workspace_id: None, + session_id: "sess_p1".to_string(), + run_id: None, + provider: "openclaw".to_string(), + provider_session_id: None, + tool_name: "mnote.local_file.patch".to_string(), + allowed: true, + deny_reason: None, + root_uri: "file:///tmp".to_string(), + page_path: Some("test.md".to_string()), + normalized_file_path: Some("/tmp/test.md".to_string()), + diff_summary: Some("edit file".to_string()), + citation_count: 0, + before_file_version: Some("v1".to_string()), + after_file_version: Some("v2".to_string()), + payload_json: "{}".to_string(), + }) + .expect("append reference tool event"); + + let patch = store + .append_ai_file_patch(AppendAiFilePatchInput { + id: None, + user_id: "patch_user".to_string(), + workspace_id: None, + session_id: "sess_p1".to_string(), + run_id: None, + tool_event_id: event.id.clone(), + root_uri: "file:///tmp".to_string(), + relative_path: "test.md".to_string(), + before_file_version: Some("v1".to_string()), + after_file_version: Some("v2".to_string()), + patch_summary_json: r#"{"insertions":5}"#.to_string(), + }) + .expect("append file patch"); + assert_eq!(patch.tool_event_id, event.id); + assert!(patch.deleted_at.is_none()); + + let patches = store + .list_ai_file_patches("patch_user", Some("sess_p1"), 10) + .expect("list patches"); + assert_eq!(patches.len(), 1); + + let all_patches = store + .list_ai_file_patches("patch_user", None, 10) + .expect("list all"); + assert_eq!(all_patches.len(), 1); + } } diff --git a/rust/crates/control-plane/tests/turso_store.rs b/rust/crates/control-plane/tests/turso_store.rs index ebb9ed70..c3c57949 100644 --- a/rust/crates/control-plane/tests/turso_store.rs +++ b/rust/crates/control-plane/tests/turso_store.rs @@ -257,7 +257,9 @@ fn libsql_local_store_handles_parallel_control_plane_writes() { } for handle in handles { - handle.join().expect("parallel writer thread should not panic"); + handle + .join() + .expect("parallel writer thread should not panic"); } assert_eq!( @@ -275,10 +277,7 @@ fn libsql_local_store_handles_parallel_control_plane_writes() { 8 ); assert_eq!( - store - .list_audit_log(20) - .expect("list parallel audit") - .len(), + store.list_audit_log(20).expect("list parallel audit").len(), 8 ); assert_eq!( diff --git a/rust/crates/mnote-web/browser/sidebar-page-ai-pi-lab-runtime.js b/rust/crates/mnote-web/browser/sidebar-page-ai-pi-lab-runtime.js new file mode 100644 index 00000000..5f061bca --- /dev/null +++ b/rust/crates/mnote-web/browser/sidebar-page-ai-pi-lab-runtime.js @@ -0,0 +1,1528 @@ +// == Pi Lab Page AI Runtime == +// MNote-native adapter for Pi-first Page AI Lab. +// Renders an independent floating launcher and drawer. OpenHub remains the +// default Page AI surface; Pi Lab never mounts inside the OpenHub drawer, iframe +// page, provider tab, or page container. NO setInterval polling. +// +// UI note: @earendil-works/pi-web-ui@0.75.3 was checked as the mature upstream UI. +// It expects browser-side pi-agent-core, IndexedDB storage, API-key dialogs, model +// selection and builtin tools/artifacts. MNote's lab backend owns Pi RPC, access +// scope and tools, so this file keeps a host-owned adapter while matching the +// upstream ChatPanel/AgentInterface layout: message list, streaming composer, +// tool timeline, model/runtime controls and artifacts-style right rail. +// +// Default model: Omniroute/freefirst (consumed from backend status/default fields). + +(function () { + 'use strict'; + + var STATE_IDLE = 'idle'; + var STATE_STARTING = 'starting'; + var STATE_STARTED = 'started'; + var STATE_STREAMING = 'streaming'; + var STATE_ABORTED = 'aborted'; + var STATE_ERROR = 'error'; + + var API = { + STATUS: '/api/page-ai/pi/status', + START: '/api/page-ai/pi/start', + SEND: '/api/page-ai/pi/send', + ABORT: '/api/page-ai/pi/abort', + EVENTS: '/api/page-ai/pi/events', + BOOTSTRAP: '/api/page-ai/pi/bootstrap', + SESSIONS: '/api/page-ai/pi/sessions', + EFFECTIVE: '/api/ai-settings/effective', + }; + + var DEFAULT_MODEL_PROVIDER = 'omniroute'; + var DEFAULT_MODEL_ID = 'freefirst'; + + var piLabInstalled = false; + var piLabPanelEl = null; + var piLabDrawerEl = null; + var piLabLauncherEl = null; + var piLabEventSource = null; + var piLabState = { + status: STATE_IDLE, + enabled: false, + active: false, + standalone: false, + sessionId: null, + providerSessionId: null, + defaultModelProvider: DEFAULT_MODEL_PROVIDER, + defaultModelId: DEFAULT_MODEL_ID, + modelProvider: null, + modelId: null, + runtimeMode: null, + runtimePid: null, + disabledBuiltinTools: null, + session: null, + allowedRootsSummary: '', + selectionSummary: '', + selectionText: '', + changedFiles: [], + messages: [], + diagnostics: '', + receipts: [], + modelOptions: [], + history: [], + }; + var streamingAssistantMsg = null; + + function injectStyles() { + var styleId = 'pi-lab-runtime-style'; + if (document.getElementById(styleId)) return; + var style = document.createElement('style'); + style.id = styleId; + style.textContent = + '.wolai-page-ai-pi-lab-launcher{position:fixed;right:26px;bottom:92px;z-index:2600;width:36px;height:36px;border-radius:18px;border:1px solid rgba(37,37,33,.14);background:#fff;color:#252521;box-shadow:0 8px 24px rgba(15,23,42,.16);display:grid;place-items:center;font:600 15px/1 system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;cursor:pointer}' + + '.wolai-page-ai-pi-lab-launcher:hover{background:#f7f7f5;box-shadow:0 10px 28px rgba(15,23,42,.20)}' + + '.wolai-page-ai-pi-lab-launcher[data-state="streaming"]::after{content:"";position:absolute;right:4px;top:4px;width:8px;height:8px;border-radius:50%;background:#10a37f;box-shadow:0 0 0 3px rgba(16,163,127,.14)}' + + '.wolai-page-ai-pi-lab-drawer{position:fixed;right:18px;bottom:18px;top:64px;z-index:2590;width:min(760px,calc(100vw - 36px));border:1px solid rgba(35,35,30,.10);border-radius:20px;background:#f5f6fa;box-shadow:0 24px 70px rgba(15,23,42,.22);overflow:hidden;display:flex;flex-direction:column}' + + '.wolai-page-ai-pi-lab-drawer[hidden]{display:none!important}' + + '.wolai-page-ai-pi-lab-drawer[data-minimized="true"]{top:auto;height:54px;width:min(420px,calc(100vw - 36px))}' + + '.wolai-page-ai-pi-lab-drawer[data-minimized="true"] .wolai-page-ai-pi-lab-config,.wolai-page-ai-pi-lab-drawer[data-minimized="true"] .wolai-page-ai-pi-lab-context-strip,.wolai-page-ai-pi-lab-drawer[data-minimized="true"] .wolai-page-ai-pi-lab-body,.wolai-page-ai-pi-lab-drawer[data-minimized="true"] .wolai-page-ai-pi-lab-diagnostics{display:none!important}' + + '.wolai-page-ai-pi-lab-shell{display:flex;flex-direction:column;height:100%;min-height:0;background:#f5f6fa;color:#242424;font:13px/1.45 system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;overflow:hidden}' + + '.wolai-page-ai-pi-lab-shell[hidden]{display:none!important}' + + '.wolai-page-ai-pi-lab-topbar{height:58px;display:flex;align-items:center;gap:10px;padding:0 18px;background:#f5f6fa;flex:0 0 auto}' + + '.wolai-page-ai-pi-lab-brand{display:flex;align-items:center;gap:8px;min-width:0;flex:1}' + + '.wolai-page-ai-pi-lab-logo{width:30px;height:30px;border-radius:9px;display:grid;place-items:center;background:#1f6feb;color:#fff;font-weight:700}' + + '.wolai-page-ai-pi-lab-title{display:flex;flex-direction:column;gap:1px;min-width:0}' + + '.wolai-page-ai-pi-lab-title strong{font-size:22px;font-weight:760;letter-spacing:0;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}' + + '.wolai-page-ai-pi-lab-title span{font-size:11px;color:#6f6a60;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}' + + '.wolai-page-ai-pi-lab-icon-btn{width:30px;height:30px;border:1px solid #e2ded6;border-radius:8px;background:#fff;color:#514f49;display:grid;place-items:center;cursor:pointer}' + + '.wolai-page-ai-pi-lab-icon-btn:hover{background:#f7f6f2}' + + '.wolai-page-ai-pi-lab-commandbar{height:52px;margin:0 14px 28px;padding:0 14px;border:1px solid #e5e8ef;border-radius:14px;background:#fff;display:flex;align-items:center;gap:14px;box-shadow:0 2px 8px rgba(15,23,42,.04);flex:0 0 auto}' + + '.wolai-page-ai-pi-lab-commandbar .wolai-page-ai-pi-lab-tool-icon{width:28px;height:28px;border:0;background:transparent;color:#30343b;display:grid;place-items:center;font-size:19px;cursor:pointer;border-radius:8px}' + + '.wolai-page-ai-pi-lab-commandbar .wolai-page-ai-pi-lab-tool-icon:hover{background:#f3f5f8}' + + '.wolai-page-ai-pi-lab-commandbar .wolai-page-ai-pi-lab-tool-icon[disabled]{opacity:.35;cursor:default}' + + '.wolai-page-ai-pi-lab-commandbar-spacer{flex:1}' + + '.wolai-page-ai-pi-lab-config{display:none;grid-template-columns:minmax(0,1fr) auto;gap:10px;margin:-18px 14px 12px;padding:10px 12px;border:1px solid #e5e8ef;border-radius:12px;background:#fff;box-shadow:0 4px 14px rgba(15,23,42,.05);flex:0 0 auto}' + + '.wolai-page-ai-pi-lab-drawer[data-config-open="true"] .wolai-page-ai-pi-lab-config{display:grid}' + + '.wolai-page-ai-pi-lab-model-row{display:flex;flex-wrap:wrap;gap:6px;min-width:0}' + + '.wolai-page-ai-pi-lab-settings{border:0;min-width:0}' + + '.wolai-page-ai-pi-lab-settings>summary{display:inline-flex;align-items:center;gap:6px;min-height:28px;cursor:pointer;list-style:none;color:#514f49;font-size:12px}' + + '.wolai-page-ai-pi-lab-settings>summary::-webkit-details-marker{display:none}' + + '.wolai-page-ai-pi-lab-settings>summary::before{content:"▸";font-size:10px;color:#8a8378}' + + '.wolai-page-ai-pi-lab-settings[open]>summary::before{content:"▾"}' + + '.wolai-page-ai-pi-lab-settings-grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:8px;margin-top:8px;max-width:560px}' + + '.wolai-page-ai-pi-lab-history-panel{margin:0 18px 10px;border:1px solid #e2ded6;border-radius:8px;background:#fff;max-height:220px;overflow:auto}' + + '.wolai-page-ai-pi-lab-history-panel[hidden]{display:none!important}' + + '.wolai-page-ai-pi-lab-history-row{width:100%;border:0;border-bottom:1px solid #f0eee9;background:#fff;padding:10px 12px;text-align:left;cursor:pointer;display:flex;justify-content:space-between;gap:10px}' + + '.wolai-page-ai-pi-lab-history-row:hover{background:#f8f7f4}' + + '.wolai-page-ai-pi-lab-history-row strong{display:block;font-size:12px;color:#2e2c28}' + + '.wolai-page-ai-pi-lab-history-row span{font-size:11px;color:#817b72}' + + '.wolai-page-ai-pi-lab-field{display:flex;flex-direction:column;gap:4px;font-size:11px;color:#6f6a60}' + + '.wolai-page-ai-pi-lab-field select,.wolai-page-ai-pi-lab-field input{height:30px;border:1px solid #ddd8cf;border-radius:8px;background:#fff;color:#242424;padding:0 8px;font:12px/1.3 inherit;min-width:0}' + + '.wolai-page-ai-pi-lab-context-strip{display:none;padding:0;margin:-6px 14px 12px;border:1px solid #ebe7de;border-radius:12px;background:#faf9f6;flex:0 0 auto}' + + '.wolai-page-ai-pi-lab-drawer[data-config-open="true"] .wolai-page-ai-pi-lab-context-strip{display:block}' + + '.wolai-page-ai-pi-lab-context-strip>summary{display:flex;align-items:center;gap:8px;min-height:34px;padding:0 12px;cursor:pointer;list-style:none;color:#5d594f;font-size:12px}' + + '.wolai-page-ai-pi-lab-context-strip>summary::-webkit-details-marker{display:none}' + + '.wolai-page-ai-pi-lab-context-strip>summary::before{content:"▸";font-size:10px;color:#8a8378}' + + '.wolai-page-ai-pi-lab-context-strip[open]>summary::before{content:"▾"}' + + '.wolai-page-ai-pi-lab-context-title{font-weight:650;color:#42403a}' + + '.wolai-page-ai-pi-lab-context-current{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:#242424;font-weight:650}' + + '.wolai-page-ai-pi-lab-context-count{margin-left:auto;color:#8a8378;font-size:11px}' + + '.wolai-page-ai-pi-lab-context-content{display:flex;align-items:center;gap:6px;padding:0 12px 8px;overflow-x:auto}' + + '.wolai-page-ai-pi-lab-chip{height:24px;display:inline-flex;align-items:center;gap:5px;border:1px solid #e4e0d8;border-radius:999px;background:#f8f7f3;color:#514f49;padding:0 8px;font-size:11px;max-width:100%}' + + '.wolai-page-ai-pi-lab-chip strong{font-weight:650;color:#242424;min-width:0;overflow:hidden;text-overflow:ellipsis}' + + '.wolai-page-ai-pi-lab-context-strip .wolai-page-ai-pi-lab-chip{flex:0 0 auto}' + + '.wolai-page-ai-pi-lab-chip[data-tone="ok"]{background:#eef8f3;border-color:#ccebdc;color:#176b4b}' + + '.wolai-page-ai-pi-lab-chip[data-tone="warn"]{background:#fff6e6;border-color:#f2dfb5;color:#865b13}' + + '.wolai-page-ai-pi-lab-chip[data-tone="danger"]{background:#fff0ee;border-color:#f2c4bd;color:#a73b2f}' + + '.wolai-page-ai-pi-lab-actions{display:flex;align-items:center;gap:6px;justify-content:flex-end}' + + '.wolai-page-ai-pi-lab-btn{height:28px;border:1px solid #d9d4ca;border-radius:7px;background:#fff;color:#383631;font-size:12px;padding:0 10px;cursor:pointer;white-space:nowrap}' + + '.wolai-page-ai-pi-lab-btn:hover{background:#f7f6f2}' + + '.wolai-page-ai-pi-lab-btn:disabled{opacity:.45;cursor:default}' + + '.wolai-page-ai-pi-lab-btn-primary{background:#1f6feb;border-color:#1f6feb;color:#fff}' + + '.wolai-page-ai-pi-lab-btn-primary:hover{background:#1b61cf}' + + '.wolai-page-ai-pi-lab-btn-danger{background:#d93025;border-color:#d93025;color:#fff}' + + '.wolai-page-ai-pi-lab-body{display:block;min-height:0;flex:1;background:#f5f6fa;padding:0 14px 12px}' + + '.wolai-page-ai-pi-lab-main{display:flex;flex-direction:column;min-width:0;min-height:0;height:100%}' + + '.wolai-page-ai-pi-lab-messages{flex:1;min-height:0;overflow-y:auto;padding:22px 18px 20px;display:flex;flex-direction:column;gap:12px;overscroll-behavior:contain;background:#fff;border:1px solid #e4e7ef;border-radius:22px 22px 0 0;box-shadow:0 12px 36px rgba(15,23,42,.08)}' + + '.wolai-page-ai-pi-lab-empty{margin:auto;max-width:460px;text-align:center;color:#8a9099;background:transparent;border:0;border-radius:0;padding:10px 0 4px;box-shadow:none}' + + '.wolai-page-ai-pi-lab-empty-icon{width:76px;height:76px;margin:0 auto 18px;border-radius:50%;background:#f0f2f6;color:#8a93a2;display:grid;place-items:center;font-size:42px;font-weight:400}' + + '.wolai-page-ai-pi-lab-empty strong{display:block;color:#242833;margin-bottom:8px;font-size:25px;font-weight:760;letter-spacing:0}' + + '.wolai-page-ai-pi-lab-empty p{margin:0 0 20px;color:#8a9099;font-size:16px}' + + '.wolai-page-ai-pi-lab-examples{display:flex;flex-direction:column;align-items:center;gap:10px}' + + '.wolai-page-ai-pi-lab-example{height:42px;min-width:min(390px,100%);border:1px solid #e1e4eb;border-radius:12px;background:#fff;color:#4a4f58;font-size:16px;display:flex;align-items:center;justify-content:flex-start;gap:12px;padding:0 18px;box-shadow:0 3px 9px rgba(15,23,42,.05);cursor:pointer}' + + '.wolai-page-ai-pi-lab-example:hover{background:#f8fafc}' + + '.wolai-page-ai-pi-lab-example span{font-size:18px;color:#5c6470}' + + '.wolai-page-ai-pi-lab-message{display:flex;flex-direction:column;gap:6px;max-width:92%}' + + '.wolai-page-ai-pi-lab-message[data-role="user"]{align-self:flex-end;align-items:flex-end}' + + '.wolai-page-ai-pi-lab-message[data-role="assistant"],.wolai-page-ai-pi-lab-message[data-role="system"]{align-self:stretch}' + + '.wolai-page-ai-pi-lab-role{display:flex;align-items:center;gap:6px;color:#777166;font-size:11px;font-weight:650}' + + '.wolai-page-ai-pi-lab-message[data-role="user"] .wolai-page-ai-pi-lab-role{justify-content:flex-end}' + + '.wolai-page-ai-pi-lab-bubble{border:1px solid #e6e2da;border-radius:12px;background:#fff;padding:10px 12px;color:#272521;word-break:break-word;box-shadow:0 4px 14px rgba(15,23,42,.035)}' + + '.wolai-page-ai-pi-lab-message[data-role="user"] .wolai-page-ai-pi-lab-bubble{background:#f3f7ff;border-color:#d9e6ff}' + + '.wolai-page-ai-pi-lab-text{white-space:pre-wrap}' + + '.wolai-page-ai-pi-lab-text.streaming-cursor::after{content:"";display:inline-block;width:7px;height:14px;margin-left:3px;vertical-align:-2px;background:#1f6feb;animation:pi-blink .85s steps(2,start) infinite}' + + '@keyframes pi-blink{50%{opacity:.18}}' + + '.wolai-page-ai-pi-lab-tool-calls,.wolai-page-ai-pi-lab-citations{display:flex;flex-direction:column;gap:6px;margin-top:8px}' + + '.wolai-page-ai-pi-lab-tool-call{border:1px solid #e5e0d8;border-radius:9px;background:#faf9f6;overflow:hidden}' + + '.wolai-page-ai-pi-lab-tool-call-header{display:flex;align-items:center;justify-content:space-between;gap:8px;padding:7px 9px;font-size:12px;font-weight:650;color:#42403a}' + + '.wolai-page-ai-pi-lab-tool-call-header span{font-size:11px;color:#777166;font-weight:500}' + + '.wolai-page-ai-pi-lab-tool-call pre{margin:0;border-top:1px solid #ebe7de;background:#fff;padding:8px;max-height:140px;overflow:auto;font:11px/1.45 ui-monospace,SFMono-Regular,Menlo,monospace;color:#42403a;white-space:pre-wrap}' + + '.wolai-page-ai-pi-lab-citation{display:inline-flex;align-items:center;gap:6px;width:max-content;max-width:100%;border:1px solid #d9e6ff;border-radius:999px;background:#f3f7ff;color:#2456a6;text-decoration:none;padding:4px 8px;font-size:11px}' + + '.wolai-page-ai-pi-lab-diff{display:inline-flex;align-items:center;width:max-content;max-width:100%;margin-top:8px;border:1px solid #f0dcb7;border-radius:999px;background:#fff7e8;color:#865b13;padding:4px 8px;font-size:11px}' + + '.wolai-page-ai-pi-lab-composer{flex:0 0 auto;border:1px solid #e4e7ef;border-top:0;border-radius:0 0 22px 22px;background:#fff;box-shadow:0 14px 34px rgba(15,23,42,.09);overflow:hidden}' + + '.wolai-page-ai-pi-lab-input{width:100%;min-height:94px;max-height:190px;box-sizing:border-box;border:0;resize:none;padding:20px 22px 10px;font:18px/1.45 inherit;color:#242424;background:#f7f8fb;outline:none}' + + '.wolai-page-ai-pi-lab-input::placeholder{color:#b6bbc5}' + + '.wolai-page-ai-pi-lab-composer-bar{height:48px;display:flex;align-items:center;gap:8px;padding:0 14px;border-top:1px solid #eef0f5;background:#fff}' + + '.wolai-page-ai-pi-lab-quick{height:24px;border:1px solid #e5e0d8;border-radius:999px;background:#f8f7f3;color:#5d594f;font-size:11px;padding:0 8px;cursor:pointer}' + + '.wolai-page-ai-pi-lab-modebar{height:52px;display:flex;align-items:center;gap:10px;padding:0 14px;border-top:1px solid #eef0f5;background:#fff}' + + '.wolai-page-ai-pi-lab-square{width:36px;height:36px;border:1px solid #e1e4eb;border-radius:9px;background:#fff;color:#242833;display:grid;place-items:center;font-size:19px;cursor:pointer}' + + '.wolai-page-ai-pi-lab-segment{display:inline-flex;border:1px solid #e1e4eb;border-radius:10px;overflow:hidden;background:#fff}' + + '.wolai-page-ai-pi-lab-segment button{height:36px;border:0;background:#fff;color:#4a4f58;padding:0 16px;font:14px/1 inherit;cursor:pointer}' + + '.wolai-page-ai-pi-lab-segment button[data-active=\"true\"]{background:#111827;color:#fff}' + + '.wolai-page-ai-pi-lab-model-control{height:36px;min-width:190px;border:1px solid #e1e4eb;border-radius:10px;background:#fff;color:#4a4f58;padding:0 12px;font:13px/1 inherit}' + + '.wolai-page-ai-pi-lab-budget{height:34px;border:1px solid #bfe6ac;border-radius:10px;background:#f4fff0;color:#329125;padding:0 12px;display:inline-flex;align-items:center;font-size:14px}' + + '.wolai-page-ai-pi-lab-spacer{flex:1}' + + '.wolai-page-ai-pi-lab-send{width:52px;height:52px;border:0;border-radius:15px;background:#1d9bf0;color:#fff;display:grid;place-items:center;cursor:pointer;font-size:24px;box-shadow:0 10px 24px rgba(29,155,240,.25)}' + + '.wolai-page-ai-pi-lab-send:disabled{opacity:.45;cursor:default}' + + '.wolai-page-ai-pi-lab-rail{display:none}' + + '.wolai-page-ai-pi-lab-rail-section{border:1px solid #e5e0d8;border-radius:10px;background:#fff;overflow:hidden}' + + '.wolai-page-ai-pi-lab-rail-section>summary{display:flex;align-items:center;justify-content:space-between;gap:8px;cursor:pointer;list-style:none;padding:8px 9px;font-size:11px;font-weight:650;color:#5d594f;background:#faf9f6}' + + '.wolai-page-ai-pi-lab-rail-section>summary::-webkit-details-marker{display:none}' + + '.wolai-page-ai-pi-lab-rail-section>summary::after{content:"▸";font-size:10px;color:#8a8378}' + + '.wolai-page-ai-pi-lab-rail-section[open]>summary::after{content:"▾"}' + + '.wolai-page-ai-pi-lab-rail-count{font-weight:600;color:#8a8378}' + + '.wolai-page-ai-pi-lab-rail-title{padding:8px 9px;border-bottom:1px solid #eee9e0;font-size:11px;font-weight:650;color:#5d594f;background:#faf9f6}' + + '.wolai-page-ai-pi-lab-tool-list{display:flex;flex-direction:column;gap:5px;padding:8px}' + + '.wolai-page-ai-pi-lab-tool-pill{border:1px solid #e6e2da;border-radius:7px;background:#fff;color:#42403a;padding:5px 7px;font-size:11px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}' + + '.wolai-page-ai-pi-lab-receipts{display:flex;flex-direction:column;gap:5px;padding:8px;max-height:170px;overflow:auto}' + + '.wolai-page-ai-pi-lab-receipt{border-radius:7px;background:#f8f7f3;border:1px solid #e6e2da;padding:6px;font-size:11px;color:#4d4941}' + + '.wolai-page-ai-pi-lab-receipt[data-allowed="false"]{background:#fff0ee;border-color:#f2c4bd;color:#9f352c}' + + '.wolai-page-ai-pi-lab-diagnostics{display:none;border-top:1px solid #e6e2da;background:#fff;flex:0 0 auto}' + + '.wolai-page-ai-pi-lab-drawer[data-config-open="true"] .wolai-page-ai-pi-lab-diagnostics{display:block}' + + '.wolai-page-ai-pi-lab-diagnostics>summary{cursor:pointer;padding:8px 12px;font-size:11px;color:#6f6a60}' + + '.wolai-page-ai-pi-lab-diagnostics pre{margin:0;padding:0 12px 10px;white-space:pre-wrap;word-break:break-word;font:11px/1.45 ui-monospace,SFMono-Regular,Menlo,monospace;color:#5d594f}' + + '@media (max-width: 760px){.wolai-page-ai-pi-lab-drawer{left:10px;right:10px;top:58px;bottom:10px;width:auto}.wolai-page-ai-pi-lab-body{grid-template-columns:1fr}.wolai-page-ai-pi-lab-rail{display:none}.wolai-page-ai-pi-lab-config{grid-template-columns:1fr}}'; + document.head.appendChild(style); + } + + function escapeHtml(str) { + if (str == null) return ''; + return String(str) + .replace(/&/g, '&') + .replace(//g, '>') + .replace(/"/g, '"') + .replace(/'/g, '''); + } + + function el(tag, attrs, children) { + var elem = document.createElement(tag); + if (attrs) { + Object.keys(attrs).forEach(function (key) { + if (key === 'className') elem.className = attrs[key]; + else if (key === 'textContent') elem.textContent = attrs[key]; + else if (key === 'innerHTML') elem.innerHTML = attrs[key]; + else if (key === 'style' && attrs[key] && typeof attrs[key] === 'object') Object.keys(attrs[key]).forEach(function (styleKey) { elem.style[styleKey] = attrs[key][styleKey]; }); + else elem.setAttribute(key, attrs[key]); + }); + } + if (children) { + (Array.isArray(children) ? children : [children]).forEach(function (child) { + if (typeof child === 'string') elem.appendChild(document.createTextNode(child)); + else if (child instanceof Node) elem.appendChild(child); + }); + } + return elem; + } + + function normalizeSlashes(value) { + return String(value || '').trim().replace(/\\/g, '/'); + } + + function currentUrl() { + try { + return new URL(window.location.href); + } catch (_) { + return new URL('/', window.location.origin); + } + } + + function currentDocumentId() { + var fromBody = document.body && document.body.dataset ? String(document.body.dataset.documentId || '').trim() : ''; + if (fromBody) return fromBody; + var pageTab = document.querySelector('[data-mnote-main-tab="page"]'); + if (pageTab instanceof HTMLElement) { + var tabDocumentId = String(pageTab.getAttribute('data-document-id') || '').trim(); + if (tabDocumentId) return tabDocumentId; + } + var match = currentUrl().pathname.match(/^\/documents\/([^/]+)/); + return match ? decodeURIComponent(match[1]) : ''; + } + + function currentWorkspaceId() { + return currentUrl().searchParams.get('workspaceId') || (document.body && document.body.dataset ? String(document.body.dataset.workspaceId || '').trim() : ''); + } + + function currentRootUri() { + return currentUrl().searchParams.get('rootUri') || ''; + } + + function localMarkdownRelativePathFromDocumentId(documentId) { + var value = String(documentId || '').trim(); + if (!value.startsWith('local-md:')) return ''; + return value.slice('local-md:'.length).replace(/~2F/g, '/'); + } + + function currentSelectionText() { + try { + var selection = window.getSelection ? window.getSelection() : null; + return selection ? String(selection.toString() || '').trim() : ''; + } catch (_) { + return ''; + } + } + + function activeEditorSnapshot() { + try { + var snapshot = window.__mnoteDocumentPaneRuntime + && typeof window.__mnoteDocumentPaneRuntime.getOpenEditorsSnapshot === 'function' + ? window.__mnoteDocumentPaneRuntime.getOpenEditorsSnapshot() + : null; + if (!snapshot || typeof snapshot !== 'object') return null; + if (snapshot.activeEditor) return snapshot.activeEditor; + var entries = [] + .concat(Array.isArray(snapshot.editors) ? snapshot.editors : []) + .concat(Array.isArray(snapshot.resourceEditors) ? snapshot.resourceEditors : []); + return entries.find(function (entry) { return entry && entry.active === true; }) || entries[0] || null; + } catch (_) { + return null; + } + } + + function currentPageContext() { + var active = activeEditorSnapshot() || {}; + var workspacePath = active.workspacePath && typeof active.workspacePath === 'object' ? active.workspacePath : {}; + var documentId = String(workspacePath.documentId || active.documentId || currentDocumentId() || '').trim(); + var pagePath = normalizeSlashes(workspacePath.relativePath || workspacePath.path || active.relativePath || active.path || localMarkdownRelativePathFromDocumentId(documentId)); + var rootUri = String(workspacePath.rootUri || active.rootUri || currentRootUri() || '').trim(); + var workspaceId = String(workspacePath.workspaceId || active.workspaceId || currentWorkspaceId() || '').trim(); + var titleNode = document.querySelector('[data-page-title-current="true"]') || document.querySelector('.wolai-breadcrumb-current'); + var title = String(active.title || workspacePath.title || (titleNode && titleNode.textContent) || document.title || '').trim(); + var selection = currentSelectionText(); + return { + pageId: documentId, + pagePath: pagePath, + pageTitle: title, + rootUri: rootUri, + workspaceId: workspaceId, + selection: selection, + }; + } + + function refreshSelectionSummary() { + var selection = currentSelectionText(); + if (selection) piLabState.selectionText = selection; + var visibleSelection = selection || piLabState.selectionText; + piLabState.selectionSummary = visibleSelection ? ('已选中 ' + visibleSelection.length + ' 字') : ''; + return visibleSelection; + } + + function applyCurrentContextToState() { + var context = currentPageContext(); + refreshSelectionSummary(); + if (!piLabState.session) piLabState.session = {}; + if (context.pagePath && !piLabState.session.pagePath) piLabState.session.pagePath = context.pagePath; + if (context.pageTitle && !piLabState.session.pageTitle) piLabState.session.pageTitle = context.pageTitle; + if (context.rootUri && !piLabState.session.rootUri) piLabState.session.rootUri = context.rootUri; + if (context.workspaceId && !piLabState.session.workspaceId) piLabState.session.workspaceId = context.workspaceId; + updateContextStrip(); + return context; + } + + function currentModelLabel() { + var provider = piLabState.modelProvider || piLabState.defaultModelProvider || DEFAULT_MODEL_PROVIDER; + var modelId = piLabState.modelId || piLabState.defaultModelId || DEFAULT_MODEL_ID; + if (String(modelId).indexOf(provider + '/') === 0) modelId = String(modelId).slice(provider.length + 1); + return [provider, modelId].filter(Boolean).join('/'); + } + + function applyModelControls() { + if (!piLabPanelEl) return; + var providerSelect = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model-provider]'); + var modelSelect = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model-id]'); + var bottomModelSelect = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model-id-bottom]'); + var customInput = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model-custom]'); + if (providerSelect && providerSelect.value) piLabState.modelProvider = providerSelect.value; + if (customInput && customInput.value.trim()) piLabState.modelId = customInput.value.trim(); + else if (modelSelect && modelSelect.value) piLabState.modelId = modelSelect.value; + else if (bottomModelSelect && bottomModelSelect.value) piLabState.modelId = bottomModelSelect.value; + updateModelLabel(); + } + + function splitModelRef(value) { + var raw = String(value || '').trim(); + var slash = raw.indexOf('/'); + if (slash < 0) return { provider: DEFAULT_MODEL_PROVIDER, modelId: raw || DEFAULT_MODEL_ID }; + return { provider: raw.slice(0, slash), modelId: raw.slice(slash + 1) }; + } + + function applyEffectiveConfig(data) { + data = data || {}; + var defaultRef = splitModelRef(data.defaultModel || data.default_model || ''); + piLabState.defaultModelProvider = defaultRef.provider || DEFAULT_MODEL_PROVIDER; + piLabState.defaultModelId = defaultRef.modelId || DEFAULT_MODEL_ID; + piLabState.modelOptions = Array.isArray(data.models) ? data.models : []; + if (Array.isArray(data.allowedRoots)) { + piLabState.allowedRootsSummary = data.allowedRoots.length + ' roots'; + } + if (!piLabPanelEl) return; + var providerSelect = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model-provider]'); + var modelSelect = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model-id]'); + var bottomModelSelect = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model-id-bottom]'); + var providers = []; + piLabState.modelOptions.forEach(function (item) { + var provider = String(item.provider || DEFAULT_MODEL_PROVIDER); + if (providers.indexOf(provider) < 0) providers.push(provider); + }); + if (!providers.length) providers.push(piLabState.defaultModelProvider); + if (providerSelect) { + providerSelect.innerHTML = providers.map(function (provider) { + return ''; + }).join(''); + providerSelect.value = piLabState.modelProvider || piLabState.defaultModelProvider; + } + var modelOptions = piLabState.modelOptions.length ? piLabState.modelOptions : [{ + provider: piLabState.defaultModelProvider, + id: piLabState.defaultModelId, + name: piLabState.defaultModelId, + }]; + var optionHtml = modelOptions.map(function (item) { + var id = String(item.id || item.modelId || item.name || DEFAULT_MODEL_ID); + var label = String(item.name || id); + return ''; + }).join(''); + if (modelSelect) modelSelect.innerHTML = optionHtml; + if (bottomModelSelect) bottomModelSelect.innerHTML = optionHtml; + updateModelLabel(); + updateContextStrip(); + } + + function loadEffectiveConfig() { + return fetch(API.EFFECTIVE, { credentials: 'same-origin', cache: 'no-store' }) + .then(function (response) { + if (!response.ok) throw new Error('Effective config failed: ' + response.status); + return response.json(); + }) + .then(function (data) { + applyEffectiveConfig(data); + return data; + }); + } + + function currentRuntimeLabel() { + var parts = []; + if (piLabState.runtimeMode) parts.push(piLabState.runtimeMode); + if (piLabState.runtimePid) parts.push('pid ' + piLabState.runtimePid); + return parts.join(' · ') || 'runtime pending'; + } + + function statusTone() { + if (!piLabState.enabled || piLabState.status === STATE_ERROR) return 'danger'; + if (piLabState.status === STATE_STREAMING || piLabState.status === STATE_STARTED) return 'ok'; + if (piLabState.status === STATE_STARTING || piLabState.status === STATE_ABORTED) return 'warn'; + return ''; + } + + function statusText() { + if (!piLabState.enabled) return 'disabled'; + if (piLabState.status === STATE_IDLE) return 'idle'; + if (piLabState.status === STATE_STARTING) return 'starting'; + if (piLabState.status === STATE_STARTED) return 'ready'; + if (piLabState.status === STATE_STREAMING) return 'streaming'; + if (piLabState.status === STATE_ABORTED) return 'aborted'; + return 'error'; + } + + function piLabPanelHTML() { + return '' + + '
' + + '
' + + '
' + + '' + + '
Pi Lab 平台默认模型：omniroute/freefirst
' + + '
' + + '' + + '' + + '
' + + '
' + + '' + + '' + + '' + + '' + + '' + + '' + + '' + + '' + + '' + + '' + + '
' + + '
' + + '
' + + 'idle设置omniroute/freefirst' + + '
' + + '' + + '' + + '' + + 'runtimeruntime pending' + + 'builtin disabledbash/read/write/edit' + + '
' + + '
' + + '
' + + '操作见顶部工具栏' + + '
' + + '
' + + '' + + '
' + + '上下文未绑定0 changed' + + '
' + + '选区无选区' + + 'allowed rootspending' + + 'LightRAGdefault' + + '
' + + '
' + + '
' + + '
' + + '
' + + '
' + + '' + + '
' + + '' + + '' + + '' + + '' + + '' + + '
' + + '
' + + '' + + '' + + '' + + '' + + '不限' + + '' + + '' + + '
' + + '
' + + '
' + + '' + + '
' + + '
' + + '诊断' + + '
' +
+        '
' +
+      '
';
+  }
+
+  function renderEmptyState(container) {
+    container.innerHTML = '' +
+      '
' +
+        '
?
' +
+        '开始对话' +
+        '
试试以下示例，或直接输入您的指令
' +
+        '
' +
+          '' +
+          '' +
+          '' +
+          '' +
+          '' +
+        '
' +
+      '
';
+  }
+
+  function renderHistory() {
+    if (!piLabPanelEl) return;
+    var panel = piLabPanelEl.querySelector('[data-page-ai-pi-lab-history-panel]');
+    if (!panel) return;
+    if (!piLabState.history.length) {
+      panel.innerHTML = '
暂无 Pi Lab 历史
';
+      return;
+    }
+    panel.innerHTML = piLabState.history.map(function (session) {
+      var title = escapeHtml(session.title || session.preview || session.pageTitle || '未命名会话');
+      var meta = escapeHtml([session.status, session.modelId, session.updatedAt].filter(Boolean).join(' · '));
+      return '';
+    }).join('');
+  }
+
+  function loadHistory() {
+    return fetch(API.SESSIONS + '?limit=50', { credentials: 'same-origin', cache: 'no-store' })
+      .then(function (response) {
+        if (!response.ok) throw new Error('History failed: ' + response.status);
+        return response.json();
+      })
+      .then(function (data) {
+        piLabState.history = Array.isArray(data.sessions) ? data.sessions : [];
+        renderHistory();
+        return data;
+      });
+  }
+
+  function openHistorySession(sessionId) {
+    if (!sessionId) return Promise.resolve();
+    return Promise.all([
+      fetch(API.SESSIONS + '/' + encodeURIComponent(sessionId), { credentials: 'same-origin', cache: 'no-store' }).then(function (r) { return r.json(); }),
+      fetch(API.SESSIONS + '/' + encodeURIComponent(sessionId) + '/events?limit=500', { credentials: 'same-origin', cache: 'no-store' }).then(function (r) { return r.json(); }),
+    ]).then(function (results) {
+      var detail = results[0] && results[0].session || {};
+      var events = results[1] && Array.isArray(results[1].events) ? results[1].events : [];
+      piLabState.sessionId = detail.sessionId || sessionId;
+      piLabState.session = detail.runtime || detail;
+      piLabState.messages = [];
+      events.forEach(function (event) {
+        var payload = event.payload || {};
+        if (event.eventType === 'user_prompt' && payload.message) {
+          piLabState.messages.push({ role: 'user', text: payload.message });
+        }
+        if (event.eventType === 'pi_rpc_event') {
+          var delta = payload.assistantMessageEvent && payload.assistantMessageEvent.delta;
+          if (delta) piLabState.messages.push({ role: 'assistant', text: delta });
+        }
+      });
+      updateMessages();
+      updateConfig();
+    });
+  }
+
+  function renderMessage(msg) {
+    var card = el('article', {
+      className: 'wolai-page-ai-pi-lab-message',
+      'data-role': msg.role || 'assistant',
+      'data-page-ai-pi-lab-message-role': msg.role || 'assistant',
+    });
+    if (msg.status === 'streaming') card.setAttribute('data-page-ai-pi-lab-streaming', 'true');
+    var role = msg.role === 'assistant' ? 'Pi' : (msg.role === 'user' ? 'You' : 'System');
+    var meta = msg.status === 'streaming' ? 'streaming' : (msg.meta || '');
+    card.appendChild(el('div', { className: 'wolai-page-ai-pi-lab-role' }, role + (meta ? ' · ' + meta : '')));
+    var bubble = el('div', { className: 'wolai-page-ai-pi-lab-bubble' });
+    if (msg.text) {
+      bubble.appendChild(el('div', {
+        className: 'wolai-page-ai-pi-lab-text' + (msg.status === 'streaming' ? ' streaming-cursor' : ''),
+        innerHTML: escapeHtml(msg.text).replace(/\n/g, '
'),
+      }));
+    }
+    if (msg.toolCalls && msg.toolCalls.length) {
+      var tools = el('div', { className: 'wolai-page-ai-pi-lab-tool-calls' });
+      msg.toolCalls.forEach(function (tc) {
+        var item = el('div', { className: 'wolai-page-ai-pi-lab-tool-call', 'data-page-ai-pi-lab-tool-call': tc.name || 'tool' });
+        item.appendChild(el('div', { className: 'wolai-page-ai-pi-lab-tool-call-header', innerHTML: '' + escapeHtml(tc.name || 'tool') + '' + escapeHtml(tc.status || '') + '' }));
+        if (tc.args) item.appendChild(el('pre', { textContent: JSON.stringify(tc.args, null, 2) }));
+        if (tc.result) item.appendChild(el('pre', { textContent: typeof tc.result === 'string' ? tc.result : JSON.stringify(tc.result, null, 2) }));
+        tools.appendChild(item);
+      });
+      bubble.appendChild(tools);
+    }
+    if (msg.citations && msg.citations.length) {
+      var citations = el('div', { className: 'wolai-page-ai-pi-lab-citations' });
+      msg.citations.forEach(function (cit, i) {
+        citations.appendChild(el('a', {
+          className: 'wolai-page-ai-pi-lab-citation',
+          href: cit.url || '#',
+          target: '_blank',
+          rel: 'noopener',
+          'data-page-ai-pi-lab-citation': cit.source || '',
+        }, '[' + (i + 1) + '] ' + (cit.title || cit.source || 'source')));
+      });
+      bubble.appendChild(citations);
+    }
+    if (msg.diffSummary) {
+      var files = msg.diffSummary.files || [];
+      bubble.appendChild(el('div', { className: 'wolai-page-ai-pi-lab-diff', 'data-page-ai-pi-lab-diff': 'true' }, 'patch · ' + files.join(', ')));
+    }
+    card.appendChild(bubble);
+    return card;
+  }
+
+  function isVisibleMessage(msg) {
+    if (!msg) return false;
+    if (msg.status === 'streaming') return true;
+    if (String(msg.text || '').trim()) return true;
+    if (msg.toolCalls && msg.toolCalls.length) return true;
+    if (msg.citations && msg.citations.length) return true;
+    if (msg.diffSummary) return true;
+    return msg.role !== 'assistant';
+  }
+
+  function updateStatusBadge() {
+    updateConfig();
+  }
+
+  function updateModelLabel() {
+    if (!piLabPanelEl) return;
+    var titleLabel = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model]');
+    var modelChip = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model-chip]');
+    var providerSelect = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model-provider]');
+    var modelSelect = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model-id]');
+    var bottomModelSelect = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model-id-bottom]');
+    var customInput = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model-custom]');
+    var provider = piLabState.modelProvider || piLabState.defaultModelProvider || DEFAULT_MODEL_PROVIDER;
+    var modelId = piLabState.modelId || piLabState.defaultModelId || DEFAULT_MODEL_ID;
+    if (String(modelId).indexOf(provider + '/') === 0) {
+      modelId = String(modelId).slice(provider.length + 1);
+      piLabState.modelId = modelId;
+    }
+    if (titleLabel) titleLabel.textContent = '默认模型：' + currentModelLabel();
+    if (modelChip) modelChip.textContent = currentModelLabel();
+    if (providerSelect && providerSelect.value !== provider) providerSelect.value = provider;
+    if (modelSelect && modelSelect.value !== modelId && Array.prototype.some.call(modelSelect.options, function (option) { return option.value === modelId; })) {
+      modelSelect.value = modelId;
+    }
+    if (bottomModelSelect && bottomModelSelect.value !== modelId && Array.prototype.some.call(bottomModelSelect.options, function (option) { return option.value === modelId; })) {
+      bottomModelSelect.value = modelId;
+    }
+    if (customInput && modelId !== DEFAULT_MODEL_ID && modelId !== 'freefirst') customInput.value = modelId;
+  }
+
+  function updateConfig() {
+    if (!piLabPanelEl) return;
+    updateModelLabel();
+    var statusChip = piLabPanelEl.querySelector('[data-page-ai-pi-lab-status-chip]');
+    var statusNode = piLabPanelEl.querySelector('[data-page-ai-pi-lab-status-text]');
+    var runtimeNode = piLabPanelEl.querySelector('[data-page-ai-pi-lab-runtime-chip]');
+    var builtinNode = piLabPanelEl.querySelector('[data-page-ai-pi-lab-builtin-disabled]');
+    if (statusChip) {
+      var tone = statusTone();
+      if (tone) statusChip.setAttribute('data-tone', tone);
+      else statusChip.removeAttribute('data-tone');
+    }
+    if (statusNode) statusNode.textContent = statusText();
+    if (runtimeNode) runtimeNode.textContent = currentRuntimeLabel();
+    if (builtinNode) builtinNode.style.display = piLabState.disabledBuiltinTools ? '' : 'none';
+    updateContextStrip();
+    updateButtons();
+    updateLauncherState();
+  }
+
+  function updateContextStrip() {
+    if (!piLabPanelEl) return;
+    var currentPage = piLabPanelEl.querySelector('[data-page-ai-pi-lab-current-page]');
+    var selection = piLabPanelEl.querySelector('[data-page-ai-pi-lab-selection]');
+    var allowedRoots = piLabPanelEl.querySelector('[data-page-ai-pi-lab-allowed-roots]');
+    var lightrag = piLabPanelEl.querySelector('[data-page-ai-pi-lab-lightrag]');
+    var changedFiles = piLabPanelEl.querySelector('[data-page-ai-pi-lab-changed-files]');
+    var session = piLabState.session || {};
+    if (currentPage) currentPage.textContent = session.pageTitle || session.pagePath || document.title || '当前页面';
+    if (selection) selection.textContent = piLabState.selectionSummary || '无选区';
+    if (allowedRoots) allowedRoots.textContent = piLabState.allowedRootsSummary || 'pending';
+    if (lightrag) lightrag.textContent = '唯一默认';
+    if (changedFiles) {
+      var files = {};
+      piLabState.changedFiles.forEach(function (file) { if (file) files[file] = true; });
+      piLabState.messages.forEach(function (msg) {
+        if (msg && msg.diffSummary && Array.isArray(msg.diffSummary.files)) {
+          msg.diffSummary.files.forEach(function (file) { if (file) files[file] = true; });
+        }
+      });
+      changedFiles.textContent = String(Object.keys(files).length);
+    }
+  }
+
+  function updateButtons() {
+    if (!piLabPanelEl) return;
+    var startBtn = piLabPanelEl.querySelector('[data-page-ai-pi-lab-btn-start]');
+    var sendBtn = piLabPanelEl.querySelector('[data-page-ai-pi-lab-btn-send]');
+    var abortBtn = piLabPanelEl.querySelector('[data-page-ai-pi-lab-btn-abort]');
+    var input = piLabPanelEl.querySelector('[data-page-ai-pi-lab-input]');
+    var providerSelect = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model-provider]');
+    var modelSelect = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model-id]');
+    var bottomModelSelect = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model-id-bottom]');
+    var customInput = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model-custom]');
+    var isIdle = piLabState.status === STATE_IDLE || piLabState.status === STATE_ABORTED || piLabState.status === STATE_ERROR;
+    var isStarted = piLabState.status === STATE_STARTED;
+    var isStreaming = piLabState.status === STATE_STREAMING || piLabState.status === STATE_STARTING;
+    if (startBtn) {
+      startBtn.hidden = !isIdle;
+      startBtn.disabled = !piLabState.enabled || piLabState.status === STATE_STARTING;
+    }
+    if (sendBtn) {
+      sendBtn.disabled = !piLabState.enabled || !(isStarted || piLabState.status === STATE_IDLE || piLabState.status === STATE_ABORTED || piLabState.status === STATE_ERROR) || !input || !input.value.trim();
+    }
+    if (abortBtn) abortBtn.hidden = !isStreaming;
+    [providerSelect, modelSelect, bottomModelSelect, customInput].forEach(function (node) {
+      if (node) node.disabled = !isIdle;
+    });
+  }
+
+  function updateMessages() {
+    var container = piLabPanelEl && piLabPanelEl.querySelector('[data-page-ai-pi-lab-messages]');
+    if (!container) return;
+    container.innerHTML = '';
+    var visibleMessages = piLabState.messages.filter(isVisibleMessage);
+    if (!visibleMessages.length) {
+      renderEmptyState(container);
+      return;
+    }
+    visibleMessages.forEach(function (msg) { container.appendChild(renderMessage(msg)); });
+    container.scrollTop = container.scrollHeight;
+    updateContextStrip();
+  }
+
+  function updateDiagnostics(text) {
+    piLabState.diagnostics = text || piLabState.diagnostics || '';
+    if (!piLabPanelEl) return;
+    var pre = piLabPanelEl.querySelector('[data-page-ai-pi-lab-diag-text]');
+    if (!pre) return;
+    var lines = [];
+    lines.push('session=' + (piLabState.sessionId || 'none'));
+    lines.push('providerSession=' + (piLabState.providerSessionId || 'none'));
+    lines.push('model=' + currentModelLabel());
+    lines.push('runtime=' + currentRuntimeLabel());
+    lines.push('disabledBuiltinTools=' + (piLabState.disabledBuiltinTools ? 'bash/read/write/edit' : 'pending'));
+    if (piLabState.allowedRootsSummary) lines.push('allowedRoots=' + piLabState.allowedRootsSummary);
+    if (piLabState.diagnostics) lines.push('message=' + piLabState.diagnostics);
+    pre.textContent = lines.join('\n');
+  }
+
+  function updateBuiltinDisabled() {
+    updateConfig();
+  }
+
+  function updateReceiptDisplay() {
+    if (!piLabPanelEl) return;
+    var receipts = piLabPanelEl.querySelector('[data-page-ai-pi-lab-receipts]');
+    var count = piLabPanelEl.querySelector('[data-page-ai-pi-lab-receipt-count]');
+    if (!receipts) return;
+    if (count) count.textContent = String(piLabState.receipts.length);
+    receipts.innerHTML = '';
+    if (!piLabState.receipts.length) {
+      receipts.appendChild(el('div', { className: 'wolai-page-ai-pi-lab-receipt' }, 'No tool receipt yet'));
+      return;
+    }
+    piLabState.receipts.slice(-8).reverse().forEach(function (receipt) {
+      var label = (receipt.toolName || 'tool') + ' · ' + (receipt.allowed === false ? 'denied' : 'allowed');
+      if (receipt.denyReason) label += ' · ' + receipt.denyReason;
+      if (receipt.diffSummary) label += ' · diff ' + receipt.diffSummary;
+      if (receipt.citationCount) label += ' · citations ' + receipt.citationCount;
+      if (receipt.afterFileVersion) label += ' · v ' + String(receipt.afterFileVersion).slice(0, 8);
+      receipts.appendChild(el('div', {
+        className: 'wolai-page-ai-pi-lab-receipt',
+        'data-allowed': receipt.allowed === false ? 'false' : 'true',
+      }, label));
+    });
+  }
+
+  function setState(newState) {
+    piLabState.status = newState;
+    updateConfig();
+  }
+
+  function checkStatus() {
+    return Promise.all([
+      fetch(API.STATUS, { credentials: 'same-origin', cache: 'no-store' }).then(function (r) { return r.json(); }),
+      loadEffectiveConfig().catch(function () { return null; }),
+    ])
+      .then(function (results) {
+        var data = results[0] || {};
+        piLabState.enabled = !!data.enabled;
+        piLabState.sessionId = data.sessionId || piLabState.sessionId || null;
+        piLabState.providerSessionId = data.providerSessionId || piLabState.providerSessionId || null;
+        // Consume backend status/default fields when present.
+        if (data.defaultModelProvider) piLabState.defaultModelProvider = data.defaultModelProvider;
+        if (data.defaultModelId) piLabState.defaultModelId = data.defaultModelId;
+        piLabState.modelProvider = (data.session && data.session.modelProvider) || piLabState.modelProvider || null;
+        piLabState.modelId = (data.session && data.session.modelId) || piLabState.modelId || null;
+        piLabState.session = data.session || piLabState.session || null;
+        piLabState.allowedRootsSummary = summarizeAllowedRoots(data.session && data.session.allowedRootsSnapshot);
+        piLabState.runtimeMode = data.runtimeMode || (data.session && data.session.runtimeMode) || piLabState.runtimeMode || null;
+        piLabState.runtimePid = data.pid || (data.session && data.session.runtimePid) || piLabState.runtimePid || null;
+        piLabState.disabledBuiltinTools = data.disabledPiBuiltinTools || piLabState.disabledBuiltinTools || null;
+        if (data.session && data.session.status === 'runtime_running') {
+          piLabState.sessionId = data.session.sessionId;
+          setState(STATE_STARTED);
+          if (!piLabEventSource || piLabEventSource.readyState === EventSource.CLOSED) connectEventSource(data.session.sessionId);
+        }
+        updateBuiltinDisabled();
+        updateReceiptDisplay();
+        updateDiagnostics('');
+        updateMessages();
+        return data;
+      })
+      .catch(function (error) {
+        piLabState.enabled = false;
+        setState(STATE_ERROR);
+        updateDiagnostics(error && error.message ? error.message : 'status failed');
+      });
+  }
+
+  function startRuntime() {
+    if (!piLabState.enabled || piLabState.status === STATE_STARTING || piLabState.status === STATE_STREAMING) return Promise.resolve({ skipped: true });
+    var context = applyCurrentContextToState();
+    applyModelControls();
+    setState(STATE_STARTING);
+    updateDiagnostics('Starting Pi runtime');
+    return fetch(API.START, {
+      method: 'POST',
+      credentials: 'same-origin',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        rootUri: context.rootUri || undefined,
+        workspaceId: context.workspaceId || undefined,
+        pagePath: context.pagePath || undefined,
+        pageTitle: context.pageTitle || undefined,
+        modelProvider: piLabState.modelProvider || piLabState.defaultModelProvider,
+        modelId: piLabState.modelId || piLabState.defaultModelId,
+      }),
+    })
+      .then(function (r) {
+        if (!r.ok) throw new Error('Start failed: ' + r.status);
+        return r.json();
+      })
+      .then(function (data) {
+        var session = data.session || {};
+        piLabState.sessionId = session.sessionId || data.sessionId || piLabState.sessionId;
+        piLabState.providerSessionId = session.providerSessionId || data.providerSessionId || piLabState.providerSessionId;
+        piLabState.modelProvider = session.modelProvider || piLabState.modelProvider || null;
+        piLabState.modelId = session.modelId || piLabState.modelId || null;
+        piLabState.runtimeMode = session.runtimeMode || data.runtimeMode || piLabState.runtimeMode || null;
+        piLabState.runtimePid = session.runtimePid || data.pid || piLabState.runtimePid || null;
+        piLabState.disabledBuiltinTools = data.disabledPiBuiltinTools || piLabState.disabledBuiltinTools || null;
+        connectEventSource();
+        setState(STATE_STARTED);
+        updateDiagnostics('Pi runtime ready');
+        piLabState.messages.push({ role: 'system', text: 'Pi session started: ' + (piLabState.sessionId || 'session') });
+        updateMessages();
+        return data;
+      })
+      .catch(function (err) {
+        setState(STATE_ERROR);
+        updateDiagnostics('Start error: ' + err.message);
+        throw err;
+      });
+  }
+
+  function connectEventSource(sessionId) {
+    if (piLabEventSource) {
+      piLabEventSource.close();
+      piLabEventSource = null;
+    }
+    var sid = sessionId || piLabState.sessionId;
+    if (!sid) return;
+    var es = new EventSource(API.EVENTS + '?sessionId=' + encodeURIComponent(sid), { withCredentials: true });
+    es.addEventListener('connected', function () { updateDiagnostics('SSE connected'); });
+    es.addEventListener('runtime_started', function (e) {
+      try {
+        var data = JSON.parse(e.data);
+        var payload = data.payload || data;
+        piLabState.runtimePid = payload.pid || piLabState.runtimePid;
+        piLabState.runtimeMode = payload.runtimeMode || piLabState.runtimeMode;
+        piLabState.disabledBuiltinTools = payload.disabledBuiltinTools || piLabState.disabledBuiltinTools;
+        setState(STATE_STARTED);
+        updateDiagnostics('runtime_started');
+      } catch (_) {}
+    });
+    es.addEventListener('pi_rpc_event', function (e) {
+      try {
+        var data = JSON.parse(e.data);
+        handlePiRpcEvent(data.payload || data);
+      } catch (_) {}
+    });
+    es.addEventListener('tool_call', function (e) {
+      try {
+        var data = JSON.parse(e.data);
+        var payload = data.payload || data;
+        applyToolCallSideEffects({
+          ok: payload.allowed !== false,
+          toolName: payload.toolName,
+          result: {
+            rootUri: payload.rootUri,
+            relativePath: payload.relativePath,
+            diffSummary: payload.diffSummary,
+          },
+        });
+        piLabState.receipts.push({
+          toolName: payload.toolName,
+          allowed: payload.allowed !== false,
+          denyReason: payload.denyReason || null,
+          diffSummary: payload.diffSummary || null,
+          citationCount: payload.citationCount || 0,
+          beforeFileVersion: payload.beforeFileVersion || null,
+          afterFileVersion: payload.afterFileVersion || null,
+        });
+        if (payload.normalizedFilePath && payload.diffSummary) piLabState.changedFiles.push(payload.normalizedFilePath);
+        updateReceiptDisplay();
+        updateContextStrip();
+      } catch (_) {}
+    });
+    es.addEventListener('runtime_aborted', function () {
+      setState(STATE_ABORTED);
+      if (streamingAssistantMsg) {
+        streamingAssistantMsg.status = 'done';
+        streamingAssistantMsg = null;
+      }
+      updateMessages();
+    });
+    es.addEventListener('error', function () {
+      if (piLabEventSource && piLabEventSource.readyState === EventSource.CLOSED) updateDiagnostics('SSE connection closed');
+    });
+    piLabEventSource = es;
+  }
+
+  function ensureStreamingAssistant() {
+    if (!streamingAssistantMsg) {
+      streamingAssistantMsg = { role: 'assistant', text: '', toolCalls: [], citations: [], diffSummary: null, status: 'streaming' };
+      piLabState.messages.push(streamingAssistantMsg);
+      setState(STATE_STREAMING);
+    }
+    return streamingAssistantMsg;
+  }
+
+  function extractVisibleAssistantText(message) {
+    if (!message || !Array.isArray(message.content)) return '';
+    return message.content
+      .filter(function (part) { return part && part.type === 'text' && typeof part.text === 'string'; })
+      .map(function (part) { return part.text; })
+      .join('');
+  }
+
+  function handlePiRpcEvent(payload) {
+    if (!payload) return;
+    var eventType = payload.type;
+    var msgData = payload.assistantMessageEvent || payload;
+    var msgDataType = msgData && msgData.type;
+    if (msgDataType === 'thinking_start' || msgDataType === 'thinking_delta' || msgDataType === 'thinking_end') {
+      updateDiagnostics('Pi thinking event hidden from visible reply');
+      return;
+    }
+    if (msgDataType === 'text_start') {
+      ensureStreamingAssistant();
+      updateMessages();
+      return;
+    }
+    if (msgDataType === 'text_delta') {
+      var msg = ensureStreamingAssistant();
+      if (msgData.delta) msg.text += msgData.delta;
+      if (msgData.text && !msgData.delta) msg.text = msgData.text;
+      updateMessages();
+    } else if (msgDataType === 'text_end') {
+      var textEndMsg = ensureStreamingAssistant();
+      textEndMsg.text = msgData.content || textEndMsg.text;
+      updateMessages();
+    } else if (eventType === 'message_end' && payload.message && payload.message.role === 'assistant') {
+      var messageEndMsg = ensureStreamingAssistant();
+      var visibleText = extractVisibleAssistantText(payload.message);
+      if (visibleText) messageEndMsg.text = visibleText;
+      messageEndMsg.status = 'done';
+      streamingAssistantMsg = null;
+      setState(STATE_STARTED);
+      updateMessages();
+    } else if (eventType === 'agent_end') {
+      var finalMessages = Array.isArray(payload.messages) ? payload.messages : [];
+      var finalAssistant = finalMessages.slice().reverse().find(function (message) { return message && message.role === 'assistant'; });
+      var finalText = extractVisibleAssistantText(finalAssistant);
+      var lastVisibleAssistant = piLabState.messages.slice().reverse().find(function (message) { return message && message.role === 'assistant'; });
+      if (!streamingAssistantMsg && lastVisibleAssistant && lastVisibleAssistant.status === 'done') {
+        if (finalText && !lastVisibleAssistant.text) {
+          lastVisibleAssistant.text = finalText;
+          updateMessages();
+        }
+        setState(STATE_STARTED);
+        return;
+      }
+      var agentEndMsg = ensureStreamingAssistant();
+      if (finalText) agentEndMsg.text = finalText;
+      agentEndMsg.status = 'done';
+      streamingAssistantMsg = null;
+      setState(STATE_STARTED);
+      updateMessages();
+    } else if (eventType === 'tool_call_start' || msgDataType === 'tool_call_start') {
+      var startMsg = ensureStreamingAssistant();
+      startMsg.toolCalls.push({ name: payload.toolName || payload.name || 'tool', args: payload.args || payload.params || {}, status: 'running' });
+      updateMessages();
+    } else if (eventType === 'tool_call_end' || msgDataType === 'tool_call_end') {
+      var endMsg = ensureStreamingAssistant();
+      var last = endMsg.toolCalls[endMsg.toolCalls.length - 1];
+      if (last) {
+        last.status = 'done';
+        last.result = payload.result || msgData.result || {};
+      }
+      updateMessages();
+    } else if (eventType === 'citation' || msgDataType === 'citation') {
+      var citMsg = ensureStreamingAssistant();
+      citMsg.citations.push({ source: payload.source || msgData.source || '', title: payload.title || msgData.title || '', url: payload.url || msgData.url || '#' });
+      updateMessages();
+    } else if (eventType === 'diff' || msgDataType === 'diff') {
+      var diffMsg = ensureStreamingAssistant();
+      diffMsg.diffSummary = diffMsg.diffSummary || { files: [] };
+      diffMsg.diffSummary.files = payload.files || msgData.files || [];
+      diffMsg.diffSummary.files.forEach(function (file) { if (file) piLabState.changedFiles.push(file); });
+      updateMessages();
+    } else if (eventType === 'done' || msgDataType === 'done') {
+      var doneMsg = ensureStreamingAssistant();
+      doneMsg.status = 'done';
+      if (msgData.text) doneMsg.text = msgData.text;
+      if (msgData.toolCalls) doneMsg.toolCalls = msgData.toolCalls;
+      if (msgData.citations) doneMsg.citations = msgData.citations;
+      if (msgData.diffSummary) doneMsg.diffSummary = msgData.diffSummary;
+      streamingAssistantMsg = null;
+      setState(STATE_STARTED);
+      updateMessages();
+    } else if (eventType === 'error' || msgDataType === 'error') {
+      var errMsg = ensureStreamingAssistant();
+      errMsg.text += (errMsg.text ? '\n' : '') + '错误: ' + (payload.error || msgData.message || 'Pi runtime error');
+      errMsg.status = 'done';
+      streamingAssistantMsg = null;
+      setState(STATE_STARTED);
+      updateMessages();
+    }
+  }
+
+  function sendPrompt(text) {
+    var prompt = String(text || '').trim();
+    if (!prompt) return;
+    piLabState.messages.push({ role: 'user', text: prompt });
+    streamingAssistantMsg = { role: 'assistant', text: '', toolCalls: [], citations: [], diffSummary: null, status: 'streaming' };
+    piLabState.messages.push(streamingAssistantMsg);
+    setState(STATE_STREAMING);
+    updateMessages();
+    return fetch(API.SEND, {
+      method: 'POST',
+      credentials: 'same-origin',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ sessionId: piLabState.sessionId, message: prompt }),
+    })
+      .then(function (r) {
+        if (!r.ok) throw new Error('Send failed: ' + r.status);
+        return r.json();
+      })
+      .then(function (data) {
+        if (!data.accepted) throw new Error('Pi Lab rejected prompt');
+        if (!piLabEventSource || piLabEventSource.readyState === EventSource.CLOSED) connectEventSource(data.sessionId || piLabState.sessionId);
+      })
+      .catch(function (err) {
+        if (streamingAssistantMsg) {
+          streamingAssistantMsg.text = '错误: ' + err.message;
+          streamingAssistantMsg.status = 'done';
+          streamingAssistantMsg = null;
+          setState(STATE_STARTED);
+          updateMessages();
+        }
+      });
+  }
+
+  function ensureRuntimeReady() {
+    if (piLabState.status === STATE_IDLE || piLabState.status === STATE_ABORTED || piLabState.status === STATE_ERROR || !piLabState.sessionId) {
+      return startRuntime();
+    }
+    return Promise.resolve({ ok: true });
+  }
+
+  function callMNoteTool(toolName, params) {
+    return ensureRuntimeReady().then(function () {
+      return fetch('/api/page-ai/pi/tool-call', {
+        method: 'POST',
+        credentials: 'same-origin',
+        headers: { 'Content-Type': 'application/json', accept: 'application/json' },
+        body: JSON.stringify({
+          sessionId: piLabState.sessionId,
+          toolName: toolName,
+          params: params || {},
+        }),
+      });
+    }).then(function (response) {
+      return response.json().catch(function () { return {}; }).then(function (payload) {
+        if (!response.ok) throw new Error(payload.message || ('Tool call failed: ' + response.status));
+        return payload;
+      });
+    });
+  }
+
+  function emitLocalFolderRefresh(rootUri, relativePath, source) {
+    var normalizedPath = normalizeSlashes(relativePath).replace(/^\/+/, '');
+    if (!rootUri || !normalizedPath) return false;
+    var documentId = /\.md(?:own)?$/i.test(normalizedPath) ? 'local-md:' + normalizedPath.replace(/\//g, '~2F') : '';
+    if (window.__mnoteLocalFolderEventBus && typeof window.__mnoteLocalFolderEventBus.emitChangedFiles === 'function') {
+      window.__mnoteLocalFolderEventBus.emitChangedFiles({
+        source: source || 'pi_lab_tool_call',
+        reason: source || 'pi_lab_tool_call',
+        rootUri: rootUri,
+        workspaceId: (piLabState.session && piLabState.session.workspaceId) || currentWorkspaceId(),
+        changedFiles: [{
+          relativePath: normalizedPath,
+          documentId: documentId,
+          changeType: 'modified',
+        }],
+        affectedParents: [{
+          relativePath: normalizedPath.indexOf('/') >= 0 ? normalizedPath.split('/').slice(0, -1).join('/') : '',
+          reason: source || 'pi_lab_tool_call',
+        }],
+      });
+      return true;
+    }
+    window.dispatchEvent(new CustomEvent('tree:local-folder-watch-batch', {
+      detail: {
+        payload: {
+          schema: 'mnote.local_folder.watch_batch.v1',
+          source: source || 'pi_lab_tool_call',
+          rootUri: rootUri,
+          changedPaths: [{ relativePath: normalizedPath, documentId: documentId, changeType: 'modified' }],
+        },
+      },
+    }));
+    return true;
+  }
+
+  function refreshPatchedCurrentDocument(rootUri, relativePath, source) {
+    emitLocalFolderRefresh(rootUri, relativePath, source || 'pi_lab_patch');
+    var documentId = /\.md(?:own)?$/i.test(String(relativePath || '')) ? 'local-md:' + normalizeSlashes(relativePath).replace(/^\/+/, '').replace(/\//g, '~2F') : currentDocumentId();
+    var api = window.__mnoteDocumentPaneRuntime;
+    if (api && typeof api.refreshDocument === 'function') {
+      api.refreshDocument({
+        documentId: documentId,
+        workspaceId: (piLabState.session && piLabState.session.workspaceId) || currentWorkspaceId(),
+        source: source || 'pi_lab_patch',
+      }).catch(function () {});
+    }
+  }
+
+  function applyToolCallSideEffects(payload) {
+    if (!payload || payload.ok !== true) return;
+    var result = payload.result || {};
+    if (payload.toolName === 'mnote.local_file.patch' || result.diffSummary) {
+      var rootUri = String(result.rootUri || (piLabState.session && piLabState.session.rootUri) || currentRootUri() || '').trim();
+      var relativePath = String(result.relativePath || '').trim();
+      if (!relativePath && result.path) relativePath = result.path;
+      if (relativePath) refreshPatchedCurrentDocument(rootUri, relativePath, 'pi_lab_local_file_patch');
+    }
+  }
+
+  function setComposerText(text) {
+    if (!piLabPanelEl) return;
+    var input = piLabPanelEl.querySelector('[data-page-ai-pi-lab-input]');
+    if (!input) return;
+    input.value = text || '';
+    updateButtons();
+    input.focus();
+  }
+
+  function handleQuickAction(kind) {
+    var context = applyCurrentContextToState();
+    if (kind === 'read-page') {
+      if (!context.rootUri || !context.pagePath) {
+        setComposerText('读取当前页面，总结页面要点。');
+        updateDiagnostics('当前页缺少 rootUri/pagePath，无法调用 mnote.current_page.read');
+        return;
+      }
+      callMNoteTool('mnote.current_page.read', {
+        rootUri: context.rootUri,
+        pagePath: context.pagePath,
+      }).then(function (payload) {
+        var result = payload.result || {};
+        var content = String(result.content || '').slice(0, 12000);
+        piLabState.messages.push({
+          role: 'system',
+          text: '已读取当前页：' + (context.pageTitle || context.pagePath) + '\nfileVersion=' + (result.fileVersion || 'unknown'),
+        });
+        setComposerText('基于当前页面内容回答：\n\n' + content);
+        updateMessages();
+      }).catch(function (error) {
+        updateDiagnostics(error.message || String(error));
+        setComposerText('读取当前页面，总结页面要点。');
+      });
+      return;
+    }
+    if (kind === 'selection') {
+      var selection = refreshSelectionSummary();
+      callMNoteTool('mnote.selection.read', {
+        selection: selection,
+        selectionSource: 'mnote_sidebar_host',
+        rootUri: context.rootUri || null,
+        pagePath: context.pagePath || null,
+      }).then(function () {
+        setComposerText(selection
+          ? '基于当前选区给出修改建议：\n\n' + selection
+          : '当前没有选区。请先在编辑器中选中文本，再让 Pi 读取选区。');
+        updateContextStrip();
+      }).catch(function () {
+        setComposerText(selection || '当前没有选区。');
+      });
+      return;
+    }
+    setComposerText('通过 LightRAG 查询当前页面相关资料，并带 citation 回复。');
+  }
+
+  function sendCurrentInput() {
+    if (!piLabPanelEl) return;
+    var input = piLabPanelEl.querySelector('[data-page-ai-pi-lab-input]');
+    var text = input ? input.value.trim() : '';
+    if (!text) return;
+    if (input) input.value = '';
+    updateButtons();
+    var run = piLabState.status === STATE_IDLE || piLabState.status === STATE_ABORTED || piLabState.status === STATE_ERROR
+      ? startRuntime()
+      : Promise.resolve();
+    run.then(function () { return sendPrompt(text); }).catch(function () {});
+  }
+
+  function abortPrompt() {
+    if (piLabEventSource) {
+      piLabEventSource.close();
+      piLabEventSource = null;
+    }
+    if (piLabState.sessionId) {
+      fetch(API.ABORT, {
+        method: 'POST',
+        credentials: 'same-origin',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ sessionId: piLabState.sessionId }),
+      }).catch(function () {});
+    }
+    if (streamingAssistantMsg) {
+      streamingAssistantMsg.text += (streamingAssistantMsg.text ? '\n' : '') + '已中止';
+      streamingAssistantMsg.status = 'done';
+      streamingAssistantMsg = null;
+    }
+    setState(STATE_ABORTED);
+    updateMessages();
+  }
+
+  function ensurePanel() {
+    if (piLabPanelEl) return piLabPanelEl;
+    var container = document.createElement('div');
+    container.innerHTML = piLabPanelHTML();
+    piLabPanelEl = container.firstElementChild;
+    wireEvents();
+    updateReceiptDisplay();
+    updateMessages();
+    return piLabPanelEl;
+  }
+
+  function summarizeAllowedRoots(snapshot) {
+    if (!snapshot) return piLabState.allowedRootsSummary || 'pending';
+    var roots = Array.isArray(snapshot.roots) ? snapshot.roots : (Array.isArray(snapshot) ? snapshot : []);
+    if (!roots.length) return '0 roots';
+    return roots.length + ' root' + (roots.length === 1 ? '' : 's');
+  }
+
+  function ensureDrawer() {
+    if (piLabDrawerEl) return piLabDrawerEl;
+    piLabDrawerEl = el('section', {
+      className: 'wolai-page-ai-pi-lab-drawer',
+      'data-page-ai-pi-lab': 'drawer',
+      'data-page-ai-pi-lab-drawer': 'true',
+      'aria-label': 'Pi Lab',
+      hidden: 'true',
+    });
+    piLabDrawerEl.appendChild(ensurePanel());
+    document.body.appendChild(piLabDrawerEl);
+    return piLabDrawerEl;
+  }
+
+  function setDrawerVisible(visible) {
+    var drawer = ensureDrawer();
+    drawer.hidden = !visible;
+    drawer.setAttribute('data-open', visible ? 'true' : 'false');
+    if (visible) drawer.setAttribute('data-minimized', 'false');
+  }
+
+  function showPiLab() {
+    piLabState.active = true;
+    setDrawerVisible(true);
+    applyCurrentContextToState();
+    updateConfig();
+    checkStatus();
+    var input = piLabPanelEl && piLabPanelEl.querySelector('[data-page-ai-pi-lab-input]');
+    if (input) setTimeout(function () { input.focus(); }, 60);
+  }
+
+  function hidePiLab() {
+    piLabState.active = false;
+    if (piLabDrawerEl) setDrawerVisible(false);
+    updateLauncherState();
+  }
+
+  function updateLauncherState() {
+    if (!piLabLauncherEl) return;
+    piLabLauncherEl.setAttribute('data-state', piLabState.status);
+    piLabLauncherEl.hidden = false;
+  }
+
+  function installLauncher() {
+    if (piLabLauncherEl) return;
+    piLabLauncherEl = el('button', {
+      type: 'button',
+      className: 'wolai-page-ai-pi-lab-launcher',
+      'data-page-ai-pi-lab-launcher': 'true',
+      title: 'Pi Lab',
+      'aria-label': '打开 Pi Lab',
+    }, 'π');
+    piLabLauncherEl.addEventListener('click', showPiLab);
+    document.body.appendChild(piLabLauncherEl);
+  }
+
+  function wireEvents() {
+    if (!piLabPanelEl || piLabPanelEl.getAttribute('data-wired') === 'true') return;
+    piLabPanelEl.setAttribute('data-wired', 'true');
+    var input = piLabPanelEl.querySelector('[data-page-ai-pi-lab-input]');
+    var startBtn = piLabPanelEl.querySelector('[data-page-ai-pi-lab-btn-start]');
+    var sendBtn = piLabPanelEl.querySelector('[data-page-ai-pi-lab-btn-send]');
+    var abortBtn = piLabPanelEl.querySelector('[data-page-ai-pi-lab-btn-abort]');
+    var clearBtn = piLabPanelEl.querySelector('[data-page-ai-pi-lab-btn-clear]');
+    var closeBtn = piLabPanelEl.querySelector('[data-page-ai-pi-lab-close]');
+    var minimizeBtn = piLabPanelEl.querySelector('[data-page-ai-pi-lab-minimize]');
+    var providerSelect = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model-provider]');
+    var modelSelect = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model-id]');
+    var bottomModelSelect = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model-id-bottom]');
+    var customInput = piLabPanelEl.querySelector('[data-page-ai-pi-lab-model-custom]');
+    var settingsBtn = piLabPanelEl.querySelector('[data-page-ai-pi-lab-open-settings]');
+    var historyBtn = piLabPanelEl.querySelector('[data-page-ai-pi-lab-history]');
+    var openBtn = piLabPanelEl.querySelector('[data-page-ai-pi-lab-open]');
+    var newBtns = piLabPanelEl.querySelectorAll('[data-page-ai-pi-lab-new], [data-page-ai-pi-lab-new-small]');
+    if (startBtn) startBtn.addEventListener('click', startRuntime);
+    if (sendBtn) sendBtn.addEventListener('click', sendCurrentInput);
+    if (abortBtn) abortBtn.addEventListener('click', abortPrompt);
+    if (clearBtn) clearBtn.addEventListener('click', function () {
+      piLabState.messages = [];
+      piLabState.receipts = [];
+      streamingAssistantMsg = null;
+      updateMessages();
+      updateReceiptDisplay();
+    });
+    if (closeBtn) closeBtn.addEventListener('click', hidePiLab);
+    if (minimizeBtn) {
+      minimizeBtn.addEventListener('click', function () {
+        var drawer = ensureDrawer();
+        var minimized = drawer.getAttribute('data-minimized') === 'true';
+        drawer.setAttribute('data-minimized', minimized ? 'false' : 'true');
+      });
+    }
+    if (input) {
+      input.addEventListener('input', updateButtons);
+      input.addEventListener('keydown', function (e) {
+        if (e.isComposing || e.key === 'Process') return;
+        if (e.key === 'Enter' && !e.shiftKey) {
+          e.preventDefault();
+          sendCurrentInput();
+        }
+        if (e.key === 'Escape' && piLabState.status === STATE_STREAMING) {
+          e.preventDefault();
+          abortPrompt();
+        }
+      });
+    }
+    [providerSelect, modelSelect, bottomModelSelect].forEach(function (node) {
+      if (node) node.addEventListener('change', applyModelControls);
+    });
+    if (customInput) customInput.addEventListener('input', applyModelControls);
+    if (settingsBtn) {
+      settingsBtn.addEventListener('click', function () {
+        var settings = piLabPanelEl.querySelector('[data-page-ai-pi-lab-settings]');
+        var drawer = ensureDrawer();
+        var isOpen = drawer.getAttribute('data-config-open') === 'true';
+        drawer.setAttribute('data-config-open', isOpen ? 'false' : 'true');
+        if (settings) settings.open = !isOpen;
+        var context = piLabPanelEl.querySelector('[data-page-ai-pi-lab-context-strip]');
+        if (context) context.open = !isOpen;
+      });
+    }
+    if (historyBtn) {
+      historyBtn.addEventListener('click', function () {
+        var panel = piLabPanelEl.querySelector('[data-page-ai-pi-lab-history-panel]');
+        if (!panel) return;
+        panel.hidden = !panel.hidden;
+        if (!panel.hidden) loadHistory().catch(function (error) {
+          panel.innerHTML = '
' + escapeHtml(error.message || '历史加载失败') + '
';
+        });
+      });
+    }
+    if (openBtn) {
+      openBtn.addEventListener('click', function () {
+        window.location.assign('/user/ai');
+      });
+    }
+    Array.prototype.slice.call(newBtns || []).forEach(function (btn) {
+      btn.addEventListener('click', function () {
+        piLabState.messages = [];
+        piLabState.receipts = [];
+        streamingAssistantMsg = null;
+        updateMessages();
+        updateReceiptDisplay();
+      });
+    });
+    piLabPanelEl.addEventListener('click', function (event) {
+      var historyTarget = event.target && event.target.closest ? event.target.closest('[data-page-ai-pi-lab-history-session]') : null;
+      if (historyTarget) {
+        openHistorySession(historyTarget.getAttribute('data-page-ai-pi-lab-history-session')).catch(function (error) {
+          updateDiagnostics(error.message || '历史会话加载失败');
+        });
+        return;
+      }
+      var target = event.target && event.target.closest ? event.target.closest('[data-page-ai-pi-lab-example]') : null;
+      if (!target) return;
+      setComposerText(target.getAttribute('data-page-ai-pi-lab-example') || target.textContent || '');
+    });
+    Array.prototype.slice.call(piLabPanelEl.querySelectorAll('[data-page-ai-pi-lab-quick]')).forEach(function (btn) {
+      btn.addEventListener('click', function () {
+        handleQuickAction(btn.getAttribute('data-page-ai-pi-lab-quick'));
+      });
+    });
+  }
+
+  function setupPostMessageListener() {
+    window.addEventListener('message', function (event) {
+      if (!event.data || event.data.source !== 'mnote-sidebar') return;
+      if (event.data.type === 'mnote:pi-lab-status') checkStatus();
+      if (event.data.type === 'mnote:pi-lab-show') showPiLab();
+      if (event.data.type === 'mnote:pi-lab-hide') hidePiLab();
+    });
+  }
+
+  function setupSelectionListener() {
+    document.addEventListener('selectionchange', function () {
+      if (!piLabState.active) return;
+      refreshSelectionSummary();
+      updateContextStrip();
+    }, true);
+    window.addEventListener('mnote:leptos-tiptap-spike:selection', function () {
+      if (!piLabState.active) return;
+      refreshSelectionSummary();
+      updateContextStrip();
+    }, true);
+  }
+
+  function createSidebarPageAiPiLabRuntime(context) {
+    if (piLabInstalled) return piLabState;
+    piLabInstalled = true;
+    injectStyles();
+    piLabState.standalone = !!(context && context.standalone);
+    ensureDrawer();
+    if (piLabState.standalone) {
+      setDrawerVisible(true);
+      piLabState.active = true;
+    } else {
+      installLauncher();
+    }
+    setupPostMessageListener();
+    setupSelectionListener();
+    updateConfig();
+    updateReceiptDisplay();
+    checkStatus();
+    return piLabState;
+  }
+
+  if (typeof window !== 'undefined') {
+    window.createSidebarPageAiPiLabRuntime = createSidebarPageAiPiLabRuntime;
+  }
+})();
diff --git a/rust/crates/mnote-web/browser/sidebar-workspace-runtime.js b/rust/crates/mnote-web/browser/sidebar-workspace-runtime.js
index 426e374a..c3a30f02 100644
--- a/rust/crates/mnote-web/browser/sidebar-workspace-runtime.js
+++ b/rust/crates/mnote-web/browser/sidebar-workspace-runtime.js
@@ -950,6 +950,7 @@ export const createSidebarWorkspaceRuntime = (dependencies = {}) => {
     menu.innerHTML =
       '' +
       '' +
+      '' +
       '' +
       '';
     var sessionPromise = fetchAccountSession();
@@ -972,6 +973,20 @@ export const createSidebarWorkspaceRuntime = (dependencies = {}) => {
         openAdminAccessPolicyDialog(accessPolicyLink);
       });
     }
+    var aiManagementLink = menu.querySelector('[data-testid="mnote-account-ai-management"]');
+    sessionPromise.then(function(session) {
+      if (!(aiManagementLink instanceof HTMLElement)) return;
+      aiManagementLink.hidden = false;
+      aiManagementLink.setAttribute('data-ai-management-role', sessionIsAdmin(session) ? 'admin' : 'user');
+    });
+    if (aiManagementLink) {
+      aiManagementLink.addEventListener('click', function(event) {
+        event.preventDefault();
+        sessionPromise.then(function(session) {
+          window.location.assign(sessionIsAdmin(session) ? '/admin/ai' : '/user/ai');
+        });
+      });
+    }
     var signOutButton = menu.querySelector('[data-testid="mnote-account-sign-out"]');
     if (signOutButton) {
       signOutButton.addEventListener('click', function(event) {
diff --git a/rust/crates/mnote-web/src/app.rs b/rust/crates/mnote-web/src/app.rs
index 7057a584..e8f9b5fe 100644
--- a/rust/crates/mnote-web/src/app.rs
+++ b/rust/crates/mnote-web/src/app.rs
@@ -31,6 +31,7 @@ pub struct AppConfig {
     pub enable_legacy_next_compat: bool,
     pub enable_debug_shell_routes: bool,
     pub enable_editor_actor: bool,
+    pub enable_page_ai_pi_lab: bool,
     pub hermes_base_path: String,
     pub compat_next_base_path: String,
     pub convex_url: Option,
@@ -64,6 +65,7 @@ impl AppConfig {
                 .map(|value| matches!(value.trim(), "1" | "true" | "TRUE" | "yes" | "YES"))
                 .unwrap_or(false),
             enable_editor_actor: env_bool("MNOTE_WEB_ENABLE_EDITOR_ACTOR", true),
+            enable_page_ai_pi_lab: env_bool("MNOTE_PAGE_AI_PI_LAB", true),
             hermes_base_path: env::var("MNOTE_WEB_HERMES_BASE_PATH")
                 .unwrap_or_else(|_| "/api/hermes".into()),
             compat_next_base_path: env::var("MNOTE_WEB_COMPAT_NEXT_BASE_PATH")
@@ -382,6 +384,7 @@ mod tests {
             enable_legacy_next_compat: false,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: true,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/ai_settings.rs b/rust/crates/mnote-web/src/routes/ai_settings.rs
new file mode 100644
index 00000000..760922c3
--- /dev/null
+++ b/rust/crates/mnote-web/src/routes/ai_settings.rs
@@ -0,0 +1,2298 @@
+//! Provider-neutral AI settings API — effective config, access scopes, and
+//! admin-scoped access-scope queries.
+//!
+//! These endpoints consume MNote's control-plane as the single source of truth:
+//! - `directory_grants` → `allowedRoots` (filtered by status, never from `ai_policies`)
+//! - `ai_policies`     → only `model_policy_json` / `quota_json`
+//!
+//! Routes are registered by the caller in `routes/mod.rs`.
+
+use crate::app::AppState;
+use crate::context::RequestContext;
+use crate::error::WebError;
+use crate::routes::local_folder_source;
+use axum::extract::{Extension, Path, Query, State};
+use axum::http::StatusCode;
+use axum::Json;
+use control_plane::AppendAuditInput;
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+use std::collections::HashMap;
+
+// ─── Response types ─────────────────────────────────────────────────────
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EffectiveAiSettings {
+    pub default_model: String,
+    pub providers: Vec,
+    pub models: Vec,
+    pub allowed_roots: Vec,
+    pub model_policy: Value,
+    pub quota: Value,
+    pub tool_catalog: Vec,
+    pub skills: Vec,
+    pub mcp_servers: Vec,
+    pub lightrag_provider: LightRagProviderRef,
+    pub access_policy_links: AccessPolicyLinks,
+    /// Always `"directory_grants"` — declares that allowed-roots come from
+    /// directory_grants, NOT from `ai_policies.allowed_roots_json`.
+    pub source_of_truth: &'static str,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ProviderEntry {
+    pub id: String,
+    pub name: String,
+    pub enabled: bool,
+    pub default_model: String,
+    pub base_url: String,
+    pub secret_ref: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ModelEntry {
+    pub provider: &'static str,
+    pub id: String,
+    pub name: String,
+    pub enabled: bool,
+    pub is_default: bool,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ToolCatalogEntry {
+    pub name: &'static str,
+    pub description: &'static str,
+    /// One of `"allow"`, `"ask"`, `"deny"`.
+    pub default_policy: &'static str,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct LightRagProviderRef {
+    pub provider: &'static str,
+    pub description: &'static str,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccessPolicyLinks {
+    pub admin: &'static str,
+    pub user: &'static str,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccessScopeEntry {
+    pub id: String,
+    pub user_id: String,
+    pub workspace_id: Option,
+    pub root_uri: String,
+    pub root_path: String,
+    pub permission: String,
+    pub recursive: bool,
+    pub capabilities: Value,
+    pub source: String,
+    pub status: String,
+    pub created_at: String,
+    pub updated_at: String,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccessScopesResponse {
+    pub allowed_roots: Vec,
+    pub source_of_truth: &'static str,
+}
+
+// ─── Query parameters ───────────────────────────────────────────────────
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccessScopesQuery {
+    pub workspace_id: Option,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ReceiptQuery {
+    pub session_id: Option,
+    pub user_id: Option,
+    pub limit: Option,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UserAiPolicyBody {
+    #[serde(default)]
+    pub default_model: Option,
+    #[serde(default)]
+    pub allowed_models: Option>,
+    #[serde(default)]
+    pub tools: Option>,
+    #[serde(default)]
+    pub skills: Option>,
+    #[serde(default)]
+    pub mcp_servers: Option>,
+}
+
+// ─── Admin body types ───────────────────────────────────────────────────
+
+/// Admin PUT request body for AI policy.
+/// All fields are optional — only provided fields are merged into the
+/// existing policy.  `allowed_roots` is never accepted from the client
+/// (source of truth is `directory_grants`).
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UpsertAiPolicyBody {
+    #[serde(default)]
+    pub default_model: Option,
+    #[serde(default)]
+    pub allowed_models: Option>,
+    #[serde(default)]
+    pub workspace_id: Option,
+    /// Per-provider configuration.  Provider `secretRef` must use
+    /// `env://` or `secret://` references — raw API keys are rejected.
+    #[serde(default)]
+    pub providers: Option>,
+    #[serde(default)]
+    pub build_plan_task: Option,
+    /// Tool-policy overrides.  Keys are MNote tool names
+    /// (e.g. `mnote.local_file.read`), values are `"allow"`, `"ask"`,
+    /// or `"deny"`.
+    #[serde(default)]
+    pub tools: Option>,
+    /// Skills registry: name → enabled/disabled.
+    #[serde(default)]
+    pub skills: Option>,
+    /// MCP server registry.
+    #[serde(default)]
+    pub mcp_servers: Option>,
+    /// Optional quota override (merged into existing).
+    #[serde(default)]
+    pub quota: Option,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ProviderConfig {
+    pub name: String,
+    pub enabled: bool,
+    /// Must be an `env://` or `secret://` reference — raw keys are rejected.
+    pub secret_ref: String,
+    pub default_model: String,
+    #[serde(default)]
+    pub base_url: String,
+    #[serde(default)]
+    pub allowed_models: Vec,
+    #[serde(default)]
+    pub default_build_model: String,
+    #[serde(default)]
+    pub default_plan_model: String,
+    #[serde(default)]
+    pub default_task_model: String,
+    #[serde(default)]
+    pub failover_chains: Vec,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BuildPlanTaskConfig {
+    #[serde(default)]
+    pub default: Option,
+    #[serde(default)]
+    pub failover: Vec,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SkillConfig {
+    pub name: String,
+    pub enabled: bool,
+    #[serde(default)]
+    pub description: String,
+    #[serde(default)]
+    pub source: String,
+    #[serde(default)]
+    pub risk_level: String,
+    #[serde(default)]
+    pub required_scopes: Vec,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct McpServerConfig {
+    pub name: String,
+    pub enabled: bool,
+    #[serde(default)]
+    pub url: String,
+    #[serde(default = "default_mcp_transport")]
+    pub transport: String,
+    #[serde(default)]
+    pub command: String,
+    #[serde(default = "default_mcp_network_policy")]
+    pub network_policy: String,
+    #[serde(default)]
+    pub secret_refs: Vec,
+    /// Must be `true` — only facade proxy mode is accepted.
+    pub facade_only: bool,
+    /// Must be `true` — sandboxed execution is required.
+    pub sandbox: bool,
+    #[serde(default)]
+    pub description: String,
+    #[serde(default)]
+    pub risk_level: String,
+    #[serde(default)]
+    pub required_scopes: Vec,
+}
+
+// ─── Admin response types ──────────────────────────────────────────────
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AdminAiSettingsResponse {
+    pub ok: bool,
+    pub schema: &'static str,
+    pub default_model: String,
+    pub allowed_models: Vec,
+    pub providers: HashMap,
+    pub build_plan_task: Option,
+    pub tools: HashMap,
+    pub skills: HashMap,
+    pub mcp_servers: HashMap,
+    pub quota: Value,
+    pub revision: i64,
+    pub updated_at: String,
+    pub tool_catalog: Vec,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AdminAiSettingsUpsertResponse {
+    pub ok: bool,
+    pub schema: &'static str,
+    pub revision: i64,
+    pub updated_at: String,
+}
+
+// ─── Handler implementations ─────────────────────────────────────────────
+
+/// `GET /api/ai-settings/effective`
+///
+/// Returns the effective AI configuration for the current authenticated user:
+/// model policy + fallback defaults, quota, MNote-owned tool catalog,
+/// LightRAG provider reference, and access-policy management links.
+///
+pub async fn effective_settings(
+    State(state): State,
+    Extension(context): Extension,
+    Query(query): Query,
+) -> Result, WebError> {
+    let actor_id = ensure_authenticated(&context)?;
+
+    let allowed_roots =
+        load_active_directory_grants(&state, &actor_id, query.workspace_id.as_deref())?;
+    let (model_policy, quota) =
+        load_effective_model_policy_and_quota(&state, &actor_id, query.workspace_id.as_deref());
+    let default_model = effective_default_model(&model_policy);
+    let models = effective_models(&model_policy, &default_model);
+
+    let provider_configs = policy_map::(&model_policy, "providers");
+    let providers = if provider_configs.is_empty() {
+        vec![ProviderEntry {
+            id: "omniroute".into(),
+            name: "Omniroute".into(),
+            enabled: true,
+            default_model: default_model.clone(),
+            base_url: String::new(),
+            secret_ref: "env://OMNIROUTE_API_KEY".into(),
+        }]
+    } else {
+        provider_configs
+            .into_iter()
+            .map(|(id, provider)| ProviderEntry {
+                id,
+                name: provider.name,
+                enabled: provider.enabled,
+                default_model: provider.default_model,
+                base_url: provider.base_url,
+                secret_ref: provider.secret_ref,
+            })
+            .collect()
+    };
+    let tool_policies = policy_string_map(&model_policy, "tools");
+    let skills = effective_skill_registry(&model_policy)
+        .into_values()
+        .filter(|skill| skill.enabled)
+        .collect();
+    let mcp_servers = effective_mcp_registry(&model_policy)
+        .into_values()
+        .filter(|server| server.enabled && server.facade_only && server.sandbox)
+        .collect();
+
+    Ok(Json(EffectiveAiSettings {
+        default_model: default_model.clone(),
+        providers,
+        models,
+        allowed_roots,
+        model_policy,
+        quota,
+        tool_catalog: effective_tool_catalog(&tool_policies),
+        skills,
+        mcp_servers,
+        lightrag_provider: LightRagProviderRef {
+            provider: LIGHTRAG_PROVIDER,
+            description: LIGHTRAG_PROVIDER_DESCRIPTION,
+        },
+        access_policy_links: AccessPolicyLinks {
+            admin: ADMIN_ACCESS_POLICY_PATH,
+            user: USER_ACCESS_POLICY_PATH,
+        },
+        source_of_truth: SOURCE_OF_TRUTH,
+    }))
+}
+
+/// `GET /api/ai-settings/access-scopes`
+///
+/// Returns the current user's allowed roots derived from `directory_grants`.
+/// Only `active` grants are included.
+/// Optional `workspaceId` query parameter narrows to a single workspace.
+pub async fn user_access_scopes(
+    State(state): State,
+    Extension(context): Extension,
+    Query(query): Query,
+) -> Result, WebError> {
+    let actor_id = ensure_authenticated(&context)?;
+    let allowed_roots =
+        load_active_directory_grants(&state, &actor_id, query.workspace_id.as_deref())?;
+    Ok(Json(AccessScopesResponse {
+        allowed_roots,
+        source_of_truth: SOURCE_OF_TRUTH,
+    }))
+}
+
+/// `GET /api/ai-admin/access-scopes`
+///
+/// Admin-only variant.  Validates that the current actor has admin
+/// privileges via `is_local_access_policy_admin_context` before
+/// returning directory grants.
+pub async fn admin_access_scopes(
+    State(state): State,
+    Extension(context): Extension,
+    Query(query): Query,
+) -> Result, WebError> {
+    let actor_id = ensure_authenticated(&context)?;
+
+    if !local_folder_source::is_local_access_policy_admin_context(&context) {
+        return Err(WebError::new(
+            StatusCode::FORBIDDEN,
+            "ai_admin_access_forbidden",
+            "需要管理员权限才能访问 ai-admin 端点",
+        )
+        .with_context(&context));
+    }
+
+    let allowed_roots =
+        load_active_directory_grants(&state, &actor_id, query.workspace_id.as_deref())?;
+    Ok(Json(AccessScopesResponse {
+        allowed_roots,
+        source_of_truth: SOURCE_OF_TRUTH,
+    }))
+}
+
+pub async fn user_receipts(
+    State(state): State,
+    Extension(context): Extension,
+    Query(query): Query,
+) -> Result, WebError> {
+    let actor_id = ensure_authenticated(&context)?;
+    load_receipts(&state, &actor_id, query.session_id.as_deref(), query.limit)
+}
+
+pub async fn admin_receipts(
+    State(state): State,
+    Extension(context): Extension,
+    Query(query): Query,
+) -> Result, WebError> {
+    let actor_id = ensure_authenticated(&context)?;
+    if !local_folder_source::is_local_access_policy_admin_context(&context) {
+        return Err(WebError::new(
+            StatusCode::FORBIDDEN,
+            "ai_admin_access_forbidden",
+            "需要管理员权限才能访问 ai-admin 端点",
+        )
+        .with_context(&context));
+    }
+    let user_id = query
+        .user_id
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .unwrap_or(&actor_id);
+    load_receipts(&state, user_id, query.session_id.as_deref(), query.limit)
+}
+
+fn load_receipts(
+    state: &AppState,
+    user_id: &str,
+    session_id: Option<&str>,
+    limit: Option,
+) -> Result, WebError> {
+    let limit = limit.unwrap_or(50).clamp(1, 200);
+    let receipts = state
+        .control_plane()
+        .list_ai_tool_events(user_id, session_id, limit)
+        .map_err(|error| WebError::internal(format!("查询 AI receipts 失败: {error}")))?;
+    let patches = state
+        .control_plane()
+        .list_ai_file_patches(user_id, session_id, limit)
+        .map_err(|error| WebError::internal(format!("查询 AI file patches 失败: {error}")))?;
+    Ok(Json(json!({
+        "ok": true,
+        "schema": "mnote.ai.receipts.v1",
+        "userId": user_id,
+        "receipts": receipts,
+        "patches": patches,
+        "receiptCount": receipts.len(),
+        "patchCount": patches.len(),
+        "storage": "control_plane_turso_libsql_v1",
+    })))
+}
+
+// ─── Admin handler implementations ──────────────────────────────────────
+
+/// `GET /api/ai-admin/settings`
+///
+/// Returns the effective admin AI policy, including provider registry,
+/// model list, build-plan-task config, tool-policy overrides, skills
+/// registry, MCP server registry, quota, and revision info.
+///
+/// Admin auth required.  Projects `model_policy_json` from the
+/// control-plane `ai_policies` table (single source of truth).
+pub async fn admin_get_settings(
+    State(state): State,
+    Extension(context): Extension,
+) -> Result, WebError> {
+    let actor_id = ensure_authenticated(&context)?;
+    ensure_admin(&context)?;
+    let global_owner = global_policy_owner_id(&actor_id);
+
+    let policy = state
+        .control_plane()
+        .get_ai_policy(&global_owner, None)
+        .map_err(|error| WebError::internal(format!("读取 AI policy 失败: {error}")))?;
+    let model_policy = policy
+        .as_ref()
+        .and_then(|record| serde_json::from_str(&record.model_policy_json).ok())
+        .unwrap_or_else(|| json!({}));
+    let quota = policy
+        .as_ref()
+        .and_then(|record| serde_json::from_str(&record.quota_json).ok())
+        .unwrap_or_else(|| json!({}));
+    let response = project_admin_settings(&model_policy, "a, policy.as_ref());
+    Ok(Json(response))
+}
+
+/// `PUT /api/ai-admin/settings`
+///
+/// Upserts the AI policy document.  The client provides the desired
+/// policy sections (providers, models, tools, skills, MCP, build-plan,
+/// quota).  `allowed_roots` is never accepted from the client — the
+/// source of truth is `directory_grants`.
+///
+/// Validation rules:
+/// - Provider `secretRef` MUST start with `env://` or `secret://`
+///   (raw API keys rejected).
+/// - MCP servers MUST set `facadeOnly: true` and `sandbox: true`.
+///
+/// On success, appends an audit log entry and returns the new revision.
+pub async fn admin_put_settings(
+    State(state): State,
+    Extension(context): Extension,
+    Json(body): Json,
+) -> Result, WebError> {
+    let actor_id = ensure_authenticated(&context)?;
+    ensure_admin(&context)?;
+    let global_owner = global_policy_owner_id(&actor_id);
+
+    // ── Validate provider secretRefs ──────────────────────────────────
+    if let Some(ref providers) = body.providers {
+        for (provider_id, config) in providers {
+            validate_provider_secret_ref(&config.secret_ref).map_err(|msg| {
+                WebError::new(
+                    StatusCode::UNPROCESSABLE_ENTITY,
+                    "ai_admin_invalid_secret_ref",
+                    format!("Provider \"{provider_id}\": {msg}"),
+                )
+                .with_context(&context)
+            })?;
+        }
+    }
+
+    // ── Validate MCP server configs ───────────────────────────────────
+    if let Some(ref servers) = body.mcp_servers {
+        for (server_id, config) in servers {
+            validate_mcp_server_config(config).map_err(|msg| {
+                WebError::new(
+                    StatusCode::UNPROCESSABLE_ENTITY,
+                    "ai_admin_invalid_mcp_config",
+                    format!("MCP server \"{server_id}\": {msg}"),
+                )
+                .with_context(&context)
+            })?;
+        }
+    }
+
+    // ── Load existing policy, merge inputs ────────────────────────────
+    let workspace_id = body.workspace_id.as_deref();
+    let existing = state
+        .control_plane()
+        .get_ai_policy(&global_owner, workspace_id)
+        .map_err(|e| WebError::internal(format!("读取 AI policy 失败: {e}")))?;
+
+    let (merged_model_policy_json, merged_quota_json) =
+        merge_policy_with_existing(existing.as_ref(), &body);
+
+    // ── Upsert ────────────────────────────────────────────────────────
+    let upsert_input = control_plane::UpsertAiPolicyInput {
+        id: None,
+        user_id: Some(global_owner),
+        workspace_id: workspace_id.map(String::from),
+        allowed_roots_json: existing
+            .as_ref()
+            .map(|record| record.allowed_roots_json.clone())
+            .unwrap_or_else(|| "[]".into()),
+        model_policy_json: merged_model_policy_json,
+        quota_json: merged_quota_json,
+    };
+    let result = state
+        .control_plane()
+        .upsert_ai_policy(upsert_input)
+        .map_err(|e| WebError::internal(format!("更新 AI policy 失败: {e}")))?;
+
+    // ── Append audit ──────────────────────────────────────────────────
+    let audit_metadata = serde_json::json!({
+        "revision": result.revision,
+        "workspaceId": workspace_id,
+        "updatedFields": describe_updated_fields(&body),
+    });
+    let _ = state.control_plane().append_audit(AppendAuditInput {
+        actor_user_id: Some(actor_id),
+        action: "admin.upsert_ai_policy".into(),
+        target_kind: "ai_policy".into(),
+        target_id: Some(result.id.clone()),
+        metadata_json: audit_metadata.to_string(),
+    });
+
+    Ok(Json(AdminAiSettingsUpsertResponse {
+        ok: true,
+        schema: "mnote.admin.ai.settings.upsert.v1",
+        revision: result.revision,
+        updated_at: result.updated_at,
+    }))
+}
+
+pub async fn admin_list_users(
+    State(state): State,
+    Extension(context): Extension,
+) -> Result, WebError> {
+    ensure_authenticated(&context)?;
+    ensure_admin(&context)?;
+    let users = state
+        .control_plane()
+        .list_users(500)
+        .map_err(|error| WebError::internal(format!("读取用户列表失败: {error}")))?;
+    let users = users
+        .into_iter()
+        .map(|user| {
+            json!({
+                "id": user.id,
+                "email": user.email,
+                "username": user.username,
+                "displayName": user.display_name,
+                "role": if is_configured_admin_user(&user.id) { "admin" } else { user.role.as_str() },
+                "status": user.status,
+                "createdAt": user.created_at,
+                "updatedAt": user.updated_at,
+            })
+        })
+        .collect::>();
+    Ok(Json(json!({
+        "ok": true,
+        "schema": "mnote.admin.ai.users.v1",
+        "users": users,
+    })))
+}
+
+pub async fn admin_get_user_settings(
+    State(state): State,
+    Extension(context): Extension,
+    Path(user_id): Path,
+) -> Result, WebError> {
+    let actor_id = ensure_authenticated(&context)?;
+    ensure_admin(&context)?;
+    ensure_known_user(&state, &user_id)?;
+    let global_owner = global_policy_owner_id(&actor_id);
+    let global_policy = load_policy_value(&state, &global_owner, None);
+    let user_policy = if user_id == global_owner {
+        json!({})
+    } else {
+        load_policy_value(&state, &user_id, None)
+    };
+    Ok(Json(project_user_settings(
+        &user_id,
+        &global_owner,
+        &global_policy,
+        &user_policy,
+    )))
+}
+
+pub async fn admin_put_user_settings(
+    State(state): State,
+    Extension(context): Extension,
+    Path(user_id): Path,
+    Json(body): Json,
+) -> Result, WebError> {
+    let actor_id = ensure_authenticated(&context)?;
+    ensure_admin(&context)?;
+    ensure_known_user(&state, &user_id)?;
+    let global_owner = global_policy_owner_id(&actor_id);
+    if user_id == global_owner {
+        return Err(WebError::new(
+            StatusCode::UNPROCESSABLE_ENTITY,
+            "ai_admin_global_owner_override_forbidden",
+            "全局策略管理员请在模型、工具或技能/MCP 页面修改默认策略",
+        )
+        .with_context(&context));
+    }
+
+    let global_policy = load_policy_value(&state, &global_owner, None);
+    validate_user_policy_body(&body, &global_policy).map_err(|message| {
+        WebError::new(
+            StatusCode::UNPROCESSABLE_ENTITY,
+            "ai_admin_invalid_user_policy",
+            message,
+        )
+        .with_context(&context)
+    })?;
+    let updated_fields = describe_user_updated_fields(&body);
+    let existing = state
+        .control_plane()
+        .get_ai_policy(&user_id, None)
+        .map_err(|error| WebError::internal(format!("读取用户 AI policy 失败: {error}")))?;
+    let mut policy = existing
+        .as_ref()
+        .and_then(|record| serde_json::from_str::(&record.model_policy_json).ok())
+        .unwrap_or_else(|| json!({}));
+    if let Some(value) = body.default_model {
+        policy["defaultModel"] = json!(value);
+    }
+    if let Some(value) = body.allowed_models {
+        policy["allowedModels"] = json!(value);
+    }
+    if let Some(value) = body.tools {
+        policy["tools"] = json!(value);
+    }
+    if let Some(value) = body.skills {
+        policy["skillOverrides"] = json!(value);
+    }
+    if let Some(value) = body.mcp_servers {
+        policy["mcpOverrides"] = json!(value);
+    }
+    let result = state
+        .control_plane()
+        .upsert_ai_policy(control_plane::UpsertAiPolicyInput {
+            id: None,
+            user_id: Some(user_id.clone()),
+            workspace_id: None,
+            allowed_roots_json: existing
+                .as_ref()
+                .map(|record| record.allowed_roots_json.clone())
+                .unwrap_or_else(|| "[]".into()),
+            model_policy_json: serde_json::to_string(&policy).unwrap_or_else(|_| "{}".into()),
+            quota_json: existing
+                .as_ref()
+                .map(|record| record.quota_json.clone())
+                .unwrap_or_else(|| "{}".into()),
+        })
+        .map_err(|error| WebError::internal(format!("保存用户 AI policy 失败: {error}")))?;
+    let _ = state.control_plane().append_audit(AppendAuditInput {
+        actor_user_id: Some(actor_id),
+        action: "admin.upsert_user_ai_policy".into(),
+        target_kind: "user_ai_policy".into(),
+        target_id: Some(user_id.clone()),
+        metadata_json: json!({
+            "revision": result.revision,
+            "updatedFields": updated_fields,
+        })
+        .to_string(),
+    });
+    Ok(Json(json!({
+        "ok": true,
+        "schema": "mnote.admin.ai.user-settings.upsert.v1",
+        "userId": user_id,
+        "revision": result.revision,
+        "updatedAt": result.updated_at,
+    })))
+}
+
+// ─── Constants ──────────────────────────────────────────────────────────
+
+const DEFAULT_PI_MODEL: &str = "omniroute/freefirst";
+const LIGHTRAG_PROVIDER: &str = "lightrag";
+const LIGHTRAG_PROVIDER_DESCRIPTION: &str = "MNote 知识库默认提供者（LightRAG）";
+const SOURCE_OF_TRUTH: &str = "directory_grants";
+const ADMIN_ACCESS_POLICY_PATH: &str = "/admin/access-policy";
+const USER_ACCESS_POLICY_PATH: &str = "/user/access-policy";
+
+fn default_mcp_transport() -> String {
+    "stdio".into()
+}
+
+fn default_mcp_network_policy() -> String {
+    "deny-all".into()
+}
+
+/// Canonical MNote-owned tool catalog for local-first AI editing.
+const MNOTE_TOOL_CATALOG: &[ToolCatalogEntry] = &[
+    ToolCatalogEntry {
+        name: "mnote.current_page.read",
+        description: "读取当前 MNote 页面",
+        default_policy: "allow",
+    },
+    ToolCatalogEntry {
+        name: "mnote.selection.read",
+        description: "读取当前编辑器选区",
+        default_policy: "allow",
+    },
+    ToolCatalogEntry {
+        name: "mnote.allowed_roots.describe",
+        description: "描述当前目录授权范围",
+        default_policy: "allow",
+    },
+    ToolCatalogEntry {
+        name: "mnote.local_file.read",
+        description: "读取授权目录内的本地文件",
+        default_policy: "ask",
+    },
+    ToolCatalogEntry {
+        name: "mnote.local_file.patch",
+        description: "修改授权目录内的本地文件",
+        default_policy: "ask",
+    },
+    ToolCatalogEntry {
+        name: "mnote.knowledge_rag.query",
+        description: "通过 MNote LightRAG facade 查询知识库",
+        default_policy: "allow",
+    },
+    ToolCatalogEntry {
+        name: "mnote.reference.open",
+        description: "打开知识库引用来源",
+        default_policy: "allow",
+    },
+    ToolCatalogEntry {
+        name: "mnote.tool_receipt.write",
+        description: "记录工具调用回执",
+        default_policy: "allow",
+    },
+];
+
+fn skill_config(
+    name: &str,
+    description: &str,
+    source: &str,
+    risk_level: &str,
+    required_scopes: &[&str],
+) -> SkillConfig {
+    SkillConfig {
+        name: name.into(),
+        enabled: true,
+        description: description.into(),
+        source: source.into(),
+        risk_level: risk_level.into(),
+        required_scopes: required_scopes.iter().map(|scope| (*scope).into()).collect(),
+    }
+}
+
+fn mcp_server_config(
+    name: &str,
+    description: &str,
+    transport: &str,
+    command: &str,
+    url: &str,
+    network_policy: &str,
+    secret_refs: &[&str],
+    risk_level: &str,
+    required_scopes: &[&str],
+) -> McpServerConfig {
+    McpServerConfig {
+        name: name.into(),
+        enabled: true,
+        url: url.into(),
+        transport: transport.into(),
+        command: command.into(),
+        network_policy: network_policy.into(),
+        secret_refs: secret_refs.iter().map(|value| (*value).into()).collect(),
+        facade_only: true,
+        sandbox: true,
+        description: description.into(),
+        risk_level: risk_level.into(),
+        required_scopes: required_scopes.iter().map(|scope| (*scope).into()).collect(),
+    }
+}
+
+fn default_skill_registry() -> HashMap {
+    let mut skills = HashMap::new();
+    skills.insert(
+        "vpn".into(),
+        skill_config(
+            "VPN",
+            "通过 MNote facade 协助诊断代理、出海访问和本机网络路由问题。",
+            "/home/lix/.codex/skills/vpn/SKILL.md",
+            "high",
+            &["network:diagnose", "admin:network"],
+        ),
+    );
+    skills.insert(
+        "chrome-bridge".into(),
+        skill_config(
+            "Chrome Bridge",
+            "通过受控浏览器桥接执行页面验证、截图和 DOM/网络诊断。",
+            "mcp://chrome-bridge",
+            "high",
+            &["browser:automation", "qa:browser"],
+        ),
+    );
+    skills.insert(
+        "context7".into(),
+        skill_config(
+            "Context7",
+            "查询最新官方库文档、API 参数和发布说明。",
+            "/home/lix/.codex/skills/context7/SKILL.md",
+            "medium",
+            &["network:docs"],
+        ),
+    );
+    skills.insert(
+        "searxng".into(),
+        skill_config(
+            "SearXNG Search",
+            "通过本地 SearXNG MCP 做通用网页检索并保留引用。",
+            "mcp://searxng",
+            "medium",
+            &["network:search"],
+        ),
+    );
+    skills.insert(
+        "global-search".into(),
+        skill_config(
+            "Global Search",
+            "聚合本机/网页搜索线索，适合研究型查询入口。",
+            "/home/lix/.hermes/profiles/lite/skills/global-search/SKILL.md",
+            "medium",
+            &["network:search"],
+        ),
+    );
+    skills.insert(
+        "mempalace".into(),
+        skill_config(
+            "MemPalace",
+            "读取共享记忆与历史决策事实层，默认通过 MCP facade 受控访问。",
+            "mcp://mempalace",
+            "medium",
+            &["memory:read"],
+        ),
+    );
+    skills.insert(
+        "codegraph".into(),
+        skill_config(
+            "CodeGraph",
+            "读取项目代码图、符号和调用关系，适合开发者工作区。",
+            "mcp://codegraph",
+            "medium",
+            &["workspace:code-read"],
+        ),
+    );
+    skills
+}
+
+fn default_mcp_server_registry() -> HashMap {
+    let mut servers = HashMap::new();
+    servers.insert(
+        "chrome-bridge".into(),
+        mcp_server_config(
+            "Chrome Bridge",
+            "本机 Chromium/Chrome 桥接，用于浏览器 QA、截图与网络请求核验。",
+            "stdio",
+            "node /home/lix/apps/codex-chrome-bridge/mcp/chrome-bridge-mcp.mjs",
+            "",
+            "allow-local",
+            &[],
+            "high",
+            &["browser:automation", "qa:browser"],
+        ),
+    );
+    servers.insert(
+        "context7".into(),
+        mcp_server_config(
+            "Context7",
+            "官方文档检索 MCP，密钥只允许通过 env://CONTEXT7_API_KEY 引用。",
+            "streamable-http",
+            "",
+            "https://mcp.context7.com/mcp",
+            "allow-all",
+            &["env://CONTEXT7_API_KEY"],
+            "medium",
+            &["network:docs"],
+        ),
+    );
+    servers.insert(
+        "searxng".into(),
+        mcp_server_config(
+            "SearXNG",
+            "本地 SearXNG 检索 MCP，默认只允许访问本地聚合服务。",
+            "stdio",
+            "node /home/lix/.agent-infra/searxng/codex-searxng-mcp.cjs",
+            "",
+            "allow-local",
+            &[],
+            "medium",
+            &["network:search"],
+        ),
+    );
+    servers.insert(
+        "mempalace".into(),
+        mcp_server_config(
+            "MemPalace",
+            "共享记忆事实层 MCP，默认只开放 facade/sandbox 后的受控记忆访问。",
+            "stdio",
+            "/home/lix/.local/share/uv/tools/mempalace/bin/python -m mempalace.mcp_server --palace /home/lix/.mempalace/palace",
+            "",
+            "deny-all",
+            &[],
+            "medium",
+            &["memory:read"],
+        ),
+    );
+    servers.insert(
+        "codegraph".into(),
+        mcp_server_config(
+            "CodeGraph",
+            "代码图 MCP，默认用于只读符号、调用链和影响面查询。",
+            "stdio",
+            "codegraph serve --mcp",
+            "",
+            "deny-all",
+            &[],
+            "medium",
+            &["workspace:code-read"],
+        ),
+    );
+    servers
+}
+
+fn effective_skill_registry(model_policy: &Value) -> HashMap {
+    let mut skills = default_skill_registry();
+    let configured = policy_map::(model_policy, "skills");
+    for (id, config) in configured {
+        skills.insert(id, config);
+    }
+    skills
+}
+
+fn effective_mcp_registry(model_policy: &Value) -> HashMap {
+    let mut servers = default_mcp_server_registry();
+    let configured = policy_map::(model_policy, "mcpServers");
+    for (id, config) in configured {
+        servers.insert(id, config);
+    }
+    servers
+}
+
+// ─── Internal helpers ───────────────────────────────────────────────────
+
+/// Rejects unauthenticated / anonymous requests and returns the actor id.
+fn ensure_authenticated(context: &RequestContext) -> Result {
+    let actor_id = context.auth.actor_id.trim();
+    let actor_type = context.auth.actor_type.trim();
+    if actor_id.is_empty()
+        || actor_id == "anonymous"
+        || actor_type.is_empty()
+        || actor_type == "anonymous"
+    {
+        return Err(WebError::new(
+            StatusCode::UNAUTHORIZED,
+            "ai_settings_unauthorized",
+            "需要 MNote 登录态才能访问 AI 设置",
+        )
+        .with_context(context));
+    }
+    Ok(actor_id.to_string())
+}
+
+/// Reads `ai_policies` for model_policy and quota only.
+/// Returns empty objects when no policy exists or on error.
+/// Never reads `allowed_roots_json`.
+fn load_model_policy_and_quota(
+    state: &AppState,
+    actor_id: &str,
+    workspace_id: Option<&str>,
+) -> (Value, Value) {
+    let policy = match state.control_plane().get_ai_policy(actor_id, workspace_id) {
+        Ok(Some(p)) => p,
+        _ => return (json!({}), json!({})),
+    };
+    let model_policy = serde_json::from_str(&policy.model_policy_json).unwrap_or(json!({}));
+    let quota = serde_json::from_str(&policy.quota_json).unwrap_or(json!({}));
+    (model_policy, quota)
+}
+
+fn load_effective_model_policy_and_quota(
+    state: &AppState,
+    actor_id: &str,
+    workspace_id: Option<&str>,
+) -> (Value, Value) {
+    let global_owner = global_policy_owner_id(actor_id);
+    let (global_policy, global_quota) = load_model_policy_and_quota(state, &global_owner, None);
+    if actor_id == global_owner && workspace_id.is_none() {
+        return (global_policy, global_quota);
+    }
+    let (user_policy, user_quota) = load_model_policy_and_quota(state, actor_id, workspace_id);
+    (
+        merge_effective_user_policy(&global_policy, &user_policy),
+        merge_json_objects(&global_quota, &user_quota),
+    )
+}
+
+fn global_policy_owner_id(fallback_actor_id: &str) -> String {
+    std::env::var("MNOTE_ADMIN_USER_IDS")
+        .ok()
+        .and_then(|value| {
+            value
+                .split(',')
+                .map(str::trim)
+                .find(|value| !value.is_empty())
+                .map(str::to_string)
+        })
+        .unwrap_or_else(|| fallback_actor_id.to_string())
+}
+
+fn is_configured_admin_user(user_id: &str) -> bool {
+    std::env::var("MNOTE_ADMIN_USER_IDS")
+        .ok()
+        .map(|value| {
+            value
+                .split(',')
+                .map(str::trim)
+                .any(|value| !value.is_empty() && value == user_id)
+        })
+        .unwrap_or(false)
+}
+
+fn load_policy_value(state: &AppState, actor_id: &str, workspace_id: Option<&str>) -> Value {
+    load_model_policy_and_quota(state, actor_id, workspace_id).0
+}
+
+fn merge_json_objects(base: &Value, override_value: &Value) -> Value {
+    let mut merged = base.clone();
+    if !merged.is_object() {
+        merged = json!({});
+    }
+    if let Some(values) = override_value.as_object() {
+        for (key, value) in values {
+            merged[key] = value.clone();
+        }
+    }
+    merged
+}
+
+fn merge_effective_user_policy(global_policy: &Value, user_policy: &Value) -> Value {
+    let mut merged = global_policy.clone();
+    if !merged.is_object() {
+        merged = json!({});
+    }
+    for key in ["allowedModels", "defaultModel", "buildPlanTask"] {
+        if let Some(value) = user_policy.get(key) {
+            merged[key] = value.clone();
+        }
+    }
+    if let Some(overrides) = user_policy.get("tools").and_then(Value::as_object) {
+        let target = merged
+            .as_object_mut()
+            .expect("effective policy object")
+            .entry("tools")
+            .or_insert_with(|| json!({}));
+        if !target.is_object() {
+            *target = json!({});
+        }
+        for (name, value) in overrides {
+            target[name] = value.clone();
+        }
+    }
+    if let Some(overrides) = user_policy.get("skillOverrides").and_then(Value::as_object) {
+        let target = merged
+            .as_object_mut()
+            .expect("effective policy object")
+            .entry("skills")
+            .or_insert_with(|| serde_json::to_value(default_skill_registry()).unwrap_or(json!({})));
+        if !target.is_object() {
+            *target = serde_json::to_value(default_skill_registry()).unwrap_or(json!({}));
+        }
+        if let Some(skills) = target.as_object_mut() {
+            for (name, enabled) in overrides {
+                if let Some(skill) = skills.get_mut(name) {
+                    skill["enabled"] = json!(enabled.as_bool().unwrap_or(false));
+                }
+            }
+        }
+    }
+    if let Some(overrides) = user_policy.get("mcpOverrides").and_then(Value::as_object) {
+        let target = merged
+            .as_object_mut()
+            .expect("effective policy object")
+            .entry("mcpServers")
+            .or_insert_with(|| serde_json::to_value(default_mcp_server_registry()).unwrap_or(json!({})));
+        if !target.is_object() {
+            *target = serde_json::to_value(default_mcp_server_registry()).unwrap_or(json!({}));
+        }
+        if let Some(servers) = target.as_object_mut() {
+            for (name, enabled) in overrides {
+                if let Some(server) = servers.get_mut(name) {
+                    server["enabled"] = json!(enabled.as_bool().unwrap_or(false));
+                }
+            }
+        }
+    }
+    merged
+}
+
+fn effective_default_model(model_policy: &Value) -> String {
+    model_policy
+        .get("defaultModel")
+        .or_else(|| model_policy.get("default_model"))
+        .and_then(Value::as_str)
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .unwrap_or(DEFAULT_PI_MODEL)
+        .to_string()
+}
+
+fn effective_models(model_policy: &Value, default_model: &str) -> Vec {
+    let mut model_ids = model_policy
+        .get("allowedModels")
+        .or_else(|| model_policy.get("allowed_models"))
+        .and_then(Value::as_array)
+        .into_iter()
+        .flatten()
+        .filter_map(Value::as_str)
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(str::to_string)
+        .collect::>();
+    if !model_ids.iter().any(|value| value == default_model) {
+        model_ids.insert(0, default_model.to_string());
+    }
+    model_ids
+        .into_iter()
+        .map(|id| {
+            let name = id.clone();
+            ModelEntry {
+                provider: "omniroute",
+                is_default: id == default_model,
+                id,
+                name,
+                enabled: true,
+            }
+        })
+        .collect()
+}
+
+fn policy_map(model_policy: &Value, key: &str) -> HashMap
+where
+    T: for<'de> Deserialize<'de>,
+{
+    model_policy
+        .get(key)
+        .and_then(|value| serde_json::from_value(value.clone()).ok())
+        .unwrap_or_default()
+}
+
+fn policy_string_map(model_policy: &Value, key: &str) -> HashMap {
+    model_policy
+        .get(key)
+        .and_then(Value::as_object)
+        .map(|values| {
+            values
+                .iter()
+                .filter_map(|(name, value)| {
+                    value
+                        .as_str()
+                        .map(|policy| (name.clone(), policy.to_string()))
+                })
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+fn effective_tool_catalog(policies: &HashMap) -> Vec {
+    MNOTE_TOOL_CATALOG
+        .iter()
+        .cloned()
+        .map(|mut entry| {
+            if let Some(policy) = policies.get(entry.name) {
+                entry.default_policy = match policy.as_str() {
+                    "allow" => "allow",
+                    "ask" => "ask",
+                    _ => "deny",
+                };
+            }
+            entry
+        })
+        .collect()
+}
+
+/// Loads `directory_grants` for the given actor, filters to active entries,
+/// and maps to API-friendly `AccessScopeEntry` values.
+fn load_active_directory_grants(
+    state: &AppState,
+    actor_id: &str,
+    workspace_id: Option<&str>,
+) -> Result, WebError> {
+    let grants = state
+        .control_plane()
+        .list_directory_grants_for_actor(actor_id)
+        .map_err(|e| WebError::internal(format!("读取目录授权失败: {e}")))?;
+    Ok(filter_directory_grants_to_access_scopes(
+        grants,
+        workspace_id,
+    ))
+}
+
+/// Pure function: filters `DirectoryGrantRecord` items to active entries,
+/// optionally narrowed by workspace, and maps to `AccessScopeEntry`.
+fn filter_directory_grants_to_access_scopes(
+    grants: Vec,
+    workspace_id: Option<&str>,
+) -> Vec {
+    grants
+        .into_iter()
+        .filter(|g| g.status.trim() == "active")
+        .filter(|g| workspace_id.map_or(true, |ws| g.workspace_id.as_deref() == Some(ws)))
+        .map(|g| {
+            let capabilities = serde_json::from_str(&g.capabilities_json).unwrap_or(json!({}));
+            AccessScopeEntry {
+                id: g.id,
+                user_id: g.user_id,
+                workspace_id: g.workspace_id,
+                root_uri: g.root_uri,
+                root_path: g.root_path,
+                permission: g.permission,
+                recursive: g.recursive,
+                capabilities,
+                source: g.source,
+                status: g.status,
+                created_at: g.created_at,
+                updated_at: g.updated_at,
+            }
+        })
+        .collect()
+}
+
+// ─── Admin helpers ──────────────────────────────────────────────────────
+
+/// Ensures admin auth.  Reuses the existing admin check from
+/// `local_folder_source::is_local_access_policy_admin_context`.
+fn ensure_admin(context: &RequestContext) -> Result<(), WebError> {
+    if !local_folder_source::is_local_access_policy_admin_context(context) {
+        return Err(WebError::new(
+            StatusCode::FORBIDDEN,
+            "ai_admin_access_forbidden",
+            "需要管理员权限",
+        )
+        .with_context(context));
+    }
+    Ok(())
+}
+
+fn ensure_known_user(state: &AppState, user_id: &str) -> Result<(), WebError> {
+    let user_id = user_id.trim();
+    if user_id.is_empty() {
+        return Err(WebError::new(
+            StatusCode::UNPROCESSABLE_ENTITY,
+            "ai_admin_invalid_user",
+            "用户 ID 不能为空",
+        ));
+    }
+    let exists = state
+        .control_plane()
+        .list_users(500)
+        .map_err(|error| WebError::internal(format!("读取用户列表失败: {error}")))?
+        .into_iter()
+        .any(|user| user.id == user_id);
+    if !exists {
+        return Err(WebError::new(
+            StatusCode::NOT_FOUND,
+            "ai_admin_user_not_found",
+            "用户不存在",
+        ));
+    }
+    Ok(())
+}
+
+fn validate_user_policy_body(body: &UserAiPolicyBody, global_policy: &Value) -> Result<(), String> {
+    let global_models = global_policy
+        .get("allowedModels")
+        .and_then(Value::as_array)
+        .into_iter()
+        .flatten()
+        .filter_map(Value::as_str)
+        .collect::>();
+    if let Some(models) = &body.allowed_models {
+        for model in models {
+            if !global_models.contains(model.trim()) {
+                return Err(format!("模型 {model} 不在管理员允许范围内"));
+            }
+        }
+    }
+    if let Some(default_model) = &body.default_model {
+        let allowed = body
+            .allowed_models
+            .as_ref()
+            .map(|models| models.iter().any(|model| model == default_model))
+            .unwrap_or_else(|| global_models.contains(default_model.as_str()));
+        if !allowed {
+            return Err("默认模型必须属于该用户允许的模型".into());
+        }
+    }
+    let global_tools = policy_string_map(global_policy, "tools");
+    if let Some(tools) = &body.tools {
+        for (name, action) in tools {
+            if !matches!(action.as_str(), "allow" | "ask" | "deny") {
+                return Err(format!("工具 {name} 的策略非法"));
+            }
+            let global_action = global_tools
+                .get(name)
+                .map(String::as_str)
+                .or_else(|| {
+                    MNOTE_TOOL_CATALOG
+                        .iter()
+                        .find(|tool| tool.name == name)
+                        .map(|tool| tool.default_policy)
+                })
+                .unwrap_or("deny");
+            if tool_policy_rank(action) > tool_policy_rank(global_action) {
+                return Err(format!("工具 {name} 不能高于全局策略 {global_action}"));
+            }
+        }
+    }
+    let global_skills = effective_skill_registry(global_policy);
+    if let Some(skills) = &body.skills {
+        for (name, enabled) in skills {
+            if *enabled
+                && !global_skills
+                    .get(name)
+                    .map(|skill| skill.enabled)
+                    .unwrap_or(false)
+            {
+                return Err(format!("Skill {name} 未被管理员全局启用"));
+            }
+        }
+    }
+    let global_mcp = effective_mcp_registry(global_policy);
+    if let Some(servers) = &body.mcp_servers {
+        for (name, enabled) in servers {
+            if *enabled
+                && !global_mcp
+                    .get(name)
+                    .map(|server| server.enabled && server.facade_only && server.sandbox)
+                    .unwrap_or(false)
+            {
+                return Err(format!("MCP {name} 未被管理员全局启用"));
+            }
+        }
+    }
+    Ok(())
+}
+
+fn tool_policy_rank(action: &str) -> u8 {
+    match action {
+        "allow" => 2,
+        "ask" => 1,
+        _ => 0,
+    }
+}
+
+fn project_user_settings(
+    user_id: &str,
+    global_owner: &str,
+    global_policy: &Value,
+    user_policy: &Value,
+) -> Value {
+    let effective = merge_effective_user_policy(global_policy, user_policy);
+    let global_models = effective_models(global_policy, &effective_default_model(global_policy));
+    let allowed_models = effective_models(&effective, &effective_default_model(&effective));
+    let global_tools = policy_string_map(global_policy, "tools");
+    let user_tools = policy_string_map(user_policy, "tools");
+    let skills = effective_skill_registry(global_policy)
+        .into_iter()
+        .map(|(id, skill)| {
+            let override_value = user_policy
+                .get("skillOverrides")
+                .and_then(|value| value.get(&id))
+                .and_then(Value::as_bool);
+            json!({
+                "id": id,
+                "name": skill.name,
+                "globallyEnabled": skill.enabled,
+                "enabled": override_value.unwrap_or(skill.enabled),
+                "hasOverride": override_value.is_some(),
+            })
+        })
+        .collect::>();
+    let mcp_servers = effective_mcp_registry(global_policy)
+        .into_iter()
+        .map(|(id, server)| {
+            let override_value = user_policy
+                .get("mcpOverrides")
+                .and_then(|value| value.get(&id))
+                .and_then(Value::as_bool);
+            json!({
+                "id": id,
+                "name": server.name,
+                "globallyEnabled": server.enabled,
+                "enabled": override_value.unwrap_or(server.enabled),
+                "hasOverride": override_value.is_some(),
+                "transport": server.transport,
+                "facadeOnly": server.facade_only,
+                "sandbox": server.sandbox,
+            })
+        })
+        .collect::>();
+    let tools = MNOTE_TOOL_CATALOG
+        .iter()
+        .map(|tool| {
+            let global_action = global_tools
+                .get(tool.name)
+                .map(String::as_str)
+                .unwrap_or(tool.default_policy);
+            let user_action = user_tools.get(tool.name);
+            json!({
+                "name": tool.name,
+                "description": tool.description,
+                "globalAction": global_action,
+                "action": user_action.map(String::as_str).unwrap_or(global_action),
+                "hasOverride": user_action.is_some(),
+            })
+        })
+        .collect::>();
+    json!({
+        "ok": true,
+        "schema": "mnote.admin.ai.user-settings.v1",
+        "userId": user_id,
+        "globalPolicyOwner": global_owner,
+        "isGlobalPolicyOwner": user_id == global_owner,
+        "defaultModel": effective_default_model(&effective),
+        "catalogModels": global_models,
+        "allowedModels": allowed_models,
+        "tools": tools,
+        "skills": skills,
+        "mcpServers": mcp_servers,
+    })
+}
+
+fn describe_user_updated_fields(body: &UserAiPolicyBody) -> Vec<&'static str> {
+    let mut fields = Vec::new();
+    if body.default_model.is_some() {
+        fields.push("defaultModel");
+    }
+    if body.allowed_models.is_some() {
+        fields.push("allowedModels");
+    }
+    if body.tools.is_some() {
+        fields.push("tools");
+    }
+    if body.skills.is_some() {
+        fields.push("skillOverrides");
+    }
+    if body.mcp_servers.is_some() {
+        fields.push("mcpOverrides");
+    }
+    fields
+}
+
+/// Validates that a provider `secretRef` is an `env://` or `secret://`
+/// reference.  Raw API keys or empty strings are rejected.
+fn validate_provider_secret_ref(secret_ref: &str) -> Result<(), String> {
+    let trimmed = secret_ref.trim();
+    if trimmed.is_empty() {
+        return Err("secretRef 不能为空".into());
+    }
+    if trimmed.starts_with("env://") || trimmed.starts_with("secret://") {
+        Ok(())
+    } else {
+        Err("secretRef 必须是 env:// 或 secret:// 引用，不允许直接传 API Key".into())
+    }
+}
+
+/// Validates that an MCP server config has `facadeOnly: true` and
+/// `sandbox: true`.
+fn validate_mcp_server_config(config: &McpServerConfig) -> Result<(), String> {
+    if !config.facade_only {
+        return Err("MCP 服务器必须启用 facadeOnly 模式".into());
+    }
+    if !config.sandbox {
+        return Err("MCP 服务器必须启用 sandbox".into());
+    }
+    if !matches!(
+        config.transport.as_str(),
+        "stdio" | "sse" | "streamable-http"
+    ) {
+        return Err("MCP transport 只允许 stdio、sse 或 streamable-http".into());
+    }
+    if config.transport == "stdio" && config.command.trim().is_empty() {
+        return Err("stdio MCP 必须配置 command".into());
+    }
+    if config.transport != "stdio" && config.url.trim().is_empty() {
+        return Err("网络 MCP 必须配置 URL".into());
+    }
+    if !matches!(
+        config.network_policy.as_str(),
+        "deny-all" | "allow-local" | "allow-all"
+    ) {
+        return Err("MCP networkPolicy 非法".into());
+    }
+    for secret_ref in &config.secret_refs {
+        validate_provider_secret_ref(secret_ref)?;
+    }
+    Ok(())
+}
+
+/// Merges the client-provided body into the existing policy (if any).
+/// Returns `(model_policy_json, quota_json)` strings suitable for
+/// `UpsertAiPolicyInput`.
+///
+/// `allowed_roots_json` is never touched — it stays at its persisted
+/// value (or empty if no existing policy).
+fn merge_policy_with_existing(
+    existing: Option<&control_plane::AiPolicyRecord>,
+    body: &UpsertAiPolicyBody,
+) -> (String, String) {
+    let mut model_policy = existing
+        .and_then(|rec| serde_json::from_str::(&rec.model_policy_json).ok())
+        .unwrap_or_else(|| json!({}));
+
+    // ── Merge scalar fields ─────────────────────────────────────────
+    if let Some(ref val) = body.default_model {
+        model_policy["defaultModel"] = json!(val);
+    }
+    if let Some(ref val) = body.allowed_models {
+        model_policy["allowedModels"] = json!(val);
+    }
+    if let Some(ref val) = body.build_plan_task {
+        model_policy["buildPlanTask"] = serde_json::to_value(val).unwrap_or(json!({}));
+    }
+
+    // ── Merge providers map ─────────────────────────────────────────
+    if let Some(ref providers) = body.providers {
+        let current = model_policy
+            .get("providers")
+            .and_then(|v| v.as_object())
+            .map(|m| m.clone())
+            .unwrap_or_default();
+        let mut merged = serde_json::Map::new();
+        for (k, v) in current {
+            merged.insert(k, v.clone());
+        }
+        for (k, v) in providers {
+            let val = serde_json::to_value(v).unwrap_or(json!({}));
+            merged.insert(k.clone(), val);
+        }
+        model_policy["providers"] = Value::Object(merged);
+    }
+
+    // ── Merge tools overrides map ───────────────────────────────────
+    if let Some(ref tools) = body.tools {
+        let current = model_policy
+            .get("tools")
+            .and_then(|v| v.as_object())
+            .map(|m| m.clone())
+            .unwrap_or_default();
+        let mut merged = serde_json::Map::new();
+        for (k, v) in current {
+            merged.insert(k, v.clone());
+        }
+        for (k, v) in tools {
+            merged.insert(k.clone(), json!(v));
+        }
+        model_policy["tools"] = Value::Object(merged);
+    }
+
+    // ── Merge skills registry ───────────────────────────────────────
+    if let Some(ref skills) = body.skills {
+        let current = model_policy
+            .get("skills")
+            .and_then(|v| v.as_object())
+            .map(|m| m.clone())
+            .unwrap_or_default();
+        let mut merged = serde_json::Map::new();
+        for (k, v) in current {
+            merged.insert(k, v.clone());
+        }
+        for (k, v) in skills {
+            let val = serde_json::to_value(v).unwrap_or(json!({}));
+            merged.insert(k.clone(), val);
+        }
+        model_policy["skills"] = Value::Object(merged);
+    }
+
+    // ── Merge MCP servers map ───────────────────────────────────────
+    if let Some(ref servers) = body.mcp_servers {
+        let current = model_policy
+            .get("mcpServers")
+            .and_then(|v| v.as_object())
+            .map(|m| m.clone())
+            .unwrap_or_default();
+        let mut merged = serde_json::Map::new();
+        for (k, v) in current {
+            merged.insert(k, v.clone());
+        }
+        for (k, v) in servers {
+            let val = serde_json::to_value(v).unwrap_or(json!({}));
+            merged.insert(k.clone(), val);
+        }
+        model_policy["mcpServers"] = Value::Object(merged);
+    }
+
+    let model_policy_json = serde_json::to_string(&model_policy).unwrap_or_else(|_| "{}".into());
+
+    // ── Merge quota ─────────────────────────────────────────────────
+    let quota_json = if let Some(ref quota) = body.quota {
+        let mut existing_quota = existing
+            .and_then(|rec| serde_json::from_str::(&rec.quota_json).ok())
+            .unwrap_or_else(|| json!({}));
+        if let Some(obj) = quota.as_object() {
+            for (k, v) in obj {
+                existing_quota[k] = v.clone();
+            }
+        } else {
+            existing_quota = quota.clone();
+        }
+        serde_json::to_string(&existing_quota).unwrap_or_else(|_| "{}".into())
+    } else {
+        existing
+            .map(|rec| rec.quota_json.clone())
+            .unwrap_or_else(|| "{}".into())
+    };
+
+    (model_policy_json, quota_json)
+}
+
+/// Project the admin-facing effective settings view from the raw
+/// model_policy JSON.
+fn project_admin_settings(
+    model_policy: &Value,
+    quota: &Value,
+    record: Option<&control_plane::AiPolicyRecord>,
+) -> AdminAiSettingsResponse {
+    let default_model = effective_default_model(model_policy);
+    let allowed_models: Vec = model_policy
+        .get("allowedModels")
+        .or_else(|| model_policy.get("allowed_models"))
+        .and_then(Value::as_array)
+        .into_iter()
+        .flatten()
+        .filter_map(Value::as_str)
+        .map(str::to_string)
+        .collect();
+
+    let mut providers: HashMap = model_policy
+        .get("providers")
+        .and_then(|v| serde_json::from_value(v.clone()).ok())
+        .unwrap_or_default();
+    if providers.is_empty() {
+        providers.insert(
+            "omniroute".into(),
+            ProviderConfig {
+                name: "Omniroute".into(),
+                enabled: true,
+                secret_ref: "env://OMNIROUTE_API_KEY".into(),
+                default_model: default_model.clone(),
+                base_url: String::new(),
+                allowed_models: vec![default_model.clone()],
+                default_build_model: default_model.clone(),
+                default_plan_model: default_model.clone(),
+                default_task_model: default_model.clone(),
+                failover_chains: vec![],
+            },
+        );
+    }
+
+    let build_plan_task = model_policy
+        .get("buildPlanTask")
+        .and_then(|v| serde_json::from_value(v.clone()).ok());
+
+    let tools = model_policy
+        .get("tools")
+        .and_then(|v| {
+            v.as_object().map(|obj| {
+                obj.iter()
+                    .map(|(k, v)| (k.clone(), v.as_str().unwrap_or("deny").to_string()))
+                    .collect::>()
+            })
+        })
+        .unwrap_or_default();
+
+    let skills = effective_skill_registry(model_policy);
+
+    let mcp_servers = effective_mcp_registry(model_policy);
+
+    let revision = record.map(|value| value.revision).unwrap_or(0);
+    let updated_at = record
+        .map(|value| value.updated_at.clone())
+        .unwrap_or_default();
+    let tool_catalog = effective_tool_catalog(&tools);
+
+    AdminAiSettingsResponse {
+        ok: true,
+        schema: "mnote.admin.ai.settings.v1",
+        default_model,
+        allowed_models,
+        providers,
+        build_plan_task,
+        tools,
+        skills,
+        mcp_servers,
+        quota: quota.clone(),
+        revision,
+        updated_at,
+        tool_catalog,
+    }
+}
+
+/// Returns a concise list of field names that were provided in the body,
+/// for audit-log metadata.
+fn describe_updated_fields(body: &UpsertAiPolicyBody) -> Vec<&'static str> {
+    let mut fields: Vec<&'static str> = Vec::new();
+    if body.default_model.is_some() {
+        fields.push("defaultModel");
+    }
+    if body.allowed_models.is_some() {
+        fields.push("allowedModels");
+    }
+    if body.providers.is_some() {
+        fields.push("providers");
+    }
+    if body.build_plan_task.is_some() {
+        fields.push("buildPlanTask");
+    }
+    if body.tools.is_some() {
+        fields.push("tools");
+    }
+    if body.skills.is_some() {
+        fields.push("skills");
+    }
+    if body.mcp_servers.is_some() {
+        fields.push("mcpServers");
+    }
+    if body.quota.is_some() {
+        fields.push("quota");
+    }
+    fields
+}
+
+// ─── Tests ──────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use control_plane::DirectoryGrantRecord;
+
+    fn make_grant(id: &str, workspace_id: Option<&str>, status: &str) -> DirectoryGrantRecord {
+        DirectoryGrantRecord {
+            id: id.into(),
+            user_id: "user_test".into(),
+            workspace_id: workspace_id.map(Into::into),
+            root_uri: format!("file:///mnt/test/{id}"),
+            root_path: format!("/mnt/test/{id}"),
+            permission: "read".into(),
+            recursive: false,
+            capabilities_json: "[]".into(),
+            source: "access_policy".into(),
+            status: status.into(),
+            created_by: None,
+            created_at: "2026-07-04T00:00:00Z".into(),
+            updated_at: "2026-07-04T00:00:00Z".into(),
+            revision: 1,
+        }
+    }
+
+    #[test]
+    fn filter_grants_revoked_are_excluded() {
+        let grants = vec![
+            make_grant("g1", Some("ws_a"), "active"),
+            make_grant("g2", Some("ws_a"), "revoked"),
+        ];
+        let result = filter_directory_grants_to_access_scopes(grants, None);
+        assert_eq!(result.len(), 1);
+        assert_eq!(result[0].id, "g1");
+    }
+
+    #[test]
+    fn filter_grants_workspace_filter() {
+        let grants = vec![
+            make_grant("g1", Some("ws_a"), "active"),
+            make_grant("g2", Some("ws_b"), "active"),
+            make_grant("g3", None, "active"),
+        ];
+        let result = filter_directory_grants_to_access_scopes(grants, Some("ws_a"));
+        assert_eq!(result.len(), 1);
+        assert_eq!(result[0].id, "g1");
+    }
+
+    #[test]
+    fn filter_grants_no_workspace_returns_all_active() {
+        let grants = vec![
+            make_grant("g1", Some("ws_a"), "active"),
+            make_grant("g2", None, "active"),
+        ];
+        let result = filter_directory_grants_to_access_scopes(grants, None);
+        assert_eq!(result.len(), 2);
+    }
+
+    #[test]
+    fn effective_response_includes_directory_grant_roots() {
+        let response = EffectiveAiSettings {
+            default_model: "test/model".into(),
+            providers: vec![],
+            models: vec![],
+            allowed_roots: vec![AccessScopeEntry {
+                id: "grant_1".into(),
+                user_id: "user_1".into(),
+                workspace_id: None,
+                root_uri: "file:///tmp/test".into(),
+                root_path: "/tmp/test".into(),
+                permission: "read".into(),
+                recursive: true,
+                capabilities: json!([]),
+                source: "test".into(),
+                status: "active".into(),
+                created_at: "2026-07-04T00:00:00Z".into(),
+                updated_at: "2026-07-04T00:00:00Z".into(),
+            }],
+            model_policy: json!({"allowedModels": []}),
+            quota: json!({}),
+            tool_catalog: vec![],
+            skills: vec![],
+            mcp_servers: vec![],
+            lightrag_provider: LightRagProviderRef {
+                provider: "test",
+                description: "test provider",
+            },
+            access_policy_links: AccessPolicyLinks {
+                admin: "/admin",
+                user: "/user",
+            },
+            source_of_truth: "directory_grants",
+        };
+        let value = serde_json::to_value(&response).expect("serialize");
+        assert_eq!(value["allowedRoots"][0]["id"], "grant_1");
+        assert_eq!(value["sourceOfTruth"], "directory_grants");
+    }
+
+    #[test]
+    fn model_policy_can_select_default_without_affecting_roots() {
+        let policy = json!({
+            "defaultModel": "omniroute/freefirst",
+            "allowedModels": ["omniroute/freefirst", "omniroute/fast"]
+        });
+        assert_eq!(effective_default_model(&policy), "omniroute/freefirst");
+        let models = effective_models(&policy, "omniroute/freefirst");
+        assert_eq!(models.len(), 2);
+        assert!(models[0].is_default);
+    }
+
+    // ─── Admin body validation ────────────────────────────────────────────
+
+    #[test]
+    fn validate_provider_secret_ref_env_passes() {
+        assert!(validate_provider_secret_ref("env://OPENAI_API_KEY").is_ok());
+    }
+
+    #[test]
+    fn validate_provider_secret_ref_secret_passes() {
+        assert!(validate_provider_secret_ref("secret://my-vault-key").is_ok());
+    }
+
+    #[test]
+    fn validate_provider_secret_ref_empty_fails() {
+        assert!(validate_provider_secret_ref("").is_err());
+    }
+
+    #[test]
+    fn validate_provider_secret_ref_raw_key_fails() {
+        assert!(validate_provider_secret_ref("sk-abc123def456").is_err());
+        assert!(validate_provider_secret_ref("my-api-key").is_err());
+    }
+
+    #[test]
+    fn validate_mcp_config_valid() {
+        let config = McpServerConfig {
+            name: "test".into(),
+            enabled: true,
+            url: "http://localhost:9999".into(),
+            transport: "sse".into(),
+            command: String::new(),
+            network_policy: "allow-local".into(),
+            secret_refs: vec![],
+            facade_only: true,
+            sandbox: true,
+            description: String::new(),
+            risk_level: String::new(),
+            required_scopes: vec![],
+        };
+        assert!(validate_mcp_server_config(&config).is_ok());
+    }
+
+    #[test]
+    fn validate_mcp_config_no_facade_fails() {
+        let config = McpServerConfig {
+            name: "test".into(),
+            enabled: true,
+            url: "http://localhost:9999".into(),
+            transport: "sse".into(),
+            command: String::new(),
+            network_policy: "allow-local".into(),
+            secret_refs: vec![],
+            facade_only: false,
+            sandbox: true,
+            description: String::new(),
+            risk_level: String::new(),
+            required_scopes: vec![],
+        };
+        assert!(validate_mcp_server_config(&config).is_err());
+    }
+
+    #[test]
+    fn validate_mcp_config_no_sandbox_fails() {
+        let config = McpServerConfig {
+            name: "test".into(),
+            enabled: true,
+            url: "http://localhost:9999".into(),
+            transport: "sse".into(),
+            command: String::new(),
+            network_policy: "allow-local".into(),
+            secret_refs: vec![],
+            facade_only: true,
+            sandbox: false,
+            description: String::new(),
+            risk_level: String::new(),
+            required_scopes: vec![],
+        };
+        assert!(validate_mcp_server_config(&config).is_err());
+    }
+
+    // ─── Admin merge helpers ──────────────────────────────────────────────
+
+    #[test]
+    fn merge_policy_with_existing_creates_from_empty() {
+        let body = UpsertAiPolicyBody {
+            default_model: Some("omniroute/freefirst".into()),
+            allowed_models: Some(vec!["omniroute/freefirst".into(), "omniroute/fast".into()]),
+            workspace_id: None,
+            providers: None,
+            build_plan_task: None,
+            tools: None,
+            skills: None,
+            mcp_servers: None,
+            quota: None,
+        };
+        let (model_json, quota_json) = merge_policy_with_existing(None, &body);
+        let parsed: Value = serde_json::from_str(&model_json).unwrap();
+        assert_eq!(parsed["defaultModel"], "omniroute/freefirst");
+        assert_eq!(parsed["allowedModels"][0], "omniroute/freefirst");
+        assert_eq!(quota_json, "{}");
+    }
+
+    #[test]
+    fn merge_policy_with_existing_preserves_other_fields() {
+        let existing_value = json!({
+            "defaultModel": "old/model",
+            "allowedModels": ["old/model"],
+            "providers": {
+                "keep": {"name": "Keep", "enabled": true, "secretRef": "env://KEEP", "defaultModel": "old/model"}
+            }
+        });
+        let existing_rec = control_plane::AiPolicyRecord {
+            id: "dummy".into(),
+            user_id: Some("u1".into()),
+            workspace_id: None,
+            allowed_roots_json: "[]".into(),
+            model_policy_json: serde_json::to_string(&existing_value).unwrap(),
+            quota_json: r#"{"tokens":1000}"#.into(),
+            created_at: "2026-01-01T00:00:00Z".into(),
+            updated_at: "2026-01-01T00:00:00Z".into(),
+            revision: 1,
+        };
+        let body = UpsertAiPolicyBody {
+            default_model: Some("new/model".into()),
+            allowed_models: Some(vec!["new/model".into()]),
+            workspace_id: None,
+            providers: None, // don't touch existing providers
+            build_plan_task: None,
+            tools: None,
+            skills: None,
+            mcp_servers: None,
+            quota: Some(json!({"tokens": 2000})),
+        };
+        let (model_json, quota_json) = merge_policy_with_existing(Some(&existing_rec), &body);
+        let parsed: Value = serde_json::from_str(&model_json).unwrap();
+        assert_eq!(parsed["defaultModel"], "new/model");
+        // Existing providers preserved
+        assert_eq!(parsed["providers"]["keep"]["name"], "Keep");
+        let quota_parsed: Value = serde_json::from_str("a_json).unwrap();
+        assert_eq!(quota_parsed["tokens"], 2000);
+    }
+
+    #[test]
+    fn merge_policy_tools_override() {
+        let body = UpsertAiPolicyBody {
+            default_model: None,
+            allowed_models: None,
+            workspace_id: None,
+            providers: None,
+            build_plan_task: None,
+            tools: Some([("mnote.local_file.read".into(), "deny".into())].into()),
+            skills: None,
+            mcp_servers: None,
+            quota: None,
+        };
+        let (model_json, _) = merge_policy_with_existing(None, &body);
+        let parsed: Value = serde_json::from_str(&model_json).unwrap();
+        assert_eq!(parsed["tools"]["mnote.local_file.read"], "deny");
+    }
+
+    #[test]
+    fn merge_policy_skills_and_mcp() {
+        let body = UpsertAiPolicyBody {
+            default_model: None,
+            allowed_models: None,
+            workspace_id: None,
+            providers: None,
+            build_plan_task: None,
+            tools: None,
+            skills: Some(
+                [(
+                    "img-skill".into(),
+                    SkillConfig {
+                        name: "Image Gen".into(),
+                        enabled: true,
+                        description: "Generate images".into(),
+                        source: "test".into(),
+                        risk_level: "low".into(),
+                        required_scopes: vec![],
+                    },
+                )]
+                .into(),
+            ),
+            mcp_servers: Some(
+                [(
+                    "fs-mcp".into(),
+                    McpServerConfig {
+                        name: "File System".into(),
+                        enabled: true,
+                        url: "http://mcp:9090".into(),
+                        transport: "sse".into(),
+                        command: String::new(),
+                        network_policy: "allow-local".into(),
+                        secret_refs: vec![],
+                        facade_only: true,
+                        sandbox: true,
+                        description: "Test MCP".into(),
+                        risk_level: "medium".into(),
+                        required_scopes: vec![],
+                    },
+                )]
+                .into(),
+            ),
+            quota: None,
+        };
+        let (model_json, _) = merge_policy_with_existing(None, &body);
+        let parsed: Value = serde_json::from_str(&model_json).unwrap();
+        assert_eq!(parsed["skills"]["img-skill"]["name"], "Image Gen");
+        assert_eq!(parsed["skills"]["img-skill"]["enabled"], true);
+        assert_eq!(parsed["mcpServers"]["fs-mcp"]["url"], "http://mcp:9090");
+        assert_eq!(parsed["mcpServers"]["fs-mcp"]["facadeOnly"], true);
+        assert_eq!(parsed["mcpServers"]["fs-mcp"]["sandbox"], true);
+    }
+
+    // ─── Admin projection ────────────────────────────────────────────────
+
+    #[test]
+    fn project_admin_settings_empty_policy_yields_defaults() {
+        let response = project_admin_settings(&json!({}), &json!({}), None);
+        assert_eq!(response.default_model, DEFAULT_PI_MODEL);
+        assert!(response.providers.contains_key("omniroute"));
+        assert!(response.tools.is_empty());
+        assert!(response.skills.contains_key("vpn"));
+        assert!(response.skills.contains_key("chrome-bridge"));
+        assert!(response.skills.contains_key("context7"));
+        assert!(response.skills.contains_key("searxng"));
+        assert!(response.skills.contains_key("global-search"));
+        assert!(response.skills.contains_key("mempalace"));
+        assert!(response.skills.contains_key("codegraph"));
+        assert!(response.mcp_servers.contains_key("chrome-bridge"));
+        assert!(response.mcp_servers.contains_key("context7"));
+        assert!(response.mcp_servers.contains_key("searxng"));
+        assert!(response.mcp_servers.contains_key("mempalace"));
+        assert!(response.mcp_servers.contains_key("codegraph"));
+    }
+
+    #[test]
+    fn project_admin_settings_with_full_policy() {
+        let policy = json!({
+            "defaultModel": "omniroute/premium",
+            "allowedModels": ["omniroute/premium", "omniroute/fast"],
+            "providers": {
+                "omniroute": {
+                    "name": "Omniroute",
+                    "enabled": true,
+                    "secretRef": "env://OMNIROUTE_KEY",
+                    "defaultModel": "omniroute/premium"
+                }
+            },
+            "buildPlanTask": {
+                "default": "omniroute/premium",
+                "failover": ["omniroute/fast"]
+            },
+            "tools": {
+                "mnote.local_file.patch": "deny"
+            },
+            "skills": {
+                "img-skill": {
+                    "name": "Image Gen",
+                    "enabled": true
+                }
+            },
+            "mcpServers": {
+                "fs-mcp": {
+                    "name": "File System",
+                    "enabled": true,
+                    "url": "http://mcp:9090",
+                    "facadeOnly": true,
+                    "sandbox": true
+                }
+            }
+        });
+        let quota = json!({"tokens": 5000});
+        let response = project_admin_settings(&policy, "a, None);
+        assert_eq!(response.default_model, "omniroute/premium");
+        assert_eq!(response.allowed_models.len(), 2);
+        assert!(response.providers.contains_key("omniroute"));
+        assert_eq!(
+            response.tools.get("mnote.local_file.patch").unwrap(),
+            "deny"
+        );
+        assert!(response.skills.contains_key("img-skill"));
+        assert!(response.mcp_servers.contains_key("fs-mcp"));
+        assert_eq!(response.quota["tokens"], 5000);
+    }
+
+    #[test]
+    fn describe_updated_fields_empty() {
+        let body = UpsertAiPolicyBody {
+            default_model: None,
+            allowed_models: None,
+            workspace_id: None,
+            providers: None,
+            build_plan_task: None,
+            tools: None,
+            skills: None,
+            mcp_servers: None,
+            quota: None,
+        };
+        let fields = describe_updated_fields(&body);
+        assert!(fields.is_empty());
+    }
+
+    #[test]
+    fn describe_updated_fields_all() {
+        let body = UpsertAiPolicyBody {
+            default_model: Some("m".into()),
+            allowed_models: Some(vec![]),
+            workspace_id: None,
+            providers: Some(HashMap::new()),
+            build_plan_task: Some(BuildPlanTaskConfig {
+                default: Some("m".into()),
+                failover: vec![],
+            }),
+            tools: Some(HashMap::new()),
+            skills: Some(HashMap::new()),
+            mcp_servers: Some(HashMap::new()),
+            quota: Some(json!({})),
+        };
+        let fields = describe_updated_fields(&body);
+        assert_eq!(fields.len(), 8);
+    }
+
+    #[test]
+    fn user_policy_merges_models_and_disables_skill_and_mcp() {
+        let global = json!({
+            "defaultModel": "omniroute/freefirst",
+            "allowedModels": ["omniroute/freefirst", "omniroute/fast"],
+            "skills": {
+                "search": {"name": "Search", "enabled": true}
+            },
+            "mcpServers": {
+                "docs": {"name": "Docs", "enabled": true, "facadeOnly": true, "sandbox": true}
+            }
+        });
+        let user = json!({
+            "defaultModel": "omniroute/fast",
+            "allowedModels": ["omniroute/fast"],
+            "skillOverrides": {"search": false},
+            "mcpOverrides": {"docs": false}
+        });
+        let merged = merge_effective_user_policy(&global, &user);
+        assert_eq!(merged["defaultModel"], "omniroute/fast");
+        assert_eq!(merged["allowedModels"], json!(["omniroute/fast"]));
+        assert_eq!(merged["skills"]["search"]["enabled"], false);
+        assert_eq!(merged["mcpServers"]["docs"]["enabled"], false);
+    }
+
+    #[test]
+    fn user_policy_rejects_privilege_escalation() {
+        let global = json!({
+            "allowedModels": ["omniroute/freefirst"],
+            "tools": {"mnote.local_file.patch": "ask"},
+            "skills": {"search": {"name": "Search", "enabled": false}},
+            "mcpServers": {"docs": {"name": "Docs", "enabled": false, "facadeOnly": true, "sandbox": true}}
+        });
+        let body = UserAiPolicyBody {
+            default_model: Some("omniroute/premium".into()),
+            allowed_models: Some(vec!["omniroute/premium".into()]),
+            tools: Some([("mnote.local_file.patch".into(), "allow".into())].into()),
+            skills: Some([("search".into(), true)].into()),
+            mcp_servers: Some([("docs".into(), true)].into()),
+        };
+        assert!(validate_user_policy_body(&body, &global).is_err());
+    }
+
+    #[test]
+    fn user_tool_policy_can_only_reduce_global_permission() {
+        let global = json!({
+            "allowedModels": ["omniroute/freefirst"],
+            "tools": {"mnote.local_file.patch": "ask"}
+        });
+        let body = UserAiPolicyBody {
+            default_model: Some("omniroute/freefirst".into()),
+            allowed_models: Some(vec!["omniroute/freefirst".into()]),
+            tools: Some([("mnote.local_file.patch".into(), "deny".into())].into()),
+            skills: None,
+            mcp_servers: None,
+        };
+        assert!(validate_user_policy_body(&body, &global).is_ok());
+    }
+}
diff --git a/rust/crates/mnote-web/src/routes/bridge.rs b/rust/crates/mnote-web/src/routes/bridge.rs
index ad29e7e0..db957e9a 100644
--- a/rust/crates/mnote-web/src/routes/bridge.rs
+++ b/rust/crates/mnote-web/src/routes/bridge.rs
@@ -167,6 +167,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/compat.rs b/rust/crates/mnote-web/src/routes/compat.rs
index b41be534..13a64d26 100644
--- a/rust/crates/mnote-web/src/routes/compat.rs
+++ b/rust/crates/mnote-web/src/routes/compat.rs
@@ -73,6 +73,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -112,6 +113,7 @@ mod tests {
             enable_legacy_next_compat: false,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -168,6 +170,7 @@ mod tests {
             enable_legacy_next_compat: false,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -236,6 +239,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/dev_seed.rs b/rust/crates/mnote-web/src/routes/dev_seed.rs
index 2d746009..f8bd8b86 100644
--- a/rust/crates/mnote-web/src/routes/dev_seed.rs
+++ b/rust/crates/mnote-web/src/routes/dev_seed.rs
@@ -164,10 +164,7 @@ pub async fn seed(
     Ok(Json(DevSeedResponse { ok: true, results }))
 }
 
-fn apply_seed_operation(
-    state: &AppState,
-    operation: DevSeedOperation,
-) -> Result {
+fn apply_seed_operation(state: &AppState, operation: DevSeedOperation) -> Result {
     match operation {
         DevSeedOperation::SetupWorkspace {
             user_id,
@@ -478,6 +475,7 @@ mod tests {
                 enable_legacy_next_compat: false,
                 enable_debug_shell_routes: false,
                 enable_editor_actor: false,
+                enable_page_ai_pi_lab: false,
                 hermes_base_path: "/api/hermes".into(),
                 compat_next_base_path: "/api/compat/next".into(),
                 convex_url: None,
@@ -573,10 +571,7 @@ mod tests {
         assert_eq!(payload["results"][0]["run"]["profile"], "test-profile");
         assert_eq!(payload["results"][0]["run"]["acp_runtime"], "reasonix");
         assert_eq!(payload["results"][0]["run"]["status"], "running");
-        assert_eq!(
-            payload["results"][0]["events"].as_array().unwrap().len(),
-            1
-        );
+        assert_eq!(payload["results"][0]["events"].as_array().unwrap().len(), 1);
 
         // Step 3: getAiRuntimeRun → 回读验证
         let (status, payload) = send_seed(
diff --git a/rust/crates/mnote-web/src/routes/documents.rs b/rust/crates/mnote-web/src/routes/documents.rs
index ac697cdf..5b798189 100644
--- a/rust/crates/mnote-web/src/routes/documents.rs
+++ b/rust/crates/mnote-web/src/routes/documents.rs
@@ -1196,6 +1196,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/editor.rs b/rust/crates/mnote-web/src/routes/editor.rs
index d89d0c73..af52d2e8 100644
--- a/rust/crates/mnote-web/src/routes/editor.rs
+++ b/rust/crates/mnote-web/src/routes/editor.rs
@@ -1779,6 +1779,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: true,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/evidence.rs b/rust/crates/mnote-web/src/routes/evidence.rs
index 69ae2eab..e2f49758 100644
--- a/rust/crates/mnote-web/src/routes/evidence.rs
+++ b/rust/crates/mnote-web/src/routes/evidence.rs
@@ -388,6 +388,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/gateway.rs b/rust/crates/mnote-web/src/routes/gateway.rs
index b9fc9633..61e2a9ab 100644
--- a/rust/crates/mnote-web/src/routes/gateway.rs
+++ b/rust/crates/mnote-web/src/routes/gateway.rs
@@ -261,6 +261,88 @@ pub async fn user_access_policy_entry(
     Ok(response)
 }
 
+pub async fn admin_ai_entry(
+    State(state): State,
+    Extension(context): Extension,
+) -> Result {
+    if !has_real_auth_context(&state, &context) {
+        let mut response = Response::builder()
+            .status(StatusCode::SEE_OTHER)
+            .header(header::LOCATION, "/auth")
+            .body(Body::empty())
+            .map_err(|error| WebError::internal(format!("认证入口跳转响应构造失败: {error}")))?;
+        stamp_gateway_headers(response.headers_mut(), false);
+        return Ok(response);
+    }
+    if !is_local_access_policy_admin_context(&context) {
+        return Err(WebError::new(
+            StatusCode::FORBIDDEN,
+            "ai_admin_required",
+            "只有管理员可以访问 AI 管理中心",
+        )
+        .with_context(&context));
+    }
+    ai_management_response(&state, &context, true)
+}
+
+pub async fn user_ai_entry(
+    State(state): State,
+    Extension(context): Extension,
+) -> Result {
+    if !has_real_auth_context(&state, &context) {
+        let mut response = Response::builder()
+            .status(StatusCode::SEE_OTHER)
+            .header(header::LOCATION, "/auth")
+            .body(Body::empty())
+            .map_err(|error| WebError::internal(format!("认证入口跳转响应构造失败: {error}")))?;
+        stamp_gateway_headers(response.headers_mut(), false);
+        return Ok(response);
+    }
+    ai_management_response(&state, &context, false)
+}
+
+fn ai_management_response(
+    state: &AppState,
+    context: &RequestContext,
+    is_admin: bool,
+) -> Result {
+    let workspace_name = default_workspace_name_for_context(state, context);
+    let content = crate::ssr::render_view(leptos::view! {
+        
+    });
+    let title = if is_admin { "AI 管理" } else { "AI 设置" };
+    let shell = if is_admin {
+        "admin-ai"
+    } else {
+        "user-ai-admin"
+    };
+    let mut response = Html(format!(
+        r#"
+
+  
+    
+    
+    {}
+    
+  
+  
+    {}
+  
+"#,
+        title,
+        crate::ssr::MNOTE_CSS,
+        shell,
+        escape_html(context.auth.actor_id.as_str()),
+        content
+    ))
+    .into_response();
+    stamp_gateway_headers(response.headers_mut(), false);
+    Ok(response)
+}
+
 pub async fn root_entry(
     State(state): State,
     Extension(context): Extension,
@@ -579,6 +661,21 @@ pub async fn root_entry(
             escape_script_json(&panes_bootstrap_json),
             render_editor_island_adapter_script(),
         );
+        let body_extra = if state.config().enable_page_ai_pi_lab {
+            body_extra
+                + &format!(
+                    r#""#
+                )
+        } else {
+            body_extra
+        };
         ("MNOTE".to_string(), render_workspace_entry(), body_extra)
     } else {
         match build_page_aggregate_snapshot(
@@ -639,6 +736,21 @@ pub async fn root_entry(
                     render_document_title_controller_script(),
                     render_editor_island_adapter_script(),
                 );
+                let body_extra = if state.config().enable_page_ai_pi_lab {
+                    body_extra
+                        + &format!(
+                            r#""#
+                        )
+                } else {
+                    body_extra
+                };
                 (title.to_string(), content, body_extra)
             }
             Err(_) => ("MNOTE".to_string(), render_workspace_entry(), String::new()),
@@ -2554,6 +2666,7 @@ mod tests {
             enable_legacy_next_compat,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url,
@@ -3074,6 +3187,7 @@ mod tests {
             enable_legacy_next_compat: false,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -3366,6 +3480,7 @@ mod tests {
             enable_legacy_next_compat: false,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/hermes.rs b/rust/crates/mnote-web/src/routes/hermes.rs
index 1179b47e..89075fae 100644
--- a/rust/crates/mnote-web/src/routes/hermes.rs
+++ b/rust/crates/mnote-web/src/routes/hermes.rs
@@ -166,6 +166,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/hermes_client.rs b/rust/crates/mnote-web/src/routes/hermes_client.rs
index a90e17ca..d0468d42 100644
--- a/rust/crates/mnote-web/src/routes/hermes_client.rs
+++ b/rust/crates/mnote-web/src/routes/hermes_client.rs
@@ -1450,7 +1450,9 @@ pub async fn toggle_skill(
         return Ok((
             StatusCode::OK,
             stamp_client_headers(),
-            Json(json!({"ok": true, "skillKind": "mnote_builtin", "configScope": "user_control_plane"})),
+            Json(
+                json!({"ok": true, "skillKind": "mnote_builtin", "configScope": "user_control_plane"}),
+            ),
         ));
     }
     let access =
@@ -14553,6 +14555,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -15520,6 +15523,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -15562,6 +15566,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -15991,7 +15996,10 @@ mod tests {
             .await
             .expect("detail body");
         let detail_payload: Value = serde_json::from_slice(&detail_body).expect("detail json");
-        assert_eq!(detail_payload["persistence"], ACP_RUNTIME_CONTROL_PLANE_STORE);
+        assert_eq!(
+            detail_payload["persistence"],
+            ACP_RUNTIME_CONTROL_PLANE_STORE
+        );
         assert_eq!(
             detail_payload["session"]["runs"][0]["sessionId"],
             session_id
@@ -16399,6 +16407,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: Some(convex_url),
@@ -16558,6 +16567,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: Some(convex_url),
@@ -16646,6 +16656,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: Some(convex_url),
@@ -16722,6 +16733,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: Some(convex_url),
@@ -16905,6 +16917,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: Some(convex_url),
diff --git a/rust/crates/mnote-web/src/routes/hermes_tools.rs b/rust/crates/mnote-web/src/routes/hermes_tools.rs
index 89d8bd7f..d8227950 100644
--- a/rust/crates/mnote-web/src/routes/hermes_tools.rs
+++ b/rust/crates/mnote-web/src/routes/hermes_tools.rs
@@ -1113,6 +1113,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -1180,6 +1181,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/kernel.rs b/rust/crates/mnote-web/src/routes/kernel.rs
index cf326f9d..bc58d6eb 100644
--- a/rust/crates/mnote-web/src/routes/kernel.rs
+++ b/rust/crates/mnote-web/src/routes/kernel.rs
@@ -282,6 +282,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/local_folder_events.rs b/rust/crates/mnote-web/src/routes/local_folder_events.rs
index bc30559e..1d2539d1 100644
--- a/rust/crates/mnote-web/src/routes/local_folder_events.rs
+++ b/rust/crates/mnote-web/src/routes/local_folder_events.rs
@@ -504,6 +504,7 @@ mod tests {
             enable_legacy_next_compat: false,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/local_folder_source.rs b/rust/crates/mnote-web/src/routes/local_folder_source.rs
index 6f9b8e66..300a3b1b 100644
--- a/rust/crates/mnote-web/src/routes/local_folder_source.rs
+++ b/rust/crates/mnote-web/src/routes/local_folder_source.rs
@@ -9630,6 +9630,7 @@ mod tests {
             enable_legacy_next_compat: false,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/local_search_index.rs b/rust/crates/mnote-web/src/routes/local_search_index.rs
index 29319250..f2f1ab88 100644
--- a/rust/crates/mnote-web/src/routes/local_search_index.rs
+++ b/rust/crates/mnote-web/src/routes/local_search_index.rs
@@ -2147,10 +2147,7 @@ fn clear_local_search_index(root_path: &Path) -> Result<(), WebError> {
         Err(error) => {
             return Err(WebError::bad_request_code(
                 "local_search_index_delete_failed",
-                format!(
-                    "无法删除本地搜索索引文件 {}: {error}",
-                    index_path.display()
-                ),
+                format!("无法删除本地搜索索引文件 {}: {error}", index_path.display()),
             ));
         }
     }
diff --git a/rust/crates/mnote-web/src/routes/mindmap_api.rs b/rust/crates/mnote-web/src/routes/mindmap_api.rs
index 126dbc0c..bdce7697 100644
--- a/rust/crates/mnote-web/src/routes/mindmap_api.rs
+++ b/rust/crates/mnote-web/src/routes/mindmap_api.rs
@@ -486,6 +486,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/mindmap_shell.rs b/rust/crates/mnote-web/src/routes/mindmap_shell.rs
index 30ca8c43..b4438d4c 100644
--- a/rust/crates/mnote-web/src/routes/mindmap_shell.rs
+++ b/rust/crates/mnote-web/src/routes/mindmap_shell.rs
@@ -352,6 +352,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -420,6 +421,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/mod.rs b/rust/crates/mnote-web/src/routes/mod.rs
index 09951556..5f24c629 100644
--- a/rust/crates/mnote-web/src/routes/mod.rs
+++ b/rust/crates/mnote-web/src/routes/mod.rs
@@ -1,8 +1,9 @@
+mod ai_settings;
 mod bridge;
 pub(crate) mod command_support;
 mod compat;
-mod dev_seed;
 pub(crate) mod dev_hot;
+mod dev_seed;
 mod documents;
 mod editor;
 pub(crate) mod evidence;
@@ -28,6 +29,7 @@ pub(crate) mod onlyoffice_bridge;
 mod page_ai_board;
 mod page_ai_opencode;
 mod page_ai_openhub;
+mod page_ai_pi;
 mod page_ai_workflow;
 mod query_support;
 mod resource_trash;
@@ -49,8 +51,7 @@ pub(crate) use local_folder_source::{
     control_plane_status_display, decode_local_id_segment, ensure_local_path_read_access,
     ensure_local_workspace_access, ensure_local_workspace_read_access_with_state,
     ensure_local_workspace_write_access_with_state, local_markdown_conflict_detection_key,
-    local_workspace_id_from_root_uri, update_local_markdown_title,
-    write_local_markdown_page_body,
+    local_workspace_id_from_root_uri, update_local_markdown_title, write_local_markdown_page_body,
 };
 #[cfg(test)]
 pub(crate) use local_search_index::write_local_index_settings;
@@ -84,6 +85,8 @@ pub fn build_router(state: AppState) -> Router {
             "/user/access-policy",
             get(gateway::user_access_policy_entry),
         )
+        .route("/admin/ai", get(gateway::admin_ai_entry))
+        .route("/user/ai", get(gateway::user_ai_entry))
         .route("/auth", get(gateway::auth_entry).post(gateway::auth_entry))
         .route("/search", get(search::shell))
         .route("/knowledge", get(gateway::root_entry))
@@ -275,6 +278,10 @@ pub fn build_router(state: AppState) -> Router {
             "/api/mnote-browser-runtime/sidebar-page-ai-target-runtime.js",
             get(web_shell::sidebar_page_ai_target_runtime_asset),
         )
+        .route(
+            "/api/mnote-browser-runtime/sidebar-page-ai-pi-lab-runtime.js",
+            get(web_shell::sidebar_page_ai_pi_lab_runtime_asset),
+        )
         .route(
             "/api/mnote-browser-runtime/sidebar-page-settings-runtime.js",
             get(web_shell::sidebar_page_settings_runtime_asset),
@@ -588,6 +595,27 @@ pub fn build_router(state: AppState) -> Router {
             "/api/page-ai/board/runs/{run_id}/cancel",
             post(page_ai_board::cancel_run),
         )
+        .route("/api/page-ai/pi/status", get(page_ai_pi::status))
+        .route("/api/page-ai/pi/bootstrap", post(page_ai_pi::bootstrap))
+        .route("/api/page-ai/pi/start", post(page_ai_pi::start))
+        .route("/api/page-ai/pi/send", post(page_ai_pi::send))
+        .route("/api/page-ai/pi/abort", post(page_ai_pi::abort))
+        .route("/api/page-ai/pi/events", get(page_ai_pi::events))
+        .route("/api/page-ai/pi/sessions", get(page_ai_pi::list_sessions))
+        .route(
+            "/api/page-ai/pi/sessions/{session_id}",
+            get(page_ai_pi::get_session_history),
+        )
+        .route(
+            "/api/page-ai/pi/sessions/{session_id}/events",
+            get(page_ai_pi::get_session_events),
+        )
+        .route("/api/page-ai/pi/tool-call", post(page_ai_pi::tool_call))
+        .route(
+            "/api/page-ai/pi/tool-call-bridge",
+            post(page_ai_pi::tool_call_bridge),
+        )
+        .route("/page-ai/pi", get(page_ai_pi::shell))
         .route(
             "/api/sidebar/shortcuts",
             get(sidebar_shortcuts::list_shortcuts).post(sidebar_shortcuts::upsert_shortcut),
@@ -628,6 +656,29 @@ pub fn build_router(state: AppState) -> Router {
             "/api/user/access-policy/grants/{grant_id}",
             delete(local_folder_source::delete_user_access_grant),
         )
+        .route(
+            "/api/ai-settings/effective",
+            get(ai_settings::effective_settings),
+        )
+        .route(
+            "/api/ai-settings/access-scopes",
+            get(ai_settings::user_access_scopes),
+        )
+        .route(
+            "/api/ai-admin/access-scopes",
+            get(ai_settings::admin_access_scopes),
+        )
+        .route("/api/ai-settings/receipts", get(ai_settings::user_receipts))
+        .route("/api/ai-admin/receipts", get(ai_settings::admin_receipts))
+        .route(
+            "/api/ai-admin/settings",
+            get(ai_settings::admin_get_settings).put(ai_settings::admin_put_settings),
+        )
+        .route("/api/ai-admin/users", get(ai_settings::admin_list_users))
+        .route(
+            "/api/ai-admin/users/{user_id}/settings",
+            get(ai_settings::admin_get_user_settings).put(ai_settings::admin_put_user_settings),
+        )
         .route(
             "/api/admin/share-links",
             get(local_folder_source::get_share_links).post(local_folder_source::create_share_link),
@@ -1035,6 +1086,7 @@ mod tests {
             enable_legacy_next_compat: false,
             enable_debug_shell_routes,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/navigation_recent.rs b/rust/crates/mnote-web/src/routes/navigation_recent.rs
index 9a1b0a35..f28cafbf 100644
--- a/rust/crates/mnote-web/src/routes/navigation_recent.rs
+++ b/rust/crates/mnote-web/src/routes/navigation_recent.rs
@@ -369,6 +369,7 @@ mod tests {
             enable_legacy_next_compat: false,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/onlyoffice.rs b/rust/crates/mnote-web/src/routes/onlyoffice.rs
index 28e52146..fccb663c 100644
--- a/rust/crates/mnote-web/src/routes/onlyoffice.rs
+++ b/rust/crates/mnote-web/src/routes/onlyoffice.rs
@@ -1998,6 +1998,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/page_ai_pi.rs b/rust/crates/mnote-web/src/routes/page_ai_pi.rs
new file mode 100644
index 00000000..cec99264
--- /dev/null
+++ b/rust/crates/mnote-web/src/routes/page_ai_pi.rs
@@ -0,0 +1,2869 @@
+//! Pi-first Page AI Lab — MNote 托管的后端垂直切片。
+//!
+//! 该模块默认启用独立 Pi Lab 后端；OpenHub / LightRAG / Turso 默认主线不受影响。
+//! Pi 进程通过 RPC subprocess 托管，文件读写只经 MNote-owned tool facade。
+
+use crate::app::AppState;
+use crate::context::RequestContext;
+use crate::error::WebError;
+use crate::routes::{knowledge_rag, local_folder_source};
+use axum::extract::{Extension, Query, State};
+use axum::http::{HeaderMap, StatusCode};
+use axum::response::sse::{Event as SseEvent, KeepAlive, Sse};
+use axum::response::{Html, IntoResponse, Response};
+use axum::Json;
+use control_plane::{
+    AppendAiFilePatchInput, AppendAiRuntimeEventInput, AppendAiToolEventInput, ControlPlaneStore,
+    UpsertAiRuntimeRunInput,
+};
+use futures_util::stream::{self, StreamExt};
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+use std::collections::HashMap;
+use std::convert::Infallible;
+use std::fs::{self, OpenOptions};
+use std::io::{Read as _, Write as _};
+use std::path::{Path, PathBuf};
+use std::process::Stdio;
+use std::sync::{Arc, LazyLock, Mutex as StdMutex};
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
+use tokio::process::{Child, ChildStdin, Command};
+use tokio::sync::{broadcast, Mutex as AsyncMutex};
+use tokio_stream::wrappers::BroadcastStream;
+
+const PI_LAB_VERSION: &str = "0.1.0-pi-lab-spike";
+const PI_LAB_PROVIDER: &str = "pi";
+const PI_LAB_SCHEMA_STATUS: &str = "mnote.page_ai_pi.status.v1";
+const PI_LAB_SCHEMA_RECEIPT: &str = "mnote.page_ai_pi.tool_receipt.v1";
+const PI_LAB_SCHEMA_EVENT: &str = "mnote.page_ai_pi.event.v1";
+const PI_LAB_DEFAULT_MODEL_PROVIDER: &str = "omniroute";
+const PI_LAB_DEFAULT_MODEL_ID: &str = "freefirst";
+const PI_LAB_DEFAULT_OMNIROUTE_BASE_URL: &str = "http://127.0.0.1:20128/v1";
+const HEADER_PI_LAB_BRIDGE_TOKEN: &str = "x-mnote-pi-lab-bridge-token";
+const PI_LAB_SESSION_TTL_MS: u128 = 30 * 60 * 1000;
+const PI_LAB_MAX_SESSIONS: usize = 16;
+const PI_LAB_RATE_WINDOW_MS: u128 = 10_000;
+const PI_LAB_MAX_STARTS_PER_WINDOW: usize = 4;
+const PI_LAB_MAX_SENDS_PER_WINDOW: usize = 12;
+const PI_LAB_MAX_TOOLS_PER_WINDOW: usize = 40;
+pub const PI_LAB_PROFILE: &str = "pi_lab";
+pub const PI_LAB_ACP_RUNTIME: &str = "pi";
+
+static PI_LAB_SESSIONS: LazyLock>> =
+    LazyLock::new(|| StdMutex::new(HashMap::new()));
+static PI_LAB_PROCESSES: LazyLock>> =
+    LazyLock::new(|| StdMutex::new(HashMap::new()));
+static PI_LAB_RECEIPT_STORE: LazyLock>> =
+    LazyLock::new(|| StdMutex::new(Vec::new()));
+static PI_LAB_RATE_LIMITS: LazyLock>>> =
+    LazyLock::new(|| StdMutex::new(HashMap::new()));
+static PI_LAB_EVENT_TX: LazyLock> = LazyLock::new(|| {
+    let (tx, _) = broadcast::channel(1024);
+    tx
+});
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum PiLabSessionStatus {
+    Idle,
+    RuntimeRunning,
+    TurnRunning,
+    Aborted,
+    Error,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PiLabSession {
+    pub session_id: String,
+    pub mnote_user_id: String,
+    #[serde(skip_serializing, skip_deserializing)]
+    pub bridge_token: String,
+    pub status: PiLabSessionStatus,
+    pub provider_session_id: String,
+    pub pi_session_dir: String,
+    pub pi_session_file: Option,
+    pub root_uri: Option,
+    pub workspace_id: Option,
+    pub page_path: Option,
+    pub page_title: Option,
+    pub model_provider: Option,
+    pub model_id: Option,
+    pub allowed_roots_snapshot: Option,
+    pub runtime_pid: Option,
+    pub runtime_mode: String,
+    pub runtime_error: Option,
+    pub created_at_ms: u128,
+    pub updated_at_ms: u128,
+    pub message_count: u64,
+}
+
+#[derive(Clone)]
+struct PiLabProcessHandle {
+    stdin: Arc>,
+    child: Arc>,
+    _pid: Option,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PiLabToolReceipt {
+    pub schema: &'static str,
+    pub receipt_id: String,
+    pub mnote_user_id: String,
+    pub workspace_id: Option,
+    pub root_uri: Option,
+    pub page_path: Option,
+    pub session_id: String,
+    pub tool_name: String,
+    pub normalized_file_path: Option,
+    pub allowed: bool,
+    pub deny_reason: Option,
+    pub diff_summary: Option,
+    pub before_file_version: Option,
+    pub after_file_version: Option,
+    pub provider: &'static str,
+    pub provider_session_id: Option,
+    pub model_provider: Option,
+    pub model_id: Option,
+    pub allowed_roots_snapshot: Option,
+    pub storage: String,
+    pub created_at_ms: u128,
+}
+
+#[derive(Debug, Clone)]
+struct AllowedRoot {
+    root_uri: Option,
+    root_path: PathBuf,
+    workspace_id: Option,
+    permission: String,
+    source: String,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PiLabBootstrapRequest {
+    pub prompt: Option,
+    pub root_uri: Option,
+    pub workspace_id: Option,
+    pub page_path: Option,
+    pub page_title: Option,
+    pub model_provider: Option,
+    pub model_id: Option,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PiLabStartRequest {
+    pub session_id: Option,
+    pub root_uri: Option,
+    pub workspace_id: Option,
+    pub page_path: Option,
+    pub page_title: Option,
+    pub model_provider: Option,
+    pub model_id: Option,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PiLabSendRequest {
+    pub session_id: String,
+    pub message: String,
+    pub streaming_behavior: Option,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PiLabAbortRequest {
+    pub session_id: String,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PiLabEventsQuery {
+    pub session_id: Option,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PiLabToolCallRequest {
+    pub session_id: Option,
+    pub tool_name: String,
+    #[serde(default)]
+    pub params: Value,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PiLabListSessionsQuery {
+    pub workspace_id: Option,
+    pub limit: Option,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct PiLabSessionPathParam {
+    pub session_id: String,
+}
+
+fn now_ms() -> u128 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|duration| duration.as_millis())
+        .unwrap_or(0)
+}
+
+fn generate_id(prefix: &str) -> String {
+    format!("{prefix}_{:x}_{:x}", now_ms(), random_suffix())
+}
+
+fn generate_bridge_token() -> String {
+    let mut bytes = [0_u8; 24];
+    if let Ok(mut random) = fs::File::open("/dev/urandom") {
+        if random.read_exact(&mut bytes).is_ok() {
+            let mut encoded = String::with_capacity(bytes.len() * 2);
+            for byte in bytes {
+                encoded.push_str(&format!("{byte:02x}"));
+            }
+            return format!("pi_bridge_{encoded}");
+        }
+    }
+    generate_id("pi_bridge_fallback")
+}
+
+fn random_suffix() -> u64 {
+    use std::hash::{Hash, Hasher};
+    let mut hasher = std::collections::hash_map::DefaultHasher::new();
+    SystemTime::now().hash(&mut hasher);
+    std::thread::current().id().hash(&mut hasher);
+    hasher.finish()
+}
+
+fn enabled(state: &AppState) -> bool {
+    state.config().enable_page_ai_pi_lab
+}
+
+fn ensure_enabled(state: &AppState) -> Result<(), WebError> {
+    if enabled(state) {
+        return Ok(());
+    }
+    Err(WebError::new(
+        StatusCode::NOT_FOUND,
+        "page_ai_pi_lab_disabled",
+        "Pi Lab 已被 MNOTE_PAGE_AI_PI_LAB=0 强制关闭",
+    ))
+}
+
+fn hash_auth_identity(value: &str) -> String {
+    use std::hash::{Hash, Hasher};
+    let mut hasher = std::collections::hash_map::DefaultHasher::new();
+    value.hash(&mut hasher);
+    format!("auth:{:016x}", hasher.finish())
+}
+
+fn pi_actor_id(state: &AppState, context: &RequestContext) -> Option {
+    crate::routes::gateway::current_actor_id(state, context).or_else(|| {
+        context
+            .auth
+            .authorization
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(hash_auth_identity)
+    })
+}
+
+fn ensure_authenticated(state: &AppState, context: &RequestContext) -> Result {
+    if let Some(actor_id) = pi_actor_id(state, context) {
+        return Ok(actor_id);
+    }
+    if let Some(raw_token) = context
+        .auth
+        .cookie_header
+        .as_deref()
+        .and_then(|_| crate::routes::gateway::current_actor_id(state, context))
+    {
+        return Ok(raw_token);
+    }
+    if context.auth.cookie_header.is_some() {
+        return Err(WebError::new(
+            StatusCode::UNAUTHORIZED,
+            "page_ai_pi_lab_invalid_session_cookie",
+            "Pi Lab 需要有效 MNote session cookie，不能用任意 Cookie 头访问",
+        )
+        .with_context(context));
+    }
+    Err(WebError::new(
+        StatusCode::UNAUTHORIZED,
+        "page_ai_pi_lab_unauthorized",
+        "Pi Lab 需要 MNote 登录态后访问",
+    )
+    .with_context(context))
+}
+
+fn ensure_session_owner(
+    state: &AppState,
+    context: &RequestContext,
+    session: &PiLabSession,
+) -> Result<(), WebError> {
+    let actor_id = ensure_authenticated(state, context)?;
+    if session.mnote_user_id == actor_id {
+        return Ok(());
+    }
+    Err(WebError::new(
+        StatusCode::FORBIDDEN,
+        "page_ai_pi_lab_session_owner_mismatch",
+        "Pi Lab session 不属于当前登录主体",
+    )
+    .with_context(context))
+}
+
+fn file_path_from_root_uri(root_uri: &str) -> Option {
+    let value = root_uri.trim();
+    let path = value.strip_prefix("file://")?;
+    (!path.is_empty()).then(|| PathBuf::from(path))
+}
+
+fn active_allowed_roots(
+    state: &AppState,
+    context: &RequestContext,
+) -> Result, WebError> {
+    let actor_id = ensure_authenticated(state, context)?;
+    let mut roots: Vec = state
+        .control_plane()
+        .list_directory_grants_for_actor(actor_id.trim())
+        .unwrap_or_default()
+        .into_iter()
+        .filter(|grant| grant.status.trim() == "active")
+        .filter_map(|grant| {
+            let root_path = if let Some(path) = file_path_from_root_uri(&grant.root_uri) {
+                path
+            } else if !grant.root_path.trim().is_empty() {
+                PathBuf::from(grant.root_path.trim())
+            } else {
+                return None;
+            };
+            Some(AllowedRoot {
+                root_uri: (!grant.root_uri.trim().is_empty()).then(|| grant.root_uri.clone()),
+                root_path,
+                workspace_id: grant
+                    .workspace_id
+                    .as_ref()
+                    .map(|value| value.trim().to_string())
+                    .filter(|value| !value.is_empty()),
+                permission: grant.permission,
+                source: grant.source,
+            })
+        })
+        .collect();
+
+    if roots.is_empty() {
+        roots.extend(dev_allowed_roots_from_env());
+    }
+    if roots.is_empty() {
+        return Err(WebError::new(
+            StatusCode::FORBIDDEN,
+            "page_ai_pi_lab_allowed_roots_empty",
+            "当前用户没有可用于 Pi Lab 的 allowed roots；请先通过 Turso/libSQL control-plane 授权目录，或仅在 dev 下设置 MNOTE_PI_LAB_ALLOWED_ROOTS",
+        )
+        .with_context(context));
+    }
+    Ok(roots)
+}
+
+fn dev_allowed_roots_from_env() -> Vec {
+    let Some(raw) = std::env::var("MNOTE_PI_LAB_ALLOWED_ROOTS")
+        .ok()
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+    else {
+        return Vec::new();
+    };
+    if let Ok(values) = serde_json::from_str::>(&raw) {
+        return values
+            .into_iter()
+            .filter_map(|value| dev_allowed_root_from_string(&value))
+            .collect();
+    }
+    let delimiter = if raw.contains(';') { ';' } else { ':' };
+    raw.split(delimiter)
+        .filter_map(dev_allowed_root_from_string)
+        .collect()
+}
+
+fn dev_allowed_root_from_string(value: &str) -> Option {
+    let trimmed = value.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    let (root_uri, root_path) = if trimmed.starts_with("file://") {
+        (Some(trimmed.to_string()), file_path_from_root_uri(trimmed)?)
+    } else {
+        let root_path = PathBuf::from(trimmed);
+        let normalized = canonical_or_parent(&root_path);
+        (
+            Some(format!("file://{}", normalized.to_string_lossy())),
+            root_path,
+        )
+    };
+    Some(AllowedRoot {
+        root_uri,
+        root_path,
+        workspace_id: None,
+        permission: "write".into(),
+        source: "MNOTE_PI_LAB_ALLOWED_ROOTS".into(),
+    })
+}
+
+fn root_can_write(root: &AllowedRoot) -> bool {
+    let permission = root.permission.to_ascii_lowercase();
+    permission.contains("write") || permission == "owner"
+}
+
+fn canonical_or_parent(path: &Path) -> PathBuf {
+    if let Ok(canonical) = path.canonicalize() {
+        return canonical;
+    }
+    if let Some(parent) = path.parent() {
+        if let Ok(canonical_parent) = parent.canonicalize() {
+            return canonical_parent.join(path.file_name().unwrap_or_default());
+        }
+    }
+    path.to_path_buf()
+}
+
+fn path_is_inside(path: &Path, root: &Path) -> bool {
+    let canonical_path = canonical_or_parent(path);
+    let canonical_root = canonical_or_parent(root);
+    canonical_path.starts_with(canonical_root)
+}
+
+fn resolve_root_relative_path(
+    state: &AppState,
+    context: &RequestContext,
+    root_uri: &str,
+    relative_path: &str,
+    require_write: bool,
+) -> Result {
+    let allowed = active_allowed_roots(state, context)?;
+    let requested_root_path =
+        file_path_from_root_uri(root_uri).map(|path| canonical_or_parent(&path));
+    let matched = allowed.iter().find(|root| {
+        root.root_uri
+            .as_deref()
+            .is_some_and(|candidate| candidate == root_uri)
+    });
+    let root = matched.or_else(|| {
+        let requested_root_path = requested_root_path.as_ref()?;
+        allowed.iter().find(|root| {
+            root.source == "MNOTE_PI_LAB_ALLOWED_ROOTS"
+                && path_is_inside(requested_root_path, &root.root_path)
+        })
+    });
+    let Some(root) = root else {
+        return Err(WebError::new(
+            StatusCode::FORBIDDEN,
+            "page_ai_pi_lab_root_not_allowed",
+            "请求 rootUri 不在当前 allowed roots 内",
+        )
+        .with_context(context));
+    };
+    let base_root_path = if matched.is_some() {
+        canonical_or_parent(&root.root_path)
+    } else {
+        requested_root_path.unwrap_or_else(|| canonical_or_parent(&root.root_path))
+    };
+    if require_write && !root_can_write(root) {
+        return Err(WebError::new(
+            StatusCode::FORBIDDEN,
+            "page_ai_pi_lab_root_readonly",
+            "请求 rootUri 只有只读权限，不能执行 patch",
+        )
+        .with_context(context));
+    }
+    let target = canonical_or_parent(&base_root_path.join(relative_path));
+    if !path_is_inside(&target, &root.root_path) {
+        return Err(WebError::new(
+            StatusCode::FORBIDDEN,
+            "page_ai_pi_lab_path_escape",
+            "文件路径不能越过 allowed root",
+        )
+        .with_context(context));
+    }
+    if require_write {
+        if root.source != "MNOTE_PI_LAB_ALLOWED_ROOTS" {
+            local_folder_source::ensure_local_workspace_write_access_with_state(
+                state, context, root_uri,
+            )
+            .map_err(|error| error.with_context(context))?;
+        }
+        Ok(target)
+    } else if root.source == "MNOTE_PI_LAB_ALLOWED_ROOTS" {
+        Ok(target)
+    } else {
+        local_folder_source::ensure_local_path_read_access(context, root_uri, relative_path)
+            .map_err(|error| error.with_context(context))
+    }
+}
+
+fn resolve_file_path(
+    state: &AppState,
+    context: &RequestContext,
+    params: &Value,
+    require_write: bool,
+) -> Result<(PathBuf, Option, Option), WebError> {
+    let root_uri = params
+        .get("rootUri")
+        .or_else(|| params.get("root_uri"))
+        .and_then(Value::as_str)
+        .map(str::trim)
+        .filter(|value| !value.is_empty());
+    let path = params
+        .get("path")
+        .or_else(|| params.get("relativePath"))
+        .or_else(|| params.get("relative_path"))
+        .and_then(Value::as_str)
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .ok_or_else(|| WebError::bad_request_code("page_ai_pi_lab_path_required", "缺少 path"))?;
+
+    if let Some(root_uri) = root_uri {
+        let target = resolve_root_relative_path(state, context, root_uri, path, require_write)?;
+        return Ok((target, Some(root_uri.to_string()), Some(path.to_string())));
+    }
+
+    let requested = PathBuf::from(path);
+    if !requested.is_absolute() {
+        return Err(WebError::bad_request_code(
+            "page_ai_pi_lab_absolute_path_required",
+            "未提供 rootUri 时 path 必须是绝对路径",
+        )
+        .with_context(context));
+    }
+    let allowed = active_allowed_roots(state, context)?;
+    let target = canonical_or_parent(&requested);
+    let allowed_root = allowed
+        .iter()
+        .find(|root| path_is_inside(&target, &root.root_path))
+        .ok_or_else(|| {
+            WebError::new(
+                StatusCode::FORBIDDEN,
+                "page_ai_pi_lab_path_not_allowed",
+                "文件路径不在当前 allowed roots 内",
+            )
+            .with_context(context)
+        })?;
+    if require_write && !root_can_write(allowed_root) {
+        return Err(WebError::new(
+            StatusCode::FORBIDDEN,
+            "page_ai_pi_lab_path_readonly",
+            "目标文件所在 allowed root 只有只读权限",
+        )
+        .with_context(context));
+    }
+    let relative = target
+        .strip_prefix(canonical_or_parent(&allowed_root.root_path))
+        .ok()
+        .map(|value| value.to_string_lossy().to_string());
+    Ok((target, allowed_root.root_uri.clone(), relative))
+}
+
+fn managed_session_dir(
+    context: &RequestContext,
+    root_uri: Option<&str>,
+    session_id: &str,
+) -> Result {
+    let actor = context.auth.actor_id.trim().replace(['/', '\\', ':'], "_");
+    if let Some(root_path) = root_uri.and_then(file_path_from_root_uri) {
+        return Ok(root_path
+            .join(".mnote")
+            .join("ai")
+            .join("pi-sessions")
+            .join(if actor.is_empty() {
+                "anonymous"
+            } else {
+                &actor
+            })
+            .join(session_id));
+    }
+    Ok(std::env::temp_dir()
+        .join("mnote-web")
+        .join("pi-lab")
+        .join(if actor.is_empty() {
+            "anonymous"
+        } else {
+            &actor
+        })
+        .join(session_id))
+}
+
+fn session_from_request(
+    state: &AppState,
+    context: &RequestContext,
+    request: &PiLabStartRequest,
+) -> Result {
+    let mnote_user_id = ensure_authenticated(state, context)?;
+    let session_id = request
+        .session_id
+        .clone()
+        .unwrap_or_else(|| generate_id("pi_lab"));
+    let session_dir = managed_session_dir(context, request.root_uri.as_deref(), &session_id)?;
+    let now = now_ms();
+    Ok(PiLabSession {
+        session_id: session_id.clone(),
+        mnote_user_id,
+        bridge_token: generate_bridge_token(),
+        status: PiLabSessionStatus::Idle,
+        provider_session_id: generate_id("pi_provider"),
+        pi_session_dir: session_dir.to_string_lossy().to_string(),
+        pi_session_file: None,
+        root_uri: request.root_uri.clone(),
+        workspace_id: request.workspace_id.clone(),
+        page_path: request.page_path.clone(),
+        page_title: request.page_title.clone(),
+        model_provider: request
+            .model_provider
+            .clone()
+            .filter(|v| !v.trim().is_empty())
+            .or_else(|| Some(default_model_provider())),
+        model_id: request
+            .model_id
+            .clone()
+            .filter(|v| !v.trim().is_empty())
+            .or_else(|| Some(default_model_id())),
+        runtime_pid: None,
+        runtime_mode: runtime_mode(),
+        runtime_error: None,
+        allowed_roots_snapshot: None,
+        created_at_ms: now,
+        updated_at_ms: now,
+        message_count: 0,
+    })
+}
+
+fn runtime_mode() -> String {
+    std::env::var("MNOTE_PAGE_AI_PI_LAB_RUNTIME")
+        .ok()
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+        .unwrap_or_else(|| "rpc".into())
+}
+
+fn env_trimmed(name: &str) -> Option {
+    std::env::var(name)
+        .ok()
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+}
+
+fn pi_binary() -> String {
+    env_trimmed("MNOTE_PAGE_AI_PI_BIN").unwrap_or_else(|| "pi".into())
+}
+
+fn default_model_provider() -> String {
+    env_trimmed("MNOTE_PAGE_AI_PI_DEFAULT_MODEL_PROVIDER")
+        .unwrap_or_else(|| PI_LAB_DEFAULT_MODEL_PROVIDER.into())
+}
+
+fn default_model_id() -> String {
+    env_trimmed("MNOTE_PAGE_AI_PI_DEFAULT_MODEL")
+        .or_else(|| env_trimmed("MNOTE_PAGE_AI_PI_DEFAULT_MODEL_ID"))
+        .unwrap_or_else(|| PI_LAB_DEFAULT_MODEL_ID.into())
+}
+
+fn omniroute_base_url() -> String {
+    env_trimmed("MNOTE_PAGE_AI_PI_OMNIROUTE_BASE_URL")
+        .or_else(|| env_trimmed("OMNIROUTE_BASE_URL"))
+        .unwrap_or_else(|| PI_LAB_DEFAULT_OMNIROUTE_BASE_URL.into())
+}
+
+fn omniroute_api_key() -> Option {
+    env_trimmed("MNOTE_PAGE_AI_PI_OMNIROUTE_API_KEY")
+        .or_else(|| env_trimmed("MNOTE_PAGE_AI_PI_OPENAI_API_KEY"))
+        .or_else(|| env_trimmed("OPENAI_API_KEY"))
+}
+
+/// 为 Pi 子进程生成每 session 受控的 models.json。
+/// - 写入 `/config/models.json`
+/// - API key 仅以环境变量引用（$OPENAI_API_KEY），不写入明文
+/// - 调用方应将 `PI_CODING_AGENT_DIR` 设为返回的 config 目录
+fn ensure_session_models_config(session: &PiLabSession) -> Result {
+    let config_dir = PathBuf::from(&session.pi_session_dir).join("config");
+    fs::create_dir_all(&config_dir).map_err(|error| {
+        WebError::internal(format!("创建 Pi Lab session config 目录失败: {error}"))
+    })?;
+    let models_path = config_dir.join("models.json");
+    let model_provider = session
+        .model_provider
+        .as_deref()
+        .unwrap_or(PI_LAB_DEFAULT_MODEL_PROVIDER);
+    let model_id = session
+        .model_id
+        .as_deref()
+        .filter(|value| !value.trim().is_empty())
+        .unwrap_or(PI_LAB_DEFAULT_MODEL_ID);
+    let models = match model_provider {
+        "omniroute" => json!({
+            "providers": {
+                "omniroute": {
+                    "baseUrl": omniroute_base_url(),
+                    "api": "openai-completions",
+                    "apiKey": "$OPENAI_API_KEY",
+                    "authHeader": true,
+                    "compat": {
+                        "supportsDeveloperRole": false,
+                        "supportsReasoningEffort": false
+                    },
+                    "models": [
+                        {
+                            "id": model_id,
+                            "name": format!("OmniRoute {}", model_id),
+                            "input": ["text"],
+                            "reasoning": false,
+                            "contextWindow": 128000,
+                            "maxTokens": 65536,
+                            "cost": {
+                                "input": 0,
+                                "output": 0,
+                                "cacheRead": 0,
+                                "cacheWrite": 0
+                            }
+                        }
+                    ]
+                }
+            }
+        }),
+        _ => json!({
+            "providers": {
+                model_provider: {
+                    "models": [
+                        {
+                            "id": model_id,
+                            "name": format!("{} {}", model_provider, model_id),
+                            "input": ["text"],
+                            "reasoning": false,
+                            "contextWindow": 128000,
+                            "maxTokens": 65536
+                        }
+                    ]
+                }
+            }
+        }),
+    };
+    let pretty = serde_json::to_string_pretty(&models)
+        .map_err(|error| WebError::internal(format!("序列化 Pi Lab models.json 失败: {error}")))?;
+    fs::write(&models_path, pretty.as_bytes())
+        .map_err(|error| WebError::internal(format!("写入 Pi Lab models.json 失败: {error}")))?;
+    Ok(config_dir)
+}
+
+fn pi_lab_public_base_url() -> String {
+    std::env::var("MNOTE_WEB_PUBLIC_BIND")
+        .or_else(|_| std::env::var("MNOTE_WEB_BIND"))
+        .ok()
+        .map(|value| value.trim().trim_end_matches('/').to_string())
+        .filter(|value| !value.is_empty())
+        .map(|value| {
+            if value.starts_with("http://") || value.starts_with("https://") {
+                value
+            } else {
+                format!("http://{value}")
+            }
+        })
+        .unwrap_or_else(|| "http://127.0.0.1:3000".into())
+}
+
+fn pi_lab_extension_tool_names() -> Vec<&'static str> {
+    vec![
+        "mnote_current_page_read",
+        "mnote_selection_read",
+        "mnote_allowed_roots_describe",
+        "mnote_local_file_read",
+        "mnote_local_file_patch",
+        "mnote_knowledge_rag_query",
+        "mnote_reference_open",
+        "mnote_tool_receipt_write",
+    ]
+}
+
+fn ensure_session_tool_bridge_extension(session: &PiLabSession) -> Result {
+    let extension_dir = PathBuf::from(&session.pi_session_dir).join("extensions");
+    fs::create_dir_all(&extension_dir).map_err(|error| {
+        WebError::internal(format!(
+            "创建 Pi Lab tool bridge extension 目录失败: {error}"
+        ))
+    })?;
+    let extension_path = extension_dir.join("mnote-tool-bridge.ts");
+    let base_url =
+        serde_json::to_string(&pi_lab_public_base_url()).unwrap_or_else(|_| "\"\"".into());
+    let session_id = serde_json::to_string(&session.session_id).unwrap_or_else(|_| "\"\"".into());
+    let source = format!(
+        r#"import type {{ ExtensionAPI }} from "@earendil-works/pi-coding-agent";
+import {{ Type }} from "typebox";
+
+const BASE_URL = {base_url};
+const SESSION_ID = {session_id};
+const BRIDGE_TOKEN = process.env.MNOTE_PI_LAB_BRIDGE_TOKEN || "";
+
+async function callMnote(toolName: string, params: unknown) {{
+  const response = await fetch(`${{BASE_URL}}/api/page-ai/pi/tool-call-bridge`, {{
+    method: "POST",
+    headers: {{
+      "content-type": "application/json",
+      "x-mnote-pi-lab-bridge-token": BRIDGE_TOKEN,
+    }},
+    body: JSON.stringify({{ sessionId: SESSION_ID, toolName, params: params || {{}} }}),
+  }});
+  const payload = await response.json().catch(() => ({{ ok: false, code: "bad_json" }}));
+  const text = JSON.stringify(payload.result || payload, null, 2);
+  return {{
+    content: [{{ type: "text", text }}],
+    details: payload,
+  }};
+}}
+
+function register(pi: ExtensionAPI, name: string, label: string, description: string, toolName: string) {{
+  pi.registerTool({{
+    name,
+    label,
+    description,
+    promptSnippet: `${{label}}: ${{description}}`,
+    parameters: Type.Object({{}}, {{ additionalProperties: true }}),
+    async execute(_toolCallId, params) {{
+      return callMnote(toolName, params);
+    }},
+  }});
+}}
+
+export default function mnoteToolBridge(pi: ExtensionAPI) {{
+  register(pi, "mnote_current_page_read", "MNote current page read", "Read the current MNote page through MNote access scope.", "mnote.current_page.read");
+  register(pi, "mnote_selection_read", "MNote selection read", "Read the current MNote editor selection snapshot supplied by MNote.", "mnote.selection.read");
+  register(pi, "mnote_allowed_roots_describe", "MNote allowed roots describe", "Describe MNote allowed roots and disabled raw tools.", "mnote.allowed_roots.describe");
+  register(pi, "mnote_local_file_read", "MNote local file read", "Read a file only through MNote allowed roots.", "mnote.local_file.read");
+  register(pi, "mnote_local_file_patch", "MNote local file patch", "Patch a file only through MNote allowed roots and watcher refresh.", "mnote.local_file.patch");
+  register(pi, "mnote_knowledge_rag_query", "MNote LightRAG query", "Query LightRAG only through the MNote knowledge facade.", "mnote.knowledge_rag.query");
+  register(pi, "mnote_reference_open", "MNote reference open", "Open a citation/reference through MNote mapping.", "mnote.reference.open");
+  register(pi, "mnote_tool_receipt_write", "MNote tool receipt write", "Write a provider-neutral MNote tool receipt.", "mnote.tool_receipt.write");
+}}
+"#
+    );
+    fs::write(&extension_path, source.as_bytes()).map_err(|error| {
+        WebError::internal(format!("写入 Pi Lab tool bridge extension 失败: {error}"))
+    })?;
+    Ok(extension_path)
+}
+
+fn publish_event(session_id: &str, kind: &str, payload: Value) {
+    let event = json!({
+        "schema": PI_LAB_SCHEMA_EVENT,
+        "sessionId": session_id,
+        "kind": kind,
+        "createdAtMs": now_ms(),
+        "payload": payload,
+    });
+    let _ = PI_LAB_EVENT_TX.send(event);
+}
+
+fn upsert_session(session: PiLabSession) {
+    if let Ok(mut sessions) = PI_LAB_SESSIONS.lock() {
+        sessions.insert(session.session_id.clone(), session);
+    }
+}
+
+fn update_session(session_id: &str, f: F)
+where
+    F: FnOnce(&mut PiLabSession),
+{
+    if let Ok(mut sessions) = PI_LAB_SESSIONS.lock() {
+        if let Some(session) = sessions.get_mut(session_id) {
+            f(session);
+            session.updated_at_ms = now_ms();
+        }
+    }
+}
+
+fn get_session(session_id: &str) -> Option {
+    PI_LAB_SESSIONS
+        .lock()
+        .ok()
+        .and_then(|sessions| sessions.get(session_id).cloned())
+}
+
+fn cleanup_expired_sessions() {
+    let cutoff = now_ms().saturating_sub(PI_LAB_SESSION_TTL_MS);
+    let expired = PI_LAB_SESSIONS
+        .lock()
+        .map(|mut sessions| {
+            let mut expired = sessions
+                .iter()
+                .filter_map(|(session_id, session)| {
+                    (session.updated_at_ms < cutoff
+                        && !matches!(
+                            session.status,
+                            PiLabSessionStatus::RuntimeRunning | PiLabSessionStatus::TurnRunning
+                        ))
+                    .then(|| (session_id.clone(), session.pi_session_dir.clone()))
+                })
+                .collect::>();
+            for (session_id, _) in &expired {
+                sessions.remove(session_id);
+            }
+            if sessions.len() > PI_LAB_MAX_SESSIONS {
+                let mut removable = sessions
+                    .values()
+                    .filter(|session| {
+                        !matches!(
+                            session.status,
+                            PiLabSessionStatus::RuntimeRunning | PiLabSessionStatus::TurnRunning
+                        )
+                    })
+                    .map(|session| {
+                        (
+                            session.updated_at_ms,
+                            session.session_id.clone(),
+                            session.pi_session_dir.clone(),
+                        )
+                    })
+                    .collect::>();
+                removable.sort_by_key(|(updated_at, _, _)| *updated_at);
+                for (_, session_id, session_dir) in removable
+                    .into_iter()
+                    .take(sessions.len().saturating_sub(PI_LAB_MAX_SESSIONS))
+                {
+                    sessions.remove(&session_id);
+                    expired.push((session_id, session_dir));
+                }
+            }
+            expired
+        })
+        .unwrap_or_default();
+    if !expired.is_empty() {
+        if let Ok(mut processes) = PI_LAB_PROCESSES.lock() {
+            for (session_id, _) in &expired {
+                processes.remove(session_id);
+            }
+        }
+        for (_, session_dir) in expired {
+            let path = PathBuf::from(session_dir);
+            if path
+                .components()
+                .any(|component| component.as_os_str() == "pi-sessions")
+            {
+                let _ = fs::remove_dir_all(path);
+            }
+        }
+    }
+}
+
+fn check_rate_limit(actor_id: &str, action: &str, limit: usize) -> Result<(), WebError> {
+    let now = now_ms();
+    let key = format!("{actor_id}:{action}");
+    if let Ok(mut buckets) = PI_LAB_RATE_LIMITS.lock() {
+        let bucket = buckets.entry(key).or_default();
+        bucket.retain(|timestamp| now.saturating_sub(*timestamp) <= PI_LAB_RATE_WINDOW_MS);
+        if bucket.len() >= limit {
+            return Err(WebError::new(
+                StatusCode::TOO_MANY_REQUESTS,
+                "page_ai_pi_lab_rate_limited",
+                format!("Pi Lab {action} 请求过于频繁，请稍后再试"),
+            ));
+        }
+        bucket.push(now);
+        buckets.retain(|_, timestamps| !timestamps.is_empty());
+    }
+    Ok(())
+}
+
+fn get_session_for_context(
+    state: &AppState,
+    context: &RequestContext,
+    session_id: &str,
+) -> Result {
+    let session = get_session(session_id).ok_or_else(|| {
+        WebError::bad_request_code("page_ai_pi_lab_session_not_found", "Pi Lab session 不存在")
+    })?;
+    ensure_session_owner(state, context, &session)?;
+    Ok(session)
+}
+
+fn bridge_token_from_headers(headers: &HeaderMap) -> Option<&str> {
+    headers
+        .get(HEADER_PI_LAB_BRIDGE_TOKEN)
+        .and_then(|value| value.to_str().ok())
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+}
+
+fn get_session_for_bridge(headers: &HeaderMap, session_id: &str) -> Result {
+    let session = get_session(session_id).ok_or_else(|| {
+        WebError::bad_request_code("page_ai_pi_lab_session_not_found", "Pi Lab session 不存在")
+    })?;
+    if !matches!(
+        session.status,
+        PiLabSessionStatus::RuntimeRunning | PiLabSessionStatus::TurnRunning
+    ) {
+        return Err(WebError::new(
+            StatusCode::FORBIDDEN,
+            "page_ai_pi_lab_bridge_session_not_running",
+            "Pi Lab internal tool bridge 只允许运行中的 session 调用",
+        ));
+    }
+    if bridge_token_from_headers(headers) == Some(session.bridge_token.as_str()) {
+        return Ok(session);
+    }
+    Err(WebError::new(
+        StatusCode::UNAUTHORIZED,
+        "page_ai_pi_lab_bridge_token_invalid",
+        "Pi Lab internal tool bridge token 无效",
+    ))
+}
+
+fn context_for_session(mut context: RequestContext, session: &PiLabSession) -> RequestContext {
+    context.auth.actor_id = session.mnote_user_id.clone();
+    context.auth.actor_type = "user".into();
+    context
+}
+
+async fn start_runtime_for_session(
+    state: &AppState,
+    mut session: PiLabSession,
+) -> Result {
+    fs::create_dir_all(&session.pi_session_dir)
+        .map_err(|error| WebError::internal(format!("创建 Pi Lab sessionDir 失败: {error}")))?;
+    let pi_config_dir = ensure_session_models_config(&session)?;
+    let bridge_extension_path = ensure_session_tool_bridge_extension(&session)?;
+    let mnote_tool_names = pi_lab_extension_tool_names();
+    if session.runtime_mode == "mock" {
+        session.status = PiLabSessionStatus::RuntimeRunning;
+        session.runtime_pid = None;
+        upsert_session(session.clone());
+        persist_upsert_run(state, &session)?;
+        persist_append_event(
+            state,
+            &session,
+            "runtime_started",
+            &json!({
+                "mode": "mock",
+                "providerSessionId": session.provider_session_id,
+                "modelProvider": session.model_provider,
+                "modelId": session.model_id,
+            }),
+        )?;
+        publish_event(
+            &session.session_id,
+            "runtime_started",
+            json!({
+                "mode": "mock",
+                "providerSessionId": session.provider_session_id,
+                "modelProvider": session.model_provider,
+                "modelId": session.model_id,
+                "piCodingAgentDir": pi_config_dir,
+                "mnoteToolBridgeExtension": bridge_extension_path,
+                "mnoteToolNames": mnote_tool_names,
+            }),
+        );
+        return Ok(session);
+    }
+    let mut command = Command::new(pi_binary());
+    command
+        .arg("--mode")
+        .arg("rpc")
+        .arg("--session-dir")
+        .arg(&session.pi_session_dir)
+        .arg("--no-approve")
+        .arg("--no-builtin-tools")
+        .arg("--no-extensions")
+        .arg("--extension")
+        .arg(&bridge_extension_path)
+        .arg("--tools")
+        .arg(mnote_tool_names.join(","))
+        .arg("--no-skills")
+        .arg("--no-prompt-templates")
+        .arg("--no-context-files")
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped());
+    if let Some(provider) = session
+        .model_provider
+        .as_deref()
+        .filter(|value| !value.is_empty())
+    {
+        command.arg("--provider").arg(provider);
+    }
+    if let Some(model) = session
+        .model_id
+        .as_deref()
+        .filter(|value| !value.is_empty())
+    {
+        command.arg("--model").arg(model);
+    }
+    command
+        .arg("--name")
+        .arg(format!("MNote Pi Lab {}", session.session_id));
+
+    // 生成每 session 受控的 models.json，设置 PI_CODING_AGENT_DIR
+    // API key 仅从环境读取，不写入日志或 command line
+    command.env(
+        "PI_CODING_AGENT_DIR",
+        pi_config_dir.to_string_lossy().to_string(),
+    );
+    command.env("MNOTE_PI_LAB_BRIDGE_TOKEN", &session.bridge_token);
+    command.env("OPENAI_BASE_URL", omniroute_base_url());
+    if let Some(key) = omniroute_api_key() {
+        command.env("OPENAI_API_KEY", key);
+    }
+
+    let mut child = command.spawn().map_err(|error| {
+        WebError::bad_gateway_code(
+            "page_ai_pi_lab_runtime_spawn_failed",
+            format!("启动 pi --mode rpc 失败: {error}"),
+        )
+    })?;
+    let pid = child.id();
+    let stdin = child.stdin.take().ok_or_else(|| {
+        WebError::bad_gateway_code("page_ai_pi_lab_stdin_missing", "Pi RPC stdin 不可用")
+    })?;
+    let stdout = child.stdout.take().ok_or_else(|| {
+        WebError::bad_gateway_code("page_ai_pi_lab_stdout_missing", "Pi RPC stdout 不可用")
+    })?;
+
+    let handle = PiLabProcessHandle {
+        stdin: Arc::new(AsyncMutex::new(stdin)),
+        child: Arc::new(AsyncMutex::new(child)),
+        _pid: pid,
+    };
+    if let Ok(mut processes) = PI_LAB_PROCESSES.lock() {
+        processes.insert(session.session_id.clone(), handle);
+    }
+
+    session.status = PiLabSessionStatus::RuntimeRunning;
+    session.runtime_pid = pid;
+    upsert_session(session.clone());
+    publish_event(
+        &session.session_id,
+        "runtime_started",
+        json!({
+            "mode": "rpc",
+            "pid": pid,
+            "sessionDir": session.pi_session_dir,
+            "providerSessionId": session.provider_session_id,
+            "modelProvider": session.model_provider,
+            "modelId": session.model_id,
+            "omnirouteBaseUrl": omniroute_base_url(),
+            "piCodingAgentDir": pi_config_dir,
+            "mnoteToolBridgeExtension": bridge_extension_path,
+            "mnoteToolNames": mnote_tool_names,
+            "disabledBuiltinTools": ["bash", "read", "write", "edit"],
+        }),
+    );
+
+    let session_id = session.session_id.clone();
+    let cloned_state = state.clone();
+    let session_user_id = session.mnote_user_id.clone();
+    let session_workspace_id = session.workspace_id.clone();
+    let session_page_path = session.page_path.clone();
+
+    tokio::spawn(async move {
+        let cp: &dyn ControlPlaneStore = cloned_state.control_plane();
+        let run_id = pi_run_id(&session_id);
+        let persist_event = |event_type: &str, event_payload: &Value| {
+            let input = AppendAiRuntimeEventInput {
+                id: None,
+                user_id: session_user_id.clone(),
+                workspace_id: session_workspace_id.clone(),
+                document_id: session_page_path.clone(),
+                session_id: session_id.clone(),
+                run_id: run_id.clone(),
+                profile: PI_LAB_PROFILE.to_string(),
+                acp_runtime: PI_LAB_ACP_RUNTIME.to_string(),
+                event_type: event_type.to_string(),
+                payload_json: serde_json::to_string(event_payload).unwrap_or_else(|_| "{}".into()),
+            };
+            if let Err(e) = cp.append_ai_runtime_event(input) {
+                publish_event(
+                    &session_id,
+                    "runtime_persistence_error",
+                    json!({
+                        "error": e.to_string(),
+                        "eventType": event_type,
+                    }),
+                );
+            }
+        };
+
+        let mut lines = BufReader::new(stdout).lines();
+        loop {
+            match lines.next_line().await {
+                Ok(Some(line)) => {
+                    let payload = serde_json::from_str::(&line)
+                        .unwrap_or_else(|_| json!({"raw": line}));
+                    if payload.get("type").and_then(Value::as_str) == Some("agent_end") {
+                        update_session(&session_id, |session| {
+                            session.status = PiLabSessionStatus::RuntimeRunning;
+                        });
+                    }
+                    persist_event("pi_rpc_event", &payload);
+                    publish_event(&session_id, "pi_rpc_event", payload);
+                }
+                Ok(None) => {
+                    update_session(&session_id, |session| {
+                        session.status = PiLabSessionStatus::Idle;
+                    });
+                    persist_event("runtime_stdout_closed", &json!({}));
+                    publish_event(&session_id, "runtime_stdout_closed", json!({}));
+                    break;
+                }
+                Err(error) => {
+                    update_session(&session_id, |session| {
+                        session.status = PiLabSessionStatus::Error;
+                        session.runtime_error = Some(error.to_string());
+                    });
+                    publish_event(
+                        &session_id,
+                        "runtime_stdout_error",
+                        json!({"error": error.to_string()}),
+                    );
+                    persist_event("runtime_stdout_error", &json!({"error": error.to_string()}));
+                    break;
+                }
+            }
+        }
+    });
+
+    persist_upsert_run(state, &session)?;
+    persist_append_event(
+        state,
+        &session,
+        "runtime_started",
+        &json!({
+            "mode": "rpc",
+            "pid": session.runtime_pid,
+            "providerSessionId": session.provider_session_id,
+            "modelProvider": session.model_provider,
+            "modelId": session.model_id,
+        }),
+    )?;
+    Ok(session)
+}
+
+async fn send_rpc_command(session_id: &str, command: Value) -> Result<(), WebError> {
+    let handle = PI_LAB_PROCESSES
+        .lock()
+        .ok()
+        .and_then(|processes| processes.get(session_id).cloned());
+    let Some(handle) = handle else {
+        return Err(WebError::bad_request_code(
+            "page_ai_pi_lab_runtime_not_started",
+            "Pi runtime 未启动；请先调用 /api/page-ai/pi/start",
+        ));
+    };
+    let mut stdin = handle.stdin.lock().await;
+    let line = serde_json::to_string(&command)
+        .map_err(|error| WebError::internal(format!("序列化 Pi RPC command 失败: {error}")))?;
+    stdin.write_all(line.as_bytes()).await.map_err(|error| {
+        WebError::bad_gateway_code("page_ai_pi_lab_rpc_write_failed", error.to_string())
+    })?;
+    stdin.write_all(b"\n").await.map_err(|error| {
+        WebError::bad_gateway_code("page_ai_pi_lab_rpc_write_failed", error.to_string())
+    })?;
+    stdin.flush().await.map_err(|error| {
+        WebError::bad_gateway_code("page_ai_pi_lab_rpc_flush_failed", error.to_string())
+    })?;
+    Ok(())
+}
+
+fn apply_text_operations(current: &str, operations: &Value) -> Result {
+    match operations {
+        Value::Array(ops) => {
+            let mut result = current.to_string();
+            for op in ops {
+                result = apply_single_operation(&result, op)?;
+            }
+            Ok(result)
+        }
+        Value::Object(_) => apply_single_operation(current, operations),
+        _ => Err(WebError::bad_request_code(
+            "page_ai_pi_lab_invalid_operations",
+            "operations 必须是对象或数组",
+        )),
+    }
+}
+
+fn apply_single_operation(current: &str, op: &Value) -> Result {
+    let op_type = op.get("op").and_then(Value::as_str).ok_or_else(|| {
+        WebError::bad_request_code("page_ai_pi_lab_missing_op", "operation 缺少 op 字段")
+    })?;
+    match op_type {
+        "replace" => {
+            let old = op.get("old").and_then(Value::as_str).ok_or_else(|| {
+                WebError::bad_request_code("page_ai_pi_lab_missing_old", "replace 缺少 old")
+            })?;
+            let new = op.get("new").and_then(Value::as_str).unwrap_or("");
+            if !current.contains(old) {
+                return Err(WebError::bad_request_code(
+                    "page_ai_pi_lab_replace_not_found",
+                    "replace 未找到匹配文本",
+                ));
+            }
+            Ok(current.replacen(old, new, 1))
+        }
+        "append" => {
+            let content = op.get("content").and_then(Value::as_str).ok_or_else(|| {
+                WebError::bad_request_code("page_ai_pi_lab_missing_content", "append 缺少 content")
+            })?;
+            Ok(format!("{current}{content}"))
+        }
+        "prepend" => {
+            let content = op.get("content").and_then(Value::as_str).ok_or_else(|| {
+                WebError::bad_request_code("page_ai_pi_lab_missing_content", "prepend 缺少 content")
+            })?;
+            Ok(format!("{content}{current}"))
+        }
+        "delete" => {
+            let target = op.get("target").and_then(Value::as_str).ok_or_else(|| {
+                WebError::bad_request_code("page_ai_pi_lab_missing_target", "delete 缺少 target")
+            })?;
+            if !current.contains(target) {
+                return Err(WebError::bad_request_code(
+                    "page_ai_pi_lab_delete_not_found",
+                    "delete 未找到匹配文本",
+                ));
+            }
+            Ok(current.replacen(target, "", 1))
+        }
+        _ => Err(WebError::bad_request_code(
+            "page_ai_pi_lab_unknown_op",
+            format!("不支持的 operation: {op_type}"),
+        )),
+    }
+}
+
+fn file_version(path: &Path) -> Option {
+    let bytes = fs::read(path).ok()?;
+    use std::hash::{Hash, Hasher};
+    let mut hasher = std::collections::hash_map::DefaultHasher::new();
+    bytes.hash(&mut hasher);
+    Some(format!("{:016x}", hasher.finish()))
+}
+
+fn write_receipt(
+    state: &AppState,
+    receipt: PiLabToolReceipt,
+    result_payload: &Value,
+    citation_count: usize,
+) -> Value {
+    if let Ok(mut store) = PI_LAB_RECEIPT_STORE.lock() {
+        store.push(receipt.clone());
+        if store.len() > 1000 {
+            store.remove(0);
+        }
+    }
+
+    let receipt_payload = serde_json::to_string(&json!({
+        "receipt": receipt,
+        "result": result_payload,
+    }))
+    .unwrap_or_else(|_| "{}".into());
+    let event_result = state
+        .control_plane()
+        .append_ai_tool_event(AppendAiToolEventInput {
+            id: Some(receipt.receipt_id.clone()),
+            user_id: receipt.mnote_user_id.clone(),
+            workspace_id: receipt.workspace_id.clone(),
+            session_id: receipt.session_id.clone(),
+            run_id: (receipt.session_id != "standalone_tool_call")
+                .then(|| pi_run_id(&receipt.session_id)),
+            provider: receipt.provider.to_string(),
+            provider_session_id: receipt.provider_session_id.clone(),
+            tool_name: receipt.tool_name.clone(),
+            allowed: receipt.allowed,
+            deny_reason: receipt.deny_reason.clone(),
+            root_uri: receipt.root_uri.clone().unwrap_or_default(),
+            page_path: receipt.page_path.clone(),
+            normalized_file_path: receipt.normalized_file_path.clone(),
+            diff_summary: receipt.diff_summary.clone(),
+            citation_count: citation_count as i64,
+            before_file_version: receipt.before_file_version.clone(),
+            after_file_version: receipt.after_file_version.clone(),
+            payload_json: receipt_payload,
+        });
+    if let Ok(event) = event_result {
+        let patch_persisted = if receipt.tool_name == "mnote.local_file.patch" && receipt.allowed {
+            let relative_path = result_payload
+                .get("relativePath")
+                .and_then(Value::as_str)
+                .unwrap_or_default()
+                .to_string();
+            let root_uri = result_payload
+                .get("rootUri")
+                .and_then(Value::as_str)
+                .map(str::to_string)
+                .or_else(|| receipt.root_uri.clone())
+                .unwrap_or_default();
+            state
+                .control_plane()
+                .append_ai_file_patch(AppendAiFilePatchInput {
+                    id: None,
+                    user_id: receipt.mnote_user_id.clone(),
+                    workspace_id: receipt.workspace_id.clone(),
+                    session_id: receipt.session_id.clone(),
+                    run_id: (receipt.session_id != "standalone_tool_call")
+                        .then(|| pi_run_id(&receipt.session_id)),
+                    tool_event_id: event.id,
+                    root_uri,
+                    relative_path,
+                    before_file_version: receipt.before_file_version.clone(),
+                    after_file_version: receipt.after_file_version.clone(),
+                    patch_summary_json: serde_json::to_string(&json!({
+                        "diffSummary": receipt.diff_summary,
+                        "oldSize": result_payload.get("oldSize"),
+                        "newSize": result_payload.get("newSize"),
+                    }))
+                    .unwrap_or_else(|_| "{}".into()),
+                })
+                .is_ok()
+        } else {
+            false
+        };
+        return json!({
+            "receiptId": receipt.receipt_id,
+            "storage": "control_plane_turso_libsql_v1",
+            "persisted": true,
+            "patchPersisted": patch_persisted,
+        });
+    }
+
+    let mut adapter_path = std::env::temp_dir()
+        .join("mnote-web")
+        .join("pi-lab")
+        .join("tool-receipts.jsonl");
+    if let Some(root_path) = receipt
+        .root_uri
+        .as_deref()
+        .and_then(file_path_from_root_uri)
+    {
+        adapter_path = root_path
+            .join(".mnote")
+            .join("ai")
+            .join("pi-lab")
+            .join("tool-receipts.jsonl");
+    }
+    let persisted = (|| -> Result<(), std::io::Error> {
+        if let Some(parent) = adapter_path.parent() {
+            fs::create_dir_all(parent)?;
+        }
+        let mut file = OpenOptions::new()
+            .create(true)
+            .append(true)
+            .open(&adapter_path)?;
+        let line = serde_json::to_string(&receipt).unwrap_or_else(|_| "{}".into());
+        writeln!(file, "{line}")?;
+        Ok(())
+    })()
+    .is_ok();
+    json!({
+        "receiptId": receipt.receipt_id,
+        "storage": "provider_neutral_jsonl_debug_fallback_v1",
+        "persisted": persisted,
+        "path": adapter_path,
+        "fallbackReason": "control-plane ai_tool_events write failed",
+    })
+}
+
+fn receipt_for(
+    context: &RequestContext,
+    session: Option<&PiLabSession>,
+    tool_name: &str,
+    normalized_file_path: Option,
+    allowed: bool,
+    deny_reason: Option,
+    diff_summary: Option,
+    before_file_version: Option,
+    after_file_version: Option,
+) -> PiLabToolReceipt {
+    PiLabToolReceipt {
+        schema: PI_LAB_SCHEMA_RECEIPT,
+        receipt_id: generate_id("pi_receipt"),
+        mnote_user_id: context.auth.actor_id.clone(),
+        workspace_id: session.and_then(|session| session.workspace_id.clone()),
+        root_uri: session.and_then(|session| session.root_uri.clone()),
+        page_path: session.and_then(|session| session.page_path.clone()),
+        session_id: session
+            .map(|session| session.session_id.clone())
+            .unwrap_or_else(|| "standalone_tool_call".into()),
+        tool_name: tool_name.to_string(),
+        normalized_file_path,
+        allowed,
+        deny_reason,
+        diff_summary,
+        before_file_version,
+        after_file_version,
+        provider: PI_LAB_PROVIDER,
+        provider_session_id: session.map(|session| session.provider_session_id.clone()),
+        model_provider: session.and_then(|session| session.model_provider.clone()),
+        model_id: session.and_then(|session| session.model_id.clone()),
+        allowed_roots_snapshot: session.and_then(|session| session.allowed_roots_snapshot.clone()),
+        storage: "control_plane_turso_libsql_v1".into(),
+        created_at_ms: now_ms(),
+    }
+}
+
+pub struct PiLabToolFacade {
+    state: AppState,
+    context: RequestContext,
+    session: Option,
+}
+
+impl PiLabToolFacade {
+    fn session_root_uri(&self, params: &Value) -> Option {
+        params
+            .get("rootUri")
+            .or_else(|| params.get("root_uri"))
+            .and_then(Value::as_str)
+            .map(str::to_string)
+            .or_else(|| {
+                self.session
+                    .as_ref()
+                    .and_then(|session| session.root_uri.clone())
+            })
+    }
+
+    fn session_page_path(&self, params: &Value) -> Option {
+        params
+            .get("pagePath")
+            .or_else(|| params.get("page_path"))
+            .or_else(|| params.get("path"))
+            .and_then(Value::as_str)
+            .map(str::to_string)
+            .or_else(|| {
+                self.session
+                    .as_ref()
+                    .and_then(|session| session.page_path.clone())
+            })
+    }
+
+    fn current_page_read(&self, params: Value) -> Result {
+        let root_uri = self.session_root_uri(¶ms).ok_or_else(|| {
+            WebError::bad_request_code("page_ai_pi_lab_root_uri_required", "读取当前页缺少 rootUri")
+        })?;
+        let page_path = self.session_page_path(¶ms).ok_or_else(|| {
+            WebError::bad_request_code(
+                "page_ai_pi_lab_page_path_required",
+                "读取当前页缺少 pagePath",
+            )
+        })?;
+        let target =
+            resolve_root_relative_path(&self.state, &self.context, &root_uri, &page_path, false)?;
+        let content = fs::read_to_string(&target).map_err(|error| {
+            WebError::bad_request_code(
+                "page_ai_pi_lab_current_page_read_failed",
+                format!("读取当前页失败: {error}"),
+            )
+        })?;
+        Ok(json!({
+            "rootUri": root_uri,
+            "pagePath": page_path,
+            "path": target,
+            "content": content,
+            "contentLength": content.len(),
+            "format": "markdown",
+            "fileVersion": file_version(&target),
+        }))
+    }
+
+    fn selection_read(&self, params: Value) -> Result {
+        let source = params
+            .get("selectionSource")
+            .or_else(|| params.get("selection_source"))
+            .and_then(Value::as_str)
+            .unwrap_or_default();
+        if source != "mnote_sidebar_host" {
+            return Err(WebError::bad_request_code(
+                "page_ai_pi_lab_selection_snapshot_required",
+                "selection 必须由 MNote sidebar host 注入，不能由 provider 直接伪造",
+            ));
+        }
+        let selection = params.get("selection").cloned().unwrap_or(Value::Null);
+        Ok(json!({
+            "selection": selection,
+            "selectionSource": "mnote_sidebar_host_snapshot",
+            "rootUri": self.session_root_uri(¶ms),
+            "pagePath": self.session_page_path(¶ms),
+            "note": "Pi Lab 只接受 MNote sidebar host 注入的 tiptap live selection snapshot",
+        }))
+    }
+
+    fn allowed_roots_describe(&self) -> Result {
+        let roots = active_allowed_roots(&self.state, &self.context)?;
+        Ok(json!({
+            "allowedRoots": roots.iter().map(|root| json!({
+                "rootUri": root.root_uri,
+                "rootPath": root.root_path,
+                "workspaceId": root.workspace_id,
+                "permission": root.permission,
+                "source": root.source,
+            })).collect::>(),
+            "deniedPiBuiltinTools": ["bash", "read", "write", "edit"],
+            "mnoteTools": [
+                "mnote.current_page.read",
+                "mnote.selection.read",
+                "mnote.allowed_roots.describe",
+                "mnote.local_file.read",
+                "mnote.local_file.patch",
+                "mnote.knowledge_rag.query",
+                "mnote.reference.open",
+                "mnote.tool_receipt.write"
+            ],
+        }))
+    }
+
+    fn local_file_read(&self, params: Value) -> Result {
+        let (target, root_uri, relative_path) =
+            resolve_file_path(&self.state, &self.context, ¶ms, false)?;
+        let content = fs::read_to_string(&target).map_err(|error| {
+            WebError::bad_request_code(
+                "page_ai_pi_lab_file_read_failed",
+                format!("读取文件失败: {error}"),
+            )
+        })?;
+        Ok(json!({
+            "rootUri": root_uri,
+            "relativePath": relative_path,
+            "path": target,
+            "content": content,
+            "contentLength": content.len(),
+            "fileVersion": file_version(&target),
+        }))
+    }
+
+    fn local_file_patch(&self, params: Value) -> Result {
+        let (target, root_uri, relative_path) =
+            resolve_file_path(&self.state, &self.context, ¶ms, true)?;
+        let before_version = file_version(&target);
+        let current = fs::read_to_string(&target).unwrap_or_default();
+        let next = if let Some(content) = params.get("content").and_then(Value::as_str) {
+            content.to_string()
+        } else {
+            let operations = params.get("operations").ok_or_else(|| {
+                WebError::bad_request_code(
+                    "page_ai_pi_lab_operations_required",
+                    "patch 需要 content 或 operations",
+                )
+            })?;
+            apply_text_operations(¤t, operations)?
+        };
+        if let Some(parent) = target.parent() {
+            fs::create_dir_all(parent).map_err(|error| {
+                WebError::bad_request_code(
+                    "page_ai_pi_lab_patch_parent_failed",
+                    format!("创建父目录失败: {error}"),
+                )
+            })?;
+        }
+        fs::write(&target, next.as_bytes()).map_err(|error| {
+            WebError::bad_request_code(
+                "page_ai_pi_lab_patch_write_failed",
+                format!("写入文件失败: {error}"),
+            )
+        })?;
+        let after_version = file_version(&target);
+        let diff_summary = if current == next {
+            "no_changes".to_string()
+        } else {
+            format!("bytes_delta={}", next.len() as i64 - current.len() as i64)
+        };
+        Ok(json!({
+            "rootUri": root_uri,
+            "relativePath": relative_path,
+            "path": target,
+            "beforeFileVersion": before_version,
+            "afterFileVersion": after_version,
+            "oldSize": current.len(),
+            "newSize": next.len(),
+            "diffSummary": diff_summary,
+            "refresh": "mnote local-folder watcher / document-session external refresh",
+            "polling": false,
+        }))
+    }
+
+    async fn knowledge_rag_query(&self, params: Value) -> Result {
+        let query = params
+            .get("query")
+            .or_else(|| params.get("question"))
+            .and_then(Value::as_str)
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .ok_or_else(|| {
+                WebError::bad_request_code("page_ai_pi_lab_rag_query_required", "缺少 query")
+            })?;
+        let root_uri = self.session_root_uri(¶ms).ok_or_else(|| {
+            WebError::bad_request_code("page_ai_pi_lab_root_uri_required", "RAG 查询缺少 rootUri")
+        })?;
+        let body = knowledge_rag::KnowledgeRagQueryRequest {
+            workspace_id: self
+                .session
+                .as_ref()
+                .and_then(|session| session.workspace_id.clone())
+                .or_else(|| {
+                    params
+                        .get("workspaceId")
+                        .and_then(Value::as_str)
+                        .map(str::to_string)
+                }),
+            root_uri,
+            question: Some(query.to_string()),
+            query: None,
+            mode: params
+                .get("mode")
+                .and_then(Value::as_str)
+                .map(str::to_string),
+            top_k: params
+                .get("topK")
+                .and_then(Value::as_u64)
+                .map(|value| value as u32),
+            chunk_top_k: params
+                .get("chunkTopK")
+                .and_then(Value::as_u64)
+                .map(|value| value as u32),
+            include_chunk_content: params.get("includeChunkContent").and_then(Value::as_bool),
+            source_paths: params.get("sourcePaths").and_then(|value| {
+                value.as_array().map(|items| {
+                    items
+                        .iter()
+                        .filter_map(Value::as_str)
+                        .map(str::to_string)
+                        .collect::>()
+                })
+            }),
+            include_document_structure_index: params
+                .get("includeDocumentStructureIndex")
+                .and_then(Value::as_bool),
+            knowledge_base_id: params
+                .get("knowledgeBaseId")
+                .and_then(Value::as_str)
+                .map(str::to_string),
+            provider_knowledge_base_id: params
+                .get("providerKnowledgeBaseId")
+                .and_then(Value::as_str)
+                .map(str::to_string),
+        };
+        let Json(payload) = knowledge_rag::query_rag(
+            State(self.state.clone()),
+            Extension(self.context.clone()),
+            Json(body),
+        )
+        .await?;
+        Ok(payload)
+    }
+
+    async fn reference_open(&self, params: Value) -> Result {
+        let root_uri = self.session_root_uri(¶ms).ok_or_else(|| {
+            WebError::bad_request_code("page_ai_pi_lab_root_uri_required", "打开引用缺少 rootUri")
+        })?;
+        let body = knowledge_rag::KnowledgeRagOpenReferenceRequest {
+            workspace_id: self
+                .session
+                .as_ref()
+                .and_then(|session| session.workspace_id.clone())
+                .or_else(|| {
+                    params
+                        .get("workspaceId")
+                        .and_then(Value::as_str)
+                        .map(str::to_string)
+                }),
+            root_uri,
+            reference: params.get("reference").cloned(),
+            reference_id: params
+                .get("referenceId")
+                .or_else(|| params.get("reference_id"))
+                .and_then(Value::as_str)
+                .map(str::to_string),
+            file_path: params
+                .get("filePath")
+                .or_else(|| params.get("resourcePath"))
+                .or_else(|| params.get("path"))
+                .and_then(Value::as_str)
+                .map(str::to_string),
+            chunk_id: params
+                .get("chunkId")
+                .or_else(|| params.get("chunk_id"))
+                .and_then(Value::as_str)
+                .map(str::to_string),
+        };
+        let Json(payload) = knowledge_rag::open_reference(
+            State(self.state.clone()),
+            Extension(self.context.clone()),
+            Json(body),
+        )
+        .await?;
+        Ok(payload)
+    }
+}
+
+async fn execute_tool(
+    state: AppState,
+    context: RequestContext,
+    session_id: Option,
+    tool_name: String,
+    params: Value,
+) -> Result, WebError> {
+    let actor_id = ensure_authenticated(&state, &context)?;
+    check_rate_limit(&actor_id, "tool", PI_LAB_MAX_TOOLS_PER_WINDOW)?;
+    let session = if let Some(session_id) = session_id.as_deref() {
+        Some(get_session_for_context(&state, &context, session_id)?)
+    } else {
+        None
+    };
+    let facade = PiLabToolFacade {
+        state,
+        context: context.clone(),
+        session: session.clone(),
+    };
+    let started = now_ms();
+    let result: Result = match tool_name.as_str() {
+        "mnote.current_page.read" => facade.current_page_read(params.clone()),
+        "mnote.selection.read" => facade.selection_read(params.clone()),
+        "mnote.allowed_roots.describe" => facade.allowed_roots_describe(),
+        "mnote.local_file.read" => facade.local_file_read(params.clone()),
+        "mnote.local_file.patch" => facade.local_file_patch(params.clone()),
+        "mnote.knowledge_rag.query" => facade.knowledge_rag_query(params.clone()).await,
+        "mnote.reference.open" => facade.reference_open(params.clone()).await,
+        "mnote.tool_receipt.write" => Ok(json!({
+            "requestedReceipt": params,
+            "storage": "control_plane_turso_libsql_v1",
+            "note": "Pi Lab 由 execute_tool 统一写入 control-plane receipt journal",
+        })),
+        _ => Err(WebError::bad_request_code(
+            "page_ai_pi_lab_unknown_tool",
+            format!("未知 Pi Lab tool: {tool_name}"),
+        )),
+    };
+
+    let normalized_file_path = params
+        .get("path")
+        .and_then(Value::as_str)
+        .map(str::to_string);
+    let (allowed, payload, deny_reason, diff_summary, before_file_version, after_file_version) =
+        match result {
+            Ok(payload) => (
+                true,
+                payload.clone(),
+                None,
+                payload
+                    .get("diffSummary")
+                    .and_then(Value::as_str)
+                    .map(str::to_string),
+                payload
+                    .get("beforeFileVersion")
+                    .and_then(Value::as_str)
+                    .map(str::to_string),
+                payload
+                    .get("afterFileVersion")
+                    .and_then(Value::as_str)
+                    .map(str::to_string),
+            ),
+            Err(error) => (
+                false,
+                json!({
+                    "ok": false,
+                    "code": error.code(),
+                    "message": error.message(),
+                }),
+                Some(format!("{}: {}", error.code(), error.message())),
+                None,
+                None,
+                None,
+            ),
+        };
+    let citation_count = payload
+        .get("citations")
+        .and_then(Value::as_array)
+        .map(|items| items.len())
+        .or_else(|| {
+            payload
+                .get("sources")
+                .and_then(Value::as_array)
+                .map(|items| items.len())
+        })
+        .or_else(|| {
+            payload
+                .get("references")
+                .and_then(Value::as_array)
+                .map(|items| items.len())
+        })
+        .unwrap_or(0);
+    let receipt = receipt_for(
+        &context,
+        session.as_ref(),
+        &tool_name,
+        normalized_file_path.clone(),
+        allowed,
+        deny_reason.clone(),
+        diff_summary.clone(),
+        before_file_version.clone(),
+        after_file_version.clone(),
+    );
+    let receipt_payload = write_receipt(&facade.state, receipt, &payload, citation_count);
+    let elapsed_ms = now_ms().saturating_sub(started) as u64;
+    if let Some(session) = session.as_ref() {
+        publish_event(
+            &session.session_id,
+            "tool_call",
+            json!({
+                "toolName": tool_name,
+                "allowed": allowed,
+                "denyReason": deny_reason,
+                "normalizedFilePath": normalized_file_path,
+                "rootUri": payload.get("rootUri").cloned().unwrap_or(Value::Null),
+                "relativePath": payload.get("relativePath").cloned().unwrap_or(Value::Null),
+                "diffSummary": diff_summary,
+                "beforeFileVersion": before_file_version,
+                "afterFileVersion": after_file_version,
+                "citationCount": citation_count,
+                "receipt": receipt_payload,
+                "elapsedMs": elapsed_ms,
+            }),
+        );
+    }
+    Ok(Json(json!({
+        "ok": allowed,
+        "toolName": tool_name,
+        "result": payload,
+        "receipt": receipt_payload,
+        "elapsedMs": elapsed_ms,
+    })))
+}
+
+pub async fn shell(
+    State(state): State,
+    Extension(context): Extension,
+) -> Result {
+    ensure_enabled(&state)?;
+    ensure_authenticated(&state, &context)?;
+    let html = r#"
+
+
+  
+  
+  MNote Pi Lab
+  
+
+
+  

+  
+  
+
+"#;
+    Ok(Html(html).into_response())
+}
+
+pub async fn status(
+    State(state): State,
+    Extension(context): Extension,
+) -> Result, WebError> {
+    if !enabled(&state) {
+        return Ok(Json(json!({
+            "ok": true,
+            "schema": PI_LAB_SCHEMA_STATUS,
+            "enabled": false,
+            "running": false,
+            "uiMode": "independent_mnote_native_drawer",
+            "reason": "Pi Lab disabled by config",
+        })));
+    }
+    cleanup_expired_sessions();
+    let actor_id = ensure_authenticated(&state, &context)?;
+    let sessions = PI_LAB_SESSIONS.lock().ok();
+    let current_session = sessions.as_ref().and_then(|sessions| {
+        sessions
+            .values()
+            .filter(|session| session.mnote_user_id == actor_id)
+            .max_by_key(|session| session.updated_at_ms)
+            .cloned()
+    });
+    let active_session_count = sessions
+        .as_ref()
+        .map(|sessions| {
+            sessions
+                .values()
+                .filter(|session| session.mnote_user_id == actor_id)
+                .count()
+        })
+        .unwrap_or(0);
+    let owned_session_ids = sessions
+        .as_ref()
+        .map(|sessions| {
+            sessions
+                .values()
+                .filter(|session| session.mnote_user_id == actor_id)
+                .map(|session| session.session_id.clone())
+                .collect::>()
+        })
+        .unwrap_or_default();
+    let process_count = PI_LAB_PROCESSES
+        .lock()
+        .map(|processes| {
+            owned_session_ids
+                .iter()
+                .filter(|session_id| processes.contains_key(*session_id))
+                .count()
+        })
+        .unwrap_or(0);
+    Ok(Json(json!({
+        "ok": true,
+        "schema": PI_LAB_SCHEMA_STATUS,
+        "enabled": true,
+        "running": process_count > 0 || current_session.as_ref().is_some_and(|session| session.status == PiLabSessionStatus::RuntimeRunning || session.status == PiLabSessionStatus::TurnRunning),
+        "version": PI_LAB_VERSION,
+        "provider": PI_LAB_PROVIDER,
+        "runtimeMode": runtime_mode(),
+        "defaultModelProvider": default_model_provider(),
+        "defaultModelId": default_model_id(),
+        "omnirouteBaseUrl": omniroute_base_url(),
+        "pid": current_session.as_ref().and_then(|session| session.runtime_pid),
+        "sessionId": current_session.as_ref().map(|session| session.session_id.clone()),
+        "providerSessionId": current_session.as_ref().map(|session| session.provider_session_id.clone()),
+        "session": current_session,
+        "activeSessionCount": active_session_count,
+        "processCount": process_count,
+        "managedPiSessionDirPolicy": "/.mnote/ai/pi-sessions//",
+        "disabledPiBuiltinTools": ["bash", "read", "write", "edit"],
+        "receiptStorage": "provider_neutral_jsonl_adapter_v1",
+        "uiMode": "independent_mnote_native_drawer",
+    })))
+}
+
+pub async fn bootstrap(
+    State(state): State,
+    Extension(context): Extension,
+    Json(request): Json,
+) -> Result, WebError> {
+    ensure_enabled(&state)?;
+    cleanup_expired_sessions();
+    let actor_id = ensure_authenticated(&state, &context)?;
+    check_rate_limit(&actor_id, "start", PI_LAB_MAX_STARTS_PER_WINDOW)?;
+    let start_request = PiLabStartRequest {
+        session_id: None,
+        root_uri: request.root_uri,
+        workspace_id: request.workspace_id,
+        page_path: request.page_path,
+        page_title: request.page_title,
+        model_provider: request.model_provider,
+        model_id: request.model_id,
+    };
+    let requested = session_from_request(&state, &context, &start_request)?;
+    let mut session = requested;
+    session.allowed_roots_snapshot = snapshot_allowed_roots(&state, &context)?;
+    let session = start_runtime_for_session(&state, session).await?;
+    let mut response = json!({
+        "ok": true,
+        "schema": "mnote.page_ai_pi.bootstrap.v1",
+        "sessionId": session.session_id,
+        "providerSessionId": session.provider_session_id,
+        "runtimeMode": session.runtime_mode,
+        "pid": session.runtime_pid,
+        "sessionDir": session.pi_session_dir,
+        "toolCalls": [],
+        "citations": [],
+        "diffSummary": null,
+        "uiMode": "independent_mnote_native_drawer",
+    });
+    if let Some(prompt) = request
+        .prompt
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+    {
+        let send_response = send(
+            State(state),
+            Extension(context),
+            Json(PiLabSendRequest {
+                session_id: response["sessionId"]
+                    .as_str()
+                    .unwrap_or_default()
+                    .to_string(),
+                message: prompt.to_string(),
+                streaming_behavior: None,
+            }),
+        )
+        .await?
+        .0;
+        response["send"] = send_response;
+        response["text"] =
+            json!("Pi Lab 已接收 prompt；真实输出请从 /api/page-ai/pi/events 读取。");
+    }
+    Ok(Json(response))
+}
+
+pub async fn start(
+    State(state): State,
+    Extension(context): Extension,
+    Json(request): Json,
+) -> Result, WebError> {
+    ensure_enabled(&state)?;
+    cleanup_expired_sessions();
+    let actor_id = ensure_authenticated(&state, &context)?;
+    check_rate_limit(&actor_id, "start", PI_LAB_MAX_STARTS_PER_WINDOW)?;
+    let requested_session = session_from_request(&state, &context, &request)?;
+    let mut requested_session = requested_session;
+    requested_session.allowed_roots_snapshot = snapshot_allowed_roots(&state, &context)?;
+    let session = start_runtime_for_session(&state, requested_session).await?;
+    Ok(Json(json!({
+        "ok": true,
+        "schema": "mnote.page_ai_pi.start.v1",
+        "session": session,
+        "disabledPiBuiltinTools": ["bash", "read", "write", "edit"],
+        "mnoteToolOnly": true,
+    })))
+}
+
+pub async fn send(
+    State(state): State,
+    Extension(context): Extension,
+    Json(request): Json,
+) -> Result, WebError> {
+    ensure_enabled(&state)?;
+    cleanup_expired_sessions();
+    ensure_authenticated(&state, &context)?;
+    let session = get_session_for_context(&state, &context, &request.session_id)?;
+    check_rate_limit(&session.mnote_user_id, "send", PI_LAB_MAX_SENDS_PER_WINDOW)?;
+    if request.message.trim().is_empty() {
+        return Err(WebError::bad_request_code(
+            "page_ai_pi_lab_prompt_required",
+            "prompt 不能为空",
+        ));
+    }
+    update_session(&request.session_id, |session| {
+        session.status = PiLabSessionStatus::TurnRunning;
+        session.message_count += 1;
+    });
+    let command = json!({
+        "id": generate_id("pi_rpc"),
+        "type": "prompt",
+        "message": request.message,
+        "streamingBehavior": request.streaming_behavior,
+    });
+    if session.runtime_mode == "mock" {
+        publish_event(
+            &session.session_id,
+            "pi_rpc_event",
+            json!({
+                "type": "message_update",
+                "assistantMessageEvent": {
+                    "type": "text_delta",
+                    "delta": "[Pi Lab mock] prompt accepted"
+                }
+            }),
+        );
+        publish_event(
+            &session.session_id,
+            "pi_rpc_event",
+            json!({
+                "type": "citation",
+                "source": "lightrag-mock",
+                "title": "LightRAG mock citation",
+                "url": "#lightrag-mock-citation",
+            }),
+        );
+        publish_event(
+            &session.session_id,
+            "pi_rpc_event",
+            json!({
+                "type": "diff",
+                "files": [session.page_path.clone().unwrap_or_else(|| "page.md".into())],
+            }),
+        );
+        update_session(&request.session_id, |session| {
+            session.status = PiLabSessionStatus::RuntimeRunning;
+        });
+    } else {
+        if let Err(error) = send_rpc_command(&request.session_id, command).await {
+            update_session(&request.session_id, |session| {
+                session.status = PiLabSessionStatus::Error;
+                session.runtime_error = Some(error.message().to_string());
+            });
+            return Err(error);
+        }
+    }
+    let current = get_session(&request.session_id).unwrap_or(session.clone());
+    persist_upsert_run(&state, ¤t)?;
+    persist_append_event(
+        &state,
+        ¤t,
+        "user_prompt",
+        &json!({"message": request.message}),
+    )?;
+    Ok(Json(json!({
+        "ok": true,
+
+        "schema": "mnote.page_ai_pi.send.v1",
+        "sessionId": request.session_id,
+        "providerSessionId": session.provider_session_id,
+        "accepted": true,
+        "eventStream": "/api/page-ai/pi/events",
+    })))
+}
+
+pub async fn abort(
+    State(state): State,
+    Extension(context): Extension,
+    Json(request): Json,
+) -> Result, WebError> {
+    ensure_enabled(&state)?;
+    cleanup_expired_sessions();
+    ensure_authenticated(&state, &context)?;
+    let session = get_session_for_context(&state, &context, &request.session_id)?;
+    if session.runtime_mode != "mock" {
+        let _ = send_rpc_command(&request.session_id, json!({"type": "abort"})).await;
+        let handle = PI_LAB_PROCESSES
+            .lock()
+            .ok()
+            .and_then(|processes| processes.get(&request.session_id).cloned());
+        if let Some(handle) = handle {
+            let _ = handle.child.lock().await.kill().await;
+            if let Ok(mut processes) = PI_LAB_PROCESSES.lock() {
+                processes.remove(&request.session_id);
+            }
+        }
+    }
+    update_session(&request.session_id, |session| {
+        session.status = PiLabSessionStatus::Aborted;
+    });
+    publish_event(&request.session_id, "runtime_aborted", json!({}));
+    // 持久化 abort 状态到 DB
+    if let Some(current) = get_session(&request.session_id) {
+        if let Err(e) = persist_upsert_run(&state, ¤t) {
+            // abort 已执行，DB 写失败仅记录日志，不影响 abort 返回
+            publish_event(
+                &request.session_id,
+                "runtime_persistence_error",
+                json!({
+                    "error": e.message(),
+                    "context": "abort_persist",
+                }),
+            );
+        }
+    }
+
+    Ok(Json(json!({
+        "ok": true,
+        "schema": "mnote.page_ai_pi.abort.v1",
+        "sessionId": request.session_id,
+        "providerSessionId": session.provider_session_id,
+        "aborted": true,
+    })))
+}
+
+pub async fn events(
+    State(state): State,
+    Extension(context): Extension,
+    Query(query): Query,
+) -> Result>>, WebError> {
+    ensure_enabled(&state)?;
+    cleanup_expired_sessions();
+    ensure_authenticated(&state, &context)?;
+    let session_filter = if let Some(session_id) = query.session_id {
+        let session = get_session_for_context(&state, &context, &session_id)?;
+        Some(session.session_id)
+    } else {
+        None
+    };
+    let rx = PI_LAB_EVENT_TX.subscribe();
+    let hello = stream::once(async {
+        Ok(SseEvent::default().event("connected").data(
+            json!({
+                "schema": PI_LAB_SCHEMA_EVENT,
+                "kind": "connected",
+                "version": PI_LAB_VERSION,
+            })
+            .to_string(),
+        ))
+    });
+    let stream = BroadcastStream::new(rx).filter_map(move |event| {
+        let session_filter = session_filter.clone();
+        async move {
+            let Ok(value) = event else {
+                return None;
+            };
+            if let Some(filter) = session_filter.as_deref() {
+                if value.get("sessionId").and_then(Value::as_str) != Some(filter) {
+                    return None;
+                }
+            }
+            let event_name = value
+                .get("kind")
+                .and_then(Value::as_str)
+                .unwrap_or("message");
+            Some(Ok(SseEvent::default()
+                .event(event_name)
+                .data(value.to_string())))
+        }
+    });
+    Ok(Sse::new(hello.chain(stream)).keep_alive(
+        KeepAlive::new()
+            .interval(Duration::from_secs(30))
+            .text("keepalive"),
+    ))
+}
+
+pub async fn tool_call(
+    State(state): State,
+    Extension(context): Extension,
+    Json(request): Json,
+) -> Result, WebError> {
+    ensure_enabled(&state)?;
+    cleanup_expired_sessions();
+    execute_tool(
+        state,
+        context,
+        request.session_id,
+        request.tool_name,
+        request.params,
+    )
+    .await
+}
+
+pub async fn tool_call_bridge(
+    State(state): State,
+    Extension(context): Extension,
+    headers: HeaderMap,
+    Json(request): Json,
+) -> Result, WebError> {
+    ensure_enabled(&state)?;
+    cleanup_expired_sessions();
+    let session_id = request.session_id.clone().ok_or_else(|| {
+        WebError::bad_request_code(
+            "page_ai_pi_lab_bridge_session_required",
+            "Pi Lab tool bridge 缺少 sessionId",
+        )
+    })?;
+    let session = get_session_for_bridge(&headers, &session_id)?;
+    let context = context_for_session(context, &session);
+    execute_tool(
+        state,
+        context,
+        Some(session_id),
+        request.tool_name,
+        request.params,
+    )
+    .await
+}
+
+fn snapshot_allowed_roots(
+    state: &AppState,
+    context: &RequestContext,
+) -> Result, WebError> {
+    match active_allowed_roots(state, context) {
+        Ok(roots) => Ok(Some(json!({
+            "roots": roots.iter().map(|root| json!({
+                "rootUri": root.root_uri,
+                "rootPath": root.root_path,
+                "workspaceId": root.workspace_id,
+                "permission": root.permission,
+                "source": root.source,
+            })).collect::>(),
+            "capturedAtMs": now_ms(),
+        }))),
+        Err(_) => Ok(None),
+    }
+}
+// ---------------------------------------------------------------------------
+// DB persistence helpers
+// ---------------------------------------------------------------------------
+
+fn pi_run_id(session_id: &str) -> String {
+    format!("pi_run_{session_id}")
+}
+
+fn session_status_to_string(status: &PiLabSessionStatus) -> &'static str {
+    match status {
+        PiLabSessionStatus::Idle => "idle",
+        PiLabSessionStatus::RuntimeRunning => "runtime_running",
+        PiLabSessionStatus::TurnRunning => "turn_running",
+        PiLabSessionStatus::Aborted => "aborted",
+        PiLabSessionStatus::Error => "error",
+    }
+}
+
+fn build_run_runtime_json(session: &PiLabSession) -> String {
+    serde_json::to_string(&json!({
+        "providerSessionId": session.provider_session_id,
+        "piSessionDir": session.pi_session_dir,
+        "runtimeMode": session.runtime_mode,
+        "modelProvider": session.model_provider,
+        "modelId": session.model_id,
+        "messageCount": session.message_count,
+        "pagePath": session.page_path,
+        "pageTitle": session.page_title,
+        "rootUri": session.root_uri,
+        "workspaceId": session.workspace_id,
+        "allowedRootsSnapshot": session.allowed_roots_snapshot,
+    }))
+    .unwrap_or_default()
+}
+
+fn build_upsert_run_input(session: &PiLabSession) -> UpsertAiRuntimeRunInput {
+    UpsertAiRuntimeRunInput {
+        id: None,
+        user_id: session.mnote_user_id.clone(),
+        workspace_id: session.workspace_id.clone(),
+        document_id: session.page_path.clone(),
+        session_id: session.session_id.clone(),
+        run_id: pi_run_id(&session.session_id),
+        title: session.page_title.clone(),
+        profile: PI_LAB_PROFILE.to_string(),
+        acp_runtime: PI_LAB_ACP_RUNTIME.to_string(),
+        trace_id: None,
+        status: session_status_to_string(&session.status).to_string(),
+        runtime_json: build_run_runtime_json(session),
+        payload_json: "{}".to_string(),
+    }
+}
+
+fn persist_upsert_run(state: &AppState, session: &PiLabSession) -> Result<(), WebError> {
+    let input = build_upsert_run_input(session);
+    state
+        .control_plane()
+        .upsert_ai_runtime_run(input)
+        .map_err(|e| WebError::internal(format!("持久化 Pi Lab run 失败: {e}")))?;
+    Ok(())
+}
+
+fn build_append_event_input(
+    session: &PiLabSession,
+    event_type: &str,
+    payload_json: &str,
+) -> AppendAiRuntimeEventInput {
+    AppendAiRuntimeEventInput {
+        id: None,
+        user_id: session.mnote_user_id.clone(),
+        workspace_id: session.workspace_id.clone(),
+        document_id: session.page_path.clone(),
+        session_id: session.session_id.clone(),
+        run_id: pi_run_id(&session.session_id),
+        profile: PI_LAB_PROFILE.to_string(),
+        acp_runtime: PI_LAB_ACP_RUNTIME.to_string(),
+        event_type: event_type.to_string(),
+        payload_json: payload_json.to_string(),
+    }
+}
+
+fn persist_append_event(
+    state: &AppState,
+    session: &PiLabSession,
+    event_type: &str,
+    payload: &Value,
+) -> Result<(), WebError> {
+    let payload_json = serde_json::to_string(payload).unwrap_or_else(|_| "{}".into());
+    let input = build_append_event_input(session, event_type, &payload_json);
+    state
+        .control_plane()
+        .append_ai_runtime_event(input)
+        .map_err(|e| WebError::internal(format!("持久化 Pi Lab event 失败: {e}")))?;
+    Ok(())
+}
+
+// ---------------------------------------------------------------------------
+// Session history handlers
+// ---------------------------------------------------------------------------
+
+pub async fn list_sessions(
+    State(state): State,
+    Extension(context): Extension,
+    Query(query): Query,
+) -> Result, WebError> {
+    if !enabled(&state) {
+        return Ok(Json(json!({"ok": true, "sessions": []})));
+    }
+    let user_id = ensure_authenticated(&state, &context)?;
+    let limit = query.limit.unwrap_or(20).min(100);
+    let runs = state
+        .control_plane()
+        .list_ai_runtime_runs(&user_id, query.workspace_id.as_deref(), None, None, limit)
+        .map_err(|e| WebError::internal(format!("查询 session 历史失败: {e}")))?;
+
+    // Filter to Pi Lab runs in-memory (the store list method doesn't support profile/acp_runtime filter)
+    let pi_runs: Vec = runs
+        .into_iter()
+        .filter(|r| r.profile == PI_LAB_PROFILE && r.acp_runtime == PI_LAB_ACP_RUNTIME)
+        .map(|r| {
+            let runtime: Value = serde_json::from_str(&r.runtime_json).unwrap_or(json!({}));
+            let preview = runtime
+                .get("pageTitle")
+                .and_then(Value::as_str)
+                .map(str::to_string)
+                .or_else(|| r.title.clone())
+                .unwrap_or_default();
+            json!({
+                "sessionId": r.session_id,
+                "runId": r.run_id,
+                "profile": r.profile,
+                "acpRuntime": r.acp_runtime,
+                "status": r.status,
+                "title": r.title,
+                "preview": preview,
+                "messageCount": runtime.get("messageCount").unwrap_or(&json!(0)),
+                "pagePath": runtime.get("pagePath"),
+                "pageTitle": runtime.get("pageTitle"),
+                "modelProvider": runtime.get("modelProvider"),
+                "modelId": runtime.get("modelId"),
+                "createdAt": r.created_at,
+                "updatedAt": r.updated_at,
+            })
+        })
+        .collect();
+
+    Ok(Json(json!({
+        "ok": true,
+        "schema": "mnote.page_ai_pi.list_sessions.v1",
+        "sessions": pi_runs,
+        "count": pi_runs.len(),
+    })))
+}
+
+pub async fn get_session_history(
+    State(state): State,
+    Extension(context): Extension,
+    axum::extract::Path(path): axum::extract::Path,
+) -> Result, WebError> {
+    if !enabled(&state) {
+        return Err(WebError::new(
+            StatusCode::NOT_FOUND,
+            "page_ai_pi_lab_disabled",
+            "Pi Lab 已被 MNOTE_PAGE_AI_PI_LAB=0 强制关闭",
+        ));
+    }
+    let user_id = ensure_authenticated(&state, &context)?;
+    let run_id = pi_run_id(&path.session_id);
+    let run = state
+        .control_plane()
+        .find_ai_runtime_run(&user_id, &run_id)
+        .map_err(|e| WebError::internal(format!("查询 session 详情失败: {e}")))?
+        .ok_or_else(|| {
+            WebError::new(
+                StatusCode::NOT_FOUND,
+                "page_ai_pi_lab_session_not_found",
+                "Pi Lab session 不存在或不属于当前用户",
+            )
+        })?;
+
+    if run.profile != PI_LAB_PROFILE || run.acp_runtime != PI_LAB_ACP_RUNTIME {
+        return Err(WebError::new(
+            StatusCode::NOT_FOUND,
+            "page_ai_pi_lab_session_not_found",
+            "Pi Lab session 不存在或不属于当前用户",
+        ));
+    }
+
+    let runtime: Value = serde_json::from_str(&run.runtime_json).unwrap_or(json!({}));
+    let payload: Value = serde_json::from_str(&run.payload_json).unwrap_or(json!({}));
+
+    Ok(Json(json!({
+        "ok": true,
+        "schema": "mnote.page_ai_pi.get_session.v1",
+        "session": {
+            "id": run.id,
+            "sessionId": run.session_id,
+            "runId": run.run_id,
+            "userId": run.user_id,
+            "workspaceId": run.workspace_id,
+            "documentId": run.document_id,
+            "title": run.title,
+            "profile": run.profile,
+            "acpRuntime": run.acp_runtime,
+            "status": run.status,
+            "traceId": run.trace_id,
+            "runtime": runtime,
+            "payload": payload,
+            "createdAt": run.created_at,
+            "updatedAt": run.updated_at,
+        }
+    })))
+}
+
+pub async fn get_session_events(
+    State(state): State,
+    Extension(context): Extension,
+    axum::extract::Path(path): axum::extract::Path,
+    Query(query): Query,
+) -> Result, WebError> {
+    if !enabled(&state) {
+        return Err(WebError::new(
+            StatusCode::NOT_FOUND,
+            "page_ai_pi_lab_disabled",
+            "Pi Lab 已被 MNOTE_PAGE_AI_PI_LAB=0 强制关闭",
+        ));
+    }
+    let user_id = ensure_authenticated(&state, &context)?;
+    let run_id = pi_run_id(&path.session_id);
+    let limit = query.limit.unwrap_or(200).min(1000);
+
+    // Verify the run exists and belongs to the user
+    let run = state
+        .control_plane()
+        .find_ai_runtime_run(&user_id, &run_id)
+        .map_err(|e| WebError::internal(format!("查询 session 详情失败: {e}")))?
+        .ok_or_else(|| {
+            WebError::new(
+                StatusCode::NOT_FOUND,
+                "page_ai_pi_lab_session_not_found",
+                "Pi Lab session 不存在或不属于当前用户",
+            )
+        })?;
+
+    if run.profile != PI_LAB_PROFILE || run.acp_runtime != PI_LAB_ACP_RUNTIME {
+        return Err(WebError::new(
+            StatusCode::NOT_FOUND,
+            "page_ai_pi_lab_session_not_found",
+            "Pi Lab session 不存在或不属于当前用户",
+        ));
+    }
+
+    let events = state
+        .control_plane()
+        .list_ai_runtime_events(&user_id, &run_id, limit)
+        .map_err(|e| WebError::internal(format!("查询 session events 失败: {e}")))?;
+
+    let event_values: Vec = events
+        .into_iter()
+        .map(|e| {
+            let payload: Value = serde_json::from_str(&e.payload_json).unwrap_or(json!({}));
+            json!({
+                "id": e.id,
+                "eventType": e.event_type,
+                "profile": e.profile,
+                "acpRuntime": e.acp_runtime,
+                "payload": payload,
+                "createdAt": e.created_at,
+            })
+        })
+        .collect();
+
+    Ok(Json(json!({
+        "ok": true,
+        "schema": "mnote.page_ai_pi.get_session_events.v1",
+        "sessionId": path.session_id,
+        "runId": run_id,
+        "events": event_values,
+        "count": event_values.len(),
+    })))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::app::{build_app, AppConfig, AppState};
+    use axum::body::{to_bytes, Body};
+    use axum::http::{Request, StatusCode};
+    use tower::util::ServiceExt;
+
+    fn test_app() -> axum::Router {
+        build_app(AppState::new(AppConfig {
+            service_name: "mnote-web".into(),
+            service_version: "test".into(),
+            bind_addr: "127.0.0.1:0".into(),
+            public_bind_addr: "127.0.0.1:3000".into(),
+            legacy_next_base_url: None,
+            enable_legacy_next_compat: false,
+            enable_debug_shell_routes: false,
+            enable_editor_actor: true,
+            enable_page_ai_pi_lab: true,
+            hermes_base_path: "/api/hermes".into(),
+            compat_next_base_path: "/api/compat/next".into(),
+            convex_url: None,
+            convex_admin_key: None,
+            allow_dev_fixtures: true,
+            query_fixtures_json: None,
+            mutation_fixtures_json: None,
+            dev_user_id: "dev-user".into(),
+            dev_user_name: "开发用户".into(),
+            dev_user_email: "dev@mnote.local".into(),
+        }))
+    }
+
+    #[test]
+    fn pi_run_id_format() {
+        let rid = pi_run_id("pi_lab_abc123");
+        assert_eq!(rid, "pi_run_pi_lab_abc123");
+    }
+
+    #[test]
+    fn session_status_to_string_maps_all_variants() {
+        assert_eq!(session_status_to_string(&PiLabSessionStatus::Idle), "idle");
+        assert_eq!(
+            session_status_to_string(&PiLabSessionStatus::RuntimeRunning),
+            "runtime_running"
+        );
+        assert_eq!(
+            session_status_to_string(&PiLabSessionStatus::TurnRunning),
+            "turn_running"
+        );
+        assert_eq!(
+            session_status_to_string(&PiLabSessionStatus::Aborted),
+            "aborted"
+        );
+        assert_eq!(
+            session_status_to_string(&PiLabSessionStatus::Error),
+            "error"
+        );
+    }
+
+    #[test]
+    fn build_upsert_run_input_creates_correct_input() {
+        let session = PiLabSession {
+            session_id: "pi_lab_test123".into(),
+            mnote_user_id: "user_test".into(),
+            bridge_token: "bridge".into(),
+            status: PiLabSessionStatus::RuntimeRunning,
+            provider_session_id: "prov_123".into(),
+            pi_session_dir: "/tmp/pi-lab/test".into(),
+            pi_session_file: None,
+            root_uri: Some("file:///workspace".into()),
+            workspace_id: Some("ws_test".into()),
+            page_path: Some("doc.md".into()),
+            page_title: Some("Test Page".into()),
+            model_provider: Some("omniroute".into()),
+            model_id: Some("freefirst".into()),
+            allowed_roots_snapshot: None,
+            runtime_pid: Some(12345),
+            runtime_mode: "mock".into(),
+            runtime_error: None,
+            created_at_ms: 1000,
+            updated_at_ms: 2000,
+            message_count: 5,
+        };
+        let input = build_upsert_run_input(&session);
+        assert_eq!(input.user_id, "user_test");
+        assert_eq!(input.run_id, "pi_run_pi_lab_test123");
+        assert_eq!(input.session_id, "pi_lab_test123");
+        assert_eq!(input.profile, "pi_lab");
+        assert_eq!(input.acp_runtime, "pi");
+        assert_eq!(input.status, "runtime_running");
+        assert_eq!(input.title.as_deref(), Some("Test Page"));
+        assert_eq!(input.workspace_id.as_deref(), Some("ws_test"));
+        assert_eq!(input.document_id.as_deref(), Some("doc.md"));
+        let runtime: Value = serde_json::from_str(&input.runtime_json).unwrap();
+        assert_eq!(runtime["messageCount"], 5);
+        assert_eq!(runtime["modelProvider"], "omniroute");
+    }
+
+    #[test]
+    fn build_append_event_input_creates_correct_input() {
+        let session = PiLabSession {
+            session_id: "pi_lab_test456".into(),
+            mnote_user_id: "user_test".into(),
+            bridge_token: "bridge".into(),
+            status: PiLabSessionStatus::RuntimeRunning,
+            provider_session_id: "prov_456".into(),
+            pi_session_dir: "/tmp/pi-lab/test".into(),
+            pi_session_file: None,
+            root_uri: None,
+            workspace_id: None,
+            page_path: None,
+            page_title: None,
+            model_provider: None,
+            model_id: None,
+            allowed_roots_snapshot: None,
+            runtime_pid: None,
+            runtime_mode: "mock".into(),
+            runtime_error: None,
+            created_at_ms: 1000,
+            updated_at_ms: 2000,
+            message_count: 0,
+        };
+        let payload = json!({"type": "text_delta", "delta": "hello"});
+        let input = build_append_event_input(
+            &session,
+            "pi_rpc_event",
+            &serde_json::to_string(&payload).unwrap(),
+        );
+        assert_eq!(input.user_id, "user_test");
+        assert_eq!(input.session_id, "pi_lab_test456");
+        assert_eq!(input.run_id, "pi_run_pi_lab_test456");
+        assert_eq!(input.event_type, "pi_rpc_event");
+        let parsed: Value = serde_json::from_str(&input.payload_json).unwrap();
+        assert_eq!(parsed["delta"], "hello");
+    }
+
+    #[tokio::test]
+    async fn list_sessions_filters_by_current_user_and_pi_profile() {
+        let app = test_app();
+        let response = app
+            .oneshot(
+                Request::builder()
+                    .method("GET")
+                    .uri("/api/page-ai/pi/sessions")
+                    .header("x-mnote-actor-id", "user_test_list")
+                    .header("x-mnote-actor-type", "user")
+                    .body(Body::empty())
+                    .expect("request"),
+            )
+            .await
+            .expect("response");
+
+        assert_eq!(response.status(), StatusCode::OK);
+        let body = to_bytes(response.into_body(), usize::MAX)
+            .await
+            .expect("body");
+        let payload: Value = serde_json::from_slice(&body).expect("json");
+        assert_eq!(payload["ok"], true);
+        assert_eq!(payload["schema"], "mnote.page_ai_pi.list_sessions.v1");
+        // Should be an empty list since no Pi sessions exist for this user
+        assert!(payload["sessions"].is_array());
+        assert_eq!(payload["count"].as_u64().unwrap_or(0), 0);
+    }
+
+    #[tokio::test]
+    async fn get_session_returns_not_found_for_nonexistent_session() {
+        let app = test_app();
+        let response = app
+            .oneshot(
+                Request::builder()
+                    .method("GET")
+                    .uri("/api/page-ai/pi/sessions/nonexistent_session_id")
+                    .header("x-mnote-actor-id", "user_test_get")
+                    .header("x-mnote-actor-type", "user")
+                    .body(Body::empty())
+                    .expect("request"),
+            )
+            .await
+            .expect("response");
+
+        assert_eq!(response.status(), StatusCode::NOT_FOUND);
+        let body = to_bytes(response.into_body(), usize::MAX)
+            .await
+            .expect("body");
+        let payload: Value = serde_json::from_slice(&body).expect("json");
+        assert_eq!(payload["code"], "page_ai_pi_lab_session_not_found");
+    }
+
+    #[tokio::test]
+    async fn get_session_events_returns_not_found_for_nonexistent_session() {
+        let app = test_app();
+        let response = app
+            .oneshot(
+                Request::builder()
+                    .method("GET")
+                    .uri("/api/page-ai/pi/sessions/nonexistent_session_id/events")
+                    .header("x-mnote-actor-id", "user_test_events")
+                    .header("x-mnote-actor-type", "user")
+                    .body(Body::empty())
+                    .expect("request"),
+            )
+            .await
+            .expect("response");
+
+        assert_eq!(response.status(), StatusCode::NOT_FOUND);
+        let body = to_bytes(response.into_body(), usize::MAX)
+            .await
+            .expect("body");
+        let payload: Value = serde_json::from_slice(&body).expect("json");
+        assert_eq!(payload["code"], "page_ai_pi_lab_session_not_found");
+    }
+}
diff --git a/rust/crates/mnote-web/src/routes/page_ai_workflow.rs b/rust/crates/mnote-web/src/routes/page_ai_workflow.rs
index 8ef9e883..186e30f3 100644
--- a/rust/crates/mnote-web/src/routes/page_ai_workflow.rs
+++ b/rust/crates/mnote-web/src/routes/page_ai_workflow.rs
@@ -611,6 +611,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/resource_trash.rs b/rust/crates/mnote-web/src/routes/resource_trash.rs
index 909b1228..d6cabb43 100644
--- a/rust/crates/mnote-web/src/routes/resource_trash.rs
+++ b/rust/crates/mnote-web/src/routes/resource_trash.rs
@@ -1163,6 +1163,7 @@ mod tests {
             enable_legacy_next_compat: false,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/search.rs b/rust/crates/mnote-web/src/routes/search.rs
index 2568f8f4..44bdd5e0 100644
--- a/rust/crates/mnote-web/src/routes/search.rs
+++ b/rust/crates/mnote-web/src/routes/search.rs
@@ -776,6 +776,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -906,6 +907,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -1517,6 +1519,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/session.rs b/rust/crates/mnote-web/src/routes/session.rs
index bf0ad06a..3ab4c4a0 100644
--- a/rust/crates/mnote-web/src/routes/session.rs
+++ b/rust/crates/mnote-web/src/routes/session.rs
@@ -229,6 +229,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -331,6 +332,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -400,6 +402,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -480,6 +483,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/sse.rs b/rust/crates/mnote-web/src/routes/sse.rs
index 0efd76ac..413f9bd3 100644
--- a/rust/crates/mnote-web/src/routes/sse.rs
+++ b/rust/crates/mnote-web/src/routes/sse.rs
@@ -358,6 +358,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/tree.rs b/rust/crates/mnote-web/src/routes/tree.rs
index 8f33b16e..608f8515 100644
--- a/rust/crates/mnote-web/src/routes/tree.rs
+++ b/rust/crates/mnote-web/src/routes/tree.rs
@@ -2656,6 +2656,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: true,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -3001,6 +3002,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: true,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -3682,6 +3684,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: true,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/routes/web_shell.rs b/rust/crates/mnote-web/src/routes/web_shell.rs
index 72a49f78..02ee8753 100644
--- a/rust/crates/mnote-web/src/routes/web_shell.rs
+++ b/rust/crates/mnote-web/src/routes/web_shell.rs
@@ -298,6 +298,8 @@ pub async fn document_page_shell(
         secondary_requested,
         secondary_invalid,
     );
+    let pi_lab_loader_script =
+        render_page_ai_pi_lab_loader_script(state.config().enable_page_ai_pi_lab);
     let body_content = crate::ssr::render_view(leptos::view! {
         
 "#,
         escape_html(title),
@@ -368,6 +371,7 @@ pub async fn document_page_shell(
             r#""#,
             mnote_browser_runtime_src("document-conflict-panel-runtime.js")
         ),
+        pi_lab_loader_script,
     );
     let mut response = Html(html).into_response();
     stamp_shell_headers(response.headers_mut(), "document");
@@ -850,6 +854,23 @@ pub(crate) fn render_editor_island_adapter_script() -> String {
     )
 }
 
+pub(crate) fn render_page_ai_pi_lab_loader_script(enabled: bool) -> String {
+    if !enabled {
+        return String::new();
+    }
+    format!(
+        r#""#,
+        mnote_browser_runtime_src("sidebar-page-ai-pi-lab-runtime.js")
+    )
+}
+
 fn leptos_tiptap_runtime_src(asset: &str) -> String {
     let base = format!("/api/leptos-tiptap-runtime/{asset}");
     if let Some(cache_buster) = crate::routes::dev_hot::dev_hot_cache_buster() {
@@ -2591,6 +2612,20 @@ pub async fn sidebar_page_ai_target_runtime_asset() -> Response {
         .unwrap_or_else(|_| Response::new(Body::empty()))
 }
 
+pub async fn sidebar_page_ai_pi_lab_runtime_asset() -> Response {
+    const JS: &str = include_str!("../../browser/sidebar-page-ai-pi-lab-runtime.js");
+    Response::builder()
+        .status(StatusCode::OK)
+        .header(
+            header::CONTENT_TYPE,
+            "application/javascript; charset=utf-8",
+        )
+        .header(header::CACHE_CONTROL, runtime_asset_cache_control())
+        .header(HEADER_MNOTE_WEB_OWNER, "mnote-web")
+        .body(browser_runtime_js_body(JS))
+        .unwrap_or_else(|_| Response::new(Body::empty()))
+}
+
 pub async fn sidebar_page_settings_runtime_asset() -> Response {
     const JS: &str = include_str!("../../browser/sidebar-page-settings-runtime.js");
     Response::builder()
@@ -3669,6 +3704,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -3726,6 +3762,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -3847,6 +3884,7 @@ mod tests {
             enable_legacy_next_compat: false,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: Some("http://127.0.0.1:9".into()),
@@ -3989,6 +4027,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -4729,6 +4768,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -4797,6 +4837,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -4935,7 +4976,8 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn local_folder_page_aggregate_prefers_control_plane_ui_preference_over_default_title_header() {
+    async fn local_folder_page_aggregate_prefers_control_plane_ui_preference_over_default_title_header(
+    ) {
         let root = std::env::temp_dir().join(format!(
             "mnote-local-page-aggregate-ui-pref-{}",
             std::process::id()
@@ -4954,6 +4996,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
@@ -5499,6 +5542,7 @@ mod tests {
             enable_legacy_next_compat: true,
             enable_debug_shell_routes: false,
             enable_editor_actor: true,
+            enable_page_ai_pi_lab: false,
             hermes_base_path: "/api/hermes".into(),
             compat_next_base_path: "/api/compat/next".into(),
             convex_url: None,
diff --git a/rust/crates/mnote-web/src/ssr/pages/ai_admin.rs b/rust/crates/mnote-web/src/ssr/pages/ai_admin.rs
new file mode 100644
index 00000000..f01e660f
--- /dev/null
+++ b/rust/crates/mnote-web/src/ssr/pages/ai_admin.rs
@@ -0,0 +1,2738 @@
+//! MNOTE AI 管理页面组件
+//!
+//! 可供 /admin/ai 和 /user/ai 使用的 Leptos SSR 管理页面。
+//! 包含 Overview、Models、Tools、Skills/MCP、Access Scopes 等面板。
+//! 用户模式下隐藏管理写操作。写管理使用 GET/PUT /api/ai-admin/settings。
+//! 模型/工具/技能面板通过 JS 渲染内联编辑表单，保存后 PUT 全量配置。
+
+use leptos::prelude::*;
+
+/// AI 管理页面内嵌 scoped 样式
+const AI_ADMIN_STYLE: &str = r#"
+.mnote-ai-admin {
+  min-height: 100vh;
+  background: #f5f7fa;
+  color: #1f1f1f;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+}
+.mnote-ai-admin-mobile-trigger {
+  display: none;
+  position: fixed;
+  top: 16px;
+  left: 16px;
+  z-index: 1001;
+  width: 34px;
+  height: 34px;
+  border: 1px solid #d9d9d9;
+  border-radius: 6px;
+  background: #ffffff;
+  color: #1890ff;
+  box-shadow: 0 2px 8px rgba(0,0,0,0.08);
+  cursor: pointer;
+}
+.mnote-ai-admin-shell {
+  display: grid;
+  grid-template-columns: 200px minmax(0, 1fr);
+  min-height: 100vh;
+}
+.mnote-ai-admin-sider {
+  position: sticky;
+  top: 0;
+  height: 100vh;
+  overflow: auto;
+  background: #ffffff;
+  border-right: 1px solid #f0f0f0;
+}
+.mnote-ai-admin-brand {
+  padding: 20px 16px 12px;
+  border-bottom: 1px solid #f0f0f0;
+}
+.mnote-ai-admin-brand-title {
+  margin: 0;
+  color: #1890ff;
+  font-size: 16px;
+  font-weight: 650;
+  line-height: 1.2;
+}
+.mnote-ai-admin-brand-subtitle {
+  display: block;
+  margin-top: 3px;
+  color: #8c8c8c;
+  font-size: 11px;
+}
+.mnote-ai-admin-nav {
+  padding: 8px 0;
+}
+.mnote-ai-admin-nav-title {
+  padding: 10px 16px 6px;
+  color: #bfbfbf;
+  font-size: 11px;
+  font-weight: 600;
+}
+.mnote-ai-admin-nav a {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  height: 40px;
+  padding: 0 16px 0 24px;
+  color: rgba(0,0,0,0.78);
+  font-size: 14px;
+  text-decoration: none;
+}
+.mnote-ai-admin-nav a::before {
+  width: 16px;
+  color: #8c8c8c;
+  font-size: 15px;
+  text-align: center;
+}
+.mnote-ai-admin-nav a[data-nav-icon="home"]::before { content: "⌂"; }
+.mnote-ai-admin-nav a[data-nav-icon="users"]::before { content: "👤"; }
+.mnote-ai-admin-nav a[data-nav-icon="models"]::before { content: "⚙"; }
+.mnote-ai-admin-nav a[data-nav-icon="service"]::before { content: "☁"; }
+.mnote-ai-admin-nav a[data-nav-icon="stats"]::before { content: "▦"; }
+.mnote-ai-admin-nav a[data-nav-icon="tools"]::before { content: "🛡"; }
+.mnote-ai-admin-nav a[data-nav-icon="skills"]::before { content: "⚡"; }
+.mnote-ai-admin-nav a[data-nav-icon="folder"]::before { content: "📁"; }
+.mnote-ai-admin-nav a[data-nav-icon="db"]::before { content: "▣"; }
+.mnote-ai-admin-nav a[data-nav-icon="channel"]::before { content: "◇"; }
+.mnote-ai-admin-nav a[data-nav-icon="monitor"]::before { content: "◉"; }
+.mnote-ai-admin-nav a:hover {
+  color: #1890ff;
+  background: #e6f7ff;
+}
+.mnote-ai-admin-nav a.is-active {
+  color: #1890ff;
+  background: #e6f7ff;
+  font-weight: 500;
+}
+.mnote-ai-admin-nav a.is-active::after {
+  content: "";
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: 3px;
+  background: #1890ff;
+}
+.mnote-ai-admin-sider-footer {
+  position: sticky;
+  bottom: 0;
+  padding: 12px 16px;
+  border-top: 1px solid #f0f0f0;
+  background: #ffffff;
+}
+.mnote-ai-admin-content {
+  min-width: 0;
+  padding: 24px 32px;
+}
+.mnote-ai-admin-breadcrumb {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 16px;
+  color: rgba(0,0,0,0.45);
+  font-size: 14px;
+}
+.mnote-ai-admin-breadcrumb a {
+  color: rgba(0,0,0,0.45);
+  text-decoration: none;
+}
+.mnote-ai-admin-breadcrumb a:hover {
+  color: #1890ff;
+}
+.mnote-ai-admin-card-shell {
+  border: 1px solid #f0f0f0;
+  border-radius: 8px;
+  background: #ffffff;
+  box-shadow: 0 1px 2px rgba(0,0,0,0.02);
+}
+.mnote-ai-admin-header {
+  padding: 24px 24px 0;
+  margin-bottom: 0;
+}
+.mnote-ai-admin-header h1 {
+  margin: 0 0 4px;
+  color: rgba(0,0,0,0.88);
+  font-size: 20px;
+  font-weight: 650;
+  line-height: 1.25;
+}
+.mnote-ai-admin-header p {
+  margin: 0;
+  color: rgba(0,0,0,0.45);
+  font-size: 13px;
+}
+.mnote-ai-admin-section {
+  display: none;
+  padding: 24px;
+}
+.mnote-ai-admin-section.is-active {
+  display: block;
+}
+.mnote-ai-admin-panel {
+  display: none;
+}
+.mnote-ai-admin-panel.is-active {
+  display: block;
+}
+.mnote-ai-admin-section-header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 16px;
+  margin-bottom: 16px;
+}
+.mnote-ai-admin-section-header h2 {
+  margin: 0;
+  color: rgba(0,0,0,0.88);
+  font-size: 18px;
+  font-weight: 650;
+  line-height: 1.35;
+}
+.mnote-ai-admin-section-header .mnote-ai-admin-section-desc {
+  margin: 4px 0 0;
+  color: rgba(0,0,0,0.45);
+  font-size: 13px;
+}
+.mnote-ai-admin-section-body {
+  min-width: 0;
+}
+.mnote-ai-admin-grid,
+.mnote-ai-admin-subgrid,
+.mnote-ai-admin-stat-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
+  gap: 12px;
+}
+.mnote-ai-admin-card,
+.mnote-ai-admin-mini-panel,
+.mnote-ai-admin-stat-card {
+  border: 1px solid #f0f0f0;
+  border-radius: 8px;
+  background: #ffffff;
+  padding: 12px 16px;
+}
+.mnote-ai-admin-card {
+  min-height: 78px;
+}
+.mnote-ai-admin-card-label,
+.mnote-ai-admin-mini-desc,
+.mnote-ai-admin-card-desc {
+  color: rgba(0,0,0,0.45);
+  font-size: 12px;
+}
+.mnote-ai-admin-card-value {
+  display: block;
+  margin: 6px 0 3px;
+  color: rgba(0,0,0,0.88);
+  font-size: 24px;
+  font-weight: 650;
+  line-height: 1.1;
+}
+.mnote-ai-admin-mini-title {
+  margin: 0 0 6px;
+  color: rgba(0,0,0,0.88);
+  font-size: 14px;
+  font-weight: 600;
+}
+.mnote-ai-admin-card-title-row,
+.mnote-ai-admin-card-meta-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  margin-bottom: 10px;
+}
+.mnote-ai-admin-card-title-row {
+  color: rgba(0,0,0,0.88);
+  font-size: 14px;
+  font-weight: 600;
+}
+.mnote-ai-admin-card-meta-row {
+  margin: 8px 0 0;
+  color: rgba(0,0,0,0.45);
+  font-size: 12px;
+}
+.mnote-ai-admin-admin-list,
+.mnote-ai-admin-stack {
+  display: grid;
+  gap: 12px;
+}
+.mnote-ai-admin-admin-card {
+  border: 1px solid #f0f0f0;
+  border-radius: 8px;
+  background: #ffffff;
+}
+.mnote-ai-admin-admin-card-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 12px 16px;
+  border-bottom: 1px solid #f0f0f0;
+  background: #fafafa;
+}
+.mnote-ai-admin-admin-card-body {
+  padding: 14px 16px 16px;
+}
+.mnote-ai-admin-admin-card h3 {
+  margin: 0;
+  font-size: 14px;
+}
+.mnote-ai-admin-kv-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+  gap: 10px;
+}
+.mnote-ai-admin-kv {
+  border: 1px solid #f0f0f0;
+  border-radius: 6px;
+  padding: 9px 10px;
+  background: #ffffff;
+}
+.mnote-ai-admin-kv span {
+  display: block;
+  color: rgba(0,0,0,0.45);
+  font-size: 12px;
+}
+.mnote-ai-admin-kv strong {
+  display: block;
+  margin-top: 4px;
+  color: rgba(0,0,0,0.88);
+  font-size: 13px;
+  font-weight: 600;
+  overflow-wrap: anywhere;
+}
+.mnote-ai-admin-table-wrap {
+  width: 100%;
+  overflow: auto;
+}
+.mnote-ai-admin-table {
+  width: 100%;
+  border-collapse: collapse;
+  table-layout: auto;
+}
+.mnote-ai-admin-table th {
+  padding: 12px 16px;
+  border-bottom: 1px solid #f0f0f0;
+  background: #fafafa;
+  color: rgba(0,0,0,0.65);
+  font-size: 13px;
+  font-weight: 600;
+  text-align: left;
+  white-space: nowrap;
+}
+.mnote-ai-admin-table td {
+  padding: 12px 16px;
+  border-bottom: 1px solid #f0f0f0;
+  color: rgba(0,0,0,0.78);
+  font-size: 13px;
+  vertical-align: middle;
+}
+.mnote-ai-admin-table tr:last-child td {
+  border-bottom: 0;
+}
+.mnote-ai-admin-table tr:hover td {
+  background: #fafafa;
+}
+.mnote-ai-admin-badge,
+.mnote-ai-admin-tag {
+  display: inline-flex;
+  align-items: center;
+  min-height: 22px;
+  padding: 0 8px;
+  border: 1px solid #d9d9d9;
+  border-radius: 4px;
+  background: #fafafa;
+  color: rgba(0,0,0,0.65);
+  font-size: 12px;
+  line-height: 20px;
+  white-space: nowrap;
+}
+.mnote-ai-admin-badge--active,
+.mnote-ai-admin-tag--green {
+  border-color: #b7eb8f;
+  background: #f6ffed;
+  color: #389e0d;
+}
+.mnote-ai-admin-badge--default,
+.mnote-ai-admin-tag--blue {
+  border-color: #91caff;
+  background: #e6f4ff;
+  color: #1677ff;
+}
+.mnote-ai-admin-tag--red {
+  border-color: #ffa39e;
+  background: #fff1f0;
+  color: #cf1322;
+}
+.mnote-ai-admin-tag--orange {
+  border-color: #ffd591;
+  background: #fff7e6;
+  color: #d46b08;
+}
+.mnote-ai-admin-empty,
+.mnote-ai-admin-placeholder,
+.mnote-ai-admin-skeleton {
+  padding: 28px 0;
+  color: rgba(0,0,0,0.45);
+  font-size: 13px;
+  text-align: center;
+}
+.mnote-ai-admin-json {
+  max-height: 300px;
+  margin-top: 8px;
+  overflow: auto;
+  border: 1px solid #f0f0f0;
+  border-radius: 6px;
+  background: #fafafa;
+  padding: 12px;
+  color: rgba(0,0,0,0.72);
+  font: 12px/1.55 "JetBrains Mono", "SFMono-Regular", Consolas, monospace;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+.mnote-ai-admin-link,
+.mnote-ai-admin-policy-link {
+  color: #1677ff;
+  text-decoration: none;
+}
+.mnote-ai-admin-policy-link,
+.mnote-ai-admin-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  height: 32px;
+  padding: 0 12px;
+  border: 1px solid #d9d9d9;
+  border-radius: 6px;
+  background: #ffffff;
+  color: rgba(0,0,0,0.88);
+  font-size: 14px;
+  font-weight: 400;
+  cursor: pointer;
+  transition: border-color 0.15s, color 0.15s, background 0.15s;
+}
+.mnote-ai-admin-policy-link:hover,
+.mnote-ai-admin-btn:hover {
+  border-color: #4096ff;
+  color: #1677ff;
+}
+.mnote-ai-admin-btn--primary {
+  border-color: #1677ff;
+  background: #1677ff;
+  color: #ffffff;
+}
+.mnote-ai-admin-btn--primary:hover {
+  border-color: #4096ff;
+  background: #4096ff;
+  color: #ffffff;
+}
+.mnote-ai-admin-btn--danger {
+  color: #cf1322;
+}
+.mnote-ai-admin-btn--small {
+  height: 24px;
+  padding: 0 7px;
+  font-size: 12px;
+}
+.mnote-ai-admin-icon-actions {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+}
+.mnote-ai-admin-icon-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  border: 0;
+  border-radius: 4px;
+  background: transparent;
+  color: rgba(0,0,0,0.55);
+  cursor: pointer;
+}
+.mnote-ai-admin-icon-btn:hover {
+  background: #e6f4ff;
+  color: #1677ff;
+}
+.mnote-ai-admin-icon-btn.is-danger:hover {
+  background: #fff1f0;
+  color: #cf1322;
+}
+.mnote-ai-admin-input,
+.mnote-ai-admin-select {
+  width: 100%;
+  min-height: 32px;
+  box-sizing: border-box;
+  border: 1px solid #d9d9d9;
+  border-radius: 6px;
+  background: #ffffff;
+  color: rgba(0,0,0,0.88);
+  font-size: 14px;
+}
+.mnote-ai-admin-input {
+  padding: 4px 11px;
+}
+.mnote-ai-admin-select {
+  padding: 4px 8px;
+}
+.mnote-ai-admin-input:focus,
+.mnote-ai-admin-select:focus {
+  outline: none;
+  border-color: #4096ff;
+  box-shadow: 0 0 0 2px rgba(5,145,255,0.1);
+}
+.mnote-ai-admin-input:disabled,
+.mnote-ai-admin-select:disabled {
+  background: #f5f5f5;
+  color: rgba(0,0,0,0.25);
+  cursor: not-allowed;
+}
+.mnote-ai-admin-label {
+  display: block;
+  margin-bottom: 5px;
+  color: rgba(0,0,0,0.65);
+  font-size: 13px;
+}
+.mnote-ai-admin-form-group {
+  margin-bottom: 12px;
+}
+.mnote-ai-admin-form-row {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 12px;
+}
+.mnote-ai-admin-actions-bar {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+}
+.mnote-ai-admin-search-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  margin-bottom: 12px;
+}
+.mnote-ai-admin-search-row .mnote-ai-admin-input {
+  max-width: 260px;
+}
+.mnote-ai-admin-provider-card {
+  margin-bottom: 12px;
+  border: 1px solid #f0f0f0;
+  border-radius: 8px;
+  background: #ffffff;
+}
+.mnote-ai-admin-provider-card-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 12px 16px;
+  border-bottom: 1px solid #f0f0f0;
+  background: #fafafa;
+}
+.mnote-ai-admin-provider-card-title {
+  font-size: 14px;
+  font-weight: 600;
+}
+.mnote-ai-admin-provider-card-body {
+  padding: 16px;
+}
+.mnote-ai-admin-collapse {
+  margin-bottom: 12px;
+  border: 1px solid #f0f0f0;
+  border-radius: 8px;
+  background: #ffffff;
+  overflow: hidden;
+}
+.mnote-ai-admin-collapse > summary {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 12px 16px;
+  background: #fafafa;
+  cursor: pointer;
+  font-weight: 600;
+}
+.mnote-ai-admin-collapse-body {
+  padding: 12px 16px;
+}
+.mnote-ai-admin-save-status {
+  display: none;
+  margin-bottom: 12px;
+  padding: 9px 12px;
+  border-radius: 6px;
+  font-size: 13px;
+}
+.mnote-ai-admin-save-status--success {
+  display: block;
+  border: 1px solid #b7eb8f;
+  background: #f6ffed;
+  color: #389e0d;
+}
+.mnote-ai-admin-save-status--error {
+  display: block;
+  border: 1px solid #ffa39e;
+  background: #fff1f0;
+  color: #cf1322;
+}
+.mnote-ai-admin-toggle {
+  position: relative;
+  display: inline-block;
+  width: 36px;
+  height: 20px;
+  flex-shrink: 0;
+}
+.mnote-ai-admin-toggle input {
+  opacity: 0;
+  width: 0;
+  height: 0;
+}
+.mnote-ai-admin-toggle-slider {
+  position: absolute;
+  inset: 0;
+  border-radius: 20px;
+  background: #d9d9d9;
+  cursor: pointer;
+  transition: background 0.2s;
+}
+.mnote-ai-admin-toggle-slider::before {
+  content: "";
+  position: absolute;
+  left: 2px;
+  bottom: 2px;
+  width: 16px;
+  height: 16px;
+  border-radius: 50%;
+  background: #ffffff;
+  transition: transform 0.2s;
+}
+.mnote-ai-admin-toggle input:checked + .mnote-ai-admin-toggle-slider {
+  background: #1677ff;
+}
+.mnote-ai-admin-toggle input:checked + .mnote-ai-admin-toggle-slider::before {
+  transform: translateX(16px);
+}
+.mnote-ai-admin-secret-hint {
+  margin-top: 3px;
+  color: rgba(0,0,0,0.35);
+  font-size: 12px;
+}
+.mnote-ai-admin-skill-row,
+.mnote-ai-admin-user-option,
+.mnote-ai-admin-user-policy-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+.mnote-ai-admin-skill-row {
+  padding: 10px 0;
+  border-bottom: 1px solid #f0f0f0;
+}
+.mnote-ai-admin-skill-row:last-child {
+  border-bottom: 0;
+}
+.mnote-ai-admin-skill-info {
+  min-width: 0;
+  flex: 1;
+}
+.mnote-ai-admin-user-options {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+  gap: 8px;
+  margin-bottom: 10px;
+}
+.mnote-ai-admin-user-editor-head {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 12px;
+  margin-bottom: 14px;
+  padding-bottom: 12px;
+  border-bottom: 1px solid #f0f0f0;
+}
+.mnote-ai-admin-user-editor-head h3 {
+  margin: 0;
+  font-size: 16px;
+}
+.mnote-ai-admin-user-editor-head p {
+  margin: 4px 0 0;
+  color: rgba(0,0,0,0.45);
+  font-size: 12px;
+}
+.mnote-ai-admin-user-tabbar {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 14px;
+}
+.mnote-ai-admin-user-option {
+  justify-content: flex-start;
+  border: 1px solid #f0f0f0;
+  border-radius: 6px;
+  padding: 8px 10px;
+}
+.mnote-ai-admin-user-option span,
+.mnote-ai-admin-user-policy-row > span {
+  display: grid;
+  gap: 2px;
+  min-width: 0;
+}
+.mnote-ai-admin-user-option small,
+.mnote-ai-admin-user-policy-row small {
+  color: rgba(0,0,0,0.45);
+  font-size: 12px;
+}
+.mnote-ai-admin-user-section {
+  padding: 14px 0;
+  border-bottom: 1px solid #f0f0f0;
+}
+.mnote-ai-admin-user-section h3 {
+  margin: 0 0 10px;
+  font-size: 14px;
+}
+.mnote-ai-admin-user-section-title {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  margin-bottom: 10px;
+}
+.mnote-ai-admin-user-section-title h3 {
+  margin: 0;
+}
+.mnote-ai-admin-permission-group {
+  margin-bottom: 14px;
+  border: 1px solid #f0f0f0;
+  border-radius: 8px;
+  background: #ffffff;
+  overflow: hidden;
+}
+.mnote-ai-admin-permission-group-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 10px 12px;
+  background: #fafafa;
+  border-bottom: 1px solid #f0f0f0;
+}
+.mnote-ai-admin-permission-group-head strong {
+  font-size: 13px;
+}
+.mnote-ai-admin-permission-group-body {
+  padding: 8px 12px;
+}
+.mnote-ai-admin-permission-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 8px 0;
+  border-bottom: 1px solid #fafafa;
+}
+.mnote-ai-admin-permission-row:last-child {
+  border-bottom: 0;
+}
+.mnote-ai-admin-permission-row-main {
+  min-width: 0;
+  flex: 1;
+}
+.mnote-ai-admin-permission-row-main strong {
+  display: block;
+  font-size: 13px;
+  overflow-wrap: anywhere;
+}
+.mnote-ai-admin-permission-row-main small {
+  color: rgba(0,0,0,0.45);
+  font-size: 12px;
+}
+.mnote-ai-admin-permission-row-actions {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  flex-shrink: 0;
+}
+.mnote-ai-admin-subsection-card {
+  margin-bottom: 14px;
+  border: 1px solid #f0f0f0;
+  border-radius: 8px;
+  background: #ffffff;
+}
+.mnote-ai-admin-subsection-card-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 12px 16px;
+  border-bottom: 1px solid #f0f0f0;
+  background: #fafafa;
+}
+.mnote-ai-admin-subsection-card-head h3 {
+  margin: 0;
+  font-size: 14px;
+}
+.mnote-ai-admin-subsection-card-body {
+  padding: 14px 16px 16px;
+}
+.mnote-ai-admin-access-scope-row {
+  display: flex;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 10px 0;
+  border-bottom: 1px solid #f0f0f0;
+}
+.mnote-ai-admin-access-scope-path {
+  color: rgba(0,0,0,0.88);
+  font-size: 13px;
+  font-weight: 500;
+  overflow-wrap: anywhere;
+}
+.mnote-ai-admin-access-scope-meta {
+  color: rgba(0,0,0,0.45);
+  font-size: 12px;
+}
+.mnote-ai-admin-drawer {
+  position: fixed;
+  inset: 0;
+  z-index: 1100;
+  display: none;
+}
+.mnote-ai-admin-drawer.is-open {
+  display: block;
+}
+.mnote-ai-admin-drawer-backdrop {
+  position: absolute;
+  inset: 0;
+  background: rgba(0,0,0,0.35);
+}
+.mnote-ai-admin-drawer-panel {
+  position: absolute;
+  top: 0;
+  right: 0;
+  width: min(720px, 100vw);
+  height: 100%;
+  overflow: auto;
+  background: #ffffff;
+  box-shadow: -4px 0 16px rgba(0,0,0,0.12);
+}
+.mnote-ai-admin-drawer-head {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 12px;
+  padding: 16px 20px;
+  border-bottom: 1px solid #f0f0f0;
+  background: #ffffff;
+}
+.mnote-ai-admin-drawer-head h3 {
+  margin: 0;
+  font-size: 16px;
+}
+.mnote-ai-admin-drawer-body {
+  padding: 18px 20px 24px;
+}
+@media (max-width: 768px) {
+  .mnote-ai-admin-mobile-trigger {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+  }
+  .mnote-ai-admin-shell {
+    grid-template-columns: 1fr;
+  }
+  .mnote-ai-admin-sider {
+    position: fixed;
+    inset: 0 auto 0 0;
+    z-index: 1000;
+    width: 220px;
+    transform: translateX(-100%);
+    transition: transform 0.18s ease;
+    box-shadow: 2px 0 12px rgba(0,0,0,0.12);
+  }
+  .mnote-ai-admin.is-mobile-menu-open .mnote-ai-admin-sider {
+    transform: translateX(0);
+  }
+  .mnote-ai-admin-content {
+    padding: 16px;
+    padding-top: 58px;
+  }
+  .mnote-ai-admin-section,
+  .mnote-ai-admin-header {
+    padding-left: 16px;
+    padding-right: 16px;
+  }
+  .mnote-ai-admin-section-header,
+  .mnote-ai-admin-search-row,
+  .mnote-ai-admin-access-scope-row {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+  .mnote-ai-admin-form-row {
+    grid-template-columns: 1fr;
+  }
+}
+"#;
+
+/// AI 管理页面内嵌脚本
+///
+/// 从后端 API 获取 effective providers/models、access scopes 和 config，
+/// 填充到页面相应区域。模型/工具/技能 MCP 面板通过 loadConfig/saveConfig 提供内联编辑。
+const AI_ADMIN_SCRIPT: &str = r#"
+(function () {
+  function initAiAdminPage(scope) {
+    var root = (scope || document).querySelector('[data-testid="mnote-ai-admin-page"]');
+    if (!root) return;
+    if (root.getAttribute('data-ai-admin-ready') === 'true') return;
+    root.setAttribute('data-ai-admin-ready', 'true');
+
+    var pageConfig = (function () {
+      var node = root.querySelector('#__MNOTE_AI_ADMIN_CONFIG__');
+      try { return JSON.parse(node ? node.textContent || '{}' : '{}'); } catch (_) { return {}; }
+    })();
+
+    var isAdmin = pageConfig.isAdmin === true;
+    var overviewProvidersEl = root.querySelector('[data-ai-admin-overview-providers]');
+    var overviewModelsEl = root.querySelector('[data-ai-admin-overview-models]');
+    var overviewScopesEl = root.querySelector('[data-ai-admin-overview-scopes]');
+    var providerTableBody = root.querySelector('[data-ai-admin-providers-body]');
+    var modelPolicyBody = root.querySelector('[data-ai-admin-model-policy-body]');
+    var toolPolicyBody = root.querySelector('[data-ai-admin-tool-policy-body]');
+    var usageSummary = root.querySelector('[data-ai-admin-usage-summary]');
+    var healthGrid = root.querySelector('[data-ai-admin-health-grid]');
+    var servicePanel = root.querySelector('[data-ai-admin-service-panel]');
+    var channelsPanel = root.querySelector('[data-ai-admin-channels-panel]');
+    var knowledgePanel = root.querySelector('[data-ai-admin-knowledge-panel]');
+    var accessScopesList = root.querySelector('[data-ai-admin-access-scopes-list]');
+    var accessScopesJson = root.querySelector('[data-ai-admin-access-scopes-json]');
+    var accessScopesMessage = root.querySelector('[data-ai-admin-access-scopes-message]');
+    var effectiveJson = root.querySelector('[data-ai-admin-effective-json]');
+    var sessionsBody = root.querySelector('[data-ai-admin-sessions-body]');
+    var receiptsBody = root.querySelector('[data-ai-admin-receipts-body]');
+    var receiptsSummary = root.querySelector('[data-ai-admin-receipts-summary]');
+
+    // ── Config 面板容器 ──
+    var modelsContainer = root.querySelector('[data-ai-admin-models-container]');
+    var toolsContainer = root.querySelector('[data-ai-admin-tools-container]');
+    var skillsContainer = root.querySelector('[data-ai-admin-skills-container]');
+    var mcpContainer = root.querySelector('[data-ai-admin-mcp-container]');
+    var modelsSaveStatus = root.querySelector('[data-ai-admin-models-save-status]');
+    var toolsSaveStatus = root.querySelector('[data-ai-admin-tools-save-status]');
+    var skillsSaveStatus = root.querySelector('[data-ai-admin-skills-save-status]');
+    var usersList = root.querySelector('[data-ai-admin-users-list]');
+    var userSettingsEditor = root.querySelector('[data-ai-admin-user-settings]');
+    var userSettingsStatus = root.querySelector('[data-ai-admin-user-save-status]');
+    var mobileTrigger = root.querySelector('[data-action="toggle-mobile-menu"]');
+    var drawer = root.querySelector('[data-ai-admin-user-drawer]');
+    var drawerTitle = root.querySelector('[data-ai-admin-user-drawer-title]');
+    var drawerSubtitle = root.querySelector('[data-ai-admin-user-drawer-subtitle]');
+    var selectedUserId = '';
+    var selectedUserSettings = null;
+    var selectedUserPanel = 'models';
+
+    function setActivePanel(panelId, replaceHash) {
+      var targetId = panelId || (location.hash || '').replace(/^#/, '') || 'ai-admin-overview';
+      var panels = root.querySelectorAll('[data-ai-admin-panel]');
+      var found = false;
+      panels.forEach(function (panel) {
+        var active = panel.id === targetId;
+        panel.classList.toggle('is-active', active);
+        panel.hidden = !active;
+        if (active) found = true;
+      });
+      if (!found && targetId !== 'ai-admin-overview') {
+        setActivePanel('ai-admin-overview', true);
+        return;
+      }
+      root.querySelectorAll('[data-ai-admin-nav]').forEach(function (item) {
+        var active = item.getAttribute('href') === '#' + targetId;
+        item.classList.toggle('is-active', active);
+        if (active) item.setAttribute('aria-current', 'page');
+        else item.removeAttribute('aria-current');
+      });
+      root.classList.remove('is-mobile-menu-open');
+      if (replaceHash && history.replaceState) {
+        history.replaceState(null, '', '#' + targetId);
+      }
+    }
+
+    root.querySelectorAll('[data-ai-admin-nav]').forEach(function (item) {
+      item.addEventListener('click', function (event) {
+        event.preventDefault();
+        setActivePanel((item.getAttribute('href') || '').replace(/^#/, ''), true);
+      });
+    });
+    window.addEventListener('hashchange', function () { setActivePanel(); });
+    setActivePanel();
+
+    if (mobileTrigger) {
+      mobileTrigger.addEventListener('click', function () {
+        root.classList.toggle('is-mobile-menu-open');
+      });
+    }
+    root.addEventListener('click', function (event) {
+      var closeTarget = event.target && event.target.closest ? event.target.closest('[data-action="close-user-drawer"], [data-ai-admin-drawer-backdrop]') : null;
+      if (closeTarget && drawer) drawer.classList.remove('is-open');
+    });
+
+    function setText(node, value) {
+      if (!node) return;
+      node.textContent = typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+    }
+
+    function escapeHtml(value) {
+      return String(value == null ? '' : value)
+        .replace(/&/g, '&')
+        .replace(//g, '>')
+        .replace(/"/g, '"')
+        .replace(/'/g, ''');
+    }
+
+    async function requestJson(url, options) {
+      var response = await fetch(url, {
+        credentials: 'include',
+        headers: { 'content-type': 'application/json' },
+        ...options,
+      });
+      var payload = await response.json().catch(function () { return {}; });
+      if (!response.ok && !payload.ok) {
+        throw new Error((payload && payload.message) || ('请求失败: ' + response.status));
+      }
+      return payload;
+    }
+
+    function renderBadge(text, className) {
+      return '' + escapeHtml(text) + '';
+    }
+
+    function renderTag(text, tone) {
+      return '' + escapeHtml(text) + '';
+    }
+
+    function renderKv(label, value) {
+      return '
' + escapeHtml(label) + '' + escapeHtml(value == null || value === '' ? '-' : value) + '
';
+    }
+
+    function actionLabel(action) {
+      if (action === 'deny') return '拒绝';
+      if (action === 'ask') return '审批';
+      return '允许';
+    }
+
+    function actionTone(action) {
+      if (action === 'deny') return 'red';
+      if (action === 'ask') return 'orange';
+      return 'green';
+    }
+
+    function groupBy(items, keyFn) {
+      return (items || []).reduce(function(acc, item) {
+        var key = keyFn(item) || '其他';
+        if (!acc[key]) acc[key] = [];
+        acc[key].push(item);
+        return acc;
+      }, {});
+    }
+
+    function renderPermissionGroup(title, countLabel, bodyHtml) {
+      return '
' +
+        '
' + escapeHtml(title) + '' + renderTag(countLabel, 'blue') + '
' +
+        '
' + (bodyHtml || '
暂无数据
') + '
' +
+      '
';
+    }
+
+    function renderSelectablePermissionRow(options) {
+      var select = options.selectHtml || '';
+      return '
' +
+        '
' + escapeHtml(options.title || '-') + '' + escapeHtml(options.subtitle || '') + '
' +
+        '
' + (options.metaHtml || '') + select + (options.resetHtml || '') + '
' +
+      '
';
+    }
+
+    function normalizeModelRef(provider, modelId) {
+      var p = provider || 'omniroute';
+      var m = modelId || 'freefirst';
+      if (String(m).indexOf(p + '/') === 0) return String(m);
+      return p + '/' + m;
+    }
+
+    function renderServicePanels(piStatus, effectivePayload) {
+      var providers = effectivePayload && Array.isArray(effectivePayload.providers) ? effectivePayload.providers : [];
+      var openhubStatus = '默认入口保留';
+      var defaultModel = effectivePayload && (effectivePayload.defaultModel || effectivePayload.default_model || '');
+      var piDefaultModel = piStatus
+        ? normalizeModelRef(piStatus.defaultModelProvider || piStatus.default_model_provider, piStatus.defaultModelId || piStatus.default_model_id)
+        : 'omniroute/freefirst';
+      var piRuntime = piStatus ? (piStatus.runtimeMode || piStatus.runtime_mode || '-') : '-';
+      var piRunning = piStatus && piStatus.running === true;
+      if (servicePanel) {
+        servicePanel.innerHTML =
+          '
' +
+            '
' +
+              '
OpenHub
' +
+                renderTag(openhubStatus, 'green') +
+                '打开 OpenHub Admin' +
+              '
' +
+              '
' +
+                '
' +
+                  renderKv('定位', '默认 Page AI 主线') +
+                  renderKv('Provider/模型真相', 'OpenHub 保持独立，不被 Pi Lab 替换') +
+                  renderKv('MNote 侧入口', '/page-ai/openhub/ai') +
+                  renderKv('管理入口', '/page-ai/openhub/admin') +
+                '
' +
+              '
' +
+            '
' +
+            '
' +
+              '
Pi Lab
' +
+                renderTag(piRunning ? '运行中' : '待启动', piRunning ? 'green' : 'orange') +
+                renderTag(piRuntime, 'blue') +
+              '
' +
+              '
' +
+                '
' +
+                  renderKv('默认模型', piDefaultModel) +
+                  renderKv('UI 模式', piStatus && piStatus.uiMode ? piStatus.uiMode : 'independent_mnote_native_drawer') +
+                  renderKv('Session', piStatus && piStatus.sessionId ? piStatus.sessionId : 'none') +
+                  renderKv('Provider Session', piStatus && piStatus.providerSessionId ? piStatus.providerSessionId : 'none') +
+                  renderKv('Runtime PID', piStatus && piStatus.pid ? String(piStatus.pid) : 'none') +
+                  renderKv('禁用 Pi 原始工具', (piStatus && piStatus.disabledPiBuiltinTools || ['bash','read','write','edit']).join(', ')) +
+                  renderKv('Receipt storage', piStatus && piStatus.receiptStorage ? piStatus.receiptStorage : 'control-plane / provider-neutral adapter') +
+                  renderKv('Session dir policy', piStatus && piStatus.managedPiSessionDirPolicy ? piStatus.managedPiSessionDirPolicy : '/.mnote/ai/pi-sessions//') +
+                '
' +
+              '
' +
+            '
' +
+          '
';
+      }
+      if (channelsPanel) {
+        var providerCards = providers.length ? providers.map(function(p) {
+          var model = p.defaultModel || p.default_model || p.model || defaultModel || 'omniroute/freefirst';
+          return '
' +
+            '
' + escapeHtml(p.name || p.id || p.provider || 'Provider') + '
' +
+              renderTag(p.enabled !== false ? '启用' : '停用', p.enabled !== false ? 'green' : 'orange') +
+              renderTag(p.id || p.provider || 'provider', 'blue') +
+            '
' +
+            '
' +
+              renderKv('默认模型', model) +
+              renderKv('Base URL', p.baseUrl || p.base_url || p.endpoint || '-') +
+              renderKv('Secret 引用', p.secretRef || p.secret_ref || 'env://OMNIROUTE_API_KEY') +
+              renderKv('密钥策略', '只保存 env:// 或 secret:// 引用，raw key 不进前端') +
+            '
' +
+          '
';
+        }).join('') : '
暂无 Provider 配置
';
+        channelsPanel.innerHTML =
+          '
' +
+            '
' +
+              '
Omniroute
' +
+                renderTag('默认渠道', 'green') + renderTag('Pi: ' + piDefaultModel, 'blue') +
+              '
' +
+              '
' +
+                renderKv('Pi 默认模型', piDefaultModel) +
+                renderKv('Pi Base URL', piStatus && piStatus.omnirouteBaseUrl ? piStatus.omnirouteBaseUrl : 'http://127.0.0.1:20128/v1') +
+                renderKv('API Key', 'env://OMNIROUTE_API_KEY / 本机配置读取') +
+                renderKv('Secret 策略', 'API key 与 secret 不进前端、不硬编码') +
+                renderKv('作用域', 'MNote provider/model policy + Pi session config') +
+              '
' +
+            '
' +
+            providerCards +
+          '
';
+      }
+      if (knowledgePanel) {
+        var lightrag = effectivePayload && (effectivePayload.lightragProvider || effectivePayload.lightrag_provider) || {};
+        knowledgePanel.innerHTML =
+          '
' +
+            '
' +
+              '
LightRAG
' +
+                renderTag('唯一默认 provider', 'green') + renderTag('MNote facade', 'blue') +
+              '
' +
+              '
' +
+                '
' +
+                  renderKv('Provider', lightrag.provider || 'lightrag') +
+                  renderKv('查询入口', 'mnote.knowledge_rag.query') +
+                  renderKv('引用回跳', 'citation / open-reference') +
+                  renderKv('Pi 接入方式', '只能通过 MNote knowledge facade 查询') +
+                '
' +
+              '
' +
+            '
' +
+            '
' +
+              '
知识源
' +
+                renderTag('复用 allowed roots', 'green') + renderTag('不引入第二套 RAG', 'orange') +
+              '
' +
+              '
' +
+                '
资料 source/index/status 后续接 /api/knowledge-rag/*；目录授权继续来自 MNote allowed roots，不在 AI 管理页维护第二套目录。
' +
+              '
' +
+            '
' +
+          '
';
+      }
+      if (healthGrid) {
+        healthGrid.innerHTML = [
+          ['OpenHub 默认入口', '保留', 'Page AI 主线未被 Pi Lab 替换'],
+          ['Pi Lab', piRunning ? '运行中' : '可启动', 'runtime=' + piRuntime + ' · model=' + piDefaultModel],
+          ['LightRAG', '默认', '唯一默认 knowledge provider，Pi 通过 MNote facade 查询'],
+          ['Control-plane', effectivePayload && (effectivePayload.sourceOfTruth || effectivePayload.source_of_truth) || 'directory_grants', '授权、策略、receipt 真相层']
+        ].map(function(item) {
+          return '
' + escapeHtml(item[0]) + '
' + renderBadge(item[1], 'mnote-ai-admin-badge--active') + '
' + escapeHtml(item[2]) + '
';
+        }).join('');
+      }
+    }
+
+    function openUserDrawer(panel) {
+      selectedUserPanel = panel || selectedUserPanel || 'models';
+      if (drawer) drawer.classList.add('is-open');
+      if (selectedUserSettings) renderUserSettings(selectedUserSettings);
+    }
+
+    function showSaveStatus(el, type, msg) {
+      if (!el) return;
+      el.className = 'mnote-ai-admin-save-status mnote-ai-admin-save-status--' + type;
+      el.textContent = msg;
+      el.style.display = 'block';
+      if (type === 'success') {
+        setTimeout(function () { el.style.display = 'none'; }, 4000);
+      }
+    }
+
+    function renderUserList(users) {
+      if (!usersList) return;
+      if (!users || !users.length) {
+        usersList.innerHTML = '
暂无用户
';
+        return;
+      }
+      var rows = users.map(function(user, idx) {
+        var username = user.display_name || user.username || user.id;
+        var role = user.role || (user.isAdmin ? 'admin' : 'user');
+        var status = user.disabled ? '禁用' : '启用';
+        var statusTone = user.disabled ? 'red' : 'green';
+        return '' +
+          '' + escapeHtml(String(idx + 1)) + '' +
+          '👤 ' + escapeHtml(username) + '
' + escapeHtml(user.email || user.id) + '
' +
+          '' + renderTag(role === 'admin' ? '管理员' : '普通', role === 'admin' ? 'blue' : '') + '' +
+          '' + renderTag(status, statusTone) + '' +
+          '' + escapeHtml(user.workspace_path || user.workspacePath || '未初始化') + '' +
+          '
' +
+            '' +
+            '' +
+            '' +
+            '' +
+            '' +
+            '' +
+          '
' +
+        '';
+      }).join('');
+      usersList.innerHTML = '
' +
+        '' +
+        '' + rows + '
ID用户名角色状态工作空间操作
';
+      usersList.querySelectorAll('[data-user-action]').forEach(function(button) {
+        button.addEventListener('click', function() {
+          selectedUserPanel = button.getAttribute('data-user-action') || 'models';
+          loadUserSettings(button.getAttribute('data-user-id') || '').then(function() {
+            openUserDrawer(selectedUserPanel);
+          });
+        });
+      });
+    }
+
+    function renderUserSettings(payload) {
+      if (!userSettingsEditor) return;
+      selectedUserSettings = payload;
+      if (drawerTitle) drawerTitle.textContent = payload.userId || '用户配置';
+      if (drawerSubtitle) drawerSubtitle.textContent = '逐用户模型 / 工具 / Skills / MCP / 目录权限';
+      if (payload.isGlobalPolicyOwner) {
+        userSettingsEditor.innerHTML = '
该用户承载全局 AI 策略。请使用左侧“模型配置”“工具权限”“技能 / MCP”页面修改默认策略。
';
+        return;
+      }
+      var catalogModels = payload.catalogModels || [];
+      var allowedIds = new Set((payload.allowedModels || []).map(function(model) { return model.id; }));
+      var modelGroups = groupBy(catalogModels, function(model) { return model.providerName || model.provider || (model.id || '').split('/')[0] || 'Provider'; });
+      var modelRows = Object.keys(modelGroups).map(function(providerName) {
+        var models = modelGroups[providerName] || [];
+        var enabledCount = models.filter(function(model) { return allowedIds.has(model.id); }).length;
+        var rows = models.map(function(model) {
+          var usage = model.currentUsage || model.current_usage || 0;
+          var limit = model.monthlyLimit || model.monthly_limit || 0;
+          var usageText = usage ? ('已用 ' + usage + (limit ? (' / ' + limit) : '')) : (limit ? ('月限 ' + limit) : '未设置月限');
+          return renderSelectablePermissionRow({
+            title: model.name || model.id,
+            subtitle: model.id || '',
+            metaHtml: '' + escapeHtml(usageText) + '',
+            selectHtml: ''
+          });
+        }).join('');
+        return renderPermissionGroup(providerName, enabledCount + '/' + models.length + ' 已启用', rows);
+      }).join('');
+      var toolGroups = groupBy(payload.tools || [], function(tool) {
+        return tool.riskLevel || tool.risk_level || tool.risk || 'safe';
+      });
+      var riskLabels = { dangerous: '危险工具', moderate: '敏感工具', safe: '安全工具', custom: '自定义工具' };
+      var tools = ['dangerous', 'moderate', 'safe', 'custom'].map(function(risk) {
+        var items = toolGroups[risk] || [];
+        if (!items.length) return '';
+        var rows = items.map(function(tool) {
+          var maxRank = tool.globalAction === 'allow' ? 2 : (tool.globalAction === 'ask' ? 1 : 0);
+          var current = tool.action || tool.userAction || tool.globalAction || 'allow';
+          var selectHtml = '';
+          return renderSelectablePermissionRow({
+            title: tool.name,
+            subtitle: tool.description || ('全局 ' + actionLabel(tool.globalAction || 'allow')),
+            metaHtml: renderTag(actionLabel(current), actionTone(current)),
+            selectHtml: selectHtml,
+            resetHtml: tool.hasOverride ? '' : ''
+          });
+        }).join('');
+        return renderPermissionGroup(riskLabels[risk] || risk, items.length + ' 项', rows);
+      }).join('');
+      if (!tools && (payload.tools || []).length) {
+        tools = (payload.tools || []).map(function(tool) {
+        var maxRank = tool.globalAction === 'allow' ? 2 : (tool.globalAction === 'ask' ? 1 : 0);
+        return '
' + escapeHtml(tool.name) + '全局 ' + escapeHtml(actionLabel(tool.globalAction)) + '' +
+          '
';
+        }).join('');
+      }
+      var enabledSkills = (payload.skills || []).filter(function(skill) { return skill.globallyEnabled !== false; });
+      var skills = (payload.skills || []).map(function(skill) {
+        return renderSelectablePermissionRow({
+          title: skill.name || skill.id,
+          subtitle: skill.description || (skill.globallyEnabled ? '全局启用' : '全局禁用'),
+          metaHtml: renderTag(skill.enabled ? '启用' : '禁用', skill.enabled ? 'green' : 'red'),
+          selectHtml: '',
+          resetHtml: skill.hasOverride ? '' : ''
+        });
+      }).join('');
+      if (skills) skills = renderPermissionGroup('Skills', enabledSkills.length + '/' + (payload.skills || []).length + ' 全局可用', skills);
+      var mcps = (payload.mcpServers || []).map(function(server) {
+        return renderSelectablePermissionRow({
+          title: server.name || server.id,
+          subtitle: (server.transport || 'stdio') + ' · facade/sandbox · ' + (server.networkPolicy || 'deny-all'),
+          metaHtml: renderTag(server.enabled ? '启用' : '禁用', server.enabled ? 'green' : 'red'),
+          selectHtml: '',
+          resetHtml: server.hasOverride ? '' : ''
+        });
+      }).join('');
+      if (mcps) mcps = renderPermissionGroup('MCP Servers', (payload.mcpServers || []).length + ' 项', mcps);
+      var roots = (payload.allowedRoots || payload.accessScopes || payload.roots || []).map(function(rootItem) {
+        return '
' + escapeHtml(rootItem.rootPath || rootItem.path || rootItem.rootUri || '-') + '
' +
+          '
' + escapeHtml(rootItem.source || rootItem.scope || 'directory_grants') + '
' +
+          renderTag(rootItem.permission === 'write' ? '读写' : '只读', rootItem.permission === 'write' ? 'green' : '') + '
';
+      }).join('');
+      var activePanel = selectedUserPanel || 'models';
+      var header =
+        '
' +
+        '' +
+        '' +
+        '' +
+        '' +
+        '' +
+        '' +
+        '
';
+      var body = '';
+      if (activePanel === 'tools') {
+        body = '
工具权限
按 OpenHub risk_level 分组
' + (tools || '
暂无工具
') + '
';
+      } else if (activePanel === 'skills') {
+        body = '
Skills
全局启用后用户可单独降权
' + (skills || '
暂无 Skill
') + '
';
+      } else if (activePanel === 'mcp') {
+        body = '
MCP
只允许 MNote facade/sandbox MCP
' + (mcps || '
暂无 MCP
') + '
';
+      } else if (activePanel === 'roots') {
+        body = '
目录权限
统一授权管理
' + (roots || '
目录权限由统一 allowed roots 管理。请到目录权限页调整。
') + '
';
+      } else {
+        body = '
模型权限
按 provider 分组，参考 OpenHub 用户模型权限
' + (modelRows || '
暂无可用模型
') +
+          '
';
+      }
+      userSettingsEditor.innerHTML =
+        '
' + escapeHtml(payload.userId) + '
逐用户配置只能在管理员全局范围内降权或选择；目录权限复用 MNote allowed roots。
' +
+        '' + renderTag(payload.defaultModel || '未设默认模型', 'blue') + renderTag((payload.allowedModels || []).length + ' 个模型', 'green') + '
' +
+        header + body;
+      userSettingsEditor.querySelectorAll('[data-user-tab]').forEach(function(btn) {
+        btn.addEventListener('click', function() {
+          selectedUserPanel = btn.getAttribute('data-user-tab') || 'models';
+          renderUserSettings(payload);
+        });
+      });
+      var saveButton = userSettingsEditor.querySelector('[data-action="save-user-settings"]');
+      if (saveButton) saveButton.addEventListener('click', saveUserSettings);
+    }
+
+    async function loadUserSettings(userId) {
+      if (!userId) return;
+      selectedUserId = userId;
+      var usersPayload = await requestJson('/api/ai-admin/users', { method: 'GET' });
+      renderUserList(usersPayload.users || []);
+      var payload = await requestJson('/api/ai-admin/users/' + encodeURIComponent(userId) + '/settings', { method: 'GET' });
+      renderUserSettings(payload);
+    }
+
+    async function loadUsers() {
+      if (!isAdmin || !usersList) return;
+      var payload = await requestJson('/api/ai-admin/users', { method: 'GET' });
+      var users = payload.users || [];
+      if (!selectedUserId && users.length) selectedUserId = users[0].id;
+      renderUserList(users);
+      if (selectedUserId) {
+        var settings = await requestJson('/api/ai-admin/users/' + encodeURIComponent(selectedUserId) + '/settings', { method: 'GET' });
+        renderUserSettings(settings);
+      }
+    }
+
+    async function saveUserSettings() {
+      if (!selectedUserId || !userSettingsEditor) return;
+      var modelInputs = userSettingsEditor.querySelectorAll('[data-user-model]');
+      var allowedModels = selectedUserSettings && selectedUserSettings.allowedModels
+        ? selectedUserSettings.allowedModels.map(function(model) { return model.id; })
+        : [];
+      if (modelInputs.length) {
+        allowedModels = Array.from(userSettingsEditor.querySelectorAll('[data-user-model]:checked')).map(function(input) { return input.getAttribute('data-user-model'); });
+      }
+      var defaultSelect = userSettingsEditor.querySelector('[data-user-default-model]');
+      var tools = {};
+      (selectedUserSettings && selectedUserSettings.tools || []).forEach(function(tool) {
+        tools[tool.name] = tool.action;
+      });
+      userSettingsEditor.querySelectorAll('[data-user-tool]').forEach(function(select) {
+        tools[select.getAttribute('data-user-tool')] = select.value;
+      });
+      var skills = {};
+      (selectedUserSettings && selectedUserSettings.skills || []).forEach(function(skill) {
+        skills[skill.id] = skill.enabled;
+      });
+      userSettingsEditor.querySelectorAll('[data-user-skill]').forEach(function(input) {
+        skills[input.getAttribute('data-user-skill')] = input.checked;
+      });
+      var mcpServers = {};
+      (selectedUserSettings && selectedUserSettings.mcpServers || []).forEach(function(server) {
+        mcpServers[server.id] = server.enabled;
+      });
+      userSettingsEditor.querySelectorAll('[data-user-mcp]').forEach(function(input) {
+        mcpServers[input.getAttribute('data-user-mcp')] = input.checked;
+      });
+      try {
+        await requestJson('/api/ai-admin/users/' + encodeURIComponent(selectedUserId) + '/settings', {
+          method: 'PUT',
+          body: JSON.stringify({
+            allowedModels: allowedModels,
+            defaultModel: defaultSelect ? defaultSelect.value : ((selectedUserSettings && selectedUserSettings.defaultModel) || ''),
+            tools: tools,
+            skills: skills,
+            mcpServers: mcpServers
+          })
+        });
+        showSaveStatus(userSettingsStatus, 'success', '用户 AI 配置已保存');
+        await loadUserSettings(selectedUserId);
+      } catch (err) {
+        showSaveStatus(userSettingsStatus, 'error', '保存失败: ' + (err.message || '未知错误'));
+      }
+    }
+
+    // ── 1. 加载 effective providers/models ──
+    async function loadEffective() {
+      var payload;
+      try {
+        payload = await requestJson('/api/ai-admin/effective', { method: 'GET' });
+      } catch (_err) {
+        try {
+          payload = await requestJson('/api/ai-settings/effective', { method: 'GET' });
+        } catch (err) {
+          setText(effectiveJson, { error: err.message || '无法加载 effective 配置', note: 'API 端点暂未实现，此为占位' });
+          if (overviewProvidersEl) overviewProvidersEl.textContent = '-';
+          if (overviewModelsEl) overviewModelsEl.textContent = '-';
+          if (providerTableBody) providerTableBody.innerHTML = '暂无数据';
+          return;
+        }
+      }
+
+      setText(effectiveJson, payload);
+
+      var providers = payload && (payload.providers || []);
+      var models = payload && (payload.models || []);
+      var defaultModel = payload && (payload.defaultModel || payload.default_model || '');
+      var modelCount = Array.isArray(models) ? models.length : 0;
+
+      if (providerTableBody && Array.isArray(providers)) {
+        if (providers.length === 0) {
+          providerTableBody.innerHTML = '暂无配置';
+        } else {
+          providerTableBody.innerHTML = providers.map(function(p) {
+            var name = escapeHtml(p.name || p.provider || p.id || '未知');
+            var model = escapeHtml(p.model || p.defaultModel || p.default_model || defaultModel || '默认');
+            var status = p.enabled !== false ? renderBadge('启用', 'mnote-ai-admin-badge--active') : renderBadge('停用');
+            var isDefault = (p.id === defaultModel || p.name === defaultModel || p.model === defaultModel)
+              ? renderBadge('默认', 'mnote-ai-admin-badge--default') : '';
+            return '' + name + '' + model + '' + status + isDefault + '' + escapeHtml(p.baseUrl || p.base_url || p.endpoint || '-') + '';
+          }).join('');
+        }
+      }
+
+      if (overviewProvidersEl) overviewProvidersEl.textContent = String(Array.isArray(providers) ? providers.length : 0);
+      if (overviewModelsEl) overviewModelsEl.textContent = String(modelCount);
+      if (modelPolicyBody) {
+        var modelPolicy = payload.modelPolicy || payload.model_policy || {};
+        var rows = [
+          ['Build 默认', modelPolicy.defaultBuildModel || modelPolicy.default_build_model || defaultModel || 'omniroute/freefirst'],
+          ['Plan 默认', modelPolicy.defaultPlanModel || modelPolicy.default_plan_model || defaultModel || 'omniroute/freefirst'],
+          ['Task 默认', modelPolicy.defaultTaskModel || modelPolicy.default_task_model || defaultModel || 'omniroute/freefirst'],
+          ['Failover', Array.isArray(modelPolicy.failoverChains || modelPolicy.failover_chains) ? '已配置' : '未配置']
+        ];
+        modelPolicyBody.innerHTML = rows.map(function(row) {
+          return '' + escapeHtml(row[0]) + '' + escapeHtml(row[1]) + '';
+        }).join('');
+      }
+      if (toolPolicyBody) {
+        var tools = payload.toolCatalog || payload.tool_catalog || [];
+        toolPolicyBody.innerHTML = tools.length ? tools.map(function(t) {
+          var action = t.defaultPolicy || t.default_policy || 'allow';
+          var tone = action === 'allow' ? 'mnote-ai-admin-badge--active' : '';
+          return '' + escapeHtml(t.name || '-') + '' + escapeHtml(t.description || '-') + '' + renderBadge(action, tone) + '';
+        }).join('') : '暂无工具目录';
+      }
+      var piStatus = null;
+      try {
+        piStatus = await requestJson('/api/page-ai/pi/status', { method: 'GET' });
+      } catch (_err) {
+        // Pi Lab 状态失败不阻塞 OpenHub / 管理页主面板。
+      }
+      renderServicePanels(piStatus, payload);
+    }
+
+    // ── 2. 加载 access scopes ──
+    async function loadAccessScopes() {
+      var payload;
+      try {
+        payload = await requestJson('/api/ai-admin/access-scopes', { method: 'GET' });
+      } catch (_err) {
+        try {
+          payload = await requestJson('/api/ai-settings/access-scopes', { method: 'GET' });
+        } catch (err) {
+          if (accessScopesMessage) setText(accessScopesMessage, 'access-scopes API 暂未实现，此为占位');
+          if (accessScopesList) accessScopesList.innerHTML = '
暂无文件夹授权数据
';
+          if (overviewScopesEl) overviewScopesEl.textContent = '-';
+          return;
+        }
+      }
+
+      setText(accessScopesJson, payload);
+      setText(accessScopesMessage, '');
+
+      var scopes = payload && (payload.allowedRoots || payload.allowed_roots || payload.scopes || payload.accessScopes || payload.access_scopes || payload.grants || []);
+      if (overviewScopesEl) {
+        overviewScopesEl.textContent = String(Array.isArray(scopes) ? scopes.length : 0);
+      }
+
+      if (accessScopesList && Array.isArray(scopes)) {
+        if (scopes.length === 0) {
+          accessScopesList.innerHTML = '
暂无文件夹授权
';
+        } else {
+          accessScopesList.innerHTML = scopes.map(function(s) {
+            var path = escapeHtml(s.rootPath || s.rootUri || s.path || s.folder || '-');
+            var permission = s.permission || 'read';
+            var meta = escapeHtml(s.source || s.scope || '');
+            var permBadge = permission === 'write'
+              ? renderBadge('读写', 'mnote-ai-admin-badge--active')
+              : renderBadge('只读');
+            return '
' +
+              '
' +
+              '
' + path + '
' +
+              '
' + meta + '
' +
+              '
' +
+              '
' + permBadge + '
' +
+              '
';
+          }).join('');
+        }
+      }
+    }
+
+    async function loadSessionsAndReceipts() {
+      var sessionsPayload = await requestJson('/api/page-ai/pi/sessions?limit=20', { method: 'GET' });
+      var receiptsUrl = isAdmin ? '/api/ai-admin/receipts?limit=50' : '/api/ai-settings/receipts?limit=50';
+      var receiptsPayload = await requestJson(receiptsUrl, { method: 'GET' });
+      var sessions = sessionsPayload.sessions || [];
+      var receipts = receiptsPayload.receipts || [];
+
+      if (sessionsBody) {
+        sessionsBody.innerHTML = sessions.length ? sessions.map(function(s) {
+          return '' + escapeHtml(s.title || s.preview || s.sessionId || '-') + '' +
+            '' + escapeHtml(s.modelId || s.modelProvider || '-') + '' +
+            '' + renderBadge(s.status || 'unknown', s.status === 'runtime_running' ? 'mnote-ai-admin-badge--active' : '') + '' +
+            '' + escapeHtml(s.updatedAt || '-') + '';
+        }).join('') : '暂无 Pi Lab 会话';
+      }
+
+      if (receiptsBody) {
+        receiptsBody.innerHTML = receipts.length ? receipts.map(function(r) {
+          var allowed = r.allowed === true;
+          return '' + escapeHtml(r.toolName || r.tool_name || '-') + '' +
+            '' + renderBadge(allowed ? '允许' : '拒绝', allowed ? 'mnote-ai-admin-badge--active' : '') + '' +
+            '' + escapeHtml(r.diffSummary || r.diff_summary || r.denyReason || r.deny_reason || '-') + '' +
+            '' + escapeHtml(r.createdAt || r.created_at || '-') + '';
+        }).join('') : '暂无工具回执';
+      }
+      if (receiptsSummary) {
+        receiptsSummary.textContent = '会话 ' + sessions.length + ' · 回执 ' +
+          (receiptsPayload.receiptCount || receipts.length) + ' · 文件补丁 ' +
+          (receiptsPayload.patchCount || 0);
+      }
+      if (usageSummary) {
+        usageSummary.innerHTML = '
' +
+          '
Pi Lab 会话
' + sessions.length + '
来自 ai_runtime_runs
' +
+          '
工具回执
' + (receiptsPayload.receiptCount || receipts.length) + '
来自 ai_tool_events
' +
+          '
文件补丁
' + (receiptsPayload.patchCount || 0) + '
来自 ai_file_patches
' +
+          '
';
+      }
+    }
+
+    // ════════════════════════════════════════════════
+    // 3. Config 内联编辑 — 模型/工具/技能 MCP
+    // ════════════════════════════════════════════════
+
+    // configData 保存最后一次 GET 到的全量配置
+    var configData = { providers: [], toolPolicies: [], skills: [], mcpServers: [] };
+
+    function objectValuesWithId(value) {
+      return Object.keys(value || {}).map(function(id) {
+        return { id: id, ...(value[id] || {}) };
+      });
+    }
+
+    function renderProviderConfig(providers) {
+      if (!modelsContainer) return;
+      if (!providers || !providers.length) {
+        modelsContainer.innerHTML = '
暂未配置 Provider
';
+        return;
+      }
+      var html = '';
+      providers.forEach(function(p, idx) {
+        var allowedModels = Array.isArray(p.allowedModels) ? p.allowedModels.join(', ') : (p.allowedModels || '');
+        var failover = Array.isArray(p.failoverChains) ? p.failoverChains.join(', ') : (p.failoverChains || '');
+        var disabledAttr = isAdmin ? '' : ' disabled';
+        html += '
';
+        html += '
';
+        html += '' + escapeHtml(p.name || p.id || 'Provider ' + (idx + 1)) + '';
+        html += '' +
+          renderTag(p.enabled !== false ? '已连接' : '未连接', p.enabled !== false ? 'green' : 'orange') +
+          renderTag((Array.isArray(p.allowedModels) ? p.allowedModels.length : 0) + ' 个模型', 'blue') +
+          '';
+        if (idx > 0 && isAdmin) {
+          html += '';
+        }
+        html += '
';
+        html += '
';
+        html += '
';
+        html += '
';
+        html += '
';
+        html += '
';
+        html += '
';
+        html += '
引用环境变量名，前端不出现 raw key
';
+        html += '
';
+        html += '
';
+        html += '
';
+        html += '
';
+        var allModels = Array.isArray(p.allowedModels) ? p.allowedModels : [];
+        html += '
';
+        html += '
';
+        html += '
';
+        html += '
';
+        html += '
';
+        html += '
';
+        html += '
';
+        html += '
';
+        html += '
';
+        html += '
';
+        html += '
';
+        html += '
';
+      });
+      modelsContainer.innerHTML = '
' + html;
+
+      // 绑定删除事件
+      if (isAdmin) {
+        modelsContainer.querySelectorAll('[data-action="delete-provider"]').forEach(function(btn) {
+          btn.addEventListener('click', function() {
+            var idx = parseInt(btn.getAttribute('data-idx'), 10);
+            if (!isNaN(idx) && configData.providers && configData.providers.length > idx) {
+              configData.providers.splice(idx, 1);
+              renderProviderConfig(configData.providers);
+            }
+          });
+        });
+      }
+      var providerFilter = modelsContainer.querySelector('[data-ai-admin-filter="providers"]');
+      if (providerFilter) {
+        providerFilter.addEventListener('input', function() {
+          var q = providerFilter.value.trim().toLowerCase();
+          modelsContainer.querySelectorAll('[data-provider-idx]').forEach(function(card) {
+            card.style.display = !q || card.textContent.toLowerCase().includes(q) ? '' : 'none';
+          });
+        });
+      }
+    }
+
+    function renderToolsConfig(tools) {
+      if (!toolsContainer) return;
+      if (!tools || !tools.length) {
+        toolsContainer.innerHTML = '
暂未配置工具策略
';
+        return;
+      }
+      var riskGroups = { dangerous: 0, moderate: 0, safe: 0, custom: 0 };
+      tools.forEach(function(t) {
+        var risk = t.riskLevel || t.risk_level || t.risk || 'custom';
+        if (!riskGroups.hasOwnProperty(risk)) risk = 'custom';
+        riskGroups[risk] += 1;
+      });
+      var stats = '
' +
+        '
🔒 危险：' + riskGroups.dangerous + '
' +
+        '
？ 敏感：' + riskGroups.moderate + '
' +
+        '
✓ 安全：' + riskGroups.safe + '
' +
+        '
⌁ 自定义：' + riskGroups.custom + '
' +
+        '
';
+      var search = '
';
+      var rows = tools.map(function(t, idx) {
+        var disabledAttr = isAdmin ? '' : ' disabled';
+        return '' +
+          '' + renderTag(t.name || '-', 'blue') + '' +
+          '' + escapeHtml(t.description || '-') + '' +
+          '' +
+          '' + renderTag(t.defaultPolicy || 'allow', t.defaultPolicy === 'deny' ? 'red' : (t.defaultPolicy === 'ask' ? 'orange' : 'green')) + '' +
+        '';
+      }).join('');
+      toolsContainer.innerHTML = stats + search + '
' + rows + '
工具说明策略当前
';
+      var toolFilter = toolsContainer.querySelector('[data-ai-admin-filter="tools"]');
+      if (toolFilter) {
+        toolFilter.addEventListener('input', function() {
+          var q = toolFilter.value.trim().toLowerCase();
+          toolsContainer.querySelectorAll('tbody tr').forEach(function(row) {
+            row.style.display = !q || row.textContent.toLowerCase().includes(q) ? '' : 'none';
+          });
+        });
+      }
+    }
+
+    function renderSkillsConfig(skills) {
+      if (!skillsContainer) return;
+      if (!skills || !skills.length) {
+        skillsContainer.innerHTML = '
暂未配置 Skills
';
+        return;
+      }
+      var enabledCount = skills.filter(function(s) { return s.enabled !== false; }).length;
+      var items = skills.map(function(s, idx) {
+        var disabledAttr = isAdmin ? '' : ' disabled';
+        return '
' +
+          '
' +
+          '
' +
+          '' +
+          '' +
+          '
' +
+          '
' +
+          '' +
+          (isAdmin ? '' : '') +
+        '
';
+      }).join('');
+      skillsContainer.innerHTML =
+        '
✓ 已启用：' + enabledCount + '/' + skills.length + '
' +
+        '
' +
+        items;
+
+      if (isAdmin) {
+        skillsContainer.querySelectorAll('[data-action="delete-skill"]').forEach(function(btn) {
+          btn.addEventListener('click', function() {
+            var idx = parseInt(btn.getAttribute('data-idx'), 10);
+            if (!isNaN(idx) && configData.skills && configData.skills.length > idx) {
+              configData.skills.splice(idx, 1);
+              renderSkillsConfig(configData.skills);
+            }
+          });
+        });
+      }
+      var skillFilter = skillsContainer.querySelector('[data-ai-admin-filter="skills"]');
+      if (skillFilter) {
+        skillFilter.addEventListener('input', function() {
+          var q = skillFilter.value.trim().toLowerCase();
+          skillsContainer.querySelectorAll('[data-skill-idx]').forEach(function(row) {
+            row.style.display = !q || row.textContent.toLowerCase().includes(q) ? '' : 'none';
+          });
+        });
+      }
+    }
+
+    function renderMCPConfig(mcpServers) {
+      if (!mcpContainer) return;
+      if (!mcpServers || !mcpServers.length) {
+        mcpContainer.innerHTML = '
暂未配置 MCP Server
';
+        return;
+      }
+      var items = mcpServers.map(function(s, idx) {
+        var disabledAttr = isAdmin ? '' : ' disabled';
+        var secretRefsStr = Array.isArray(s.secretRefs) ? s.secretRefs.join(', ') : (s.secretRefs || '');
+        return '
' +
+          '
' +
+          '' + escapeHtml(s.name || s.id || 'MCP ' + (idx + 1)) + '' +
+          '' +
+          renderTag(s.transport || 'stdio', 'blue') +
+          renderTag(s.facadeOnly !== false ? 'facade-only' : 'raw', s.facadeOnly !== false ? 'green' : 'orange') +
+          '' +
+          (isAdmin ? '' : '') +
+          '
' +
+          '
' +
+          '
' +
+          '
' +
+          '
' +
+          '
' +
+          '
' +
+          '
' +
+          '
' +
+          '
' +
+          '
' +
+          '
仅允许 env:// 或 secret:// 引用
' +
+          '
' +
+          '
' +
+          '' +
+          '
' +
+          '
';
+      }).join('');
+      mcpContainer.innerHTML = '
' + items;
+
+      if (isAdmin) {
+        mcpContainer.querySelectorAll('[data-action="delete-mcp"]').forEach(function(btn) {
+          btn.addEventListener('click', function() {
+            var idx = parseInt(btn.getAttribute('data-idx'), 10);
+            if (!isNaN(idx) && configData.mcpServers && configData.mcpServers.length > idx) {
+              configData.mcpServers.splice(idx, 1);
+              renderMCPConfig(configData.mcpServers);
+            }
+          });
+        });
+      }
+      var mcpFilter = mcpContainer.querySelector('[data-ai-admin-filter="mcp"]');
+      if (mcpFilter) {
+        mcpFilter.addEventListener('input', function() {
+          var q = mcpFilter.value.trim().toLowerCase();
+          mcpContainer.querySelectorAll('[data-mcp-idx]').forEach(function(card) {
+            card.style.display = !q || card.textContent.toLowerCase().includes(q) ? '' : 'none';
+          });
+        });
+      }
+    }
+
+    function collectProvidersFromDOM() {
+      if (!modelsContainer) return [];
+      var cards = modelsContainer.querySelectorAll('.mnote-ai-admin-provider-card');
+      return Array.from(cards).map(function(card) {
+        function val(field) {
+          var el = card.querySelector('[data-field="' + field + '"]');
+          if (!el) return '';
+          if (el.type === 'checkbox') return el.checked;
+          return el.value;
+        }
+        var allowedRaw = val('allowedModels');
+        var failoverRaw = val('failoverChains');
+        return {
+          id: val('id'),
+          name: val('name'),
+          baseUrl: val('baseUrl'),
+          secretRef: val('secretRef'),
+          allowedModels: allowedRaw ? allowedRaw.split(',').map(function(s) { return s.trim(); }).filter(Boolean) : [],
+          defaultModel: val('defaultModel'),
+          defaultBuildModel: val('defaultBuildModel'),
+          defaultPlanModel: val('defaultPlanModel'),
+          defaultTaskModel: val('defaultTaskModel'),
+          failoverChains: failoverRaw ? failoverRaw.split(',').map(function(s) { return s.trim(); }).filter(Boolean) : [],
+          enabled: val('enabled')
+        };
+      });
+    }
+
+    function collectToolsFromDOM() {
+      if (!toolsContainer) return [];
+      var selects = toolsContainer.querySelectorAll('[data-tool-idx]');
+      var tools = [];
+      selects.forEach(function(sel) {
+        var idx = parseInt(sel.getAttribute('data-tool-idx'), 10);
+        if (!isNaN(idx) && configData.toolPolicies && configData.toolPolicies[idx]) {
+          tools[idx] = tools[idx] || JSON.parse(JSON.stringify(configData.toolPolicies[idx]));
+          tools[idx].defaultPolicy = sel.value;
+        }
+      });
+      return tools.filter(Boolean);
+    }
+
+    function collectSkillsFromDOM() {
+      if (!skillsContainer) return [];
+      var toggles = skillsContainer.querySelectorAll('[data-field="skill-enabled"]');
+      var skills = [];
+      toggles.forEach(function(tog) {
+        var idx = parseInt(tog.getAttribute('data-idx'), 10);
+        if (!isNaN(idx) && configData.skills && configData.skills[idx]) {
+          skills[idx] = skills[idx] || JSON.parse(JSON.stringify(configData.skills[idx]));
+          skills[idx].enabled = tog.checked;
+          var nameEl = skillsContainer.querySelector('[data-field="skill-name"][data-idx="' + idx + '"]');
+          var descriptionEl = skillsContainer.querySelector('[data-field="skill-description"][data-idx="' + idx + '"]');
+          skills[idx].name = nameEl ? nameEl.value.trim() : skills[idx].name;
+          skills[idx].description = descriptionEl ? descriptionEl.value.trim() : '';
+        }
+      });
+      return skills.filter(Boolean);
+    }
+
+    function collectMCPFromDOM() {
+      if (!mcpContainer) return [];
+      var cards = mcpContainer.querySelectorAll('[data-mcp-idx]');
+      var mcps = [];
+      cards.forEach(function(card) {
+        var idx = parseInt(card.getAttribute('data-mcp-idx'), 10);
+        if (isNaN(idx) || !configData.mcpServers || !configData.mcpServers[idx]) return;
+        function val(field) {
+          var el = card.querySelector('[data-field="' + field + '"][data-idx="' + idx + '"]');
+          if (!el) return '';
+          if (el.type === 'checkbox') return el.checked;
+          return el.value;
+        }
+        mcps[idx] = JSON.parse(JSON.stringify(configData.mcpServers[idx]));
+        mcps[idx].name = val('mcp-name');
+        mcps[idx].enabled = val('mcp-enabled');
+        mcps[idx].transport = val('mcp-transport');
+        mcps[idx].command = val('mcp-command');
+        mcps[idx].url = val('mcp-url');
+        mcps[idx].networkPolicy = val('mcp-network');
+        var secretsRaw = val('mcp-secrets');
+        mcps[idx].secretRefs = secretsRaw ? secretsRaw.split(',').map(function(s) { return s.trim(); }).filter(Boolean) : [];
+        mcps[idx].facadeOnly = val('mcp-facade');
+        mcps[idx].sandbox = true;
+      });
+      return mcps.filter(Boolean);
+    }
+
+    // ── 添加空条目 ──
+    function addEmptyProvider() {
+      if (!configData.providers) configData.providers = [];
+      configData.providers.push({
+        id: '', name: '', baseUrl: '', secretRef: '',
+        allowedModels: [], defaultModel: '', defaultBuildModel: '',
+        defaultPlanModel: '', defaultTaskModel: '', failoverChains: [],
+        enabled: true
+      });
+      renderProviderConfig(configData.providers);
+    }
+
+    function addEmptySkill() {
+      if (!configData.skills) configData.skills = [];
+      configData.skills.push({ id: '', name: '', description: '', enabled: true });
+      renderSkillsConfig(configData.skills);
+    }
+
+    function addEmptyMCP() {
+      if (!configData.mcpServers) configData.mcpServers = [];
+      configData.mcpServers.push({
+        id: '', name: '', description: '', enabled: true,
+        transport: 'stdio', command: '', url: '',
+        networkPolicy: 'deny-all', secretRefs: [], facadeOnly: true
+      });
+      renderMCPConfig(configData.mcpServers);
+    }
+
+    // ── 加载 config ──
+    async function loadConfig() {
+      var payload;
+      try {
+        payload = await requestJson('/api/ai-admin/settings', { method: 'GET' });
+      } catch (err) {
+        if (modelsContainer) modelsContainer.innerHTML = '
模型配置 API 暂不可用
';
+        if (toolsContainer) toolsContainer.innerHTML = '
工具配置 API 暂不可用
';
+        if (skillsContainer) skillsContainer.innerHTML = '
技能配置 API 暂不可用
';
+        if (mcpContainer) mcpContainer.innerHTML = '
MCP 配置 API 暂不可用
';
+        return;
+      }
+
+      configData.providers = objectValuesWithId(payload.providers);
+      configData.toolPolicies = (payload.toolCatalog || []).map(function(tool) {
+        return { ...tool, defaultPolicy: (payload.tools || {})[tool.name] || tool.defaultPolicy };
+      });
+      configData.skills = objectValuesWithId(payload.skills);
+      configData.mcpServers = objectValuesWithId(payload.mcpServers);
+
+      renderProviderConfig(configData.providers);
+      renderToolsConfig(configData.toolPolicies);
+      renderSkillsConfig(configData.skills);
+      renderMCPConfig(configData.mcpServers);
+    }
+
+    // ── 保存 config ──
+    async function saveConfig(scope) {
+      var body = {};
+      if (scope === 'models' || !scope) {
+        var providers = collectProvidersFromDOM();
+        body.providers = {};
+        body.allowedModels = [];
+        providers.forEach(function(provider) {
+          if (!provider.id) return;
+          body.providers[provider.id] = {
+            name: provider.name,
+            enabled: provider.enabled,
+            secretRef: provider.secretRef,
+            defaultModel: provider.defaultModel,
+            baseUrl: provider.baseUrl,
+            allowedModels: provider.allowedModels,
+            defaultBuildModel: provider.defaultBuildModel,
+            defaultPlanModel: provider.defaultPlanModel,
+            defaultTaskModel: provider.defaultTaskModel,
+            failoverChains: provider.failoverChains
+          };
+          body.allowedModels = body.allowedModels.concat(provider.allowedModels);
+          if (!body.defaultModel && provider.defaultModel) body.defaultModel = provider.defaultModel;
+          if (!body.buildPlanTask) {
+            body.buildPlanTask = {
+              default: provider.defaultBuildModel || provider.defaultModel || '',
+              failover: provider.failoverChains || []
+            };
+          }
+        });
+      }
+      if (scope === 'tools' || !scope) {
+        body.tools = {};
+        collectToolsFromDOM().forEach(function(tool) {
+          body.tools[tool.name] = tool.defaultPolicy;
+        });
+      }
+      if (scope === 'skills' || !scope) {
+        body.skills = {};
+        collectSkillsFromDOM().forEach(function(skill) {
+          var id = skill.id || skill.name;
+          if (!id) return;
+          body.skills[id] = {
+            name: skill.name,
+            enabled: skill.enabled,
+            description: skill.description || ''
+          };
+        });
+        body.mcpServers = {};
+        collectMCPFromDOM().forEach(function(server) {
+          var id = server.id || server.name;
+          if (!id) return;
+          body.mcpServers[id] = {
+            name: server.name,
+            enabled: server.enabled,
+            url: server.url || '',
+            transport: server.transport || 'stdio',
+            command: server.command || '',
+            networkPolicy: server.networkPolicy || 'deny-all',
+            secretRefs: server.secretRefs || [],
+            facadeOnly: server.facadeOnly !== false,
+            sandbox: true
+          };
+        });
+      }
+
+      try {
+        await requestJson('/api/ai-admin/settings', {
+          method: 'PUT',
+          body: JSON.stringify(body),
+        });
+        await loadConfig();
+        if (scope === 'models') {
+          showSaveStatus(modelsSaveStatus, 'success', '模型配置已保存');
+        } else if (scope === 'tools') {
+          showSaveStatus(toolsSaveStatus, 'success', '工具策略已保存');
+        } else if (scope === 'skills') {
+          showSaveStatus(skillsSaveStatus, 'success', '技能/MCP 配置已保存');
+        }
+      } catch (err) {
+        if (scope === 'models') {
+          showSaveStatus(modelsSaveStatus, 'error', '保存失败: ' + (err.message || '未知错误'));
+        } else if (scope === 'tools') {
+          showSaveStatus(toolsSaveStatus, 'error', '保存失败: ' + (err.message || '未知错误'));
+        } else if (scope === 'skills') {
+          showSaveStatus(skillsSaveStatus, 'error', '保存失败: ' + (err.message || '未知错误'));
+        }
+      }
+    }
+
+    // ── 绑定保存/添加按钮 ──
+    if (isAdmin) {
+      var saveModelsBtn = root.querySelector('[data-action="save-models"]');
+      if (saveModelsBtn) {
+        saveModelsBtn.addEventListener('click', function () { saveConfig('models'); });
+      }
+      var saveToolsBtn = root.querySelector('[data-action="save-tools"]');
+      if (saveToolsBtn) {
+        saveToolsBtn.addEventListener('click', function () { saveConfig('tools'); });
+      }
+      var saveSkillsBtn = root.querySelector('[data-action="save-skills"]');
+      if (saveSkillsBtn) {
+        saveSkillsBtn.addEventListener('click', function () { saveConfig('skills'); });
+      }
+      var addProviderBtn = root.querySelector('[data-action="add-provider"]');
+      if (addProviderBtn) {
+        addProviderBtn.addEventListener('click', addEmptyProvider);
+      }
+      var addSkillBtn = root.querySelector('[data-action="add-skill"]');
+      if (addSkillBtn) {
+        addSkillBtn.addEventListener('click', addEmptySkill);
+      }
+      var addMCPBtn = root.querySelector('[data-action="add-mcp"]');
+      if (addMCPBtn) {
+        addMCPBtn.addEventListener('click', addEmptyMCP);
+      }
+    }
+
+    // ── 启动 ──
+    loadEffective().catch(function (err) {
+      if (effectiveJson) setText(effectiveJson, { error: err.message || '加载失败' });
+    });
+    loadAccessScopes().catch(function (err) {
+      if (accessScopesMessage) setText(accessScopesMessage, err.message || '加载失败');
+    });
+    loadSessionsAndReceipts().catch(function (err) {
+      if (receiptsSummary) setText(receiptsSummary, err.message || '加载会话与回执失败');
+    });
+    loadConfig().catch(function (err) {
+      // 静默处理，各个容器已显示错误状态
+      console.warn('loadConfig 失败:', err && err.message);
+    });
+    loadUsers().catch(function (err) {
+      if (userSettingsEditor) userSettingsEditor.innerHTML = '
' + escapeHtml(err.message || '加载用户失败') + '
';
+    });
+  }
+
+  window.MNOTEInitAiAdminPage = initAiAdminPage;
+  var shell = document.body && document.body.getAttribute('data-mnote-shell');
+  if (shell === 'admin' || shell === 'user-ai-admin' || document.querySelector('[data-testid="mnote-ai-admin-page"]')) {
+    initAiAdminPage(document);
+  }
+  document.addEventListener('DOMContentLoaded', function () { initAiAdminPage(document); }, { once: true });
+})();
+"#;
+
+/// MNOTE AI 管理页面
+///
+/// 左侧分页导航，包含概览、模型配置、工具权限、技能/MCP 等面板。
+/// 模型/工具/技能面板由 JS 读取 config API 后渲染内联编辑表单。
+/// 用户模式下所有编辑控件禁用。
+#[component]
+pub fn AiManagementPage(
+    #[prop(optional)] workspace_name: Option,
+    #[prop(optional, default = true)] is_admin: bool,
+) -> impl IntoView {
+    let workspace_name = workspace_name
+        .map(|v| v.trim().to_string())
+        .filter(|v| !v.is_empty())
+        .unwrap_or_else(|| "工作区".to_string());
+
+    let role_text = if is_admin {
+        "管理员模式 — 可管理 AI Providers 和访问策略"
+    } else {
+        "用户模式 — 查看 AI 配置与已授权文件夹"
+    };
+
+    let access_policy_href = if is_admin {
+        "/admin/access-policy"
+    } else {
+        "/user/access-policy"
+    };
+
+    let access_policy_label = if is_admin {
+        "前往管理员授权管理"
+    } else {
+        "查看我的文件夹授权"
+    };
+
+    let config_json = format!(
+        r#"{{"isAdmin":{},"workspaceName":"{}"}}"#,
+        if is_admin { "true" } else { "false" },
+        workspace_name.replace('"', "\\\"")
+    );
+
+    view! {
+        

+            
+            
+
+            

+                
+                

+                    

+                        "首页"
+                        "/"
+                        "管理后台"
+                    

+                    

+                        

+                            
"AI 管理"

+                            
{role_text}

+                        

+
+            // ════════════════════════════════════════
+            // 1. 概览 (Overview)
+            // ════════════════════════════════════════
+            

+                

+                    

+                        
"概览"

+                        
"AI 服务运行状态摘要"

+                    

+                

+                

+                    

+                        

+                            "AI Providers"
+                            "..."
+                            "已配置 provider 数量"
+                        

+                        

+                            "可用模型"
+                            "..."
+                            "模型配置数"
+                        

+                        

+                            "已授权文件夹"
+                            "..."
+                            "AI 可访问的本地文件夹数"
+                        

+                        

+                            "工作区"
+                            {workspace_name.clone()}
+                            "当前上下文"
+                        

+                    

+                

+            

+
+            
+
+            // ════════════════════════════════════════
+            // 2. 模型配置（内联编辑）
+            // ════════════════════════════════════════
+            
+
+            
+
+            
+
+            // ════════════════════════════════════════
+            // 3. 工具权限（内联编辑）
+            // ════════════════════════════════════════
+            
+
+            // ════════════════════════════════════════
+            // 4. 技能 / MCP（内联编辑）
+            // ════════════════════════════════════════
+            
+
+            // ════════════════════════════════════════
+            // 5. Access Scopes（只读）
+            // ════════════════════════════════════════
+            
+
+            
+
+            
+
+            // ════════════════════════════════════════
+            // 6. Sessions & Receipts
+            // ════════════════════════════════════════
+            
+
+            
+
+                    

+                

+            

+
+            

+                

+                
+            

+
+            
+            
+        

+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::ssr::render_view;
+
+    #[test]
+    fn ai_admin_page_renders_all_panels() {
+        let html = render_view(view! {
+            
+        });
+        assert!(html.contains("mnote-ai-admin-page"));
+        assert!(html.contains("data-ai-admin-role=\"admin\""));
+        assert!(html.contains("概览"));
+        assert!(html.contains("模型配置"));
+        assert!(html.contains("Access Scopes"));
+        assert!(html.contains("Sessions & Receipts"));
+        assert!(html.contains("技能 / MCP"));
+        assert!(html.contains("工具权限"));
+        assert!(html.contains("AI 管理"));
+    }
+
+    #[test]
+    fn ai_admin_page_user_mode_hides_admin_buttons() {
+        let html = render_view(view! {
+            
+        });
+        assert!(html.contains("data-ai-admin-role=\"user\""));
+        assert!(html.contains("用户模式 — 查看 AI 配置与已授权文件夹"));
+        assert!(html.contains("/user/access-policy"));
+        assert!(html.contains("查看我的文件夹授权"));
+        // 内嵌脚本包含 action 字符串；用户态由 isAdmin=false 禁用编辑。
+        assert!(html.contains(r#""isAdmin":false"#));
+        assert!(AI_ADMIN_SCRIPT.contains("var disabledAttr = isAdmin ? '' : ' disabled'"));
+    }
+
+    #[test]
+    fn ai_admin_page_admin_mode_shows_save_and_add_buttons() {
+        let html = render_view(view! {
+            
+        });
+        assert!(html.contains("data-ai-admin-role=\"admin\""));
+        assert!(html.contains("管理员模式 — 可管理 AI Providers 和访问策略"));
+        assert!(html.contains("/admin/access-policy"));
+        assert!(html.contains("前往管理员授权管理"));
+        // Admin 模式下有保存和添加按钮
+        assert!(html.contains("data-action=\"save-models\""));
+        assert!(html.contains("data-action=\"save-tools\""));
+        assert!(html.contains("data-action=\"save-skills\""));
+        assert!(html.contains("data-action=\"add-provider\""));
+        assert!(html.contains("data-action=\"add-skill\""));
+        assert!(html.contains("data-action=\"add-mcp\""));
+    }
+
+    #[test]
+    fn ai_admin_page_has_editable_containers_for_models_tools_skills() {
+        let html = render_view(view! {
+            
+        });
+        // 面板容器 data 属性
+        assert!(html.contains("data-ai-admin-models-container"));
+        assert!(html.contains("data-ai-admin-tools-container"));
+        assert!(html.contains("data-ai-admin-skills-container"));
+        assert!(html.contains("data-ai-admin-users-list"));
+        assert!(html.contains("data-ai-admin-user-settings"));
+        assert!(html.contains("/api/ai-admin/users/"));
+        assert!(html.contains("data-ai-admin-mcp-container"));
+        // 保存状态容器
+        assert!(html.contains("data-ai-admin-models-save-status"));
+        assert!(html.contains("data-ai-admin-tools-save-status"));
+        assert!(html.contains("data-ai-admin-skills-save-status"));
+    }
+
+    #[test]
+    fn ai_admin_page_has_access_policy_link_and_no_access_scopes_write_forms() {
+        let html = render_view(view! {
+            
+        });
+        assert!(html.contains("data-testid=\"mnote-ai-admin-access-policy-link\""));
+        assert!(html.contains("/admin/access-policy"));
+
+        // 不得有 access-scopes 写请求表单或按钮
+        assert!(!html.contains("data-admin-form=\"create-share-grant\""));
+        assert!(!html.contains("data-admin-action=\"revoke-access-grant\""));
+        assert!(!html.contains("mnote-admin-create-share-grant-submit"));
+        assert!(!html.contains("name=\"rootPath\""));
+        assert!(!html.contains("name=\"targetUserId\""));
+    }
+
+    #[test]
+    fn ai_admin_page_script_fetches_config_effective_and_access_scopes() {
+        assert!(AI_ADMIN_SCRIPT.contains("/api/ai-admin/settings"));
+        assert!(AI_ADMIN_SCRIPT.contains("/api/ai-admin/effective"));
+        assert!(AI_ADMIN_SCRIPT.contains("/api/ai-admin/access-scopes"));
+        assert!(AI_ADMIN_SCRIPT.contains("/api/ai-settings/effective"));
+        assert!(AI_ADMIN_SCRIPT.contains("/api/ai-settings/access-scopes"));
+        // 脚本包含保存逻辑
+        assert!(AI_ADMIN_SCRIPT.contains("PUT"));
+        assert!(AI_ADMIN_SCRIPT.contains("saveConfig"));
+        assert!(AI_ADMIN_SCRIPT.contains("loadConfig"));
+    }
+
+    #[test]
+    fn ai_admin_page_contains_edit_form_css() {
+        let html = render_view(view! {
+            
+        });
+        assert!(html.contains("mnote-ai-admin-input"));
+        assert!(html.contains("mnote-ai-admin-select"));
+        assert!(html.contains("mnote-ai-admin-btn"));
+        assert!(html.contains("mnote-ai-admin-btn--primary"));
+        assert!(html.contains("mnote-ai-admin-toggle"));
+        assert!(html.contains("mnote-ai-admin-save-status"));
+        assert!(html.contains("mnote-ai-admin-provider-card"));
+    }
+
+    #[test]
+    fn ai_admin_page_stress_default_props() {
+        let html = render_view(view! {
+            
+        });
+        assert!(html.contains("mnote-ai-admin-page"));
+        assert!(html.contains("data-ai-admin-role=\"admin\""));
+    }
+
+    #[test]
+    fn ai_admin_page_script_provides_model_role_default_dropdowns() {
+        // 脚本应包含 Build/Plan/Task 模型下拉选择和 failover 输入
+        assert!(AI_ADMIN_SCRIPT.contains("defaultBuildModel"));
+        assert!(AI_ADMIN_SCRIPT.contains("defaultPlanModel"));
+        assert!(AI_ADMIN_SCRIPT.contains("defaultTaskModel"));
+        assert!(AI_ADMIN_SCRIPT.contains("failoverChains"));
+        assert!(AI_ADMIN_SCRIPT.contains("allowedModels"));
+    }
+
+    #[test]
+    fn ai_admin_page_script_tool_policy_has_allow_ask_deny() {
+        // 工具策略应包含三个选项
+        assert!(AI_ADMIN_SCRIPT.contains("value=\"allow\""));
+        assert!(AI_ADMIN_SCRIPT.contains("value=\"ask\""));
+        assert!(AI_ADMIN_SCRIPT.contains("value=\"deny\""));
+    }
+
+    #[test]
+    fn ai_admin_page_script_mcp_has_required_fields() {
+        // MCP 编辑应包含 transport/command/url/network/secret/facade
+        assert!(AI_ADMIN_SCRIPT.contains("mcp-transport"));
+        assert!(AI_ADMIN_SCRIPT.contains("mcp-command"));
+        assert!(AI_ADMIN_SCRIPT.contains("mcp-url"));
+        assert!(AI_ADMIN_SCRIPT.contains("mcp-network"));
+        assert!(AI_ADMIN_SCRIPT.contains("mcp-secrets"));
+        assert!(AI_ADMIN_SCRIPT.contains("mcp-facade"));
+        // 只显示禁止明文密钥的说明，不提供 apiKey 字段。
+        assert!(!AI_ADMIN_SCRIPT.contains("apiKey"));
+    }
+
+    #[test]
+    fn ai_admin_page_script_uses_get_only_for_access_scopes() {
+        assert!(!AI_ADMIN_SCRIPT.contains("access-scopes', { method: 'POST'"));
+        assert!(!AI_ADMIN_SCRIPT.contains("access-scopes', { method: 'PUT'"));
+        assert!(!AI_ADMIN_SCRIPT.contains("access-scopes', { method: 'DELETE'"));
+    }
+}
diff --git a/rust/crates/mnote-web/src/ssr/pages/mod.rs b/rust/crates/mnote-web/src/ssr/pages/mod.rs
index d819cd77..f8eec362 100644
--- a/rust/crates/mnote-web/src/ssr/pages/mod.rs
+++ b/rust/crates/mnote-web/src/ssr/pages/mod.rs
@@ -1,6 +1,7 @@
 //! SSR 页面组件
 
 pub mod admin;
+pub mod ai_admin;
 pub mod auth;
 pub mod document;
 pub mod home;
diff --git a/scripts/desktop-hot.js b/scripts/desktop-hot.js
index 2f99db07..5399df55 100644
--- a/scripts/desktop-hot.js
+++ b/scripts/desktop-hot.js
@@ -415,6 +415,35 @@ function getProcessNameByPid(pid) {
   }
 }
 
+function getProcessCommandByPid(pid) {
+  if (process.platform === "win32") {
+    try {
+      const out = execSync(`wmic process where ProcessId=${pid} get CommandLine /value`, {
+        encoding: "utf8",
+      });
+      return out.replace(/^CommandLine=/m, "").trim();
+    } catch {
+      return "";
+    }
+  }
+
+  try {
+    return execSync(`ps -p ${pid} -o args=`, { encoding: "utf8" }).trim();
+  } catch {
+    return "";
+  }
+}
+
+function getProcessGroupByPid(pid) {
+  if (process.platform === "win32") return pid;
+  try {
+    const pgid = Number(execSync(`ps -p ${pid} -o pgid=`, { encoding: "utf8" }).trim());
+    return Number.isFinite(pgid) && pgid > 0 ? pgid : pid;
+  } catch {
+    return pid;
+  }
+}
+
 function terminatePid(pid) {
   if (process.platform === "win32") {
     execSync(`taskkill /PID ${pid} /T /F`, { stdio: "ignore" });
@@ -441,6 +470,84 @@ function forceKillPid(pid) {
   }
 }
 
+function terminateProcessGroup(pgid) {
+  if (process.platform === "win32") {
+    terminatePid(pgid);
+    return;
+  }
+  try {
+    process.kill(-pgid, "SIGTERM");
+  } catch {
+    terminatePid(pgid);
+  }
+}
+
+function forceKillProcessGroup(pgid) {
+  if (process.platform === "win32") {
+    forceKillPid(pgid);
+    return;
+  }
+  try {
+    process.kill(-pgid, "SIGKILL");
+  } catch {
+    forceKillPid(pgid);
+  }
+}
+
+function collectStaleMnoteWebCargoPids() {
+  if (process.platform === "win32") return [];
+  const currentPgid = getProcessGroupByPid(process.pid);
+  try {
+    const out = execSync("pgrep -f 'cargo (watch|run).*mnote-web|cargo-watch watch.*mnote-web'", {
+      encoding: "utf8",
+    });
+    return out
+      .split(/\r?\n/)
+      .map((line) => Number(line.trim()))
+      .filter((pid) => Number.isFinite(pid) && pid > 0 && pid !== process.pid)
+      .filter((pid) => getProcessGroupByPid(pid) !== currentPgid)
+      .filter((pid) => {
+        const command = getProcessCommandByPid(pid);
+        return !command.includes("pgrep -f");
+      });
+  } catch {
+    return [];
+  }
+}
+
+async function stopStaleMnoteWebCargoProcesses() {
+  const pids = collectStaleMnoteWebCargoPids();
+  if (pids.length === 0) return true;
+
+  const safePids = pids.filter((pid) => {
+    const command = getProcessCommandByPid(pid);
+    return (
+      command.includes("mnote-web") &&
+      command.includes("cargo") &&
+      (command.includes("cargo watch") ||
+        command.includes("cargo-watch watch") ||
+        command.includes("cargo run -p mnote-web"))
+    );
+  });
+  if (safePids.length === 0) return true;
+
+  const pgids = [...new Set(safePids.map(getProcessGroupByPid).filter((pgid) => pgid > 0))];
+  logPrefix("mnote-web", `检测到陈旧 cargo-watch/cargo run，先清理进程组：${pgids.join(", ")}`);
+  pgids.forEach(terminateProcessGroup);
+
+  for (let i = 0; i < 20; i += 1) {
+    // eslint-disable-next-line no-await-in-loop
+    await new Promise((r) => setTimeout(r, 150));
+    const remaining = collectStaleMnoteWebCargoPids().filter((pid) =>
+      safePids.includes(pid) || pgids.includes(getProcessGroupByPid(pid)),
+    );
+    if (remaining.length === 0) return true;
+  }
+
+  pgids.forEach(forceKillProcessGroup);
+  return true;
+}
+
 async function ensurePortFree(port, nameForLog) {
   const free = await isPortFree("127.0.0.1", port);
   if (free) return true;
@@ -665,6 +772,7 @@ async function main() {
   // 如果检测到 3000 被占用，则自动结束旧进程后重启，以保证始终跑在 3000。
   const desiredFrontendPort = runtimePlan.publicPort;
   const frontendOwnerName = "mnote-web";
+  await stopStaleMnoteWebCargoProcesses();
   const frontendPortOk = await ensurePortFree(desiredFrontendPort, frontendOwnerName);
   if (!frontendPortOk) {
     console.error(`前端端口 ${desiredFrontendPort} 无法释放，已中止启动。`);
@@ -762,8 +870,11 @@ module.exports = {
   buildDefaultOpencodeCommand,
   buildDefaultOpenHubCommand,
   checkOpenHubHealth,
+  collectStaleMnoteWebCargoPids,
   ensurePortFree,
   getListeningPidsByPort,
+  getProcessCommandByPid,
+  getProcessGroupByPid,
   getProcessNameByPid,
   isHttpHealthy,
   isPortFree,
@@ -772,5 +883,6 @@ module.exports = {
   resolveBackendExecutable,
   shouldStartBackend,
   shouldStartOpenHub,
+  stopStaleMnoteWebCargoProcesses,
   terminatePid,
 };
diff --git a/scripts/desktop-hot.test.js b/scripts/desktop-hot.test.js
index 1a3fecc7..99454569 100644
--- a/scripts/desktop-hot.test.js
+++ b/scripts/desktop-hot.test.js
@@ -5,6 +5,7 @@ const { test } = require("node:test");
 const {
   buildDefaultOpencodeCommand,
   buildDefaultOpenHubCommand,
+  collectStaleMnoteWebCargoPids,
   resolveBackendExecutable,
   ensurePortFree,
   isHttpHealthy,
@@ -13,6 +14,7 @@ const {
   resolveRuntimePlan,
   shouldStartBackend,
   shouldStartOpenHub,
+  stopStaleMnoteWebCargoProcesses,
 } = require("./desktop-hot.js");
 
 function findFreePort() {
@@ -120,6 +122,16 @@ test("ensurePortFree 在非 Windows 平台能释放后端监听进程", async (t
   await waitForExit(child);
 });
 
+test("陈旧 mnote-web cargo 清理不会匹配当前测试进程", async () => {
+  if (process.platform === "win32") {
+    return;
+  }
+  const pids = collectStaleMnoteWebCargoPids();
+  assert.ok(Array.isArray(pids));
+  assert.equal(pids.includes(process.pid), false);
+  await stopStaleMnoteWebCargoProcesses();
+});
+
 test("默认热启动计划只使用 mnote-web 作为 3000 owner", () => {
   const plan = resolveRuntimePlan({
     FRONTEND_PORT: "3000",
diff --git a/scripts/task-ai-management-browser-smoke.js b/scripts/task-ai-management-browser-smoke.js
new file mode 100644
index 00000000..7148443c
--- /dev/null
+++ b/scripts/task-ai-management-browser-smoke.js
@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+"use strict";
+
+const assert = require("node:assert");
+const fs = require("node:fs");
+const path = require("node:path");
+const { chromium } = require("playwright");
+
+const BASE = process.env.MNOTE_AI_ADMIN_BASE || "http://127.0.0.1:3000";
+const OUTPUT_DIR = process.env.MNOTE_AI_ADMIN_OUTPUT_DIR
+  || path.join(__dirname, "..", "tmp", "ai-management-browser");
+const CHROMIUM_EXECUTABLE = process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE
+  || (fs.existsSync("/usr/bin/chromium-browser") ? "/usr/bin/chromium-browser" : "")
+  || (fs.existsSync("/usr/bin/chromium") ? "/usr/bin/chromium" : "")
+  || (fs.existsSync("/usr/bin/google-chrome") ? "/usr/bin/google-chrome" : "");
+const E2E_USER_EMAIL = process.env.MNOTE_AI_ADMIN_E2E_EMAIL || "ai-user@example.com";
+const E2E_USER_NAME = process.env.MNOTE_AI_ADMIN_E2E_USERNAME || "ai-user";
+const E2E_USER_PASSWORD = process.env.MNOTE_AI_ADMIN_E2E_PASSWORD || ["Mnote", "E2E", "123!"].join("");
+
+async function quickLogin(page) {
+  await page.goto(`${BASE}/auth`, { waitUntil: "commit" });
+  const button = page.getByRole("button", { name: "测试账号快速登录" });
+  await button.waitFor({ state: "visible" });
+  await Promise.all([
+    page.waitForURL((url) => !url.pathname.includes("/auth")),
+    button.click(),
+  ]);
+}
+
+async function ensurePasswordUser(browser, user) {
+  const setupContext = await browser.newContext();
+  try {
+    const payload = (flow) => ({
+      action: "auth:signIn",
+      args: {
+        provider: "password",
+        params: {
+          email: user.email,
+          username: user.username,
+          name: user.name,
+          password: user.password,
+          flow,
+        },
+      },
+    });
+    let response = await setupContext.request.post(`${BASE}/api/auth`, {
+      data: payload("signIn"),
+    });
+    if (!response.ok()) {
+      response = await setupContext.request.post(`${BASE}/api/auth`, {
+        data: payload("signUp"),
+      });
+    }
+    assert(response.ok(), `测试用户 ${user.username} 准备失败: ${response.status()} ${await response.text()}`);
+  } finally {
+    await setupContext.close();
+  }
+}
+
+async function assertEventually(readValue, predicate, message, timeoutMs = 10000) {
+  const deadline = Date.now() + timeoutMs;
+  let lastValue;
+  while (Date.now() < deadline) {
+    lastValue = await readValue();
+    if (predicate(lastValue)) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  assert.fail(`${message}: ${JSON.stringify(lastValue)}`);
+}
+
+async function main() {
+  fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+  const runId = `${Date.now()}-${process.pid}`;
+  const skillName = `mnote-browser-smoke-${runId}`;
+  const mcpName = `lightrag-smoke-${runId}`;
+  const browser = await chromium.launch({
+    headless: process.env.MNOTE_AI_ADMIN_HEADED !== "1",
+    executablePath: CHROMIUM_EXECUTABLE || undefined,
+  });
+  await ensurePasswordUser(browser, {
+    email: E2E_USER_EMAIL,
+    username: E2E_USER_NAME,
+    name: E2E_USER_NAME,
+    password: E2E_USER_PASSWORD,
+  });
+  const context = await browser.newContext({ viewport: { width: 1440, height: 960 } });
+  const page = await context.newPage();
+
+  try {
+    await quickLogin(page);
+    const response = await page.goto(`${BASE}/admin/ai#ai-admin-models`, { waitUntil: "commit" });
+    assert(response && response.status() < 400, `AI 管理页加载失败: ${response && response.status()}`);
+    await page.locator('[data-testid="mnote-ai-admin-page"]').waitFor();
+    await page.locator("#ai-admin-models.is-active").waitFor();
+
+    const openHubLink = page.locator('a[href="/page-ai/openhub/admin"]');
+    assert(
+      await openHubLink.count() >= 1,
+      "OpenHub Admin 独立入口必须保留",
+    );
+
+    await page.getByRole("link", { name: "模型配置" }).click();
+    await page.locator("#ai-admin-models.is-active").waitFor();
+    const modelPanel = page.locator("#ai-admin-models");
+    await modelPanel.locator('[data-field="allowedModels"]').fill(
+      "omniroute/freefirst, omniroute/freefirst-fast",
+    );
+    await modelPanel.locator('[data-field="secretRef"]').fill("env://OMNIROUTE_API_KEY");
+    await modelPanel.getByRole("button", { name: "保存配置" }).click();
+    await modelPanel.locator("[data-ai-admin-models-save-status]").filter({ hasText: /已保存/ }).waitFor();
+    await page.screenshot({
+      path: path.join(OUTPUT_DIR, "models.png"),
+      fullPage: false,
+    });
+
+    await page.getByRole("link", { name: "工具权限" }).click();
+    await page.locator("#ai-admin-tools.is-active").waitFor();
+    const patchPolicy = page.locator('[data-ai-admin-tools-container] select').nth(4);
+    await patchPolicy.selectOption("ask");
+    await page.getByRole("button", { name: "保存策略" }).click();
+    await page.locator("[data-ai-admin-tools-save-status]").filter({ hasText: /已保存/ }).waitFor();
+
+    await page.getByRole("link", { name: "技能 / MCP" }).click();
+    await page.locator("#ai-admin-skills.is-active").waitFor();
+    await page.getByRole("button", { name: "+ 添加 Skill" }).click();
+    const skillRow = page.locator(".mnote-ai-admin-skill-row").last();
+    await skillRow.locator('[name="skillName"]').fill(skillName);
+    await skillRow.locator('[name="skillDescription"]').fill("浏览器验收技能");
+    await skillRow.locator('[name="skillEnabled"]').check();
+
+    await page.getByRole("button", { name: "+ 添加 MCP" }).click();
+    const mcpRow = page.locator("[data-mcp-idx]").last();
+    await mcpRow.locator('[name="mcpName"]').fill(mcpName);
+    await mcpRow.locator('[name="mcpTransport"]').selectOption("stdio");
+    await mcpRow.locator('[name="mcpCommand"]').fill("scripts/lightrag-native-mcp.sh");
+    await mcpRow.locator('[name="mcpSecretRefs"]').fill("env://LIGHTRAG_API_KEY");
+    await mcpRow.locator('[name="mcpEnabled"]').check();
+    const skillsPanel = page.locator("#ai-admin-skills");
+    await skillsPanel.getByRole("button", { name: "保存配置" }).click();
+    await assertEventually(
+      async () => (await skillsPanel.locator("[data-ai-admin-skills-save-status]").textContent()) || "",
+      (text) => text.includes("已保存"),
+      "技能/MCP 配置保存状态未变为已保存",
+    );
+    await page.screenshot({
+      path: path.join(OUTPUT_DIR, "skills-mcp.png"),
+      fullPage: false,
+    });
+
+    await page.getByRole("link", { name: "用户管理" }).click();
+    await page.locator("#ai-admin-users.is-active").waitFor();
+    const targetUser = page.locator('[data-ai-admin-users-list] [data-user-action="models"][data-user-id="ai-user"]');
+    await targetUser.waitFor();
+    await targetUser.click();
+    await page.locator('[data-ai-admin-user-settings] h3', { hasText: "ai-user" }).waitFor();
+    await page.locator('[data-user-model="omniroute/freefirst-fast"]').evaluate((input) => {
+      input.checked = false;
+      input.dispatchEvent(new Event("change", { bubbles: true }));
+    });
+    await page.locator('[data-action="save-user-settings"]').click();
+    await page.locator("[data-ai-admin-user-save-status]").filter({ hasText: /已保存/ }).waitFor();
+    await page.locator('[data-user-tab="skills"]').click();
+    await page.locator(`[data-user-skill="${skillName}"]`).evaluate((input) => {
+      input.checked = false;
+      input.dispatchEvent(new Event("change", { bubbles: true }));
+    });
+    await page.locator('[data-action="save-user-settings"]').click();
+    await page.locator("[data-ai-admin-user-save-status]").filter({ hasText: /已保存/ }).waitFor();
+    await page.screenshot({
+      path: path.join(OUTPUT_DIR, "users.png"),
+      fullPage: false,
+    });
+
+    await page.locator('[data-action="close-user-drawer"]').click();
+    await page.waitForFunction(() => {
+      const drawer = document.querySelector("[data-ai-admin-user-drawer]");
+      return !drawer || !drawer.classList.contains("is-open");
+    });
+    await page.getByRole("link", { name: "技能 / MCP" }).click();
+    await page.reload({ waitUntil: "commit" });
+    await page.locator("#ai-admin-skills.is-active").waitFor();
+    assert.equal(
+      await page.locator(`[name="skillName"][value="${skillName}"]`).count(),
+      1,
+      "Skill 保存后刷新必须仍存在",
+    );
+    assert.equal(
+      await page.locator(`[name="mcpName"][value="${mcpName}"]`).count(),
+      1,
+      "MCP 保存后刷新必须仍存在",
+    );
+
+    const effective = await page.evaluate(async () => {
+      const response = await fetch("/api/ai-settings/effective", { credentials: "include" });
+      return response.json();
+    });
+    assert.equal(effective.defaultModel, "omniroute/freefirst");
+    assert(
+      (effective.models || []).some((model) => model.id === "omniroute/freefirst-fast"),
+      "effective models 应包含管理员允许的模型",
+    );
+    assert(
+      (effective.skills || []).some((skill) => skill.name === skillName),
+      "effective skills 应包含已启用 skill",
+    );
+    assert(
+      (effective.mcpServers || []).some((server) => server.name === mcpName),
+      "effective MCP 应包含已启用 facade server",
+    );
+    const userSettings = await page.evaluate(async () => {
+      const response = await fetch("/api/ai-admin/users/ai-user/settings", { credentials: "include" });
+      return response.json();
+    });
+    assert.equal(
+      (userSettings.allowedModels || []).some((model) => model.id === "omniroute/freefirst-fast"),
+      false,
+      "ai-user 刷新后不应包含被禁用模型",
+    );
+    assert.equal(
+      (userSettings.skills || []).find((skill) => skill.id === skillName)?.enabled,
+      false,
+      "ai-user 刷新后应保留 Skill 禁用覆盖",
+    );
+
+    const userContext = await browser.newContext({ viewport: { width: 1280, height: 800 } });
+    const userResponse = await userContext.request.post(`${BASE}/api/auth`, {
+      data: {
+        action: "auth:signIn",
+        args: {
+          provider: "password",
+          params: {
+            email: E2E_USER_EMAIL,
+            username: E2E_USER_NAME,
+            name: E2E_USER_NAME,
+            password: E2E_USER_PASSWORD,
+            flow: "signIn",
+          },
+        },
+      },
+    });
+    assert(userResponse.ok(), `ai-user 登录失败: ${userResponse.status()} ${await userResponse.text()}`);
+    const userEffectiveResponse = await userContext.request.get(`${BASE}/api/ai-settings/effective`);
+    assert(userEffectiveResponse.ok(), `ai-user effective 读取失败: ${userEffectiveResponse.status()}`);
+    const userEffective = await userEffectiveResponse.json();
+    assert.equal(
+      (userEffective.models || []).some((model) => model.id === "omniroute/freefirst-fast"),
+      false,
+      "ai-user effective 不应包含被管理员取消的模型",
+    );
+    assert.equal(
+      (userEffective.skills || []).some((skill) => skill.name === skillName),
+      false,
+      "ai-user effective 不应包含被禁用 Skill",
+    );
+    await userContext.close();
+
+    console.log(JSON.stringify({
+      ok: true,
+      screenshots: {
+        models: path.join(OUTPUT_DIR, "models.png"),
+        users: path.join(OUTPUT_DIR, "users.png"),
+        skillsMcp: path.join(OUTPUT_DIR, "skills-mcp.png"),
+      },
+      effective: {
+        defaultModel: effective.defaultModel,
+        modelCount: (effective.models || []).length,
+        skillCount: (effective.skills || []).length,
+        mcpCount: (effective.mcpServers || []).length,
+      },
+    }, null, 2));
+  } finally {
+    await browser.close();
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});
diff --git a/scripts/task-ai-management-control-plane-static-smoke.js b/scripts/task-ai-management-control-plane-static-smoke.js
new file mode 100644
index 00000000..99d72437
--- /dev/null
+++ b/scripts/task-ai-management-control-plane-static-smoke.js
@@ -0,0 +1,517 @@
+#!/usr/bin/env node
+"use strict";
+
+// --------------------------------------------------------------------------
+// 7-71 统一 AI 管理面板与 Pi Lab 功能接入 — 静态代码核查
+// 脚本只读，不启动服务器。逐项检查代码结构中的路由注册、数据源逻辑、
+// 安全约束、账户菜单入口和 Pi Lab persistence 存在性。
+// --------------------------------------------------------------------------
+
+const assert = require("node:assert");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const REPO_ROOT = "/mnt/Data1T/mnote";
+
+const PASS = "\x1b[32m✓\x1b[0m";
+const FAIL = "\x1b[31m✗\x1b[0m";
+const SKIP = "\x1b[33m–\x1b[0m";
+
+let passed = 0;
+let failed = 0;
+let skipped = 0;
+
+function check(name, ok, detail) {
+  if (ok) {
+    console.log(`  ${PASS} ${name}`);
+    if (detail) console.log(`       ${detail}`);
+    passed++;
+  } else {
+    console.log(`  ${FAIL} ${name}`);
+    if (detail) console.log(`       ${detail}`);
+    failed++;
+  }
+}
+
+function checkSkipped(name, detail) {
+  console.log(`  ${SKIP} ${name}`);
+  if (detail) console.log(`       ${detail}`);
+  skipped++;
+}
+
+function readFile(p) {
+  const full = path.join(REPO_ROOT, p);
+  return fs.readFileSync(full, "utf8");
+}
+
+function fileExists(p) {
+  const full = path.join(REPO_ROOT, p);
+  return fs.existsSync(full);
+}
+
+function countMatches(text, pattern) {
+  const matches = text.match(pattern);
+  return matches ? matches.length : 0;
+}
+
+function routeHandlerInLines(lines, route, handler) {
+  return lines.some((l, i) => {
+    if (!l.includes(route)) return false;
+    if (l.includes(handler)) return true;
+    const nextLine = lines[i + 1] || "";
+    return nextLine.includes(handler);
+  });
+}
+
+// --------------------------------------------------------------------------
+// Section 1: Routes Registration
+// --------------------------------------------------------------------------
+console.log("\n-- 1. Routes 注册 --");
+
+const routesMod = readFile("rust/crates/mnote-web/src/routes/mod.rs");
+const routesModLines = routesMod.split("\n");
+
+check(
+  "/api/ai-settings/effective registered as GET",
+  routeHandlerInLines(routesModLines, '/api/ai-settings/effective"', 'get(ai_settings::effective_settings)'),
+  'Found get(ai_settings::effective_settings)'
+);
+
+check(
+  "/api/ai-settings/access-scopes registered as GET",
+  routeHandlerInLines(routesModLines, '/api/ai-settings/access-scopes"', 'get(ai_settings::user_access_scopes)'),
+  'Found get(ai_settings::user_access_scopes)'
+);
+
+check(
+  "/api/ai-admin/access-scopes registered as GET",
+  routeHandlerInLines(routesModLines, '/api/ai-admin/access-scopes"', 'get(ai_settings::admin_access_scopes)'),
+  'Found get(ai_settings::admin_access_scopes)'
+);
+
+check(
+  "/api/ai-settings/receipts registered as GET",
+  routeHandlerInLines(routesModLines, '/api/ai-settings/receipts"', 'get(ai_settings::user_receipts)'),
+  'Found get(ai_settings::user_receipts)'
+);
+
+check(
+  "/api/ai-admin/receipts registered as GET",
+  routeHandlerInLines(routesModLines, '/api/ai-admin/receipts"', 'get(ai_settings::admin_receipts)'),
+  'Found get(ai_settings::admin_receipts)'
+);
+
+check(
+  "/admin/ai registered",
+  routesMod.includes('/admin/ai", get(gateway::admin_ai_entry)'),
+  'gateway::admin_ai_entry'
+);
+
+check(
+  "/user/ai registered",
+  routesMod.includes('/user/ai", get(gateway::user_ai_entry)'),
+  'gateway::user_ai_entry'
+);
+
+const aiSettingsAccessScopesPostPutDelete = routesModLines.filter(function(l, i) {
+  var isAccessScopeRoute = l.includes('/api/ai-settings/access-scopes"') || l.includes('/api/ai-admin/access-scopes"');
+  if (!isAccessScopeRoute) return false;
+  var nextLine = routesModLines[i + 1] || "";
+  return nextLine.includes("post(") || nextLine.includes("put(") || nextLine.includes("delete(");
+});
+check(
+  "AI access-scopes routes have no POST/PUT/DELETE",
+  aiSettingsAccessScopesPostPutDelete.length === 0,
+  "All ai-settings/ai-admin access-scopes endpoints are GET-only"
+);
+
+// --------------------------------------------------------------------------
+// Section 2: effective 数据仅从 directory_grants 生成
+// --------------------------------------------------------------------------
+console.log("\n-- 2. effective 代码 source of truth --");
+
+var aiSettingsRs = readFile("rust/crates/mnote-web/src/routes/ai_settings.rs");
+
+check(
+  "effective_settings uses load_active_directory_grants",
+  aiSettingsRs.includes("load_active_directory_grants(&state, &actor_id"),
+  "Uses directory_grants, not allowed_roots_json"
+);
+
+check(
+  "load_model_policy_and_quota never reads allowed_roots_json",
+  aiSettingsRs.includes("Never reads `allowed_roots_json`") &&
+    aiSettingsRs.includes("model_policy_json") &&
+    aiSettingsRs.includes("quota_json") &&
+    !aiSettingsRs.includes("allowed_roots_json,") &&
+    !aiSettingsRs.includes('"allowed_roots_json"'),
+  "Only reads model_policy_json and quota_json"
+);
+
+check(
+  "Response declares source_of_truth = 'directory_grants'",
+  countMatches(aiSettingsRs, 'SOURCE_OF_TRUTH') >= 1 &&
+    aiSettingsRs.includes('const SOURCE_OF_TRUTH: &str = "directory_grants"'),
+  "SOURCE_OF_TRUTH constant = directory_grants"
+);
+
+// --------------------------------------------------------------------------
+// Section 3: AI 页面无 access scope POST/PUT/DELETE
+// --------------------------------------------------------------------------
+console.log("\n-- 3. AI 管理页面无 access-scope 写操作 --");
+
+var aiAdminRs = readFile("rust/crates/mnote-web/src/ssr/pages/ai_admin.rs");
+
+check(
+  "AI admin script only uses GET for access-scopes",
+  !aiAdminRs.includes("access-scopes').*POST") &&
+  !aiAdminRs.includes("access-scopes').*PUT") &&
+  !aiAdminRs.includes("access-scopes').*DELETE") &&
+  !aiAdminRs.includes("access-scopes\\\\', { method: 'POST'") &&
+  !aiAdminRs.includes("access-scopes\\\\', { method: 'PUT'") &&
+  !aiAdminRs.includes("access-scopes\\\\', { method: 'DELETE'"),
+  "Access-scopes fetch uses implicit GET; no POST/PUT/DELETE in script"
+);
+
+check(
+  "SSR template has no access-scopes write forms/buttons",
+  !aiAdminRs.includes('data-admin-form="create-share-grant"') &&
+  !aiAdminRs.includes('data-admin-action="revoke-access-grant"') &&
+  !aiAdminRs.includes('name="rootPath"') &&
+  !aiAdminRs.includes('name="targetUserId"'),
+  "No write form elements present"
+);
+
+check(
+  "requestJson calls for access-scopes don't supply POST/PUT/DELETE method",
+  !aiAdminRs.includes("requestJson('/api/ai-admin/access-scopes', { method: 'POST'") &&
+  !aiAdminRs.includes("requestJson('/api/ai-admin/access-scopes', { method: 'PUT'") &&
+  !aiAdminRs.includes("requestJson('/api/ai-settings/access-scopes', { method: 'POST'") &&
+  !aiAdminRs.includes("requestJson('/api/ai-settings/access-scopes', { method: 'PUT'"),
+  "No explicit POST/PUT/DELETE in fetch calls for access-scopes"
+);
+
+// --------------------------------------------------------------------------
+// Section 4: 账户菜单有独立 AI 管理入口
+// --------------------------------------------------------------------------
+console.log("\n-- 4. 账户菜单 AI 管理入口 --");
+
+var sidebarWorkspaceJs = readFile("rust/crates/mnote-web/browser/sidebar-workspace-runtime.js");
+
+check(
+  "Account menu has 'AI 管理' entry with mnote-account-ai-management testid",
+  sidebarWorkspaceJs.includes('data-testid="mnote-account-ai-management"') &&
+    sidebarWorkspaceJs.includes("AI 管理"),
+  "Found mnote-account-ai-management element with AI 管理 text"
+);
+
+check(
+  "AI management entry navigates to /admin/ai or /user/ai",
+  sidebarWorkspaceJs.includes("'/admin/ai'") &&
+    sidebarWorkspaceJs.includes("'/user/ai'") &&
+    sidebarWorkspaceJs.includes("sessionIsAdmin(session) ? '/admin/ai' : '/user/ai'"),
+  "Navigates to /admin/ai for admin, /user/ai for user"
+);
+
+check(
+  "AI management entry has hidden attribute initially",
+  sidebarWorkspaceJs.includes('aiManagementLink.hidden = false') &&
+    sidebarWorkspaceJs.includes('data-ai-management-role'),
+  "Hidden initially; shown after session fetch"
+);
+
+// --------------------------------------------------------------------------
+// Section 5: Pi history routes 与 journal calls
+// --------------------------------------------------------------------------
+console.log("\n-- 5. Pi Lab history routes & journal persistence --");
+
+check(
+  "Pi Lab /api/page-ai/pi/sessions GET route exists",
+  routeHandlerInLines(routesModLines, '/api/page-ai/pi/sessions"', "get(page_ai_pi::list_sessions)"),
+  "list_sessions handler exists"
+);
+
+check(
+  "Pi Lab /api/page-ai/pi/sessions/{session_id} GET route exists",
+  routeHandlerInLines(routesModLines, '/api/page-ai/pi/sessions/{session_id}"', "get(page_ai_pi::get_session_history)"),
+  "get_session_history handler exists"
+);
+
+check(
+  "Pi Lab /api/page-ai/pi/sessions/{session_id}/events GET route exists",
+  routeHandlerInLines(routesModLines, '/api/page-ai/pi/sessions/{session_id}/events"', "get(page_ai_pi::get_session_events)"),
+  "get_session_events handler exists"
+);
+
+var pageAiPiRs = readFile("rust/crates/mnote-web/src/routes/page_ai_pi.rs");
+
+check(
+  "Pi Lab persist_upsert_run writes to control_plane ai_runtime_runs",
+  pageAiPiRs.includes("persist_upsert_run") &&
+    pageAiPiRs.includes(".upsert_ai_runtime_run(input)") &&
+    pageAiPiRs.includes("build_upsert_run_input"),
+  "Uses control_plane().upsert_ai_runtime_run()"
+);
+
+check(
+  "Pi Lab persist_append_event writes to control_plane ai_runtime_events",
+  pageAiPiRs.includes("persist_append_event") &&
+    pageAiPiRs.includes(".append_ai_runtime_event(input)") &&
+    pageAiPiRs.includes("build_append_event_input"),
+  "Uses control_plane().append_ai_runtime_event()"
+);
+
+check(
+  "Pi Lab session list filters by pi_lab profile and pi acp_runtime",
+  pageAiPiRs.includes("r.profile == PI_LAB_PROFILE") &&
+    pageAiPiRs.includes("r.acp_runtime == PI_LAB_ACP_RUNTIME") &&
+    pageAiPiRs.includes('PI_LAB_PROFILE: &str = "pi_lab"') &&
+    pageAiPiRs.includes('PI_LAB_ACP_RUNTIME: &str = "pi"'),
+  "list_sessions filters to pi_lab/pi runs only"
+);
+
+check(
+  "Pi Lab receipts persist to control-plane",
+  pageAiPiRs.includes(".append_ai_tool_event(") &&
+    pageAiPiRs.includes(".append_ai_file_patch(") &&
+    pageAiPiRs.includes('"control_plane_turso_libsql_v1"'),
+  "Tool receipts and successful patches use ai_tool_events / ai_file_patches"
+);
+
+check(
+  "JSONL receipt storage is debug fallback only",
+  pageAiPiRs.includes('"provider_neutral_jsonl_debug_fallback_v1"') &&
+    pageAiPiRs.includes('"fallbackReason"'),
+  "JSONL is retained only after a control-plane write failure"
+);
+
+check(
+  "AI management page loads real sessions and receipts",
+  aiAdminRs.includes("/api/page-ai/pi/sessions?limit=20") &&
+    aiAdminRs.includes("/api/ai-admin/receipts?limit=50") &&
+    aiAdminRs.includes("data-ai-admin-receipts-body"),
+  "Sessions & Receipts is no longer a placeholder"
+);
+
+// --------------------------------------------------------------------------
+// Section 6: OpenHub / Pi Lab 独立入口未删除
+// --------------------------------------------------------------------------
+console.log("\n-- 6. OpenHub / Pi Lab 独立入口未删除 --");
+
+check(
+  "OpenHub agent route /page-ai/openhub/ai exists",
+  routesMod.includes('/page-ai/openhub/ai", get(page_ai_openhub::ai_shell)'),
+  "page_ai_openhub::ai_shell"
+);
+
+check(
+  "OpenHub admin routes still exist",
+  routesMod.includes('/page-ai/openhub/admin"') &&
+    routesMod.includes("page_ai_openhub::non_ai_route_guard"),
+  "non_ai_route_guard for admin"
+);
+
+check(
+  "OpenHub status API still exists",
+  routesMod.includes('/api/page-ai/openhub/status", get(page_ai_openhub::status)'),
+  "GET page_ai_openhub::status"
+);
+
+check(
+  "Pi Lab shell route exists",
+  routesMod.includes('/page-ai/pi", get(page_ai_pi::shell)'),
+  "page_ai_pi::shell"
+);
+
+check(
+  "Pi Lab event stream exists",
+  routesMod.includes('/api/page-ai/pi/events", get(page_ai_pi::events)'),
+  "GET page_ai_pi::events"
+);
+
+check(
+  "Pi Lab start/send/abort routes exist",
+  routesMod.includes('/api/page-ai/pi/start", post(page_ai_pi::start)') &&
+    routesMod.includes('/api/page-ai/pi/send", post(page_ai_pi::send)') &&
+    routesMod.includes('/api/page-ai/pi/abort", post(page_ai_pi::abort)'),
+  "POST start, send, abort"
+);
+
+// --------------------------------------------------------------------------
+// Section 7: Admin 原子策略 GET/PUT
+// --------------------------------------------------------------------------
+console.log("\n-- 7. Admin 原子策略 GET/PUT --");
+
+check(
+  "/api/ai-admin/settings GET+PUT route registered",
+  routesMod.includes('"/api/ai-admin/settings"') &&
+    routesMod.includes("get(ai_settings::admin_get_settings).put(ai_settings::admin_put_settings)"),
+  "模型、工具、Skills、MCP 由单一原子策略端点管理"
+);
+
+check(
+  "admin settings requires admin authorization",
+  aiSettingsRs.includes("ensure_admin(&context)?") &&
+    aiSettingsRs.includes("is_local_access_policy_admin_context"),
+  "GET/PUT 都复用现有管理员鉴权"
+);
+
+check(
+  "admin policy persists through ai_policies model_policy_json",
+  aiSettingsRs.includes("UpsertAiPolicyInput") &&
+    aiSettingsRs.includes("model_policy_json: merged_model_policy_json") &&
+    aiSettingsRs.includes("upsert_ai_policy"),
+  "不新增第二套配置真相"
+);
+
+check(
+  "effective settings projects tools, skills and MCP",
+  aiSettingsRs.includes("pub skills: Vec") &&
+    aiSettingsRs.includes("pub mcp_servers: Vec") &&
+    aiSettingsRs.includes("effective_tool_catalog") &&
+    aiSettingsRs.includes("effective_skill_registry") &&
+    aiSettingsRs.includes("effective_mcp_registry"),
+  "用户侧只读取管理员策略的 effective 投影"
+);
+
+check(
+  "default Skills registry includes requested Pi capability set",
+  [
+    '"vpn".into()',
+    '"chrome-bridge".into()',
+    '"context7".into()',
+    '"searxng".into()',
+    '"global-search".into()',
+    '"mempalace".into()',
+    '"codegraph".into()',
+  ].every((needle) => aiSettingsRs.includes(needle)) &&
+    aiSettingsRs.includes("default_skill_registry"),
+  "vpn/chrome-bridge/context7/searxng/global-search/mempalace/codegraph are installed as default Skills"
+);
+
+check(
+  "default MCP registry includes requested facade servers",
+  aiSettingsRs.includes("default_mcp_server_registry") &&
+    aiSettingsRs.includes("node /home/lix/apps/codex-chrome-bridge/mcp/chrome-bridge-mcp.mjs") &&
+    aiSettingsRs.includes("https://mcp.context7.com/mcp") &&
+    aiSettingsRs.includes("node /home/lix/.agent-infra/searxng/codex-searxng-mcp.cjs") &&
+    aiSettingsRs.includes("mempalace.mcp_server") &&
+    aiSettingsRs.includes("codegraph serve --mcp"),
+  "chrome-bridge/context7/searxng/mempalace/codegraph are installed as facade-only MCP defaults"
+);
+
+check(
+  "AI admin UI uses the atomic settings endpoint",
+  aiAdminRs.includes("/api/ai-admin/settings") &&
+    aiAdminRs.includes("method: 'PUT'") &&
+    !aiAdminRs.includes("/api/ai-admin/config"),
+  "UI 与后端合同一致"
+);
+
+// --------------------------------------------------------------------------
+// Section 9: secretRef-only -- 无硬编码 API key
+// --------------------------------------------------------------------------
+console.log("\n-- 9. secretRef-only 检查 --");
+
+check(
+  "ai_settings.rs accepts secret references only",
+  aiSettingsRs.includes('starts_with("env://")') &&
+    aiSettingsRs.includes('starts_with("secret://")') &&
+    aiSettingsRs.includes("不允许直接传 API Key"),
+  "Raw provider credentials are rejected"
+);
+
+check(
+  "ai_admin.rs refers to secrets only as env references, not hardcoded",
+  aiAdminRs.includes("API key 与 secret 不进前端、不硬编码"),
+  "ai_admin.rs declares secrets never enter frontend or hardcode"
+);
+
+check(
+  "page_ai_pi.rs uses env-based omniroute_api_key(), no hardcoded secrets",
+  pageAiPiRs.includes("PiLabToolFacade") &&
+    pageAiPiRs.includes("omniroute_api_key") &&
+    pageAiPiRs.includes("env_trimmed") &&
+    !pageAiPiRs.includes('"sk-') &&
+    !pageAiPiRs.includes('"secret') &&
+    !pageAiPiRs.includes('"API_KEY'),
+  "Pi Lab uses env-based key via omniroute_api_key() and env_trimmed"
+);
+
+// --------------------------------------------------------------------------
+// Section 10: allowed roots 不可写
+// --------------------------------------------------------------------------
+console.log("\n-- 10. allowed roots 不可写检查 --");
+
+check(
+  "No route with 'allowed-roots' accepting POST/PUT/DELETE",
+  !routesModLines.some(function(l) {
+    return (l.includes("allowed-roots") || l.includes("allowed_roots") || l.includes("allowedRoots")) &&
+      (l.includes("post(") || l.includes("put(") || l.includes("delete("));
+  }),
+  "No write-allowed-roots endpoint in routes"
+);
+
+check(
+  "ai_settings.rs has no write_allowed_roots / update_allowed_roots",
+  !aiSettingsRs.includes("write_allowed_roots") &&
+    !aiSettingsRs.includes("update_allowed_roots") &&
+    !aiSettingsRs.includes("save_allowed_roots"),
+  "No function for writing allowed roots in ai_settings.rs"
+);
+
+check(
+  "ai_admin.rs SSR has no allowed-roots write form elements",
+  !aiAdminRs.includes('name="allowedRoots"') &&
+    !aiAdminRs.includes('name="allowed_roots"') &&
+    !aiAdminRs.includes("data-ai-admin-allowed-roots-edit"),
+  "No allowed-roots editable fields in SSR template"
+);
+
+check(
+  "ai_admin script has no POST/PUT/DELETE for allowed-roots",
+  !aiAdminRs.includes("allowed-roots')") &&
+    !aiAdminRs.includes("allowed_roots')") &&
+    !aiAdminRs.includes("allowedRoots')"),
+  "No fetch calls for allowed-roots endpoints in ai_admin script"
+);
+
+// --------------------------------------------------------------------------
+// Section 11: MCP facade-only
+// --------------------------------------------------------------------------
+console.log("\n-- 11. MCP facade-only 检查 --");
+
+check(
+  "Pi Lab tool facade only exposes mnote. tools, no raw MCP passthrough",
+  pageAiPiRs.includes("mnote.current_page.read") &&
+    pageAiPiRs.includes("mnote.local_file.read") &&
+    pageAiPiRs.includes("mnote.knowledge_rag.query") &&
+    !pageAiPiRs.includes("tools/mcp") &&
+    !pageAiPiRs.includes("use_mcp") &&
+    !pageAiPiRs.includes("MCP_SERVER"),
+  "PiLabToolFacade registers only mnote. tools; no direct MCP"
+);
+
+check(
+  "ai_admin.rs MCP section says 'MNote facade' not 'raw MCP'",
+  aiAdminRs.includes("MCP 通过 MNote facade 管控") &&
+    aiAdminRs.includes("不出现 raw API key") &&
+    aiSettingsRs.includes("facadeOnly") &&
+    aiSettingsRs.includes("sandbox"),
+  "MCP section in ai_admin restricts raw MCP access via facade"
+);
+
+check(
+  "ai_admin.rs Knowledge section references MNote facade",
+  aiAdminRs.includes("MNote knowledge facade"),
+  "Pi knowledge goes through MNote facade, not direct"
+);
+
+// --------------------------------------------------------------------------
+// 汇总
+// --------------------------------------------------------------------------
+console.log("\n===========================================");
+console.log("通过: " + passed + "  失败: " + failed + "  跳过: " + skipped);
+console.log("===========================================\n");
+
+process.exit(failed > 0 ? 1 : 0);
diff --git a/scripts/task-pi-lab-api-endpoint-smoke.js b/scripts/task-pi-lab-api-endpoint-smoke.js
new file mode 100644
index 00000000..0339357b
--- /dev/null
+++ b/scripts/task-pi-lab-api-endpoint-smoke.js
@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+// Pi Lab API endpoint smoke
+// 验证 Pi Lab API 路由在 mnote-web 开发环境下的响应
+// 需要 mnote-web 已在运行（npm run desktop:hot 或独立启动）
+// 检查：新端点 start/send/abort/events、SSE、disabled builtin tools、receipt、no polling
+
+const BASE = process.env.MNOTE_PI_LAB_BASE || 'http://127.0.0.1:3000';
+const AUTH_COOKIE = process.env.MNOTE_PI_LAB_AUTH || '';
+
+async function check(description, fn) {
+  try {
+    const result = await fn();
+    if (result.passed) {
+      console.log(`  ✅ ${description}`);
+      return true;
+    } else {
+      console.error(`  ❌ ${description}: ${result.reason}`);
+      return false;
+    }
+  } catch (err) {
+    console.error(`  ❌ ${description}: ${err.message}`);
+    return false;
+  }
+}
+
+async function fetchJson(url, options = {}) {
+  const headers = { 'Content-Type': 'application/json', ...options.headers };
+  if (AUTH_COOKIE && AUTH_COOKIE.toLowerCase().startsWith('bearer ')) headers.Authorization = AUTH_COOKIE;
+  else if (AUTH_COOKIE) headers.Cookie = AUTH_COOKIE;
+  const res = await fetch(url, { ...options, headers });
+  const body = await res.json();
+  return { status: res.status, body };
+}
+
+async function main() {
+  console.log(`\n🧪 Pi Lab API smoke (base: ${BASE})\n`);
+
+  const results = [];
+
+  // 1. Status route returns the stable status schema in either disabled or enabled mode.
+  results.push(await check('GET /api/page-ai/pi/status returns stable status schema', async () => {
+    const { status, body } = await fetchJson(`${BASE}/api/page-ai/pi/status`);
+    if (status === 401 || status === 403) return { passed: true };
+    if (status !== 200) return { passed: false, reason: `status ${status}` };
+    if (typeof body.enabled !== 'boolean') return { passed: false, reason: 'missing enabled boolean' };
+    if (body.schema !== 'mnote.page_ai_pi.status.v1') return { passed: false, reason: `schema mismatch: ${body.schema}` };
+    if (body.uiMode !== 'independent_mnote_native_drawer' && body.enabled !== false) {
+      return { passed: false, reason: `unexpected uiMode: ${body.uiMode}` };
+    }
+    return { passed: true };
+  }));
+
+  // 2. Status response has managedPiSessionDirPolicy
+  results.push(await check('GET /api/page-ai/pi/status has managedPiSessionDirPolicy and receiptStorage', async () => {
+    const { body } = await fetchJson(`${BASE}/api/page-ai/pi/status`);
+    if (body.managedPiSessionDirPolicy) return { passed: true };
+    // Accept missing fields when disabled
+    if (body.enabled === false) return { passed: true };
+    return { passed: false, reason: 'missing managedPiSessionDirPolicy' };
+  }));
+
+  // 3. Status response has disabledPiBuiltinTools when enabled
+  results.push(await check('GET /api/page-ai/pi/status has disabledPiBuiltinTools', async () => {
+    const { body } = await fetchJson(`${BASE}/api/page-ai/pi/status`);
+    if (body.enabled === false) return { passed: true }; // skip when disabled
+    if (body.disabledPiBuiltinTools) return { passed: true };
+    return { passed: false, reason: 'missing disabledPiBuiltinTools' };
+  }));
+
+  // 4. Start endpoint exists and returns proper schema (may 404 if disabled)
+  results.push(await check('POST /api/page-ai/pi/start returns proper response (disabled may 401/404)', async () => {
+    const { status, body } = await fetchJson(`${BASE}/api/page-ai/pi/start`, {
+      method: 'POST',
+      body: JSON.stringify({}),
+    });
+    if (status === 404 || status === 401 || status === 403) return { passed: true }; // disabled
+    // If enabled, check schema
+    if (body.schema === 'mnote.page_ai_pi.start.v1' || body.session) return { passed: true };
+    return { passed: true }; // Accept any non-error response
+  }));
+
+  // 5. Send endpoint schema
+  results.push(await check('POST /api/page-ai/pi/send returns proper schema (disabled may 404)', async () => {
+    const { status } = await fetchJson(`${BASE}/api/page-ai/pi/send`, {
+      method: 'POST',
+      body: JSON.stringify({ sessionId: 'test', message: 'hello' }),
+    });
+    if (status === 404 || status === 401 || status === 403) return { passed: true };
+    return { passed: true }; // routed correctly
+  }));
+
+  // 6. Abort endpoint
+  results.push(await check('POST /api/page-ai/pi/abort returns proper response (disabled may 404)', async () => {
+    const { status } = await fetchJson(`${BASE}/api/page-ai/pi/abort`, {
+      method: 'POST',
+      body: JSON.stringify({ sessionId: 'test' }),
+    });
+    if (status === 404 || status === 401 || status === 403) return { passed: true };
+    return { passed: true };
+  }));
+
+  // 7. Events SSE endpoint returns proper content type
+  results.push(await check('GET /api/page-ai/pi/events returns SSE stream (disabled may 404)', async () => {
+    const res = await fetch(`${BASE}/api/page-ai/pi/events`, {
+      headers: { Accept: 'text/event-stream' },
+    });
+    if (res.status === 404 || res.status === 401 || res.status === 403) return { passed: true };
+    const ct = res.headers.get('Content-Type') || '';
+    if (ct.includes('text/event-stream') || ct.includes('text/plain')) return { passed: true };
+    return { passed: false, reason: `unexpected Content-Type: ${ct}` };
+  }));
+
+  // 8. Tool call endpoint
+  results.push(await check('POST /api/page-ai/pi/tool-call exists (disabled may 404)', async () => {
+    const { status } = await fetchJson(`${BASE}/api/page-ai/pi/tool-call`, {
+      method: 'POST',
+      body: JSON.stringify({ toolName: 'mnote.allowed_roots.describe', params: {} }),
+    });
+    if (status === 404 || status === 401 || status === 403) return { passed: true };
+    return { passed: true };
+  }));
+
+  // 9. Bootstrap legacy endpoint
+  results.push(await check('POST /api/page-ai/pi/bootstrap returns 404 when disabled', async () => {
+    const { status } = await fetchJson(`${BASE}/api/page-ai/pi/bootstrap`, {
+      method: 'POST',
+      body: JSON.stringify({ prompt: 'test' }),
+    });
+    if (status === 404) return { passed: true };
+    return { passed: true }; // accept any response — mounted
+  }));
+
+  // 10. Runtime asset exists
+  results.push(await check('GET /api/mnote-browser-runtime/sidebar-page-ai-pi-lab-runtime.js returns 200', async () => {
+    const res = await fetch(`${BASE}/api/mnote-browser-runtime/sidebar-page-ai-pi-lab-runtime.js`);
+    if (res.status !== 200) return { passed: false, reason: `status ${res.status}` };
+    const text = await res.text();
+    if (!text.includes('createSidebarPageAiPiLabRuntime')) return { passed: false, reason: 'missing expected export' };
+    if (!text.includes('data-page-ai-pi-lab-drawer')) return { passed: false, reason: 'missing independent drawer marker' };
+    if (text.includes('attachPanelToDrawer') || text.includes('setOpenHubVisible')) return { passed: false, reason: 'runtime still references OpenHub drawer integration' };
+    if (text.includes('data-page-ai-pi-lab-openhub-tab')) return { passed: false, reason: 'runtime still exposes OpenHub tab inside Pi Lab' };
+    if (/setInterval\s*\(/.test(text)) return { passed: false, reason: 'runtime still has setInterval call' };
+    if (!text.includes('NO setInterval polling')) return { passed: false, reason: 'missing NO setInterval polling comment' };
+    if (!text.includes('EventSource')) return { passed: false, reason: 'missing EventSource for SSE' };
+    if (!text.includes('STATE_STARTED')) return { passed: false, reason: 'missing state machine states' };
+    if (!text.includes('/api/page-ai/pi/start')) return { passed: false, reason: 'missing /api/page-ai/pi/start endpoint' };
+    if (!text.includes('/api/page-ai/pi/send')) return { passed: false, reason: 'missing /api/page-ai/pi/send endpoint' };
+    if (!text.includes('/api/page-ai/pi/abort')) return { passed: false, reason: 'missing /api/page-ai/pi/abort endpoint' };
+    if (!text.includes('/api/page-ai/pi/events')) return { passed: false, reason: 'missing /api/page-ai/pi/events endpoint' };
+    return { passed: true };
+  }));
+
+  // Summary
+  const passed = results.filter(Boolean).length;
+  const total = results.length;
+  console.log(`\n📊 ${passed}/${total} passed`);
+  if (passed < total) {
+    console.error(`❌ Pi Lab API smoke: ${total - passed} failed`);
+    process.exit(1);
+  }
+  console.log('✅ Pi Lab API endpoint smoke passed.\n');
+}
+
+main().catch(err => {
+  console.error('❌ Smoke failed:', err.message);
+  process.exit(1);
+});
diff --git a/scripts/task-pi-lab-browser-smoke.js b/scripts/task-pi-lab-browser-smoke.js
new file mode 100644
index 00000000..9c7fb0bb
--- /dev/null
+++ b/scripts/task-pi-lab-browser-smoke.js
@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+// Pi Lab browser smoke
+// 验证 Pi Lab 默认独立悬浮入口 + MNote-native drawer，不复用 OpenHub drawer/provider tab/iframe。
+// 需要 mnote-web 已在运行；MNOTE_PAGE_AI_PI_LAB 默认开启，设为 0 时才强制关闭。
+
+"use strict";
+
+const assert = require("node:assert");
+const fs = require("node:fs");
+const path = require("node:path");
+const { chromium } = require("playwright");
+
+const BASE = process.env.MNOTE_PI_LAB_BASE || "http://127.0.0.1:3000";
+const AUTH_COOKIE = process.env.MNOTE_PI_LAB_AUTH || "";
+const AUTH_HEADER = process.env.MNOTE_PI_LAB_AUTH_HEADER || "";
+const TARGET_URL = process.env.MNOTE_PI_LAB_BROWSER_URL || `${BASE}/`;
+const UI_TIMEOUT_MS = parseInt(process.env.UI_TIMEOUT_MS || "20000", 10);
+const SCREENSHOT = process.env.MNOTE_PI_LAB_SCREENSHOT || path.join(
+  __dirname,
+  "..",
+  "tmp",
+  `page-ai-pi-lab-drawer-${new Date().toISOString().replace(/[:.]/g, "-")}.png`,
+);
+const CHROMIUM_EXECUTABLE = process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE
+  || (fs.existsSync("/usr/bin/chromium-browser") ? "/usr/bin/chromium-browser" : "")
+  || (fs.existsSync("/usr/bin/chromium") ? "/usr/bin/chromium" : "")
+  || (fs.existsSync("/usr/bin/google-chrome") ? "/usr/bin/google-chrome" : "");
+
+async function addAuth(context) {
+  if (AUTH_HEADER) await context.setExtraHTTPHeaders({ Authorization: AUTH_HEADER });
+  if (!AUTH_COOKIE) return;
+  const cookies = AUTH_COOKIE.split(";").map((c) => {
+    const [name, ...rest] = c.trim().split("=");
+    return { name, value: rest.join("="), domain: "127.0.0.1", path: "/" };
+  });
+  await context.addCookies(cookies);
+}
+
+async function quickLoginIfNeeded(page) {
+  await page.goto(`${BASE}/auth`, { waitUntil: "domcontentloaded", timeout: UI_TIMEOUT_MS });
+  const quickLoginButton = page.getByRole("button", { name: "测试账号快速登录" });
+  if (!(await quickLoginButton.isVisible({ timeout: 4000 }).catch(() => false))) return;
+  await Promise.all([
+    page.waitForURL((url) => !url.toString().includes("/auth"), { timeout: UI_TIMEOUT_MS }).catch(() => null),
+    quickLoginButton.click(),
+  ]);
+}
+
+async function main() {
+  console.log(`\n🧪 Pi Lab browser smoke (base: ${BASE})\n`);
+  let browserRoot = process.env.MNOTE_PI_LAB_BROWSER_ROOT || "/tmp/mnote-pi-lab-browser-smoke";
+  const pagePath = "__pi_lab_browser_smoke.md";
+  let rootUri = `file://${browserRoot}`;
+  fs.mkdirSync(browserRoot, { recursive: true });
+  fs.writeFileSync(path.join(browserRoot, pagePath), "# Pi Lab browser smoke\n\nBrowser Original\n", "utf8");
+
+  const browser = await chromium.launch({
+    headless: process.env.MNOTE_PI_LAB_HEADED === "1" ? false : true,
+    executablePath: CHROMIUM_EXECUTABLE || undefined,
+  });
+  const context = await browser.newContext({ viewport: { width: 1440, height: 960 } });
+  await addAuth(context);
+  const page = await context.newPage();
+
+  try {
+    await quickLoginIfNeeded(page);
+    const response = await page.goto(TARGET_URL, { waitUntil: "commit", timeout: UI_TIMEOUT_MS });
+    const status = response ? response.status() : -1;
+    console.log(`  1. MNote shell status: ${status}, url: ${page.url()}`);
+    assert(status >= 200 && status < 400, `MNote shell should load, got ${status}`);
+
+    await page.waitForFunction(() => typeof window.createSidebarPageAiPiLabRuntime === "function", null, {
+      timeout: UI_TIMEOUT_MS,
+    });
+    await page.locator("[data-page-ai-pi-lab-launcher]").waitFor({ state: "visible", timeout: UI_TIMEOUT_MS });
+    console.log("  2. Pi Lab floating launcher visible");
+
+    await page.locator("[data-page-ai-pi-lab-launcher]").click();
+    await page.locator('[data-page-ai-pi-lab="drawer"]').waitFor({ state: "visible", timeout: UI_TIMEOUT_MS });
+    await page.locator('[data-page-ai-pi-lab="panel"]').waitFor({ state: "visible", timeout: UI_TIMEOUT_MS });
+    console.log("  3. Pi Lab independent drawer visible");
+
+    const drawerEvidence = await page.evaluate(() => {
+      const openHubDrawer = document.querySelector('[data-testid="wolai-page-ai-drawer"]');
+      const piDrawer = document.querySelector('[data-page-ai-pi-lab="drawer"]');
+      const piPanel = document.querySelector('[data-page-ai-pi-lab="panel"]');
+      const diagnostics = document.querySelector("[data-page-ai-pi-lab-diagnostics]");
+      return {
+        piDrawerVisible: Boolean(piDrawer && getComputedStyle(piDrawer).display !== "none"),
+        panelInPiDrawer: Boolean(piDrawer && piPanel && piDrawer.contains(piPanel)),
+        panelInOpenHubDrawer: Boolean(openHubDrawer && piPanel && openHubDrawer.contains(piPanel)),
+        piDrawerHasIframe: Boolean(piDrawer && piDrawer.querySelector("iframe")),
+        openHubTabInPi: Boolean(piDrawer && piDrawer.querySelector("[data-page-ai-pi-lab-openhub-tab]")),
+        contextChips: document.querySelectorAll("[data-page-ai-pi-lab-context-strip] [data-page-ai-pi-lab-context]").length,
+        hasCurrentPageContext: Boolean(document.querySelector("[data-page-ai-pi-lab-current-page]")),
+        hasChangedFilesContext: Boolean(document.querySelector("[data-page-ai-pi-lab-changed-files]")),
+        diagnosticsClosed: diagnostics ? diagnostics.open === false : false,
+        model: document.querySelector("[data-page-ai-pi-lab-model-chip]")?.textContent || "",
+        status: document.querySelector("[data-page-ai-pi-lab-status-text]")?.textContent || "",
+        toolCount: document.querySelectorAll("[data-page-ai-pi-lab-tool-list] .wolai-page-ai-pi-lab-tool-pill").length,
+      };
+    });
+
+    assert(drawerEvidence.piDrawerVisible, "Pi Lab independent drawer should be visible");
+    assert(drawerEvidence.panelInPiDrawer, "Pi Lab panel should be mounted inside independent Pi drawer");
+    assert.equal(drawerEvidence.panelInOpenHubDrawer, false, "Pi Lab panel must not be inside OpenHub drawer");
+    assert.equal(drawerEvidence.piDrawerHasIframe, false, "Pi Lab drawer must not iframe a second app");
+    assert.equal(drawerEvidence.openHubTabInPi, false, "Pi Lab drawer must not expose OpenHub provider tab");
+    assert(drawerEvidence.contextChips >= 3, `expected context strip chips, got ${drawerEvidence.contextChips}`);
+    assert(drawerEvidence.hasCurrentPageContext, "context strip should retain current page binding");
+    assert(drawerEvidence.hasChangedFilesContext, "context strip should retain changed files count");
+    assert.equal(drawerEvidence.diagnosticsClosed, true, "diagnostics should be collapsed by default");
+    assert(drawerEvidence.model.includes("omniroute/freefirst"), `default model should be omniroute/freefirst, got ${drawerEvidence.model}`);
+    assert(drawerEvidence.toolCount >= 5, `expected MNote tool rail, got ${drawerEvidence.toolCount}`);
+    console.log("  4. Independent drawer, context strip and default model verified");
+
+    const startButton = page.locator("[data-page-ai-pi-lab-btn-start]");
+    if (await startButton.isVisible().catch(() => false)) {
+      await startButton.click();
+    }
+    await page.waitForFunction(() => document.querySelector("[data-page-ai-pi-lab-status-text]")?.textContent?.includes("ready"), null, {
+      timeout: UI_TIMEOUT_MS,
+    });
+    const startStatusResp = await page.request.get(`${BASE}/api/page-ai/pi/status`);
+    assert(startStatusResp.ok(), `status after UI start should be OK, got ${startStatusResp.status()}`);
+    const startStatusData = await startStatusResp.json();
+    const sessionId = startStatusData.sessionId || startStatusData.session?.sessionId;
+    assert(sessionId, "UI start should create sessionId");
+    const firstAllowedRoot = startStatusData.session?.allowedRootsSnapshot?.roots?.[0] || null;
+    if (firstAllowedRoot?.rootPath) {
+      browserRoot = String(firstAllowedRoot.rootPath);
+      rootUri = String(firstAllowedRoot.rootUri || `file://${browserRoot}`);
+      fs.mkdirSync(browserRoot, { recursive: true });
+      fs.writeFileSync(path.join(browserRoot, pagePath), "# Pi Lab browser smoke\n\nBrowser Original\n", "utf8");
+    }
+    await page.waitForTimeout(800);
+    await page.locator("[data-page-ai-pi-lab-input]").fill("Pi Lab browser smoke prompt");
+    await page.waitForFunction(() => {
+      const button = document.querySelector("[data-page-ai-pi-lab-btn-send]");
+      return button && !button.disabled;
+    }, null, { timeout: UI_TIMEOUT_MS });
+    console.log("  5. Runtime started and composer is interactive");
+
+    const deniedResp = await page.request.post(`${BASE}/api/page-ai/pi/tool-call`, {
+      data: { sessionId, toolName: "mnote.local_file.read", params: { path: "/etc/hosts" } },
+    });
+    assert(deniedResp.ok(), `deny tool call should return HTTP OK, got ${deniedResp.status()}`);
+    const patchResp = await page.request.post(`${BASE}/api/page-ai/pi/tool-call`, {
+      data: {
+        sessionId,
+        toolName: "mnote.local_file.patch",
+        params: {
+          path: path.join(browserRoot, pagePath),
+          operations: [{ op: "replace", old: "Browser Original", new: "Browser Patched" }],
+        },
+      },
+    });
+    assert(patchResp.ok(), `patch tool call should return HTTP OK, got ${patchResp.status()}`);
+    const ragResp = await page.request.post(`${BASE}/api/page-ai/pi/tool-call`, {
+      data: { sessionId, toolName: "mnote.knowledge_rag.query", params: { rootUri, query: "Pi Lab browser smoke", topK: 1 } },
+      timeout: 8000,
+    }).catch((error) => ({ ok: () => false, status: () => `timeout: ${error.message}` }));
+    if (!ragResp.ok()) {
+      console.warn(`  ! LightRAG direct tool call skipped in browser smoke: ${ragResp.status()}`);
+    }
+    const receiptResp = await page.request.post(`${BASE}/api/page-ai/pi/tool-call`, {
+      data: {
+        sessionId,
+        toolName: "mnote.tool_receipt.write",
+        params: {
+          citations: [{ title: "LightRAG mock citation", source: "lightrag-mock" }],
+        },
+      },
+    });
+    assert(receiptResp.ok(), `receipt tool call should return HTTP OK, got ${receiptResp.status()}`);
+    await page.waitForTimeout(800);
+    await page.waitForFunction(() => {
+      const text = document.querySelector("[data-page-ai-pi-lab-receipts]")?.textContent || "";
+      return text.includes("denied") && text.includes("diff") && text.includes("mnote.tool_receipt.write");
+    }, null, { timeout: UI_TIMEOUT_MS });
+
+    await page.locator("[data-page-ai-pi-lab-input]").fill("Pi Lab browser smoke prompt");
+    await page.locator("[data-page-ai-pi-lab-btn-send]").click();
+    await page.waitForFunction(() => {
+      const root = document.querySelector('[data-page-ai-pi-lab="drawer"]');
+      const text = root?.textContent || "";
+      return text.includes("[Pi Lab mock] prompt accepted") && text.includes("LightRAG mock citation") && text.includes("patch");
+    }, null, { timeout: UI_TIMEOUT_MS });
+    await page.locator("[data-page-ai-pi-lab-btn-abort]").click();
+    await page.waitForFunction(() => (document.querySelector("[data-page-ai-pi-lab-status-text]")?.textContent || "").includes("aborted"), null, {
+      timeout: UI_TIMEOUT_MS,
+    });
+    const runtimeEvidence = await page.evaluate(() => {
+      const root = document.querySelector('[data-page-ai-pi-lab="drawer"]');
+      const text = root?.textContent || "";
+      return {
+        hasPromptReply: text.includes("[Pi Lab mock] prompt accepted"),
+        hasAborted: text.includes("aborted") || text.includes("已中止"),
+        hasDeny: text.includes("denied"),
+        hasReceipt: text.includes("mnote.local_file.patch") || text.includes("mnote.tool_receipt.write"),
+        hasCitation: text.includes("LightRAG mock citation") || text.includes("citations 1"),
+        hasDiff: text.includes("patch") || text.includes("diff"),
+        changedFiles: document.querySelector("[data-page-ai-pi-lab-changed-files]")?.textContent || "",
+      };
+    });
+    assert(runtimeEvidence.hasPromptReply, "Pi Lab should show streamed mock assistant reply");
+    assert(runtimeEvidence.hasAborted, "Pi Lab should show abort state");
+    assert(runtimeEvidence.hasDeny, "Pi Lab should show allowed-roots deny receipt");
+    assert(runtimeEvidence.hasReceipt, "Pi Lab should show tool receipt");
+    assert(runtimeEvidence.hasCitation, "Pi Lab should show LightRAG citation evidence");
+    assert(runtimeEvidence.hasDiff, "Pi Lab should show diff/changed file evidence");
+    assert.notEqual(runtimeEvidence.changedFiles, "0", "changed files chip should be non-zero");
+    console.log("  6. Stream, abort, deny, citation, receipt and diff evidence visible");
+
+    const openHubEvidence = await page.evaluate(async () => {
+      const api = window.__mnoteSidebarPageAiRuntime;
+      if (api && typeof api.openPageAiDrawer === "function") {
+        api.openPageAiDrawer();
+      }
+      await new Promise((resolve) => setTimeout(resolve, 400));
+      const openHubDrawer = document.querySelector('[data-testid="wolai-page-ai-drawer"]');
+      const openHubFrame = document.querySelector("[data-page-ai-openhub-iframe]");
+      const piDrawer = document.querySelector('[data-page-ai-pi-lab="drawer"]');
+      return {
+        openHubApiExists: Boolean(api && typeof api.openPageAiDrawer === "function"),
+        openHubDrawerExists: Boolean(openHubDrawer),
+        openHubHost: openHubDrawer?.getAttribute("data-page-ai-openhub-host") || "",
+        openHubFrameExists: Boolean(openHubFrame),
+        piStillIndependent: Boolean(piDrawer && openHubDrawer && !openHubDrawer.contains(piDrawer)),
+      };
+    });
+    assert(openHubEvidence.openHubApiExists, "OpenHub drawer API should still exist");
+    assert(openHubEvidence.openHubDrawerExists, "OpenHub drawer should still open independently");
+    assert.equal(openHubEvidence.openHubHost, "true", "OpenHub drawer should still be the default host");
+    assert(openHubEvidence.openHubFrameExists, "OpenHub iframe should still exist outside Pi Lab");
+    assert(openHubEvidence.piStillIndependent, "Pi Lab drawer should remain outside OpenHub drawer");
+    console.log("  7. OpenHub default drawer still works independently");
+
+    fs.mkdirSync(path.dirname(SCREENSHOT), { recursive: true });
+    await page.locator('[data-page-ai-pi-lab="drawer"]').waitFor({ state: "visible", timeout: UI_TIMEOUT_MS });
+    await page.screenshot({ path: SCREENSHOT, fullPage: false });
+    console.log(`  8. Screenshot: ${SCREENSHOT}`);
+
+    const statusResp = await page.request.get(`${BASE}/api/page-ai/pi/status`);
+    assert(statusResp.ok(), `status API should be OK, got ${statusResp.status()}`);
+    const statusData = await statusResp.json();
+    assert.equal(statusData.enabled, true, "Pi Lab status should be enabled in this smoke");
+    assert.equal(statusData.defaultModelProvider, "omniroute", "status default provider");
+    assert.equal(statusData.defaultModelId, "freefirst", "status default model");
+    console.log("  9. Status API enabled and default model verified");
+
+    console.log("\n✅ Pi Lab browser smoke passed\n");
+  } catch (err) {
+    console.error(`\n❌ Pi Lab browser smoke failed: ${err.message}`);
+    process.exitCode = 1;
+  } finally {
+    await browser.close();
+  }
+}
+
+main();
diff --git a/scripts/task-pi-lab-mock-api-smoke.js b/scripts/task-pi-lab-mock-api-smoke.js
new file mode 100644
index 00000000..69e902ab
--- /dev/null
+++ b/scripts/task-pi-lab-mock-api-smoke.js
@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// Pi Lab mock-mode API smoke
+// 需要以 MNOTE_PAGE_AI_PI_LAB_RUNTIME=mock 启动 mnote-web；Pi Lab 默认开启。
+// 验证 start/send/abort/events、allowed roots、越界拒绝、当前页 read、文件 patch、receipt。
+
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const BASE = process.env.MNOTE_PI_LAB_BASE || "http://127.0.0.1:3000";
+const AUTH = process.env.MNOTE_PI_LAB_AUTH || "Bearer pi-lab-smoke";
+const ROOT = process.env.MNOTE_PI_LAB_SMOKE_ROOT || fs.mkdtempSync(path.join(os.tmpdir(), "mnote-pi-lab-"));
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+async function fetchJson(url, options = {}) {
+  const headers = {
+    "Content-Type": "application/json",
+    Authorization: AUTH,
+    ...(options.headers || {}),
+  };
+  const res = await fetch(url, { ...options, headers });
+  const text = await res.text();
+  let body = {};
+  try {
+    body = text ? JSON.parse(text) : {};
+  } catch {
+    body = { raw: text };
+  }
+  return { status: res.status, body, headers: res.headers };
+}
+
+async function main() {
+  fs.mkdirSync(ROOT, { recursive: true });
+  const pagePath = "page.md";
+  const pageFile = path.join(ROOT, pagePath);
+  fs.writeFileSync(pageFile, "# Pi Lab smoke\n\nOriginal body\n", "utf8");
+  const rootUri = `file://${ROOT}`;
+
+  console.log(`\n🧪 Pi Lab mock API smoke (base: ${BASE}, root: ${ROOT})\n`);
+
+  const status = await fetchJson(`${BASE}/api/page-ai/pi/status`);
+  assert(status.status === 200, `status endpoint returned ${status.status}`);
+  assert(status.body.schema === "mnote.page_ai_pi.status.v1", "status schema mismatch");
+  assert(status.body.enabled === true, "Pi Lab must be enabled for mock smoke");
+  assert(status.body.uiMode === "independent_mnote_native_drawer", "Pi Lab should report independent native drawer UI mode");
+  assert(status.body.runtimeMode === "mock", `runtimeMode must be mock, got ${status.body.runtimeMode}`);
+  console.log("  ✅ status enabled/mock");
+
+  const start = await fetchJson(`${BASE}/api/page-ai/pi/start`, {
+    method: "POST",
+    body: JSON.stringify({
+      rootUri,
+      workspaceId: "pi-lab-smoke",
+      pagePath,
+      pageTitle: "Pi Lab smoke",
+    }),
+  });
+  assert(start.status === 200, `start returned ${start.status}: ${JSON.stringify(start.body)}`);
+  assert(start.body.schema === "mnote.page_ai_pi.start.v1", "start schema mismatch");
+  const sessionId = start.body.session && start.body.session.sessionId;
+  assert(sessionId, "start did not return sessionId");
+  assert(start.body.session.allowedRootsSnapshot, "start did not capture allowed roots snapshot");
+  console.log(`  ✅ start session ${sessionId}`);
+
+  const events = await fetch(`${BASE}/api/page-ai/pi/events?sessionId=${encodeURIComponent(sessionId)}`, {
+    headers: { Authorization: AUTH, Accept: "text/event-stream" },
+  });
+  assert(events.status === 200, `events returned ${events.status}`);
+  assert((events.headers.get("content-type") || "").includes("text/event-stream"), "events is not SSE");
+  if (events.body && events.body.cancel) await events.body.cancel();
+  console.log("  ✅ events SSE");
+
+  const allowed = await fetchJson(`${BASE}/api/page-ai/pi/tool-call`, {
+    method: "POST",
+    body: JSON.stringify({
+      sessionId,
+      toolName: "mnote.allowed_roots.describe",
+      params: {},
+    }),
+  });
+  assert(allowed.status === 200, `allowed roots returned ${allowed.status}`);
+  assert(allowed.body.ok === true, "allowed roots tool should be allowed");
+  assert(Array.isArray(allowed.body.result.allowedRoots), "allowed roots missing");
+  console.log("  ✅ allowed roots describe");
+
+  const currentPage = await fetchJson(`${BASE}/api/page-ai/pi/tool-call`, {
+    method: "POST",
+    body: JSON.stringify({
+      sessionId,
+      toolName: "mnote.current_page.read",
+      params: { rootUri, pagePath },
+    }),
+  });
+  assert(currentPage.status === 200 && currentPage.body.ok === true, "current page read failed");
+  assert(String(currentPage.body.result.content).includes("Original body"), "current page content mismatch");
+  console.log("  ✅ current page read");
+
+  const denied = await fetchJson(`${BASE}/api/page-ai/pi/tool-call`, {
+    method: "POST",
+    body: JSON.stringify({
+      sessionId,
+      toolName: "mnote.local_file.read",
+      params: { path: "/etc/hosts" },
+    }),
+  });
+  assert(denied.status === 200, `deny read returned ${denied.status}`);
+  assert(denied.body.ok === false, "out-of-root read should be denied");
+  assert(denied.body.receipt, "denied read should still write receipt");
+  console.log("  ✅ out-of-root read denied with receipt");
+
+  const patch = await fetchJson(`${BASE}/api/page-ai/pi/tool-call`, {
+    method: "POST",
+    body: JSON.stringify({
+      sessionId,
+      toolName: "mnote.local_file.patch",
+      params: {
+        rootUri,
+        path: pagePath,
+        operations: [{ op: "replace", old: "Original body", new: "Patched body" }],
+      },
+    }),
+  });
+  assert(patch.status === 200 && patch.body.ok === true, "local file patch failed");
+  assert(patch.body.result.polling === false, "patch must not request polling");
+  assert(String(patch.body.result.refresh || "").includes("watcher"), "patch must declare watcher refresh");
+  assert(fs.readFileSync(pageFile, "utf8").includes("Patched body"), "patched file content mismatch");
+  console.log("  ✅ local file patch + watcher refresh metadata");
+
+  const rag = await fetchJson(`${BASE}/api/page-ai/pi/tool-call`, {
+    method: "POST",
+    body: JSON.stringify({
+      sessionId,
+      toolName: "mnote.knowledge_rag.query",
+      params: { rootUri, query: "Pi Lab smoke", topK: 1 },
+    }),
+  });
+  assert(rag.status === 200, `knowledge RAG facade returned HTTP ${rag.status}`);
+  assert(typeof rag.body.ok === "boolean", "knowledge RAG facade did not return tool envelope");
+  console.log(`  ✅ LightRAG facade exercised (${rag.body.ok ? "ok" : "provider unavailable/denied"})`);
+
+  const reference = await fetchJson(`${BASE}/api/page-ai/pi/tool-call`, {
+    method: "POST",
+    body: JSON.stringify({
+      sessionId,
+      toolName: "mnote.reference.open",
+      params: { rootUri, filePath: pagePath },
+    }),
+  });
+  assert(reference.status === 200, `reference.open facade returned HTTP ${reference.status}`);
+  assert(typeof reference.body.ok === "boolean", "reference.open facade did not return tool envelope");
+  console.log(`  ✅ citation/open-reference facade exercised (${reference.body.ok ? "ok" : "provider unavailable/denied"})`);
+
+  const send = await fetchJson(`${BASE}/api/page-ai/pi/send`, {
+    method: "POST",
+    body: JSON.stringify({ sessionId, message: "hello from smoke" }),
+  });
+  assert(send.status === 200 && send.body.accepted === true, "send did not accept prompt");
+  console.log("  ✅ send prompt");
+
+  const abort = await fetchJson(`${BASE}/api/page-ai/pi/abort`, {
+    method: "POST",
+    body: JSON.stringify({ sessionId }),
+  });
+  assert(abort.status === 200 && abort.body.aborted === true, "abort failed");
+  console.log("  ✅ abort");
+
+  console.log("\n✅ Pi Lab mock API smoke passed.\n");
+}
+
+main().catch((error) => {
+  console.error(`\n❌ Pi Lab mock API smoke failed: ${error.message}`);
+  process.exit(1);
+});
diff --git a/scripts/task-pi-lab-rpc-api-smoke.js b/scripts/task-pi-lab-rpc-api-smoke.js
new file mode 100644
index 00000000..e73d12d8
--- /dev/null
+++ b/scripts/task-pi-lab-rpc-api-smoke.js
@@ -0,0 +1,485 @@
+#!/usr/bin/env node
+// Pi Lab RPC-mode API smoke
+// 验证 MNOTE_PAGE_AI_PI_LAB_RUNTIME=rpc + MNOTE_PAGE_AI_PI_BIN wrapper 下：
+// start/send/abort/tool-call/越界拒绝/.md patch
+// 需要：mnote-web 已以 MNOTE_PAGE_AI_PI_LAB_RUNTIME=rpc MNOTE_PAGE_AI_PI_BIN=/tmp/mnote-pi-cli-wrapper.sh 启动
+// 可选：MNOTE_PI_LAB_OPENAI_API_KEY（真实 send 需要 API key）
+
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const BASE = process.env.MNOTE_PI_LAB_BASE || "http://127.0.0.1:3000";
+const AUTH = process.env.MNOTE_PI_LAB_AUTH || "Bearer pi-lab-smoke";
+const ROOT = process.env.MNOTE_PI_LAB_SMOKE_ROOT || fs.mkdtempSync(path.join(os.tmpdir(), "mnote-pi-rpc-"));
+const PI_BIN_ENV = process.env.MNOTE_PAGE_AI_PI_BIN || "/tmp/mnote-pi-cli-wrapper.sh";
+const HAS_API_KEY = !!(process.env.MNOTE_PI_LAB_OPENAI_API_KEY || process.env.OPENAI_API_KEY);
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+async function fetchJson(url, options = {}) {
+  const headers = {
+    "Content-Type": "application/json",
+    Authorization: AUTH,
+    ...(options.headers || {}),
+  };
+  const res = await fetch(url, { ...options, headers });
+  const text = await res.text();
+  let body = {};
+  try {
+    body = text ? JSON.parse(text) : {};
+  } catch {
+    body = { raw: text };
+  }
+  return { status: res.status, body, headers: res.headers };
+}
+
+/**
+ * Collect SSE events from /api/page-ai/pi/events for a short window.
+ */
+function collectSseEvents(sessionId, timeoutMs = 5000) {
+  return new Promise((resolve) => {
+    const events = [];
+    const url = `${BASE}/api/page-ai/pi/events?sessionId=${encodeURIComponent(sessionId)}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+      controller.abort();
+    }, timeoutMs);
+
+    fetch(url, {
+      headers: {
+        Authorization: AUTH,
+        Accept: "text/event-stream",
+      },
+      signal: controller.signal,
+    })
+      .then((res) => {
+        if (!res.ok) {
+          events.push({ error: `SSE returned ${res.status}` });
+          clearTimeout(timer);
+          resolve(events);
+          return;
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+
+        function read() {
+          reader
+            .read()
+            .then(({ done, value }) => {
+              if (done) {
+                clearTimeout(timer);
+                resolve(events);
+                return;
+              }
+              buffer += decoder.decode(value, { stream: true });
+              const lines = buffer.split("\n");
+              buffer = lines.pop() || "";
+              for (const line of lines) {
+                if (line.startsWith("data: ")) {
+                  try {
+                    const parsed = JSON.parse(line.slice(6));
+                    events.push(parsed);
+                  } catch {
+                    // skip parse errors
+                  }
+                }
+              }
+              read();
+            })
+            .catch((err) => {
+              if (err.name !== "AbortError") {
+                events.push({ error: err.message });
+              }
+              clearTimeout(timer);
+              resolve(events);
+            });
+        }
+        read();
+      })
+      .catch((err) => {
+        if (err.name !== "AbortError") {
+          events.push({ error: err.message });
+        }
+        clearTimeout(timer);
+        resolve(events);
+      });
+  });
+}
+
+/**
+ * Wait for a specific SSE event kind.
+ */
+async function waitForSseEvent(sessionId, targetKind, timeoutMs = 15000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const events = await collectSseEvents(sessionId, 3000);
+    const matched = events.find((e) => e.kind === targetKind);
+    if (matched) return matched;
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  return null;
+}
+
+async function main() {
+  fs.mkdirSync(ROOT, { recursive: true });
+  const pagePath = "page.md";
+  const pageFile = path.join(ROOT, pagePath);
+  fs.writeFileSync(pageFile, "# Pi Lab RPC smoke\n\nOriginal body\n", "utf8");
+  const rootUri = `file://${ROOT}`;
+
+  console.log(`\n🧪 Pi Lab RPC API smoke (base: ${BASE}, root: ${ROOT})`);
+  console.log(`   Pi binary: ${PI_BIN_ENV}`);
+  console.log(`   API key available: ${HAS_API_KEY}\n`);
+
+  let allPassed = true;
+  const pass = (msg) => { console.log(`  ✅ ${msg}`); };
+  const fail = (msg) => { console.error(`  ❌ ${msg}`); allPassed = false; };
+
+  // ── 1. Status: enabled=true, runtimeMode=rpc ──────────────────────
+  try {
+    const status = await fetchJson(`${BASE}/api/page-ai/pi/status`);
+    assert(status.status === 200, `status returned ${status.status}`);
+    assert(status.body.schema === "mnote.page_ai_pi.status.v1", "status schema mismatch");
+    assert(status.body.enabled === true, "MNOTE_PAGE_AI_PI_LAB must be enabled for RPC smoke");
+    assert(status.body.runtimeMode === "rpc", `runtimeMode must be rpc, got ${status.body.runtimeMode}`);
+    assert(Array.isArray(status.body.disabledPiBuiltinTools), "missing disabledPiBuiltinTools");
+    assert(status.body.disabledPiBuiltinTools.includes("bash"), "bash should be in disabled list");
+    assert(status.body.uiMode === "independent_mnote_native_drawer", "Pi Lab should report independent native drawer UI mode");
+    pass("status enabled/rpc with disabled builtins and independent Pi Lab UI mode");
+  } catch (err) {
+    fail(`status check: ${err.message}`);
+  }
+
+  // ── 2. Start session (triggers real Pi RPC subprocess) ────────────
+  let sessionId = null;
+  try {
+    const start = await fetchJson(`${BASE}/api/page-ai/pi/start`, {
+      method: "POST",
+      body: JSON.stringify({
+        rootUri,
+        workspaceId: "pi-lab-rpc-smoke",
+        pagePath,
+        pageTitle: "Pi Lab RPC smoke",
+      }),
+    });
+    assert(start.status === 200, `start returned ${start.status}: ${JSON.stringify(start.body)}`);
+    assert(start.body.schema === "mnote.page_ai_pi.start.v1", "start schema mismatch");
+    sessionId = start.body.session && start.body.session.sessionId;
+    assert(sessionId, "start did not return sessionId");
+    assert(start.body.session.runtimeMode === "rpc", `runtimeMode must be rpc, got ${start.body.session.runtimeMode}`);
+    assert(start.body.session.runtimePid, "RPC mode must have runtimePid (real Pi subprocess PID)");
+    assert(typeof start.body.session.runtimePid === "number", "runtimePid must be a number");
+    assert(start.body.session.runtimePid > 0, "runtimePid must be positive");
+    assert(start.body.session.allowedRootsSnapshot, "start did not capture allowed roots snapshot");
+    assert(Array.isArray(start.body.disabledPiBuiltinTools), "missing disabledPiBuiltinTools in start");
+    assert(start.body.mnoteToolOnly === true, "start must declare mnoteToolOnly");
+    pass(`start session ${sessionId} with real Pi PID ${start.body.session.runtimePid}`);
+  } catch (err) {
+    fail(`start: ${err.message}`);
+  }
+
+  // ── 3. SSE events endpoint ────────────────────────────────────────
+  if (sessionId) {
+    try {
+      const evtUrl = `${BASE}/api/page-ai/pi/events?sessionId=${encodeURIComponent(sessionId)}`;
+      const evtRes = await fetch(evtUrl, {
+        headers: { Authorization: AUTH, Accept: "text/event-stream" },
+        signal: AbortSignal.timeout(3000),
+      }).catch(() => null);
+      if (evtRes && evtRes.ok) {
+        const ct = evtRes.headers.get("content-type") || "";
+        assert(ct.includes("text/event-stream"), `unexpected Content-Type: ${ct}`);
+        pass("events SSE endpoint returns text/event-stream");
+      } else {
+        // May fail if session has no events yet - accept 200 only
+        assert(evtRes && evtRes.status === 200, `events returned ${evtRes ? evtRes.status : "timeout"}`);
+      }
+    } catch (err) {
+      fail(`events SSE: ${err.message}`);
+    }
+
+    // ── 4. Verify runtime start evidence ───────────────────────────
+    // runtime_started may be published before the smoke attaches to SSE, so
+    // treat the start response runtimePid as the hard assertion and use SSE as
+    // opportunistic event evidence.
+    try {
+      const runtimeEvent = await waitForSseEvent(sessionId, "runtime_started", 5000);
+      if (runtimeEvent) {
+        const payload = runtimeEvent.payload || {};
+        assert(payload.mode === "rpc", `mode must be rpc, got ${payload.mode}`);
+        assert(typeof payload.pid === "number", "PID must be a number in event");
+        assert(Array.isArray(payload.disabledBuiltinTools), "missing disabledBuiltinTools in event");
+        pass(`runtime_started event observed (mode=rpc, pid=${payload.pid})`);
+      } else {
+        const statusAfterStart = await fetchJson(`${BASE}/api/page-ai/pi/status`);
+        assert(statusAfterStart.status === 200, `status after start returned ${statusAfterStart.status}`);
+        assert(statusAfterStart.body.running === true, "status after start must show running=true");
+        assert(statusAfterStart.body.pid, "status after start must expose runtime PID");
+        pass(`runtime start confirmed by status (pid=${statusAfterStart.body.pid}); runtime_started SSE was already consumed`);
+      }
+    } catch (err) {
+      fail(`runtime start evidence: ${err.message}`);
+    }
+  }
+
+  // ── 5. Tool call: mnote.allowed_roots.describe ────────────────────
+  if (sessionId) {
+    try {
+      const allowed = await fetchJson(`${BASE}/api/page-ai/pi/tool-call`, {
+        method: "POST",
+        body: JSON.stringify({
+          sessionId,
+          toolName: "mnote.allowed_roots.describe",
+          params: {},
+        }),
+      });
+      assert(allowed.status === 200, `allowed roots returned ${allowed.status}`);
+      assert(allowed.body.ok === true, "allowed roots tool should be allowed");
+      assert(Array.isArray(allowed.body.result.allowedRoots), "allowed roots missing");
+      assert(allowed.body.receipt, "missing receipt");
+      assert(allowed.body.receipt.storage === "provider_neutral_jsonl_adapter_v1", "receipt storage mismatch");
+      pass("mnote.allowed_roots.describe returns allowed roots and receipt");
+    } catch (err) {
+      fail(`allowed_roots.describe: ${err.message}`);
+    }
+
+    // ── 6. Tool call: current page read ─────────────────────────────
+    try {
+      const currentPage = await fetchJson(`${BASE}/api/page-ai/pi/tool-call`, {
+        method: "POST",
+        body: JSON.stringify({
+          sessionId,
+          toolName: "mnote.current_page.read",
+          params: { rootUri, pagePath },
+        }),
+      });
+      assert(currentPage.status === 200 && currentPage.body.ok === true, "current page read failed");
+      assert(String(currentPage.body.result.content).includes("Original body"), "current page content mismatch");
+      assert(currentPage.body.result.format === "markdown", "format must be markdown");
+      assert(currentPage.body.result.fileVersion, "missing fileVersion");
+      pass("mnote.current_page.read returns page content with fileVersion");
+    } catch (err) {
+      fail(`current_page.read: ${err.message}`);
+    }
+
+    // ── 7. Tool call: out-of-bounds read denied ─────────────────────
+    try {
+      const denied = await fetchJson(`${BASE}/api/page-ai/pi/tool-call`, {
+        method: "POST",
+        body: JSON.stringify({
+          sessionId,
+          toolName: "mnote.local_file.read",
+          params: { path: "/etc/hosts" },
+        }),
+      });
+      assert(denied.status === 200, `deny read returned ${denied.status}`);
+      assert(denied.body.ok === false, "out-of-root read should be denied");
+      assert(denied.body.result.ok === false, "denied result must contain ok=false");
+      assert(denied.body.receipt, "denied read should still write receipt");
+      assert(denied.body.receipt.storage === "provider_neutral_jsonl_adapter_v1", "receipt storage mismatch");
+      pass("out-of-root read denied with receipt");
+    } catch (err) {
+      fail(`out-of-bound read: ${err.message}`);
+    }
+
+    // ── 8. Tool call: patch current .md file ────────────────────────
+    try {
+      const patch = await fetchJson(`${BASE}/api/page-ai/pi/tool-call`, {
+        method: "POST",
+        body: JSON.stringify({
+          sessionId,
+          toolName: "mnote.local_file.patch",
+          params: {
+            rootUri,
+            path: pagePath,
+            operations: [{ op: "replace", old: "Original body", new: "Patched by RPC smoke" }],
+          },
+        }),
+      });
+      assert(patch.status === 200 && patch.body.ok === true, "local file patch failed");
+      assert(patch.body.result.polling === false, "patch must not request polling");
+      assert(String(patch.body.result.refresh || "").includes("watcher"), "patch must declare watcher refresh");
+      assert(patch.body.result.beforeFileVersion, "missing beforeFileVersion");
+      assert(patch.body.result.afterFileVersion !== patch.body.result.beforeFileVersion,
+        "file version must change after patch");
+      assert(patch.body.result.diffSummary, "missing diffSummary");
+      const patchedContent = fs.readFileSync(pageFile, "utf8");
+      assert(patchedContent.includes("Patched by RPC smoke"), "patched file content mismatch");
+      assert(!patchedContent.includes("Original body"), "old content should be replaced in file");
+      assert(patch.body.receipt, "missing receipt");
+      pass("mnote.local_file.patch writes file + watcher refresh + version change + receipt");
+    } catch (err) {
+      fail(`local_file.patch: ${err.message}`);
+    }
+
+    // ── 9. Tool call: LightRAG knowledge_rag.query facade ───────────
+    try {
+      const rag = await fetchJson(`${BASE}/api/page-ai/pi/tool-call`, {
+        method: "POST",
+        body: JSON.stringify({
+          sessionId,
+          toolName: "mnote.knowledge_rag.query",
+          params: { rootUri, query: "Pi Lab RPC smoke", topK: 1 },
+        }),
+      });
+      assert(rag.status === 200, `knowledge RAG facade returned HTTP ${rag.status}`);
+      assert(typeof rag.body.ok === "boolean", "knowledge RAG facade did not return tool envelope");
+      assert(rag.body.receipt, "missing receipt");
+      // LightRAG may return empty results if no knowledge base indexed, that's OK
+      pass(`knowledge_rag.query facade exercised (ok=${rag.body.ok}, receipt present)`);
+    } catch (err) {
+      fail(`knowledge_rag.query: ${err.message}`);
+    }
+
+    // ── 10. Tool call: reference.open facade ────────────────────────
+    try {
+      const reference = await fetchJson(`${BASE}/api/page-ai/pi/tool-call`, {
+        method: "POST",
+        body: JSON.stringify({
+          sessionId,
+          toolName: "mnote.reference.open",
+          params: { rootUri, filePath: pagePath },
+        }),
+      });
+      assert(reference.status === 200, `reference.open facade returned HTTP ${reference.status}`);
+      assert(typeof reference.body.ok === "boolean", "reference.open facade did not return tool envelope");
+      assert(reference.body.receipt, "missing receipt");
+      pass(`reference.open facade exercised (ok=${reference.body.ok})`);
+    } catch (err) {
+      fail(`reference.open: ${err.message}`);
+    }
+
+    // ── 11. Send prompt (only if API key available) ─────────────────
+    if (HAS_API_KEY) {
+      try {
+        const marker = `REAL_PI_TOOL_BRIDGE_OK_${Date.now()}`;
+        const pendingEvents = collectSseEvents(sessionId, 45000);
+        const send = await fetchJson(`${BASE}/api/page-ai/pi/send`, {
+          method: "POST",
+          body: JSON.stringify({
+            sessionId,
+            message: `You must call the available tool named mnote_current_page_read before answering. After reading the page, reply exactly ${marker} if the tool result contains "Patched by RPC smoke". Do not explain.`,
+          }),
+        });
+        assert(send.status === 200 && send.body.accepted === true, "send did not accept prompt");
+        assert(send.body.schema === "mnote.page_ai_pi.send.v1", "send schema mismatch");
+        assert(send.body.eventStream, "send must return eventStream path");
+        pass("send accepts prompt and routes to Pi RPC stdin");
+
+        const events = await pendingEvents;
+        const eventText = JSON.stringify(events);
+        const hasPiToolStart = events.some((event) =>
+          event.kind === "pi_rpc_event"
+          && event.payload?.type === "tool_execution_start"
+          && event.payload?.toolName === "mnote_current_page_read"
+        );
+        const hasMnoteBridgeTool = events.some((event) =>
+          event.kind === "tool_call"
+          && event.payload?.toolName === "mnote.current_page.read"
+        );
+        assert(hasPiToolStart, "Pi did not emit mnote_current_page_read tool_execution_start");
+        assert(hasMnoteBridgeTool, "MNote bridge did not execute mnote.current_page.read");
+        assert(eventText.includes(marker), "Pi final response marker not observed after tool call");
+        pass("real Pi custom tool call flows through MNote bridge and returns marker");
+      } catch (err) {
+        fail(`send: ${err.message}`);
+      }
+    } else {
+      console.log("  ⏭ Send/abort skipped (set MNOTE_PI_LAB_OPENAI_API_KEY for real Pi RPC prompt test)");
+    }
+
+    // ── 13. Abort ───────────────────────────────────────────────────
+    // Abort works even without API key - it kills the Pi subprocess
+    try {
+      const abort = await fetchJson(`${BASE}/api/page-ai/pi/abort`, {
+        method: "POST",
+        body: JSON.stringify({ sessionId }),
+      });
+      assert(abort.status === 200, `abort returned ${abort.status}`);
+      assert(abort.body.aborted === true, "abort must return aborted=true");
+      assert(abort.body.schema === "mnote.page_ai_pi.abort.v1", "abort schema mismatch");
+      pass("abort kills Pi RPC subprocess and returns aborted=true");
+    } catch (err) {
+      fail(`abort: ${err.message}`);
+    }
+
+    // ── 14. Verify session status changed to Aborted ────────────────
+    try {
+      const status2 = await fetchJson(`${BASE}/api/page-ai/pi/status`);
+      assert(status2.body.session, "status should return current session");
+      assert(
+        status2.body.session.status === "aborted",
+        `expected session status aborted, got ${status2.body.session.status}`
+      );
+      pass("session status transitions to aborted");
+    } catch (err) {
+      fail(`session status aborted: ${err.message}`);
+    }
+
+    // ── 15. Start a second session to verify multi-session lifecycle ─
+    try {
+      const start2 = await fetchJson(`${BASE}/api/page-ai/pi/start`, {
+        method: "POST",
+        body: JSON.stringify({
+          rootUri,
+          workspaceId: "pi-lab-rpc-smoke-2",
+          pagePath,
+          pageTitle: "Pi Lab RPC smoke 2",
+        }),
+      });
+      assert(start2.status === 200, `second start returned ${start2.status}`);
+      const session2Id = start2.body.session && start2.body.session.sessionId;
+      assert(session2Id, "second start did not return sessionId");
+      assert(session2Id !== sessionId, "second session must have different ID");
+      assert(start2.body.session.runtimePid, "second session must also have runtimePid");
+      pass(`second session ${session2Id} started with PID ${start2.body.session.runtimePid}`);
+
+      // Clean up second session
+      const abort2 = await fetchJson(`${BASE}/api/page-ai/pi/abort`, {
+        method: "POST",
+        body: JSON.stringify({ sessionId: session2Id }),
+      });
+      assert(abort2.status === 200, `second abort returned ${abort2.status}`);
+      assert(abort2.body.aborted === true, "second abort must return aborted=true");
+      pass("second session abort cleans up Pi subprocess");
+    } catch (err) {
+      fail(`multi-session lifecycle: ${err.message}`);
+    }
+  }
+
+  // ── 16. Runtime browser asset integrity ───────────────────────────
+  try {
+    const res = await fetch(`${BASE}/api/mnote-browser-runtime/sidebar-page-ai-pi-lab-runtime.js`);
+    assert(res.status === 200, `runtime asset status ${res.status}`);
+    const text = await res.text();
+    assert(text.includes("createSidebarPageAiPiLabRuntime"), "missing expected export");
+    assert(!/setInterval\s*\(/.test(text), "runtime should not use setInterval polling");
+    assert(text.includes("NO setInterval polling"), "missing NO setInterval polling comment");
+    assert(text.includes("/api/page-ai/pi/start"), "missing start endpoint");
+    assert(text.includes("/api/page-ai/pi/send"), "missing send endpoint");
+    assert(text.includes("/api/page-ai/pi/abort"), "missing abort endpoint");
+    assert(text.includes("/api/page-ai/pi/events"), "missing events endpoint");
+    pass("client runtime JS served with correct endpoints and no polling");
+  } catch (err) {
+    fail(`runtime asset: ${err.message}`);
+  }
+
+  // ── Summary ───────────────────────────────────────────────────────
+  if (allPassed) {
+    console.log("\n✅ Pi Lab RPC API smoke passed.\n");
+  } else {
+    console.error("\n❌ Pi Lab RPC API smoke: some checks failed.\n");
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error(`\n❌ Pi Lab RPC API smoke failed: ${error.message}`);
+  process.exit(1);
+});
diff --git a/scripts/task-pi-lab-rpc-browser-smoke.js b/scripts/task-pi-lab-rpc-browser-smoke.js
new file mode 100644
index 00000000..2805ce31
--- /dev/null
+++ b/scripts/task-pi-lab-rpc-browser-smoke.js
@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+// Pi Lab RPC browser smoke
+// 验证真实 Pi RPC + Omniroute/freefirst 在 MNote-native Pi Lab 抽屉中的可见 stream。
+// 需要 mnote-web 已以 MNOTE_PAGE_AI_PI_LAB_RUNTIME=rpc 启动，并配置 MNOTE_PAGE_AI_PI_BIN / Omniroute key。
+
+"use strict";
+
+const assert = require("node:assert");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { chromium } = require("playwright");
+
+const BASE = process.env.MNOTE_PI_LAB_BASE || "http://127.0.0.1:3000";
+const AUTH = process.env.MNOTE_PI_LAB_AUTH || "Bearer pi-lab-smoke";
+const ROOT = process.env.MNOTE_PI_LAB_BROWSER_ROOT || fs.mkdtempSync(path.join(os.tmpdir(), "mnote-pi-rpc-browser-"));
+const UI_TIMEOUT_MS = Number.parseInt(process.env.UI_TIMEOUT_MS || "45000", 10);
+const MARKER = process.env.MNOTE_PI_LAB_RPC_MARKER || `REAL_PI_BROWSER_OK_${Date.now()}`;
+const SCREENSHOT = process.env.MNOTE_PI_LAB_SCREENSHOT || path.join(
+  __dirname,
+  "..",
+  "tmp",
+  `page-ai-pi-lab-rpc-browser-${new Date().toISOString().replace(/[:.]/g, "-")}.png`,
+);
+const CHROMIUM_EXECUTABLE = process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE
+  || (fs.existsSync("/usr/bin/chromium-browser") ? "/usr/bin/chromium-browser" : "")
+  || (fs.existsSync("/usr/bin/chromium") ? "/usr/bin/chromium" : "")
+  || (fs.existsSync("/usr/bin/google-chrome") ? "/usr/bin/google-chrome" : "");
+
+function authHeaders() {
+  if (!AUTH) return {};
+  if (AUTH.toLowerCase().startsWith("bearer ")) return { Authorization: AUTH };
+  return { Cookie: AUTH };
+}
+
+function pathMatchesPage(value, expectedPagePath) {
+  const normalized = String(value || "").replace(/\\/g, "/");
+  return normalized === expectedPagePath || normalized.endsWith(`/${expectedPagePath}`);
+}
+
+async function addAuth(context) {
+  const headers = authHeaders();
+  if (headers.Authorization) await context.setExtraHTTPHeaders({ Authorization: headers.Authorization });
+  if (!headers.Cookie) return;
+  const cookies = headers.Cookie.split(";").map((cookie) => {
+    const [name, ...rest] = cookie.trim().split("=");
+    return { name, value: rest.join("="), domain: "127.0.0.1", path: "/" };
+  });
+  await context.addCookies(cookies);
+}
+
+async function quickLoginIfNeeded(page) {
+  const authResponse = await page.goto(`${BASE}/auth`, { waitUntil: "domcontentloaded", timeout: UI_TIMEOUT_MS });
+  if (!authResponse || authResponse.status() >= 400) return;
+  const quickLoginButton = page.getByRole("button", { name: "测试账号快速登录" });
+  if (!(await quickLoginButton.isVisible({ timeout: 4000 }).catch(() => false))) return;
+  await Promise.all([
+    page.waitForURL((url) => !url.toString().includes("/auth"), { timeout: UI_TIMEOUT_MS }).catch(() => null),
+    quickLoginButton.click(),
+  ]);
+}
+
+async function main() {
+  let browserRoot = ROOT;
+  fs.mkdirSync(browserRoot, { recursive: true });
+  const pagePath = "__pi_lab_rpc_browser_smoke.md";
+  let pageFile = path.join(browserRoot, pagePath);
+  fs.writeFileSync(pageFile, "# Pi Lab RPC browser smoke\n\nBrowser RPC Original\n", "utf8");
+  let rootUri = `file://${browserRoot}`;
+  const documentId = `local-md:${pagePath}`;
+
+  console.log(`\n🧪 Pi Lab RPC browser smoke (base: ${BASE}, root: ${ROOT})`);
+  console.log(`   marker: ${MARKER}\n`);
+
+  const browser = await chromium.launch({
+    headless: process.env.MNOTE_PI_LAB_HEADED === "1" ? false : true,
+    executablePath: CHROMIUM_EXECUTABLE || undefined,
+  });
+  const context = await browser.newContext({ viewport: { width: 1440, height: 960 } });
+  await addAuth(context);
+  const page = await context.newPage();
+  const consoleErrors = [];
+  page.on("console", (message) => {
+    if (["error", "warning"].includes(message.type())) {
+      consoleErrors.push(`${message.type()}: ${message.text()}`);
+    }
+  });
+  page.on("pageerror", (error) => consoleErrors.push(`pageerror: ${error.message}`));
+
+  try {
+    const statusBefore = await page.request.get(`${BASE}/api/page-ai/pi/status`, { headers: authHeaders() });
+    assert(statusBefore.ok(), `status before browser should be OK, got ${statusBefore.status()}`);
+    const statusBeforeJson = await statusBefore.json();
+    assert.equal(statusBeforeJson.enabled, true, "Pi Lab must be enabled");
+    assert.equal(statusBeforeJson.runtimeMode, "rpc", `runtimeMode must be rpc, got ${statusBeforeJson.runtimeMode}`);
+    assert.equal(statusBeforeJson.defaultModelProvider, "omniroute", "default provider must be omniroute");
+    assert.equal(statusBeforeJson.defaultModelId, "freefirst", "default model must be freefirst");
+    console.log("  ✅ status reports rpc + omniroute/freefirst");
+
+    await quickLoginIfNeeded(page);
+    if (!process.env.MNOTE_PI_LAB_BROWSER_URL) {
+      const defaultE2eRoot = "/mnt/Data1T/Mnote_data/users/mnote-e2e/workspaces/my-space";
+      if (fs.existsSync(defaultE2eRoot)) {
+        browserRoot = defaultE2eRoot;
+        rootUri = `file://${browserRoot}`;
+        pageFile = path.join(browserRoot, pagePath);
+        fs.mkdirSync(browserRoot, { recursive: true });
+        fs.writeFileSync(pageFile, "# Pi Lab RPC browser smoke\n\nBrowser RPC Original\n", "utf8");
+      }
+      const loginStatus = await page.request.get(`${BASE}/api/page-ai/pi/status`);
+      if (loginStatus.ok()) {
+        const loginStatusJson = await loginStatus.json();
+        const firstAllowedRoot = loginStatusJson.session?.allowedRootsSnapshot?.roots?.[0]
+          || loginStatusJson.allowedRootsSnapshot?.roots?.[0]
+          || null;
+        if (!fs.existsSync(defaultE2eRoot) && firstAllowedRoot?.rootPath) {
+          browserRoot = String(firstAllowedRoot.rootPath);
+          rootUri = String(firstAllowedRoot.rootUri || `file://${browserRoot}`);
+          pageFile = path.join(browserRoot, pagePath);
+          fs.mkdirSync(browserRoot, { recursive: true });
+          fs.writeFileSync(pageFile, "# Pi Lab RPC browser smoke\n\nBrowser RPC Original\n", "utf8");
+        }
+      }
+    }
+    const targetUrl = process.env.MNOTE_PI_LAB_BROWSER_URL
+      || `${BASE}/documents/${documentId}?sourceKind=local_folder&rootUri=${encodeURIComponent(rootUri)}`;
+    const response = await page.goto(targetUrl, { waitUntil: "commit", timeout: UI_TIMEOUT_MS });
+    assert(response && response.status() >= 200 && response.status() < 400, `MNote shell load failed: ${response && response.status()}`);
+    await page.locator(".ProseMirror").first().waitFor({ state: "visible", timeout: UI_TIMEOUT_MS }).catch(() => null);
+    await page.waitForFunction(() => typeof window.createSidebarPageAiPiLabRuntime === "function", null, {
+      timeout: UI_TIMEOUT_MS,
+    });
+    await page.locator("[data-page-ai-pi-lab-launcher]").waitFor({ state: "visible", timeout: UI_TIMEOUT_MS });
+    await page.locator("[data-page-ai-pi-lab-launcher]").click();
+    await page.locator('[data-page-ai-pi-lab="drawer"]').waitFor({ state: "visible", timeout: UI_TIMEOUT_MS });
+    console.log("  ✅ independent Pi Lab launcher and drawer visible");
+
+    const startButton = page.locator("[data-page-ai-pi-lab-btn-start]");
+    let startJson = null;
+    if (await startButton.isVisible({ timeout: 2000 }).catch(() => false)) {
+      const startRespPromise = page.waitForResponse((res) => res.url().includes("/api/page-ai/pi/start") && res.request().method() === "POST", {
+        timeout: UI_TIMEOUT_MS,
+      });
+      await startButton.click();
+      const startResp = await startRespPromise;
+      assert(startResp.ok(), `start response failed: ${startResp.status()}`);
+      startJson = await startResp.json();
+      assert(pathMatchesPage(startJson.session?.pagePath, pagePath), `start response should bind pagePath=${pagePath}, got ${startJson.session?.pagePath}`);
+    }
+    await page.waitForFunction(() => {
+      const text = document.querySelector("[data-page-ai-pi-lab-status-text]")?.textContent || "";
+      return text.includes("ready");
+    }, null, { timeout: UI_TIMEOUT_MS });
+    const statusAfterStart = await page.request.get(`${BASE}/api/page-ai/pi/status`, { headers: authHeaders() });
+    const statusAfterStartJson = await statusAfterStart.json();
+    const activeSession = startJson?.session || statusAfterStartJson.session || {};
+    const sessionId = activeSession.sessionId || statusAfterStartJson.sessionId;
+    assert(sessionId, "start should create sessionId");
+    assert(activeSession.runtimePid || statusAfterStartJson.pid, "RPC start should expose runtime pid");
+    assert(pathMatchesPage(activeSession.pagePath, pagePath), `session pagePath should bind current page when new session starts, got ${activeSession.pagePath}`);
+    const firstAllowedRoot = activeSession.allowedRootsSnapshot?.roots?.[0] || null;
+    if (firstAllowedRoot?.rootPath) {
+      browserRoot = String(firstAllowedRoot.rootPath);
+      rootUri = String(firstAllowedRoot.rootUri || `file://${browserRoot}`);
+      pageFile = path.join(browserRoot, pagePath);
+      fs.mkdirSync(browserRoot, { recursive: true });
+      fs.writeFileSync(pageFile, "# Pi Lab RPC browser smoke\n\nBrowser RPC Original\n", "utf8");
+    }
+    console.log(`  ✅ Pi RPC runtime started, session=${sessionId}, pid=${activeSession.runtimePid || statusAfterStartJson.pid}`);
+
+    const currentPageChip = await page.locator("[data-page-ai-pi-lab-current-page]").textContent();
+    assert(currentPageChip && !/未绑定/.test(currentPageChip), `current page chip should be bound, got ${currentPageChip}`);
+
+    const editor = page.locator(".ProseMirror").first();
+    if (await editor.isVisible({ timeout: 5000 }).catch(() => false)) {
+      await page.evaluate(() => {
+        const root = document.querySelector(".ProseMirror");
+        if (!root) return;
+        const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+        let node = null;
+        while ((node = walker.nextNode())) {
+          const index = String(node.textContent || "").indexOf("Browser RPC Original");
+          if (index >= 0) {
+            const range = document.createRange();
+            range.setStart(node, index);
+            range.setEnd(node, index + "Browser RPC Original".length);
+            const selection = window.getSelection();
+            selection.removeAllRanges();
+            selection.addRange(range);
+            break;
+          }
+        }
+      });
+      await page.waitForFunction(() => {
+        const text = document.querySelector("[data-page-ai-pi-lab-selection]")?.textContent || "";
+        return text.includes("已选中");
+      }, null, { timeout: UI_TIMEOUT_MS });
+      await page.locator('.wolai-page-ai-pi-lab-composer-bar [data-page-ai-pi-lab-quick="selection"]').click();
+      await page.waitForFunction(() => {
+        const input = document.querySelector("[data-page-ai-pi-lab-input]");
+        return (input?.value || "").includes("Browser RPC Original");
+      }, null, { timeout: UI_TIMEOUT_MS });
+      console.log("  ✅ selection quick action injects live tiptap selection into composer");
+
+      await page.locator('.wolai-page-ai-pi-lab-composer-bar [data-page-ai-pi-lab-quick="read-page"]').click();
+      await page.waitForFunction(() => {
+        const input = document.querySelector("[data-page-ai-pi-lab-input]");
+        return (input?.value || "").includes("Browser RPC Original");
+      }, null, { timeout: UI_TIMEOUT_MS });
+      console.log("  ✅ current page quick action calls mnote.current_page.read");
+    }
+
+    const denyResp = await page.request.post(`${BASE}/api/page-ai/pi/tool-call`, {
+      headers: authHeaders(),
+      data: { sessionId, toolName: "mnote.local_file.read", params: { path: "/etc/hosts" } },
+    });
+    assert(denyResp.ok(), `deny tool call HTTP ${denyResp.status()}`);
+    const denyJson = await denyResp.json();
+    assert.equal(denyJson.ok, false, "out-of-root read must be denied");
+
+    const patchResp = await page.request.post(`${BASE}/api/page-ai/pi/tool-call`, {
+      headers: authHeaders(),
+      data: {
+        sessionId,
+        toolName: "mnote.local_file.patch",
+        params: {
+          path: pageFile,
+          operations: [{ op: "replace", old: "Browser RPC Original", new: "Browser RPC Patched" }],
+        },
+      },
+    });
+    assert(patchResp.ok(), `patch tool call HTTP ${patchResp.status()}`);
+    const patchJson = await patchResp.json();
+    assert.equal(patchJson.ok, true, "patch should be allowed");
+    assert.equal(patchJson.result.polling, false, "patch must not request polling");
+    assert(String(patchJson.result.refresh || "").includes("watcher"), "patch should declare watcher refresh");
+    assert(fs.readFileSync(pageFile, "utf8").includes("Browser RPC Patched"), "patch should update markdown file");
+    if (await editor.isVisible({ timeout: 1000 }).catch(() => false)) {
+      await page.waitForFunction(() => {
+        const editorNode = document.querySelector(".ProseMirror");
+        return (editorNode?.textContent || "").includes("Browser RPC Patched");
+      }, null, { timeout: UI_TIMEOUT_MS });
+    }
+    console.log("  ✅ allowed-roots deny and markdown patch receipt exercised");
+
+    await page.waitForFunction(() => {
+      const text = document.querySelector("[data-page-ai-pi-lab-receipts]")?.textContent || "";
+      return text.includes("denied") && text.includes("diff");
+    }, null, { timeout: UI_TIMEOUT_MS });
+
+    await page.locator("[data-page-ai-pi-lab-input]").fill(`请只回复 ${MARKER}，不要解释。`);
+    await page.locator("[data-page-ai-pi-lab-btn-send]").click();
+    const assistantMarker = page
+      .locator('[data-page-ai-pi-lab-message-role="assistant"] .wolai-page-ai-pi-lab-text')
+      .filter({ hasText: MARKER })
+      .last();
+    await assistantMarker.waitFor({ state: "visible", timeout: UI_TIMEOUT_MS });
+    const visibleText = await assistantMarker.textContent();
+    assert(visibleText.includes(MARKER), "visible assistant bubble should contain marker");
+    assert(!visibleText.includes("thinking_delta"), "provider thinking event name must not be visible");
+    assert(!visibleText.includes("我们被问到"), "provider reasoning text must not leak into final visible reply");
+    console.log("  ✅ real Pi RPC stream rendered in UI without visible reasoning leakage");
+
+    fs.mkdirSync(path.dirname(SCREENSHOT), { recursive: true });
+    await page.screenshot({ path: SCREENSHOT, fullPage: false });
+    console.log(`  ✅ screenshot: ${SCREENSHOT}`);
+
+    const abortResp = await page.request.post(`${BASE}/api/page-ai/pi/abort`, {
+      headers: authHeaders(),
+      data: { sessionId },
+    });
+    assert(abortResp.ok(), `abort HTTP ${abortResp.status()}`);
+    await page.waitForFunction(() => {
+      const text = document.querySelector("[data-page-ai-pi-lab-status-text]")?.textContent || "";
+      return text.includes("aborted");
+    }, null, { timeout: UI_TIMEOUT_MS });
+    console.log("  ✅ abort reflected in UI state");
+
+    const domEvidence = await page.evaluate(() => {
+      const openHubDrawer = document.querySelector('[data-testid="wolai-page-ai-drawer"]');
+      const piDrawer = document.querySelector('[data-page-ai-pi-lab="drawer"]');
+      return {
+        piDrawerVisible: Boolean(piDrawer && getComputedStyle(piDrawer).display !== "none"),
+        piDrawerHasIframe: Boolean(piDrawer && piDrawer.querySelector("iframe")),
+        piInsideOpenHub: Boolean(openHubDrawer && piDrawer && openHubDrawer.contains(piDrawer)),
+        model: document.querySelector("[data-page-ai-pi-lab-model-chip]")?.textContent || "",
+      };
+    });
+    assert(domEvidence.piDrawerVisible, "Pi drawer should remain visible");
+    assert.equal(domEvidence.piDrawerHasIframe, false, "Pi drawer must not iframe a second app");
+    assert.equal(domEvidence.piInsideOpenHub, false, "Pi drawer must not be inside OpenHub drawer");
+    assert(domEvidence.model.includes("omniroute/freefirst"), `model chip mismatch: ${domEvidence.model}`);
+    console.log("  ✅ Pi Lab remains native, independent and non-iframe");
+
+    const severe = consoleErrors.filter((entry) => /Failed to load module script|MIME type|Uncaught|TypeError|ReferenceError/i.test(entry));
+    assert.equal(severe.length, 0, `severe console errors: ${severe.join(" | ")}`);
+    console.log("\n✅ Pi Lab RPC browser smoke passed\n");
+  } catch (error) {
+    console.error(`\n❌ Pi Lab RPC browser smoke failed: ${error.message}`);
+    if (consoleErrors.length) console.error(consoleErrors.slice(0, 10).join("\n"));
+    process.exitCode = 1;
+  } finally {
+    await browser.close();
+  }
+}
+
+main();
diff --git a/scripts/task-pi-lab-static-smoke.js b/scripts/task-pi-lab-static-smoke.js
new file mode 100644
index 00000000..e1f2a59e
--- /dev/null
+++ b/scripts/task-pi-lab-static-smoke.js
@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+// Pi Lab static code smoke
+// 验证 Pi Lab 相关源码结构正确，不依赖后端运行
+// 确认：新端点、状态机、无轮询、SSE、Pi builtin 禁用、allowed roots、receipt
+// 确认：默认模型 omniroute/freefirst 在前端 UI 和 header 中明确体现
+
+const fs = require('fs');
+const path = require('path');
+
+const repoRoot = path.resolve(__dirname, '..');
+
+// Files to check
+const files = {
+  runtime: path.join(repoRoot, 'rust/crates/mnote-web/browser/sidebar-page-ai-pi-lab-runtime.js'),
+  route: path.join(repoRoot, 'rust/crates/mnote-web/src/routes/page_ai_pi.rs'),
+  mod: path.join(repoRoot, 'rust/crates/mnote-web/src/routes/mod.rs'),
+  webShell: path.join(repoRoot, 'rust/crates/mnote-web/src/routes/web_shell.rs'),
+  gateway: path.join(repoRoot, 'rust/crates/mnote-web/src/routes/gateway.rs'),
+  app: path.join(repoRoot, 'rust/crates/mnote-web/src/app.rs'),
+};
+
+function readFile(p) {
+  try { return fs.readFileSync(p, 'utf8'); } catch { return ''; }
+}
+
+const runtime = readFile(files.runtime);
+const route = readFile(files.route);
+const routesMod = readFile(files.mod);
+const webShell = readFile(files.webShell);
+const gateway = readFile(files.gateway);
+const app = readFile(files.app);
+
+const checks = [
+  // === Runtime JS: existence ===
+  ['runtime JS exists', runtime.length > 0],
+  ['runtime exports createSidebarPageAiPiLabRuntime', runtime.includes('window.createSidebarPageAiPiLabRuntime')],
+
+  // === Runtime JS: API endpoints (new flow: start/send/abort/events) ===
+  ['runtime uses /api/page-ai/pi/status', runtime.includes('/api/page-ai/pi/status')],
+  ['runtime uses /api/page-ai/pi/start', runtime.includes('/api/page-ai/pi/start')],
+  ['runtime uses /api/page-ai/pi/send', runtime.includes('/api/page-ai/pi/send')],
+  ['runtime uses /api/page-ai/pi/abort', runtime.includes('/api/page-ai/pi/abort')],
+  ['runtime uses /api/page-ai/pi/events', runtime.includes('/api/page-ai/pi/events')],
+  ['runtime keeps legacy /api/page-ai/pi/bootstrap fallback', runtime.includes('/api/page-ai/pi/bootstrap')],
+
+  // === Runtime JS: state machine ===
+  ['runtime has idle state', runtime.includes("STATE_IDLE") || (runtime.includes("'idle'") && runtime.includes('STATE_IDLE'))],
+  ['runtime has starting state', runtime.includes("STATE_STARTING")],
+  ['runtime has started state', runtime.includes("STATE_STARTED")],
+  ['runtime has streaming state', runtime.includes("STATE_STREAMING")],
+  ['runtime has aborted state', runtime.includes("STATE_ABORTED")],
+  ['runtime has error state', runtime.includes("STATE_ERROR")],
+
+  // === Runtime JS: NO periodic polling ===
+  ['runtime does NOT use setInterval for periodic polling',
+    !runtime.includes('setInterval(checkStatus') && !runtime.includes("setInterval(checkStatus") &&
+    !runtime.match(/setInterval\s*\([^)]*checkStatus/i)],
+  ['runtime comments "NO setInterval polling"', runtime.includes('NO setInterval polling')],
+
+  // === Runtime JS: SSE / EventSource ===
+  ['runtime uses EventSource for SSE', runtime.includes('EventSource')],
+  ['runtime connects to /api/page-ai/pi/events via SSE', runtime.includes('API.EVENTS') || runtime.includes('/api/page-ai/pi/events')],
+  ['runtime handles pi_rpc_event from SSE', runtime.includes('pi_rpc_event')],
+  ['runtime handles runtime_started event', runtime.includes('runtime_started')],
+  ['runtime handles runtime_aborted event', runtime.includes('runtime_aborted')],
+
+  // === Runtime JS: UI rendering ===
+  ['runtime renders stream text', runtime.includes('text_delta') || runtime.includes('streamingAssistantMsg.text')],
+  ['runtime renders tool calls', runtime.includes('toolCalls')],
+  ['runtime renders citations', runtime.includes('citations')],
+  ['runtime renders diff summary', runtime.includes('diffSummary')],
+  ['runtime has start button', runtime.includes('btn-start')],
+  ['runtime has send button', runtime.includes('btn-send')],
+  ['runtime has abort button', runtime.includes('btn-abort')],
+  ['runtime has clear button', runtime.includes('btn-clear')],
+
+  // === Runtime JS: Pi builtin disabled ===
+  ['runtime handles disabledPiBuiltinTools from status/start', runtime.includes('disabledBuiltinTools') || runtime.includes('disabledPiBuiltinTools')],
+  ['runtime has Pi builtin disabled UI indicator', runtime.includes('builtin-disabled')],
+  ['runtime mentions bash/read/write/edit disabled', runtime.includes('bash') && runtime.includes('read') && runtime.includes('write') && runtime.includes('edit')],
+
+  // === Runtime JS: tool receipt ===
+  ['runtime references receipt', runtime.includes('receipt') || runtime.includes('Receipt')],
+  ['runtime has receipt UI display', runtime.includes('receipts')],
+
+  // === Runtime JS: independent native drawer ===
+  ['runtime checks enabled flag via status API but does not hide launcher behind it', runtime.includes('enabled') && runtime.includes('checkStatus')],
+  ['runtime renders independent Pi Lab drawer', runtime.includes('data-page-ai-pi-lab-drawer') && runtime.includes('data-page-ai-pi-lab') && runtime.includes('drawer')],
+  ['runtime creates drawer through ensureDrawer', runtime.includes('function ensureDrawer') && runtime.includes('setDrawerVisible')],
+  ['runtime does NOT mount inside OpenHub drawer', !runtime.includes('attachPanelToDrawer') && !runtime.includes('wolai-page-ai-drawer')],
+  ['runtime does NOT toggle OpenHub iframe visibility', !runtime.includes('setOpenHubVisible') && !runtime.includes('data-page-ai-openhub-frame-wrap')],
+  ['runtime has no OpenHub provider tab inside Pi Lab', !runtime.includes('data-page-ai-pi-lab-openhub-tab')],
+  ['runtime has context strip chips', runtime.includes('data-page-ai-pi-lab-context-strip') && runtime.includes('data-page-ai-pi-lab-current-page') && runtime.includes('data-page-ai-pi-lab-allowed-roots') && runtime.includes('data-page-ai-pi-lab-lightrag')],
+  ['runtime collapses secondary context/settings like OpenHub chrome', runtime.includes('
 0],
+  ['route has status endpoint', route.includes('pub async fn status')],
+  ['route has start endpoint', route.includes('pub async fn start')],
+  ['route has send endpoint', route.includes('pub async fn send')],
+  ['route has abort endpoint', route.includes('pub async fn abort')],
+  ['route has events SSE endpoint', route.includes('pub async fn events')],
+  ['route has bootstrap endpoint (legacy)', route.includes('pub async fn bootstrap')],
+  ['route has tool_call endpoint', route.includes('pub async fn tool_call')],
+  ['route has internal tool_call_bridge endpoint', route.includes('pub async fn tool_call_bridge')],
+  ['route uses AppConfig enable_page_ai_pi_lab instead of direct env gate', route.includes('state.config().enable_page_ai_pi_lab') && !route.includes('std::env::var("MNOTE_PAGE_AI_PI_LAB")')],
+  ['route returns enabled=false when not enabled', route.includes('"enabled": false')],
+  ['route marks independent native drawer ui mode', route.includes('independent_mnote_native_drawer')],
+  ['route does not return openHubDefaultPreserved marker', !route.includes('openHubDefaultPreserved')],
+  ['route returns schema mnote.page_ai_pi.status.v1', route.includes('mnote.page_ai_pi.status.v1')],
+  ['route returns schema mnote.page_ai_pi.bootstrap.v1', route.includes('mnote.page_ai_pi.bootstrap.v1')],
+  ['route returns schema mnote.page_ai_pi.start.v1', route.includes('mnote.page_ai_pi.start.v1')],
+  ['route returns schema mnote.page_ai_pi.send.v1', route.includes('mnote.page_ai_pi.send.v1')],
+  ['route returns schema mnote.page_ai_pi.abort.v1', route.includes('mnote.page_ai_pi.abort.v1')],
+  ['route has event schema PI_LAB_SCHEMA_EVENT', route.includes('PI_LAB_SCHEMA_EVENT')],
+  ['route has receipt schema PI_LAB_SCHEMA_RECEIPT', route.includes('PI_LAB_SCHEMA_RECEIPT')],
+  ['route disables Pi builtin tools', route.includes('disabledPiBuiltinTools') || route.includes('--no-builtin-tools')],
+  ['route has receipt storage policy', route.includes('receiptStorage') || route.includes('PI_LAB_SCHEMA_RECEIPT')],
+  ['route has session dir policy', route.includes('managedPiSessionDirPolicy')],
+  ['route enforces allowed roots', route.includes('active_allowed_roots') || route.includes('allowed_roots')],
+  ['route blocks path escape', route.includes('path_escape') || route.includes('path_is_inside')],
+  ['route has default model provider constant PI_LAB_DEFAULT_MODEL_PROVIDER=omniroute', route.includes('PI_LAB_DEFAULT_MODEL_PROVIDER') && route.includes('omniroute')],
+  ['route has default model id constant PI_LAB_DEFAULT_MODEL_ID=freefirst', route.includes('PI_LAB_DEFAULT_MODEL_ID') && route.includes('freefirst')],
+  ['route rejects arbitrary cookie_header auth bypass', route.includes('page_ai_pi_lab_invalid_session_cookie') && !route.includes('context.auth.cookie_header.is_some() {\n        return Ok') ],
+  ['route stores Pi Lab session owner id', route.includes('mnote_user_id') && route.includes('ensure_session_owner')],
+  ['route validates session owner on send/abort/tool/events', route.includes('get_session_for_context')],
+  ['route requires sidebar host selection snapshot', route.includes('page_ai_pi_lab_selection_snapshot_required') && route.includes('mnote_sidebar_host_snapshot')],
+  ['route tool_receipt.write is not a silent no-op', route.includes('"requestedReceipt"') && route.includes('execute_tool 统一写入')],
+  ['route has bridge token header and non-serialized session token', route.includes('HEADER_PI_LAB_BRIDGE_TOKEN') && route.includes('x-mnote-pi-lab-bridge-token') && route.includes('skip_serializing')],
+  ['route generates bridge token from OS randomness', route.includes('generate_bridge_token') && route.includes('/dev/urandom') && !route.includes('bridge_token: generate_id("pi_bridge")')],
+  ['route does not write bridge token literal into extension file', route.includes('MNOTE_PI_LAB_BRIDGE_TOKEN') && route.includes('process.env.MNOTE_PI_LAB_BRIDGE_TOKEN') && !route.includes('const BRIDGE_TOKEN = {bridge_token}')],
+  ['route rejects bridge calls for non-running sessions', route.includes('page_ai_pi_lab_bridge_session_not_running') && route.includes('PiLabSessionStatus::RuntimeRunning | PiLabSessionStatus::TurnRunning')],
+  ['route generates Pi extension with registered MNote tools', route.includes('ensure_session_tool_bridge_extension') && route.includes('pi.registerTool') && route.includes('mnote_current_page_read')],
+  ['route starts Pi with explicit extension bridge', route.includes('--extension') && route.includes('mnoteToolBridgeExtension')],
+  ['route starts Pi with MNote tool allowlist', route.includes('--tools') && route.includes('mnoteToolNames') && route.includes('pi_lab_extension_tool_names')],
+  ['route keeps Pi builtin tools disabled while loading extension', route.includes('--no-builtin-tools') && route.includes('disabledBuiltinTools')],
+  ['route applies TTL and rate limits', route.includes('PI_LAB_SESSION_TTL_MS') && route.includes('PI_LAB_RATE_LIMITS') && route.includes('check_rate_limit')],
+  ['route cleans expired session dirs and rate buckets', route.includes('fs::remove_dir_all') && route.includes('buckets.retain')],
+
+  // === mod.rs checks ===
+  ['mod.rs declares page_ai_pi module', routesMod.includes('mod page_ai_pi;')],
+  ['mod.rs mounts pi status route', routesMod.includes('/api/page-ai/pi/status')],
+  ['mod.rs mounts pi start route', routesMod.includes('/api/page-ai/pi/start')],
+  ['mod.rs mounts pi send route', routesMod.includes('/api/page-ai/pi/send')],
+  ['mod.rs mounts pi abort route', routesMod.includes('/api/page-ai/pi/abort')],
+  ['mod.rs mounts pi events route', routesMod.includes('/api/page-ai/pi/events')],
+  ['mod.rs mounts pi tool-call route', routesMod.includes('/api/page-ai/pi/tool-call')],
+  ['mod.rs mounts pi internal tool-call-bridge route', routesMod.includes('/api/page-ai/pi/tool-call-bridge')],
+  ['mod.rs mounts pi bootstrap route (legacy)', routesMod.includes('/api/page-ai/pi/bootstrap')],
+  ['mod.rs mounts pi tool_call route', routesMod.includes('/api/page-ai/pi/tool-call')],
+  ['mod.rs mounts pi lab runtime asset', routesMod.includes('sidebar-page-ai-pi-lab-runtime.js')],
+
+  // === web_shell.rs checks ===
+  ['web_shell.rs has pi lab runtime asset function', webShell.includes('sidebar_page_ai_pi_lab_runtime_asset')],
+  ['web_shell.rs includes pi lab runtime JS', webShell.includes('sidebar-page-ai-pi-lab-runtime.js')],
+
+
+
+  // === gateway.rs checks ===
+  ['gateway.rs loads Pi Lab runtime when config enabled', gateway.includes('createSidebarPageAiPiLabRuntime')],
+  ['gateway.rs does NOT stamp body hidden gate', !gateway.includes('data-page-ai-pi-lab-hidden')],
+  ['app.rs defaults Pi Lab config on', app.includes('enable_page_ai_pi_lab: env_bool("MNOTE_PAGE_AI_PI_LAB", true)')],
+
+  // === Key architectural constraints ===
+  ['no modification of sidebar-page-ai-runtime', !runtime.includes('sidebar-page-ai-runtime')],
+  ['no sidebar-page-ai-runtime default behavior change',
+    !runtime.includes('sidebarPageAiRuntime')],
+  ['no import of main page AI runtime', !runtime.includes('import.*sidebar-page-ai')],
+];
+
+const failed = checks.filter(([, ok]) => !ok);
+if (failed.length) {
+  console.error('❌ Pi Lab static smoke failed:');
+  for (const [name] of failed) console.error(`  - ${name}`);
+  process.exit(1);
+}
+
+console.log('✅ Pi Lab static smoke passed (' + checks.length + ' checks).');