@ai_mind/ade-plugin-sdk 0.1.1 → 0.2.1

package/README.md

@@ -18,7 +18,7 @@
 
 | 开发条件 | 要求 |
 | --- | --- |
-| ADE | 0.45.0 或更新的 0.x 版本 |
+| ADE | 0.46.0 或更新的 0.x 版本；使用 SDK 0.2 的新增接口时需要此版本 |
 | Node.js | 18 或更新版本；用于 npm 安装和构建 |
 | 插件 API | `apiVersion: 1` |
 | SDK | 安装 `@ai_mind/ade-plugin-sdk@0` |
@@ -36,7 +36,7 @@ SDK 与 ADE 的 **major 必须相同**。minor 和 patch 分别发布。
 | `plugin.json.apiVersion` | 插件宿主 API 协议版本 | `1` |
 | `plugin.json.version` | 你自己的插件版本 | `1.0.0` |
 
-SDK major 相同不代表所有 ADE minor 都提供相同能力。这个指南中的功能要求 ADE 0.45.0 或更新版本。使用以后增加的 API 时，先确认用户的 ADE 提供该 API。
+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`。
 
@@ -70,6 +70,9 @@ main 和 renderer 是两个独立实例。它们不共享变量、服务注册
 | 文件工具按钮 | `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` | 用户选项、插件缓存 |
@@ -79,7 +82,7 @@ main 和 renderer 是两个独立实例。它们不共享变量、服务注册
 ### 2.3 当前边界
 
 - 功能区域是 ADE 布局中的 React 区域。注册区域不会创建 Git worktree。
-- 插件区域排在核心区域之后。当前不能用 `registerView` 替换核心编辑器或聊天区域。
+- 插件区域与核心区域使用同一布局。用户可以移动插件区域。`registerView` 不能替换核心编辑器或聊天组件。
 - UI 上下文只提供项目、worktree 和当前文件的路径。它不提供编辑器实例、未保存正文或选区。
 - 读取文件得到磁盘内容。统计未保存草稿需要以后提供的编辑器扩展 API。
 - API 添加项目或创建 worktree，不会自动切换界面的当前选择。
@@ -414,14 +417,31 @@ renderer 和 main 都可以 `registerCommand`。main 上下文没有 `executeCom
 | `title` | 中文区域标题 |
 | `component` | React 组件，接收 `PluginComponentProps` |
 | `defaultVisible` | 初始可见状态；用户之后可以修改 |
-| `defaultSize` | 初始区域大小，按布局百分比设置 |
-| `minSize` / `maxSize` | 区域大小限制 |
-| `order` | 插件区域排序，数值越小越靠前 |
+| `defaultSize` | 首次放置时参考的相对大小；不会覆盖用户保存的大小 |
+| `minSize` / `maxSize` | 旧单行布局的尺寸字段；继续接受，但 ADE 0.47 起不作为停靠布局的硬限制 |
+| `order` | 首次新增插件区域时的排列顺序，数值越小越靠前；不会重排已有区域 |
 
-宿主为区域 ID 加上插件命名空间。不同插件可以使用相同局部 ID。布局由 ADE 保存。
+宿主为区域 ID 加上插件命名空间。不同插件可以使用相同局部 ID。请保持区域 `id` 不变。用户保存的位置与这个 ID 关联。
 
 view 没有 `when` 字段。需要空状态时，在组件中检查上下文。用户通过「视图」菜单控制区域可见性。
 
