@mbws/plugin-sdk 0.2.4 → 0.3.0

package/dist/dev-mock.js

@@ -1,6 +1,97 @@
 import { fetchContract } from "./contract.js";
+/** dev spawn：先试 dev 执行端点（真跑），失败退模拟 */
+async function spawnDevJob(req) {
+    const session = { lineCbs: new Set(), waiters: [], settled: false };
+    const settle = (exitCode, stderrTail = "") => {
+        if (session.settled)
+            return;
+        session.settled = true;
+        session.result = { exitCode, stderrTail };
+        for (const w of session.waiters)
+            w.resolve(session.result);
+        session.waiters = [];
+    };
+    const emit = (lines) => {
+        for (const line of lines)
+            for (const cb of session.lineCbs)
+                cb(line);
+    };
+    let response = null;
+    try {
+        response = await fetch("/__mbws__/dev/exec", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(req),
+        });
+    }
+    catch {
+        response = null;
+    }
+    if (response?.ok && response.body) {
+        // NDJSON 事件流：{kind:"lines",lines}|{kind:"exit",exitCode,stderrTail}
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        const pump = async () => {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                let newlineAt = buffer.indexOf("\n");
+                while (newlineAt >= 0) {
+                    const rawLine = buffer.slice(0, newlineAt);
+                    buffer = buffer.slice(newlineAt + 1);
+                    try {
+                        const event = JSON.parse(rawLine);
+                        if (event.kind === "lines" && event.lines)
+                            emit(event.lines);
+                        else if (event.kind === "exit")
+                            settle(event.exitCode ?? -1, event.stderrTail ?? "");
+                    }
+                    catch {
+                        // 非 JSON 行忽略
+                    }
+                    newlineAt = buffer.indexOf("\n");
+                }
+            }
+            // 流结束仍无 exit（进程被强杀等）：按失败收尾
+            settle(-1, "dev 执行流意外结束");
+        };
+        void pump();
+    }
+    else {
+        console.info(`[mbws:dev] spawn(${req.attachment}) 无 dev 执行端点（非 vite dev 或未配本机附件）——模拟执行`);
+        setTimeout(() => {
+            emit([
+                { stream: "stdout", text: `[mbws:dev] simulated ${req.attachment} ${req.args.join(" ")}` },
+            ]);
+            settle(0);
+        }, 100);
+    }
+    return {
+        jobId: `dev-${Date.now()}-${Math.floor(Math.random() * 1e6)}`,
+        wait: () => {
+            if (session.settled && session.result)
+                return Promise.resolve(session.result);
+            return new Promise((resolve, reject) => session.waiters.push({ resolve, reject }));
+        },
+        cancel: async () => {
+            console.info("[mbws:dev] cancel（模拟环境无进程可杀）");
+            settle(-1, "cancelled");
+        },
+        onLine: (cb) => {
+            session.lineCbs.add(cb);
+            return () => session.lineCbs.delete(cb);
+        },
+        read: async (path) => {
+            console.info(`[mbws:dev] readFile(${path}) no-op`);
+            return null;
+        },
+    };
+}
 /**
- * 创建 dev mock 客户端。四个固定命名空间全部构造（dev 无授权语义），
+ * 创建 dev mock 客户端。固定命名空间 + caps 全部构造（dev 无授权语义），
  * panel 生命周期面上报/应答均无宿主可收，no-op 即可。
  */
 export function createDevMockMbws() {
@@ -38,6 +129,52 @@ export function createDevMockMbws() {
                 console.info(`[mbws:dev] ui.toast：${message}`);
             },
         },
