@ai_mind/ade-plugin-sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,19 +1,116 @@
-# ADE 插件 SDK
+# ADE 插件 SDK 与接入指南
 
-公开 npm 包 **`@ai_mind/ade-plugin-sdk`**，提供 ADE 插件 API 的自包含 TypeScript 类型、helper 和 `ade-plugin-build`。SDK 当前版本为 **0.1.0**，要求 **ADE 0.45.0 或更新的 0.x 版本**，对应插件 `apiVersion: 1`。
+`@ai_mind/ade-plugin-sdk` 是 ADE 的公开 npm SDK。它提供 TypeScript 类型、插件 helper 和 `ade-plugin-build` 构建器。开发插件不需要获取 ADE 源码。
 
-SDK 与 ADE 的 **major 必须一致**，minor 和 patch 分别发布：SDK `0.x` 面向 ADE `0.x`，SDK `1.x` 面向 ADE `1.x`。major 匹配后，仍需满足 SDK 要求的最低 ADE 版本与插件 `apiVersion`，并确认当前宿主已提供所用功能。插件自身的 `version` 独立管理，下面的 `1.0.0` 是示例插件的版本。
+插件可以增加自己的功能区域、工具按钮、设置组件和聊天 adapter。插件还可以调用 ADE 的文件、项目、worktree 和对话 API。需要 Node.js 时，在插件的 main 入口实现功能。
 
-开发插件无需获取 ADE 源码。安装 Node.js / npm 后，在自己的插件目录中运行：
+本 README 同时是 ADE 内置的插件开发指南。在 ADE 中打开「设置 → 插件 → 开发指南」，即可离线阅读同一份内容。SDK 是开发依赖；用户安装到 ADE 的是你构建的插件包。
+
+## 1. 阅读路线与开发条件
+
+- 首次接入：阅读第 2 节，然后完成第 3 节。
+- 需要 Node.js：完成第 5 节的文件统计示例。
+- 需要扩展界面：阅读第 6 节。
+- 需要插件间协作：阅读第 8 节。
+- 需要接入 agent CLI 或模型 SDK：阅读第 10 节。
+- 准备交付：完成第 12 节与第 14 节。
+- 不使用 TypeScript：使用第 13 节的 JavaScript 示例。
+
+| 开发条件 | 要求 |
+| --- | --- |
+| ADE | 0.46.0 或更新的 0.x 版本；使用 SDK 0.2 的新增接口时需要此版本 |
+| Node.js | 18 或更新版本；用于 npm 安装和构建 |
+| 插件 API | `apiVersion: 1` |
+| SDK | 安装 `@ai_mind/ade-plugin-sdk@0` |
+| React | ADE 提供 React 19 与 ReactDOM；插件共享宿主实例 |
+| 操作系统 | main 使用的命令、路径和原生依赖必须支持用户的平台 |
+
+### 1.1 版本规则
+
+SDK 与 ADE 的 **major 必须相同**。minor 和 patch 分别发布。
+
+| 版本字段 | 含义 | 示例 |
+| --- | --- | --- |
+| SDK npm 版本 | 开发工具和类型的版本 | SDK `0.x` 对应 ADE `0.x` |
+| `plugin.json.adeMajor` | 插件面向的 ADE major | `0` |
+| `plugin.json.apiVersion` | 插件宿主 API 协议版本 | `1` |
+| `plugin.json.version` | 你自己的插件版本 | `1.0.0` |
+
+SDK major 相同不代表所有 ADE minor 都提供相同能力。基础区域和 slot 从 ADE 0.45.0 起提供。SDK 0.2 增加的文件菜单、工作区操作和提示接口要求 ADE 0.46.0 或更新版本。使用以后增加的 API 时，先确认用户的 ADE 提供该 API。
+
+builder 根据已安装 SDK 的 major 写入 `adeMajor`。如果 manifest 已声明不同 major，构建失败。手写 JavaScript 插件也应声明 `adeMajor`。
+
+ADE 在执行入口前检查 `adeMajor` 和 `apiVersion`。不匹配时，插件列表显示错误。旧插件没有 `adeMajor` 时，ADE 保留按 `apiVersion` 检查的兼容行为。
+
+## 2. 插件机制与能力边界
+
+### 2.1 插件如何运行
+
+一个插件是包含 `plugin.json` 的目录。manifest 指定运行文件、配置表单和可选的静态聊天 adapter。
+
+安装时，ADE 将文件复制到用户插件目录。启用时，宿主校验 manifest，加载入口并调用 `activate(ctx)`。入口通过上下文 `ctx` 注册能力。停用时，宿主撤销注册，并执行清理函数。
+
+| 入口 | 运行位置 | 主要职责 |
+| --- | --- | --- |
+| `main` | Electron 主进程 | Node.js、文件处理、进程、网络、聊天 adapter、主进程命令与服务 |
+| `renderer` | ADE 的 React 树 | 功能区域、slot、交互、配置 UI、调用 preload API |
+
+插件可以只声明一个入口。需要 Node.js 和 UI 时，声明两个入口。
+
+main 和 renderer 是两个独立实例。它们不共享变量、服务注册表或事件总线。renderer 通过命令或 preload API 调用 main。跨进程参数和结果必须能被 Electron IPC 序列化。
+
+插件按**可信本地代码**运行。main 保留完整 Node.js 能力。renderer 与 ADE 共享页面和 React。宿主没有为插件提供隔离沙箱。
+
+### 2.2 可以实现哪些功能
+
+| 能力 | 接入点 | 示例 |
+| --- | --- | --- |
+| 独立功能区域 | renderer `registerView` | 看板、搜索、任务列表、数据浏览 |
+| 状态栏组件 | renderer `registerSlot` | 文件状态、连接状态、统计结果 |
+| 文件工具按钮 | `editor.toolbar` slot | 统计文件、复制路径、运行检查 |
+| 插件设置组件 | `settings` slot | 自定义配置表单、连接测试 |
+| 自定义扩展位置 | SDK `Slot` 与 `registerSlot` | 允许其他插件扩展你的工具栏 |
+| 文件树菜单 | renderer `registerFileMenu` | 为目录和文件增加操作 |
+| 编辑器与文件树交互 | renderer `ctx.workspace` | 打开文件、刷新目录、检查未保存状态 |
+| 操作提示 | renderer `ctx.ui.showToast` | 显示结果或带链接的提示 |
+| 文件、项目与 worktree 操作 | renderer `ctx.api`；main 内置服务或 Node.js | 读取文件、创建文件、查询 worktree |
+| 对话与 agent 接入 | main `registerAdapter`；renderer `ctx.api.chat` | agent CLI、模型 SDK、会话工具 |
+| 配置与持久数据 | `getConfig/setConfig`；main `dataPath` | 用户选项、插件缓存 |
+| 插件间调用 | 命令、服务、事件 | 提供可复用功能、通知同进程插件 |
+| 插件样式与资源 | manifest `styles`；renderer `addStyle` | 区域样式、图标、字体 |
+
+### 2.3 当前边界
+
+- 功能区域是 ADE 布局中的 React 区域。注册区域不会创建 Git worktree。
+- 插件区域排在核心区域之后。当前不能用 `registerView` 替换核心编辑器或聊天区域。
+- UI 上下文只提供项目、worktree 和当前文件的路径。它不提供编辑器实例、未保存正文或选区。
+- 读取文件得到磁盘内容。统计未保存草稿需要以后提供的编辑器扩展 API。
+- API 添加项目或创建 worktree，不会自动切换界面的当前选择。
+- 插件没有自动更新、自动编译或开发目录热加载。更新代码后，需要构建并重新安装。
+- 注册聊天 adapter 不会自动创建 daemon/relay provider。
+- ADE 采用可撤销注册和 React 扩展点。DeepSeek Harness 插件需要按本指南移植。
+
+## 3. 快速入门：创建一个 React 功能区域
+
+**目标：**安装后出现「我的插件」区域。点击按钮时，计数从 0 变为 1。
+
+### 步骤 1：创建开发目录
+
+在终端执行：
 
 ```sh
+mkdir my-plugin
+cd my-plugin
 npm init -y
-npm install --save-dev @ai_mind/ade-plugin-sdk@0 @types/react @types/react-dom
+npm install --save-dev @ai_mind/ade-plugin-sdk@0 @types/react@19 @types/react-dom@19
+mkdir src
 ```
 
