@ai_mind/ade-plugin-sdk 0.0.0-stage → 0.1.1

package/cli/build.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+import { build } from 'esbuild'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const modulePath = await fs.realpath(fileURLToPath(import.meta.url))
+const sdkPackage = JSON.parse(await fs.readFile(path.resolve(path.dirname(modulePath), '../package.json'), 'utf8'))
+const sdkVersion = /^(\d+)\.\d+\.\d+(?:[-+][\w.-]+)?$/.exec(sdkPackage.version)
+const sdkMajor = sdkVersion ? Number(sdkVersion[1]) : NaN
+if (!Number.isSafeInteger(sdkMajor)) throw new Error('插件 SDK 版本无效')
+
+const sharedModules = ['react', 'react/jsx-runtime', 'react/jsx-dev-runtime', 'react-dom', 'react-dom/client', '@ai_mind/ade-plugin-sdk', '@ai_mind/plugin-sdk', '@ade/plugin-sdk']
+const assetLoaders = Object.fromEntries([
+  '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.avif', '.ico',
+  '.woff', '.woff2', '.ttf', '.otf', '.eot'
+].map((extension) => [extension, 'file']))
+
+function ownedPath(directory, relative, label) {
+  if (typeof relative !== 'string' || !relative || path.isAbsolute(relative)) {
+    throw new Error(`${label}必须是插件目录内的相对路径`)
+  }
+  const resolved = path.resolve(directory, relative)
+  if (!resolved.startsWith(`${directory}${path.sep}`)) throw new Error(`${label}不能越过插件目录`)
+  return resolved
+}
+
+/** 将 TSX 和依赖预构建为浏览器插件，保留 ADE 提供的 React 模块身份。 */
+export async function buildPlugin(directory, options = {}) {
+  directory = path.resolve(directory)
+  const manifest = JSON.parse(await fs.readFile(path.join(directory, 'plugin.json'), 'utf8'))
+  const pluginId = manifest.id ?? manifest.name
+  if (typeof pluginId !== 'string' || !/^[a-z0-9][a-z0-9._-]*$/.test(pluginId)) {
+    throw new Error('plugin.json 必须声明稳定的小写插件 ID')
+  }
+  if (manifest.apiVersion !== 1) throw new Error('插件构建工具只支持 apiVersion: 1')
+  if (manifest.rendererFormat !== 'register') {
+    throw new Error('TSX 构建要求 plugin.json 声明 rendererFormat: "register"')
+  }
+  const addedAdeMajor = !Object.hasOwn(manifest, 'adeMajor')
+  if (!addedAdeMajor && (!Number.isSafeInteger(manifest.adeMajor) || manifest.adeMajor < 0 || manifest.adeMajor !== sdkMajor)) {
+    throw new Error(`plugin.json 的 adeMajor 必须是当前 SDK 对应的 ADE major 版本 ${sdkMajor}`)
+  }
+  if (addedAdeMajor) manifest.adeMajor = sdkMajor
+  if (manifest.styles !== undefined && (!Array.isArray(manifest.styles) || manifest.styles.some((style) => typeof style !== 'string'))) {
+    throw new Error('plugin.json 的 styles 必须是相对路径数组')
+  }
+  const entry = ownedPath(directory, options.entry ?? 'src/renderer.tsx', '渲染入口')
+  const output = ownedPath(directory, manifest.renderer, 'renderer')
+  const assetDirectory = path.relative(directory, path.dirname(output)).split(path.sep).filter(Boolean).map(encodeURIComponent).join('/')
+  const result = await build({
+    absWorkingDir: directory,
+    entryPoints: [entry],
+    outfile: output,
+    bundle: true,
+    write: false,
+    platform: 'browser',
+    format: 'cjs',
+    target: 'es2022',
+    jsx: 'automatic',
+    loader: assetLoaders,
+    assetNames: 'assets/[name]-[hash]',
+    publicPath: `ade-plugin://${pluginId}/${assetDirectory ? `${assetDirectory}/` : ''}`,
+    external: sharedModules,
+    metafile: true,
+    legalComments: 'none',
+    logLevel: 'silent',
+    plugins: [{
+      name: 'ade-browser-boundary',
+      setup(builder) {
+        builder.onResolve({ filter: /^node:/ }, ({ path: name }) => ({
+          errors: [{ text: `渲染插件不能引入 ${name}；请在 main 入口通过命令提供此能力` }]
+        }))
+      }
+    }]
+  })
+  const code = result.outputFiles.find((file) => file.path === output)?.text
+  if (!code) throw new Error('未生成渲染插件文件')
+  // 浏览器用 <script> 装载工厂；不使用 eval 或 new Function，也不引入第二份 React。
+  const wrapped = `globalThis.__adeRegisterPlugin(${JSON.stringify(pluginId)}, function(require, module, exports) {\n${code}\n});\n`
+  // CSS 和 url() 引用的字体、图片也是预构建产物，不能只保留入口 JS。
+  const outputFiles = result.outputFiles.map((file) => ({
+    ...file,
+    relative: path.relative(directory, file.path).split(path.sep).join('/')
+  }))
+  for (const file of outputFiles) ownedPath(directory, file.relative, '构建产物')
+  await Promise.all(outputFiles.map(async (file) => {
+    await fs.mkdir(path.dirname(file.path), { recursive: true })
+    await fs.writeFile(file.path, file.path === output ? wrapped : file.contents)
+  }))
+  const generatedStyles = outputFiles.filter((file) => file.path.endsWith('.css')).map((file) => file.relative)
+  const originalStyles = manifest.styles ?? []
+  const existingStyles = new Set(originalStyles.map((style) => ownedPath(directory, style, 'styles')))
+  const addedStyles = generatedStyles.filter((style) => !existingStyles.has(path.resolve(directory, style)))
+  if (addedStyles.length) {
+    manifest.styles = [...originalStyles, ...addedStyles]
+  }
+  if (addedAdeMajor || addedStyles.length) {
+    await fs.writeFile(path.join(directory, 'plugin.json'), `${JSON.stringify(manifest, null, 2)}\n`)
+  }
+  if (options.mainEntry) {
+    await build({
+      absWorkingDir: directory,
+      entryPoints: [ownedPath(directory, options.mainEntry, '主进程入口')],
+      outfile: ownedPath(directory, manifest.main, 'main'),
+      bundle: true,
+      platform: 'node',
+      format: 'cjs',
+      target: 'node24',
+      external: ['electron'],
+      plugins: [{
+        name: 'ade-main-sdk-runtime',
+        setup(builder) {
+          builder.onResolve({ filter: /^(?:@ai_mind\/(?:ade-)?plugin-sdk|@ade\/plugin-sdk)$/ }, () => ({ path: path.resolve(path.dirname(modulePath), '../index.mjs') }))
+        }
+      }],
+      legalComments: 'none',
+      logLevel: 'silent'
+    })
+  }
+  return { pluginId, output, files: outputFiles.map((file) => file.path), inputs: Object.keys(result.metafile.inputs) }
+}
+
+async function main() {
+  const args = process.argv.slice(2)
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log('用法：ade-plugin-build [插件目录] [--entry src/renderer.tsx] [--main-entry src/main.ts]')
+    return
+  }
+  let directory = '.'
+  let directorySeen = false
+  const options = {}
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]
+    if (arg === '--entry' || arg === '--main-entry') {
+      const value = args[++i]
+      if (!value || value.startsWith('--')) throw new Error(`${arg} 缺少文件路径`)
+      options[arg === '--entry' ? 'entry' : 'mainEntry'] = value
+    } else if (arg.startsWith('-')) throw new Error(`未知参数：${arg}`)
+    else if (!directorySeen) { directory = arg; directorySeen = true }
+    else throw new Error('只能指定一个插件目录')
+  }
+  const result = await buildPlugin(directory, options)
+  console.log(`已构建插件「${result.pluginId}」：${result.output}`)
+}
+
+// npm 的 .bin 命令是符号链接；Node 会将模块 URL 解析为真实文件地址。
+const invokedPath = process.argv[1] ? await fs.realpath(path.resolve(process.argv[1])).catch(() => null) : null
+if (invokedPath === modulePath) {
+  main().catch((error) => {
+    console.error(`插件构建失败：${error instanceof Error ? error.message : String(error)}`)
+    process.exitCode = 1
+  })
+}

