@mbws/plugin-sdk 0.2.4 → 0.3.0

package/dist/caps.d.ts

@@ -0,0 +1,97 @@
+/**
+ * caps 能力面协议类型——附件执行/上传查询的共享契约（SDK 客户端 / 宿主 broker / 桌面桥共用）。
+ *
+ * 模型（docs/plan §7.6 偏离记录）：开放附件声明 + 完整执行权。宿主不关心附件是什么，
+ * 职责收缩为四件事——下载校验、执行通道、进度/取消、产物登记。插件开发者 shell 级
+ * 驱动附件（任意 args），字节不过协议通道（输入 localize 进沙箱、产物宿主代传）。
+ *
+ * 命名空间固定两个（附件种类开放，不按附件分命名空间）：
+ * - caps.exec   —— 附件 ensure/状态 + 输入本地化 + spawn 长任务 + 产物登记 + 媒体预览（有 attachments 声明才授予）
+ * - caps.uploads —— 上传队列状态查询（桌面宿主恒授）
+ */
+/** 附件状态机（宿主侧 attachment-store 的投影）。 */
+export interface AttachmentState {
+    name: string;
+    /** missing → downloading → verifying → ready；failed 附 message */
+    status: "missing" | "downloading" | "verifying" | "ready" | "failed";
+    version?: string;
+    sha256?: string;
+    /** 下载进度 0..1（downloading 时有值） */
+    ratio?: number;
+    message?: string;
+}
+/** 子进程行流事件（宿主 100ms 节流合并后下发）。 */
+export interface CapsJobLine {
+    stream: "stdout" | "stderr";
+    text: string;
+}
+/** `mbws:event { event: "job" }` 的 payload 形状。 */
+export interface CapsJobEvent {
+    jobId: string;
+    kind: "lines" | "exit";
+    /** kind=lines：节流合并的行批 */
+    lines?: CapsJobLine[];
+    /** kind=exit：退出码（-1 = 被 kill；timedOut 标记超时） */
+    exitCode?: number;
+    timedOut?: boolean;
+    /** 尾部 stderr 摘要（exit 时随行，8KB 截断） */
+    stderrTail?: string;
+}
+/** `mbws:event { event: "attachment" }` 的 payload 形状。 */
+export interface CapsAttachmentEvent {
+    name: string;
+    phase: "downloading" | "verifying" | "ready" | "failed";
+    ratio?: number;
+    message?: string;
+}
+export type CapsEvent = CapsJobEvent | CapsAttachmentEvent;
+/** caps.uploads.status 返回的占位值上传状态（pending-uploads 状态机投影）。 */
+export interface UploadStatusPayload {
+    status: "registered" | "pending" | "uploading" | "done" | "failed" | "missing";
+    /** uploading 时 0..1 */
+    progress?: number;
+    /** done 时的 OSS objectKey */
+    objectKey?: string | null;
+}
+/** caps.exec.localize 返回：job 沙箱相对路径（cwd 相对，args 直接引用）。 */
+export interface LocalizedInput {
+    path: string;
+    size: number;
+}
+/** caps.exec.registerOutput 返回：`local:` 占位值（apply 回写用，宿主代传）。 */
+export interface RegisteredOutput {
+    placeholder: string;
+}
+/** caps.exec.spawn 返回的裸句柄（SDK 包装成 ExecJob；jobResult 断线兜底同形）。 */
+export interface SpawnedJob {
+    jobId: string;
+}
+export interface JobResultPayload {
+    done: boolean;
+    exitCode?: number;
+    timedOut?: boolean;
+    stderrTail?: string;
+}
+/**
+ * 客户端侧 job 句柄（SDK 构造，插件消费）。wait() 以 job 事件 exit 结算，
+ * 非零退出抛 MbwsInvokeError(E_JOB_FAILED, data: { exitCode, stderrTail })。
+ */
+export interface ExecJob {
+    jobId: string;
+    /** 等待退出（exit 事件结算；断线时走 caps.exec.jobResult 兜底轮询） */
+    wait(): Promise<{
+        exitCode: number;
+        stderrTail: string;
+    }>;
+    /** 取消执行（SIGTERM → 3s SIGKILL），幂等 */
+    cancel(): Promise<void>;
+    /** 行级订阅（stdout/stderr；返回退订函数）。ffmpeg -progress 行从这里来 */
+    onLine(cb: (e: CapsJobLine) => void): () => void;
+    /** 读沙箱内小文本文件（相对路径，maxBytes 上限默认 1MB；不存在返回 null） */
+    read(path: string, maxBytes?: number): Promise<string | null>;
+}
+/** caps.exec 方法白名单（宿主 broker 路由 + 参数校验依据，防调到桥内部方法）。 */
+export declare const CAPS_EXEC_METHODS: readonly ["ensureAttachment", "attachmentStatus", "localize", "spawn", "jobResult", "cancelJob", "readFile", "registerOutput", "mediaUrl"];
+export declare const CAPS_UPLOADS_METHODS: readonly ["status"];
+export type CapsExecMethod = (typeof CAPS_EXEC_METHODS)[number];
+export type CapsUploadsMethod = (typeof CAPS_UPLOADS_METHODS)[number];