+        caps: {
+            exec: {
+                ensureAttachment: async (name) => {
+                    console.info(`[mbws:dev] ensureAttachment(${name})——dev 不预下载，spawn 时由 dev 中间件解析（attachments 声明的 devPath / MBWS_DEV_ATTACHMENT_${name.replace(/-/g, "_").toUpperCase()} 本机覆盖，否则按 attachments 声明自动从官方附件库下载缓存）`);
+                    return { status: "ready", version: "dev", sha256: `dev-${name}` };
+                },
+                attachmentStatus: async (name) => ({ name, status: "ready" }),
+                localize: async (ref) => {
+                    try {
+                        const response = await fetch(`/__mbws__/dev/localize?ref=${encodeURIComponent(ref)}`);
+                        if (response.ok)
+                            return (await response.json());
+                    }
+                    catch {
+                        // 非 dev server 场景，走兜底
+                    }
+                    const basename = ref.split("/").pop() ?? "input";
+                    return { path: `samples/${basename}`, size: 0 };
+                },
+                spawn: (req) => spawnDevJob(req),
+                registerOutput: async (req) => {
+                    console.info(`[mbws:dev] registerOutput(${req.filename})——假占位不入库`);
+                    return { placeholder: `devlocal:${encodeURIComponent(req.filename)}` };
+                },
+                mediaUrl: async (ref) => {
+                    try {
+                        const response = await fetch(`/__mbws__/dev/localize?ref=${encodeURIComponent(ref)}`);
+                        if (response.ok) {
+                            const { path } = (await response.json());
+                            return { url: `/__mbws__/dev/file?path=${encodeURIComponent(path)}` };
+                        }
+                    }
+                    catch {
+                        // 兜底走 dev:// 假地址
+                    }
+                    return { url: `dev://samples/${ref}` };
+                },
+                onAttachment: (_cb) => () => { },
+            },
+            uploads: {
+                status: async (placeholder) => {
+                    console.info(`[mbws:dev] uploads.status(${placeholder})`);
+                    return { status: "registered" };
+                },
+            },
+        },
         panel: {
             resize: () => { },
             onBeforeClose: () => { },

package/dist/errors.d.ts

@@ -17,6 +17,10 @@ export declare const MBWS_ERROR_CODES: {
     readonly E_WRITE_GATE_REJECTED: "E_WRITE_GATE_REJECTED";
     /** 依赖的能力包未安装或版本不满足 */
     readonly E_CAPABILITY_UNAVAILABLE: "E_CAPABILITY_UNAVAILABLE";
+    /** 附件下载/校验/解包失败（网络错误、sha256 不符、解包路径穿越等） */
+    readonly E_ATTACHMENT_DOWNLOAD_FAILED: "E_ATTACHMENT_DOWNLOAD_FAILED";
+    /** 附件子进程非零退出（error.data 带 exitCode / stderrTail） */
+    readonly E_JOB_FAILED: "E_JOB_FAILED";
     /** 调用超时（宿主侧 wall-clock 预算） */
     readonly E_TIMEOUT: "E_TIMEOUT";
     /** 被取消（对齐 ffmpeg-cancel 语义，runtime.signal 触发后的在途调用收尾） */

package/dist/errors.js

@@ -17,6 +17,10 @@ export const MBWS_ERROR_CODES = {
     E_WRITE_GATE_REJECTED: "E_WRITE_GATE_REJECTED",
     /** 依赖的能力包未安装或版本不满足 */
     E_CAPABILITY_UNAVAILABLE: "E_CAPABILITY_UNAVAILABLE",
+    /** 附件下载/校验/解包失败（网络错误、sha256 不符、解包路径穿越等） */
+    E_ATTACHMENT_DOWNLOAD_FAILED: "E_ATTACHMENT_DOWNLOAD_FAILED",
+    /** 附件子进程非零退出（error.data 带 exitCode / stderrTail） */
+    E_JOB_FAILED: "E_JOB_FAILED",
     /** 调用超时（宿主侧 wall-clock 预算） */
     E_TIMEOUT: "E_TIMEOUT",
     /** 被取消（对齐 ffmpeg-cancel 语义，runtime.signal 触发后的在途调用收尾） */

package/dist/index.d.ts

@@ -5,6 +5,7 @@
  * M2：createMbws() 工厂与 dev mock。
  * 后续里程碑在此包内扩展：CLI dev/build/sign（M4）、fns/DSL（M4）。
  */
+export * from "./caps.js";
 export * from "./client.js";
 export * from "./config.js";
 export * from "./contract.js";

package/dist/index.js

@@ -5,6 +5,7 @@
  * M2：createMbws() 工厂与 dev mock。
  * 后续里程碑在此包内扩展：CLI dev/build/sign（M4）、fns/DSL（M4）。
  */
+export * from "./caps.js";
 export * from "./client.js";
 export * from "./config.js";
 export * from "./contract.js";

package/dist/manifest.d.ts

@@ -20,6 +20,44 @@ import { z } from "zod";
 type Json = null | boolean | number | string | Json[] | {
     [key: string]: Json;
 };
+/**
+ * 支持的附件平台（process.platform + os.arch 映射）。
+ * linux-x64 留字段供未来，当前投放三桌面平台。
+ */
+export declare const ATTACHMENT_PLATFORMS: readonly ["darwin-arm64", "darwin-x64", "win-x64", "linux-x64"];
+export type AttachmentPlatform = (typeof ATTACHMENT_PLATFORMS)[number];
+/** 宿主必配的平台集合（manifest 校验：三桌面平台缺一即拒）。 */
+export declare const REQUIRED_ATTACHMENT_PLATFORMS: AttachmentPlatform[];
+/**
+ * 附件声明（完整形态，进 manifest）。开发者侧只填 name/version 引用，
+ * platforms hash 由构建期从官方附件库 index 解析填充（单一权威在库）。
+ */
+export declare const AttachmentDeclSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    entry: z.ZodOptional<z.ZodString>;
+    platforms: z.ZodRecord<z.ZodString, z.ZodObject<{
+        sha256: z.ZodString;
+        size: z.ZodNumber;
+        archive: z.ZodDefault<z.ZodEnum<{
+            "tar.gz": "tar.gz";
+            zip: "zip";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AttachmentDecl = z.output<typeof AttachmentDeclSchema>;
+/**
+ * 开发者侧的附件引用（mbws.config.ts 可填形态）——platforms 由构建解析填充。
+ * devPath 是 dev-only 的本机路径覆盖（线上还没有的新版本附件指到本机开发；
+ * 未填/路径不存在时 dev 自动按 name+version 从官方附件库下载缓存），不进产物。
+ */
+export declare const AttachmentRefSchema: z.ZodObject<{
+    version: z.ZodString;
+    name: z.ZodString;
+    entry: z.ZodOptional<z.ZodString>;
+    devPath: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AttachmentRef = z.output<typeof AttachmentRefSchema>;
 export declare const ManifestSchema: z.ZodObject<{
     id: z.ZodString;
     version: z.ZodString;
@@ -31,7 +69,19 @@ export declare const ManifestSchema: z.ZodObject<{
     inputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodType<Json, unknown, z.core.$ZodTypeInternals<Json, unknown>>>]>>>;
     outputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodType<Json, unknown, z.core.$ZodTypeInternals<Json, unknown>>>]>>>;
     paramsSchema: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodType<Json, unknown, z.core.$ZodTypeInternals<Json, unknown>>>]>>;
-    requiresCapabilities: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    attachments: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        entry: z.ZodOptional<z.ZodString>;
+        platforms: z.ZodRecord<z.ZodString, z.ZodObject<{
+            sha256: z.ZodString;
+            size: z.ZodNumber;
+            archive: z.ZodDefault<z.ZodEnum<{
+                "tar.gz": "tar.gz";
+                zip: "zip";
+            }>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
     permissions: z.ZodDefault<z.ZodArray<z.ZodString>>;
     automation: z.ZodEnum<{
         batchable: "batchable";

package/dist/manifest.js

@@ -29,8 +29,55 @@ const JsonSchemaValue = z.union([z.boolean(), z.record(z.string(), jsonValue)]);
  */
 const PLUGIN_ID_RE = /^[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)*$/;
 const SEMVER_RE = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/;
-/** 能力依赖：`<域>.<名>` 可带版本约束，如 `media.ffmpeg@>=7`。 */
-const CAPABILITY_RE = /^[a-z][a-z0-9-]*(\.[a-z0-9-]+)+(@.+)?$/;
+/** 附件名：官方附件库唯一键，如 "ffmpeg" / "ffprobe"。 */
+const ATTACHMENT_NAME_RE = /^[a-z][a-z0-9-]{1,63}$/;
+/** 包内可执行入口文件名（无路径分隔，防穿越）。 */
+const ATTACHMENT_ENTRY_RE = /^[^/\\]+$/;
+/**
+ * 支持的附件平台（process.platform + os.arch 映射）。
+ * linux-x64 留字段供未来，当前投放三桌面平台。
+ */
+export const ATTACHMENT_PLATFORMS = ["darwin-arm64", "darwin-x64", "win-x64", "linux-x64"];
+/** 宿主必配的平台集合（manifest 校验：三桌面平台缺一即拒）。 */
+export const REQUIRED_ATTACHMENT_PLATFORMS = [
+    "darwin-arm64",
+    "darwin-x64",
+    "win-x64",
+];
+/** 附件平台描述：内容寻址键 + 展示/预算信息。 */
+const AttachmentPlatformSchema = z.object({
+    /** 压缩包 sha256（hex）——内容寻址键 + 完整性校验，一切以 hash 为准 */
+    sha256: z.string().regex(/^[0-9a-f]{64}$/),
+    /** 压缩包字节数（consent「约 xx MB」与下载预算） */
+    size: z.number().int().positive(),
+    archive: z.enum(["tar.gz", "zip"]).default("tar.gz"),
+});
+/**
+ * 附件声明（完整形态，进 manifest）。开发者侧只填 name/version 引用，
+ * platforms hash 由构建期从官方附件库 index 解析填充（单一权威在库）。
+ */
+export const AttachmentDeclSchema = z.object({
+    name: z.string().regex(ATTACHMENT_NAME_RE),
+    /** 官方附件库索引键；宿主下载校验一切以 sha256 为准 */
+    version: z.string().regex(SEMVER_RE),
+    /** 包内可执行入口，缺省 = name */
+    entry: z.string().regex(ATTACHMENT_ENTRY_RE).optional(),
+    // 宽松 record + refine：zod v4 的 z.record(enum) 会强制枚举键全量（linux-x64 误成必填）
+    platforms: z
+        .record(z.string(), AttachmentPlatformSchema)
+        .refine((p) => Object.keys(p).every((k) => ATTACHMENT_PLATFORMS.includes(k)), { message: `未知平台键（合法：${ATTACHMENT_PLATFORMS.join(" / ")}）` })
+        .refine((p) => REQUIRED_ATTACHMENT_PLATFORMS.every((k) => p[k] != null), {
+        message: `附件平台必填：${REQUIRED_ATTACHMENT_PLATFORMS.join(" / ")}`,
+    }),
+});
+/**
+ * 开发者侧的附件引用（mbws.config.ts 可填形态）——platforms 由构建解析填充。
+ * devPath 是 dev-only 的本机路径覆盖（线上还没有的新版本附件指到本机开发；
+ * 未填/路径不存在时 dev 自动按 name+version 从官方附件库下载缓存），不进产物。
+ */
+export const AttachmentRefSchema = AttachmentDeclSchema.omit({ platforms: true }).extend({
+    devPath: z.string().optional(),
+});
 /**
  * 权限声明，两种语法（CSP connect-src 与权限预览文案的推导输入，设计稿 §6.5）：
  * - `ai.<purpose>`：走项目 AI 中心的调用（如 `ai.ocr`）
@@ -54,8 +101,12 @@ export const ManifestSchema = z.object({
     outputs: z.record(z.string(), JsonSchemaValue).optional(),
     /** 参数位约束：宿主据此渲染参数表单（插件零 UI 代码即有参数面板） */
     paramsSchema: JsonSchemaValue.optional(),
-    /** 能力依赖：机器未装/未授则 `mbws.caps.*` 命名空间不存在 */
-    requiresCapabilities: z.array(z.string().regex(CAPABILITY_RE)).default([]),
+    /**
+     * 附件声明（二进制外挂，纯桌面端）：宿主懒加载（首次使用按需下载、内容寻址共享），
+     * 插件经 caps.* 获得 shell 级执行权。有声明 → 桌面 only，web 宿主灰显。
+     * 取代旧 requiresCapabilities（typed 能力包模型已裁撤，见 docs/plan §7.6 偏离记录）。
+     */
+    attachments: z.array(AttachmentDeclSchema).max(8).default([]),
     /** 权限逐条授予：consent 列表与 CSP 白名单的推导源 */
     permissions: z.array(z.string().regex(PERMISSION_RE)).default([]),
     /** interactive-only 不进入批量/自动驱动 */

package/dist/protocol.d.ts

@@ -16,8 +16,11 @@ import { type MbwsErrorCode } from "./errors.js";
  * `caps.*` 由已装且已授予的能力包动态注册（如 `caps.video`），协议面不硬编码能力包 API。
  */
 export declare const MBWS_NAMESPACES: readonly ["data", "runtime", "storage", "ui"];
-/** 宿主 → 插件事件种类（设计稿 §6.6：progress / log / cancel / theme） */
-export declare const MBWS_EVENT_KINDS: readonly ["progress", "log", "cancel", "theme"];
+/**
+ * 宿主 → 插件事件种类（设计稿 §6.6：progress / log / cancel / theme + caps 长任务两族）。
+ * `job`：附件子进程行流/退出；`attachment`：附件下载进度/状态。payload 形状见 caps.ts。
+ */
+export declare const MBWS_EVENT_KINDS: readonly ["progress", "log", "cancel", "theme", "job", "attachment"];
 export declare const MbwsMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     v: z.ZodLiteral<1>;
     type: z.ZodLiteral<"mbws:invoke">;
@@ -52,6 +55,8 @@ export declare const MbwsMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             readonly E_QUOTA_EXCEEDED: "E_QUOTA_EXCEEDED";
             readonly E_WRITE_GATE_REJECTED: "E_WRITE_GATE_REJECTED";
             readonly E_CAPABILITY_UNAVAILABLE: "E_CAPABILITY_UNAVAILABLE";
+            readonly E_ATTACHMENT_DOWNLOAD_FAILED: "E_ATTACHMENT_DOWNLOAD_FAILED";
+            readonly E_JOB_FAILED: "E_JOB_FAILED";
             readonly E_TIMEOUT: "E_TIMEOUT";
             readonly E_CANCELLED: "E_CANCELLED";
             readonly E_PROTOCOL_VIOLATION: "E_PROTOCOL_VIOLATION";
@@ -63,10 +68,12 @@ export declare const MbwsMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     v: z.ZodLiteral<1>;
     type: z.ZodLiteral<"mbws:event">;
     event: z.ZodEnum<{
+        cancel: "cancel";
         progress: "progress";
         log: "log";
-        cancel: "cancel";
         theme: "theme";
+        job: "job";
+        attachment: "attachment";
     }>;
     payload: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strip>, z.ZodObject<{

package/dist/protocol.js

@@ -19,8 +19,18 @@ import { PROTOCOL_VERSION } from "./version.js";
 export const MBWS_NAMESPACES = ["data", "runtime", "storage", "ui"];
 const NS_RE = /^(data|runtime|storage|ui|caps(\.[a-z0-9-]+)?)$/;
 const nsField = z.string().regex(NS_RE);
-/** 宿主 → 插件事件种类（设计稿 §6.6：progress / log / cancel / theme） */
-export const MBWS_EVENT_KINDS = ["progress", "log", "cancel", "theme"];
+/**
+ * 宿主 → 插件事件种类（设计稿 §6.6：progress / log / cancel / theme + caps 长任务两族）。
+ * `job`：附件子进程行流/退出；`attachment`：附件下载进度/状态。payload 形状见 caps.ts。
+ */
+export const MBWS_EVENT_KINDS = [
+    "progress",
+    "log",
+    "cancel",
+    "theme",
+    "job",
+    "attachment",
+];
 const InvokeMessage = z.object({
     v: z.literal(PROTOCOL_VERSION),
     type: z.literal("mbws:invoke"),

package/dist/version.d.ts

@@ -12,4 +12,4 @@ export declare const PROTOCOL_VERSION: 1;
  * SDK 自身版本（与 package.json version 保持一致）。
  * init-ack 上报给宿主做审计，与 manifest.sdk（build 写入）交叉核对。
  */
-export declare const SDK_VERSION = "0.2.4";
+export declare const SDK_VERSION = "0.3.0";

package/dist/version.js

@@ -12,4 +12,4 @@ export const PROTOCOL_VERSION = 1;
  * SDK 自身版本（与 package.json version 保持一致）。
  * init-ack 上报给宿主做审计，与 manifest.sdk（build 写入）交叉核对。
  */
-export const SDK_VERSION = "0.2.4";
+export const SDK_VERSION = "0.3.0";

package/dist/vite.d.ts

@@ -13,3 +13,14 @@ export interface MbwsVitePluginOptions {
  * 转发到真实后端——插件 dev 端口不在后端 CORS 白名单的问题由此消解。
  */
 export declare function mbwsVitePlugin(opts: MbwsVitePluginOptions): Plugin;
+/** /__mbws__/<rest> → <apiBase>/<rest>：方法/头透传，响应状态码/content-type/body 透传 */
+/**
+ * 当前进程 → 附件平台键（与 manifest 的 ATTACHMENT_PLATFORMS 同词表）。
+ */
+export declare function currentAttachmentPlatform(): string;
+/**
+ * dev 用附件本地覆盖：env MBWS_DEV_ATTACHMENT_<NAME>（名字大写、- → _）优先，
+ * 其次 attachments 声明里的 devPath（线上还没有的新版本指本机路径）。
+ * 未配置/路径不存在返回 null（走官方附件库自动下载）。
+ */
+export declare function resolveDevAttachmentOverride(config: MbwsUserConfig, name: string): string | null;