+**ADE 0.47 起的区域布局：**项目、worktree、目录、编辑、对话、Aone 看板和插件区域使用同一停靠布局。项目与 worktree 是两个独立区域。用户可以调整每个区域的位置、顺序和大小。插件无需增加布局接口。按 SDK 0.2 开发的区域可以直接使用这个布局。
+
+| 用户操作 | 操作方法 |
+| --- | --- |
+| 移动并分屏 | 拖拽区域标签到目标区域的左侧、右侧、上方或下方，确认预览后松开 |
+| 合并为标签页 | 拖拽区域标签到目标区域的中间或标签栏 |
+| 调整标签顺序 | 在同一标签栏中拖拽标签到所需位置 |
+| 调整大小 | 拖拽区域之间的分隔线 |
+| 隐藏或显示区域 | 点击区域标签的隐藏按钮，或使用标题栏「视图」菜单 |
+| 恢复默认布局 | 打开「视图 → 恢复默认布局」，恢复区域的位置、顺序和大小；保留显示开关 |
+
+ADE 自动保存分屏结构、标签顺序和区域大小。重新打开 ADE 后恢复布局。布局在全 ADE 共用，切换项目或 worktree 不会切换布局。停用插件时，ADE 保留区域的位置记录。重新启用插件后，区域恢复到保存的位置。
+
+`defaultSize` 和 `order` 只用于首次放置。更新配置、重新安装插件或修改这些声明，不会强制重排用户已有的区域。`minSize` 和 `maxSize` 保留给旧客户端使用。新停靠布局允许用户自由调整大小，不把这些旧百分比作为限制。当前不提供浮动区域或独立窗口。
+
+不要假定插件区域始终在右侧。让组件适应不同的宽度和高度。内容过长时，在区域内提供滚动。区域移动、标签切换和最大化不应触发新的业务任务。用户隐藏区域或停用插件时，组件可能卸载。持久业务数据按第 7 节保存。资源按第 9 节清理。
+
 ### 6.2 注册内置 slot
 
 `ctx.registerSlot(name, registration)` 在指定位置追加组件。
