@dipoleml/dcode-cli 1.1.0 → 1.2.1

package/node_modules/@dcode/shared/dist/marketingTouch.js

@@ -0,0 +1,170 @@
+import { z } from "zod";
+import { cloudButtonThemeSchema } from "./cloudContent.js";
+const id = z.string().trim().min(1).max(128);
+const url = z
+    .string()
+    .max(4096)
+    .url()
+    .refine((value) => {
+    if (!URL.canParse(value))
+        return false;
+    const parsed = new URL(value);
+    return ["http:", "https:"].includes(parsed.protocol) && !parsed.username && !parsed.password;
+});
+export const marketingAssetSchema = z.object({
+    src: url,
+    sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+});
+const text = z.object({
+    format: z.enum(["plaintext", "html", "markdown"]),
+    content: z.string().max(20_000),
+});
+export const marketingNavigationSchema = z.discriminatedUnion("page", [
+    z.object({ page: z.literal("upgrade") }).strict(),
+    z.object({ page: z.literal("rewards") }).strict(),
+    z
+        .object({
+        page: z.literal("settings"),
+        section: z
+            .enum([
+            "general",
+            "appearance",
+            "models",
+            "browser",
+            "computer_use",
+            "memory",
+            "subagents",
+            "plugins",
+            "mcp",
+            "skills",
+            "commands",
+            "hooks",
+            "usage",
+        ])
+            .optional(),
+        provider_id: id.optional(),
+    })
+        .strict()
+        .refine((args) => args.provider_id === undefined || args.section === "models"),
+    z
+        .object({
+        page: z.literal("plugin_marketplace"),
+        plugin_id: id.regex(/^[^@\s]+@[^@\s]+$/u).optional(),
+    })
+        .strict(),
+]);
+export const marketingActionSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("close") }),
+    z.object({ type: z.literal("open_url"), args: z.object({ url }) }),
+    z.object({ type: z.literal("claim_dcode_plan"), args: z.object({ plan_id: id }) }),
+    z.object({ type: z.literal("navigate"), args: marketingNavigationSchema }),
+    z.object({
+        type: z.literal("copy_text"),
+        args: z
+            .object({
+            text: z
+                .string()
+                .max(20_000)
+                .refine((value) => value.trim().length > 0),
+        })
+            .strict(),
+    }),
+]);
+const button = z.object({
+    text,
+    action: marketingActionSchema,
+    theme: cloudButtonThemeSchema.nullish(),
+});
+// Banner 允许空格式；若复用弹窗约束会丢弃有效投放，仅在此按纯文本归一。
+const bannerButton = button.omit({ theme: true }).extend({
+    text: text.extend({
+        format: z
+            .enum(["", "plaintext", "html", "markdown"])
+            .transform((value) => value || "plaintext"),
+    }),
+});
+const layout = z.enum(["", "v1"]).optional();
+const visualArgs = z
+    .record(z.string(), z.unknown())
+    .refine((value) => JSON.stringify(value).length <= 64_000)
+    .optional();
+const image = z.object({
+    type: z.literal("image"),
+    image: z.object({ default: marketingAssetSchema, dark: marketingAssetSchema.nullish() }),
+    args: visualArgs,
+});
+export const marketingVisualSchema = z.discriminatedUnion("type", [
+    image,
+    z.object({
+        type: z.literal("video"),
+        video: z.object({ src: marketingAssetSchema, fallback: marketingAssetSchema }),
+        args: visualArgs,
+    }),
+    z.object({
+        type: z.literal("bundle"),
+        bundle: z.object({
+            bundle: marketingAssetSchema,
+            entry: z
+                .string()
+                .min(1)
+                .max(240)
+                .refine((value) => !value.includes("\\") &&
+                value.split("/").every((part) => part && part !== "." && part !== "..")),
+            fallback: marketingAssetSchema.nullish(),
+        }),
+        args: visualArgs,
+    }),
+]);
+export const marketingPopupSchema = z.object({
+    layout,
+    title: text,
+    description: text,
+    hero: marketingVisualSchema.nullish(),
+    buttons: z.array(button).max(4),
+});
+const banner = z
+    .object({
+    layout,
+    background: marketingVisualSchema,
+    buttons: z.array(bannerButton).max(2),
+    success_popup: marketingPopupSchema.nullish(),
+})
+    .refine((value) => value.buttons.filter((b) => b.action.type === "close").length <= 1 &&
+    value.buttons.filter((b) => b.action.type !== "close").length <= 1);
+const deliveryBase = { campaign_id: id, priority: z.number().int().min(0).max(100) };
+// 服务端已将旧 card 改名为 banner；判别值与内容字段必须同步，否则有效投放会被丢弃。
+export const marketingDeliverySchema = z.discriminatedUnion("resource_position", [
+    z.object({ ...deliveryBase, resource_position: z.literal("banner"), banner }),
+    z.object({ ...deliveryBase, resource_position: z.literal("popup"), popup: marketingPopupSchema }),
+]);
+const envelope = z.object({
+    code: z.literal(0),
+    data: z.object({
+        server_time: z.number().finite(),
+        language: z.enum(["zh-CN", "en-US"]),
+        deliveries: z.array(z.unknown()).max(32),
+    }),
+});
+/** 单条坏投放不影响其他资源位；外层失败不能伪装成成功空结果。 */
+export function parseMarketingTouchResponse(input) {
+    const { data } = envelope.parse(input);
+    const deliveries = [];
+    let rejectedCount = 0;
+    const positions = new Set();
+    for (const raw of data.deliveries) {
+        const result = marketingDeliverySchema.safeParse(raw);
+        if (!result.success || positions.has(result.data.resource_position)) {
+            rejectedCount++;
+            continue;
+        }
+        positions.add(result.data.resource_position);
+        deliveries.push(result.data);
+    }
+    return {
+        serverTime: data.server_time * 1000,
+        language: data.language,
+        deliveries,
+        rejectedCount,
+    };
+}
+//# sourceMappingURL=marketingTouch.js.map

