@dimina-kit/devtools 0.3.1 → 0.3.2-dev.20260522085907

package/README.md

@@ -83,6 +83,7 @@ import { app, globalShortcut } from 'electron'
 import path from 'path'
 import { createMainWindow } from '@dimina-kit/devtools/create-window'
 import { createWorkbenchContext } from '@dimina-kit/devtools/context'
+import { registerAppIpc } from '@dimina-kit/devtools'
 import { registerSimulatorIpc } from '@dimina-kit/devtools/ipc-simulator'
 import { registerPanelsIpc } from '@dimina-kit/devtools/ipc-panels'
 import { registerToolbarIpc } from '@dimina-kit/devtools/ipc-toolbar'
@@ -95,7 +96,7 @@ import { rendererDir, defaultPreloadPath } from '@dimina-kit/devtools/paths'
 app.whenReady().then(() => {
   const mainWindow = createMainWindow({
     title: 'My DevTools',
-    indexHtml: path.join(rendererDir, 'index.html'),
+    indexHtml: path.join(rendererDir, 'entries/main/index.html'),
   })
 
   const ctx = createWorkbenchContext({
@@ -105,6 +106,9 @@ app.whenReady().then(() => {
     rendererDir,
   })
 
+  // registerAppIpc 必装：renderer 启动时调用 app:getPreloadPath / app:getBranding，
+  // 缺它会卡在加载阶段。
+  registerAppIpc(ctx)
   registerProjectsIpc(ctx)
   registerSessionIpc(ctx)
   registerSimulatorIpc(ctx)
@@ -112,6 +116,11 @@ app.whenReady().then(() => {
   registerToolbarIpc(ctx)
   registerPopoverIpc(ctx)
 
+  // Storage / 元素选区面板的后端 handler 由 setupSimulatorStorage 单独装。
+  // 该函数当前**未列入稳定公共 API**（在 `@dimina-kit/devtools` 之外）。
+  // 若需要这两个面板，建议改用上方的 `createWorkbenchApp({ onSetup })` 路线，
+  // 框架会自动注册；模块组装路线下你只能用不依赖它们的精简面板集。
+
   // 添加自定义 IPC — 通过 ctx.workspace 访问会话状态
   ipcMain.handle('my:action', () => {
     console.log('current project:', ctx.workspace.getProjectPath())
@@ -150,9 +159,6 @@ src/
       app.ts                             # createWorkbenchApp 工厂
       bootstrap.ts                       # suppressEpipe / setupCdpPort
       lifecycle.ts                       # Electron app 生命周期注册
-    windows/
-      main-window/                       # 主窗口创建 + 事件接线
-      settings-window/                   # 独立设置窗口
     ipc/                                 # 只做 handler 注册，不写业务
       index.ts                           # 聚合 register 函数导出
       simulator.ts                       # simulator attach/detach/resize
@@ -166,17 +172,33 @@ src/
       settings/                          # 用户级 workbench 设置读写 + 主题应用
       projects/                          # 项目列表 CRUD（持久化）
       layout/                            # 布局常量 + bounds 计算
+      views/                             # ViewManager（settings / popover overlay 等）
+      workspace/                         # 项目会话生命周期
+      notifications/                     # 主进程 → renderer 的事件通知
       mcp/                               # MCP server
       automation/                        # 自动化 WebSocket 服务
       simulator/                         # simulator dir / referer
+      simulator-storage/                 # CDP DOMStorage + 元素 inspect 桥接
+      update/                            # UpdateManager + GitHubReleaseChecker
       workbench-context.ts               # 共享状态类型 + 工厂 + 辅助函数
+      window-service.ts                  # main / settings 窗口聚合访问
+      module.ts                          # WorkbenchModule 协议
       default-adapter.ts                 # 默认 CompilationAdapter
     menu/                                # 应用菜单
-    utils/paths.ts                       # rendererDir / defaultPreloadPath
+    utils/
+      paths.ts                           # rendererDir / defaultPreloadPath / simulatorDir
+      disposable.ts                      # DisposableRegistry + AggregateError 聚合
+      ipc-registry.ts                    # ipcMain.handle 包装 + SenderPolicy 闸门
+      sender-policy.ts                   # sender webContents id 白名单
+      ipc-schema.ts                      # zod schema 校验工具
+    windows/
+      main-window/                       # 主窗口创建 + 事件接线
+      settings-window/                   # 独立设置窗口
+      navigation-hardening.ts            # will-navigate / setWindowOpenHandler 限流
 
   preload/                               # 按注入目标分
     windows/                             # contextBridge 类型 preload
-      main.ts                            # 主窗口 preload，可组合导出 install*Instrumentation
+      main.ts                            # workbench 三窗口 preload，仅暴露 window.devtools.ipc
       simulator.ts                       # simulator webview 的默认 preload
     shared/                              # preload 之间共享
       api-compat.ts                      # setupApiCompatHook
@@ -184,19 +206,23 @@ src/
       types.ts
     instrumentation/                     # 注入到小程序 runtime 的探针
       console.ts                         # 控制台拦截
-      storage.ts                         # localStorage 拦截
-      app-data.ts                        # Worker setData 拦截
-      wxml.ts                            # Vue 组件树提取
+      app-data.ts                        # Worker setData 拦截 → createAppDataSource
+      wxml.ts                            # Vue 组件树提取 → createWxmlSource
+      disposable.ts                      # instrumentation 共用的清理工具
+    miniapp-snapshot/                    # 面板数据统一快照框架（docs/miniapp-snapshot.md）
+      types.ts                           # MiniappSnapshotSource / SnapshotEnvelope
+      host.ts                            # createMiniappSnapshotHost → push/pull/__miniappSnapshot
     runtime/
-      bridge.ts                          # installSimulatorBridge
-      host.ts
+      bridge.ts                          # installSimulatorBridge → window.__simulatorData
+      custom-apis.ts                     # installCustomApisBridge → window.__diminaCustomApis
+      host.ts                            # sendToHost 推送封装
 
   renderer/
     entries/                             # 各窗口 HTML + React 挂载点
       main/ popover/ settings/ workbench-settings/
     modules/                             # 先按窗口分，再按区域
       main/
-        app/                             # 主窗口 App 根
+        main.tsx                         # 主窗口 React 根
         features/                        # 主窗口内的业务区域
           project-runtime/               # 项目视图 + 工具栏 + 右侧面板切换
           right-panel/                   # WXML / AppData / Storage 面板
@@ -248,6 +274,8 @@ src/
 | `onSetup`       | `(instance) => void`                        | —           | 窗口和 context 创建后的回调，用于注册自定义 IPC   |
 | `onBeforeClose` | `(instance) => void`                        | —           | 窗口关闭前的回调，session 关闭由框架自动处理      |
 | `window`        | `WorkbenchWindowConfig`                     | —           | 窗口尺寸覆盖                                      |
+| `updateChecker` | `UpdateChecker`                             | —           | 自定义更新检查器；提供后启用"检查更新"功能        |
+| `updateOptions` | `{ checkInterval?, initialDelay?, getCurrentVersion? }` | —  | 仅当 `updateChecker` 提供时生效，默认 1h / 5s     |
 
 ### 内置面板 ID
 
@@ -259,6 +287,126 @@ src/
 
 ---
 
+## Embedding & Extending the Project Panel
+
+宿主（如 qdmp）通过 `createWorkbenchApp({...})` 嵌入 devtools 时，可对项目面板做三个正交扩展：
+
+| 扩展点 | 用途 |
+| --- | --- |
+| `projectsProvider` | 接管项目列表存储 —— 替换默认 `<userData>/dimina-projects.json`，对接 qdmp 后台 / IDE workspace / 远端工程库 |
+| `projectTemplates` + `builtinTemplates` | 注入/覆盖/裁剪"新建项目"模板列表（同 id 覆盖内置；`builtinTemplates` 控制内置策略） |
+| `customCreateProjectDialog` | 用宿主自家页面替换内置"新建项目"对话框（main 进程 hook，可 `new BrowserWindow` 加载任意 URL，通过 IPC/postMessage 回传结果） |
+
+### 何时需要哪个扩展点
+
+| 场景 | 需要的扩展点 |
+| --- | --- |
+| 项目列表来自 qdmp 后台 / 团队工程库 | `projectsProvider` |
+| 仅替换可选模板（e.g. 只提供 taro / qdmp 自家脚手架） | `projectTemplates` + `builtinTemplates` |
+| 创建项目流程要走宿主自己的 wizard / 登录态 | `customCreateProjectDialog` |
+
+### 最小示例
+
+```typescript
+import { createWorkbenchApp } from '@dimina-kit/devtools/app'
+import type { ProjectsProvider, ProjectTemplate } from '@dimina-kit/devtools/projects-provider'
+import { BrowserWindow } from 'electron'
+
+const provider: ProjectsProvider = {
+  async listProjects() {
+    return await qdmp.api.listProjects()
+  },
+  async validateProjectDir(dirPath) {
+    return (await qdmp.api.isMiniApp(dirPath)) ? null : '不是合法的小程序工程'
+  },
+  async addProject(dirPath) {
+    return await qdmp.api.addProject(dirPath)
+  },
+  async removeProject(dirPath) {
+    await qdmp.api.removeProject(dirPath)
+  },
+  async updateLastOpened(dirPath) {
+    await qdmp.api.touchLastOpened(dirPath)
+  },
+  async getCompileConfig(dirPath) {
+    return await qdmp.api.getCompileConfig(dirPath)
+  },
+  async saveCompileConfig(dirPath, cfg) {
+    await qdmp.api.saveCompileConfig(dirPath, cfg)
+  },
+  // 缩略图走云端存储——dataUrl 形如 'data:image/png;base64,...'
+  async saveThumbnail(dirPath, imageDataUrl) {
+    await qdmp.api.uploadThumbnail(dirPath, imageDataUrl)
+  },
+  async getThumbnail(dirPath) {
+    return await qdmp.api.fetchThumbnail(dirPath)
+  },
+}
+
+const qdmpBlank: ProjectTemplate = {
+  id: 'blank', // 同 id 覆盖内置 blank
+  name: 'qdmp 空白工程',
+  description: '由 qdmp 维护的官方空白模板',
+  source: { type: 'directory', path: '/abs/path/to/template' },
+}
+
+createWorkbenchApp({
+  projectsProvider: provider,
+  projectTemplates: [qdmpBlank],
+  builtinTemplates: ['taro-todo'], // 只保留 taro-todo，干掉默认 blank
+  customCreateProjectDialog: async ({ parentWindow }) => {
+    const win = new BrowserWindow({ parent: parentWindow, modal: true, width: 720, height: 520 })
+    await win.loadURL('https://qdmp.example.com/devtools/new-project')
+    return await new Promise((resolve) => {
+      win.webContents.ipc.once('qdmp:create-project:done', (_e, payload) => {
+        win.close()
+        // payload 三选一（CustomCreateProjectDialogResult）：
+        //   null                  → 用户取消
+        //   CreateProjectInput    → 让 devtools 在本地物化模板并注册到 provider
+        //   { ready: Project }    → 宿主后端已经创建好，devtools 直接刷新列表
+        resolve(payload ?? null)
+      })
+      win.on('closed', () => resolve(null))
+    })
+  },
+}).start()
+```
+
+### `customCreateProjectDialog` 返回值
+
+`hook` 返回 `CustomCreateProjectDialogResult`，三种情形分别对应不同后续动作：
+
+| 返回 | 行为 |
+| --- | --- |
+| `null` | 用户取消，无副作用 |
+| `CreateProjectInput`（`{ name, path, templateId?, extra? }`） | devtools 在本地拷贝/生成模板 → 改写 `project.config.json` → `provider.addProject(path)`；适合"只想换 UI 但物化由 devtools 兜底" |
+| `{ ready: Project }` | devtools 跳过物化，只刷新列表并打开该项目；适合宿主后端已经远端创建好项目，本地完全无需落盘 |
+
+物化失败（路径已存在/模板缺失/`provider.addProject` reject）会经 native dialog 弹出错误，再 reject 给渲染层；宿主端无需自己 toast。
+
+### 内置模板
+
+devtools 自带两个 `source`-style 模板，位于 `packages/devtools/templates/`：
+
+- `blank` — 最小空白小程序骨架（pages/index + app.js/json/wxss + project.config.json，约 8 个文件）
+- `taro-todo` — 复制自 `dimina/fe/example/taro-todo`，作为 Taro 编译产物的端到端演示工程
+
+`builtinTemplates: 'none'` 排除全部内置；`builtinTemplates: ['taro-todo']` 仅保留指定 id；`projectTemplates` 同 id 注入会覆盖（例如上文 `qdmpBlank` 覆盖了内置 `blank`）。
+
+### Provider 部分实现 / fallback 行为
+
+`ProjectsProvider` 的多数方法是可选的；当宿主只实现 `listProjects` / `addProject` / `removeProject` 时：
+
+- `validateProjectDir` 缺省 → 返回 `null`（不校验）
+- `updateLastOpened` 缺省 → 静默 no-op，"最近"排序退化为 `listProjects` 返回顺序
+- `getCompileConfig` 缺省 → 返回 `DEFAULT_COMPILE_CONFIG`（`{ startPage: '', scene: 1001, queryParams: [] }`）
+- `saveCompileConfig` 缺省 → 静默 no-op，编译配置面板的编辑不会持久化
+- `saveThumbnail` / `getThumbnail` 缺省 → save 静默 no-op，get 返回 `null`；项目卡缩略图不显示。实现这两个方法可让远端项目用云端缩略图（详见示例）
+
+> 完整契约、参数语义和默认值见 `src/main/services/projects/types.ts` 的 JSDoc，那是 source of truth。
+
+---
+
 ## CompilationAdapter
 
 实现此接口接入自定义构建流程：
@@ -285,37 +433,63 @@ const myAdapter: CompilationAdapter = {
 
 ## Preload Instrumentation
 
-模拟器 webview 注入 preload 脚本在全局安装 instrumentation。内置 preload（`preload/windows/simulator.ts`）组装了以下模块：
+模拟器 webview 注入 preload 脚本，在 webview 全局上安装两类东西：**桥接**（把数据通道暴露到 webview）+ **instrumentation**（监听运行时事件并写入桥接）。内置 preload 见 `src/preload/windows/simulator.ts`。
+
+### 必装：桥接
+
+| 函数 | 作用 | 不装会怎样 |
+| --- | --- | --- |
+| `installSimulatorBridge()` | 暴露 `window.__simulatorData`，承载 `highlightElement` / `unhighlightElement` / `getAppdata` / `getWxml` / `getStorageSnapshot` 等只读 API（供主进程 `executeJavaScript` 拉取） | 元素选区 overlay 不显示；automation `Page.getData` 返回空对象；MCP `simulator_get_overview` 在 hints 中追加 `simulator bridge not ready (window.__simulatorData missing)`。注：Storage 面板走主进程 CDP，不受影响；Console/AppData/WXML 推送走 `sendToHost`，也不受影响 |
+| `installCustomApisBridge()` | 暴露 `window.__diminaCustomApis`，承载 `list` / `invoke`，让模拟器侧把主进程注册的 API 代理回小程序 runtime | `registerSimulatorApi` 注册的业务 API 在小程序里调用全部 no-op（参见下方 "Simulator 自定义 API"） |
+| `setupApiCompatHook()` | 兼容上游 API 名称变更 | 部分 API 调用兼容性问题 |
+
+下游写自定义 preload 时，这三项原则上都要装。若不需要 `registerSimulatorApi`，`installCustomApisBridge` 可省略。
 
-| Instrumentation                           | 捕获内容                                        |
-| ----------------------------------------- | ----------------------------------------------- |
-| Console (`installConsoleInstrumentation`) | `console.*`、`window.onerror`、未捕获 rejection |
-| Storage (`installStorageInstrumentation`) | `localStorage.setItem/removeItem`、全量快照     |
-| AppData (`installAppDataInstrumentation`) | Worker `type='u'` 消息、setData 调用            |
-| WXML (`installWxmlInstrumentation`)       | Vue 组件树提取、MutationObserver 自动更新       |
+### 按需：instrumentation
 
-所有 install\* 函数从 `@dimina-kit/devtools/preload` 统一导出，调用后通过 `installSimulatorBridge` 暴露的内部桥接通道把数据推到宿主。面板打开时调用 `panel:eval` 通过 `executeJavaScript` 拉取当前状态。
+Console 是独立 instrumentation；AppData 与 WXML 已迁移到 **miniappSnapshot** 框架——各自实现一个 `MiniappSnapshotSource`，由 `MiniappSnapshotHost` 统一负责推送 / 拉取 / reload 重同步（详见 `docs/miniapp-snapshot.md`）。
+
+| 探针 | 捕获内容 | 数据通道 |
+| --- | --- | --- |
+| `installConsoleInstrumentation()` | `console.*`、`window.onerror`、未捕获 rejection | `sendToHost` |
+| `createAppDataSource()` | Worker `ub` 消息、setData / page init | miniappSnapshot 框架（`miniapp-snapshot:push`） |
+| `createWxmlSource()` | Vue 组件树提取、MutationObserver 自动更新 | miniappSnapshot 框架（`miniapp-snapshot:push`） |
+
+> Storage 面板的数据由主进程通过 CDP `DOMStorage` 域抓取（`src/main/services/simulator-storage`），**不需要 preload 侧 instrumentation**。
+
+各面板的数据流详见下方 "数据流" 章节。
 
 ### 自定义 Preload
 
-按需组合或追加自定义逻辑（`src/preload/windows/simulator.ts` 作为参考）：
+参考 `src/preload/windows/simulator.ts`：
 
 ```typescript
 // my-preload.ts
 import {
   installSimulatorBridge,
+  installCustomApisBridge,
   installConsoleInstrumentation,
-  installStorageInstrumentation,
+  createMiniappSnapshotHost,
+  createAppDataSource,
+  createWxmlSource,
   setupApiCompatHook,
 } from '@dimina-kit/devtools/preload'
-// 不需要 WXML/AppData，不导入
 
+// 1. 兼容 hook + 桥接（必装，且应在 instrumentation 之前）
 setupApiCompatHook()
 installSimulatorBridge()
+installCustomApisBridge()   // 若用到 registerSimulatorApi，必装
+
+// 2. Console instrumentation（按需）
 installConsoleInstrumentation()
-installStorageInstrumentation()
 
-// 自定义 hook
+// 3. miniappSnapshot 框架：注册面板数据源后 install()
+const snapshotHost = createMiniappSnapshotHost()
+snapshotHost.register(createAppDataSource())
+snapshotHost.register(createWxmlSource())
+snapshotHost.install()
+
+// 4. 自定义 hook
 window.addEventListener('error', (e) => {
   console.error('[my-preload]', e.message)
 })
@@ -329,49 +503,94 @@ launch({ preloadPath: '/absolute/path/to/my-preload.js' })
 
 ---
 
+## Simulator 自定义 API
+
+下游可以通过 `registerSimulatorApi` 把业务 API 注入到模拟器内运行的小程序。Handler 在 Electron **主进程**执行，能用任何 Node 能力（fs、net、原生模块、持久状态）；模拟器侧拿到 `wx.<name>(params)` 调用后通过 IPC 转发到主进程，await 返回结果，handler 抛错则原型回传给小程序。
+
+> ⚠️ 使用本功能要求模拟器 preload 调用 `installCustomApisBridge()`（详见上方 "Preload Instrumentation"）。内置 preload 已包含此调用；若你用了自定义 preload 又忘记调用，注册的 API 在小程序运行时**没有任何反应**，且不会报错。
+
+### 命名约定
+
+`name` 是 dimina service 层 `invokeAPI(name, opts)` 用的**裸名**，不带 `wx.` 前缀。注册之后小程序里通过 `wx.<name>(...)`（以及你在 `apiNamespaces` 配的其它命名空间）调用都会命中：
+
+| 小程序里写 | `registerSimulatorApi` 的 name |
+| --- | --- |
+| `wx.login(...)` | `'login'` |
+| `wx.request(...)` | `'request'` |
+| `wx.getStorage(...)` 覆盖内置 | `'getStorage'`（小心：这会**屏蔽** dimina 容器的实现） |
+
+```typescript
+import { registerSimulatorApi } from '@dimina-kit/devtools/simulator-apis'
+
+// 提供 wx.login 的实现（dimina 容器默认未实现，注册后才能用）
+const dispose = registerSimulatorApi('login', async ({ success }) => {
+  // 主进程上下文：可调用内部 HTTP、读取凭证文件、访问原生模块
+  const code = await callInternalAuth()
+  return { code }
+})
+
+// 不再需要时取消注册（不传也行，进程退出会一起清理）
+dispose()
+```
+
+### 行为约定
+
+- **命中顺序**：小程序运行时按 `apiRegistry[name] → MiniApp 实例方法 → 扩展模块兜底` 查找，所以 `registerSimulatorApi` 注册的 name **优先于内置实现**——既能给"未实现"的 wx.* 补功能（如 `wx.login`），也能覆盖默认的 wx.* 行为（如 `wx.request`，dimina-kit 本身就在用这条路把 `request` 接到主进程 fetch）。
+- 同名重复注册：后注册的覆盖前者，静默替换。
+- `dispose()` 只会移除自己创建的那次注册——如果之后被别人覆盖了，旧的 disposer 是 no-op。
+- 调用未注册且容器内也没有的 name：小程序侧拿到 reject，错误信息里带 name。
+- Handler 可同步或异步返回；**返回值需可 JSON 序列化**（IPC 限制）。函数、Symbol、Map/Set、循环引用都会丢失。
+
+---
+
 ## 模块导出一览
 
+### Stable public exports
+
+`@dimina-kit/devtools` 的稳定入口，签名遵循 semver；新版本不会做破坏性改动（除非 major bump）。
+
 ```
 @dimina-kit/devtools                        launch, createWorkbenchApp, buildDefaultMenu,
                                        openSettingsWindow, suppressEpipe, setupCdpPort,
-                                       createWorkbenchContext, createMainWindow, ...
-                                       （api.ts 聚合了下方全部入口）
+                                       createWorkbenchContext, createMainWindow,
+                                       createViewManager, register*Ipc,
+                                       registerSimulatorApi,
+                                       setHeaderHeight, UpdateManager,
+                                       createGitHubReleaseChecker, ...
+                                       （api.ts 聚合了所有公共 API；优先从根入口导入）
 @dimina-kit/devtools/launch                 launch(config?), buildDefaultMenu, openSettingsWindow
 @dimina-kit/devtools/app                    createWorkbenchApp(config?)
 @dimina-kit/devtools/types                  TypeScript 类型定义
+@dimina-kit/devtools/bootstrap              suppressEpipe(), setupCdpPort()
+@dimina-kit/devtools/paths                  rendererDir, defaultPreloadPath, simulatorDir,
+                                       getRendererDir, getPreloadDir, getRendererHtml
+@dimina-kit/devtools/simulator-apis         registerSimulatorApi(name, handler) →
+                                       注入由主进程托管的小程序 API（详见上方"Simulator 自定义 API"）
+@dimina-kit/devtools/preload                installSimulatorBridge,
+                                       installCustomApisBridge,
+                                       installConsoleInstrumentation,
+                                       createMiniappSnapshotHost,
+                                       createAppDataSource, createWxmlSource,
+                                       setupApiCompatHook
+                                       （storage 面板数据由主进程 CDP 抓取，无 preload 侧 hook）
+```
+
+### Experimental exports (v0.x — signatures may change in minor versions)
+
+下列子路径主要用于"模块组装"等深度定制场景。在 0.x 阶段，函数签名和模块边界可能在 minor 版本之间调整；如果你不需要逐模块组装，请优先使用上方的 stable 入口或根 barrel。
+
+```
 @dimina-kit/devtools/context                createWorkbenchContext(opts),
                                        hasBuiltinPanel(ctx, panelId), getDefaultTab(ctx)
 @dimina-kit/devtools/create-window          createMainWindow(opts)
-@dimina-kit/devtools/view-manager           createViewManager(ctx) → ViewManager
-                                       (attachSimulator, detachSimulator, showSimulator,
-                                        hideSimulator, showSettings, hideSettings,
-                                        showPopover, hidePopover, resize,
-                                        setVisible, repositionAll, disposeAll)
-@dimina-kit/devtools/layout                 computeRightPanelBounds, computeSimulatorBounds,
-                                       computeSettingsBounds, computePopoverBounds,
-                                       setHeaderHeight, getRightX,
-                                       HEADER_H, SPLITTER_W, SETTINGS_W
-@dimina-kit/devtools/projects               listProjects, addProject, removeProject,
-                                       getCompileConfig, saveCompileConfig,
-                                       updateLastOpened
-@dimina-kit/devtools/paths                  rendererDir, defaultPreloadPath,
-                                       getRendererDir, getPreloadDir, getRendererHtml
 @dimina-kit/devtools/ipc-simulator          registerSimulatorIpc(ctx)
 @dimina-kit/devtools/ipc-panels             registerPanelsIpc(ctx)
 @dimina-kit/devtools/ipc-toolbar            registerToolbarIpc(ctx)
 @dimina-kit/devtools/ipc-popover            registerPopoverIpc(ctx)
 @dimina-kit/devtools/ipc-settings           registerSettingsIpc(ctx)
 @dimina-kit/devtools/ipc-projects           registerProjectsIpc(ctx)
-@dimina-kit/devtools/ipc-session            registerSessionIpc(ctx), sendStatus(ctx, status, msg)
-@dimina-kit/devtools/bootstrap              suppressEpipe(), setupCdpPort()
+@dimina-kit/devtools/ipc-session            registerSessionIpc(ctx), sessionModule
 @dimina-kit/devtools/workbench-settings     loadWorkbenchSettings(), saveWorkbenchSettings(), applyTheme()
-@dimina-kit/devtools/preload                installConsoleInstrumentation,
-                                       installStorageInstrumentation,
-                                       installAppDataInstrumentation, sendAllAppData,
-                                       installWxmlInstrumentation, sendWxmlTree,
-                                       setupWxmlObserver, installSimulatorBridge,
-                                       setupApiCompatHook
-@dimina-kit/devtools/simulator-dir          simulatorDir
 ```
 
 ---
@@ -382,7 +601,6 @@ launch({ preloadPath: '/absolute/path/to/my-preload.js' })
 
 ```typescript
 interface WorkbenchContext {
-  mainWindow: BrowserWindow
   adapter: CompilationAdapter
   preloadPath: string
   rendererDir: string
@@ -391,24 +609,24 @@ interface WorkbenchContext {
   appName: string
   toolbarActions?: () => Promise<ToolbarAction[]> | ToolbarAction[]
   brandingProvider?: () => Promise<{ appName: string }> | { appName: string }
-  workbenchSettingsWindow: BrowserWindow | null
 
   // ── Services（运行时状态封装在内部，通过方法访问）──
+  windows: WindowService // ctx.windows.mainWindow, ctx.windows.settingsWindow, ...
   views: ViewManager // ctx.views.repositionAll(), ctx.views.getSimulatorWebContentsId(), ...
   notify: RendererNotifier // ctx.notify.projectStatus(), ctx.notify.windowNavigateBack(), ...
   workspace: WorkspaceService // ctx.workspace.getProjectPath(), ctx.workspace.hasActiveSession(), ...
+
+  // ── Internal lifecycle / security (host 不直接消费) ──
+  registry: DisposableRegistry // 框架在创建时统一聚合 dispose
+  senderPolicy: SenderPolicy   // IpcRegistry 自动校验 sender 白名单
 }
 ```
 
-会话和视图状态不再作为 ctx 的直接字段暴露，而是封装在对应 service 的私有闭包中：
+会话和视图状态封装在对应 service 的私有闭包中，通过方法访问，例如：
 
-| 旧写法                       | 新写法                                                            |
-| ---------------------------- | ----------------------------------------------------------------- |
-| `ctx.currentProjectPath`     | `ctx.workspace.getProjectPath()`                                  |
-| `ctx.currentSession`         | `ctx.workspace.getSession()` / `ctx.workspace.hasActiveSession()` |
-| `ctx.simulatorWebContentsId` | `ctx.views.getSimulatorWebContentsId()`                           |
-| `ctx.devToolsViewAdded`      | `ctx.views.isSimulatorAdded()`                                    |
-| `ctx.lastSimWidth`           | `ctx.views.getLastSimWidth()`                                     |
+- `ctx.workspace.getProjectPath()` / `ctx.workspace.getSession()` / `ctx.workspace.hasActiveSession()`
+- `ctx.views.getSimulatorWebContentsId()` / `ctx.views.isSimulatorAdded()` / `ctx.views.getLastSimWidth()`
+- `ctx.windows.mainWindow` / `ctx.windows.settingsWindow`
 
 ---
 
@@ -438,76 +656,22 @@ flowchart TB
 
 ### 数据流
 
-内置面板采用**拉取式**数据流，避免长期订阅：
+按面板 / 场景拆分：
 
-```mermaid
-sequenceDiagram
-    autonumber
-    actor User as 用户
-    participant UI as 面板 UI (React)
-    participant R as renderer
-    participant M as main<br/>ipc/panels.ts
-    participant P as preload<br/>instrumentation
-
-    User->>UI: 打开面板 / 刷新
-    UI->>R: invokeMain('panel:eval', expression)
-    R->>M: IPC: panel:eval
-    M->>P: webContents.executeJavaScript(expression)
-    Note over P: window 上已挂好取值函数
-    P-->>M: 结构化数据
-    M-->>R: 返回结果
-    R-->>UI: 渲染
-```
+| 面板 / 场景 | 模式 | 路径 |
+| --- | --- | --- |
+| Console | 推送 | `installConsoleInstrumentation` 经 `runtime/host.ts:sendToHost` → webview `ipcRenderer.sendToHost` 推到宿主 → renderer 监听 `ipc-message` |
+| AppData / WXML 树 | 推送 + 拉取 | **miniappSnapshot 框架**：preload `MiniappSnapshotHost` 经 `miniapp-snapshot:push` 推全量快照，renderer `useMiniappSnapshot` 整份投影；面板「刷新」走 `miniapp-snapshot:pull`（详见 `docs/miniapp-snapshot.md`） |
+| Storage | 拉取 + 推送 | renderer `ipcInvoke(SimulatorStorageChannel.GetSnapshot)` → 主进程 CDP `DOMStorage` 域；变更事件由主进程通过 `SimulatorStorageChannel.Event` 推回 renderer |
+| 元素选区 / `Page.getData` / MCP overview | 拉取 | 主进程 `webContents.executeJavaScript(...)` 或 `Runtime.evaluate(...)` 读 `window.__simulatorData.*`（由 `installSimulatorBridge` 暴露）；面板快照亦可经 `window.__miniappSnapshot.get(id)` 同步读取（由 `MiniappSnapshotHost` 暴露） |
 
-Console 输出等推送场景仍由 preload 通过 `installSimulatorBridge()` 经由 webview ipcRenderer 送至宿主，再由 renderer 分发到相应面板。
+> `src/main/ipc/panels.ts` 暴露 `panel:eval` handler 供外部 host 自定义面板复用，内置 renderer 不消费它。
 
 ---
 
 ## IPC 通信总览
 
-| 频道                              | 方向  | 说明                                           |
-| --------------------------------- | ----- | ---------------------------------------------- |
-| `projects:list`                   | R→M   | 获取项目列表                                   |
-| `projects:add`                    | R→M   | 添加项目                                       |
-| `projects:remove`                 | R→M   | 删除项目                                       |
-| `dialog:openDirectory`            | R→M   | 打开目录选择对话框                             |
-| `project:open`                    | R→M   | 编译并启动项目                                 |
-| `project:close`                   | R→M   | 停止编译，清理 View                            |
-| `project:status`                  | M→R   | 编译状态推送                                   |
-| `project:getPages`                | R→M   | 读取 app.json pages                            |
-| `project:getCompileConfig`        | R→M   | 读取编译配置                                   |
-| `project:saveCompileConfig`       | R→M   | 保存编译配置                                   |
-| `app:getPreloadPath`              | R→M   | 获取 preload 脚本路径                          |
-| `app:getBranding`                 | R→M   | 读取品牌信息（`brandingProvider`）             |
-| `toolbar:getActions`              | R→M   | 读取自定义工具栏按钮                           |
-| `workbench:getPanelConfig`        | R→M   | 获取 panels 配置                               |
-| `workbench:getApiNamespaces`      | R→M   | 获取自定义 API namespaces                      |
-| `simulator:attach`                | R→M   | 绑定 simulator webContents，创建 simulatorView |
-| `simulator:detach`                | R→M   | 销毁所有 View                                  |
-| `simulator:resize`                | R→M   | 更新 View 位置（分割线拖动）                   |
-| `simulator:setVisible`            | R→M   | 显示/隐藏 simulator 面板                       |
-| `workbench:reset`                 | R→M   | 通知主窗口重置面板状态                         |
-| `panel:list`                      | R→M   | 获取启用的内置面板列表                         |
-| `panel:eval`                      | R→M   | 在 simulator webContents 执行 JS 并返回结果    |
-| `panel:select`                    | R→M   | 切换到指定内置面板                             |
-| `panel:selectSimulator`           | R→M   | 切换到 simulator tab                           |
-| `popover:show`                    | R→M   | 创建弹窗                                       |
-| `popover:hide`                    | R→M   | 销毁弹窗                                       |
-| `popover:init`                    | M→P   | 初始化弹窗数据                                 |
-| `popover:relaunch`                | P→M→R | 重新编译                                       |
-| `popover:closed`                  | M→R   | 弹窗关闭通知                                   |
-| `settings:setVisible`             | R→M   | 显示/隐藏设置视图                              |
-| `settings:init`                   | M→P   | 初始化设置面板                                 |
-| `settings:configChanged`          | P→M→R | 编译配置变更通知                               |
-| `settings:projectSettingsChanged` | P→M   | 项目级设置（如 sourcemap）落盘                 |
-| `settings:closed`                 | M→R   | 设置面板关闭通知                               |
-| `workbenchSettings:get`           | R→M   | 读取用户级 workbench 设置                      |
-| `workbenchSettings:save`          | R→M   | 保存 workbench 设置并应用主题                  |
-| `workbenchSettings:setTheme`      | R→M   | 仅切换主题                                     |
-| `workbenchSettings:getCdpStatus`  | R→M   | 读取当前 CDP 端口状态                          |
-| `workbenchSettings:setVisible`    | R→M   | 打开/关闭独立设置窗口                          |
-
-R=渲染进程，M=主进程，P=子 WebContentsView
+IPC 频道名常量集中定义在 `src/shared/ipc-channels.ts`，按域分组（`SimulatorChannel` / `ProjectChannel` / `PanelChannel` / `WorkbenchSettingsChannel` 等）。该文件是频道清单的唯一真相源；此处不再维护手抄表，以免与代码漂移。
 
 ---
 
@@ -545,18 +709,18 @@ pnpm test               # 运行测试
 
 ## 安全说明
 
-- 本工具仅用于本地开发调试，不应部署到生产环境
-- 为方便开发调试，BrowserWindow 启用了 `nodeIntegration` 并禁用了 `contextIsolation`，这在生产环境中存在安全风险
-- 仅在受信任的本地开发环境中使用本工具
-- 不要在 devtools 窗口中加载不受信任的远程内容
-- 如需在非本地环境使用，请自行评估并加固安全配置
+本工具仅用于本地开发调试。当前的安全配置：
 
-### MCP Server 风险
+- **Workbench 窗口**（main / settings / popover overlay）均启用 `contextIsolation` 并禁用 `nodeIntegration`；renderer 通过 main preload 经 `contextBridge` 拿到 `window.devtools.ipc`，每个 IPC handler 经 sender whitelist 校验调用方
+- **Simulator 加载的小程序代码** 运行在独立 `<webview>` 中（`partition='persist:simulator'`、`nodeIntegration=false`），preload 由 `session.registerPreloadScript` 在 session 层固定，渲染进程无法替换
+- **renderer 入口** 启用了保守 CSP；`will-navigate` / `setWindowOpenHandler` 屏蔽外部跳转
 
-内置的 MCP server 默认关闭，由 `startMcpServer` 入口显式启动，或通过 workbench 设置中的 `mcp.enabled` 开启。开启后会在本机监听 SSE 端点，向任何可以连接到该端点的 MCP 客户端暴露一组工具，能力包括：在页面上下文执行任意 JS（`evaluate`）、读取 DOM 结构、截屏、拉取网络日志、触发导航等。
+仍然不要在 devtools 窗口中加载不受信任的远程内容；本工具不打算在非本地环境部署。
+
+### MCP Server 风险
 
-由于 workbench 主窗口出于调试需要启用了 `nodeIntegration` 并关闭了 `contextIsolation`，通过 MCP 客户端执行的 `evaluate` 实际拥有 Node API 访问权限。换言之，开启 MCP 等同于允许已连接的本机 MCP 客户端在 DevTools 进程中执行 Node 代码，读写本机文件和启动子进程均在其能力范围内。
+内置的 MCP server 默认关闭，由 `startMcpServer` 入口显式启动，或通过 workbench 设置中的 `mcp.enabled` 开启。开启后会在本机监听 SSE 端点，向任何可以连接到该端点的 MCP 客户端暴露一组工具，能力包括：读取 DOM 结构、截屏、拉取网络日志、触发导航等。
 
-因此仅在连接到可信的本机 MCP 客户端或被信任的 AI 工具时启用该功能；不要在公共 WiFi、共享机器或存在远程 SSH 端口转发的场景下开启，以免监听端口被非预期的客户端访问。
+`workbench_evaluate` 已从 MCP 工具集中移除，workbench 只暴露只读诊断工具（截屏、console 日志、DOM、网络日志等）。`simulator_evaluate` 仍然保留，但 simulator 使用 `<webview>`、`nodeIntegration=false`，其 `evaluate` 仅在页面 JS 上下文执行，不具备 Node API 访问能力。
 
-作为收窄 RCE 面的默认策略，`workbench_evaluate` 已从 MCP 工具集中移除，workbench 只暴露只读诊断工具（截屏、console 日志、DOM、网络日志等）。`simulator_evaluate` 仍然保留，因为 simulator 使用 `<webview>`，默认 `nodeIntegration=false`，其 `evaluate` 仅在页面 JS 上下文执行，不具备 Node API 访问能力。
+仅在连接到可信的本机 MCP 客户端或被信任的 AI 工具时启用该功能；不要在公共 WiFi、共享机器或存在远程 SSH 端口转发的场景下开启，以免监听端口被非预期的客户端访问。

package/dist/main/api.d.ts

@@ -7,6 +7,10 @@ export type { WorkbenchContext, CreateContextOptions } from './services/workbenc
 export { createMainWindow } from './windows/main-window/index.js';
 export { createViewManager } from './services/views/view-manager.js';
 export type { ViewManager } from './services/views/view-manager.js';
+export type { WorkspaceService } from './services/workspace/workspace-service.js';
+export type { Project, ProjectPages, ProjectSettings } from './services/projects/project-repository.js';
+export { registerSimulatorApi } from './simulator-apis.js';
+export type { SimulatorApiHandler } from './simulator-apis.js';
 export { registerAppIpc } from './ipc/app.js';
 export { registerSimulatorIpc } from './ipc/simulator.js';
 export { registerPanelsIpc } from './ipc/panels.js';
@@ -15,8 +19,8 @@ export { registerSettingsIpc } from './ipc/settings.js';
 export { registerProjectsIpc } from './ipc/projects.js';
 export { registerSessionIpc } from './ipc/session.js';
 export { registerToolbarIpc } from './ipc/toolbar.js';
-export { rendererDir, defaultPreloadPath, getRendererDir, getPreloadDir, getRendererHtml } from './utils/paths.js';
-export { simulatorDir } from './services/simulator/dir.js';
+export { rendererDir, defaultPreloadPath, simulatorDir, getRendererDir, getPreloadDir, getRendererHtml, } from './utils/paths.js';
+export { setHeaderHeight } from './services/layout/index.js';
 export { UpdateManager, createGitHubReleaseChecker } from './services/update/index.js';
 export type { UpdateManagerOptions, GitHubReleaseCheckerOptions, PickAssetContext, VersionScheme, } from './services/update/index.js';
 export type { WorkbenchConfig, WorkbenchAppConfig, CompilationAdapter, ProjectSession, ToolbarAction, BuiltinPanelId, BuiltinModuleId, UpdateChecker, UpdateInfo, } from '../shared/types.js';