package/index.d.ts

@@ -0,0 +1,77 @@
+import type * as React from 'react'
+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
+} from './types/plugins.js'
+
+export type * from './types/plugins.js'
+export type * from './types/api.js'
+export type * from './types/ade-types.js'
+export type * from './types/adapter.js'
+export type PluginManagementApi = AdeApi['plugins']
+
+/** Component 在 ADE 的同一棵 React 树内运行。 */
+export interface PluginComponentProps {
+  context: PluginCommandContext
+  config: PluginConfig
+  api: AdeApi
+}
+
+export interface PluginSlotRegistration {
+  id: string
+  component: React.ComponentType<PluginComponentProps>
+  order?: number
+  when?: (context: PluginCommandContext) => boolean
+}
+
+export interface PluginViewRegistration extends PluginViewInfo {
+  component: React.ComponentType<PluginComponentProps>
+}
+
+export interface RendererPluginContext {
+  pluginId: string
+  React: typeof React
+  ReactDOM: typeof ReactDOM
+  api: AdeApi
+  subscriptions: PluginDisposer[]
+  getContext(): PluginCommandContext
+  useContext(): PluginCommandContext
+  getConfig(): PluginConfig
+  useConfig(): PluginConfig
+  setConfig(patch: PluginConfig): Promise<PluginConfig>
+  onConfigChanged(listener: (config: PluginConfig) => void): PluginDisposer
+  registerView(view: PluginViewRegistration): PluginDisposer
+  registerSlot(name: PluginSlotName, contribution: PluginSlotRegistration): 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>
+  on(event: string, listener: (data: unknown) => void): PluginDisposer
+  emit(event: string, data?: unknown): void
+  provideService(name: string, value: unknown): PluginDisposer
+  getService<T = unknown>(name: string): T | undefined
+  /** 接收清理函数，而不是 effect setup；注册项已经由宿主自动管理。 */
+  effect(cleanup: PluginDisposer): PluginDisposer
+  addStyle(css: string): PluginDisposer
+}
+
+export type PluginSessionContext = SessionContext
+export type PluginChatSession = ChatSession
+export type PluginChatAdapter = ChatAdapter
+export type MainPluginContext = PluginContext
+
+export interface RendererPlugin {
+  activate(context: RendererPluginContext): void | PluginDisposer | Promise<void | PluginDisposer>
+  deactivate?(): void | Promise<void>
+}
+export interface MainPlugin {
+  activate(context: MainPluginContext): void | PluginDisposer | Promise<void | PluginDisposer>
+  deactivate?(): void | Promise<void>
+}
+
+/** 带类型推导的插件定义；不会执行插件。 */
+export function definePlugin<T extends RendererPlugin | MainPlugin>(plugin: T): T
+
+/** 渲染插件约定的子扩展位置；pluginId 可筛选其拥有者。 */
+export const Slot: React.ComponentType<{ name: PluginSlotName; pluginId?: string }>