-`@0` 选择与 ADE `0.x` 对应的 SDK major；使用 ADE `1.x` 时改为 `@1`，并满足对应 SDK 的最低版本要求。
+后续命令均在这个目录执行。
+
+### 步骤 2：保存 manifest
 
-保存 `plugin.json`：
+保存以下内容为 `plugin.json`：
 
 ```json
 {
@@ -27,7 +124,9 @@ npm install --save-dev @ai_mind/ade-plugin-sdk@0 @types/react @types/react-dom
 }
 ```
 
-保存 `src/renderer.tsx`：
+### 步骤 3：保存 renderer 源码
+
+保存以下内容为 `src/renderer.tsx`：
 
 ```tsx
 import { useState } from 'react'
@@ -40,29 +139,1153 @@ export default definePlugin({
       const [count, setCount] = useState(0)
       return <button onClick={() => setCount(count + 1)}>点击计数：{count}</button>
     }
-    ctx.registerView({ id: 'counter', title: '我的插件', component: Counter })
+    ctx.registerView({
+      id: 'counter', title: '我的插件', component: Counter,
+      defaultVisible: true, defaultSize: 22, minSize: 10
+    })
   }
 })
 ```
 
-构建后，在 ADE 的「设置 → 插件」中选择「本地目录」，安装自己的插件目录：
+`definePlugin` 保留传入的插件对象。它不会启动宿主或调用 `activate`。ADE 负责调用入口。
+
+### 步骤 4：构建插件
+
+执行：
 
 ```sh
 npx ade-plugin-build .
 ```
 
