@linkdesk/contracts 0.1.2 → 0.1.4

package/linkdesk.d.ts

@@ -1,7 +1,7 @@
 /**
  * 🔥 linkdesk.d.ts——window.linkdesk 插件 API 契约（自动生成，勿手改）
  *
- * 生成源：src/core/api/linkdesk-api.ts + linkdesk-api/（13 域接口 + types.ts）
+ * 生成源：src/core/api/linkdesk-api.ts + linkdesk-api/（14 域接口 + types.ts）
  *         + src/core/types/ipc/* + src/core/types/pool/*（wire 载荷类型）
  * 生成器：scripts/generate-contract.mjs（Route C——契约类型文件为源，纯类型打包）
  * 改契约源 → 跑 `node scripts/generate-contract.mjs`（npm run check 里 check-contracts 强制）
@@ -105,6 +105,9 @@ export interface CommandsAPI {
         getCommands(): Promise<LinkDeskCommand[]>;
         /** 壳侧插件入口模块级注册（双进程执行壳侧半程）——壳 preload 独有 */
         _executeShellLocal?(id: string, ...args: unknown[]): Promise<unknown>;
+        /** E6#62e 池 preload 独有内部钩——池 renderer 注册 on-command 激活回调（命令 miss → import 属主插件入口）。
+         *  underscore 内部面（对标 _executeShellLocal），非插件作者 API——纯命令插件按需激活的接线位。 */
+        _setCommandMissHandler?(handler: (pluginId: string) => Promise<boolean>): void;
     };
     /** 配置—新名——对标 VS Code vscode.workspace.getConfiguration */
     configuration: {
@@ -376,8 +379,8 @@ export interface PluginToastAction {
 }
 /** 进度通知句柄——progress=true 时 show() 返回 */
 export interface NotificationHandle {
-    /** 更新进度消息 */
-    update(message: string): Promise<void>;
+    /** 更新进度消息 + 可选进度百分比（E6#71i：0-100 确定条；不传 = 不定态动画照常推消息） */
+    update(message: string, percent?: number): Promise<void>;
     /** 完成——关闭进度通知，可选弹完成 toast */
     finish(message?: string): Promise<void>;
     /** 取消——直接关闭，不弹完成 toast */
@@ -433,6 +436,20 @@ export interface DialogOpenOptions {
         extensions: string[];
     }[];
 }
+/** E6#71c 富内容确认打开参数——池插件 → 壳 DialogService（content 视图声明寻址）。
+ *  title/message 兜底——content 视图解析失败时壳回落纯文字确认（弹窗仍出，不静默死）。 */
+export interface DialogContentOpenOptions {
+    /** 兜底标题——content 解析失败回落用；池侧已 t() 解析 */
+    title?: string;
+    /** 兜底正文——同上 */
+    message?: string;
+    /** 内容归属插件（壳经 ViewContainerService.getView 复合寻址） */
+    pluginId: string;
+    /** 内容视图声明 id（contributes.views 注册） */
+    viewId: string;
+    /** 不透明载荷——结构克隆过 IPC，壳不解释，内容视图经 dialogHost.current() 读 */
+    payload?: unknown;
+}
 /** 插件侧条目——对标 VS Code QuickPickItem 三字段（label 第一行左 / description 第一行右 / detail 第二行左） */
 export interface PluginQuickPickItem {
     label: string;
@@ -486,29 +503,6 @@ export interface PoolQuickPickData {
     prefix?: string;
     items: PoolQuickPickItem[];
 }
-/** 行内操作按钮——onClick 闭包留在壳，池只回传 actionId（位置序号）。
- *  E5.8#20-c：改名 PoolToastButton——与 poolActions.ts PoolToastAction（IPC 回传动作）同名，
- *  契约平铺进单文件会声明合并成幽灵复合型；按钮描述型用 Button 后缀消歧。 */
-export interface PoolToastButton {
-    /** 位置序号字符串——壳按 actions[Number(actionId)] 重解析 onClick */
-    actionId: string;
-    label: string;
-    isPrimary?: boolean;
-}
-export interface PoolToastItem {
-    id: string;
-    message: string;
-    /** 壳侧已解析的图标类（codicon + severity 类）——池原样渲染 */
-    iconClass: string;
-    /** 壳侧已 t() 解析的 "来源: xxx"——池原样渲染 */
-    sourceText?: string;
-    actions?: PoolToastButton[];
-}
-export interface PoolToastData {
-    toasts: PoolToastItem[];
-    /** NotificationCenter 打开时壳推 true——池整体隐藏（对标壳 ToastContainer） */
-    suppressed: boolean;
-}
 /**
  * Pool Dialog 哑渲染数据——E5.7#17（浮层归一化设计.md §7）。
  *
@@ -527,10 +521,21 @@ export type PoolDialogData = {
     cancelLabel?: string;
     /** alert 模式——只有确定按钮，无取消/Escape/backdrop 关闭 */
     isAlert: boolean;
+    /** E6#71c 富内容槽——present 时替代 title/message/默认按钮渲染（弹窗机制不变：
+     *  居中/遮罩/Esc/trap/点遮罩取消仍由 DialogHost 提供）。内容 = 插件视图——
+     *  壳不持渲染器，池经 PluginComponent 挂载（仿 FloatingPanel DTO）。payload 不透明——
+     *  壳不解释、池原样持，内容视图经 window.linkdesk.dialogHost.current() 读。 */
+    content?: {
+        pluginId: string;
+        /** 池视图注册表寻址键——loader 运行时附挂（ViewContainerService._renderPath） */
+        renderPath: string;
+        /** 不透明序列化载荷——随打开参数过壳→回池（结构克隆），内容视图取数用 */
+        payload?: unknown;
+    };
 };
 /** 标题栏动作按钮——池渲染 + 回传壳侧重解析业务语义（池零语义，UI 机械知识除外）。
  *  E5.8#20-c：改名 PoolFloatingPanelButton——与 poolActions.ts PoolFloatingPanelAction（IPC 回传动作）
- *  同名，契约平铺进单文件会声明合并成幽灵复合型；按钮描述型用 Button 后缀消歧（poolToast 同款）。 */
+ *  同名，契约平铺进单文件会声明合并成幽灵复合型；按钮描述型用 Button 后缀消歧（契约族命名消歧惯例）。 */
 export interface PoolFloatingPanelButton {
     /** 动作 id——open-in（在主窗口中打开）/ maximize（最大化）/ close（关闭），壳侧重解析 */
     id: string;
@@ -562,18 +567,33 @@ export type PoolFloatingPanelData = {
     /** 语言切换文案重推标记（refreshPanelText）——池仅更新标题/动作渲染，跳过焦点获取（I8-8 首次打开才入焦点） */
     refresh?: boolean;
 };
-/** UI 浮层/菜单/通知命名空间面——对标 VS Code vscode.window + ContextKey + 池内 QuickPick/Toast/Dialog 宿主桥 */
+/** UI 浮层/菜单/通知命名空间面——对标 VS Code vscode.window + ContextKey + 池内 QuickPick/Dialog/FloatingPanel 宿主桥 */
 export interface UiAPI {
-    /** 通知——插件弹出壳侧 toast，对标 VS Code vscode.window.showInformationMessage */
+    /** 通知——插件弹通知（E6#72：唯一通知面 = 铃铛宽通知面板，右下窄卡链路已整删），对标 VS Code vscode.window.showInformationMessage */
     notifications: {
-        /** 弹出通知。progress=true 时返回 ProgressHandle（含 update/finish/cancel）。
+        /** 弹出通知，**一律返回句柄**（含 update/finish/cancel）——E6#73f（S6）句柄隔离：
+         *  此前只在 progress:true 时返回句柄 ⇒ persistent 的失败通知（带 [重试]）撤不下来，
+         *  用户手动重试成功后那条「安装失败」仍长驻，面板变成失败墙（18 档 A3/E4）。
+         *  ⇒ 一条通知只能被**创建它的那个句柄**更新/删除，不管它是不是进度条。
          *  E6#13.5：options.actions 带主动作按钮——点击走壳 executeCommand(action.command, action.args)，
-         *  命令 handler 插件自注册。不传 actions → 无按钮（现状）。error 类自动停留 8s。 */
+         *  命令 handler 插件自注册。不传 actions → 无按钮（现状）。error 类自动停留 8s。
+         *  E6#71j：options.persistent=true 长驻通知——不自动消失、等用户手动点 ×（错误诊断类用）;
+         *  常驻上限**按来源分桶**各 5 条（E6#73f S3），超出顶掉同来源最老的并给汇总提示 */
         show(message: string, options?: {
             type?: "info" | "warning" | "error";
+            /** true → 进度通知：update 可带 0-100 百分比驱动真进度条（E6#71i） */
             progress?: boolean;
+            /** true → 长驻通知：不自动消失（E6#71j）；错误诊断/需用户决定的场景用 */
+            persistent?: boolean;
             actions?: PluginToastAction[];
-        }): Promise<NotificationHandle | undefined>;
+            /** E6#73g（S5）生产者身份 id——**机器读的归属键，不含人类文案**（人类可读名由壳解析）。
+             *  面板**按来源分组**、每组各 5 条常驻配额都以此为键；不传 → 全落「其他」组。
+             *  插件传自己的插件 id；壳自身域用 `app.<域>`（如 `app.update`）。
+             *  ⚠️ **做不到自动注入**——池是单进程共享 realm，所有插件共用同一个 `window.linkdesk`，
+             *  preload 无从知道「这次 show() 是哪个插件的树发的」⇒ **只能作者显式报**。
+             *  ⚠️ 老插件不填就仍然全落「其他」组：这是**新契约**，要作者重新发布才生效。 */
+            source?: string;
+        }): Promise<NotificationHandle>;
     };
     /** E5#69：菜单——插件声明式读写 */
     menu: {
@@ -593,6 +613,11 @@ export interface UiAPI {
         open(opts?: DialogOpenOptions): Promise<string | null>;
         /** 打开文件选择器——返回用户选中路径，取消 → null。安全由主进程控制 */
         openFile(opts?: DialogOpenOptions): Promise<string | null>;
+        /** E6#71c：富内容确认——确认框内容 = 插件自绘视图（content 视图声明寻址 + 不透明 payload）。
+         *  弹窗机制同 confirm（居中/遮罩/Esc/焦点锁/点遮罩取消）；内容排版与按钮由插件视图自画
+         *  （对标 VS Code「对话框是壳、内容插件定」）。title/message 兜底——content 视图解析
+         *  失败时壳回落纯文字确认（弹窗仍出，不静默死）。返回 true = 确认，false = 取消/关闭。 */
+        confirmContent(options: DialogContentOpenOptions): Promise<boolean>;
     };
     /** E5.7#63：插件 quickPick 选择器——池内本地桥（零 IPC，QuickPickHost 渲染）。结算 null → undefined */
     quickPick: {
@@ -607,16 +632,13 @@ export interface UiAPI {
         close(): void;
         itemAction(key: string, actionId: string): void;
     };
-    /** E5.7#16：Toast 哑渲染订阅——池 ToastHost 消费（壳 preload 无此面） */
-    toast: {
-        onShow(cb: (data: PoolToastData) => void): () => void;
-        dismiss(id: string): void;
-        action(id: string, actionId: string): void;
-    };
     /** E5.7#17：Dialog 哑渲染订阅——池 DialogHost 消费（壳 preload 无此面）。命名 dialogHost——
      * dialog 命名空间已是插件侧 confirm/alert/open API */
     dialogHost: {
         onShow(cb: (data: PoolDialogData) => void): () => void;
+        /** E6#71c：当前打开的 Dialog 数据——富内容视图挂载后经 dialogHost.current()?.content?.payload
+         *  取数（content 模式才可读；无打开/已关闭 → null）。壳 preload 无此面（池内本地读）。 */
+        current(): PoolDialogData | null;
         confirm(): void;
         cancel(): void;
     };
@@ -954,13 +976,19 @@ export interface PluginManifest {
     version: string;
     icon?: string;
     iconSource?: "codicon" | "svg" | "url" | "lucide";
+    /** 市场展示图（cover art，14 档案双图标模型 E6#67）——svg 资产相对路径，可画得讲究复杂
+     *  （与 icon 的「界面单色小图标」语义分开：壳图标栏/标签栏只读 icon）。缺省 → 市场回退用 icon。
+     *  惯例：值 = 包内资源相对路径（如 "resources/cover.svg"）、iconSource 省略 → linkdesk:// 路径推断。 */
+    marketIcon?: string;
+    marketIconSource?: "codicon" | "svg" | "url" | "lucide";
     description?: string;
     author?: string;
     entry?: string;
     sidebar?: string;
     tabBehavior?: TabBehavior;
     /** 系统插槽角色——声明此插件填充哪个系统级功能。settings=设置页，marketplace=插件市场。
-     *  多个插件声明同一 role → 第一个 core: true 的胜出。
+     *  同一 role 多插件合法并存（一对多，全收进槽位候选）；默认 = 首注册稳定序
+     *  （E6#18b：core:true 无行为特权，不抢默认），用户切换的活动套持久化保持。
      *  E5.7#65：开放 string——第三方可声明新角色名，壳零改动（FactorySlots 按字符串查表）。 */
     factoryRole?: string;
     statusBar?: StatusBarItem[];
@@ -992,19 +1020,8 @@ export interface PluginManifest {
      *  纯声明：无版本约束（版本语义属 E6 市场范畴，激活顺序不承载）；缺依赖 → loader 状态机挂 PENDING。
      *  与 ConfigurationRegistry 的配置项级 dependsOn（同一 manifest 内某配置项依赖另一配置项）不同域。 */
     requires?: string[];
-    changelog?: {
-        version: string;
-        date: string;
-        changes?: string[];
-    }[];
     screenshots?: string[];
     minAppVersion?: string;
-    /** 激活事件——对标 VS Code activationEvents。空或含 "*" = 启动时立即加载。
-     *  具体事件（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 落地迁移。 */
     extensionDependencies?: string[];
@@ -1027,7 +1044,12 @@ export interface PluginManifest {
         iconBar?: "top" | "bottom";
         sidePanel?: boolean;
         tabBar?: boolean;
-        statusBar?: boolean;
+        /** 自绘（代码）状态栏组件文件路径（相对插件根，.tsx）——存在 + 文件二合一声明（对标视图 render）。
+         *  有值 = 插件自绘状态栏组件取代其静态 statusBar 贡献项；loader 注册时 resolveRuntimePluginRoot
+         *  归一 → ViewPluginEntry.statusBarRenderPath（dev /@fs 源码 / prod linkdesk:// dist，SDK 打包后
+         *  此字段改写为 statusBar.bundle.js 编译表面），壳发 component marker → 池直动态 import（E6#62d）。
+         *  缺省 = 无自绘组件（静态贡献项照常）。 */
+        statusBar?: string;
     };
     /** @deprecated E5#14——用 appearsIn.iconBar 替代。仅 viewRegistry.ts 向后兼容兜底。 */
     iconLocation?: "top" | "bottom";
@@ -1064,6 +1086,15 @@ export interface PluginDiscoveryEntry {
         subdir: string | null;
     };
 }
+/** E6#73c：安装进度的 job 身份——壳侧 `installPlugin` 调主进程 fs/net 段（download/extract）时随行，
+ *  主进程段据此把 `plugin:installProgress` 事件回填到**具体的 job/插件**（18 档 §五 I.6③ 的「事件侧回填」）。
+ *  此前下载/解压段的事件**不带任何身份**，多单并行时百分比互相灌进同一行；N=1 时靠「归活跃会话」侥幸正确。
+ *  `jobId` 是壳侧 job 表的产物（单一生产者，见 install-queue.ts）——主进程只透传，不生成、不持久化。 */
+export interface PluginInstallJobRef {
+    jobId: string;
+    /** 池侧请求已带 id 时同带——下载段靠它把进度归到具体插件（待解压才知 id 的包流只有 jobId） */
+    pluginId?: string;
+}
 /** E6#13b（段 B）：pluginManager.checkUpdates 返回——主进程 fetch catalog + semver 对比（壳传 current，壳是账本/磁盘 owner） */
 export interface PluginUpdateCheckResult {
     current: string;
@@ -1071,7 +1102,11 @@ export interface PluginUpdateCheckResult {
     downloadUrl?: string;
     update: boolean;
 }
-/** list() 的 manifest 序列化子集——与 handlePluginsCall "list" 7 字段对齐 */
+/** list() 的 manifest 序列化子集——与 handlePluginsCall "list" 投影字段对齐
+ *  E6#30.5e/30.6c3：声明依赖 id 列表（manifest.requires 透传）——marketplace 判缺依赖 + 依赖/被依赖行
+ *  数据源（dependencies.ts 引擎只壳内；消费经 list() 投影）。无 requires = undefined。
+ *  E6#65a（14 档案批次一）：+ icon/iconSource——市场行/详情图标的数据通道（注释自认的"7 字段对齐"
+ *  原取舍现在市场要图标，属同通道需扩，见 IpcBridgeHandler/pluginManager.ts list 投影同步）。 */
 export interface PluginListSubset {
     name?: string;
     description?: string;
@@ -1080,6 +1115,17 @@ export interface PluginListSubset {
     author?: string;
     statusBar?: PluginManifest["statusBar"];
     contributes?: PluginManifest["contributes"];
+    requires?: string[];
+    // E6#65a（14 档案批次一数据通道）：icon/iconSource 透传——市场拿到插件图标
+    // （行/详情 PluginIcon 渲染的唯一 manifest 数据源；无图标 = undefined → 消费端默认图兜底）。
+    // 与 E5.8#37.9.1 同构：list() 子集继续只挑 UI 消费字段，不整 manifest 过 IPC。
+    icon?: PluginManifest["icon"];
+    iconSource?: PluginManifest["iconSource"];
+    // E6#67（14 档案批次二·五）：marketIcon/marketIconSource 透传——市场展示图（cover art）数据通道。
+    // 市场消费「marketIcon ?? icon」在 marketplace 层 pick（壳界面只读 icon，故 list 一并透传两对）；
+    // 无 marketIcon = undefined → 市场回退 icon，再空 → 默认封面。
+    marketIcon?: PluginManifest["marketIcon"];
+    marketIconSource?: PluginManifest["marketIconSource"];
 }
 /** 插件列表条目——pluginManager.list() 返回（主进程序列化后的 manifest 子集）。
  *  E5.7#98：Partial<PluginManifest> 过宽（component 等字段 IPC 不可达）——收窄为
@@ -1091,6 +1137,24 @@ export interface PluginListEntry {
     manifest: PluginListSubset;
     /** 缺依赖挂起原因——marketplace 显示 PENDING 徽标 + 详情提示条（E5.8#15.5） */
     pendingReason?: string;
+    /** E6#73j（G6）：该插件**住哪**——`true` = 在用户安装家（`{userData}/plugins`），可被下载来的新包替换。
+     *  `false` = 只读 app 根（随包发货件 / 目录源安装的插件）——更新流对它必然抛「不在用户安装区」，
+     *  市场**不得**渲染「更新到 vX」（那是点下去必失败的死钮，含 8 只官方随包插件在内）。
+     *  判据唯一源 = `isPluginUpdatable`（磁盘住所事实，非插件身份——硬约束 11）。 */
+    updatable?: boolean;
+}
+/** E6#73q：安装请求侧身份——job 表按 pluginId 去重、job 行要显示名，而两者都只有池侧知道
+ *  （显示名今天只存在于池侧目录 store，壳拿不到）。
+ *  jobId **不在这里**：它是壳侧 job 表的产物（单一生产者），池侧从 `plugin:installJobs` 广播里认领。 */
+export interface PluginInstallRequestOpts {
+    /** 账本来源（add 的 source）；缺省 user */
+    ledgerSource?: "user" | "marketplace";
+    /** 插件 id——job 表去重键 + 广播载荷的 pluginId；池侧目录条目已知者传入 */
+    pluginId?: string;
+    /** 显示名——job 行文案；不传则退化为 pluginId */
+    displayName?: string;
+    /** job 出身——行 = 一次用户动作（user，缺省）；插件拖来的依赖（dependency）藏在那一行里 */
+    origin?: "user" | "dependency";
 }
 /** E5.7#81：安装结果——success:false 时 error 为中文失败原因（校验 / 版本冲突 / 复制失败）。
  *  安装进度事件：events.on("plugin:installProgress", ({ stage, pluginId, message }) => ...)
@@ -1104,13 +1168,27 @@ export interface PluginInstallResult {
     version?: string;
     needRestart?: boolean;
     error?: string;
-}
-/** 禁用/卸载列表条目——loader getDisabledPluginInfo/getUninstalledPluginInfo 序列化形状（PluginListSubset 的再子集） */
+    /** E6#73q（18 档 §五 I.6⑦）：第三类终态——**已安装但缺依赖**（装上去了，插件在列表里，但不可用）。
+     *  为真时 success 也是 true（文件真落盘了），但消费方**不得渲染成「✓ 已安装」**——那是撒谎。
+     *  job 行显示「已安装但缺依赖：{名}」。 */
+    parked?: boolean;
+    /** E6#73d：用户在面板上点了「取消安装」——**不是失败**（`success` 为 false 只是「没装成」）。
+     *  消费方据此**不得**走失败分支（不弹错误 toast、不推 [重试]、不打红行）——用户主动叫停已表明意图，
+     *  再报一次错等于拿用户自己的决定去吓他。job 行由队列侧**整条撤掉**（不渲染 ✗）。 */
+    cancelled?: boolean;
+}
+/** 禁用/卸载列表条目——loader getDisabledPluginInfo/getUninstalledPluginInfo 序列化形状（PluginListSubset 的再子集）
+ *  E6#30.5b：core 旗标透传——list() EXCLUDES 禁用插件，禁用态详情页卸载钮守 E6#18「core:true 详情页不画」
+ *  只能经此拿到 core（缓存 manifest 内取值，纯新增可选字段零回归）。 */
 export interface PluginInfoEntry {
     pluginId: string;
     name: string;
     description?: string;
     version?: string;
+    core?: boolean;
+    /** E6#73j（G6）：同 `PluginListEntry.updatable` 的住所判据——禁用**不改住所**（disable 只记名单，
+     *  目录原地不动）⇒ userData 家的禁用插件照样可更新，app 树的则否。 */
+    updatable?: boolean;
 }
 /** E6#11c/#13b（段 B）：更新结果——PluginInstallResult 的更新扩展。
  *  upToDate = catalog 直答已是最新（success:true 但非"更新发生"——UI 显示"已是最新"非红错误）；
@@ -1137,21 +1215,30 @@ export interface PluginsAPI {
         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<{
+        /** E6#11/#13（1.2-5）：主进程真下载段——fetch .linkdesk-plugin 包 → {userData}/tmp/<原包名>（壳 preload 独有；loader 包安装流 packageOps 调）。
+         *  E6#73c：可带 job 身份——主进程段的进度事件据此回填 jobId/pluginId（缺省 = 事件不带身份，N=1 时归活跃会话） */
+        packageDownload?(url: string, job?: PluginInstallJobRef): 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<{
+        /** E6#11/#13（1.2-5）：主进程真解压段——共享 bundle-zip 语义 → {userData}/plugins/<id>/（2026-09-05 塌平单根；壳 preload 独有；目标已存在拒绝）。
+         *  E6#73c：job 同 packageDownload——解压段进度事件回填身份 */
+        packageExtract?(zipPath: string, expectedPluginId?: string, job?: PluginInstallJobRef): Promise<{
             pluginId: string;
             version: string;
             targetDir: string;
         }>;
+        /** E6#73d：按 jobId 中止在途下载——面板「取消安装」的唯一落点。
+         *  AbortSignal 不可跨 IPC（结构化克隆拒绝），只能发这条**定向消息**；主进程只持
+         *  jobId → AbortController 登记表，不解释语义。返回 false = 该 job 当前没有在途下载
+         *  （已下完/未开始/非下载段）——调用方按「取消已受理，等终态」理解，不当失败。 */
+        packageCancel?(jobId: string): Promise<boolean>;
         /** 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<{
+        /** E6#13b/c（段 B）：主进程真下载+解压段——下载到 tmp → 解压到 {userData}/tmp/.stage-<id>（id 一致 + 版本方向校验，不碰旧目录）。
+         *  E6#33c（锚①）：allowOlder 显式 true 放行「包内版本 < 当前」的降级（版本下拉选旧版 + F2 确认后传）；默认仍拒 <=；同版恒拒。
+         *  E6#73j（G1）：job 同 packageDownload——更新下载段的进度按 jobId 归行，并按 jobId 可真中止。 */
+        packageStageUpdate?(pluginId: string, source: string, currentVersion?: string, allowOlder?: boolean, job?: PluginInstallJobRef): Promise<{
             pluginId: string;
             newVersion: string;
             stagedDir: string;
@@ -1168,17 +1255,20 @@ export interface PluginsAPI {
         enable(id: string): Promise<unknown>;
         disable(id: string): Promise<unknown>;
         uninstall(id: string): Promise<unknown>;
-        install(path: string): Promise<PluginInstallResult>;
+        /** E6#73q：opts 携带请求侧身份（pluginId/displayName/origin）——job 表去重 + job 行显示名 */
+        install(path: string, opts?: PluginInstallRequestOpts): Promise<PluginInstallResult>;
         /** E6#13（1.2-5）：url/.linkdesk-plugin 包安装流显式名（installPlugin 路由别名；壳与池 preload 双面同款——池经 plugins:call 代理）。进度走 plugin:installProgress 通道 */
-        installWithProgress?(path: string): Promise<PluginInstallResult>;
+        installWithProgress?(path: string, opts?: PluginInstallRequestOpts): 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?（直给更新包） } */
+        /** E6#11c（段 B）：安全更新（#11c 原子 + unload 机械路径）——opts: { catalogUrl?（走 check 选最新） | url?（直给更新包） }。
+         *  E6#33c（锚①）：allowOlder 显式 true 放行降级（版本下拉选旧版 + F2 确认后传）；默认拒 <=。 */
         update?(pluginId: string, opts?: {
             catalogUrl?: string;
             url?: string;
+            allowOlder?: boolean;
         }): Promise<PluginUpdateResult>;
         /** E6#13b（段 B）：只读查更新——有新版返回 downloadUrl（UI 徽标数据源；更新动作走 update） */
         checkUpdates?(pluginId: string, catalogUrl: string): Promise<PluginUpdateCheckResult>;
@@ -1257,7 +1347,8 @@ export interface TitleBarLayout {
         unpin: string;
     };
 }
-/** 图标栏图标——壳 resolvePluginIcon 序列化（池不 import pluginLoader，Lucide 名由池映射组件渲染） */
+/** 池侧图标——壳序列化（池不 import pluginLoader，Lucide 名由池映射组件渲染）。
+ *  图标栏 + 标签栏共用（E6#69f 标签栏视图标签 / #69g 文件标签走同一联合） */
 export type IconBarIcon = {
     kind: "lucide";
     name: string;
@@ -1265,11 +1356,12 @@ export type IconBarIcon = {
  | {
     kind: "codicon";
     name: string;
-} // codicon CSS 类
+    color?: string;
+} // codicon CSS 类（可选每图标色——文件图标主题数据，E6#69g）
  | {
     kind: "img";
     src: string;
-} // linkdesk:// 协议 URL
+} // linkdesk:// 协议 URL / data URI
  | {
     kind: "emoji";
     text: string;
@@ -1347,8 +1439,8 @@ export type TitleActionWidget =
 export interface SidebarViewMeta {
     id: string; // view ID（"folders" / "search" / "installed"）
     title: string; // 显示标题
-    pluginId: string; // _pluginId——PluginComponent 用它找 import.meta.glob
-    renderPath: string; // loader.ts 构建的 glob key——池 O(1) 查找 view 组件
+    pluginId: string; // _pluginId——PluginComponent 用它定位插件根（resolvePath IPC）
+    renderPath: string; // _renderPath 归一化 URL（dev /@fs | prod linkdesk://）——池直动态 import（E6#62b）
     role?: "toolbar" | "section"; // 默认 "section"
     order?: number;
     collapsed?: boolean; // 插件声明的初始折叠态（collapsed: true）
@@ -1427,8 +1519,9 @@ export interface PoolTab {
     sourceId?: string;
     dirty?: boolean;
     // 🆕 E5.6#16.5：TabBar 渲染所需元数据
-    /** 插件图标 URL——getAssetPath() 解析后的路径 */
-    icon?: string;
+    /** 标签图标——IconBarIcon 判别联合（E6#69f/#69g：视图标签 = Type-2 身份图 img；文件标签 = 文件类型图标
+     *  codicon/img。壳 serializeGroups 现场解析，池哑渲染——此前仅 emoji/img string，codicon/lucide 标签落空） */
+    icon?: IconBarIcon;
     /** 固定标签页（对标 VS Code pinned tabs） */
     pinned?: boolean;
     /** 标签页关闭行为——from plugin.json tabBehavior.closeBehavior */
@@ -1441,6 +1534,14 @@ export interface PoolTab {
     shellType?: string;
     /** plugin-detail 视图的目标插件 ID（哪个插件的详情页） */
     detailPluginId?: string;
+    /** E6#30.10b：plugin-detail 主区贡献视图的宿主插件 ID（factorySlots 活跃 marketplace 插件——贡献
+     *  渲染面的是它，≠ detailPluginId）。壳 serializeGroups 现场解析盖章，池宿主加载贡献模块用（resolvePath
+     *  要贡献插件根）；无活跃市场插件 → undefined = 无贡献。 */
+    detailContributorId?: string;
+    /** E6#30.10b：plugin-detail 主区贡献视图 renderPath——活跃 marketplace 插件 contributes.views.main[]
+     *  "plugin-detail" 声明的 _renderPath。壳 serializeGroups 现场解析盖章；池 ShellViewRenderer 消费：
+     *  有 → 动态 import 市场 DetailView，缺/加载失败 → 壳 PluginDetailPoolView 保底。 */
+    detailViewRenderPath?: string;
 }
 /** 分屏组——每个 group 占一个 flex 区域，内含 N 个 keep-alive 标签页 */
 export interface PoolGroup {
@@ -1548,11 +1649,48 @@ export interface PoolStatusBarItem {
     align: "left" | "right";
     /** 点击执行的命令 ID */
     onClick?: string;
-    /** 插件有 statusBarComponent——池侧懒加载渲染（serial-monitor TX/RX 实时计数） */
-    component?: boolean;
+    /** 自绘状态栏组件 marker——插件声明 appearsIn.statusBar 的归一化 URL（E6#62d：loader 注册时
+     *  算 ViewPluginEntry.statusBarRenderPath，壳读此发 marker）→ 池按 URL 直动态 import（serial-monitor 连接灯）。
+     *  有值 = 自绘组件取代该插件全部静态项；无 = 普通条目。 */
+    componentRenderPath?: string;
     /** 前导分隔线——壳 StatusBar 渲染语义（左区每项除首个；右区组内除首个） */
     dividerBefore?: boolean;
 }
+/**
+ * E6#73d：安装 job 的行——面板「进行中 / 等待安装中」两段的**唯一**行形状（18 档 §五 I.4）。
+ *
+ * **为什么结果区不在这里**：安装终态（成功 / 失败 / 已安装但缺依赖）由既有的 toast 发声
+ * （成功 = lifecycle 消费端唯一口，失败 = settle 失败 toast 带 [重试]，见 73h/73e），
+ * 结果区仍按来源分组（`NotifGroup`）。job 行只在「还没有结果」的两段里出现——
+ * 一条安装永远只在一处可见，不会「装了两遍」。
+ */
+export interface NotifJobRow {
+    /** 行 key——jobId（**不是**显示名：同名不同插件要能区分，18 档 §七 73d 行）。 */
+    id: string;
+    pluginId: string;
+    /** 显示名（壳侧解析：调用方带入，或解压后从包内 manifest 回填） */
+    name: string;
+    /** 状态字形 codicon 类串（⟳ 进行中 / ○ 等待中） */
+    iconClass: string;
+    /** 右端状态短语（壳 t() 已解析，如「下载中 62%」「等待安装中」）——池哑渲染 */
+    statusLabel: string;
+    /** 下载段有真值才有 → 池画 3px 确定态进度条；缺省不画（同 NotifItem.percent 语义）。 */
+    percent?: number;
+    /** 本行能不能取消——true 时池渲染 [取消安装] 按钮 */
+    cancellable?: boolean;
+    /** [取消安装] 按钮文案（壳 t()） */
+    cancelLabel?: string;
+}
+/** E6#73d：安装 job 段——面板固定三段里前两段的容器（顺序永不重排，§五 I.4） */
+export interface NotifSection {
+    /** "running" | "queued"——段身份（池不做判别，只当 key 用） */
+    key: string;
+    /** 段标题（壳 t()，如「3 项进行中」「另有 4 项等待安装中」） */
+    label: string;
+    items: NotifJobRow[];
+    /** 段内超出「每段 5 条」被折叠的说明（壳 t()）——缺省 = 没折叠过 */
+    foldedLabel?: string;
+}
 /** 通知动作——壳 ToastAction 序列化（onClick 是壳侧闭包——池点击回传壳执行） */
 export interface NotifAction {
     label: string;
@@ -1569,6 +1707,12 @@ export interface NotifItem {
     /** 壳 t("来源: {{source}}")——无 source 则缺省 */
     sourceLabel?: string;
     actions: NotifAction[];
+    /** E6#72c：进度类通知——池据此画 3px 进度行（缺省 = 非进度通知，不画）。
+     *  progress 由壳 toast 存储直通（pushToast/updateToast 的 progress 旗标）。 */
+    progress?: boolean;
+    /** E6#72c：确定态百分比 0-100——有值画定宽填充，无值画不定态扫动（对标 E3e 原版语义）。
+     *  池侧渲染时自行钳位（壳不作保证——契约宽容，畸形值不撑破布局）。 */
+    percent?: number;
 }
 /** 通知分组——壳 NotificationCenter buildSourceGroups（source 第一段归类 + 未读排序） */
 export interface NotifGroup {
@@ -1577,6 +1721,10 @@ export interface NotifGroup {
     label: string;
     unread: number;
     items: NotifItem[];
+    /** E6#73f（S3/A6）：本组因超过「每来源 5 条」上限被淘汰折叠掉的**说明文案**（壳侧 t() 已解析，
+     *  池哑渲染——同 timeLabel/sourceLabel/clearLabel 的「显示文本铁律」）。
+     *  缺省 = 没折叠过（契约宽容——旧快照/测试替身不填此字段时行为不变，不渲染该行）。 */
+    foldedLabel?: string;
 }
 /** 通知中心数据——壳侧序列化（未读计数/文案/分组全壳侧完成） */
 export interface NotifLayout {
@@ -1584,10 +1732,31 @@ export interface NotifLayout {
     /** 铃铛 tooltip——t("{{count}} 条通知") / t("通知") */
     bellTitle: string;
     panelTitle: string;
+    /** E6#73a：头部「清除已完成」按钮文案——只清**已出结果且已读**的旧消息，面板不关、进行中的一条不碰。 */
     clearLabel: string;
+    /** E6#73a：头部「最小化」按钮文案——关闭面板的**唯一**动作（语义 = 收起，什么都不丢）。 */
+    minimizeLabel: string;
     emptyLabel: string;
     dismissTitle: string;
+    /** E6#73d：头部摘要（「3 项进行中 · 另有 4 项等待安装中」）——**没有安装 job 时缺省不渲染**。
+     *  ⚠️ 只报**进行中 / 等待中**两个数：不写「已完成 N/M」——装了没有不由进度条消失来判定
+     *  （18 档 §七 73d 行明令）。 */
+    summaryLabel?: string;
+    /** E6#73d：安装 job 两段（进行中 → 等待安装中），固定序排在结果区之前。
+     *  缺省 = 没有在途安装（契约宽容——旧快照/测试替身不填此字段时行为不变，不渲染这两段）。 */
+    sections?: NotifSection[];
+    /** E6#73d：第三段固定标题「已有结果」（§五 I.4 三段永不重排）。
+     *  结果**行**不在这里——它们是既有的按来源分组的 toast（见 NotifJobRow 注释）；
+     *  本字段只提供那一区上方的固定标题。缺省 = 没有安装活动（不渲染该标题，避免纯通知场景凭空多一行）。 */
+    resultLabel?: string;
+    /** 第三段标题右端的计数（「1 项失败 · 3 项已完成」）——数**安装 job 的终态**，不是数面板上的行：
+     *  行会被 TTL 收走/被来源折叠，用它计数会让摘要随无关动作跳变（18 档 §五 I.4 的样例即此计数）。 */
+    resultSummary?: string;
     groups: NotifGroup[];
+    /** E6#72d：自动展开请求——壳判定「存在重要且未读的通知，且面板当前是关着的」时为 true。
+     *  池侧只做 **false→true 边沿触发**（置面板为开），true 持续期间不反复动作；
+     *  缺省 = 不自动展开（契约宽容——旧快照/测试替身不填此字段时行为不变）。 */
+    autoOpen?: boolean;
 }
 /** 状态栏布局——Phase 2 #8 StatusBarZone 消费 */
 export interface StatusBarLayout {
@@ -1758,9 +1927,10 @@ export interface TabDragPositionPayload {
      *  窗外 → 主进程 OS 幽灵显示（DOM 浮块出窗被裁剪）；窗内 → OS 幽灵隐藏（DOM 浮块可见）。壳/吸附忽略此字段 */
     outside?: boolean;
     /** E5.8#46.19 进化：拖拽幽灵外观——主题三色（源池 getComputedStyle 读 --bg-card/--border/--text-primary，
-     *  均为纯 hex 值）+ 被拖标签图标（tab.icon：emoji 字符或 getAssetPath 解析的图片 URL，iconKind 区分渲染）。
+     *  均为纯 hex 值）+ 被拖标签图标（E6#69g：池把 tab.icon 判别联合裁成幽灵窗可渲染形态——emoji 文本或 img
+     *  URL；codicon/lucide 无字形字体注入 → null，iconKind 区分渲染）。
      *  仅 outside=true（窗外）时主进程消费；壳/吸附忽略此字段。可选用——旧池不带上限。
-     *  iconKind 判定与 DragOverlays 浮块同款（emoji：len≤2 且命中 emoji 正则；img：其余一律当图片 URL）。 */
+     *  iconKind 判定与 DragOverlays 浮块同款（emoji：直渲文本；img：图片 URL）。 */
     ghost?: {
         theme: {
             bg: string;
@@ -1797,12 +1967,6 @@ export interface PoolQuickPickAction {
     key?: string;
     actionId?: string;
 }
-/** Toast 动作——dismiss/action 按 id + actionId 回传 */
-export interface PoolToastAction {
-    type: string;
-    id: string;
-    actionId?: string;
-}
 /** Dialog 动作——confirm/cancel 回传，壳侧 settle Promise */
 export interface PoolDialogAction {
     type: string;
@@ -1838,6 +2002,18 @@ export interface PoolWindowBoundsPayload {
     windowId: string;
     bounds: WindowBounds;
 }
+/** E6#78：插件磁盘位置——市场详情页「打开所在位置 / 数据位置」两行的数据源。
+ *  主进程解析（池内**零**安装路径知识——渲染侧只拿结果，不拼路径）。 */
+export interface PluginDiskLocation {
+    /** 插件目录绝对路径（正斜杠——与 `plugins.resolvePath` 同规；消费端用作链接 tooltip，不自行拼接） */
+    installDir: string;
+    /** 插件数据目录——**只有该插件真有数据时才非空**（目录不存在或空 → null）。
+     *  与 VS Code 详情页「缓存」行同判据（`computeSize` 后 `if (!cacheSize) return`——空则整行不显示）：
+     *  纯 UI 插件恒 null，**不是人人都有**，故不造空行。 */
+    dataDir: string | null;
+}
+/** E6#78：`shell.openPluginFolder` 的两枚落点——安装目录 / 数据目录 */
+export type PluginFolderKind = "install" | "data";
 /** 壳↔插件中继/池控制/窗口/壳级命令/热退出暂存命名空间面——双端注入面（bridge 真壳独有 / hotExit 池侧独有） */
 export interface ShellAPI {
     /** 壳↔插件通信中继——壳 preload 独有 */
@@ -1868,8 +2044,6 @@ export interface ShellAPI {
         onAdsorbIndex(cb: (payload: AdsorbIndexPayload) => void): () => void;
         pushQuickPick(data: unknown): void;
         onQuickPickAction(cb: (action: PoolQuickPickAction) => void): () => void;
-        pushToast(data: unknown): void;
-        onToastAction(cb: (action: PoolToastAction) => void): () => void;
         pushDialog(data: unknown): void;
         onDialogAction(cb: (action: PoolDialogAction) => void): () => void;
         // E5.8#37（Phase 8 类型 B）：壳内悬浮面板——pushPanel 哑渲染数据 + 动作回传
@@ -1921,11 +2095,26 @@ export interface ShellAPI {
         isAlwaysOnTop(): Promise<boolean>;
         onAlwaysOnTopChange(cb: (pinned: boolean) => void): () => void;
     };
-    /** 壳级命令——revealInOS / openInTerminal / startDrag，双端注入 */
+    /** 壳级命令——revealInOS / openInTerminal / startDrag / relaunch，双端注入 */
     shell: {
         showItemInFolder(p: string): Promise<void>;
         openInTerminal(dirPath: string, terminalExe?: string, customCommand?: string): Promise<void>;
+        /** E6#78：已装插件的磁盘位置——市场详情页「打开所在位置 / 数据位置」的**判据**数据源
+         *  （是否有数据目录决定那行画不画）。主进程解析（池内零安装路径知识）；盘上找不到该插件 → null。
+         *  ⚠️ 与 `shell.showItemInFolder(p)` 的分工：**那个要路径、这个给身份**——调用方（市场）拿不到也不该拼绝对路径。 */
+        pluginLocation(pluginId: string): Promise<PluginDiskLocation | null>;
+        /** E6#78：资源管理器打开插件的安装目录 / 数据目录——主进程解析路径后 `shell.openPath`。
+         *  开的是目录**内容**（与 E5.8#153 `appearance.revealStorage`「打开存储位置」同一手感），
+         *  **不是** `showItemInFolder` 的「父目录 + 选中它」。目录不存在时：`install` 抛错（插件不在盘上，
+         *  不假装打开成功）；`data` 先建空目录再开（同 revealStorage——打开即见存储位置，空目录同样合法）。 */
+        openPluginFolder(pluginId: string, kind: PluginFolderKind): Promise<void>;
         startDrag(filePath: string, iconPath?: string): void;
+        /** E6#73j（G4）：**真重启应用**（退出并重新启动进程）。
+         *  与 `window.location.reload()` 的区别是「池在不在」——池是独立的 WebContentsView，壳 reload 不重建它，
+         *  更新视图类插件后池里跑的仍是旧 bundle（界面看起来毫无变化）。
+         *  诚实边界：整个应用会退出再起——未保存的编辑器内容由热退出（hotExit）负责，工作区布局走持久化恢复。
+         *  壳 preload 独有（池不需要自己重启宿主）；调用后本进程随即终止，不要再依赖它的返回。 */
+        relaunch?(): Promise<void>;
     };
     /** 热退出暂存——编辑器未保存内容落盘（E5.7#53）。`?`：池侧独有（壳 preload 不注入） */
     hotExit?: {
@@ -1991,6 +2180,21 @@ export interface FactorySlotsAPI {
         setActive(role: string, pluginId: string): Promise<void>;
     };
 }
+/**
+ * linkdesk-api app 域——主软件产品身份只读面（E6#57，06-主软件更新）。
+ * 自 linkdesk-api.ts 拆出（E6#57.2a）——第 14 个命名空间域接口。
+ * 依赖方向：app → 无（纯函数签名，零类型依赖）；被聚合器交叉组装。
+ *
+ * 暴露边界（00-README §三② 2026-08-30 拍板）：只读不写——版本号给第三方可读（市场 minAppVersion
+ * 校验 E6#30.8c 消费），更新写命令（下载/重启）是壳私事不开放。ProductInfo（app:getProductInfo
+ * 全量身份）非第三方插件面——主软件产品内部（关于页 E6#57.14）用，不进本契约（见 electron/product.ts）。
+ */
+export interface AppAPI {
+    /** app 命名空间——只读产品身份。版本号唯一运行时来源 = 主进程 app.getVersion()（package.json 单点，02 §2.3）。 */
+    app: {
+        getVersion(): Promise<string>;
+    };
+}
 /**
  * linkdesk API——插件代码的类型安全入口。
  * 对标 VS Code `vscode` 对象的全局命名空间结构。
@@ -2000,7 +2204,7 @@ export interface FactorySlotsAPI {
  * E5.8#0d.10-9e：由 12 个命名空间域接口交叉组装（interface→type intersection，
  * 索引访问 LinkDeskAPI["pool"]/["configuration"] 等消费方契约不变）。
  */
-export type LinkDeskAPI = CommandsAPI & AppearanceAPI & TabsAPI & KeybindingsAPI & UiAPI & DataAPI & WorkspaceAPI & EditorAPI & PluginsAPI & ShellAPI & PanelAPI & SettingsAPI & FactorySlotsAPI;
+export type LinkDeskAPI = CommandsAPI & AppearanceAPI & TabsAPI & KeybindingsAPI & UiAPI & DataAPI & WorkspaceAPI & EditorAPI & PluginsAPI & ShellAPI & PanelAPI & SettingsAPI & FactorySlotsAPI & AppAPI;
 /** 图标映射条目——字体 glyph 形态（单色/带色字体，seti 类每图标一色；codicon 即保底单色） */
 export interface IconThemeGlyph {
     /** CSS 类名（codicon 保底 / 自定义图标字体资产） */

package/package.json

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