package/dist/caps.js

@@ -0,0 +1,24 @@
+/**
+ * caps 能力面协议类型——附件执行/上传查询的共享契约（SDK 客户端 / 宿主 broker / 桌面桥共用）。
+ *
+ * 模型（docs/plan §7.6 偏离记录）：开放附件声明 + 完整执行权。宿主不关心附件是什么，
+ * 职责收缩为四件事——下载校验、执行通道、进度/取消、产物登记。插件开发者 shell 级
+ * 驱动附件（任意 args），字节不过协议通道（输入 localize 进沙箱、产物宿主代传）。
+ *
+ * 命名空间固定两个（附件种类开放，不按附件分命名空间）：
+ * - caps.exec   —— 附件 ensure/状态 + 输入本地化 + spawn 长任务 + 产物登记 + 媒体预览（有 attachments 声明才授予）
+ * - caps.uploads —— 上传队列状态查询（桌面宿主恒授）
+ */
+/** caps.exec 方法白名单（宿主 broker 路由 + 参数校验依据，防调到桥内部方法）。 */
+export const CAPS_EXEC_METHODS = [
+    "ensureAttachment",
+    "attachmentStatus",
+    "localize",
+    "spawn",
+    "jobResult",
+    "cancelJob",
+    "readFile",
+    "registerOutput",
+    "mediaUrl",
+];
+export const CAPS_UPLOADS_METHODS = ["status"];

package/dist/client.d.ts

@@ -13,6 +13,7 @@
  * 安全定位：客户端只是包装不是防线——插件绕过客户端手发消息伪造调用，
  * broker 对每条进入的消息仍按 manifest 独立校验（防线在宿主侧）。
  */
+import type { AttachmentState, CapsAttachmentEvent, ExecJob, LocalizedInput, RegisteredOutput, UploadStatusPayload } from "./caps.js";
 import { type FetchContractOptions, type PluginContract } from "./contract.js";
 import { type MbwsErrorCode } from "./errors.js";
 import type { MbwsErrorPayload } from "./protocol.js";
