@linkdesk/contracts 0.1.0 → 0.1.2

package/README.md

@@ -23,7 +23,7 @@ window.linkdesk.configuration.get("editor.fontSize"); // 智能提示 + 类型
 
 - **纯类型**：不含 `getLinkDesk`/`linkdesk` 值导出——运行时走 `window.linkdesk`（preload 注入）。
 - **自包含**：无任何 `@src/core` 依赖，拷一个 d.ts 进项目即完整类型。
-- **版本联动**：包版本 = 壳版本（同版本发布）。升级壳即换契约——插件 `npm update @linkdesk/contracts` 拿到新类型。
+- **版本轴独立（2026-09-06 拆焊，反向 E5.8#22.6）**：包版本不再随壳——壳升级 ≠ 契约升级（软件升级是用户轴，与本包无关）。只有当 `window.linkdesk.*` API 面变了、作者要拿新类型时才升版发布。**内容仍与壳源码逐字节同步**（生成器比对，漂移即 `contracts:check` 红）——类型永远描述当前壳，只是版本号不绑壳。`npm update @linkdesk/contracts` 在版本升后拿新类型。
 
 ## 与仓库产物双轨
 

package/linkdesk.d.ts

@@ -358,6 +358,22 @@ export interface KeybindingsAPI {
         onForwardedEvent?(cb: (input: ForwardedKeyboardInput) => void): () => void;
     };
 }
