@dimina-kit/devtools 0.4.0-dev.20260828161241 → 0.4.0-dev.20260907055341

package/README.md

@@ -1,766 +1,89 @@
-# Dimina DevTools
+# @dimina-kit/devtools
 
-基于 Electron 的小程序开发者工具。提供模拟器、Chrome DevTools 面板、WXML/AppData/Storage/编译 面板、编译配置等功能。
+Dimina DevTools 是调试 [Dimina](https://github.com/didi/dimina) 小程序的桌面工具。它把小程序模拟器、Chrome DevTools、WXML、AppData、Storage、编译日志和 VS Code 工作台放在同一个 Electron 应用中。
 
-下游 host 通过 `launch(config)` 集成并定制 devtools（零配置直接 `launch()`，配置驱动 `launch({...})`；见下方「两种用法」）。两种用法都经领域中立的 [`@dimina-kit/electron-deck`](../electron-deck) 框架编排——框架接管 Electron 进程生命周期（whenReady / will-quit）、wire/trust 原语，devtools 作为 `RuntimeBackend` 注入完整运行时（见 [`electron-deck 架构`](../electron-deck/docs/architecture.md)）。
+![Dimina DevTools](../../docs/devtools.png)
 
----
+## 获取和运行
 
-## 两种用法
+直接使用桌面应用，可以从项目的 [Releases](https://github.com/EchoTechFE/dimina-kit/releases) 下载已发布的桌面构建。要从源码运行，请先按[仓库根 README](../../README.md#快速开始)准备仓库，然后执行：
 
-单一入口 `launch(config?)`——不传配置即零配置直接运行，传 `WorkbenchAppConfig` 即配置驱动定制。
+```bash
+pnpm --filter @dimina-kit/devtools build
+pnpm --filter @dimina-kit/devtools start
+```
 
-| 用法         | 调用                   | 控制力                | 适合场景       |
-| ------------ | ---------------------- | --------------------- | -------------- |
-| **零配置**   | `launch()`             | 无                    | 直接运行       |
-| **配置驱动** | `launch({...})`        | 配置 Provider + 扩展点 | 品牌化、深度定制 |
+## 作为 Electron 库使用
 
-### 零配置
+`@dimina-kit/devtools` 也可以作为 Electron 应用的基础包，用于替换品牌、编译后端、项目来源，或注册宿主自己的小程序 API 和模拟器界面。
 
-```typescript
-import { launch } from '@dimina-kit/devtools/launch'
-launch()
+```bash
+pnpm add @dimina-kit/devtools electron@^43.2.0
 ```
 
-### 配置驱动
+当前包声明的 Electron peer 版本为 `^43.2.0`。
 
-扩展点分两类：**配置 Provider**（构造期、一对一，替换某个内置能力）走 `launch` 配置字段；**Contribution**（`onSetup` 期、一对多，添加多个同类条目）走 `onSetup(instance)` 上的 typed 方法。所有 Contribution 都 per-context，随 context 自动销毁。
+最小入口是 `launch(config?)`：
 
-```typescript
-import { suppressEpipe } from '@dimina-kit/devtools/bootstrap'
+```ts
 import { launch } from '@dimina-kit/devtools'
-import { rendererDir } from '@dimina-kit/devtools/paths'
-import { Menu } from 'electron'
 
-suppressEpipe()
-
-launch({
-  // ── 配置 Provider（构造期，一对一）──
-  appName: '我的开发工具',
-  adapter: myAdapter,
-  preloadPath: '/path/to/my-preload.js',
-  rendererDir,
-  apiNamespaces: ['my'],
-  brandingProvider: () => ({ appName: '我的开发工具' }),
-  icon: '/path/to/icon.png',
-  menuBuilder: (mainWindow, menuCtx) => {
-    // menuCtx 是 MenuContext（只读 menu 相关状态）
-    Menu.setApplicationMenu(/* ... */)
-  },
-
-  // ── Contribution（onSetup 期，一对多）──
-  onSetup: (instance) => {
-    // simulator 自定义 API：per-context
-    instance.registerSimulatorApi('login', (params) => myLogin(params))
-
-    // simulator 下游 UI：框架管理 DeviceShell 挂载点与生命周期
-    const nativeUi = instance.registerSimulatorUiExtension({
-      id: 'my.native-ui',
-      rendererScriptPath: '/absolute/path/to/native-ui.js',
-    })
-    instance.registerSimulatorApi('share', params => nativeUi.invoke('share', params))
-
-    // 自定义 IPC：经 gated 的 IpcRegistry，不再裸 ipcMain.handle
-    instance.ipc.handle('my:action', () => collectStats())
-
-    // host 自己的弹窗须注册为受信 sender 后才能调 instance.ipc
-    // const win = createDialogWindow(/* ... */)
-    // instance.registerTrustedWindow(win)
-  },
-  onBeforeClose: ({ context }) => {
-    // 窗口关闭前的自定义清理；session 关闭和 view 销毁由框架自动处理
-  },
+launch().catch((err) => {
+  console.error(err)
+  process.exit(1)
 })
 ```
 
-> Contribution 注册物全部自动进 `context.registry`，host 无需手写 cleanup。devtools 内部仍用 `WorkbenchModule` 组织内置 IPC 模块，但这是实现细节，不再作为对外接入方式导出。
-
----
-
-## 目录结构
-
-```
-src/
-  shared/
-    types.ts                             # 跨层共享类型
-    constants.ts                         # 跨层共享常量
-    ipc-channels.ts                      # IPC 频道名称常量
-  main/
-    api.ts                               # 公共 API 聚合入口（package main）
-    app/
-      launch.ts                          # 零配置入口
-      app.ts                             # createDevtoolsRuntime 装配体 + runDevtoolsBootstrap
-      bootstrap.ts                       # suppressEpipe / setupCdpPort
-      lifecycle.ts                       # Electron app 生命周期注册
-    ipc/                                 # 只做 handler 注册，不写业务
-      index.ts                           # 聚合 register 函数导出
-      simulator.ts                       # simulator attach/detach/设备信息/custom-api invoke
-      popover.ts                         # 编译配置弹窗
-      settings.ts                        # 项目设置 + workbench 设置
-      projects.ts                        # 项目列表管理
-      session.ts                         # 编译会话 open/close/status
-    services/                            # 按业务领域分，真正的业务能力
-      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 / simulatorDir / cjsSiblingPreloadPath
-      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                            # workbench 三窗口 preload，仅暴露 window.devtools.ipc
-      simulator.ts                       # simulator（WCV）frame preload（native-host 跑其 .cjs sibling）
-    shared/                              # preload 之间共享
-      api-compat.ts                      # setupApiCompatHook
-      constants.ts
-      types.ts
-    instrumentation/                     # 注入到小程序 runtime 的探针
-      console.ts                         # 控制台拦截
-      app-data.ts                        # Worker setData 拦截 → createAppDataSource
-      wxml.ts                            # Vue 组件树提取 → createWxmlSource
-    miniapp-snapshot/                    # 面板数据统一快照框架（docs/miniapp-snapshot.md）
-      types.ts                           # MiniappSnapshotSource / SnapshotEnvelope
-      host.ts                            # createMiniappSnapshotHost → push/pull/__miniappSnapshot
-    runtime/
-      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/
-        main.tsx                         # 主窗口 React 根
-        features/                        # 主窗口内的业务区域
-          project-runtime/               # 项目视图 + 工具栏 + 右侧面板切换
-          right-panel/                   # WXML / AppData / Storage / 编译 面板
-      popover/ settings/ workbench-settings/
-    shared/
-      components/                        # UI 组件（ui / layout / json-viewer / ...）
-      lib/                               # ipc / simulator-url / utils / ...
-
-  simulator/                             # 小程序容器运行时（独立 webview 入口）
-    simulator.html
-    main.tsx
-    simulator-api.ts
-    simulator-api-storage.ts
-    simulator-api-device.ts
-    simulator-api-media.ts
-    simulator-api-fs.ts
-```
-
-渲染层使用 **React + shadcn/ui + Tailwind CSS**，通过 Vite 构建，产物输出到 `dist/renderer/`。
-
----
-
-## 配置参考
-
-### WorkbenchConfig
+别在 main 模块顶层 `await launch()`：它内部等 `app.whenReady()`，而 Electron 要等 main 模块求值完成才触发 ready，顶层 await 会死锁。
 
-`launch()` 接受的基础字段（`WorkbenchConfig`）：
+带宿主配置的最小形状：
 
-| 字段               | 类型                 | 默认值              | 说明                               |
-| ------------------ | -------------------- | ------------------- | ---------------------------------- |
-| `appName`          | `string`             | `'Dimina DevTools'` | 窗口标题                           |
-| `adapter`          | `CompilationAdapter` | 内置                | 项目编译适配器                     |
-| `panels`           | `BuiltinPanelId[]`   | —                   | **已废弃，运行时忽略**：界面恒显示全部内置面板（WXML / AppData / Storage / Console / 编译）；保留字段仅为兼容仍传它的 host |
-| `preloadPath`      | `string`             | 内置                | 统一的 host 级 preload 入口；native-host simulator（WCV）自动跑其 `.cjs` sibling（`cjsSiblingPreloadPath`） |
-| `apiNamespaces`    | `string[]`           | `[]`                | 自定义 API 命名空间（如 `['qd']`） |
-| `brandingProvider` | `() => { appName }`  | —                   | 品牌信息 provider                  |
-| `headerHeight`     | `number`             | —                   | **已废弃，运行时忽略**：头部栏恒为 40px（`HEADER_H`）；需要自定义工具栏请用 host toolbar WCV |
-
-### WorkbenchAppConfig（扩展 WorkbenchConfig）
-
-`launch()` 完整接受的 `WorkbenchAppConfig` 额外支持：
-
-| 字段            | 类型                                        | 默认值      | 说明                                              |
-| --------------- | ------------------------------------------- | ----------- | ------------------------------------------------- |
-| `modules`       | `Partial<Record<BuiltinModuleId, boolean>>` | 全部 `true` | 开关内置 IPC 模块组                               |
-| `rendererDir`   | `string`                                    | 内置        | 自定义 renderer HTML 目录                         |
-| `icon`          | `string`                                    | —           | 窗口/任务栏图标路径（macOS 使用 app bundle 图标） |
-| `menuBuilder`   | `(mainWindow, menuContext: MenuContext) => void` | 内置菜单 | 自定义菜单构建器；`menuContext` 为手写窄契约 `MenuContext`（`appName` + workspace 窄集 + `openSettings` + `notify.{projectStatus, windowNavigateBack}`），不含内部管线 |
-| `onSetup`       | `(instance) => void`                        | —           | 窗口和 context 创建后的回调，用于注册 Contribution（见下文）|
-| `onBeforeClose` | `(instance) => void`                        | —           | 窗口关闭前的回调，session 关闭由框架自动处理      |
-| `onBeforeOpenProject` | `(projectPath: string) => void \| Promise<void>` | — | 打开项目前、任何副作用（旧会话拆除 / 编译 / dev-server）之前运行的声明式权限门控。抛错即否决：`openProject` 返回 `{ success: false, error }`，当前活动会话保持不动、适配器不被调用，且框架自动把 error 透到状态条（`notify.projectStatus`）。覆盖 IPC / 菜单 / 内部直调三个打开入口 |
-| `window`        | `WorkbenchWindowConfig`（`width`/`height`/`autoShow?`） | — | 主窗口尺寸覆盖；`autoShow`（默认 `true`）控制 `ready-to-show` 是否自动显示窗口。`autoShow: false` 时窗口创建即隐藏（test / 非 test 一致），由 host 在登录通过后自行 `instance.mainWindow.show()` |
-| `updateChecker` | `UpdateChecker`                             | —           | 自定义更新检查器；提供后启用"检查更新"功能        |
-| `updateOptions` | `{ checkInterval?, initialDelay?, getCurrentVersion? }` | —  | 仅当 `updateChecker` 提供时生效，默认 1h / 5s     |
-
-### onSetup Contribution
-
-`onSetup(instance)` 收到的 `instance` 上有一组 typed 注册方法，全部 per-context、自动进 `context.registry`：
-
-| 方法 | 说明 |
-| --- | --- |
-| `instance.registerSimulatorApi(name, handler)` | 注册 simulator 自定义 API，小程序里 `wx.<name>()` 调用（详见下方"Simulator 自定义 API"）。返回 `Disposable` |
-| `instance.registerSimulatorUiExtension({ id, rendererScriptPath })` | 注册可信 renderer bundle。框架负责注入当前 simulator、稳定 Overlay Root、soft reload 的 current/pending 切换和销毁；返回可 `invoke()` 的句柄 |
-| `instance.ipc` | `IpcRegistry` 实例，`instance.ipc.handle(channel, fn)` 注册自定义 IPC；已绑定 `senderPolicy` 网关 |
-| `instance.registerTrustedWindow(win)` | 把 host 自有弹窗 `BrowserWindow` 加入受信 sender 集，否则其发起的 `instance.ipc` 调用会被网关拒绝。窗口关闭即移除 |
-
-### 内置面板 ID
-
-`'wxml'` \| `'console'` \| `'appdata'` \| `'storage'`
-
-### 内置模块 ID
-
-`'projects'` \| `'session'` \| `'simulator'` \| `'popover'` \| `'settings'`
-
----
-
-## Embedding & Extending the Project Panel
-
-下游宿主通过 `launch({...})` 嵌入 devtools 时，可对项目面板做三个正交扩展：
-
-| 扩展点 | 用途 |
-| --- | --- |
-| `projectsProvider` | 接管项目列表存储 —— 替换默认 `<userData>/dimina-projects.json`，对接下游宿主后台 / IDE workspace / 远端工程库 |
-| `projectTemplates` + `builtinTemplates` | 注入/覆盖/裁剪"新建项目"模板列表（同 id 覆盖内置；`builtinTemplates` 控制内置策略） |
-| `customCreateProjectDialog` | 用宿主自家页面替换内置"新建项目"对话框（main 进程 hook，可 `new BrowserWindow` 加载任意 URL，通过 IPC/postMessage 回传结果） |
-
-### 何时需要哪个扩展点
-
-| 场景 | 需要的扩展点 |
-| --- | --- |
-| 项目列表来自下游宿主后台 / 团队工程库 | `projectsProvider` |
-| 仅替换可选模板（e.g. 只提供 taro / 宿主自家脚手架） | `projectTemplates` + `builtinTemplates` |
-| 创建项目流程要走宿主自己的 wizard / 登录态 | `customCreateProjectDialog` |
-
-### 最小示例
-
-```typescript
+```ts
 import { launch } from '@dimina-kit/devtools'
-import type { ProjectsProvider, ProjectTemplate } from '@dimina-kit/devtools/projects-provider'
-import { BrowserWindow } from 'electron'
-
-const provider: ProjectsProvider = {
-  async listProjects() {
-    return await host.api.listProjects()
-  },
-  async validateProjectDir(dirPath) {
-    return (await host.api.isMiniApp(dirPath)) ? null : '不是合法的小程序工程'
-  },
-  async addProject(dirPath) {
-    return await host.api.addProject(dirPath)
-  },
-  async removeProject(dirPath) {
-    await host.api.removeProject(dirPath)
-  },
-  async updateLastOpened(dirPath) {
-    await host.api.touchLastOpened(dirPath)
-  },
-  async getCompileConfig(dirPath) {
-    return await host.api.getCompileConfig(dirPath)
-  },
-  async saveCompileConfig(dirPath, cfg) {
-    await host.api.saveCompileConfig(dirPath, cfg)
-  },
-  // 缩略图走云端存储——dataUrl 形如 'data:image/png;base64,...'
-  async saveThumbnail(dirPath, imageDataUrl) {
-    await host.api.uploadThumbnail(dirPath, imageDataUrl)
-  },
-  async getThumbnail(dirPath) {
-    return await host.api.fetchThumbnail(dirPath)
-  },
-}
-
-const hostBlank: ProjectTemplate = {
-  id: 'blank', // 同 id 覆盖内置 blank
-  name: '宿主空白工程',
-  description: '由下游宿主维护的官方空白模板',
-  source: { type: 'directory', path: '/abs/path/to/template' },
-}
 
 launch({
-  projectsProvider: provider,
-  projectTemplates: [hostBlank],
-  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://host.example.com/devtools/new-project')
-    return await new Promise((resolve) => {
-      win.webContents.ipc.once('host:create-project:done', (_e, payload) => {
-        win.close()
-        // payload 三选一（CustomCreateProjectDialogResult）：
-        //   null                  → 用户取消
-        //   CreateProjectInput    → 让 devtools 在本地物化模板并注册到 provider
-        //   { ready: Project }    → 宿主后端已经创建好，devtools 直接刷新列表
-        resolve(payload ?? null)
-      })
-      win.on('closed', () => resolve(null))
-    })
-  },
-})
-```
-
-### `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 注入会覆盖（例如上文 `hostBlank` 覆盖了内置 `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
-
-实现此接口接入自定义构建流程：
-
-```typescript
-import type { CompilationAdapter } from '@dimina-kit/devtools/types'
-
-const myAdapter: CompilationAdapter = {
-  async openProject(opts) {
-    // opts.projectPath  — 小程序项目绝对路径
-    // opts.sourcemap    — 是否生成 sourcemap
-    // opts.onRebuild    — 热更新回调
-    // opts.onBuildError — 构建错误回调
-    return {
-      port: 3000,
-      appInfo: { appName: 'my-app' },
-      close: async () => {},
-    }
-  },
-}
-```
-
----
-
-## Preload Instrumentation
-
-模拟器 frame 注入 preload 脚本，在其全局上安装两类东西：**桥接**（把数据通道暴露到运行时全局）+ **instrumentation**（监听运行时事件并写入桥接）。内置 preload 见 `src/preload/windows/simulator.ts`（native-host simulator 跑其 `.cjs` sibling）。
-
-### 必装：桥接
-
-| 函数 | 作用 | 不装会怎样 |
-| --- | --- | --- |
-| `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；AppData/WXML 走主进程 `SimulatorAppDataChannel` / `SimulatorWxmlChannel`；Console 走 render-host/service-host guest preload → 主进程 `consoleLog`），均不依赖 `window.__simulatorData`，不受影响 |
-| `installCustomApisBridge()` | 暴露 `window.__diminaCustomApis`，承载 `list` / `invoke`，让模拟器侧把主进程注册的 API 代理回小程序 runtime | `registerSimulatorApi` 注册的业务 API 在小程序里调用全部 no-op（参见下方 "Simulator 自定义 API"） |
-| `setupApiCompatHook()` | 兼容上游 API 名称变更 | 部分 API 调用兼容性问题 |
-
-下游写自定义 preload 时，这三项原则上都要装。若不需要 `registerSimulatorApi`，`installCustomApisBridge` 可省略。
-
-### 按需：instrumentation
-
-这些探针是**可组合的 preload API**：`@dimina-kit/devtools/preload` 把它们导出，供下游自己拼装自定义 preload。下表是各探针自身的契约（捕获什么 + 推到哪个通道）。
-
-| 探针 | 捕获内容 | 数据通道 |
-| --- | --- | --- |
-| `installConsoleInstrumentation()` | `console.*`、`window.onerror`、未捕获 rejection | `sendToHost`（guest → embedder） |
-| `createAppDataSource()` | Worker `ub` 消息、setData / page init | miniappSnapshot 框架（`miniapp-snapshot:push`） |
-| `createWxmlSource()` | Vue 组件树提取、MutationObserver 自动更新 | miniappSnapshot 框架（`miniapp-snapshot:push`） |
-
-> ⚠️ **内置 native-host 运行时并不靠这条 `miniapp-snapshot:push` 通道喂面板**：右侧 WXML / AppData 面板的数据由主进程服务（`SimulatorWxmlChannel` / `SimulatorAppDataChannel`）直接供给（见下方「数据流」）。内置 simulator preload 仍调用 `createAppDataSource().start()`，但只为副作用（填 `window.__simulatorData.getAppdata()` 供 automation / MCP 读取），并**不**把它 wrap 进 `MiniappSnapshotHost`——所以 `miniapp-snapshot:push` 在内置路径下无消费者。该框架契约（含 `createWxmlSource`）仍为外部/组合式 preload 保留导出（详见 `docs/miniapp-snapshot.md`）。
-
-> Storage 面板的数据由主进程通过 CDP `DOMStorage` 域抓取（`src/main/services/simulator-storage`），**不需要 preload 侧 instrumentation**。
-
-各面板的数据流详见下方 "数据流" 章节。
-
-### 自定义 Preload
-
-参考 `src/preload/windows/simulator.ts`：
-
-```typescript
-// my-preload.ts
-import {
-  installSimulatorBridge,
-  installCustomApisBridge,
-  installConsoleInstrumentation,
-  createMiniappSnapshotHost,
-  createAppDataSource,
-  createWxmlSource,
-  setupApiCompatHook,
-} from '@dimina-kit/devtools/preload'
-
-// 1. 兼容 hook + 桥接（必装，且应在 instrumentation 之前）
-setupApiCompatHook()
-installSimulatorBridge()
-installCustomApisBridge()   // 若用到 registerSimulatorApi，必装
-
-// 2. Console instrumentation（按需）
-installConsoleInstrumentation()
-
-// 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)
+  appName: 'My Miniapp Studio',
+  adapter: myCompilationAdapter,
+  onSetup(instance) {
+    instance.registerSimulatorApi('login', params => login(params))
+  },
+}).catch((err) => {
+  console.error(err)
+  process.exit(1)
 })
 ```
 
-编译后传入路径：
-
-```typescript
-launch({ preloadPath: '/absolute/path/to/my-preload.js' })
-```
-
----
-
-## Simulator 自定义 API
-
-下游通过 `onSetup` 里的 `instance.registerSimulatorApi(name, handler)` 把业务 API 注入到模拟器内运行的小程序。注册 per-context，随 context 销毁。Handler 在 Electron **主进程**执行，能用任何 Node 能力（fs、net、原生模块、持久状态）；模拟器侧拿到 `wx.<name>(params)` 调用后通过 IPC 转发到主进程，await 返回结果，handler 抛错则原型回传给小程序。
+配置字段、`CompilationAdapter`、项目 Provider、preload、模拟器 UI、host toolbar 和公共导出已经移到[库集成参考](./docs/library-integration.md)。
 
-> ⚠️ 使用本功能要求模拟器 preload 调用 `installCustomApisBridge()`（详见上方 "Preload Instrumentation"）。内置 preload 已包含此调用；若用了自定义 preload 又漏装，注册的 API 在小程序运行时**没有任何反应**，simulator 端会有 `console.warn`。
+## 先读哪些文档
 
-### 命名约定
-
-`name` 是 dimina service 层 `invokeAPI(name, opts)` 用的**裸名**，不带 `wx.` 前缀。注册之后小程序里通过 `wx.<name>(...)`（以及在 `apiNamespaces` 配的其它命名空间）调用都会命中：
-
-| 小程序里写 | `registerSimulatorApi` 的 name |
+| 目标 | 文档 |
 | --- | --- |
-| `wx.login(...)` | `'login'` |
-| `wx.request(...)` | `'request'` |
-| `wx.getStorage(...)` 覆盖内置 | `'getStorage'`（小心：这会**屏蔽** dimina 容器的实现） |
-
-```typescript
-launch({
-  onSetup: (instance) => {
-    // 提供 wx.login 的实现（dimina 容器默认未实现，注册后才能用）
-    const dispose = instance.registerSimulatorApi('login', async ({ success }) => {
-      // 主进程上下文：可调用内部 HTTP、读取凭证文件、访问原生模块
-      const code = await callInternalAuth()
-      return { code }
-    })
-
-    // 注册物已进 context.registry，随 context 销毁；
-    // 提前取消用返回的 dispose()
-  },
-})
-```
-
-### 行为约定
-
-- **注册时机**：模拟器在启动小程序之前会 `await` 主进程的自定义 API 全量列表并完成注册，因此运行时框架在初始化时一次性枚举 API 表（典型如 Taro 的 `Object.keys(wx)`）也能枚举到 `registerSimulatorApi` 注册的 name。bridge 异常或超时（3s）则降级为"无自定义 API"，不会阻塞小程序启动。
-- **命中顺序**：小程序运行时按 `apiRegistry[name] → MiniApp 实例方法 → 扩展模块兜底` 查找，所以 `registerSimulatorApi` 注册的 name **优先于内置实现**——既能给"未实现"的 wx.* 补功能（如 `wx.login`），也能覆盖默认的 wx.* 行为（如 `wx.request`，dimina-kit 本身就在用这条路把 `request` 接到主进程 fetch）。
-- **回调风格自动桥接**：小程序用微信风格 `wx.<name>({ success, fail, complete })` 调用时，模拟器会把 handler 的 resolve 派发给 `success`、reject 派发给 `fail`，并在两种情况下都触发 `complete`。handler 本身只需 promise 风格 resolve/reject —— `success/fail/complete` 是渲染端回调 id，转发到主进程前已被剔除，handler 不会收到它们。
-- 同名重复注册：后注册的覆盖前者，静默替换。
-- `dispose()` 只会移除自己创建的那次注册——如果之后被别人覆盖了，旧的 disposer 是 no-op。
-- 调用未注册且容器内也没有的 name：小程序侧拿到 reject，错误信息里带 name。
-- Handler 可同步或异步返回；**返回值需可 JSON 序列化**（IPC 限制）。函数、Symbol、Map/Set、循环引用都会丢失。
-
----
-
-## Simulator UI 扩展
-
-需要分享面板、授权弹窗等产品 UI 的下游 host，应同时使用两个正交接口：
-
-- `registerSimulatorApi` 定义小程序侧 `wx.*` 命令。
-- `registerSimulatorUiExtension` 安装下游 renderer bundle，并通过返回句柄把命令送到 UI。
-
-主进程只注册绝对路径指向的可信构建产物：
-
-```typescript
-const nativeUi = instance.registerSimulatorUiExtension({
-  id: 'my.native-ui',
-  rendererScriptPath: fileURLToPath(
-    new URL('../renderer/native-ui.js', import.meta.url),
-  ),
-})
-
-instance.registerSimulatorApi('share', params =>
-  nativeUi.invoke('share', params),
-)
-```
-
-renderer bundle 使用 `@dimina-kit/devtools/simulator-ui` 注册实现：
-
-```typescript
-import { registerSimulatorUiExtension } from '@dimina-kit/devtools/simulator-ui'
-
-let runtime
-
-registerSimulatorUiExtension({
-  id: 'my.native-ui',
-  mount({ overlayRoot, appId, signal }) {
-    runtime = createNativeUi({ root: overlayRoot, appId })
-    signal.addEventListener('abort', () => runtime.destroy(), { once: true })
-    return () => runtime.destroy()
-  },
-  invoke(method, params) {
-    return runtime.invoke(method, params)
-  },
-  onChromeAction(action) {
-    if (action.name !== 'capsule.more') return false
-    runtime.showMoreMenu(action)
-    return true
-  },
-})
-```
-
-契约边界：
-
-- 框架只提供设备内的稳定 Overlay Root，不接收 React Component，因而不绑定下游 React 版本。
-- 只有可见的 current `DeviceShell` 持有挂载点；soft reload 提升 pending shell 时，旧 mount 先收到 abort/cleanup，再在新 root 上 mount。
-- Overlay Root 默认不拦截页面点击；扩展实际创建的交互层需要设置 `pointer-events: auto`。
-- 胶囊菜单通过语义动作 `capsule.more` 分发，不应查询 `.menu-capsule__more` 或拦截 DOM click。
-- `id` 在一个 context 内唯一；script 必须用相同 `id` 注册 renderer 实现，否则安装失败。
-- 每次 simulator 顶层文档完成加载时都会重新读取 `rendererScriptPath`，因此开发态重建
-  bundle 后执行硬 reload 即可加载新代码；soft reload 只切换 DeviceShell 挂载点，不重复执行 bundle。
-- `dispose()` 会注销 renderer 实现；context 销毁时自动执行。`invoke()` 参数和返回值必须可跨 Electron IPC/`executeJavaScript` 序列化。
-
----
-
-## Host Toolbar（宿主自定义工具栏）
-
-下游通过 `instance.context.views.hostToolbar` 拥有 devtools 头部下方的工具栏条（一个 WebContentsView）：`loadURL` / `loadFile` 加载自己的内容，`setPreloadPath` 注入自己的 preload，`setHeightMode` 钉死或自动跟随内容高度（自动模式要求内容自带 shrink-to-fit 的 `[data-host-toolbar-root]` 包裹元素；`{ fixed }` 校验入参——非有限数或负数同步抛 `TypeError` 且不污染既有模式）。主进程保留最后一次下发的高度（`views.getHostToolbarHeight()`），项目视图的占位条挂载时会主动拉取并回放——广播器对已上报的高度去重不再重发，没有这一步，冷启动在项目列表期间的上报、以及关闭项目再打开后的高度都会永久丢失（工具栏条塌缩为 0）。
-
-### 双向消息：onMessage / send
-
-主进程与工具栏页面之间有一条门控窄通道（按 load 握手的 MessagePort，信封 `{ channel, payload }`）：
-
-- `hostToolbar.onMessage(channel, handler): { dispose() }` — 接收页面消息。控制面级注册：可在 view 创建前调用，且跨页面 reload 自动续接，无需重新注册。空串/非 string channel 抛错。
-- `hostToolbar.send(channel, payload): boolean` — 发消息给页面。门控不排队：没有活的工具栏 webContents、本次 load 的握手未完成、或正处于换文档导航窗口期（`loadURL`/`loadFile` 发起后、以及页面自发的主框架跨文档导航开始后，直到新文档握手完成）时返回 `false`（不投递、不建 view）；返回 `true` 即已发出。返回值本身就是就绪信号，下游不再需要拿 `getHostToolbarWebContentsId()` 手工判断工具栏是否就绪（该 API 保留）。
-- `hostToolbar.onReady(handler): { dispose() }` — 握手完成的推送信号（每个 load generation fire 一次；已就绪后注册在微任务上补发一次，补发前复查订阅与 generation）。在 handler 内 `send()` 必然返回 `true`，可用于推送初始状态，替代轮询 retry loop。
-
-页面侧由框架自动注入 `window.diminaHostToolbar`（仅 `{ send, onMessage }` 两个函数；类型可从根入口导入 `DiminaHostToolbarPageBridge`，并附带 optional 的 `Window` 增强。握手前的 `send` 进队列、握手后按序送达。队列上限 128 条：超限丢弃最新一条、首次超限 console.warn 一次，不抛错。`send`/`onMessage` 对空串/非 string channel 同步抛 `TypeError`，与主进程同语义）：
-
-```js
-// 工具栏页面内
-window.diminaHostToolbar.onMessage('host:cmd', (payload) => { /* ... */ })
-window.diminaHostToolbar.send('page:event', { clicked: 'compile' })
-```
-
-```ts
-// 主进程（onSetup 内）
-const sub = instance.context.views.hostToolbar.onMessage('page:event', (payload) => { /* ... */ })
-instance.context.views.hostToolbar.send('host:cmd', { theme: 'dark' }) // false = 未送达
-```
+| 把 devtools 嵌入自己的 Electron 应用 | [库集成参考](./docs/library-integration.md) |
+| 了解目录、构建、调试和安全边界 | [贡献者指南](./docs/contributing.md) |
+| 了解窗口、WebContentsView、IPC 和生命周期 | [Electron Container 架构](./docs/electron-container.md) |
+| 了解模拟器与页面 render host | [模拟器渲染架构](./docs/simulator-render-architecture.md) |
+| 了解 Chrome DevTools 的 Console、Network、Elements 和源码跳转 | [DevTools CDP 路由](./docs/devtools-cdp-routing.mdx) |
+| 了解内置 VS Code 工作台 | [编辑器集成](./docs/editor-integration.md) |
+| 了解项目窗口的 dock、分屏和原生视图定位 | [项目窗口布局](./docs/project-window-layout.md) 与 [视图 Placement 对账](./docs/view-placement-reconciler.md) |
+| 了解页面栈或 TabBar | [页面栈](./docs/page-stack.md) 与 [TabBar](./docs/tab-bar.md) |
 
----
-
-## 模块导出一览
-
-`@dimina-kit/devtools` 的公共入口。`api.ts`（根入口）聚合了所有公共 API，优先从根入口导入。
-
-```
-@dimina-kit/devtools                        launch, buildDefaultMenu,
-                                       openSettingsWindow, suppressEpipe, setupCdpPort,
-                                       asMiniappRuntime, MiniappRuntime / MiniappSessionAppInfo /
-                                       DiminaHostToolbarPageBridge（type）,
-                                       createWorkbenchContext, createMainWindow,
-                                       createViewManager, IpcRegistry,
-                                       UpdateManager, createGitHubReleaseChecker, ...
-@dimina-kit/devtools/launch                 launch(config?), buildDefaultMenu, openSettingsWindow
-@dimina-kit/devtools/types                  TypeScript 类型定义
-@dimina-kit/devtools/bootstrap              suppressEpipe(), setupCdpPort()
-@dimina-kit/devtools/context                createWorkbenchContext(opts)
-@dimina-kit/devtools/create-window          createMainWindow(opts)
-@dimina-kit/devtools/paths                  rendererDir, defaultPreloadPath, simulatorDir,
-                                       getRendererDir, getPreloadDir, getRendererHtml
-@dimina-kit/devtools/projects-provider      ProjectsProvider / ProjectTemplate 等类型
-@dimina-kit/devtools/workbench-settings     loadWorkbenchSettings(), saveWorkbenchSettings(), applyTheme()
-@dimina-kit/devtools/preload                installSimulatorBridge,
-                                       installCustomApisBridge,
-                                       installConsoleInstrumentation,
-                                       createMiniappSnapshotHost,
-                                       createAppDataSource, createWxmlSource,
-                                       setupApiCompatHook
-                                       （storage 面板数据由主进程 CDP 抓取，无 preload 侧 hook）
-```
-
-> `IpcRegistry` 是 host 写自定义 IPC 的网关基类——`onSetup` 里通过 `instance.ipc` 拿到一个已绑定 `senderPolicy` 的实例，无需自行构造。
-> 自定义 simulator API 通过 `instance.registerSimulatorApi` 注册，没有独立的导出入口。
-> 内置 IPC 模块（`register*Ipc` / `WorkbenchModule`）是 devtools 内部实现，不再对外导出。
-
----
-
-## MiniappRuntime（宿主集成推荐契约）
-
-下游宿主集成时，推荐依赖手写的稳定契约 `MiniappRuntime`，而不是整个 `WorkbenchContext`——后者携带全部内部 service 类型，内部重构会直接破坏下游编译。`asMiniappRuntime(ctx)` 恒等返回（typed view，非拷贝），宿主对 `runtime.workspace.openProject` 的 monkey-patch 会落在真实对象上：
-
-```typescript
-import { asMiniappRuntime, type MiniappRuntime } from '@dimina-kit/devtools'
-
-const runtime: MiniappRuntime = asMiniappRuntime(instance.context)
-runtime.workspace.openProject = gated(runtime.workspace.openProject) // 权限闸（契约保证可写）
-runtime.views.hostToolbar.send('host:cmd', { theme: 'dark' })
-runtime.notify.projectStatus({ status: 'ready', message: '编译完成' })
-```
-
-契约面：`views.hostToolbar`（7 成员，含 `onReady`，无 `webContents`）/ `workspace`（7 方法，`getSession().appInfo` 为结构化 `MiniappSessionAppInfo`，`appId` 必有）/ `notify.projectStatus` / `registry.add`（接受 `{ dispose }` 对象或裸函数两种习语）/ `openSettings()`。零 Electron 类型。0.4.0 起不再含 `rendererDir`（用 `/paths` 导出）与 `windows`（用 `openSettings()`）。
-
-## WorkbenchContext
-
-`WorkbenchContext` 是所有扩展点的唯一容器。配置字段直接暴露，运行时状态通过 service 访问。host hook 拿到的 `instance.context` 即此类型；`menuBuilder` 拿到的是手写窄契约 `MenuContext`（`appName` + workspace 窄集 + `openSettings` + `notify.{projectStatus, windowNavigateBack}`，不再是 `WorkbenchContext` 的 Omit 投影）。
-
-```typescript
-interface WorkbenchContext {
-  adapter: CompilationAdapter
-  preloadPath: string
-  rendererDir: string
-  apiNamespaces: string[]
-  appName: string
-  brandingProvider?: () => Promise<{ appName: string }> | { appName: string }
-
-  // ── 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(), ...
-
-  // ── 扩展容器（host 通过 instance 上的方法写入，不直接操作）──
-  simulatorApis: SimulatorApiRegistry  // instance.registerSimulatorApi 写入
-  trustedWindowSenderIds: Map<number, number>  // instance.registerTrustedWindow 写入（webContents.id → 引用计数）
-
-  // ── Internal lifecycle / security (host 不直接消费) ──
-  registry: DisposableRegistry // 框架在创建时统一聚合 dispose
-  senderPolicy: SenderPolicy   // IpcRegistry 自动校验 sender 白名单
-}
-```
-
-会话和视图状态封装在对应 service 的私有闭包中，通过方法访问，例如：
-
-- `ctx.workspace.getProjectPath()` / `ctx.workspace.getSession()` / `ctx.workspace.hasActiveSession()`
-- `ctx.views.getSimulatorWebContentsId()` / `ctx.views.getSimulatorWebContents()`
-- `ctx.windows.mainWindow` / `ctx.windows.settingsWindow`
-
----
-
-## 整体架构
-
-### 视图层级（从上到下 = 从顶层到底层）
-
-```mermaid
-flowchart TB
-    subgraph BW["BrowserWindow"]
-        direction TB
-        Z4["⑤ popoverView &nbsp;[顶层]<br/>entries/popover/index.html<br/>全屏透明遮罩 + 编译配置表单"]
-        Z3["④ settingsView<br/>entries/settings/index.html<br/>固定宽度 320px，右侧对齐"]
-        Z2["② simulatorView<br/>Chrome DevTools 面板（绑到活跃 render-host guest / service host）"]
-        Z1["① nativeSimulatorView : WebContentsView<br/>模拟器主进程顶层 WCV（跑 simulator/main.tsx 的 DeviceShell）<br/>partition=persist:simulator，托管每页 render-host &lt;webview&gt; guest"]
-        subgraph Z0["⓪ mainWindow &nbsp;[底层]&nbsp;entries/main/index.html"]
-            direction LR
-            SIM["&lt;SimulatorPanel&gt; 占位 / 锚点<br/>（仅 nativeSimulatorView 的 bounds target，无 webview）"]
-            PNL["WXML / AppData / Storage<br/>React 中直接渲染"]
-        end
-        Z4 -. 覆盖 .-> Z3
-        Z3 -. 覆盖 .-> Z2
-        Z2 -. 覆盖 .-> Z1
-        Z1 -. 覆盖 .-> Z0
-    end
-```
-
-层级由 `addChildView()` 调用顺序决定，后添加的 View 在上层。overlay 栈里有**两个不同的** simulator 相关 view：`nativeSimulatorView`（模拟器本体，主进程顶层 `WebContentsView`，跑 `simulator/main.tsx` 的 DeviceShell，内部托管每页 render-host `<webview>` guest）和 `simulatorView`（Chrome DevTools 面板本身，绑到活跃 render-host guest / service host）。模拟器**不是** mainWindow renderer 里的 `<webview>`——主 renderer 的 `<SimulatorPanel>` 只画一个空占位 div 当 `nativeSimulatorView` 的 bounds 锚点（手机框 / 圆角 / 刘海 / 页面 `<webview>` 都在那个 WCV 内部的 DeviceShell 里）。内置面板（WXML / AppData / Storage）不使用独立 WebContentsView，直接在主窗口 React 中渲染；只有 nativeSimulator / Chrome DevTools / settings / popover 需要 View 覆盖。
-
-### 数据流
-
-按面板 / 场景拆分：
-
-| 面板 / 场景 | 模式 | 路径 |
-| --- | --- | --- |
-| Console | 推送 | render-host / service-host preload monkeypatch `console.*` → 主进程 `consoleLog` 容器消息 → bridge-router → `ctx.guestConsole.emit` → `services/console-forward`。render（视图）层条目以 `[视图]` 前缀注入挂在 service host 上的 Chrome DevTools，service 层本就原生显示在同一面板；automation WS 等外部订阅者也从这里 fan-out |
-| AppData / WXML 树 | 推送 + 拉取 | 主进程服务，镜像 Storage 的 main→renderer 契约：WXML 由 `services/simulator-wxml` 经 render-inspect 从活跃 render-host `<webview>` guest 拉树（`SimulatorWxmlChannel.GetSnapshot`），render 活动时推 `SimulatorWxmlChannel.Event`；AppData 由 `services/simulator-appdata` 在 bridge-router 里 tap service→render 的 setData 流，推 `SimulatorAppDataChannel.Event` |
-| Storage | 拉取 + 推送 | renderer `ipcInvoke(SimulatorStorageChannel.GetSnapshot)` → 主进程 CDP `DOMStorage` 域；变更事件由主进程通过 `SimulatorStorageChannel.Event` 推回 renderer |
-| 元素选区 / `Page.getData` / MCP overview | 拉取 | 主进程 `webContents.executeJavaScript(...)` 或 `Runtime.evaluate(...)` 读 `window.__simulatorData.*`（由 `installSimulatorBridge` 暴露） |
-
----
-
-## IPC 通信总览
-
-IPC 频道名常量集中定义在 `src/shared/ipc-channels.ts`，按域分组（`SimulatorChannel` / `ProjectChannel` / `WorkbenchSettingsChannel` 等）。该文件是频道清单的唯一真相源；此处不再维护手抄表，以免与代码漂移。
-
----
-
-## 已知限制：Electron `chrome.devtools.panels.create()` 不可用
-
-Electron 对 `chrome.devtools.panels.create()` 的支持**长期不稳定**。该 API 调用成功（无报错，返回 panel 对象），但面板 tab 永远不出现在 DevTools UI 中。
-
-**影响范围**：从 Electron 7 到 39 均有报告（[#23662](https://github.com/electron/electron/issues/23662)、[#41613](https://github.com/electron/electron/issues/41613)、[#48705](https://github.com/electron/electron/issues/48705)），非特定版本 bug，而是系统性实现缺陷。官方文档声称完全支持，但实际因竞态条件和实现不完整导致面板无法可靠渲染。Electron 团队无修复计划。
-
-**当前方案**：内置面板（WXML / AppData / Storage）直接在主窗口 React 中渲染，数据由主进程服务直接供给——WXML / AppData 走 `SimulatorWxmlChannel` / `SimulatorAppDataChannel`（main → renderer 的 seed `GetSnapshot` + push `Event`），Storage 走 CDP `DOMStorage` 域（详见上方「数据流」）；Chrome DevTools 仍作为独立 `WebContentsView` 通过 `setDevToolsWebContents()` 挂载。面板切换由 renderer toolbar 的 tab 栏控制，主进程负责 nativeSimulator/settings/popover View 的创建、定位和显隐。详见 `src/main/ipc/simulator.ts`。
-
----
-
-## 调试
-
-- **Cmd+Shift+I** / **Ctrl+Shift+I** — 打开 mainWindow 的 Electron DevTools（调试 React 渲染层）
-- 模拟器活跃 render-host `<webview>` guest 的 Chrome DevTools 在编译完成、`dom-ready` 后自动打开
-- 开发模式（`!app.isPackaged`）下 mainWindow DevTools 自动以 detach 模式打开
-
----
-
-## 开发
+## 在仓库中开发
 
 ```bash
-pnpm build              # 构建全部（main + preload + renderer）
-pnpm build:main         # 仅构建主进程 TypeScript
-pnpm build:preload      # 仅构建 preload TypeScript
-pnpm build:renderer     # Vite 构建渲染层
-pnpm dev                # Watch 模式 + Electron
-pnpm check-types        # 类型检查
-pnpm test               # 运行单元测试（vitest）
-pnpm test:coverage      # 单元测试 + 覆盖率报告（终端表格 + coverage/index.html）
-pnpm test:e2e           # 运行 Playwright e2e 测试
+pnpm --filter @dimina-kit/devtools build
+pnpm --filter @dimina-kit/devtools dev
+pnpm --filter @dimina-kit/devtools check-types
+pnpm --filter @dimina-kit/devtools test
+pnpm --filter @dimina-kit/devtools test:e2e
 ```
 
-> 覆盖率：`pnpm test:coverage`（单包）或仓库根 `pnpm test:coverage`（全部包），报告输出到各包 `coverage/`，浏览器打开 `coverage/index.html` 看逐行高亮。
-
----
-
-## 安全说明
-
-本工具仅用于本地开发调试。当前的安全配置：
-
-- **Workbench 窗口**（main / settings / popover overlay）均启用 `contextIsolation` 并禁用 `nodeIntegration`；renderer 通过 main preload 经 `contextBridge` 拿到 `window.devtools.ipc`，每个 IPC handler 经 sender whitelist 校验调用方
-- **Simulator 本体** 是主进程顶层 `WebContentsView`（`nativeSimulatorView`，per-project `persist:miniapp-<key>` partition、无 appId 时回落共享 `persist:simulator`、`nodeIntegration=false`），其 preload 由 `webPreferences.preload = cjsSiblingPreloadPath(ctx.preloadPath)` 在创建时（`attachNativeSimulator`）固定。**小程序的每页代码** 运行在该 WCV 内部 DeviceShell 托管的 render-host `<webview>` guest 里（`nodeIntegration=false`），承载逐页沙箱；guest 不带静态 `partition` 属性，由主进程 `will-attach-webview` 钉到同一 per-project partition，并钉死 contextIsolation/sandbox，渲染进程无法替换
-- **renderer 入口** 启用了保守 CSP；`will-navigate` / `setWindowOpenHandler` 屏蔽外部跳转
-
-仍然不要在 devtools 窗口中加载不受信任的远程内容；本工具不打算在非本地环境部署。
+`dev` 会先完整构建，再启动 renderer、simulator、主进程和 preload 的监听任务，最后打开 Electron。
 
-### MCP Server 风险
+## 安全提醒
 
-内置的 MCP server 默认关闭，由 `startMcpServer` 入口显式启动，或通过 workbench 设置中的 `mcp.enabled` 开启。开启后会在本机监听 SSE 端点，向任何可以连接到该端点的 MCP 客户端暴露一组工具，能力包括：读取 DOM 结构、截屏、拉取网络日志、触发导航等。
+devtools 面向本地开发。不要在它的窗口或宿主扩展中加载不受信任的远程内容。自定义 IPC 应通过 `onSetup(instance)` 提供的 `instance.ipc` 注册；宿主自己创建的窗口还要先调用 `instance.registerTrustedWindow(win)`。更完整的边界见[贡献者指南](./docs/contributing.md#安全边界)。
 
-`workbench_evaluate` 已从 MCP 工具集中移除，workbench 只暴露只读诊断工具（截屏、console 日志、DOM、网络日志等）。`simulator_evaluate` 仍然保留，但小程序页面跑在 render-host `<webview>` guest 里（`nodeIntegration=false`），其 `evaluate` 仅在页面 JS 上下文执行，不具备 Node API 访问能力。
+## License
 
-仅在连接到可信的本机 MCP 客户端或被信任的 AI 工具时启用该功能；不要在公共 WiFi、共享机器或存在远程 SSH 端口转发的场景下开启，以免监听端口被非预期的客户端访问。
+[MIT](../../LICENSE)