@@ -22,8 +23,8 @@ import type { MbwsErrorPayload } from "./protocol.js";
  * 不传泛型时退宽类型（Record<string, unknown>），与生成前的用法完全兼容。
  */
 export interface MbwsContractTypes {
-    inputs: Record<string, unknown>;
-    outputs: Record<string, unknown>;
+    inputs: object;
+    outputs: object;
 }
 /** C 的 inputs 面（C 未声明时退宽 Record） */
 export type MbwsContractInputs<C> = C extends {
@@ -85,6 +86,48 @@ export interface MbwsClient<C extends MbwsContractTypes = MbwsContractTypes> {
         /** 应答宿主的 before-close 询问（dirty=true 宿主先弹确认再关） */
         replyBeforeClose(dirty: boolean): void;
     };
+    /**
+     * caps 能力面（桌面宿主注入能力桥才存在；web 宿主 undefined）。
+     * exec 需 manifest.attachments 声明；uploads 桌面恒授。
+     */
+    caps?: {
+        exec: {
+            /** 确保附件就绪：未下载则触发下载（宿主先弹 consent），返回就绪态 */
+            ensureAttachment(name: string): Promise<{
+                status: "ready";
+                version: string;
+                sha256: string;
+            }>;
+            /** 非触发式状态查询（下载进度轮询兜底；主通道是 onAttachment 事件） */
+            attachmentStatus(name: string): Promise<AttachmentState>;
+            /** 输入本地化：OSS objectKey 或 local: 占位 → job 沙箱相对路径（args 直接引用） */
+            localize(ref: string): Promise<LocalizedInput>;
+            /** 启动附件执行（args 插件全权组装，cwd = job 沙箱），返回 job 句柄 */
+            spawn(req: {
+                attachment: string;
+                args: string[];
+                timeoutMs?: number;
+            }): Promise<ExecJob>;
+            /** 产物登记：job 沙箱内相对路径 → local: 占位值（宿主 move 进上传队列代传） */
+            registerOutput(req: {
+                jobId: string;
+                path: string;
+                filename: string;
+                contentType?: string;
+            }): Promise<RegisteredOutput>;
+            /** 媒体预览 URL：local: 占位 / OSS key → media-local://（桌面）或签名 URL */
+            mediaUrl(ref: string): Promise<{
+                url: string;
+                mime?: string;
+            }>;
+            /** 附件下载进度/状态事件订阅（返回退订函数） */
+            onAttachment(cb: (e: CapsAttachmentEvent) => void): () => void;
+        };
+        uploads: {
+            /** 占位值上传状态查询（面板展示「待上传/上传中 42%/已上传」） */
+            status(placeholder: string): Promise<UploadStatusPayload>;
+        };
+    };
     /**
      * 数据结构（契约）面：拉关联任务的最新契约。不经宿主端口——服务端按插件编号
      * （manifest.id）公开派生，dev 预览/宿主内同一调用；故不随 grants 增减、恒在。

package/dist/client.js

@@ -1,18 +1,3 @@
-/**
- * createMbws() 工厂——SDK 侧协议客户端（设计稿 §6.1 / §6.3 的代码落地）。
- *
- * 时序真话：`mbws` 不是静态导出的对象——端口握手是异步的，插件代码零环境分支：
- * - 生产（宿主 sandbox iframe 内）：等宿主经 window.postMessage 递来的 MessagePort
- *   （校验 event.source === window.parent，防嵌套 iframe 抢端口）→ init 握手
- *   → 按 grants 构造命名空间 → 返回 mbws。
- * - 开发（harness/单测/直接起 dev server）：顶窗口或等待端口超时 → dev mock 降级。
- *
- * 传输约定（对 M1 starter 手写引导的收紧）：init 经窗口通道递端口是唯一一次
- * window.postMessage；此后所有消息（含 init-ack / panel:* 生命周期）一律走端口。
- *
- * 安全定位：客户端只是包装不是防线——插件绕过客户端手发消息伪造调用，
- * broker 对每条进入的消息仍按 manifest 独立校验（防线在宿主侧）。
- */
 import { fetchContract } from "./contract.js";
 import { createDevMockMbws } from "./dev-mock.js";
 import { MBWS_ERROR_CODES } from "./errors.js";
@@ -63,6 +48,85 @@ export function connectMbwsPort(port, init, opts = {}) {
         });
     });
     const has = (ns) => init.grants.includes(ns);