package/node_modules/@dcode/shared/dist/mcp-apps/appTools.d.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+/**
+ * App-Provided Tools（MCP Apps 规范「App-Provided Tools」）：页面在 `ui/initialize` 声明 `tools` 能力后，
+ * 宿主 `tools/list` 发现页面工具、登记到 agent 暴露给模型；模型调用经"实例信箱"（live-only 投影增量
+ * `pluginUi.appToolCall`，按 scopeId + generation 投递）到达渲染端，页面 `tools/call` 执行后回传。
+ * 这里只有限额、描述符归一化与模型侧命名；纯 domain，零 IO。
+ */
+/** 每个页面实例最多登记的工具数（规范推荐值）。 */
+export declare const MCP_APPS_APP_TOOLS_MAX_PER_INSTANCE = 50;
+export declare const MCP_APPS_APP_TOOL_NAME_MAX_CHARS = 128;
+export declare const MCP_APPS_APP_TOOL_TITLE_MAX_CHARS = 256;
+export declare const MCP_APPS_APP_TOOL_DESCRIPTION_MAX_CHARS = 4096;
+/** inputSchema / outputSchema 序列化后的上限（UTF-8 字节）。 */
+export declare const MCP_APPS_APP_TOOL_SCHEMA_MAX_BYTES: number;
+/** 渲染端认领待执行调用的期限；超时视为页面未运行（信箱投递不重发）。 */
+export declare const MCP_APPS_APP_TOOL_CLAIM_TIMEOUT_MS = 5000;
+/** 认领后页面执行 tools/call 的期限（规范推荐值）。 */
+export declare const MCP_APPS_APP_TOOL_CALL_TIMEOUT_MS = 30000;
+/** 单次结果序列化上限（规范推荐值）。 */
+export declare const MCP_APPS_APP_TOOL_RESULT_MAX_BYTES: number;
+/** 模型调用参数进信箱前的上限；超限直接以错误结束，不下发。 */
+export declare const MCP_APPS_APP_TOOL_ARGUMENTS_MAX_BYTES: number;
+/** list_changed 触发的重新登记最小间隔。 */
+export declare const MCP_APPS_APP_TOOLS_REFRESH_INTERVAL_MS = 1000;
+export declare const MCP_APPS_APP_TOOL_ERROR_MESSAGE_MAX_CHARS = 4096;
+export declare const MCP_APPS_APP_TOOL_CALL_ID_MAX_CHARS = 128;
+/** 模型侧名字前缀：与 server 工具的 `mcp__` 天然不冲突。 */
+export declare const MCP_APPS_APP_TOOL_MODEL_NAME_PREFIX = "app__";
+/** 与 agent 的 MCP 工具名同一清洗规则：非 `[A-Za-z0-9_-]` 替换为 `_` 并合并连续下划线。 */
+export declare function sanitizeMcpAppsModelNamePart(name: string): string;
+/** 模型侧名字 `app__<server>__<tool>`。 */
+export declare function buildMcpAppsAppToolModelName(serverName: string, toolName: string): string;
+export declare const mcpAppsAppToolAnnotationsSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+    destructiveHint: z.ZodOptional<z.ZodBoolean>;
+    idempotentHint: z.ZodOptional<z.ZodBoolean>;
+    openWorldHint: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type McpAppsAppToolAnnotations = z.infer<typeof mcpAppsAppToolAnnotationsSchema>;
+export declare const mcpAppsAppToolDescriptorSchema: z.ZodObject<{
+    name: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    annotations: z.ZodOptional<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+        destructiveHint: z.ZodOptional<z.ZodBoolean>;
+        idempotentHint: z.ZodOptional<z.ZodBoolean>;
+        openWorldHint: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type McpAppsAppToolDescriptor = z.infer<typeof mcpAppsAppToolDescriptorSchema>;
+/**
+ * 渲染端用：把页面 `tools/list` 的结果收窄成可登记的描述符。不合规的项跳过（不让整次登记失败），
+ * 超过 50 个只取前 50 个；返回被跳过的名字与原因供日志。
+ */
+export declare function normalizeMcpAppsAppTools(tools: readonly unknown[]): {
+    tools: McpAppsAppToolDescriptor[];
+    skipped: Array<{
+        name: string | null;
+        reason: string;
+    }>;
+};
+/** 页面 `tools/call` 的结果（MCP CallToolResult 形状，字段集宽松：content 项原样保留）。 */
+export declare const mcpAppsAppToolCallResultSchema: z.ZodObject<{
+    content: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    structuredContent: z.ZodOptional<z.ZodUnknown>;
+    isError: z.ZodOptional<z.ZodBoolean>;
+    _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type McpAppsAppToolCallResult = z.infer<typeof mcpAppsAppToolCallResultSchema>;
+/** 信箱里的一次待执行调用：按 (scopeId, generation) 投递给唯一实例。 */
+export interface McpAppsAppToolCallRequest {
+    activity?: boolean;
+    cancelled?: boolean;
+    callId: string;
+    toolName: string;
+    arguments: Record<string, unknown>;
+}
+//# sourceMappingURL=appTools.d.ts.map

package/node_modules/@dcode/shared/dist/mcp-apps/appTools.js

@@ -0,0 +1,124 @@
+import { z } from "zod";
+/**
+ * App-Provided Tools（MCP Apps 规范「App-Provided Tools」）：页面在 `ui/initialize` 声明 `tools` 能力后，
+ * 宿主 `tools/list` 发现页面工具、登记到 agent 暴露给模型；模型调用经"实例信箱"（live-only 投影增量
+ * `pluginUi.appToolCall`，按 scopeId + generation 投递）到达渲染端，页面 `tools/call` 执行后回传。
+ * 这里只有限额、描述符归一化与模型侧命名；纯 domain，零 IO。
+ */
+/** 每个页面实例最多登记的工具数（规范推荐值）。 */
+export const MCP_APPS_APP_TOOLS_MAX_PER_INSTANCE = 50;
+export const MCP_APPS_APP_TOOL_NAME_MAX_CHARS = 128;
+export const MCP_APPS_APP_TOOL_TITLE_MAX_CHARS = 256;
+export const MCP_APPS_APP_TOOL_DESCRIPTION_MAX_CHARS = 4096;
+/** inputSchema / outputSchema 序列化后的上限（UTF-8 字节）。 */
+export const MCP_APPS_APP_TOOL_SCHEMA_MAX_BYTES = 64 * 1024;
+/** 渲染端认领待执行调用的期限；超时视为页面未运行（信箱投递不重发）。 */
+export const MCP_APPS_APP_TOOL_CLAIM_TIMEOUT_MS = 5_000;
+/** 认领后页面执行 tools/call 的期限（规范推荐值）。 */
+export const MCP_APPS_APP_TOOL_CALL_TIMEOUT_MS = 30_000;
+/** 单次结果序列化上限（规范推荐值）。 */
+export const MCP_APPS_APP_TOOL_RESULT_MAX_BYTES = 10 * 1024 * 1024;
+/** 模型调用参数进信箱前的上限；超限直接以错误结束，不下发。 */
+export const MCP_APPS_APP_TOOL_ARGUMENTS_MAX_BYTES = 1024 * 1024;
+/** list_changed 触发的重新登记最小间隔。 */
+export const MCP_APPS_APP_TOOLS_REFRESH_INTERVAL_MS = 1_000;
+export const MCP_APPS_APP_TOOL_ERROR_MESSAGE_MAX_CHARS = 4096;
+export const MCP_APPS_APP_TOOL_CALL_ID_MAX_CHARS = 128;
+/** 模型侧名字前缀：与 server 工具的 `mcp__` 天然不冲突。 */
+export const MCP_APPS_APP_TOOL_MODEL_NAME_PREFIX = "app__";
+const utf8Bytes = (value) => new TextEncoder().encode(value).length;
+/** 与 agent 的 MCP 工具名同一清洗规则：非 `[A-Za-z0-9_-]` 替换为 `_` 并合并连续下划线。 */
+export function sanitizeMcpAppsModelNamePart(name) {
+    const sanitized = name.replace(/[^a-zA-Z0-9_-]/g, "_").replace(/_+/g, "_");
+    return sanitized.length > 0 ? sanitized : "unknown";
+}
+/** 模型侧名字 `app__<server>__<tool>`。 */
+export function buildMcpAppsAppToolModelName(serverName, toolName) {
+    return `${MCP_APPS_APP_TOOL_MODEL_NAME_PREFIX}${sanitizeMcpAppsModelNamePart(serverName)}__${sanitizeMcpAppsModelNamePart(toolName)}`;
+}
+const objectSchemaSchema = z
+    .record(z.string(), z.unknown())
+    .refine((value) => value.type === "object", { message: "schema type must be object" })
+    .refine((value) => utf8Bytes(JSON.stringify(value)) <= MCP_APPS_APP_TOOL_SCHEMA_MAX_BYTES, {
+    message: "schema is too large",
+});
+export const mcpAppsAppToolAnnotationsSchema = z.strictObject({
+    title: z.string().max(MCP_APPS_APP_TOOL_TITLE_MAX_CHARS).optional(),
+    readOnlyHint: z.boolean().optional(),
+    destructiveHint: z.boolean().optional(),
+    idempotentHint: z.boolean().optional(),
+    openWorldHint: z.boolean().optional(),
+});
+export const mcpAppsAppToolDescriptorSchema = z.strictObject({
+    name: z.string().min(1).max(MCP_APPS_APP_TOOL_NAME_MAX_CHARS),
+    title: z.string().max(MCP_APPS_APP_TOOL_TITLE_MAX_CHARS).optional(),
+    description: z.string().max(MCP_APPS_APP_TOOL_DESCRIPTION_MAX_CHARS).optional(),
+    inputSchema: objectSchemaSchema,
+    outputSchema: objectSchemaSchema.optional(),
+    annotations: mcpAppsAppToolAnnotationsSchema.optional(),
+});
+const ANNOTATION_BOOLEAN_KEYS = [
+    "readOnlyHint",
+    "destructiveHint",
+    "idempotentHint",
+    "openWorldHint",
+];
+/**
+ * 渲染端用：把页面 `tools/list` 的结果收窄成可登记的描述符。不合规的项跳过（不让整次登记失败），
+ * 超过 50 个只取前 50 个；返回被跳过的名字与原因供日志。
+ */
+export function normalizeMcpAppsAppTools(tools) {
+    const accepted = [];
+    const skipped = [];
+    const seen = new Set();
+    for (const raw of tools) {
+        const record = raw && typeof raw === "object" ? raw : null;
+        const name = typeof record?.name === "string" ? record.name : null;
+        if (accepted.length >= MCP_APPS_APP_TOOLS_MAX_PER_INSTANCE) {
+            skipped.push({ name, reason: "limit" });
+            continue;
+        }
+        if (!record || name === null) {
+            skipped.push({ name, reason: "invalid" });
+            continue;
+        }
+        if (seen.has(name)) {
+            skipped.push({ name, reason: "duplicate" });
+            continue;
+        }
+        const rawAnnotations = record.annotations && typeof record.annotations === "object"
+            ? record.annotations
+            : null;
+        const annotations = {};
+        if (typeof rawAnnotations?.title === "string")
+            annotations.title = rawAnnotations.title;
+        for (const key of ANNOTATION_BOOLEAN_KEYS) {
+            if (typeof rawAnnotations?.[key] === "boolean")
+                annotations[key] = rawAnnotations[key];
+        }
+        const candidate = {
+            name,
+            ...(typeof record.title === "string" ? { title: record.title } : {}),
+            ...(typeof record.description === "string" ? { description: record.description } : {}),
+            inputSchema: record.inputSchema,
+            ...(record.outputSchema !== undefined ? { outputSchema: record.outputSchema } : {}),
+            ...(Object.keys(annotations).length > 0 ? { annotations } : {}),
+        };
+        const parsed = mcpAppsAppToolDescriptorSchema.safeParse(candidate);
+        if (!parsed.success) {
+            skipped.push({ name, reason: parsed.error.issues[0]?.message ?? "invalid" });
+            continue;
+        }
+        seen.add(name);
+        accepted.push(parsed.data);
+    }
+    return { tools: accepted, skipped };
+}
+/** 页面 `tools/call` 的结果（MCP CallToolResult 形状，字段集宽松：content 项原样保留）。 */
+export const mcpAppsAppToolCallResultSchema = z.object({
+    content: z.array(z.record(z.string(), z.unknown())),
+    structuredContent: z.unknown().optional(),
+    isError: z.boolean().optional(),
+    _meta: z.record(z.string(), z.unknown()).optional(),
+});
+//# sourceMappingURL=appTools.js.map

package/node_modules/@dcode/shared/dist/mcp-apps/content.d.ts

@@ -0,0 +1,4 @@
+import type { McpAppsContentBlock } from "./hostContract.js";
+/** 把 content 块里的 text 拼成一段纯文本；非 text 块跳过。 */
+export declare function concatMcpAppsTextContent(content: readonly McpAppsContentBlock[]): string;
+//# sourceMappingURL=content.d.ts.map

package/node_modules/@dcode/shared/dist/mcp-apps/content.js

@@ -0,0 +1,8 @@
+/** 把 content 块里的 text 拼成一段纯文本；非 text 块跳过。 */
+export function concatMcpAppsTextContent(content) {
+    return content
+        .filter((block) => block.type === "text" && typeof block.text === "string")
+        .map((block) => block.text)
+        .join("\n");
+}
+//# sourceMappingURL=content.js.map

package/node_modules/@dcode/shared/dist/mcp-apps/contract.d.ts

@@ -0,0 +1,241 @@
+/**
+ * MCP Apps 协议契约：agent、host、renderer 与 main 共用的常量、工具 UI 元数据类型、沙箱句柄与登记载荷。
+ * 页面 ↔ 宿主的线协议（`ui/*` 方法、握手、版本协商、JSON-RPC）由官方 `@modelcontextprotocol/ext-apps` 定义，
+ * 这里只保留 DCode 自己的扩展键与限额。只放类型与常量；归一化与 schema 在同目录其他文件，经 index.ts 导出。
+ */
+/** MCP 扩展标识（规范「Extension Identifier」）；与官方 SDK `EXTENSION_ID` 一致。 */
+export declare const MCP_APPS_EXTENSION_ID = "io.modelcontextprotocol/ui";
+/** UI 资源 mimeType（规范 MUST）；与官方 SDK `RESOURCE_MIME_TYPE` 一致。 */
+export declare const MCP_APPS_RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/** 弃用的扁平键 `_meta["ui/resourceUri"]`；规范要求宿主 MUST 同时兼容，与官方 SDK `RESOURCE_URI_META_KEY` 一致。 */
+export declare const MCP_APPS_LEGACY_RESOURCE_URI_META_KEY = "ui/resourceUri";
+/**
+ * MCP client `initialize` 里的 ui 扩展能力声明（规范「Client (Host) Capabilities」）。
+ * 用 type 而不是 interface：MCP SDK 的 `ClientCapabilities.extensions` 要求值带字符串索引签名。
+ */
+export type McpAppsClientCapability = {
+    mimeTypes: string[];
+};
+/** agent 对每个 MCP server 宣告的能力片段；放进 `Client` 构造参数的 `capabilities.extensions`。 */
+export declare function buildMcpAppsClientCapabilities(): {
+    extensions: {
+        [extensionId: string]: McpAppsClientCapability;
+    };
+};
+/** 宿主 hostInfo.name；hostInfo.version 只供页面 feature detect，与应用版本无关。 */
+export declare const MCP_APPS_HOST_NAME = "dcode";
+export declare const MCP_APPS_HOST_VERSION = "1";
+/** `ui/initialize` 握手超时（端口到达起算）与卸载前 `ui/resource-teardown` 的等待上限。 */
+export declare const MCP_APPS_HANDSHAKE_TIMEOUT_MS = 15000;
+export declare const MCP_APPS_TEARDOWN_TIMEOUT_MS = 500;
+export type McpAppsDisplayMode = "inline" | "fullscreen" | "pip";
+export type McpAppsToolVisibility = "model" | "app";
+export declare const MCP_APPS_DEFAULT_TOOL_VISIBILITY: readonly McpAppsToolVisibility[];
+/** MCP Apps 资源级 CSP（`McpUiResourceCsp`）：四类域。资源 `_meta` 为主，工具级 `_meta.ui.csp` 只在资源没有声明时兜底。 */
+export interface McpToolUiCsp {
+    connectDomains?: string[];
+    resourceDomains?: string[];
+    frameDomains?: string[];
+    baseUriDomains?: string[];
+}
+/**
+ * 资源级 `_meta["dcode/csp"]`：宿主缺省按规范块（只有 'self' 'unsafe-inline'），不放行 `'unsafe-eval'` /
+ * `'wasm-unsafe-eval'`；需要 eval / WebAssembly 的资源在这里显式声明。宿主经
+ * `hostCapabilities.experimental["dcode/csp"].flags` 宣告支持的键。
+ */
+export declare const MCP_APPS_CSP_RELAXATION_META_KEY = "dcode/csp";
+export declare const MCP_APPS_CSP_RELAXATION_FLAGS: readonly ["unsafeEval", "wasmUnsafeEval"];
+export type McpAppCspRelaxationFlag = (typeof MCP_APPS_CSP_RELAXATION_FLAGS)[number];
+export type McpAppCspRelaxations = Partial<Record<McpAppCspRelaxationFlag, boolean>>;
+export declare function buildMcpAppsCspExperimentalCapability(): {
+    [MCP_APPS_CSP_RELAXATION_META_KEY]: {
+        flags: McpAppCspRelaxationFlag[];
+    };
+};
+/**
+ * 资源可声明的浏览器权限（规范草案 `UIResourceMeta.permissions` 的四键），顺序即归一化顺序。
+ * 宿主：未声明一律拒绝；camera / microphone / geolocation 首次使用时原生弹框确认，clipboardWrite 按声明放行。
+ */
+export declare const MCP_APPS_RESOURCE_PERMISSIONS: readonly ["camera", "microphone", "geolocation", "clipboardWrite"];
+export type McpAppsResourcePermission = (typeof MCP_APPS_RESOURCE_PERMISSIONS)[number];
+/** 规范权限键 → 插件 iframe `allow` 的 Permissions Policy 特性名。 */
+export declare const MCP_APPS_IFRAME_ALLOW_TOKENS: Record<McpAppsResourcePermission, string>;
+/** 与官方 SDK `buildAllowAttribute` 同形：`"camera; clipboard-write"`；没有声明返回空串。 */
+export declare function buildMcpAppsIframeAllow(permissions: readonly McpAppsResourcePermission[] | undefined): string;
+/**
+ * `ui://` HTML 资源自己的 `_meta`（`resources/read` 内容项优先）。`heightHint` / `minFrameHeight` 是初始高度与
+ * 最小高度（px）；`showInline` 为 true 时卡片强制常驻、不进折叠区。
+ */
+export interface McpAppResourceMeta {
+    csp?: McpToolUiCsp;
+    cspRelaxations?: McpAppCspRelaxations;
+    /** `_meta.ui.permissions` 声明的浏览器权限（规范四键；顺序固定、去重）。 */
+    permissions?: McpAppsResourcePermission[];
+    prefersBorder?: boolean;
+    heightHint?: number;
+    minFrameHeight?: number;
+    showInline?: boolean;
+}
+/** 随沙箱句柄回到 renderer 的资源级呈现信息；CSP 与放宽只在 main 生效，不回传。 */
+export type PluginSandboxResourceMeta = Omit<McpAppResourceMeta, "csp" | "cspRelaxations">;
+/** 工具 `_meta` 归一化后的 UI 描述；`resourceUri` 非法时整个描述不存在。 */
+export interface McpToolUiDescriptor {
+    resourceUri: string;
+    visibility?: McpAppsToolVisibility[];
+    preferredDisplayMode?: McpAppsDisplayMode;
+    csp?: McpToolUiCsp;
+    prefersBorder?: boolean;
+    /** 工具结果归属的面板 id（清单 `ui.surfaces[].id`）。 */
+    surface?: string;
+    /** 工具级 `openai/widgetShowCodexWidgetInline`，卡片强制常驻。 */
+    showInline?: boolean;
+}
+/** `_meta.ui.surface` / 清单 surface id 的长度与字符集（与 sandboxId 同源：可进 CSP host-source）。 */
+export declare const MCP_APPS_SURFACE_ID_MAX_CHARS = 128;
+export declare const MCP_APPS_SURFACE_ID_PATTERN: RegExp;
+export declare const MCP_APPS_UI_RESOURCE_SCHEME = "ui://";
+export declare const MCP_APPS_RESOURCE_URI_MAX_CHARS = 2048;
+/**
+ * `display.ui.structuredContent` / `widgetMeta` / `content` 的持久化上限（JSON 文本的 UTF-8 字节）。
+ * 超限不截断字符串（半截 JSON 没有意义）：字段整个省略，`truncated: true` 且 `truncatedBytes` 记被丢弃的字节数；
+ * 页面侧 `toolOutput` 为 null、`toolResponseMetadata["dcode/truncated"] = { bytes }`，可用 tools/call 重取。
+ */
+export declare const MCP_APPS_STRUCTURED_CONTENT_MAX_BYTES: number;
+export declare const MCP_APPS_WIDGET_META_MAX_BYTES: number;
+export declare const MCP_APPS_CONTENT_MAX_BYTES: number;
+export declare const MCP_APPS_TRUNCATED_META_KEY = "dcode/truncated";
+/** host 侧接受的 `ui://` HTML 上限与 mimeType 白名单（规范只认带 profile 的；无 profile 的 text/html 是有意的宽松超集）。 */
+export declare const MCP_APPS_HTML_MAX_BYTES: number;
+export declare const MCP_APPS_HTML_MIME_TYPES: readonly ["text/html;profile=mcp-app", "text/html"];
+/**
+ * 页面经 ui/update-model-context 与 ui/message 送来的 image 块：白名单三种位图，单张解码后 ≤ 4 MiB；
+ * 不在白名单或超限整个请求 -32602 `unsupported_content`。
+ */
+export declare const MCP_APPS_IMAGE_MIME_TYPES: readonly ["image/png", "image/jpeg", "image/webp"];
+export declare const MCP_APPS_IMAGE_MAX_BYTES: number;
+export { MCP_APPS_UI_READ_RESOURCE_MAX_BYTES, MCP_APPS_UI_READ_RESOURCE_MIME_ALLOWLIST, isMcpAppsUiReadResourceMimeAllowed, } from "./resourceMime.js";
+/**
+ * `hostCapabilities.experimental` 里 DCode 扩展的键。官方 SDK 的 zod 会剥掉标准位之外的未知能力键，
+ * 扩展一律放 experimental（规范预留位），页面按键 feature detect。
+ */
+export declare const MCP_APPS_WIDGET_STATE_EXPERIMENTAL_KEY = "dcode/widgetState";
+export declare const MCP_APPS_RESOURCE_SUBSCRIBE_EXPERIMENTAL_KEY = "dcode/resourceSubscribe";
+export declare const MCP_APPS_SURFACE_EXPERIMENTAL_KEY = "dcode/surface";
+/**
+ * DCode 扩展方法 `ui/set-widget-state { widgetState }`（MCP Apps 无 widgetState）：页面把界面状态交给宿主
+ * renderer 内存保存（不持久化，会话内重挂载可恢复）；初值经 hostContext 的 `dcode/widgetState` 键随握手下发。
+ */
+export declare const MCP_APPS_SET_WIDGET_STATE_METHOD = "ui/set-widget-state";
+export declare const MCP_APPS_WIDGET_STATE_CONTEXT_KEY = "dcode/widgetState";
+/** 宿主 renderer ↔ relay shell 之间唯一一条 MessageChannel 的名字；上面跑原始 JSON-RPC（官方 AppBridge / App）。 */
+export declare const PLUGIN_SANDBOX_PORT_NAME = "plugin-sandbox-rpc";
+/** MessagePort 的最小结构类型；宿主 renderer 的 Transport 与 relay shell 都只依赖这几个成员。 */
+export interface PluginSandboxTransportPort {
+    postMessage(message: unknown): void;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    start?(): void;
+    close(): void;
+}
+/** main → 宿主 renderer 的端口事件（经 preload `window.postMessage` transfer）。 */
+export interface PluginSandboxPortsEvent {
+    sandboxId: string;
+    initId: number;
+    port: PluginSandboxTransportPort;
+}
+/**
+ * renderer 可用的沙箱平台端口，以 `IPlatformService.pluginSandbox` 可选字段挂载；web 端为 undefined，UI 据此回退。
+ * 登记沙箱不在这里：它由 host 经 parentPort 完成，renderer 只拿句柄。
+ */
+export interface PluginSandboxPlatformPort {
+    /** preload 已安装限定的沙箱原子移动适配。 */
+    supportsRetainedMove?: boolean;
+    /** 仅宿主操作可用；Main 校验 owner/代次后复制当前页面内容。 */
+    copyImage?(input: PluginSandboxCaptureRequest): Promise<void>;
+    /** 宿主窗口 webContents id；prepareSandbox 用它作为 owner，main 在 will-attach 时校验。 */
+    getOwnerWebContentsId(): Promise<number>;
+    /**
+     * 释放沙箱。带 initId 时只释放捕获的登记：新页面使用新 Agent 凭证和 sandboxId，
+     * 两条 IPC 路径不同（host parentPort vs ipcMain），旧 dispose 到得晚也不能误杀新登记。
+     */
+    disposeSandbox(sandboxId: string, initId?: number): Promise<void>;
+    consumeUserGesture(sandboxId: string): Promise<boolean>;
+    onPorts(handler: (event: PluginSandboxPortsEvent) => void): () => void;
+}
+export interface PluginSandboxCaptureRequest {
+    sandboxId: string;
+    initId: number;
+    captureRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    viewportSize: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * 沙箱作用域。工具卡片按 toolCallId，面板（清单 `ui.surfaces[]`）按 surfaceId；
+ * 两者都映射到一个字符串 scopeId 进注册表幂等键与 widgetState 路由，避免 main / host 认识"面板"概念。
+ */
+export type PluginUiScopeRef = {
+    kind: "toolCall";
+    toolCallId: string;
+} | {
+    kind: "surface";
+    surfaceId: string;
+};
+export declare function buildPluginSandboxScopeId(scope: PluginUiScopeRef): string;
+/** host → main 登记沙箱内容的消息载荷（模式同 LocalMediaPreviewPathAuthorize*）。 */
+export interface PluginSandboxRegisterRequestPayload {
+    instance: import("./instance.js").McpAppInstance;
+    requestId: string;
+    /** 工作区隔离；旧调用允许缺省，新宿主登记须贯穿实际 workspace 范围。 */
+    workspacePath?: string;
+    workspaceIdentity?: string;
+    ownerWebContentsId: number;
+    sessionId: string;
+    /** Gen UI has Host provenance and never impersonates an MCP plugin. */
+    contentKind?: "gen-ui";
+    pluginId?: string;
+    /** 资源所属的 MCP server 运行时名；沙箱 partition 按它派生（同一 server 的页面共享一份持久存储）。 */
+    serverName?: string;
+    /** `buildPluginSandboxScopeId` 的结果：`tool:<toolCallId>` 或 `surface:<surfaceId>`。 */
+    scopeId: string;
+    html: string;
+    /** 有效 CSP：资源级优先，工具级兜底（host plugin-ui-bridge 已合并）。 */
+    csp?: McpToolUiCsp;
+    /** 资源级 `_meta["dcode/csp"]` 声明的放宽项。 */
+    cspRelaxations?: McpAppCspRelaxations;
+    /** 资源声明的浏览器权限；main 据此放宽 Permissions-Policy 与 iframe allow，并把权限请求交给闸门。 */
+    permissions?: McpAppsResourcePermission[];
+    prefersBorder?: boolean;
+    /** 资源级尺寸提示，原样进句柄回给 renderer。 */
+    heightHint?: number;
+    minFrameHeight?: number;
+    /** 资源级强制常驻标记，随句柄 resourceMeta 回 renderer。 */
+    showInline?: boolean;
+}
+/** host 内部使用的登记输入：去掉传输层 requestId。 */
+export type PluginSandboxRegisterInput = Omit<PluginSandboxRegisterRequestPayload, "requestId">;
+export interface PluginSandboxHandle {
+    instance: import("./instance.js").McpAppInstance;
+    sandboxId: string;
+    initId: number;
+    shellUrl: string;
+    partition: string;
+    /** 资源级呈现信息（prefersBorder / heightHint / minFrameHeight / showInline）；资源没声明时省略。 */
+    resourceMeta?: PluginSandboxResourceMeta;
+}
+export type PluginSandboxRegisterResultPayload = ({
+    requestId: string;
+    ok: true;
+} & PluginSandboxHandle) | {
+    requestId: string;
+    ok: false;
+    error: string;
+};
+//# sourceMappingURL=contract.d.ts.map

package/node_modules/@dcode/shared/dist/mcp-apps/contract.example.d.ts

@@ -0,0 +1,31 @@
+import type { McpToolUiDescriptor, PluginSandboxHandle } from "./contract.js";
+/** 一个带 UI 资源的工具 `_meta` 归一化后应得到的描述。 */
+export declare const exampleToolUiDescriptor: McpToolUiDescriptor;
+/** main 登记成功后返回给 renderer 的句柄；partition 按 server 身份派生，同一 server 的页面共享。 */
+export declare const exampleSandboxHandle: PluginSandboxHandle;
+/** agent 对 MCP server `initialize` 时宣告的 ui 扩展能力。 */
+export declare const exampleClientCapabilities: {
+    extensions: {
+        [extensionId: string]: import("./contract.js").McpAppsClientCapability;
+    };
+};
+/** 宿主在 hostCapabilities.experimental 里宣告的 CSP 放宽键。 */
+export declare const exampleCspExperimental: {
+    "dcode/csp": {
+        flags: import("./contract.js").McpAppCspRelaxationFlag[];
+    };
+};
+/** 资源级 `_meta` 里声明放宽的写法。 */
+export declare const exampleResourceMetaWithRelaxations: {
+    ui: {
+        csp: {
+            connectDomains: string[];
+        };
+    };
+    "dcode/csp": {
+        unsafeEval: boolean;
+    };
+};
+export declare const exampleSetWidgetStateMethod = "ui/set-widget-state";
+export declare const examplePortName = "plugin-sandbox-rpc";
+//# sourceMappingURL=contract.example.d.ts.map