qcanvas-local-agent 0.1.0 → 0.1.1

package/README.md

@@ -1,5 +1,19 @@
 # qcanvas-local-agent
 
+## 发布新版固定流程
+
+每次修改本地 Agent 后，如需让 `npx -y qcanvas-local-agent` 获取新能力，必须按以下顺序发布：
+
+```powershell
+cd "D:\胡东山\py学习\QCanvas\apps\qcanvas-local-agent"
+npm run build
+# 手动将 package.json 的 version 提升到一个从未发布过的新版本
+npm publish
+# npm 要求双重验证时：npm publish --otp=手机显示的6位验证码
+```
+
+发布后使用 `npm view qcanvas-local-agent version` 验证 registry 已更新。禁止重复使用已经发布过的版本号，也不要使用会自动创建 Git tag 的 `npm version`。
+
 QCanvas 「本机 Agent」：在你自己的电脑上运行一个本地桥接服务，让 QCanvas 网页画布可以调用**本机登录的 Codex / Claude** 来读写画布。
 
 ## 一条命令启动
@@ -34,3 +48,16 @@ npx -y qcanvas-local-agent
 
 - 所有对画布的写操作都会由浏览器二次确认后才真正应用。
 - 令牌仅用于本机 `127.0.0.1` 回环连接的鉴权。
+
+## 画布 MCP 工具
+
+- `tapcanvas_flow_get`：读取浏览器实时画布快照。
+- `tapcanvas_node_context_bundle_get`：按 `nodeId` 读取节点、上下游、节点契约、已绑定预设和当前启用模型；省略 `nodeId` 时只允许画布恰好选中一个节点。
+- `tapcanvas_node_presets_get`：读取浏览器已同步的真实节点预设，可按精确 `id` 和 `type` 筛选。
+- `tapcanvas_node_prompt_preview`：查看节点当前提示词、绑定预设、精确差异和结构性就绪状态；它不会伪装成生成 runner 的最终提示词编译结果。省略 `nodeId` 时同样要求恰好选中一个节点。
+
+上述三个节点取证工具与云端 Agents Bridge 使用同一组顶层响应契约（`nodeContract`、`presetBinding`、`modelCatalog`、`divergence`、`structuralReadiness`）；浏览器会同时同步运行时节点 kind 到规范契约的真实映射，因此 `storyboardImage`、`composeVideo` 等派生 kind 不需要本地 Agent 维护第二套节点知识。
+- `tapcanvas_create_generation_flow`：创建并连接单个生成节点，但不会自动提交生成。
+- `tapcanvas_flow_patch`：提交需浏览器确认的画布结构变更。
+
+以上只读工具只使用已连接浏览器同步的实时快照。未知节点、未知预设，以及预设或模型目录加载失败都会显式报错，不会返回伪造数据或静默兜底。

package/dist/canvas-session.js

@@ -1,5 +1,6 @@
 import crypto from "node:crypto";