+    // caps 会话：job 行流/退出事件路由 + 附件事件订阅（事件都在端口上，invoke 只是控制面）
+    const jobSessions = new Map();
+    const attachmentCbs = new Set();
+    const jobSessionOf = (jobId) => {
+        let session = jobSessions.get(jobId);
+        if (!session) {
+            session = { lineCbs: new Set(), waiters: [], settled: false };
+            jobSessions.set(jobId, session);
+        }
+        return session;
+    };
+    const handleCapsEvent = (payload) => {
+        const e = payload;
+        if (!e || typeof e !== "object")
+            return;
+        if ("jobId" in e) {
+            // CapsJobEvent
+            const session = jobSessions.get(e.jobId);
+            if (!session)
+                return;
+            if (e.kind === "lines" && e.lines) {
+                for (const line of e.lines) {
+                    for (const cb of session.lineCbs)
+                        cb(line);
+                }
+            }
+            else if (e.kind === "exit") {
+                const exitCode = e.exitCode ?? -1;
+                const stderrTail = e.stderrTail ?? "";
+                session.settled = true;
+                session.result = { exitCode, stderrTail };
+                if (exitCode === 0) {
+                    for (const w of session.waiters)
+                        w.resolve(session.result);
+                }
+                else {
+                    for (const w of session.waiters) {
+                        w.reject(new MbwsInvokeError({
+                            code: MBWS_ERROR_CODES.E_JOB_FAILED,
+                            message: `附件执行失败（exit ${exitCode}）`,
+                            data: { exitCode, stderrTail, timedOut: e.timedOut },
+                        }));
+                    }
+                }
+                session.waiters = [];
+            }
+        }
+        else if ("name" in e) {
+            for (const cb of attachmentCbs)
+                cb(e);
+        }
+    };
+    /** spawn 返回的裸 jobId 包装成 ExecJob（wait 以 exit 事件结算，断线走 jobResult 兜底） */
+    const makeExecJob = (jobId) => {
+        jobSessionOf(jobId);
+        return {
+            jobId,
+            wait: () => {
+                const session = jobSessionOf(jobId);
+                if (session.settled && session.result) {
+                    if (session.result.exitCode === 0)
+                        return Promise.resolve(session.result);
+                    return Promise.reject(new MbwsInvokeError({
+                        code: MBWS_ERROR_CODES.E_JOB_FAILED,
+                        message: `附件执行失败（exit ${session.result.exitCode}）`,
+                        data: { exitCode: session.result.exitCode, stderrTail: session.result.stderrTail },
+                    }));
+                }
+                return new Promise((resolve, reject) => session.waiters.push({ resolve, reject }));
+            },
+            cancel: () => invoke("caps.exec", "cancelJob", { jobId }),
+            onLine: (cb) => {
+                const session = jobSessionOf(jobId);
+                session.lineCbs.add(cb);
+                return () => session.lineCbs.delete(cb);
+            },
+            read: (path, maxBytes) => invoke("caps.exec", "readFile", { jobId, path, maxBytes }),
+        };
+    };
     port.addEventListener("message", (event) => {
         const message = parseMbwsMessage(event.data);
         if (!message)
@@ -87,9 +151,12 @@ export function connectMbwsPort(port, init, opts = {}) {
                 break;
             }
             case "mbws:event": {
-                // 取消事件桥到 AbortSignal；progress/log/theme 由宿主按需下发，客户端不消费
+                // 取消事件桥到 AbortSignal；job/attachment 事件路由进 caps 会话
                 if (message.event === "cancel")
                     abortController.abort();
+                else if (message.event === "job" || message.event === "attachment") {
+                    handleCapsEvent(message.payload);
+                }
                 break;
             }
             case "panel:before-close": {
@@ -140,6 +207,30 @@ export function connectMbwsPort(port, init, opts = {}) {
                 },
             }
             : {}),
+        ...(has("caps.exec") && has("caps.uploads")
+            ? {
+                caps: {
+                    exec: {
+                        ensureAttachment: (name) => invoke("caps.exec", "ensureAttachment", { name }),
+                        attachmentStatus: (name) => invoke("caps.exec", "attachmentStatus", { name }),
+                        localize: (ref) => invoke("caps.exec", "localize", { ref }),
+                        spawn: async (req) => {
+                            const spawned = (await invoke("caps.exec", "spawn", req));
+                            return makeExecJob(spawned.jobId);
+                        },
+                        registerOutput: (req) => invoke("caps.exec", "registerOutput", req),
+                        mediaUrl: (ref) => invoke("caps.exec", "mediaUrl", { ref }),
+                        onAttachment: (cb) => {
+                            attachmentCbs.add(cb);
+                            return () => attachmentCbs.delete(cb);
+                        },
+                    },
+                    uploads: {
+                        status: (placeholder) => invoke("caps.uploads", "status", { placeholder }),
+                    },
+                },
+            }
+            : {}),
         panel: {
             resize: (height) => post({ v: PROTOCOL_VERSION, type: "panel:resize", height }),
             onBeforeClose(cb) {

package/dist/config.d.ts

@@ -10,18 +10,20 @@
  * 面；I/O 契约两头都不落（服务端按编号实时派生，见 contract.ts）。
  */
 import { z } from "zod";
-import { type Manifest } from "./manifest.js";
+import { type AttachmentDecl, type AttachmentRef, type Manifest } from "./manifest.js";
 /**
  * 用户可填面 = manifest 静态合同 - 派生字段（artifactVersion/sdk 由构建注入）
- * - 契约快照（inputs/outputs，服务端才是权威，不给本地副本留口子）。
+ * - 契约快照（inputs/outputs，服务端才是权威，不给本地副本留口子）
+ * - 附件平台 hash（开发者算不出三平台 sha256/size——只填 name/version 引用，
+ *   platforms 由 resolveAttachmentRefs 从官方附件库解析，buildManifest 填充）。
  */
 declare const UserConfigSchema: z.ZodObject<{
-    id: z.ZodString;
     version: z.ZodString;
     kind: z.ZodEnum<{
         producer: "producer";
         validator: "validator";
     }>;
+    id: z.ZodString;
     paramsSchema: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodType<string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | {
         [key: string]: string | number | boolean | /*elided*/ any | /*elided*/ any | null;
     } | null)[] | {
@@ -71,7 +73,6 @@ declare const UserConfigSchema: z.ZodObject<{
     } | null)[] | {
         [key: string]: string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null)[] | /*elided*/ any | null;
     } | null, unknown>>>]>>;
-    requiresCapabilities: z.ZodDefault<z.ZodArray<z.ZodString>>;
     permissions: z.ZodDefault<z.ZodArray<z.ZodString>>;
     automation: z.ZodEnum<{
         batchable: "batchable";
@@ -88,6 +89,12 @@ declare const UserConfigSchema: z.ZodObject<{
         vendor: z.ZodOptional<z.ZodString>;
         screenshots: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>;
+    attachments: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        version: z.ZodString;
+        name: z.ZodString;
+        entry: z.ZodOptional<z.ZodString>;
+        devPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
     devKey: z.ZodOptional<z.ZodString>;
     apiBaseUrl: z.ZodOptional<z.ZodString>;
     plugin: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -107,6 +114,18 @@ export declare function validateUserConfig(input: unknown): MbwsUserConfig;
 /**
  * config → 装载合同 manifest：注入 artifactVersion，剥掉全部动态开发字段，
  * 补默认值后产出宿主装载所需的完整合同。build 写 dist、dev 虚拟供给共用此派生。
+ *
+ * 附件声明需先经 resolveAttachmentRefs 解析（platforms hash 权威在官方附件库），
+ * 经 resolvedAttachments 传入；声明了附件但没传解析结果 → 抛错（防产物缺平台 hash）。
+ */
+export declare function buildManifest(config: MbwsUserConfig, opts?: {
+    resolvedAttachments?: AttachmentDecl[];
+    allowEmptyAttachments?: boolean;
+}): Manifest;
+/**
+ * 按引用批量拉官方附件库 index → 完整附件声明（platforms hash 填充）。
+ * 附件不在库中 / 平台不全 → 抛错（build 阻断）；离线或后端不可达时 dev 虚拟
+ * manifest 由调用方决定降级（构建必须成功解析，不允许带占位 hash 出产物）。
  */
-export declare function buildManifest(config: MbwsUserConfig): Manifest;
+export declare function resolveAttachmentRefs(refs: AttachmentRef[], apiBase: string): Promise<AttachmentDecl[]>;
 export {};

package/dist/config.js

@@ -10,18 +10,26 @@
  * 面；I/O 契约两头都不落（服务端按编号实时派生，见 contract.ts）。
  */
 import { z } from "zod";
-import { ManifestSchema } from "./manifest.js";
-import { ARTIFACT_VERSION } from "./version.js";
+import { AttachmentDeclSchema, AttachmentRefSchema, ManifestSchema, } from "./manifest.js";
+import { ARTIFACT_VERSION, SDK_VERSION } from "./version.js";
 /**
  * 用户可填面 = manifest 静态合同 - 派生字段（artifactVersion/sdk 由构建注入）
- * - 契约快照（inputs/outputs，服务端才是权威，不给本地副本留口子）。
+ * - 契约快照（inputs/outputs，服务端才是权威，不给本地副本留口子）
+ * - 附件平台 hash（开发者算不出三平台 sha256/size——只填 name/version 引用，
+ *   platforms 由 resolveAttachmentRefs 从官方附件库解析，buildManifest 填充）。
  */
 const UserConfigSchema = ManifestSchema.omit({
     artifactVersion: true,
     sdk: true,
     inputs: true,
     outputs: true,
-}).extend({
+    attachments: true,
+})
+    .extend({
+    /** 附件引用（name+version；platforms hash 构建期从官方附件库解析填充） */
+    attachments: z.array(AttachmentRefSchema).max(8).default([]),
+})
+    .extend({
     /** 开发者 key（预留：认领发放的开发验证凭证，契约拉取 X-Dev-Key 用）——不进产物 */
     devKey: z.string().optional(),
     /**
@@ -54,8 +62,67 @@ export function validateUserConfig(input) {
 /**
  * config → 装载合同 manifest：注入 artifactVersion，剥掉全部动态开发字段，
  * 补默认值后产出宿主装载所需的完整合同。build 写 dist、dev 虚拟供给共用此派生。
+ *
+ * 附件声明需先经 resolveAttachmentRefs 解析（platforms hash 权威在官方附件库），
+ * 经 resolvedAttachments 传入；声明了附件但没传解析结果 → 抛错（防产物缺平台 hash）。
+ */
+export function buildManifest(config, opts = {}) {
+    const { devKey: _devKey, apiBaseUrl: _apiBaseUrl, plugin: _plugin, attachments, ...contract } = UserConfigSchema.parse(config);
+    let resolved = opts.resolvedAttachments ?? [];
+    if (attachments.length > 0 && resolved.length === 0 && !opts.allowEmptyAttachments) {
+        throw new Error(`mbws.config 声明了附件（${attachments.map((a) => `${a.name}@${a.version}`).join(", ")}）` +
+            "但未提供解析结果——先调 resolveAttachmentRefs（vite 插件已自动处理）");
+    }
+    if (resolved.length > 0) {
+        // 解析结果必须与声明一一对齐（名字/版本/入口一致，防解析结果张冠李戴）
+        const byKey = new Map(resolved.map((decl) => [`${decl.name}@${decl.version}`, decl]));
+        resolved = attachments.map((ref) => {
+            const decl = byKey.get(`${ref.name}@${ref.version}`);
+            if (!decl)
+                throw new Error(`附件解析结果缺 ${ref.name}@${ref.version}`);
+            return AttachmentDeclSchema.parse({ ...decl, entry: ref.entry ?? decl.entry });
+        });
+    }
+    // sdk 由构建注入（手写无效）：产物用的 SDK 版本留痕，审查页/宿主可读——
+    // 「本地 dev 与线上构建版本一致性」排查的第一现场
+    return ManifestSchema.parse({
+        ...contract,
+        attachments: resolved,
+        artifactVersion: ARTIFACT_VERSION,
+        sdk: SDK_VERSION,
+    });
+}
+/**
+ * 按引用批量拉官方附件库 index → 完整附件声明（platforms hash 填充）。
+ * 附件不在库中 / 平台不全 → 抛错（build 阻断）；离线或后端不可达时 dev 虚拟
+ * manifest 由调用方决定降级（构建必须成功解析，不允许带占位 hash 出产物）。
  */
-export function buildManifest(config) {
-    const { devKey: _devKey, apiBaseUrl: _apiBaseUrl, plugin: _plugin, ...contract } = UserConfigSchema.parse(config);
-    return ManifestSchema.parse({ ...contract, artifactVersion: ARTIFACT_VERSION });
+export async function resolveAttachmentRefs(refs, apiBase) {
+    return Promise.all(refs.map(async (ref) => {
+        const url = `${apiBase.replace(/\/+$/, "")}/api/plugin-attachments` +
+            `?name=${encodeURIComponent(ref.name)}&version=${encodeURIComponent(ref.version)}`;
+        let index;
+        try {
+            const response = await fetch(url);
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            index = (await response.json());
+        }
+        catch (error) {
+            throw new Error(`附件 ${ref.name}@${ref.version} 解析失败（${error instanceof Error ? error.message : error}）` +
+                "——官方附件库不可达或该版本未登记（发布附件见 scripts/publish-attachment.mjs）");
+        }
+        const parsed = AttachmentDeclSchema.safeParse({
+            name: index.name,
+            version: index.version,
+            entry: ref.entry,
+            platforms: index.platforms,
+        });
+        if (!parsed.success) {
+            throw new Error(`附件 ${ref.name}@${ref.version} 官方库 index 不合法/平台不全：` +
+                parsed.error.issues.map((issue) => issue.message).join("；"));
+        }
+        return parsed.data;
+    }));
 }

package/dist/dev-mock.d.ts

@@ -1,12 +1,6 @@
-/**
- * dev mock——开发环境（harness/单测/dev server 直接起）无宿主端口时的降级实现（设计稿 §6.3）。
- *
- * 语义边界：data.read 回 `samples/` 夹具数据；data.apply 只在控制台输出、不入任何库；
- * 其余命名空间 no-op。插件代码零环境分支——同一份代码在 harness 里跑 mock、在宿主里跑真端口。
- */
 import type { MbwsClient } from "./client.js";
 /**
- * 创建 dev mock 客户端。四个固定命名空间全部构造（dev 无授权语义），
+ * 创建 dev mock 客户端。固定命名空间 + caps 全部构造（dev 无授权语义），
  * panel 生命周期面上报/应答均无宿主可收，no-op 即可。
  */
 export declare function createDevMockMbws(): MbwsClient;