-builder 根据 SDK 自身的 major 自动将 `adeMajor` 写入 `plugin.json`。手写 JavaScript 插件也应声明该字段；ADE 拒绝加载跨 major 插件。旧插件未声明 `adeMajor` 时，继续按 `apiVersion` 判断兼容。
+确认目录中出现 `lib/renderer.js`。ADE 加载这个文件，不加载 `src/renderer.tsx`。
+
+### 步骤 5：安装并验证
+
+1. 打开 ADE 的「设置 → 插件」。
+2. 选择「本地目录」。
+3. 选择 `my-plugin` 目录。
+4. 启用插件。
+5. 在「我的插件」区域点击按钮。
+
+预期结果：按钮显示「点击计数：1」。区域可以拖拽调整大小，也可以在「视图」菜单中显示或隐藏。
+
+### 步骤 6：更新代码
+
+1. 修改 `src/renderer.tsx`。
+2. 再次执行 `npx ade-plugin-build .`。
+3. 在 ADE 重新安装同一个目录。
+
+相同插件 ID 会更新已安装副本，并保留配置。仅停用再启用，会继续加载旧副本。
+
+## 4. 目录与 manifest
+
+### 4.1 推荐目录
+
+```text
+my-plugin/
+├── plugin.json
+├── package.json
+├── package-lock.json
+├── src/
+│   ├── renderer.tsx
+│   ├── main.ts             # 需要 Node.js 时添加
+│   └── style.css           # 按需添加
+└── lib/
+    ├── renderer.js         # 构建产物
+    ├── main.cjs            # main 构建产物
+    └── assets/             # 构建生成的资源
+```
+
+源码用于开发。交付包必须包含 manifest 指向的运行文件、样式和资源。
+
+### 4.2 manifest 字段
+
+| 字段 | 类型 | 用途 |
+| --- | --- | --- |
+| `id` | string | 稳定技术标识。新插件显式声明小写 ID，例如 `file-statistics` |
+| `name` | string | 插件管理页的显示名 |
+| `version` | string | 插件自身版本 |
+| `description` | string，可选 | 功能说明 |
+| `apiVersion` | number | 新插件声明 `1` |
+| `adeMajor` | number | 目标 ADE major；当前声明 `0` |
+| `defaultEnabled` | boolean，可选 | 默认启用状态；用户可以修改 |
+| `main` | string，可选 | 主进程 JavaScript 入口 |
+| `renderer` | string，可选 | 渲染进程 JavaScript 入口 |
+| `rendererFormat` | `register` 或 `module` | builder 产物用 `register`；浏览器 ESM 用 `module` |
+| `styles` | string[]，可选 | 随插件加载和移除的 CSS 文件 |
+| `settings` | object，可选 | 自动生成的配置表单，见第 7 节 |
+| `adapters` | array，可选 | 静态终端 adapter，见第 10 节 |
+
+入口和样式路径相对于插件根目录。路径必须留在插件目录内。不要使用 `../` 指向插件外的运行文件。
+
+升级时保持 `id` 不变。配置、命令命名空间和数据目录使用这个 ID。npm 的包名可以带组织前缀；插件 ID 使用自己的小写技术标识。
+
+## 5. 完整接入：main 命令、React UI 与配置
+
+**目标：**增加「文件统计」区域和文件工具按钮。按钮通过 main 读取已保存文件。配置控制字符统计是否包含空白。
+
+这个示例独立于第 3 节。创建新的 `file-statistics` 目录。
+
+### 步骤 1：安装开发依赖
+
+```sh
+mkdir file-statistics
+cd file-statistics
+npm init -y
+npm install --save-dev @ai_mind/ade-plugin-sdk@0 @types/react@19 @types/react-dom@19 @types/node@24
+mkdir src
+```
+
+### 步骤 2：保存 plugin.json
+
+```json
+{
+  "id": "file-statistics",
+  "name": "文件统计",
+  "version": "1.0.0",
+  "apiVersion": 1,
+  "adeMajor": 0,
+  "main": "lib/main.cjs",
+  "renderer": "lib/renderer.js",
+  "rendererFormat": "register",
+  "settings": {
+    "caption": {
+      "type": "string", "label": "状态栏文字", "default": "文件统计"
+    },
+    "includeWhitespace": {
+      "type": "boolean", "label": "统计空白字符", "default": true
+    }
+  }
+}
+```
+
+### 步骤 3：保存 src/main.ts
+
+```ts
+import { readFile } from 'node:fs/promises'
+import { definePlugin } from '@ai_mind/ade-plugin-sdk'
+import type { MainPluginContext } from '@ai_mind/ade-plugin-sdk'
+
+export default definePlugin({
+  activate(ctx: MainPluginContext) {
+    ctx.registerCommand('stats', async (_args, context) => {
+      if (!context.filePath) throw new Error('请先打开一个文本文件')
+      let text: string
+      try {
+        text = await readFile(context.filePath, 'utf8')
+      } catch {
+        throw new Error('无法读取当前文件，请确认文件存在且可读取')
+      }
+      const includeWhitespace = ctx.getConfig().includeWhitespace !== false
+      const counted = includeWhitespace ? text : text.replace(/\s/g, '')
+      return {
+        filePath: context.filePath,
+        lines: text.length === 0 ? 0 : text.split(/\r?\n/).length,
+        characters: [...counted].length,
+        includeWhitespace
+      }
+    })
+  }
+})
+```
+
+`stats` 是插件内部的命令 ID。handler 的第二个参数是调用时的 UI 上下文。没有活动文件时，命令返回中文错误。
+
+这个示例按 Unicode 码点统计字符。行数按换行分段计算；末尾换行会增加一个空行。它读取 UTF-8 文本，不用于图片或其他二进制文件。
+
+### 步骤 4：保存 src/renderer.tsx
+
+```tsx
+import { useEffect, useRef, useState } from 'react'
+import { definePlugin } from '@ai_mind/ade-plugin-sdk'
+import type { PluginComponentProps, RendererPluginContext } from '@ai_mind/ade-plugin-sdk'
+
+interface Statistics {
+  filePath: string
+  lines: number
+  characters: number
+  includeWhitespace: boolean
+}
+
+export default definePlugin({
+  activate(ctx: RendererPluginContext) {
+    function ReadButton({ context }: PluginComponentProps) {
+      const [result, setResult] = useState<Statistics | null>(null)
+      const [error, setError] = useState('')
+      const [busy, setBusy] = useState(false)
+      const mounted = useRef(false)
+      const config = ctx.useConfig()
+
+      useEffect(() => {
+        mounted.current = true
+        return () => { mounted.current = false }
+      }, [])
+
+      async function calculate() {
+        setBusy(true)
+        setError('')
+        try {
+          const next = await ctx.executeCommand('stats') as Statistics
+          if (mounted.current && ctx.getContext().filePath === next.filePath) {
+            setResult(next)
+          }
+        } catch (cause) {
+          if (mounted.current) {
+            setError(cause instanceof Error ? cause.message : '统计失败，请重试')
+          }
+        } finally {
+          if (mounted.current) setBusy(false)
+        }
+      }
+
+      const current = result?.filePath === context.filePath &&
+        result.includeWhitespace === (config.includeWhitespace !== false) ? result : null
+
+      return <span>
+        <button type="button" onClick={calculate} disabled={!context.filePath || busy}>
+          {busy ? '正在统计…' : '统计已保存文件'}
+        </button>
+        {current && <output> {current.lines} 行 · {current.characters} 字符</output>}
+        {error && <span role="alert"> {error}</span>}
+      </span>
+    }
+
+    function Panel(props: PluginComponentProps) {
+      return <section style={{ padding: 16, fontFamily: 'var(--ade-font-sans)' }}>
+        <h2>文件统计</h2>
+        <p>{props.context.filePath ?? '尚未打开文件'}</p>
+        <ReadButton {...props} />
+      </section>
+    }
+
+    ctx.registerView({ id: 'panel', title: '文件统计', component: Panel })
+    ctx.registerSlot('statusBar.right', {
+      id: 'status', component: ({ config }) => <span>{String(config.caption)}</span>
+    })
+    ctx.registerSlot('editor.toolbar', {
+      id: 'calculate', component: ReadButton,
+      when: context => Boolean(context.filePath)
+    })
+  }
+})
+```
+
+React UI 负责显示结果。main 负责文件读取。组件卸载后，异步结果不会更新组件状态。切换文件或修改统计配置后，旧结果不再显示。
+
+### 步骤 5：构建两个入口
+
+```sh
+npx ade-plugin-build . --main-entry src/main.ts
+```
+
+确认 `lib/main.cjs` 和 `lib/renderer.js` 都存在。然后按第 3 节的安装步骤安装 `file-statistics`。
+
+### 步骤 6：验证调用链
+
+1. 在 ADE 打开一个已保存的 UTF-8 文本文件。
+2. 点击「文件统计」区域内的「统计已保存文件」。
+3. 确认区域显示行数和字符数。
+4. 在插件设置中关闭「统计空白字符」。
+5. 保存配置。
+6. 再次点击统计按钮。
+
+预期结果：字符数不再包含空格和换行。修改「状态栏文字」并保存后，状态栏立即显示新文字。
+
+文件工具栏也有同名按钮。点击工具栏按钮时，结果显示在按钮旁。区域和工具栏各自保存自己的统计结果。
+
+### 5.1 命令的路由规则
+
+| 调用 | 执行位置 |
+| --- | --- |
+| renderer `ctx.executeCommand('stats', args)` | 先查本插件 renderer 命令；没有时查本插件 main 命令 |
+| renderer `ctx.executeCommand('plugin:file-statistics:stats', args)` | 指定插件的命令，按同样规则查找 |
+| renderer `ctx.api.plugins.executeCommand(pluginId, command, args, context)` | 直接调用指定插件的 main 命令 |
+
+renderer 和 main 都可以 `registerCommand`。main 上下文没有 `executeCommand`。不要在 main 中复制 renderer 调用代码。
+
+跨进程传普通数据，例如字符串、数字、数组和对象。不要传 React 元素、函数、DOM 节点或 Node.js 实例。
+
+## 6. UI 区域、slot 与上下文
+
+### 6.1 注册功能区域
+
+`ctx.registerView(view)` 返回清理函数。宿主自动管理这个注册。
+
+| view 字段 | 含义 |
+| --- | --- |
+| `id` | 插件内部唯一 ID |
+| `title` | 中文区域标题 |
+| `component` | React 组件，接收 `PluginComponentProps` |
+| `defaultVisible` | 初始可见状态；用户之后可以修改 |
+| `defaultSize` | 初始区域大小，按布局百分比设置 |
+| `minSize` / `maxSize` | 区域大小限制 |
+| `order` | 插件区域排序，数值越小越靠前 |
+
+宿主为区域 ID 加上插件命名空间。不同插件可以使用相同局部 ID。布局由 ADE 保存。
+
+view 没有 `when` 字段。需要空状态时，在组件中检查上下文。用户通过「视图」菜单控制区域可见性。
+
+### 6.2 注册内置 slot
+
+`ctx.registerSlot(name, registration)` 在指定位置追加组件。
+
+| 内置 slot 名称 | 位置 |
+| --- | --- |
+| `statusBar.left` | 状态栏左侧 |
+| `statusBar.right` | 状态栏右侧 |
+| `editor.toolbar` | 当前文件的右上角工具栏 |
+| `settings` | 当前插件的独立设置区域 |
+
+registration 包含 `id`、`component`、可选的 `order` 和 `when(context)`。`when` 返回 false 时，组件不显示。同一 slot 按 `order` 升序排列。顺序相同时，按带命名空间的 ID 排列。
+
+`settings` slot 只显示所选插件自己的组件。它不会把所有插件的设置混在一个页面。
+
+### 6.3 创建自己的 slot
+
+在拥有该位置的 renderer 组件中使用 SDK 的 `Slot`：
+
+```tsx
+import { Slot } from '@ai_mind/ade-plugin-sdk'
+
+export function Toolbar() {
+  return <div><Slot name="file-statistics.toolbar" /></div>
+}
+```
+
+把 `Toolbar` 放入自己的已注册组件。其他插件可以在其 `activate(ctx)` 中追加组件：
+
+```tsx
+ctx.registerSlot('file-statistics.toolbar', {
+  id: 'extra-button', component: () => <button type="button">扩展按钮</button>
+})
+```
+
+后一段是 renderer `activate` 内的代码片段。`Slot` 必须由宿主渲染。它不是独立应用容器。
+
+`Slot` 接收 `name` 和可选的 `pluginId` 过滤条件。它不转发自定义 props。贡献组件仍接收自己的 `{ context, config, api }`。共享额外数据时，使用同进程服务或事件。
+
+### 6.4 读取上下文
+
+```ts
+interface PluginCommandContext {
+  projectPath: string | null
+  worktreePath: string | null
+  filePath: string | null
+}
+```
+
+| 读取方式 | 使用位置 | 行为 |
+| --- | --- | --- |
+| 组件 `props.context` | 已注册组件 | 宿主更新项目、worktree 和文件上下文 |
+| `ctx.useContext()` | React 组件内部 | hook；变化时重新渲染 |
+| `ctx.getContext()` | 点击回调、异步处理 | 获取调用时的最新上下文 |
+| main 命令第二参数 | main handler | 获取命令发起时的上下文快照 |
+
+三个路径都可能是 `null`。在操作前检查需要的路径。hook 只在 React 组件或自定义 hook 中调用。
+
+组件的 `api` 与 renderer 的 `ctx.api` 都是 ADE preload API。renderer 使用该 API 访问本地能力。不要在 renderer 导入 `node:fs` 或使用 `require` 加载 Node.js 模块。
+
+### 6.5 样式
+
+在 `src/renderer.tsx` 导入 `./style.css`。builder 生成 CSS，并追加到 manifest 的 `styles`。
+
+```css
+.file-statistics-panel {
+  padding: 16px;
+  color: var(--ade-text);
+  font-family: var(--ade-font-sans);
+}
+.file-statistics-code {
+  font-family: var(--ade-font-mono);
+}
+```
+
+类名使用插件前缀。宿主主题变量提供颜色和字体。避免全局 `button`、`body` 或 `*` 选择器影响其他区域。
+
+renderer 也可以 `ctx.addStyle(cssText)`。宿主在停用时移除样式。不要直接修改其他功能的 DOM。
+
+### 6.6 文件树菜单
+
+SDK 0.2 可以在 renderer `activate` 中注册文件菜单：
+
+```ts
+ctx.registerFileMenu({
+  id: 'open-local', label: '在 ADE 中打开', order: 10,
+  when: context => context.node.type === 'file',
+  onSelect: async context => {
+    await ctx.workspace.openFile(context.node.path)
+  }
+})
+```
+
+菜单上下文包含 `projectPath`、`worktreePath`、`filePath`，以及 `node`、`isRoot` 和 `selection`。节点提供 `name`、`path`、`type`。`selection` 是打开菜单时的选中项。
+
+`when` 控制是否显示。`enabled` 控制是否可用。宿主先关闭菜单，再执行 `onSelect`。执行前再次检查插件状态和条件。停用插件后，菜单注册自动撤销。
+
+### 6.7 工作区操作与提示
+
+这些接口在 renderer 中使用，不属于 preload IPC：
+
+| 方法 | 结果与边界 |
+| --- | --- |
+| `await ctx.workspace.openFile(path)` | 在 ADE 打开真实存在的文件，返回 boolean。目录和缺失文件不会进入标签页；等待期间切换 worktree 或停用插件时，不打开旧结果 |
+| `await ctx.workspace.refreshTree(directory?)` | 默认刷新当前 worktree。指定目录必须在当前 worktree 内；保留已展开缓存；忽略切换后的旧结果 |
+| `ctx.workspace.isFileDirty(path)` | 返回文件当前是否有未保存修改。操作开始前读取；此方法不是 React hook |
+| `ctx.ui.showToast(message, url?)` | 显示中文提示；可以附结果链接 |
+
+这些接口不暴露编辑器草稿或选区。上传磁盘内容时，先检查 dirty；为 true 时提示用户保存。等待用户选择上传目标后，在真正上传前再次检查。
+
+## 7. 配置与持久数据
+
+### 7.1 声明配置表单
+
+在 manifest 的 `settings` 中声明字段。每个字段使用一个稳定 key。
+
+```json
+{
+  "caption": {
+    "type": "string", "label": "显示文字", "default": "文件统计"
+  },
+  "limit": {
+    "type": "number", "label": "结果数量", "default": 20, "min": 1, "max": 100
+  },
+  "enabled": {
+    "type": "boolean", "label": "显示结果", "default": true
+  },
+  "mode": {
+    "type": "select", "label": "显示模式", "default": "brief",
+    "options": [
+      { "value": "brief", "label": "简洁" },
+      { "value": "full", "label": "完整" }
+    ]
+  }
+}
+```
+
+这段是 `settings` 字段的值，不是完整 manifest。字段还可以声明 `description`。string 字段支持 `multiline` 和 `secret`。
+
+`secret: true` 只遮挡表单输入。配置存储没有因此加密。需要安全凭据存储时，在 main 中集成适当的凭据管理方案。
+
+### 7.2 读取和修改配置
+
+| 方法 | 使用位置 | 行为 |
+| --- | --- | --- |
+| `ctx.getConfig()` | main 或 renderer 回调 | 返回当前配置 |
+| `ctx.useConfig()` | renderer React 组件 | 返回配置，并在变化时重新渲染 |
+| `await ctx.setConfig(patch)` | main 或 renderer | 校验、浅合并并持久化，返回完整配置 |
+| `ctx.onConfigChanged(listener)` | main 或 renderer | 订阅本插件配置；返回清理函数 |
+| 组件 `props.config` | 已注册组件 | 宿主提供本插件的配置 |
+
+main 和 renderer 读取同一份插件配置。表单保存和 `setConfig` 都会通知两侧。不同插件按插件 ID 分开保存配置。
+
+下面的代码放在需要修改配置的异步回调中：
+
+```ts
+await ctx.setConfig({ caption: '新的状态文字' })
+```
+
+只传要修改的字段。未修改字段保留原值。自动表单之外的交互，可以放在 `settings` slot 中。
+
+### 7.3 保存插件数据
+
+main 的 `ctx.pluginPath` 是安装副本目录。`ctx.dataPath` 是插件专属数据目录。宿主在激活前创建数据目录。
+
+缓存、索引和用户数据写入 `dataPath`。不要写入 `pluginPath`；重新安装会替换插件文件。
+
+下面是完整的 main CJS 入口示例。将 manifest 的 `main` 指向 `main.cjs`：
+
+```js
+const fs = require('node:fs/promises')
+const path = require('node:path')
+
+exports.activate = function (ctx) {
+  const target = path.join(ctx.dataPath, 'note.txt')
+  ctx.registerCommand('saveNote', async (args) => {
+    if (typeof args !== 'string') throw new Error('笔记内容必须是文本')
+    try {
+      await fs.writeFile(target, args, 'utf8')
+    } catch {
+      throw new Error('保存插件笔记失败，请检查数据目录是否可写')
+    }
+    return { saved: true }
+  })
+  ctx.registerCommand('readNote', async () => {
+    try {
+      return await fs.readFile(target, 'utf8')
+    } catch (error) {
+      if (error.code === 'ENOENT') return ''
+      throw new Error('读取插件笔记失败')
+    }
+  })
+}
+```
+
+renderer 使用 `ctx.executeCommand('saveNote', text)` 和 `ctx.executeCommand('readNote')`。ADE 卸载插件时删除安装副本，保留插件配置和数据目录。重新安装同 ID 插件可以继续使用它们。不要把插件目录当作数据备份。
+
+## 8. 服务、事件与跨进程调用
+
+### 8.1 同进程服务
+
+服务适合暴露可复用操作。名称使用插件前缀，例如 `file-statistics.reader`。
+
+main `provideService` 接收一个对象。renderer `provideService` 可以接收任意同进程值。两侧的 `getService` 只查询所在进程。
+
+main 中已有以下内置服务：
+
+| 名称 | 常用方法 | 返回形式 |
+| --- | --- | --- |
+| `files` | `readFile(path)`、`readDirTree(dir)`、`statFile(path)`、`writeFile(path, text)` | 这些方法同步返回 |
+| `projects` | `listProjects()`、`addProject(path)`、`removeProject(path)` | 同步返回 |
+| `worktrees` | `listWorktrees(project)`、`createWorktree(project, name)`、`removeWorktree(project, path)` | Promise |
+| `settings` | `getSettings()`、`getSettingsFile()`、`updateSettings(patch)`、`onSettingsChanged(listener)`、`getLegacySettingsFile()` | 设置对象、完整设置文件、原始迁移备份或清理函数 |
+| `app` | `getVersion()`、`getPath('userData' 或 'temp')`、`openExternal(url)` | 版本、应用目录字符串或 Promise |
+| `chat` | `listAdapters()`、`listSessions()`、`listHistory()`、`sendMessage(id, prompt)`、`stop(id)` | 列表同步返回；发送和停止返回 Promise |
+
+main `getService` 返回 `unknown`。先声明所需接口，再检查服务是否存在。下面的片段放在 main `activate` 内：
+
+```ts
+const files = ctx.getService('files') as {
+  readFile(path: string): string
+} | undefined
+if (!files) throw new Error('当前 ADE 未提供文件服务')
+ctx.registerCommand('readSaved', (_args, context) => {
+  if (!context.filePath) throw new Error('请先打开文件')
+  return files.readFile(context.filePath)
+})
+```
+
+main 内置服务与 renderer preload API 的方法名不同。例如 main 用 `files.readFile(path)`，renderer 用 `await ctx.api.files.read(path)`。
+
+`settings.getLegacySettingsFile()` 返回规范化前保存的原始设置副本。核心移出的字段可供插件以后安装时迁移。该备份只用于一次性迁移，不作为新的插件配置存储。插件应校验数据，并用自己的迁移标记避免覆盖用户后续配置。
+
+`settings.getSettingsFile()` 同步返回当前 `AdeSettingsFile`，包含 `settings` 和 `state`。插件迁移旧区域时，可读取 `state.pluginAreasVisible`，先检查用户是否已设置对应区域，再决定是否写入迁移值。
+
+main `files` 服务没有 renderer 的 `watch`、`trash`、`reveal` 或剪贴板方法。main 需要其他本地能力时，使用 Node.js。
+
+### 8.2 renderer 调用 main 服务
+
+以下是完整 main CJS 入口 `main.cjs`：
+
+```js
+const fs = require('node:fs/promises')
+
+exports.activate = function (ctx) {
+  ctx.provideService('file-statistics.reader', {
+    async read(filePath) {
+      if (typeof filePath !== 'string') throw new Error('文件路径必须是文本')
+      try {
+        return await fs.readFile(filePath, 'utf8')
+      } catch {
+        throw new Error('读取文件失败，请确认文件存在且可读取')
+      }
+    }
+  })
+}
+```
+
+将下面的片段放在 renderer 的异步回调中。该插件 manifest 的 `id` 为 `file-statistics`：
+
+```ts
+const context = ctx.getContext()
+if (!context.filePath) throw new Error('请先打开文件')
+const text = await ctx.api.plugins.invokeService(
+  ctx.pluginId, 'file-statistics.reader', 'read', [context.filePath]
+)
+```
+
+`invokeService` 的参数依次为调用方插件 ID、主进程服务名、方法名、参数数组。它返回 Promise。目标服务可以来自其他主进程插件，也可以是内置服务。
+
+可调用方法必须是服务对象自身的函数属性。类原型方法不能直接通过这个桥调用。使用对象方法，或将实例方法显式绑定为对象属性。
+
+命令适合有明确操作名的请求。服务适合提供一组相关操作。两种方式都遵守 IPC 序列化要求。
+
+### 8.3 事件
+
+| 方法 | 总线 |
+| --- | --- |
+| renderer `ctx.on(name, listener)` / `ctx.emit(name, payload)` | 渲染进程 |
+| main `ctx.events.on(name, listener)` / `ctx.events.emit(name, payload)` | 主进程 |
+
+同名事件不会自动跨进程传播。跨进程使用命令或 preload API。
+
+renderer 可以订阅内置 `context:changed`。下面的代码放在 renderer `activate` 中：
+
+```ts
+ctx.on('context:changed', () => {
+  const context = ctx.getContext()
+  console.info('活动文件：', context.filePath)
+})
+```
+
+自定义事件名称加插件前缀。事件用于即时通知，不保存历史，也不代替配置或持久数据。不要依赖某个插件一定先于另一个插件激活。服务可能暂时不存在；必要时提示用户启用依赖插件。
+
+## 9. 生命周期与清理
+
+### 9.1 入口形式
+
+新插件使用命名导出的 `activate(ctx)`，或默认插件对象的 `activate(ctx)`。`activate` 可以返回 Promise，也可以返回一个清理函数。入口可以另外导出 `deactivate()`。
+
+轻量 CJS 使用 `exports.activate = ...`。旧 `register(host)` 仍受支持。不要把 CJS 入口写成 `module.exports = function (...) { ... }`；该形式没有宿主识别的入口方法。
+
+启用后，宿主为插件创建上下文。停用、卸载、重新加载或激活失败时，宿主撤销注册。重新启用会创建新实例。
+
+### 9.2 哪些资源自动清理
+
+区域、slot、命令、服务、事件监听、配置监听和宿主添加的样式由宿主管理。它们通常返回 disposer，便于提前撤销。不要再把这些 disposer 重复放入 `subscriptions`。
+
+main `registerAdapter` 返回 `void`。adapter 归属当前插件。停用插件会撤销 adapter，并停止相关任务；只读历史保留。
+
+插件自己创建的定时器、进程、文件监听和连接需要自行清理。以下片段放在 main 或 renderer 的 `activate` 中：
+
+```ts
+const timer = setInterval(() => {
+  // 更新插件自己的状态。
+}, 1000)
+ctx.effect(() => clearInterval(timer))
+```
+
+`ctx.effect` 接收**清理函数**。它不会执行 setup，也不是 React 的 `useEffect`。也可以把清理函数放入 `ctx.subscriptions`，二选一即可。
+
+组件资源使用 React cleanup。以下是完整 renderer 组件，可作为已注册区域的组件：
+
+```tsx
+import { useEffect, useState } from 'react'
+import type { PluginComponentProps } from '@ai_mind/ade-plugin-sdk'
+
+export function FileRevision({ context, api }: PluginComponentProps) {
+  const [revision, setRevision] = useState(0)
+  useEffect(() => {
+    if (!context.filePath) return
+    return api.files.watch(context.filePath, () => setRevision(value => value + 1))
+  }, [api, context.filePath])
+  return <span>文件变化次数：{revision}</span>
+}
+```
+
+组件卸载或路径变化时，文件订阅解除。网络请求可以用 `AbortController`，并在 cleanup 中调用 `abort()`。
+
+### 9.3 超时与旧上下文
+
+main 的入口加载和激活分别有默认 10 秒等待期限。renderer 激活有等待期限。异步期限不能中断同步死循环。
+
+停用时，main 先关闭上下文并撤销注册，再调用 `deactivate`，最后逆序执行清理函数。main 清理共用 10 秒总期限。超时后宿主仍启动剩余清理项，并继续退出。
+
+不要在清理函数中重新注册资源。已停用实例的异步任务应停止访问旧上下文。给进程和请求设置自己的取消机制。
+
+重启用会重新加载入口，但不保证所有 ESM 依赖都冷加载。更新开发代码时，使用「构建 → 重新安装」流程。
+
+## 10. 接入聊天 adapter
+
+聊天 adapter 在 main 中运行。它负责创建会话、接收输入、输出数据和释放资源。SDK 导出 `ChatAdapter`、`SessionContext`、`ChatSession` 和结构化对话类型。
+
+### 10.1 静态终端 adapter
+
+如果接入一个已安装的交互式 CLI，可以在 manifest 增加以下 `adapters` 字段：
+
+```json
+{
+  "adapters": [
+    {
+      "id": "my-plugin.agent",
+      "label": "我的 Agent",
+      "description": "运行本机已安装的 agent CLI",
+      "kind": "terminal",
+      "command": "my-agent-cli"
+    }
+  ]
+}
+```
+
+这段只展示需要合并的 manifest 字段。将 `my-agent-cli` 替换为真实可执行文件名或路径。安装 CLI 后，再启用插件并创建会话。
+
+`command` 是可执行程序，不是完整 shell 命令。这里没有 `argv` 字段。需要自定义参数、环境或协议时，使用动态 adapter。
+
+静态 manifest 只实现 terminal adapter。静态 `kind: "sdk"` 不会建立 SDK 会话。
+
+### 10.2 动态 adapter 的最小完整入口
+
+下面是 main CJS 入口 `main.cjs`。将 manifest 的 `main` 指向它。这个示例用于验证注册和终端输入输出；它不调用模型。
+
+```js
+exports.activate = function (host) {
+  host.registerAdapter({
+    id: `${host.pluginId}.echo`,
+    label: '回声测试',
+    kind: 'terminal',
+    createSession(session) {
+      let disposed = false
+      session.onData('回声会话已启动\r\n')
+      return {
+        id: session.id,
+        write(data) {
+          if (!disposed) session.onData(data)
+        },
+        resize(_cols, _rows) {},
+        dispose() {
+          if (disposed) return
+          disposed = true
+          session.onExit(0)
+        }
+      }
+    }
+  })
+}
+```
+
+1. 安装并启用插件。
+2. 在新建对话时选择「回声测试」。
+3. 在终端视图输入文本。
+4. 停止会话。
+
+预期结果：输入出现在终端中，停止后会话退出。实际 CLI adapter 应在 `write` 转发输入，在 `resize` 调整终端，在 `dispose` 结束进程。
+
+adapter ID 在 ADE 中全局唯一。建议使用 `<plugin-id>.<adapter-name>`。`shell`、`agent:*`、`daemon:*` 和重复 ID 被宿主保留或拒绝。
+
+### 10.3 会话接口
+
+| 接口成员 | 职责 |
+| --- | --- |
+| `SessionContext.id` | ADE 会话 ID |
+| `cwd` / `worktree` | 会话工作目录与所属 worktree |
+| `projectPath` | 可选项目路径 |
+| `sessionId` / `resume` | provider 会话标识与续接状态 |
+| `config` | 用户选择的会话参数 |
+| `onData(text)` | 输出终端数据 |
+| `onError(error)` | 报告运行错误；消息使用中文 |
+| `onExit(code)` | 报告退出；退出时完成资源释放 |
+| `ChatSession.write(data)` | 接收终端输入 |
+| `ChatSession.resize(cols, rows)` | 接收终端尺寸变化 |
+| `ChatSession.dispose()` | 停止会话并释放资源；可以异步 |
+| `ChatSession.closed` | 可选 Promise；底层会话真正退出后返回退出码 |
+
+### 10.4 模型 SDK 的兼容气泡接口
+
+动态 `kind: "sdk"` 使用 SDK 会话界面。用户输入经 `ChatSession.write` 传入。通过 `onData` 输出换行分隔的 JSON 消息，每行格式为 `{ id?, role?, content }`。
+
+`content` 必须是字符串。`role` 使用 `assistant`、`user` 或 `system`。每条完整 JSON 后追加 `\n`。ADE 将每条消息作为一个已完成气泡记录；这不是 token 增量事件协议。
+
+以下是完整的 main CJS 测试入口。它验证 SDK 气泡通道，不调用模型：
+
+```js
+exports.activate = function (host) {
+  host.registerAdapter({
+    id: `${host.pluginId}.sdk-echo`,
+    label: 'SDK 气泡测试',
+    kind: 'sdk',
+    createSession(session) {
+      let disposed = false
+      return {
+        id: session.id,
+        write(data) {
+          if (disposed) return
+          const content = `收到：${data.trimEnd()}`
+          session.onData(JSON.stringify({ role: 'assistant', content }) + '\n')
+        },
+        resize(_cols, _rows) {},
+        dispose() {
+          if (disposed) return
+          disposed = true
+          session.onExit(0)
+        }
+      }
+    }
+  })
+}
+```
 