-import { isLocalAgentToolName, localAgentToolInputSchemas } from "./schemas.js";
+import { isLocalAgentToolName, localAgentToolInputSchemas, localCanvasCapabilitiesSchema, } from "./schemas.js";
+import { getNodeContextBundle, getNodePresets, getNodePromptPreview, resolveNodeId, } from "./node-introspection.js";
 import { compileGenerationFlow, GenerationFlowCompileError, } from "./generation-flow-compiler.js";
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -31,6 +32,7 @@ function parseCanvasSnapshot(value, clientId) {
         throw new Error("canvas state missing nodes array");
     if (!edges)
         throw new Error("canvas state missing edges array");
+    const capabilities = localCanvasCapabilitiesSchema.parse(value);
     return {
         clientId,
         url: readString(value.url),
@@ -42,6 +44,7 @@ function parseCanvasSnapshot(value, clientId) {
         edges,
         selectedNodeIds: readStringArray(value.selectedNodeIds),
         viewport: readViewport(value.viewport),
+        ...capabilities,
         updatedAt: readString(value.updatedAt) || new Date().toISOString(),
     };
 }
@@ -105,6 +108,20 @@ export class CanvasSession {
         }
         if (rawName === "tapcanvas_flow_get")
             return this.readFlow();
+        if (rawName === "tapcanvas_node_context_bundle_get") {
+            const parsed = localAgentToolInputSchemas.tapcanvas_node_context_bundle_get.parse(input);
+            const snapshot = this.readFlow();
+            return getNodeContextBundle(snapshot, resolveNodeId(snapshot, parsed.nodeId));
+        }
+        if (rawName === "tapcanvas_node_presets_get") {
+            const parsed = localAgentToolInputSchemas.tapcanvas_node_presets_get.parse(input);
+            return getNodePresets(this.readFlow(), parsed);
+        }
+        if (rawName === "tapcanvas_node_prompt_preview") {
+            const parsed = localAgentToolInputSchemas.tapcanvas_node_prompt_preview.parse(input);
+            const snapshot = this.readFlow();
+            return getNodePromptPreview(snapshot, resolveNodeId(snapshot, parsed.nodeId));
+        }
         if (rawName === "tapcanvas_create_generation_flow")
             return this.createGenerationFlow(input, agent);
         return this.requestBrowserPatch(rawName, input, agent);

package/dist/mcp-server.js

@@ -5,6 +5,8 @@ import { localAgentToolDescriptions, localAgentToolInputSchemas, localAgentToolN
 const INSTRUCTIONS = [
     "Use QCanvas local tools only for the connected live browser canvas.",
     "Read tapcanvas_flow_get before writing.",
+    "Use tapcanvas_node_context_bundle_get to inspect a node's live contract, graph neighbors, bound preset, and enabled models before deciding how to edit or execute it.",
+    "Use tapcanvas_node_presets_get for on-demand preset lookup and tapcanvas_node_prompt_preview for factual prompt/readiness inspection. The preview never claims to reproduce runner prompt compilation.",
     "Prefer tapcanvas_create_generation_flow over tapcanvas_flow_patch when creating a single generation node with reference wiring; it auto-computes placement, handles, and reference asset inputs. It only creates the node and never submits generation by itself.",
     "All tapcanvas_flow_patch writes (including those issued by tapcanvas_create_generation_flow) are confirmed by the browser before they apply.",
     "If no live browser tab is connected, report the error directly.",

package/dist/node-introspection.d.ts

@@ -0,0 +1,14 @@
+import type { QCanvasNodePreset, QCanvasSnapshot } from "./types.js";
+export declare function resolveNodeId(snapshot: QCanvasSnapshot, requestedNodeId?: string): string;
+export declare function getNodePresets(snapshot: QCanvasSnapshot, input: {
+    id?: string;
+    type?: "text" | "image" | "video";
+}): {
+    items: Array<QCanvasNodePreset | Omit<QCanvasNodePreset, "prompt">>;
+    filter: {
+        id: string | null;
+        type: "text" | "image" | "video" | null;
+    };
+};
+export declare function getNodeContextBundle(snapshot: QCanvasSnapshot, nodeId: string): Record<string, unknown>;
+export declare function getNodePromptPreview(snapshot: QCanvasSnapshot, nodeId: string): Record<string, unknown>;

package/dist/node-introspection.js

@@ -0,0 +1,270 @@
+export function resolveNodeId(snapshot, requestedNodeId) {
+    if (requestedNodeId)
+        return requestedNodeId;
+    if (snapshot.selectedNodeIds.length === 1) {
+        const selectedNodeId = snapshot.selectedNodeIds[0];
+        if (selectedNodeId)
+            return selectedNodeId;
+    }
+    throw new Error(`nodeId is required when the live canvas has ${snapshot.selectedNodeIds.length} selected nodes; select exactly one node or provide nodeId`);
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function requiredString(record, key, label) {
+    const value = record[key];
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`${label} missing ${key}`);
+    return value.trim();
+}
+function optionalString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function readNodes(snapshot) {
+    return snapshot.nodes.map((value, index) => {
+        if (!isRecord(value))
+            throw new Error(`canvas node at index ${index} must be an object`);
+        const id = requiredString(value, "id", `canvas node at index ${index}`);
+        if (!isRecord(value.data))
+            throw new Error(`canvas node ${id} missing data object`);
+        return { ...value, id, data: value.data };
+    });
+}
+function readEdges(snapshot) {
+    return snapshot.edges.map((value, index) => {
+        if (!isRecord(value))
+            throw new Error(`canvas edge at index ${index} must be an object`);
+        return {
+            ...value,
+            id: requiredString(value, "id", `canvas edge at index ${index}`),
+            source: requiredString(value, "source", `canvas edge at index ${index}`),
+            target: requiredString(value, "target", `canvas edge at index ${index}`),
+        };
+    });
+}
+function assertCapability(snapshot, capability) {
+    const error = snapshot.capabilityErrors.find((item) => item.startsWith(`${capability}:`));
+    if (error)
+        throw new Error(`browser snapshot capability unavailable: ${error}`);
+}
+function findNode(snapshot, nodeId) {
+    const node = readNodes(snapshot).find((item) => item.id === nodeId);
+    if (!node)
+        throw new Error(`QCanvas node does not exist: ${nodeId}`);
+    return node;
+}
+function findContract(snapshot, node) {
+    const kind = requiredString(node.data, "kind", `QCanvas node ${node.id}.data`);
+    const normalizedKind = kind.toLowerCase();
+    const contract = snapshot.nodeContracts.find((item) => item.kind === kind || item.runtimeKinds.some((runtimeKind) => runtimeKind.toLowerCase() === normalizedKind));
+    if (!contract)
+        throw new Error(`QCanvas node contract does not exist for kind: ${kind}`);
+    return contract;
+}
+function resolvePreset(snapshot, node) {
+    const presetId = optionalString(node.data.llmPresetId);
+    if (!presetId)
+        return null;
+    assertCapability(snapshot, "nodePresets");
+    return snapshot.nodePresets.find((item) => item.id === presetId) ?? null;
+}
+function findModel(snapshot, identifier) {
+    return Object.values(snapshot.enabledModels)
+        .flat()
+        .find((item) => item.modelKey === identifier || item.modelAlias === identifier) ?? null;
+}
+function readModelBinding(node, contract) {
+    const fields = contract.promptEditor?.presetType === "image"
+        ? ["imageModel", "modelSelect", "modelKey", "geminiModel"]
+        : contract.promptEditor?.presetType === "video"
+            ? ["videoModel", "modelSelect", "modelKey", "geminiModel"]
+            : contract.promptEditor?.presetType === "text"
+                ? ["geminiModel", "modelSelect", "modelKey"]
+                : contract.kind === "audio"
+                    ? ["model", "modelSelect", "modelKey"]
+                    : ["modelKey", "modelSelect", "geminiModel"];
+    for (const field of fields) {
+        const modelKey = optionalString(node.data[field]);
+        if (modelKey)
+            return { field, modelKey };
+    }
+    return null;
+}
+function toNodeContract(contract, runtimeKind) {
+    return {
+        kind: runtimeKind,
+        known: true,
+        label: contract.label,
+        purpose: contract.promptEditor?.purpose ?? null,
+        fields: {},
+        input: { handles: contract.handles.targets },
+        output: { handles: contract.handles.sources },
+        editorGuidance: contract.promptEditor
+            ? {
+                promptField: "prompt",
+                placeholder: contract.promptEditor.placeholder,
+                presetType: contract.promptEditor.presetType,
+                supportsMentions: contract.promptEditor.supportsMentions,
+                upstreamBehavior: contract.promptEditor.upstreamBehavior,
+                previewBoundary: contract.promptEditor.previewBoundary,
+            }
+            : null,
+    };
+}
+function buildPresetBinding(node, contract, preset) {
+    const presetId = optionalString(node.data.llmPresetId);
+    return {
+        presetId,
+        presetType: contract.promptEditor?.presetType ?? null,
+        presetTitle: preset?.title ?? optionalString(node.data.llmPresetTitle),
+        status: !presetId ? "not_bound" : preset ? "resolved" : "unavailable",
+    };
+}
+function buildModelCatalog(snapshot) {
+    return {
+        status: "available",
+        summary: {
+            textModels: snapshot.enabledModels.text,
+            imageModels: snapshot.enabledModels.image,
+            videoModels: snapshot.enabledModels.video,
+            audioModels: snapshot.enabledModels.audio,
+        },
+    };
+}
+function readPrimaryAssetUrl(node, field) {
+    return optionalString(node.data[field]);
+}
+function collectUpstreamAssetUrls(nodes) {
+    const urls = new Set();
+    nodes.forEach((node) => {
+        const imageUrl = readPrimaryAssetUrl(node, "imageUrl");
+        const videoUrl = readPrimaryAssetUrl(node, "videoUrl");
+        if (imageUrl)
+            urls.add(imageUrl);
+        if (videoUrl)
+            urls.add(videoUrl);
+    });
+    return Array.from(urls);
+}
+function enabledModelsForContract(snapshot, contract) {
+    if (contract.kind === "audio")
+        return snapshot.enabledModels.audio;
+    const presetType = contract.promptEditor?.presetType;
+    return presetType ? snapshot.enabledModels[presetType] : null;
+}
+function enabledModelMissingKey(contract) {
+    if (contract.kind === "audio")
+        return "enabledAudioModel";
+    if (contract.promptEditor?.presetType === "image")
+        return "enabledImageModel";
+    if (contract.promptEditor?.presetType === "video")
+        return "enabledVideoModel";
+    return "enabledTextModel";
+}
+export function getNodePresets(snapshot, input) {
+    assertCapability(snapshot, "nodePresets");
+    if (input.id && !snapshot.nodePresets.some((item) => item.id === input.id)) {
+        throw new Error(`QCanvas node preset does not exist: ${input.id}`);
+    }
+    const matched = snapshot.nodePresets.filter((item) => (!input.id || item.id === input.id) && (!input.type || item.type === input.type));
+    if (input.id && matched.length === 0) {
+        throw new Error(`QCanvas node preset ${input.id} does not match requested type: ${input.type}`);
+    }
+    const items = input.id
+        ? matched
+        : matched.map(({ prompt: _prompt, ...summary }) => summary);
+    return { items, filter: { id: input.id ?? null, type: input.type ?? null } };
+}
+export function getNodeContextBundle(snapshot, nodeId) {
+    const node = findNode(snapshot, nodeId);
+    const contract = findContract(snapshot, node);
+    assertCapability(snapshot, "nodePresets");
+    assertCapability(snapshot, "enabledModels");
+    const resolvedPreset = resolvePreset(snapshot, node);
+    const runtimeKind = requiredString(node.data, "kind", `QCanvas node ${node.id}.data`);
+    const nodes = readNodes(snapshot);
+    const nodeById = new Map(nodes.map((item) => [item.id, item]));
+    const edges = readEdges(snapshot);
+    const upstreamEdges = edges.filter((edge) => edge.target === nodeId);
+    const downstreamEdges = edges.filter((edge) => edge.source === nodeId);
+    const resolveConnectedNode = (id) => {
+        const connected = nodeById.get(id);
+        if (!connected)
+            throw new Error(`canvas edge references unknown node: ${id}`);
+        return connected;
+    };
+    const upstreamNodes = upstreamEdges.map((edge) => resolveConnectedNode(edge.source));
+    const downstreamNodes = downstreamEdges.map((edge) => resolveConnectedNode(edge.target));
+    return {
+        projectId: snapshot.projectId,
+        flowId: snapshot.flowId,
+        nodeId,
+        node,
+        nodeContract: toNodeContract(contract, runtimeKind),
+        presetBinding: buildPresetBinding(node, contract, resolvedPreset),
+        selectedPreset: resolvedPreset,
+        modelCatalog: buildModelCatalog(snapshot),
+        upstreamNodes,
+        downstreamNodes,
+        snapshotUpdatedAt: snapshot.updatedAt,
+    };
+}
+export function getNodePromptPreview(snapshot, nodeId) {
+    const node = findNode(snapshot, nodeId);
+    const contract = findContract(snapshot, node);
+    if (!contract.promptEditor) {
+        throw new Error(`QCanvas node prompt editor contract is not declared for kind: ${contract.kind}`);
+    }
+    assertCapability(snapshot, "nodePresets");
+    assertCapability(snapshot, "enabledModels");
+    const preset = resolvePreset(snapshot, node);
+    const currentPrompt = optionalString(node.data.prompt);
+    const modelBinding = readModelBinding(node, contract);
+    const model = modelBinding ? findModel(snapshot, modelBinding.modelKey) : null;
+    const presetBinding = buildPresetBinding(node, contract, preset);
+    const presetId = optionalString(node.data.llmPresetId);
+    const divergence = !presetId
+        ? "not_bound"
+        : !preset
+            ? "bound_preset_unavailable"
+            : currentPrompt === preset.prompt.trim()
+                ? "matches_preset"
+                : "differs_from_preset";
+    const enabledModels = enabledModelsForContract(snapshot, contract);
+    const missing = [];
+    if (["image", "panorama360", "video", "audio"].includes(contract.kind) && !currentPrompt)
+        missing.push("prompt");
+    if (enabledModels && enabledModels.length === 0)
+        missing.push(enabledModelMissingKey(contract));
+    else if (modelBinding && !model)
+        missing.push("selectedModelEnabled");
+    const nodes = readNodes(snapshot);
+    const nodeById = new Map(nodes.map((item) => [item.id, item]));
+    const upstreamNodes = readEdges(snapshot)
+        .filter((edge) => edge.target === nodeId)
+        .map((edge) => {
+        const upstream = nodeById.get(edge.source);
+        if (!upstream)
+            throw new Error(`canvas edge references unknown node: ${edge.source}`);
+        return upstream;
+    });
+    return {
+        projectId: snapshot.projectId,
+        flowId: snapshot.flowId,
+        nodeId,
+        currentPrompt,
+        presetBinding,
+        resolvedPreset: preset,
+        divergence,
+        structuralReadiness: {
+            ready: missing.length === 0,
+            missing,
+            selectedModelKey: modelBinding?.modelKey ?? null,
+            selectedModelEnabled: modelBinding ? Boolean(model) : null,
+            enabledModelCount: enabledModels?.length ?? null,
+            upstreamAssetUrls: collectUpstreamAssetUrls(upstreamNodes),
+            note: "This result validates browser snapshot fields, the dynamic model catalog, and real upstream asset URLs only; it does not reproduce runner prompt or model-request compilation.",
+        },
+        snapshotUpdatedAt: snapshot.updatedAt,
+    };
+}

package/dist/schemas.d.ts

@@ -1,8 +1,498 @@
 import { z } from "zod";
-export declare const localAgentToolNames: readonly ["tapcanvas_flow_get", "tapcanvas_create_generation_flow", "tapcanvas_flow_patch"];
+export declare const localCanvasCapabilitiesSchema: z.ZodObject<{
+    nodeContracts: z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        runtimeKinds: z.ZodArray<z.ZodString, "many">;
+        label: z.ZodString;
+        category: z.ZodString;
+        features: z.ZodArray<z.ZodString, "many">;
+        handles: z.ZodObject<{
+            dynamic: z.ZodBoolean;
+            targets: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                type: z.ZodString;
+                position: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                id: string;
+                type: string;
+                position?: string | undefined;
+            }, {
+                id: string;
+                type: string;
+                position?: string | undefined;
+            }>, "many">;
+            sources: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                type: z.ZodString;
+                position: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                id: string;
+                type: string;
+                position?: string | undefined;
+            }, {
+                id: string;
+                type: string;
+                position?: string | undefined;
+            }>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            dynamic: boolean;
+            targets: {
+                id: string;
+                type: string;
+                position?: string | undefined;
+            }[];
+            sources: {
+                id: string;
+                type: string;
+                position?: string | undefined;
+            }[];
+        }, {
+            dynamic: boolean;
+            targets: {
+                id: string;
+                type: string;
+                position?: string | undefined;
+            }[];
+            sources: {
+                id: string;
+                type: string;
+                position?: string | undefined;
+            }[];
+        }>;
+        promptEditor: z.ZodNullable<z.ZodObject<{
+            purpose: z.ZodString;
+            placeholder: z.ZodString;
+            presetType: z.ZodNullable<z.ZodEnum<["text", "image", "video"]>>;
+            supportsMentions: z.ZodBoolean;
+            upstreamBehavior: z.ZodString;
+            previewBoundary: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            purpose: string;
+            placeholder: string;
+            presetType: "text" | "image" | "video" | null;
+            supportsMentions: boolean;
+            upstreamBehavior: string;
+            previewBoundary: string;
+        }, {
+            purpose: string;
+            placeholder: string;
+            presetType: "text" | "image" | "video" | null;
+            supportsMentions: boolean;
+            upstreamBehavior: string;
+            previewBoundary: string;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        kind: string;
+        runtimeKinds: string[];
+        label: string;
+        category: string;
+        features: string[];
+        handles: {
+            dynamic: boolean;
+            targets: {
+                id: string;
+                type: string;
+                position?: string | undefined;
+            }[];
+            sources: {
+                id: string;
+                type: string;
+                position?: string | undefined;
+            }[];
+        };
+        promptEditor: {
+            purpose: string;
+            placeholder: string;
+            presetType: "text" | "image" | "video" | null;
+            supportsMentions: boolean;
+            upstreamBehavior: string;
+            previewBoundary: string;
+        } | null;
+    }, {
+        kind: string;
+        runtimeKinds: string[];
+        label: string;
+        category: string;
+        features: string[];
+        handles: {
+            dynamic: boolean;
+            targets: {
+                id: string;
+                type: string;
+                position?: string | undefined;
+            }[];
+            sources: {
+                id: string;
+                type: string;
+                position?: string | undefined;
+            }[];
+        };
+        promptEditor: {
+            purpose: string;
+            placeholder: string;
+            presetType: "text" | "image" | "video" | null;
+            supportsMentions: boolean;
+            upstreamBehavior: string;
+            previewBoundary: string;
+        } | null;
+    }>, "many">;
+    nodePresets: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        type: z.ZodEnum<["text", "image", "video"]>;
+        prompt: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        scope: z.ZodEnum<["base", "user"]>;
+        updatedAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        updatedAt: string;
+        type: "text" | "image" | "video";
+        title: string;
+        prompt: string;
+        description: string | null;
+        scope: "base" | "user";
+    }, {
+        id: string;
+        updatedAt: string;
+        type: "text" | "image" | "video";
+        title: string;
+        prompt: string;
+        description: string | null;
+        scope: "base" | "user";
+    }>, "many">;
+    enabledModels: z.ZodObject<{
+        text: z.ZodArray<z.ZodObject<{
+            modelKey: z.ZodString;
+            modelAlias: z.ZodNullable<z.ZodString>;
+            label: z.ZodString;
+            vendorKey: z.ZodString;
+            kind: z.ZodString;
+            enabled: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }, {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }>, "many">;
+        image: z.ZodArray<z.ZodObject<{
+            modelKey: z.ZodString;
+            modelAlias: z.ZodNullable<z.ZodString>;
+            label: z.ZodString;
+            vendorKey: z.ZodString;
+            kind: z.ZodString;
+            enabled: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }, {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }>, "many">;
+        video: z.ZodArray<z.ZodObject<{
+            modelKey: z.ZodString;
+            modelAlias: z.ZodNullable<z.ZodString>;
+            label: z.ZodString;
+            vendorKey: z.ZodString;
+            kind: z.ZodString;
+            enabled: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }, {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }>, "many">;
+        audio: z.ZodArray<z.ZodObject<{
+            modelKey: z.ZodString;
+            modelAlias: z.ZodNullable<z.ZodString>;
+            label: z.ZodString;
+            vendorKey: z.ZodString;
+            kind: z.ZodString;
+            enabled: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }, {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        text: {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }[];
+        image: {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }[];
+        video: {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }[];
+        audio: {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }[];
+    }, {
+        text: {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }[];
+        image: {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }[];
+        video: {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }[];
+        audio: {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }[];
+    }>;
+    capabilityErrors: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    nodeContracts: {
+        kind: string;
+        runtimeKinds: string[];
+        label: string;
+        category: string;
+        features: string[];
+        handles: {
+            dynamic: boolean;
+            targets: {
+                id: string;
+                type: string;
+                position?: string | undefined;
+            }[];
+            sources: {
+                id: string;
+                type: string;
+                position?: string | undefined;
+            }[];
+        };
+        promptEditor: {
+            purpose: string;
+            placeholder: string;
+            presetType: "text" | "image" | "video" | null;
+            supportsMentions: boolean;
+            upstreamBehavior: string;
+            previewBoundary: string;
+        } | null;
+    }[];
+    nodePresets: {
+        id: string;
+        updatedAt: string;
+        type: "text" | "image" | "video";
+        title: string;
+        prompt: string;
+        description: string | null;
+        scope: "base" | "user";
+    }[];
+    enabledModels: {
+        text: {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }[];
+        image: {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }[];
+        video: {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }[];
+        audio: {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }[];
+    };
+    capabilityErrors: string[];
+}, {
+    nodeContracts: {
+        kind: string;
+        runtimeKinds: string[];
+        label: string;
+        category: string;
+        features: string[];
+        handles: {
+            dynamic: boolean;
+            targets: {
+                id: string;
+                type: string;
+                position?: string | undefined;
+            }[];
+            sources: {
+                id: string;
+                type: string;
+                position?: string | undefined;
+            }[];
+        };
+        promptEditor: {
+            purpose: string;
+            placeholder: string;
+            presetType: "text" | "image" | "video" | null;
+            supportsMentions: boolean;
+            upstreamBehavior: string;
+            previewBoundary: string;
+        } | null;
+    }[];
+    nodePresets: {
+        id: string;
+        updatedAt: string;
+        type: "text" | "image" | "video";
+        title: string;
+        prompt: string;
+        description: string | null;
+        scope: "base" | "user";
+    }[];
+    enabledModels: {
+        text: {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }[];
+        image: {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }[];
+        video: {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }[];
+        audio: {
+            kind: string;
+            label: string;
+            modelKey: string;
+            modelAlias: string | null;
+            vendorKey: string;
+            enabled: boolean;
+        }[];
+    };
+    capabilityErrors: string[];
+}>;
+export declare const localAgentToolNames: readonly ["tapcanvas_flow_get", "tapcanvas_node_context_bundle_get", "tapcanvas_node_presets_get", "tapcanvas_node_prompt_preview", "tapcanvas_create_generation_flow", "tapcanvas_flow_patch"];
 export type LocalAgentToolName = (typeof localAgentToolNames)[number];
 export declare const localAgentToolInputSchemas: {
     tapcanvas_flow_get: z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>;
+    tapcanvas_node_context_bundle_get: z.ZodObject<{
+        nodeId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        nodeId?: string | undefined;
+    }, {
+        nodeId?: string | undefined;
+    }>;
+    tapcanvas_node_presets_get: z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        type: z.ZodOptional<z.ZodEnum<["text", "image", "video"]>>;
+    }, "strip", z.ZodTypeAny, {
+        id?: string | undefined;
+        type?: "text" | "image" | "video" | undefined;
+    }, {
+        id?: string | undefined;
+        type?: "text" | "image" | "video" | undefined;
+    }>;
+    tapcanvas_node_prompt_preview: z.ZodObject<{
+        nodeId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        nodeId?: string | undefined;
+    }, {
+        nodeId?: string | undefined;
+    }>;
     tapcanvas_create_generation_flow: z.ZodObject<{
         kind: z.ZodString;
         prompt: z.ZodString;

package/dist/schemas.js

@@ -4,6 +4,60 @@ const finitePositionSchema = z.object({
     x: z.number().finite(),
     y: z.number().finite(),
 });
+const nodeHandleFactSchema = z.object({
+    id: z.string().min(1),
+    type: z.string().min(1),
+    position: z.string().min(1).optional(),
+});
+const promptEditorContractSchema = z.object({
+    purpose: z.string(),
+    placeholder: z.string(),
+    presetType: z.enum(["text", "image", "video"]).nullable(),
+    supportsMentions: z.boolean(),
+    upstreamBehavior: z.string(),
+    previewBoundary: z.string(),
+});
+const nodeContractSchema = z.object({
+    kind: z.string().min(1),
+    runtimeKinds: z.array(z.string().min(1)),
+    label: z.string().min(1),
+    category: z.string().min(1),
+    features: z.array(z.string()),
+    handles: z.object({
+        dynamic: z.boolean(),
+        targets: z.array(nodeHandleFactSchema),
+        sources: z.array(nodeHandleFactSchema),
+    }),
+    promptEditor: promptEditorContractSchema.nullable(),
+});
+const nodePresetSchema = z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    type: z.enum(["text", "image", "video"]),
+    prompt: z.string(),
+    description: z.string().nullable(),
+    scope: z.enum(["base", "user"]),
+    updatedAt: z.string().min(1),
+});
+const modelFactSchema = z.object({
+    modelKey: z.string().min(1),
+    modelAlias: z.string().min(1).nullable(),
+    label: z.string().min(1),
+    vendorKey: z.string().min(1),
+    kind: z.string().min(1),
+    enabled: z.boolean(),
+});
+export const localCanvasCapabilitiesSchema = z.object({
+    nodeContracts: z.array(nodeContractSchema),
+    nodePresets: z.array(nodePresetSchema),
+    enabledModels: z.object({
+        text: z.array(modelFactSchema),
+        image: z.array(modelFactSchema),
+        video: z.array(modelFactSchema),
+        audio: z.array(modelFactSchema),
+    }),
+    capabilityErrors: z.array(z.string()),
+});
 const createNodeSchema = z
     .object({
     id: z.string().min(1),
@@ -50,13 +104,26 @@ const createGenerationFlowSchema = z.object({
     groupId: z.string().min(1).optional(),
     nodeId: z.string().min(1).optional(),
 });
+const nodeIdSchema = z.object({
+    nodeId: z.string().min(1).optional(),
+});
+const nodePresetsGetSchema = z.object({
+    id: z.string().min(1).optional(),
+    type: z.enum(["text", "image", "video"]).optional(),
+});
 export const localAgentToolNames = [
     "tapcanvas_flow_get",
+    "tapcanvas_node_context_bundle_get",
+    "tapcanvas_node_presets_get",
+    "tapcanvas_node_prompt_preview",
     "tapcanvas_create_generation_flow",
     "tapcanvas_flow_patch",
 ];
 export const localAgentToolInputSchemas = {
     tapcanvas_flow_get: z.object({}).passthrough(),
+    tapcanvas_node_context_bundle_get: nodeIdSchema,
+    tapcanvas_node_presets_get: nodePresetsGetSchema,
+    tapcanvas_node_prompt_preview: nodeIdSchema,
     tapcanvas_create_generation_flow: createGenerationFlowSchema,
     tapcanvas_flow_patch: z.object({
         allowOverwrite: z.boolean().optional(),
@@ -70,6 +137,9 @@ export const localAgentToolInputSchemas = {
 };
 export const localAgentToolDescriptions = {
     tapcanvas_flow_get: "Read the live QCanvas graph from the connected browser tab. Use this before any patch.",
+    tapcanvas_node_context_bundle_get: "Read one live node with its upstream/downstream graph neighbors, node contract, bound prompt preset, and enabled model catalog from the browser snapshot. nodeId may be omitted only when exactly one node is selected. Unknown nodes, contracts, or bound presets fail explicitly.",
+    tapcanvas_node_presets_get: "Read live node prompt presets cached by the connected browser. Without id it returns compact metadata only; request an exact id to read the full prompt. Optionally filter by type. An unknown requested id fails explicitly.",
+    tapcanvas_node_prompt_preview: "Inspect a node's current prompt, bound preset, exact prompt divergence, and structural readiness from the live browser snapshot. nodeId may be omitted only when exactly one node is selected. This is factual inspection, not a simulation of the generation runner's compiled prompt.",
     tapcanvas_create_generation_flow: "Create one runnable taskNode for a generation intent, auto-placed next to existing nodes and auto-wired to referenceNodeIds via real edges + assetInputs/referenceImages carrying those nodes' current output image. This only creates and wires the node; it does NOT submit generation. Call tapcanvas_flow_patch's browser-side runner (or ask the user to run the node) to actually generate.",
     tapcanvas_flow_patch: "Request a browser-confirmed QCanvas graph patch. The browser must approve the write before it is applied.",
 };

package/dist/types.d.ts

@@ -4,6 +4,54 @@ export type QCanvasViewport = {
     y: number;
     zoom: number;
 };
+export type QCanvasNodeHandleFact = {
+    id: string;
+    type: string;
+    position?: string;
+};
+export type QCanvasNodeContract = {
+    kind: string;
+    runtimeKinds: string[];
+    label: string;
+    category: string;
+    features: string[];
+    handles: {
+        dynamic: boolean;
+        targets: QCanvasNodeHandleFact[];
+        sources: QCanvasNodeHandleFact[];
+    };
+    promptEditor: {
+        purpose: string;
+        placeholder: string;
+        presetType: "text" | "image" | "video" | null;
+        supportsMentions: boolean;
+        upstreamBehavior: string;
+        previewBoundary: string;
+    } | null;
+};
+export type QCanvasNodePreset = {
+    id: string;
+    title: string;
+    type: "text" | "image" | "video";
+    prompt: string;
+    description: string | null;
+    scope: "base" | "user";
+    updatedAt: string;
+};
+export type QCanvasModelFact = {
+    modelKey: string;
+    modelAlias: string | null;
+    label: string;
+    vendorKey: string;
+    kind: string;
+    enabled: boolean;
+};
+export type QCanvasEnabledModels = {
+    text: QCanvasModelFact[];
+    image: QCanvasModelFact[];
+    video: QCanvasModelFact[];
+    audio: QCanvasModelFact[];
+};
 export type QCanvasSnapshot = {
     clientId: string;
     url: string | null;
@@ -15,6 +63,10 @@ export type QCanvasSnapshot = {
     edges: unknown[];
     selectedNodeIds: string[];
     viewport: QCanvasViewport | null;
+    nodeContracts: QCanvasNodeContract[];
+    nodePresets: QCanvasNodePreset[];
+    enabledModels: QCanvasEnabledModels;
+    capabilityErrors: string[];
     updatedAt: string;
 };
 export type LocalToolResultEnvelope = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qcanvas-local-agent",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "QCanvas 本机 Agent —— 在本机驱动 Codex / Claude 操控 QCanvas 网页画布的本地桥接服务。",
   "type": "module",
   "main": "./dist/index.js",