feat(plugins): 依赖互调 + SQLite 存储，契约 0.3.0

packages/plugin-sdk/src/index.ts

@@ -6,4 +6,5 @@ export * from './manifest'
 export * from './settings'
 export * from './async'
 export * from './status'
+export * from './storage'
 export * from './plugin'

packages/plugin-sdk/src/manifest.ts

@@ -36,6 +36,11 @@ export interface PluginManifest {
   /** 外置插件遮蔽"组件级"内置插件时必须为 true（能力降级声明，
    * 防止带原生视图能力的内置被页面级外置静默顶掉） */
   replacesNative?: boolean
+  /** 必需依赖：插件 id → semver 范围（^x.y.z / ~x.y.z / >=x.y.z / 精确 x.y.z / *）。
+   * 缺失 / 已停用 / 版本不符 → 本插件激活失败并提示；api.requirePlugin 仅对声明过的依赖放行 */
+  dependencies?: Record<string, string>
+  /** 可选依赖：同范围语法；缺失或停用只降级不报错（requirePlugin 返回 undefined） */
+  optionalDependencies?: Record<string, string>
   /** 更新索引地址（JSON；格式见 docs/plugins.md） */
   updateURL?: string
 }

packages/plugin-sdk/src/plugin.ts

@@ -6,13 +6,7 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 import type { PluginManifest } from './manifest'
 import type { PluginSettingsSchema, PluginSettingValues } from './settings'
 import type { StatusItem, ToolbarButtonDef } from './status'
-
-/** 插件私有 KV 存储（主进程落盘 userData/aso-plugin-storage.json，按 pluginId 命名空间隔离） */
-export interface PluginStorage {
-  get<T>(key: string): T | undefined
-  set(key: string, value: unknown): void
-  delete(key: string): void
-}
+import type { PluginStorage } from './storage'
 
 /** 插件日志通道：宿主注入，写入统一日志文件（userData/logs/，带 pluginId 字段）。
  * Agent 自诊断依赖该通道——插件应当把装载/激活/关键决策与失败都记到这里。 */
@@ -50,10 +44,18 @@ export interface HarnessPluginApi {
   /** pi 原生扩展 API：工具/事件/命令/消息全走这里（pi.registerTool 等，语义与 pi CLI 扩展一致） */
   pi: ExtensionAPI
   ui: HarnessUiApi
+  /** 私有存储：每插件一个 SQLite 库（KV + 自建表 + 文件目录），API 全 async */
   storage: PluginStorage
   /** 结构化日志（scope=plugin，自动带 pluginId；error 级别会进日志文件） */
   log: PluginLogger
   manifest: PluginManifest
+  /** 注册跨插件服务（按名键控；dispose/重载时宿主自动清空）。
+   * 只有在 manifest 中声明了本插件为依赖的插件才能取用。 */
+  service(name: string, impl: unknown): void
+  /** 取依赖插件的服务对象（{ serviceName: impl }）。
+   * 未在 dependencies / optionalDependencies 声明 targetId → 抛错（依赖声明即访问授权）；
+   * 必需依赖未就绪 → 抛错；可选依赖未就绪 → 返回 undefined。 */
+  requirePlugin(targetId: string): Record<string, unknown> | undefined
 }
 
 /** 插件工厂：同步或异步返回 dispose */

packages/plugin-sdk/src/storage.ts

@@ -0,0 +1,57 @@
+/**
+ * 插件存储契约（0.3.0）：每插件一个 SQLite 库（userData/plugin-data/<id>/data.db），
+ * 由宿主共享 worker 线程持有连接——API 全 async，永不阻塞主进程。
+ * 本模块只含类型（同时被宿主、渲染层、插件消费），不得引入 node:sqlite。
+ */
+
+/** SQLite 存储声明中的一列（description 必填——Agent 自我迭代读的就是它） */
+export interface PluginStorageColumn {
+  name: string
+  /** SQLite 类型：TEXT / INTEGER / REAL / BLOB / NUMERIC */
+  type: string
+  description: string
+}
+
+/** 插件自建表声明 */
+export interface PluginStorageTable {
+  name: string
+  description: string
+  columns: PluginStorageColumn[]
+}
+
+/** 机器可读存储 schema：UI Tooltip 与 Agent 内省同源（plugin:check 强制描述非空）。
+ * kv 表由宿主管理（api.storage.get/set 的底层），这里只要求描述键空间用途。 */
+export interface PluginStorageSchema {
+  tables: PluginStorageTable[]
+  kv?: { description: string }
+}
+
+/** 宿主管理的 KV 表（SQLite kv 表键值对；value JSON 编码） */
+export interface PluginKvStore {
+  get<T>(key: string): Promise<T | undefined>
+  set(key: string, value: unknown): Promise<void>
+  delete(key: string): Promise<void>
+  keys(): Promise<string[]>
+}
+
+/** 插件自建表的 SQL 入口（worker 线程执行） */
+export interface PluginDb {
+  /** 多语句 DDL/脚本（无参数） */
+  exec(sql: string): Promise<void>
+  /** 写语句（INSERT/UPDATE/DELETE/DDL，带参数） */
+  run(sql: string, params?: unknown[]): Promise<void>
+  /** 查询（返回全部行） */
+  query(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>
+  /** 原子批量：worker 端 BEGIN/COMMIT 包裹，任一失败整体回滚 */
+  batch(statements: Array<{ sql: string; params?: unknown[] }>): Promise<void>
+}
+
+/** 插件私有存储（api.storage）：KV + 自建表 SQLite + 自由文件目录 + schema 声明 */
+export interface PluginStorage {
+  kv: PluginKvStore
+  db: PluginDb
+  /** 插件数据目录（userData/plugin-data/<id>/，可自由写文件；清除数据时整体删除） */
+  dir(): string
+  /** 声明机器可读存储 schema（每次激活重新声明；使用 db 前必须声明） */
+  declareSchema(schema: PluginStorageSchema): void
+}