+/** 通知主动作按钮描述（E6#13.5 缝隙 K1）——插件 notifications.show 传 actions，
+ *  经 IPC 序列化到壳；点击时壳 executeCommand(command, args) 真执行。
+ *  对标 VS Code `INotificationAction`（命令面）。按钮文案 = 最终显示文本，壳不二次翻译。 */
+export interface PluginToastAction {
+    /** 动作 id——插件侧标识（同一通知内唯一）；点击回执按位置序号，id 仅供调试/日志 */
+    id?: string;
+    /** 按钮文案（最终显示文本） */
+    label: string;
+    /** true → 主按钮（accent 色）；false/未设 → 次级文本按钮 */
+    isPrimary?: boolean;
+    /** 点击执行的命令 id——壳 executeCommand(command, args)。命令 handler 由插件自注册
+     *  （window.linkdesk.commands.registerCommand）。无 command → 按钮点击仅关闭 toast（无副作用） */
+    command?: string;
+    /** 透传给命令 handler 的 ...args */
+    args?: unknown[];
+}
 /** 进度通知句柄——progress=true 时 show() 返回 */
 export interface NotificationHandle {
     /** 更新进度消息 */
@@ -550,10 +566,13 @@ export type PoolFloatingPanelData = {
 export interface UiAPI {
     /** 通知——插件弹出壳侧 toast，对标 VS Code vscode.window.showInformationMessage */
     notifications: {
-        /** 弹出通知。progress=true 时返回 ProgressHandle（含 update/finish/cancel） */
+        /** 弹出通知。progress=true 时返回 ProgressHandle（含 update/finish/cancel）。
+         *  E6#13.5：options.actions 带主动作按钮——点击走壳 executeCommand(action.command, action.args)，
+         *  命令 handler 插件自注册。不传 actions → 无按钮（现状）。error 类自动停留 8s。 */
         show(message: string, options?: {
             type?: "info" | "warning" | "error";
             progress?: boolean;
+            actions?: PluginToastAction[];
         }): Promise<NotificationHandle | undefined>;
     };
     /** E5#69：菜单——插件声明式读写 */
@@ -736,6 +755,8 @@ export interface EnvInfo {
     appDataDir: string;
     pluginsRootDir: string;
     appPluginsDir: string;
+    /** E6#7（1.2-4）：用户安装包代码根 {userData}/plugins——.linkdesk-plugin 解压家（与 appPluginsDir 只读根分开） */
+    userPluginsDir: string;
     pluginDataDir?: string;
     pluginCacheDir?: string;
     pluginExportsDir?: string;
@@ -882,6 +903,16 @@ export interface EditorAPI {
         registerView(pluginId: string, containerId: string, descriptor: Record<string, unknown>): Promise<void>;
     };
 }
+/** E6#7（1.2-4）：plugins.resolveEntry() 返回——resolvePath 的兄弟（discovery 族，非安装 handler）。
+ *  pool/运行时按 { root, entry } 拼 dev /@fs 与 prod linkdesk:// 两种 URL。 */
+export interface PluginEntryInfo {
+    /** 插件目录绝对路径（正斜杠）；插件不存在 = null */
+    root: string | null;
+    /** 入口文件名——bundle → "index.bundle.js"；源码 → manifest.entry（缺省 "src/index.tsx"）；无 = null */
+    entry: string | null;
+    /** 目录是否含 index.bundle.js（bundle 格式事实） */
+    bundle: boolean;
+}
 /**
  * Phase 4 核心类型定义。
  * 插件元数据、标签页扩展字段、视图注册表条目。
@@ -969,7 +1000,10 @@ export interface PluginManifest {
     screenshots?: string[];
     minAppVersion?: string;
     /** 激活事件——对标 VS Code activationEvents。空或含 "*" = 启动时立即加载。
-     *  具体事件：onCommand:id / onFileOpen:.ext / onPortOpen / onLanguage:id / onView:id */
+     *  具体事件（canonical 无前导点——与 fileAssociations.extension 一致）：
+     *  onCommand:id / onFileOpen:ext / onLanguage:ext / onPortOpen / onView:containerId。
+     *  未写此字段 → 壳按 contributes 自动推断（#9g：fileAssociations→onLanguage / views→onView / commands→onCommand），
+     *  写了则显式优先（精确控制）。延迟插件启动注册-only，首用事件才 import JS。 */
     activationEvents?: string[];
     /** @deprecated E5.8#14——归并到 requires（插件级激活依赖统一由 requires 声明）。
      *  零插件使用；loader 兼容读取直到 #14 落地迁移。 */
@@ -1010,6 +1044,33 @@ export interface PluginManifest {
      */
     contributes?: Record<string, unknown>;
 }
+/** 发现条目——plugins.listAll() 返回（E6#9a：主进程直扫 plugins/ 全子目录，替代渲染进程 import.meta.glob）。
+ *  打包/市场安装的插件不在源码树——glob 发现不了；listAll 以磁盘为唯一真源，dev/prod 同一面。
+ *  完整 manifest 为纯 JSON 数据（IPC 可序列化），statusBar/contributes 等随 manifest 携带
+ *  （#9b：statusBar 入口由消费方从 manifest.statusBar 派生，无需单独通道）。 */
+export interface PluginDiscoveryEntry {
+    pluginId: string;
+    /** manifest.entry——插件 JS 入口（无 = 纯贡献插件，只有 manifest 无组件） */
+    entry?: string;
+    /** 完整 plugin.json */
+    manifest: PluginManifest;
+    /** E6#7（1.2-4）：目录含 index.bundle.js = SDK 打包的 .linkdesk-plugin 解压产物。
+     *  磁盘格式事实（非插件身份——硬约束 11）；bundle 插件 JS 入口恒 index.bundle.js（runtime 分支依据）。 */
+    bundle?: boolean;
+    /** E6#7（1.2-4）：磁盘位置事实——home = 代码根（app = 只读 app 插件根 / userData = {userData}/plugins 用户安装家）。
+     *  subdir = 2026-09-05 塌平单根后恒 null（平铺树 root-direct 扫描不产出子目录；类型保留 null 供下游空安全）。 */
+    origin?: {
+        home: "app" | "userData";
+        subdir: string | null;
+    };
+}
+/** E6#13b（段 B）：pluginManager.checkUpdates 返回——主进程 fetch catalog + semver 对比（壳传 current，壳是账本/磁盘 owner） */
+export interface PluginUpdateCheckResult {
+    current: string;
+    latestVersion: string;
+    downloadUrl?: string;
+    update: boolean;
+}
 /** list() 的 manifest 序列化子集——与 handlePluginsCall "list" 7 字段对齐 */
 export interface PluginListSubset {
     name?: string;
@@ -1051,15 +1112,55 @@ export interface PluginInfoEntry {
     description?: string;
     version?: string;
 }
+/** E6#11c/#13b（段 B）：更新结果——PluginInstallResult 的更新扩展。
+ *  upToDate = catalog 直答已是最新（success:true 但非"更新发生"——UI 显示"已是最新"非红错误）；
+ *  currentVersion 随行供 toast/日志显示 v旧→v新。needRestart 恒 true（bundle 模块缓存需重启激活）。 */
+export interface PluginUpdateResult extends PluginInstallResult {
+    /** 更新前磁盘版本 */
+    currentVersion?: string;
+    /** 查目录后已是最新（本次无替换发生） */
+    upToDate?: boolean;
+}
 /** 插件发现/管理命名空间面——桥接 IpcBridgeHandler → loader 函数 */
 export interface PluginsAPI {
-    /** 插件发现——双端注入：resolvePath 双端同面；读面（listDirs/listDisabledDirs/readManifest）壳 preload 独有（loader 只在壳跑） */
+    /** 插件发现——双端注入：resolvePath 双端同面；读面（listDirs/listAll/readAllManifests/listDisabledDirs/readManifest）壳 preload 独有（loader 只在壳跑） */
     plugins: {
         resolvePath(id: string): Promise<string>;
+        /** E6#7（1.2-4）：resolvePath 的兄弟（discovery 族）——返回 { root, entry, bundle }（bundle 入口恒 index.bundle.js）。
+         *  可选——保 state.ts 守卫与两 preload 面（壳/池）编译不裂；调用方先判存在再调用。 */
+        resolveEntry?(id: string): Promise<PluginEntryInfo>;
         listDirs?(): Promise<string[]>;
+        /** E6#9a：全量发现——[{ pluginId, entry, manifest }]（替代 import.meta.glob；打包插件不在源码树，主进程读盘唯一真源） */
+        listAll?(): Promise<PluginDiscoveryEntry[]>;
         listDisabledDirs?(): Promise<string[]>;
         /** 返回 plugin.json 原始 JSON 文本——消费方自行 JSON.parse */
         readManifest?(id: string): Promise<string>;
+        /** E6#9c：全量 manifest——Record<pluginId, PluginManifest>（pluginManifests eager glob 的 IPC 替代） */
+        readAllManifests?(): Promise<Record<string, PluginManifest>>;
+        /** E6#11/#13（1.2-5）：主进程真下载段——fetch .linkdesk-plugin 包 → {userData}/tmp/<原包名>（壳 preload 独有；loader 包安装流 packageOps 调） */
+        packageDownload?(url: string): Promise<{
+            zipPath: string;
+            sizeBytes?: number;
+        }>;
+        /** E6#11/#13（1.2-5）：主进程真解压段——共享 bundle-zip 语义 → {userData}/plugins/<id>/（2026-09-05 塌平单根；壳 preload 独有；目标已存在拒绝） */
+        packageExtract?(zipPath: string, expectedPluginId?: string): Promise<{
+            pluginId: string;
+            version: string;
+            targetDir: string;
+        }>;
+        /** E6#13b（段 B）：主进程真网络段——fetch marketplace.json → 版本对比（不碰账本——current 由壳传）。prerelease 默认忽略。 */
+        packageUpdateCheck?(pluginId: string, catalogUrl: string, currentVersion?: string): Promise<PluginUpdateCheckResult>;
+        /** E6#13b/c（段 B）：主进程真下载+解压段——下载到 tmp → 解压到 {userData}/tmp/.stage-<id>（id 一致 + 新版>旧版校验，不碰旧目录） */
+        packageStageUpdate?(pluginId: string, source: string, currentVersion?: string): Promise<{
+            pluginId: string;
+            newVersion: string;
+            stagedDir: string;
+        }>;
+        /** E6#13c（段 B）：主进程原子替换段——同卷 rename：target→.bak→staged→target→rm .bak（失败复原旧版） */
+        packageCommitUpdate?(pluginId: string, stagedDir: string): Promise<{
+            pluginId: string;
+            version: string;
+        }>;
     };
     /** 插件管理——桥接 IpcBridgeHandler → loader 函数。池权威（marketplace 插件消费），必选 */
     pluginManager: {
@@ -1068,10 +1169,19 @@ export interface PluginsAPI {
         disable(id: string): Promise<unknown>;
         uninstall(id: string): Promise<unknown>;
         install(path: string): Promise<PluginInstallResult>;
+        /** E6#13（1.2-5）：url/.linkdesk-plugin 包安装流显式名（installPlugin 路由别名；壳与池 preload 双面同款——池经 plugins:call 代理）。进度走 plugin:installProgress 通道 */
+        installWithProgress?(path: string): Promise<PluginInstallResult>;
         reinstall(id: string): Promise<unknown>;
         getDisabled(): Promise<PluginInfoEntry[]>;
         getUninstalled(): Promise<PluginInfoEntry[]>;
         isDisabled(id: string): Promise<boolean>;
+        /** E6#11c（段 B）：安全更新（#11c 原子 + unload 机械路径）——opts: { catalogUrl?（走 check 选最新） | url?（直给更新包） } */
+        update?(pluginId: string, opts?: {
+            catalogUrl?: string;
+            url?: string;
+        }): Promise<PluginUpdateResult>;
+        /** E6#13b（段 B）：只读查更新——有新版返回 downloadUrl（UI 徽标数据源；更新动作走 update） */
+        checkUpdates?(pluginId: string, catalogUrl: string): Promise<PluginUpdateCheckResult>;
         /** E5.7#48：装/卸/重装成功 → 通知主进程全量重扫三表 */
         notifyManifestChanged?(): void;
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linkdesk/contracts",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "LinkDesk 插件契约类型——window.linkdesk.* 全量类型定义（E5.8 契约生成产物）。第三方插件作者唯一合法类型消费路径。",
   "type": "module",
   "types": "./linkdesk.d.ts",