-React 与 ReactDOM 由 ADE 提供，构建时不会打进插件。构建只发生在插件开发阶段；用户安装的插件必须包含 `plugin.json` 指向的 JavaScript 文件，ADE 不会自动编译 TypeScript 或执行安装脚本。
+安装并启用后，新建「SDK 气泡测试」会话。发送「你好」。预期结果：显示用户消息和「收到：你好」回复。实际模型接入时，在 `write` 中调用 provider，再按这个协议输出完整回复。释放或取消请求的逻辑由 adapter 实现。
 
-本地目录安装会复制文件。修改代码并重新构建后，在 ADE 重新安装同一个目录；相同插件 ID 会更新副本并保留配置。
+这个路径不需要 `chat.startTurn`。当前 SDK 界面使用 `write` 输入；不要将 `kind: "sdk"` 与 `chat.startTurn` 组合成原生结构化聊天路径。
 
-完整教程已内置在 ADE 的「设置 → 插件 → 开发指南」，支持离线阅读和复制代码。无需 SDK 的 JavaScript 示例和 main、设置、slots、命令、服务及清理规则都在指南中；内置「工作区工具」可在插件管理中启用体验。仓库维护的同一份教程位于 `docs/plugins.md`。
+### 10.5 原生结构化聊天
 
-需要离线开发包时，点击指南顶部「导出 SDK」，用实际文件路径安装：
+需要流式事件、工具、用量、审批和聊天/终端切换时，使用 `kind: "terminal"` 并实现 `chat.startTurn(ctx, options)`。每轮由 ADE 调用一次。通过 `StructuredSessionContext.onEvent` 发送 `StructuredEvent`。轮次结束时调用 `onExit`。仍需提供 `createSession` 和返回的会话接口。
+
+| 可选扩展 | 用途 |
+| --- | --- |
+| `chat.preassignedSessionId` / `prepareSession` | 分配 provider 会话标识 |
+| `chat.readHistory` / `discoverSessions` | 读取和发现 provider 原生历史 |
+| `chat.steer` | 对正在执行的轮次追加指令 |
+| `chat.respond` | 回复审批或用户输入请求 |
+| `chat.detach` / `disposeSession` | 释放 provider 连接或会话资源 |
+| `chat.attachmentKinds` | 声明支持的附件类型 |
+| `loadOptions` / `listModelsArgs` / `parseModels` | 提供模型和选项 |
+| `excludedOptions` | 隐藏被协议自身管理的 CLI 参数 |
+
+不同 provider 的续接、取消、审批和附件协议不同。按 SDK 的 `ChatTurnOptions`、`StructuredEvent` 和 `ChatApprovalResponse` 类型实现这些操作。不要把 provider 原始输出直接当成 ADE 结构化事件。
+
+## 11. SDK 构建器与运行依赖
+
+### 11.1 构建命令
+
+| 命令 | 行为 |
+| --- | --- |
+| `npx ade-plugin-build .` | 构建默认 `src/renderer.tsx` 到 manifest 的 `renderer` |
+| `npx ade-plugin-build . --entry src/panel.tsx` | 改用指定 renderer 源码 |
+| `npx ade-plugin-build . --main-entry src/main.ts` | 同时构建 main 到 manifest 的 `main` |
+
+builder 转译和打包源码。它不执行 TypeScript 类型检查。需要类型检查时，在开发目录安装 TypeScript：
 
 ```sh
-npm install --save-dev /绝对路径/ai_mind-ade-plugin-sdk-0.1.0.tgz @types/react @types/react-dom
+npm install --save-dev typescript
 ```
 