package/index.mjs

@@ -0,0 +1,9 @@
+/** 为编辑器提供类型推导，运行时保持插件定义原样。 */
+export function definePlugin(plugin) {
+  return plugin
+}
+
+/** 浏览器运行时提供 Slot；离开 ADE 时不能渲染宿主扩展位置。 */
+export function Slot() {
+  throw new Error('Slot 只能在 ADE 插件运行时使用')
+}

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "@ai_mind/ade-plugin-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "ADE 可信插件 SDK、类型与 React 插件构建工具",
+  "license": "MIT",
+  "author": "sepmini",
+  "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"],
+  "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" }
+}

package/types/adapter.d.ts

@@ -0,0 +1,153 @@
+// 由 sdk/scripts/sync-types.mjs 从 ADE 宿主生成，请勿手工修改。
+import type { ChatAdapterInfo, ChatApprovalResponse, ChatAttachment, ChatAttachmentKind, ChatMessageRecord, CliModelOption, CliOption, StructuredEvent } from './ade-types.js';
+import type { PluginCommandContext, PluginConfig, PluginDisposer } from './plugins.js';
+export interface SessionContext {
+    id: string;
+    worktree: string;
+    cwd: string;
+    /** 会话所属 ADE 项目根目录；daemon 用于生成 Paseo projectKey。 */
+    projectPath?: string | null;
+    onData: (data: string) => void;
+    onExit: (code: number) => void;
+    onError: (err: Error) => void;
+    /**
+     * 底层 agent CLI 的会话标识（由 ChatManager 生成）。终端适配器用它
+     * 以固定会话启动/续接 TUI（如 qodercli --session-id / -r），使聊天视图
+     * 与终端视图共享同一会话、切换不丢内容。不支持时为 undefined。
+     */
+    sessionId?: string;
+    /** 是否为续接（该会话已有历史，spawn 时用 resume 而非创建） */
+    resume?: boolean;
+    /** 会话级 CLI 配置（用户在新会话对话框中选择的选项，如 --model） */
+    config?: Record<string, string>;
+}
+export interface ChatSession {
+    id: string;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    dispose(): void | Promise<void>;
+    /** 底层进程真正退出时完成；用于切换传输前等待文件锁/会话锁释放。 */
+    closed?: Promise<number>;
+}
+/** 结构化对话会话的上下文：除原始字节流外，额外提供解析后的事件通道 */
+export interface StructuredSessionContext extends SessionContext {
+    onEvent: (ev: StructuredEvent) => void;
+}
+/** 启动一轮结构化对话的参数 */
+export interface ChatTurnOptions {
+    prompt: string;
+    attachments?: ChatAttachment[];
+    /** CLI 会话标识：续接已有会话时传入（由 ChatManager 维护） */
+    sessionId: string | null;
+    /** 是否为续接（true 时用 resume 而非创建新会话） */
+    resume: boolean;
+    /** 会话级 CLI 配置（用户选择，如 --model / --permission-mode） */
+    config?: Record<string, string>;
+}
+/** provider 已持久化、可通过原生 session/thread id 继续的会话摘要。 */
+export interface ProviderChatSession {
+    sessionId: string;
+    cwd: string;
+    name?: string;
+    preview?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface ChatAdapter {
+    id: string;
+    label: string;
+    description?: string;
+    kind: 'terminal' | 'sdk';
+    /** Spawn command, used by terminal adapters and available to plugins */
+    command?: string;
+    /** Plugin id that registered this adapter */
+    plugin?: string;
+    /**
+     * 该 CLI 的「YOLO / 跳过权限确认」参数；未声明表示不支持（设置页不提供开关）。
+     * 设置里按 Agent 开启后，新建会话时由 ChatManager 并入会话配置。
+     */
+    yoloFlag?: string;
+    /** 结构化协议是否原生流式输出（渲染层据此决定打字机动画） */
+    streaming?: boolean;
+    /** 构造 --help 的 argv（有协议的适配器提供，如 codex 需 exec --help） */
+    helpArgs?: () => string[];
+    /** 核心配置项（显示在对话配置条上；其余动态选项在「更多配置」） */
+    coreOptions?: string[];
+    /** 模型列表命令 argv（如 qodercli --list-models）；无则模型自由输入 */
+    listModelsArgs?: () => string[];
+    /** 把 CLI 模型列表解析为实际 value、显示名与分组。 */
+    parseModels?: (output: string) => CliModelOption[];
+    /** 对 help 未声明 choices 的选项提供建议值（如 qoder --reasoning-effort） */
+    suggestions?: Record<string, string[]>;
+    /**
+     * 该协议自己拥有、不应出现在配置界面的原生参数（会话续接、工程、日志、输出 schema 等）。
+     * 按 adapter 作用域排除，避免为了某个 CLI 而在全局黑名单里误伤其他 CLI 的同名参数。
+     */
+    excludedOptions?: string[];
+    /** 通过 provider 原生协议补充/覆盖配置元数据（例如 Codex model/list）。refresh 为 true 时忽略缓存重新拉取。 */
+    loadOptions?: (refresh?: boolean) => Promise<CliOption[]>;
+    createSession(ctx: SessionContext): ChatSession | Promise<ChatSession>;
+    /**
+     * 原生对话能力（可选）：适配器支持结构化事件流（如 qodercli stream-json）
+     * 时实现它，聊天面板可渲染原生气泡界面。每轮对话由 ChatManager 调用一次，
+     * 进程输出经解析后通过 ctx.onEvent 广播；进程退出（或异常）调 onExit。
+     */
+    chat?: {
+        /**
+         * 会话标识是否由应用预分配（qoder/claude/pi 支持 --session-id 创建指定
+         * 会话）。false 表示会话 id 由 CLI 生成（如 codex thread_id），首轮后
+         * 通过 init 事件回填，续接必须等回填完成。
+         */
+        preassignedSessionId?: boolean;
+        /**
+         * 在首轮消息前预创建 provider 会话。返回的 id 只代表已分配；在首个 turn
+         * 持久化前，不能假定终端 CLI 已经可以 resume 它。
+         */
+        prepareSession?: (ctx: StructuredSessionContext, config?: Record<string, string>) => Promise<{
+            sessionId: string;
+        }>;
+        /** 图形化连接让位给 TUI 前释放 provider 连接。 */
+        detach?: (id: string) => void | Promise<void>;
+        /** 从 provider 原生历史重建气泡消息（终端交互后回到图形界面时使用）。 */
+        readHistory?: (ctx: StructuredSessionContext, sessionId: string, config?: Record<string, string>) => Promise<ChatMessageRecord[]>;
+        /** 发现本地 CLI 已持久化、可 resume 的会话。 */
+        discoverSessions?: (cwds: string[]) => Promise<ProviderChatSession[]>;
+        /** 活跃 turn 支持追加指令时使用；不支持的适配器由 ChatManager 排队。 */
+        steer?: (id: string, prompt: string, attachments?: ChatAttachment[]) => Promise<void>;
+        /** 回复审批或运行时用户输入请求。 */
+        respond?: (id: string, requestId: string, response: ChatApprovalResponse) => Promise<void>;
+        /** 永久关闭适配器为该 ADE 会话保留的资源。 */
+        disposeSession?: (id: string) => void | Promise<void>;
+        /** 实际可发送的附件类型；目录始终作为提示词中的路径引用。 */
+        attachmentKinds?: ChatAttachmentKind[];
+        /** 旧插件兼容字段；未声明 attachmentKinds 时 true 视为支持 image/file。 */
+        attachmentSupported?: boolean;
+        /** 启动一轮结构化对话 */
+        startTurn(ctx: StructuredSessionContext, opts: ChatTurnOptions): ChatSession | Promise<ChatSession>;
+    };
+}
+export interface PluginHost {
+    registerAdapter(adapter: ChatAdapter): void;
+    log(level: 'info' | 'warn' | 'error', message: string): void;
+}
+/** 可信本地插件的主进程上下文；所有注册项在停用时自动撤销。 */
+export interface PluginContext extends PluginHost {
+    pluginId: string;
+    pluginPath: string;
+    dataPath: string;
+    subscriptions: PluginDisposer[];
+    registerCommand(id: string, handler: (args: unknown, context: PluginCommandContext) => unknown | Promise<unknown>): PluginDisposer;
+    provideService(name: string, service: Record<string, unknown>): PluginDisposer;
+    getService(name: string): unknown;
+    events: {
+        on(name: string, listener: (payload: unknown) => void): PluginDisposer;
+        emit(name: string, payload?: unknown): void;
+    };
+    getConfig(): PluginConfig;
+    setConfig(patch: PluginConfig): Promise<PluginConfig>;
+    onConfigChanged(listener: (config: PluginConfig) => void): PluginDisposer;
+    /** 登记定时器、文件监听等资源的清理函数。 */
+    effect(disposer: PluginDisposer): PluginDisposer;
+}
+export type PluginMain = (host: PluginHost) => void | Promise<void>;
+export declare function adapterToInfo(a: ChatAdapter): ChatAdapterInfo;