@@ -501,6 +521,37 @@ interface PluginCommandContext {
 
 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 声明配置表单
@@ -603,8 +654,8 @@ 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()`、`updateSettings(patch)`、`onSettingsChanged(listener)` | 设置对象或清理函数 |
-| `app` | `getVersion()`、`openExternal(url)` | 版本字符串或 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` 内：
@@ -622,6 +673,10 @@ ctx.registerCommand('readSaved', (_args, context) => {
 
 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 服务
@@ -1170,6 +1225,9 @@ export function activate(ctx) {
 | `getContext` / `useContext` | 读取 UI 路径上下文 |
 | `getConfig` / `useConfig` / `setConfig` / `onConfigChanged` | 读取、修改和订阅配置 |
 | `registerView` / `registerSlot` | 注册区域与扩展组件 |
+| `registerFileMenu` | 注册文件树菜单，自动随插件清理 |
+| `workspace` | 打开文件、刷新文件树、读取 dirty 状态 |
+| `ui.showToast` | 操作提示与结果链接 |
 | `registerCommand` / `executeCommand` | 注册与调用命令 |
 | `provideService` / `getService` | 同进程服务 |
 | `on` / `emit` | 同进程事件 |
@@ -1205,12 +1263,13 @@ main 没有 renderer 的 `api`、hook、区域或 slot 方法。
 | `api.settings` | 读取与修改 ADE 设置、agent 列表、设置变化订阅 |
 | `api.plugins` | 插件列表、配置、安装、启停、卸载与变更订阅；SDK 导出、main 命令和服务调用 |
 | `api.daemon` | daemon 信息与 relay 配置 |
-| `api.dingtalk` | 钉钉文档、会议内容与文件上传下载；需要相应账号配置 |
 | `api.aone` | Aone 看板与工作项操作；需要相应账号配置 |
 | `api.logs` | 日志查询、scope 列表、清空、目录和摘要 |
 
 调用写操作会产生实际效果。例如 `files.write` 修改磁盘，`chat.sendMessage` 发送消息。插件应在自己的交互中清楚表达操作目标。
 
+ADE 0.46 起，钉钉业务由独立插件提供，SDK 不再声明 `api.dingtalk`。业务插件通过自己的 main 服务与 React 区域接入；其他插件经 `api.plugins.invokeService` 调用其公开服务。
+
 下面的 renderer 回调片段读取当前已保存文件：
 
 ```ts

package/index.d.ts

@@ -3,7 +3,8 @@ import type * as ReactDOM from 'react-dom'
 import type { AdeApi } from './types/api.js'
 import type { PluginContext, SessionContext, ChatSession, ChatAdapter } from './types/adapter.js'
 import type {
-  PluginCommandContext, PluginConfig, PluginDisposer, PluginSlotName, PluginViewInfo
+  PluginCommandContext, PluginConfig, PluginDisposer, PluginFileMenuRegistration,
+  PluginSlotName, PluginUiApi, PluginViewInfo, PluginWorkspaceApi
 } from './types/plugins.js'
 
 export type * from './types/plugins.js'
@@ -35,6 +36,8 @@ export interface RendererPluginContext {
   React: typeof React
   ReactDOM: typeof ReactDOM
   api: AdeApi
+  workspace: PluginWorkspaceApi
+  ui: PluginUiApi
   subscriptions: PluginDisposer[]
   getContext(): PluginCommandContext
   useContext(): PluginCommandContext
@@ -44,6 +47,7 @@ export interface RendererPluginContext {
   onConfigChanged(listener: (config: PluginConfig) => void): PluginDisposer
   registerView(view: PluginViewRegistration): PluginDisposer
   registerSlot(name: PluginSlotName, contribution: PluginSlotRegistration): PluginDisposer
+  registerFileMenu(contribution: PluginFileMenuRegistration): PluginDisposer
   registerCommand(id: string, handler: (args: unknown, context: PluginCommandContext) => unknown | Promise<unknown>): PluginDisposer
   /** 优先执行本插件 renderer 命令，其次执行本插件 main 命令；跨插件使用 plugin:ID:command。 */
   executeCommand(id: string, args?: unknown): Promise<unknown>

package/package.json

@@ -1,23 +1,47 @@
 {
   "name": "@ai_mind/ade-plugin-sdk",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "ADE 可信插件 SDK、类型与 React 插件构建工具",
   "license": "MIT",
   "author": "sepmini",
-  "engines": { "node": ">=18" },
-  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "type": "module",
   "main": "./index.mjs",
   "types": "./index.d.ts",
-  "exports": { ".": { "types": "./index.d.ts", "default": "./index.mjs" } },
-  "bin": { "ade-plugin-build": "./cli/build.mjs" },
-  "files": ["index.mjs", "index.d.ts", "types", "cli", "README.md", "LICENSE"],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.mjs"
+    }
+  },
+  "bin": {
+    "ade-plugin-build": "./cli/build.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "index.d.ts",
+    "types",
+    "cli",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
     "sync:types": "node scripts/sync-types.mjs",
     "release:preflight": "node scripts/release-preflight.mjs",
     "release:dry-run": "node scripts/release-preflight.mjs --dry-run",
     "prepublishOnly": "node scripts/release-preflight.mjs"
   },
-  "dependencies": { "esbuild": "^0.25.0" },
-  "peerDependencies": { "react": "^19.0.0", "react-dom": "^19.0.0" }
+  "dependencies": {
+    "esbuild": "^0.25.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  }
 }

package/types/ade-types.d.ts

@@ -279,7 +279,7 @@ export interface WorktreeTabState {
     /** 各文件在该 worktree 下的滚动位置（px），用于切回时恢复浏览位置 */
     scrolls: Record<string, number>;
 }
-export type AreaKey = 'project' | 'worktree' | 'files' | 'editor' | 'chat' | 'dingtalk' | 'aone';
+export type AreaKey = 'project' | 'worktree' | 'files' | 'editor' | 'chat' | 'aone';
 export type AoneCategory = 'req' | 'bug' | 'task';
 /** a1 CLI 可用性与 BUC 登录状态。 */
 export interface AoneStatus {
@@ -481,19 +481,45 @@ export interface AgentSettings {
      */
     yolo: string[];
 }
-export interface DingTalkSettings {
-    cli: 'dws' | 'dwsx';
-    dwsxPath: string;
-    /** 留空使用 DWSX_DATA_DIR 或 ~/.local/share/dwsx，与终端共用登录态 */
-    dwsxDataDir?: string;
-    /** dws CLI 路径；留空时自动从 PATH 与常见目录探测 */
-    dwsPath: string;
-}
 export interface AppSettings {
     appearance: AppearanceSettings;
     editor: EditorSettings;
     agents: AgentSettings;
-    dingtalk: DingTalkSettings;
+}
+/** 可持久化的区域布局；只保存位置、比例和标签，不保存插件业务参数。 */
+export interface AdeDockPanel {
+    id: string;
+    contentComponent: 'area';
+    renderer: 'always';
+    title?: string;
+}
+export interface AdeDockGroup {
+    id: string;
+    views: string[];
+    activeView?: string;
+}
+export type AdeDockNode = {
+    type: 'leaf';
+    data: AdeDockGroup;
+    size?: number;
+} | {
+    type: 'branch';
+    data: AdeDockNode[];
+    size?: number;
+};
+export interface AdeDockLayout {
+    grid: {
+        root: AdeDockNode;
+        width: number;
+        height: number;
+        orientation: 'HORIZONTAL' | 'VERTICAL';
+    };
+    panels: Record<string, AdeDockPanel>;
+    activeGroup?: string;
+}
+export interface AdeWorkspaceLayout {
+    version: 1;
+    dock: AdeDockLayout;
 }
 /** 应用状态（原 state.json + localStorage ade-areas 的统一归宿） */
 export interface AdeState {
@@ -502,6 +528,8 @@ export interface AdeState {
     worktreeTabs: Record<string, WorktreeTabState>;
     /** 插件功能区域的显示状态，以插件 ID 和区域 ID 组合为 key。 */
     pluginAreasVisible?: Record<string, boolean>;
+    /** 完整布局保留隐藏及暂不可用的区域；null 表示使用默认布局。 */
+    workspaceLayout?: AdeWorkspaceLayout | null;
 }
 /** ~/.ade/settings.json 的完整结构 */
 export interface AdeSettingsFile {
@@ -515,7 +543,6 @@ export interface SettingsPatch {
         appearance?: Partial<AppearanceSettings>;
         editor?: Partial<EditorSettings>;
         agents?: Partial<AgentSettings>;
-        dingtalk?: Partial<DingTalkSettings>;
     };
     state?: Partial<AdeState>;
 }
@@ -523,155 +550,6 @@ export interface SettingsPatch {
 export interface AgentSettingInfo extends ChatAdapterInfo {
     hidden: boolean;
 }
-/** dws / 钉钉集成状态（设置页与钉钉面板共用） */
-export interface DingTalkStatus {
-    cliKind?: 'dws' | 'dwsx';
-    dataDirectory?: string;
-    available: boolean;
-    authenticated: boolean;
-    version?: string;
-    /** dws 0.x 旧版接口线：上传走 doc create 而非 doc import */
-    legacy?: boolean;
-    message: string;
-    executable?: string;
-}
-/** 钉钉在线文档搜索结果条目 */
-export interface DingTalkDocItem {
-    nodeId: string;
-    name: string;
-    docType?: string;
-    url?: string;
-    createTime?: number | string;
-    modifiedTime?: number | string;
-    creatorUid?: string;
-    creatorName?: string;
-    creatorNick?: string;
-    workspaceId?: string;
-    workspaceName?: string;
-}
-export type DingTalkDocDownloadFormat = 'dingdoc' | 'markdown';
-/** 钉钉听记列表条目 */
-export interface DingTalkMinutesItem {
-    taskUuid: string;
-    title: string;
-    url?: string;
-    startTime?: number | string;
-    status?: string;
-    creatorUid?: string;
-    creatorName?: string;
-    creatorNick?: string;
-}
-/** 下载到本地的结果 */
-export interface DingTalkDownloadResult {
-    kind: 'doc' | 'minutes';
-    path: string;
-    title?: string;
-    url?: string;
-    taskUuid?: string;
-    /** dingdoc / dingmin 文件夹等场景下应打开的首选文件 */
-    entryPath?: string;
-    /** 钉钉文档/听记下载格式 */
-    format?: 'dingdoc' | 'dingmin' | 'markdown';
-}
-/** 可作为上传目标的钉钉知识库 / 个人空间 */
-export interface DingTalkUploadWorkspace {
-    workspaceId: string;
-    name: string;
-    /** org = 组织知识库；mine = 「我的文档」个人空间 */
-    type: 'org' | 'mine';
-}
-/** 知识库内的文件夹节点（上传目标位置选择） */
-export interface DingTalkUploadFolderNode {
-    nodeId: string;
-    name: string;
-}
-/** 粘贴钉钉链接后解析出的上传目标 */
-export interface DingTalkUploadTarget {
-    /** 知识库 ID / URL */
-    workspace: string;
-    /** 文件夹 ID / URL */
-    folder: string;
-    /** 给人看的位置描述 */
-    label: string;
-    /** 链接指向文档本身时：可作为覆盖上传目标 */
-    document?: {
-        nodeId: string;
-        name: string;
-    };
-}
-/** 上传本地 Markdown 为钉钉文档的结果 */
-export interface DingTalkUploadResult {
-    success: boolean;
-    documentUrl?: string;
-    nodeId?: string;
-    documentName?: string;
-    taskId?: string;
-    message?: string;
-    /** 随文档上传的本地图片（含 SVG）统计；无本地图片时不存在 */
-    images?: {
-        total: number;
-        inserted: number;
-        /** 上传失败的本地图片文件名 */
-        missing: string[];
-        /** 未能清理的占位块数量 */
-        leftoverPlaceholders: number;
-    };
-}
-/**
- * dwsx JSONML 读取范围。不传 scope = 整篇 canonical body（root）；
- * outline 只取标题大纲（fragment，heading 带 uuid，可当块 ID）。
- */
-export type DingTalkJsonmlScope = 'outline' | 'tags' | 'section' | 'range';
-/** dwsx doc read --content-format jsonml 的读取选项 */
-export interface DingTalkJsonmlReadOptions {
-    scope?: DingTalkJsonmlScope;
-    /** scope=tags：只取指定标签的块 */
-    tags?: string[];
-    /** scope=range：起始块 ID（可从块列表 / outline 的 uuid 取） */
-    startBlockId?: string;
-    /** scope=range：结束块 ID */
-    endBlockId?: string;
-    /** scope=section/outline：最大层级 */
-    maxDepth?: number;
-    /** 指定文档历史版本 */
-    version?: number | string;
-    /** 落盘路径；留空写入 ADE 钉钉缓存目录，读回文件即覆盖前的备份 */
-    outputPath?: string;
-}
-/** JSONML canonical body（["root"|"fragment", attrs, ...blocks]）读取结果 */
-export interface DingTalkJsonmlDocument {
-    nodeId: string;
-    jsonml: unknown[];
-    contentFormat: 'jsonml';
-    /** 落盘备份路径，可直接作为 overwriteDocJsonml 的 filePath 回写 */
-    savedPath?: string;
-    bytes?: number;
-    revision?: string;
-    scope?: DingTalkJsonmlScope;
-}
-/**
- * JSONML 覆盖输入：裸数组 / { jsonml: [...] } / { jsonml: "…" } / 读回落盘的信封。
- * filePath 与对象形态都接受，ADE 与 dwsx 一样逐层解包。
- */
-export type DingTalkJsonmlInput = unknown[] | {
-    jsonml: unknown;
-} | {
-    filePath: string;
-};
-/** JSONML 整篇覆盖结果 */
-export interface DingTalkJsonmlWriteResult {
-    success: boolean;
-    message?: string;
-    nodeId?: string;
-    documentUrl?: string;
-    documentName?: string;
-    chunksWritten?: number;
-}
-/** 块 element 写入结果（dwsx doc block update / insert） */
-export interface DingTalkBlockWriteResult {
-    success: boolean;
-    message?: string;
-}
 /** 日志等级：error > warn > info > debug */
 export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
 /** 单条日志 */
@@ -694,19 +572,3 @@ export interface LogFilter {
     query?: string;
     limit?: number;
 }
-/** 可恢复的钉钉上传任务，正文与图片分别记录完成状态。 */
-export interface DingTalkUploadJob {
-    filePath: string;
-    title?: string;
-    folder?: string;
-    workspace?: string;
-    nodeId?: string;
-    status: 'running' | 'failed' | 'completed';
-    step: string;
-    error?: string;
-    result?: DingTalkUploadResult;
-    steps: {
-        label: string;
-        status: 'running' | 'completed' | 'failed';
-    }[];
-}

package/types/api.d.ts

@@ -1,6 +1,6 @@
 // 由 sdk/scripts/sync-types.mjs 从 ADE 宿主生成，请勿手工修改。
 import type { PluginCommandContext, PluginConfig, PluginInstallRequest } from './plugins.js';
-import type { AdeSettingsFile, AgentSettingInfo, AoneBoardData, AoneBoardRequest, AoneCreateField, AoneCreateRequest, AoneStatus, AoneUpdateRequest, AoneWorkItem, AoneWorkItemDetail, ChatApprovalResponse, ChatAdapterInfo, ChatAttachment, ChatAttachmentKind, ChatSessionInfo, ChatSessionRecord, CliModelOption, CliOption, CopiedEntry, DingTalkBlockWriteResult, DingTalkDocDownloadFormat, DingTalkDocItem, DingTalkDownloadResult, DingTalkJsonmlDocument, DingTalkJsonmlInput, DingTalkJsonmlReadOptions, DingTalkJsonmlWriteResult, DingTalkMinutesItem, DingTalkStatus, DingTalkUploadFolderNode, DingTalkUploadResult, DingTalkUploadJob, DingTalkUploadTarget, DingTalkUploadWorkspace, FileNode, FileStat, LogEntry, LogFilter, PluginInfo, Project, SettingsPatch, StructuredEvent, Worktree } from './ade-types.js';
+import type { AdeSettingsFile, AgentSettingInfo, AoneBoardData, AoneBoardRequest, AoneCreateField, AoneCreateRequest, AoneStatus, AoneUpdateRequest, AoneWorkItem, AoneWorkItemDetail, ChatApprovalResponse, ChatAdapterInfo, ChatAttachment, ChatAttachmentKind, ChatSessionInfo, ChatSessionRecord, CliModelOption, CliOption, CopiedEntry, FileNode, FileStat, LogEntry, LogFilter, PluginInfo, Project, SettingsPatch, StructuredEvent, Worktree } from './ade-types.js';
 export interface ChatEvent {
     id: string;
     data?: string;
@@ -140,47 +140,6 @@ declare const api: {
         listAgents: () => Promise<AgentSettingInfo[]>;
         onChanged: (cb: (file: AdeSettingsFile) => void) => (() => void);
     };
-    dingtalk: {
-        getUploadJob: (filePath: string) => Promise<DingTalkUploadJob | null>;
-        runUploadJob: (request: {
-            filePath: string;
-            title?: string;
-            folder?: string;
-            workspace?: string;
-            nodeId?: string;
-        }, retry?: boolean) => Promise<DingTalkUploadJob>;
-        getStatus: () => Promise<DingTalkStatus>;
-        login: () => Promise<{
-            started: boolean;
-        }>;
-        restartWukong: () => Promise<{
-            restarted: boolean;
-            message: string;
-        }>;
-        searchDocs: (query: string, source?: "recent" | "mine") => Promise<DingTalkDocItem[]>;
-        listMinutes: (query: string) => Promise<DingTalkMinutesItem[]>;
-        previewDoc: (node: string, preferredName?: string) => Promise<DingTalkDownloadResult>;
-        downloadDoc: (node: string, targetDir: string, format?: DingTalkDocDownloadFormat, preferredName?: string) => Promise<DingTalkDownloadResult>;
-        downloadMinutes: (taskUuid: string, targetDir: string, outputName?: string, format?: "dingmin" | "markdown") => Promise<DingTalkDownloadResult>;
-        uploadMarkdown: (filePath: string, title: string, folder: string, workspace: string) => Promise<DingTalkUploadResult>;
-        listUploadWorkspaces: () => Promise<DingTalkUploadWorkspace[]>;
-        listUploadFolders: (workspaceId: string, parentNodeId?: string) => Promise<DingTalkUploadFolderNode[]>;
-        resolveUploadTarget: (input: string) => Promise<DingTalkUploadTarget>;
-        listUploadDocs: (workspaceId: string, parentNodeId?: string) => Promise<DingTalkUploadFolderNode[]>;
-        overwriteDoc: (nodeId: string, filePath: string) => Promise<DingTalkUploadResult>;
-        readDocJsonml: (nodeId: string, options?: DingTalkJsonmlReadOptions) => Promise<DingTalkJsonmlDocument>;
-        overwriteDocJsonml: (nodeId: string, input: DingTalkJsonmlInput) => Promise<DingTalkJsonmlWriteResult>;
-        createDocWithJsonml: (name: string, input: DingTalkJsonmlInput, location?: {
-            folder?: string;
-            workspace?: string;
-        }) => Promise<DingTalkJsonmlWriteResult>;
-        listDocBlockElements: (nodeId: string, options?: {
-            startIndex?: number;
-            contentFormat?: "element" | "jsonml";
-        }) => Promise<unknown[]>;
-        updateDocBlock: (nodeId: string, blockId: string, element: unknown) => Promise<DingTalkBlockWriteResult>;
-        insertDocBlock: (nodeId: string, index: number, element: unknown) => Promise<DingTalkBlockWriteResult>;
-    };
     aone: {
         getStatus: () => Promise<AoneStatus>;
         loadBoard: (request: AoneBoardRequest) => Promise<AoneBoardData>;

package/types/plugins.d.ts

@@ -69,6 +69,37 @@ export interface PluginCommandContext {
   filePath: string | null
 }
 
+/** 文件树菜单捕获的节点与选择；不暴露宿主 store 或 DOM。 */
+export interface PluginFileMenuNode {
+  name: string
+  path: string
+  type: 'file' | 'dir'
+}
+export interface PluginFileMenuContext extends PluginCommandContext {
+  node: PluginFileMenuNode
+  isRoot: boolean
+  selection: PluginFileMenuNode[]
+}
+export interface PluginFileMenuRegistration {
+  id: string
+  label: string
+  order?: number
+  when?: (context: PluginFileMenuContext) => boolean
+  enabled?: (context: PluginFileMenuContext) => boolean
+  onSelect(context: PluginFileMenuContext): void | Promise<void>
+}
+export interface PluginWorkspaceApi {
+  /** 仅打开真实普通文件；不存在、目录或过期操作返回 false。 */
+  openFile(path: string): Promise<boolean>
+  /** 刷新当前 worktree 的目录；其他路径及过期结果不改动文件树。 */
+  refreshTree(directory?: string): Promise<void>
+  /** 查询当前未保存标记，不包含编辑器正文。 */
+  isFileDirty(path: string): boolean
+}
+export interface PluginUiApi {
+  showToast(message: string, url?: string): void
+}
+
 export interface PluginViewInfo {
   id: string
   title: string