-`.tgz` 包含 SDK 本身；首次安装仍需依赖缓存或网络来取得构建器和 React 类型。宿主保留旧离线包的 `@ade/plugin-sdk` 和开发阶段的 `@ai_mind/plugin-sdk` 模块别名，兼容已有包与预构建插件；新项目从 npm 安装正式包 `@ai_mind/ade-plugin-sdk`。
+保存 `tsconfig.json`：
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"]
+}
+```
+
+执行 `npx tsc --noEmit`。通过后再构建和分发。main 使用 Node.js 类型时，安装 `@types/node@24`。
+
+当前 builder 要求有效 renderer 入口和 `rendererFormat: "register"`。`--main-entry` 是附加构建参数，不是 main-only 模式。main-only 插件可以直接交付第 7、8 或 10 节的 CJS；TypeScript main-only 需要自行配置构建。
+
+### 11.2 React 与 renderer 格式
+
+`register` 格式是 SDK builder 的产物。ADE 用 script 注册模块工厂。构建保留宿主的 React、ReactDOM 和 SDK 模块，不把第二份 React 打入插件。
+
+其他浏览器依赖会被打入 bundle。不要调用 `createRoot` 接管 ADE 容器。使用宿主注册的组件和 slot。
+
+`module` 格式用于预构建浏览器 ESM。它可以直接导出 `activate`。浏览器不能直接解析 npm 裸模块名。使用 `ctx.React`，或预先打包其他依赖。第 13 节提供完整示例。
+
+宿主保留 `@ade/plugin-sdk` 和 `@ai_mind/plugin-sdk` 两个旧模块别名。新项目使用正式名称 `@ai_mind/ade-plugin-sdk`。
+
+### 11.3 main 依赖与资源
+
+main 构建生成 CJS，目标为 Node.js 24。Node.js 内置模块保留，`electron` 保留为外部模块。一般 JavaScript 依赖会被打包。
+
+动态加载、原生模块和额外数据文件可能需要单独交付。原生模块必须匹配 ADE 使用的 Electron ABI、平台和 CPU 架构。用户安装时不会运行原生编译脚本。
+
+CSS 导入会生成样式文件。支持的图片和字体导入写入产物的 `assets` 目录。生成的资源使用 `ade-plugin://` 地址。分发时保留这些资源；不要只复制入口 JS。
+
+### 11.4 使用导出的 SDK 包
+
+在 ADE 开发指南顶部点击「导出 SDK」。将包保存到本地。然后在插件开发目录执行：
+
+```sh
+npm install --save-dev '/绝对路径/导出的-sdk.tgz' @types/react@19 @types/react-dom@19
+```
+
+替换为真实文件路径。导出的 `.tgz` 包含 SDK 本身。首次安装构建器依赖和 React 类型时，仍需要网络或已有 npm 缓存。
+
+## 12. 分发、安装与升级
+
+### 12.1 四种安装来源
+
+| 来源 | 用户操作 | 作者交付内容 |
+| --- | --- | --- |
+| 本地目录 | 选择包含 `plugin.json` 的目录 | 已构建的插件目录 |
+| ZIP | 选择插件 ZIP 文件 | manifest、JavaScript、CSS、资源和运行依赖 |
+| npm | 输入包名，可指定版本 | 带运行产物的 npm 包 |
+| Git | 输入插件 Git 仓库来源 | 仓库中已提交的运行产物 |
+
+npm/Git 安装生产依赖时跳过 scripts 和 devDependencies。ADE 不执行 `prepare`、`postinstall` 或 TypeScript 构建。目录/ZIP 安装不下载依赖。
+
+安装 npm 来源需要本机有 npm。Git 来源需要 Git；有生产依赖时也需要 npm。网络来源需要能够访问对应仓库和 registry。
+
+main 使用未打包依赖时，npm/Git 包需要在 `dependencies` 中声明它们。目录/ZIP 包需要附带可运行的依赖，或预先打包。renderer 的浏览器依赖应在发布前打入 bundle。
+
+### 12.2 打包 ZIP
+
+1. 构建插件。
+2. 检查 manifest 中的每个入口和样式文件。
+3. 将 `plugin.json`、`lib` 和其他运行文件放在交付目录。
+4. 将交付目录压缩为 ZIP。
+5. 在一个新用户配置中安装该 ZIP。
+
+`plugin.json` 放在 ZIP 根目录，或唯一顶级插件文件夹中。宿主不会继续搜索更深目录。ZIP 不接受符号链接，最多包含 20,000 个条目，解压内容最多 512 MiB。不要把 SDK 的 `.tgz` 当作你的插件 ZIP。
+
+### 12.3 发布自己的 npm 插件包
+
+SDK npm 包与插件 npm 包是两个包。为插件选择自己的包名。以下是文件统计插件的 `package.json` 示例：
+
+```json
+{
+  "name": "ade-file-statistics-example",
+  "version": "1.0.0",
+  "description": "ADE 文件统计插件",
+  "files": ["plugin.json", "lib", "README.md"],
+  "scripts": {
+    "build": "ade-plugin-build . --main-entry src/main.ts"
+  },
+  "devDependencies": {
+    "@ai_mind/ade-plugin-sdk": "^0.1.1",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0"
+  }
+}
+```
+
+包名只是示例。发布时使用你有权限的 npm 用户或组织名。将所有额外运行资源加入 `files`。
+
+在已完成 npm 登录的开发机执行：
+
+```sh
+npm run build
+npm pack --dry-run
+npm pack
+```
+
+先检查打包清单。确认入口和资源都在包中。验证生成的包后，再执行：
+
+```sh
+npm publish --access public
+```
+
+用户在 ADE 的 npm 安装输入框中填写你的插件包名。例如 `ade-file-statistics-example@1.0.0`。用户不需要安装 SDK。
+
+### 12.4 Git 交付与更新
+
+Git 仓库必须包含 `plugin.json` 和已构建产物。使用 HTTPS 或 SSH 仓库地址。ADE 克隆默认分支；当前没有单独选择分支或 commit 的安装参数。不要只提交 `src`，然后依赖安装时构建。
+
+修改代码后，更新插件自身 `version` 并重新构建。用相同 `id` 安装新目录、ZIP、npm 包或 Git 来源。ADE 替换副本并保留插件配置。
+
+插件没有自动更新流程。作者应在插件 README 写清安装来源、最低 ADE 版本、外部 CLI 要求和升级方式。
+
+### 12.5 停用与卸载
+
+停用会撤销注册并释放资源，安装副本和配置保留。再次启用会创建新实例。
+
+卸载会删除用户插件的安装副本，保留配置和 `dataPath`。内置插件可以停用，不能由用户插件覆盖或卸载。
+
+## 13. 无需 SDK 的快速入门
+
+这个例子不需要下载依赖、安装 SDK 或编译。它增加一个区域、一个状态栏组件和一个文件工具按钮。
+
+### 步骤 1：创建目录和 manifest
+
+创建 `my-first-plugin` 目录。保存 `plugin.json`：
+
+```json
+{
+  "id": "my-first-plugin",
+  "name": "我的第一个插件",
+  "version": "1.0.0",
+  "apiVersion": 1,
+  "adeMajor": 0,
+  "renderer": "renderer.js",
+  "rendererFormat": "module",
+  "settings": {
+    "caption": { "type": "string", "label": "显示文字", "default": "你好，ADE" }
+  }
+}
+```
+
+### 步骤 2：保存 renderer.js
+
+```js
+export function activate(ctx) {
+  const React = ctx.React
+
+  function Greeting({ context, config }) {
+    const [count, setCount] = React.useState(0)
+    return React.createElement('section', {
+      style: { padding: 16, fontFamily: 'var(--ade-font-sans)' }
+    },
+      React.createElement('h2', null, config.caption),
+      React.createElement('p', null, context.worktreePath || '尚未选择 worktree'),
+      React.createElement('button', {
+        type: 'button', onClick: () => setCount(count + 1)
+      }, `点击计数：${count}`)
+    )
+  }
+
+  function Status({ config }) {
+    return React.createElement('span', null, config.caption)
+  }
+
+  function CopyFile({ context, api }) {
+    const [label, setLabel] = React.useState('复制文件路径')
+    async function copy() {
+      try {
+        await api.app.copyText(context.filePath)
+        setLabel('已复制')
+      } catch {
+        setLabel('复制失败，请重试')
+      }
+    }
+    return React.createElement('button', {
+      type: 'button', onClick: copy, disabled: !context.filePath
+    }, label)
+  }
+
+  ctx.registerView({
+    id: 'greeting', title: '我的插件', component: Greeting,
+    defaultSize: 22, minSize: 10
+  })
+  ctx.registerSlot('statusBar.right', { id: 'status', component: Status })
+  ctx.registerSlot('editor.toolbar', {
+    id: 'copy-file', component: CopyFile,
+    when: context => Boolean(context.filePath)
+  })
+}
+```
+
+### 步骤 3：安装并验证
+
+1. 在 ADE 的插件设置中选择「本地目录」。
+2. 安装 `my-first-plugin`。
+3. 启用插件。
+4. 点击区域中的计数按钮。
+5. 打开一个文件。
+6. 点击文件工具栏的「复制文件路径」。
+7. 修改插件设置中的「显示文字」并保存。
+
+预期结果：计数增加，文件路径写入剪贴板，区域和状态栏显示新的配置文字。
+
+## 14. 排错与交付验证
+
+### 14.1 常见问题
+
+| 现象 | 检查与处理 |
+| --- | --- |
+| 插件列表显示入口不存在 | 确认已构建；确认交付包包含 manifest 指向的 JS |
+| API 或 ADE 版本不匹配 | 检查 `apiVersion: 1`、`adeMajor` 与最低 ADE 版本 |
+| 修改代码后没有变化 | 重新构建，再重新安装开发目录；停用再启用不会更新副本 |
+| 区域没有出现 | 检查插件已启用；检查「视图」菜单中的区域开关 |
+| slot 没有出现 | 检查名称、`when` 条件和当前位置是否渲染；settings 只显示所选插件 |
+| hook 错误或 Invalid hook call | 使用 SDK builder，共享宿主 React；移除自行打包的 React |
+| renderer 无法导入 Node.js | 把本地操作移到 main，通过命令调用 |
+| module 无法解析 npm 包名 | 使用 `ctx.React`，或改为 builder 的 `register` 产物 |
+| 命令找不到 | 检查注册入口、插件启用状态、局部 ID 和跨插件命名空间 |
+| main 服务在 renderer 中取不到 | 两侧注册表独立；使用 `api.plugins.invokeService` |
+| 服务方法不可调用 | 方法必须是对象自身的函数属性；不要直接暴露类原型 |
+| 事件没有传到另一进程 | 事件总线不跨进程；使用命令或 preload API |
+| 配置更新后结果仍旧 | 用 props 或 `useConfig` 读取；避免把初始配置永久缓存 |
+| 字符统计与编辑器内容不同 | 示例读取磁盘；先保存文件，再统计 |
+| 安装后依赖找不到 | 检查已打包依赖或运行 dependencies；安装不会执行构建脚本 |
+| 原生模块加载失败 | 检查 Electron ABI、平台和架构；预先构建并交付 |
+| 停用后仍有任务输出 | 清理进程、定时器、监听和连接；取消未完成请求 |
+| SDK 气泡没有回复 | 检查 `kind: "sdk"`、`write` 和 `onData` 的换行 JSON 消息；不要混用原生 chat 路径 |
+| terminal adapter 没有聊天视图 | 实现 `chat.startTurn` 和 `onEvent` 结构化事件 |
+
+先查看插件管理中的状态和错误。main 用 `ctx.log('info' | 'warn' | 'error', message)` 记录插件日志。renderer 可以通过 `ctx.api.logs.list(filter)` 查询 ADE 日志。
+
+出现用户可见错误时，使用中文说明失败原因和下一步。不要把完整凭据写入日志。
+
+### 14.2 插件作者的交付检查
+
+按顺序执行以下检查：
+
+1. 在没有项目、worktree 和文件时启用插件。
+2. 选择项目，再打开和切换文件。
+3. 执行插件的主要操作。
+4. 修改配置并保存。
+5. 重启 ADE，检查配置恢复。
+6. 隐藏并重新显示插件区域。
+7. 连续停用、启用插件三次。
+8. 在异步任务执行期间停用插件。
+9. 重新安装同 ID 的新版本。
+10. 在独立用户配置中安装最终分发包。
+
+检查结果：无白屏，无重复组件，无残留任务。空上下文有清楚的提示。失败消息为中文。配置和升级行为与插件说明一致。
+
+如果插件读写文件、启动进程或调用远程服务，还要验证权限失败、目标不存在、网络失败和取消操作。实际 CLI 或模型 adapter 还要验证续接、停止和历史恢复。
+
+## 15. API 速查
+
+以下内容用于定位 API。完整参数和返回类型随 SDK 发布。编辑器可以直接补全，不需要 ADE 源码。
+
+### 15.1 renderer 上下文
+
+| 成员 | 用途 |
+| --- | --- |
+| `pluginId` | 当前插件 ID |
+| `React` / `ReactDOM` | 宿主模块实例 |
+| `api` | ADE preload API，见下表 |
+| `getContext` / `useContext` | 读取 UI 路径上下文 |
+| `getConfig` / `useConfig` / `setConfig` / `onConfigChanged` | 读取、修改和订阅配置 |
+| `registerView` / `registerSlot` | 注册区域与扩展组件 |
+| `registerFileMenu` | 注册文件树菜单，自动随插件清理 |
+| `workspace` | 打开文件、刷新文件树、读取 dirty 状态 |
+| `ui.showToast` | 操作提示与结果链接 |
+| `registerCommand` / `executeCommand` | 注册与调用命令 |
+| `provideService` / `getService` | 同进程服务 |
+| `on` / `emit` | 同进程事件 |
+| `addStyle` | 添加自动清理的 CSS |
+| `effect` / `subscriptions` | 登记自己的资源清理 |
+
+### 15.2 main 上下文
+
+| 成员 | 用途 |
+| --- | --- |
+| `pluginId` / `pluginPath` / `dataPath` | 插件标识、安装目录、数据目录 |
+| `registerAdapter` | 注册聊天 adapter |
+| `registerCommand` | 注册 main 命令 |
+| `provideService` / `getService` | 主进程服务 |
+| `events.on` / `events.emit` | 主进程事件 |
+| `getConfig` / `setConfig` / `onConfigChanged` | 读取、修改和订阅配置 |
+| `log` | 记录插件日志 |
+| `effect` / `subscriptions` | 登记资源清理 |
+
+main 没有 renderer 的 `api`、hook、区域或 slot 方法。
+
+### 15.3 ADE preload API
+
+绝大多数操作返回 Promise。订阅方法返回解除订阅函数。调用前查看 SDK 中的精确签名。
+
+| 命名空间 | 主要能力与方法 |
+| --- | --- |
+| `api.projects` | `list/add/remove/touch`；目录和 Markdown 文件选择 |
+| `api.worktrees` | `list/create/remove` |
+| `api.files` | `tree/read/readBinary/write/stat/isMarkdown`；创建、重命名、复制、回收站；文件监听、系统剪贴板、系统打开与定位 |
+| `api.chat` | adapter 查询；新建、输入、调整尺寸、发送消息、切换视图、停止、取消；历史、选项、模型、附件、审批；事件订阅 |
+| `api.app` | 版本、复制文本、关闭窗口、下载页、检查与安装 ADE 更新、更新状态 |
+| `api.settings` | 读取与修改 ADE 设置、agent 列表、设置变化订阅 |
+| `api.plugins` | 插件列表、配置、安装、启停、卸载与变更订阅；SDK 导出、main 命令和服务调用 |
+| `api.daemon` | daemon 信息与 relay 配置 |
+| `api.aone` | Aone 看板与工作项操作；需要相应账号配置 |
+| `api.logs` | 日志查询、scope 列表、清空、目录和摘要 |
+
+调用写操作会产生实际效果。例如 `files.write` 修改磁盘，`chat.sendMessage` 发送消息。插件应在自己的交互中清楚表达操作目标。
+
+ADE 0.46 起，钉钉业务由独立插件提供，SDK 不再声明 `api.dingtalk`。业务插件通过自己的 main 服务与 React 区域接入；其他插件经 `api.plugins.invokeService` 调用其公开服务。
+
+下面的 renderer 回调片段读取当前已保存文件：
+
+```ts
+const context = ctx.getContext()
+if (!context.filePath) throw new Error('请先打开文件')
+const savedText = await ctx.api.files.read(context.filePath)
+```
+
+### 15.4 类型文件
+
+安装后，这些文件位于 `node_modules/@ai_mind/ade-plugin-sdk/`：
+
+| 文件 | 内容 |
+| --- | --- |
+| `index.d.ts` | renderer 上下文、组件 props、helper 与所有公共类型导出 |
+| `types/plugins.d.ts` | manifest、配置、区域、上下文与 disposer |
+| `types/api.d.ts` | 完整 ADE preload API |
+| `types/adapter.d.ts` | main 上下文、adapter、会话与轮次 |
+| `types/ade-types.d.ts` | 项目、worktree、文件、聊天消息和结构化事件等共享类型 |
+
+从 SDK 根模块导入类型即可：
+
+```ts
+import type {
+  AdeApi, MainPluginContext, RendererPluginContext,
+  PluginComponentProps, ChatAdapter, StructuredEvent
+} from '@ai_mind/ade-plugin-sdk'
+```
+
+## 16. 本指南的写作规则
+
+本指南参考 ASD-STE100 Issue 9 的技术写作原则：固定术语、短句、主动表达、一个句子一个操作，并在步骤前说明条件。中文内容采用这些可迁移的原则。代码、API 名称和领域术语保留原文。[标准说明](https://www.asd-ste100.org/about_STE.html)、[程序写作规则](https://www.asd-ste100.org/assets/files/ASD-STE100_ISSUE9.pdf)。
+
+“80%”是本指南的写作目标。ASD-STE100 是英语标准，英语受控词表和单词数不能直接用于中文。因此，本指南不声称经过正式的 STE 符合率认证。
+
+后续维护按同一规则：先说明目标与前提，再给出操作，最后写明可观察的结果。完整示例标出文件路径。局部代码明确标出放置位置。能力说明同时写出运行位置和限制。