@kobinflow/canvas-agent 0.6.0

package/dist/canvas/schemas.js

@@ -0,0 +1,155 @@
+import { z } from "zod";
+const recordSchema = z.record(z.unknown());
+const positionSchema = z.object({ x: z.number(), y: z.number() });
+const viewportSchema = z.object({ x: z.number(), y: z.number(), k: z.number() });
+const nodeTypeSchema = z.enum(["image", "text", "config", "video", "audio"]);
+const generationModeSchema = z.enum(["text", "image", "video", "audio"]);
+/** Canvas Agent 对外提供的工具名称。 */
+export const toolNames = [
+    "site_navigate",
+    "canvas_list_projects",
+    "canvas_get_state",
+    "canvas_get_selection",
+    "canvas_export_snapshot",
+    "canvas_apply_ops",
+    "canvas_create_node",
+    "canvas_create_attachment_nodes",
+    "canvas_create_text_node",
+    "canvas_create_text_nodes",
+    "canvas_create_config_node",
+    "canvas_create_image_prompt_flow",
+    "canvas_create_generation_flow",
+    "canvas_generate_text",
+    "canvas_generate_image",
+    "canvas_generate_video",
+    "canvas_generate_audio",
+    "canvas_update_node",
+    "canvas_update_node_text",
+    "canvas_move_nodes",
+    "canvas_resize_node",
+    "canvas_delete_nodes",
+    "canvas_connect_nodes",
+    "canvas_select_nodes",
+    "canvas_set_viewport",
+    "canvas_run_generation",
+    "generation_get_status",
+    "workbench_image_get_config",
+    "workbench_image_generate",
+    "workbench_video_get_config",
+    "workbench_video_generate",
+    "prompts_search",
+    "assets_list",
+    "assets_add",
+];
+export const canvasOpSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("add_node"), nodeType: nodeTypeSchema.optional(), id: z.string().optional(), title: z.string().optional(), x: z.number().optional(), y: z.number().optional(), width: z.number().optional(), height: z.number().optional(), position: positionSchema.optional(), metadata: recordSchema.optional() }).passthrough(),
+    z.object({ type: z.literal("update_node"), id: z.string(), patch: recordSchema.optional(), metadata: recordSchema.optional() }).passthrough(),
+    z.object({ type: z.literal("delete_node"), id: z.string().optional(), ids: z.array(z.string()).optional() }).passthrough(),
+    z.object({ type: z.literal("delete_connections"), id: z.string().optional(), ids: z.array(z.string()).optional(), all: z.boolean().optional() }).passthrough(),
+    z.object({ type: z.literal("connect_nodes"), id: z.string().optional(), fromNodeId: z.string(), toNodeId: z.string() }).passthrough(),
+    z.object({ type: z.literal("set_viewport"), viewport: viewportSchema }).passthrough(),
+    z.object({ type: z.literal("select_nodes"), ids: z.array(z.string()) }).passthrough(),
+    z.object({ type: z.literal("run_generation"), nodeId: z.string(), mode: generationModeSchema.optional(), prompt: z.string().optional() }).passthrough(),
+]);
+const textNodeSchema = z.object({
+    text: z.string(),
+    title: z.string().optional(),
+    x: z.number().optional(),
+    y: z.number().optional(),
+    width: z.number().optional(),
+    height: z.number().optional(),
+});
+const generationOptionsSchema = z.object({
+    model: z.string().optional(),
+    size: z.string().optional(),
+    quality: z.string().optional(),
+    count: z.number().optional(),
+    seconds: z.string().optional(),
+    vquality: z.string().optional(),
+    generateAudio: z.string().optional(),
+    watermark: z.string().optional(),
+    videoMode: z.string().optional(),
+    audioVoice: z.string().optional(),
+    audioFormat: z.string().optional(),
+    audioSpeed: z.string().optional(),
+    audioInstructions: z.string().optional(),
+});
+const generationFlowSchema = z.object({
+    prompt: z.string(),
+    title: z.string().optional(),
+    x: z.number().optional(),
+    y: z.number().optional(),
+    referenceNodeIds: z.array(z.string()).optional(),
+});
+export const toolInputSchemas = {
+    site_navigate: z.object({ path: z.string() }),
+    canvas_list_projects: z.object({ keyword: z.string().optional(), page: z.number().optional(), pageSize: z.number().optional() }),
+    canvas_get_state: z.object({}).passthrough(),
+    canvas_get_selection: z.object({}).passthrough(),
+    canvas_export_snapshot: z.object({}).passthrough(),
+    canvas_apply_ops: z.object({ ops: z.array(canvasOpSchema) }),
+    canvas_create_node: z.object({ nodeType: nodeTypeSchema, title: z.string().optional(), x: z.number().optional(), y: z.number().optional(), width: z.number().optional(), height: z.number().optional(), metadata: recordSchema.optional() }),
+    canvas_create_attachment_nodes: z.object({ attachmentIds: z.array(z.string()).min(1), x: z.number().optional(), y: z.number().optional(), gap: z.number().optional(), direction: z.enum(["row", "column"]).optional() }),
+    canvas_create_text_node: z.object({ text: z.string().optional(), x: z.number().optional(), y: z.number().optional(), title: z.string().optional(), width: z.number().optional(), height: z.number().optional() }),
+    canvas_create_text_nodes: z.object({ items: z.array(textNodeSchema).min(1), x: z.number().optional(), y: z.number().optional(), gap: z.number().optional(), direction: z.enum(["row", "column"]).optional() }),
+    canvas_create_config_node: z.object({ prompt: z.string().optional(), mode: generationModeSchema.optional(), title: z.string().optional(), x: z.number().optional(), y: z.number().optional(), width: z.number().optional(), height: z.number().optional(), autoRun: z.boolean().optional() }).merge(generationOptionsSchema),
+    canvas_create_image_prompt_flow: z.object({ prompt: z.string(), x: z.number().optional(), y: z.number().optional(), autoRun: z.boolean().optional() }).merge(generationOptionsSchema),
+    canvas_create_generation_flow: generationFlowSchema.extend({ mode: generationModeSchema.optional(), autoRun: z.boolean().optional() }).merge(generationOptionsSchema),
+    canvas_generate_text: generationFlowSchema.merge(generationOptionsSchema),
+    canvas_generate_image: generationFlowSchema.merge(generationOptionsSchema),
+    canvas_generate_video: generationFlowSchema.merge(generationOptionsSchema),
+    canvas_generate_audio: generationFlowSchema.merge(generationOptionsSchema),
+    canvas_update_node: z.object({ id: z.string(), patch: recordSchema.optional(), metadata: recordSchema.optional() }),
+    canvas_update_node_text: z.object({ id: z.string(), text: z.string(), title: z.string().optional() }),
+    canvas_move_nodes: z.object({ items: z.array(z.object({ id: z.string(), x: z.number().optional(), y: z.number().optional(), dx: z.number().optional(), dy: z.number().optional() })).min(1) }),
+    canvas_resize_node: z.object({ id: z.string(), width: z.number(), height: z.number(), freeResize: z.boolean().optional() }),
+    canvas_delete_nodes: z.object({ ids: z.array(z.string()).min(1) }),
+    canvas_connect_nodes: z.object({ connections: z.array(z.object({ fromNodeId: z.string(), toNodeId: z.string() })).min(1) }),
+    canvas_select_nodes: z.object({ ids: z.array(z.string()) }),
+    canvas_set_viewport: z.object({ viewport: viewportSchema }),
+    canvas_run_generation: z.object({ nodeId: z.string(), mode: generationModeSchema.optional(), prompt: z.string().optional() }),
+    generation_get_status: z.object({ scope: z.enum(["all", "canvas", "image", "video"]).optional(), taskId: z.string().optional(), nodeIds: z.array(z.string()).optional(), limit: z.number().optional() }),
+    workbench_image_get_config: z.object({}).passthrough(),
+    workbench_image_generate: z.object({ prompt: z.string(), model: z.string().optional(), quality: z.string().optional(), size: z.string().optional(), count: z.number().optional(), run: z.boolean().optional() }),
+    workbench_video_get_config: z.object({}).passthrough(),
+    workbench_video_generate: z.object({ prompt: z.string(), model: z.string().optional(), size: z.string().optional(), seconds: z.string().optional(), resolution: z.string().optional(), generateAudio: z.boolean().optional(), watermark: z.boolean().optional(), mode: z.enum(["frames", "reference"]).optional(), run: z.boolean().optional() }),
+    prompts_search: z.object({ keyword: z.string().optional(), category: z.string().optional(), tags: z.array(z.string()).optional(), page: z.number().optional(), pageSize: z.number().optional() }),
+    assets_list: z.object({ kind: z.enum(["all", "text", "image", "video"]).optional(), keyword: z.string().optional(), page: z.number().optional(), pageSize: z.number().optional() }),
+    assets_add: z.object({ kind: z.enum(["text", "image"]), title: z.string(), content: z.string().optional(), imageUrl: z.string().optional(), tags: z.array(z.string()).optional(), source: z.string().optional(), note: z.string().optional() }),
+};
+export const toolDescriptions = {
+    site_navigate: "跳转网站页面。path 可为 / (首页)、/canvas (我的画布)、/canvas/:id (指定画布)、/image (生图工作台)、/video (视频创作台)、/prompts (提示词库)、/assets (我的素材)、/config (配置)。操作画布前若不在画布页，先用本工具打开画布。",
+    canvas_list_projects: "列出用户全部画布（仅标题、创建/更新时间、节点数、连线数，不含完整数据），支持 keyword 搜索和 page/pageSize 分页。返回的 id 可配合 site_navigate 跳转到 /canvas/:id 打开对应画布。",
+    canvas_get_state: "读取当前网页画布的节点、连线、选区和视口。",
+    canvas_get_selection: "读取当前网页画布选中的节点。",
+    canvas_export_snapshot: "导出当前画布快照，用于理解布局。",
+    canvas_apply_ops: "批量操作当前网页画布。ops 支持 add_node、update_node、delete_node、delete_connections、connect_nodes、set_viewport、select_nodes、run_generation。",
+    canvas_create_node: "创建任意类型节点：text、image、config、video、audio。适合创建占位图、媒体占位、配置节点或自定义 metadata 节点。",
+    canvas_create_attachment_nodes: "把当前对话中用户上传的图片附件创建成真实画布图片节点。attachmentIds 使用本轮附件清单中的 ID；返回的节点 ID 可传给 canvas_create_generation_flow.referenceNodeIds 作为生成参考图。",
+    canvas_create_text_node: "在当前画布创建单个文本节点。",
+    canvas_create_text_nodes: "批量创建文本节点，适合生成标题、段落、脚本、说明等内容块。",
+    canvas_create_config_node: "创建生成配置节点，可指定 text/image/video/audio 模式和生成参数，可选择立即触发生成。",
+    canvas_create_image_prompt_flow: "创建提示词文本节点和图片生成配置节点，并自动连线，可选择立即触发生图。",
+    canvas_create_generation_flow: "创建通用生成流程：提示词文本节点、生成配置节点、参考节点连线，可用于文案、生图、视频或音频。",
+    canvas_generate_text: "创建通用文本生成流程并立即触发生成。",
+    canvas_generate_image: "创建通用图片生成流程并立即触发生成。",
+    canvas_generate_video: "创建通用视频生成流程并立即触发生成。",
+    canvas_generate_audio: "创建通用音频生成流程并立即触发生成。",
+    canvas_update_node: "更新节点基础字段或 metadata。",
+    canvas_update_node_text: "更新文本节点内容和标题。",
+    canvas_move_nodes: "移动一个或多个节点，支持绝对坐标或 dx/dy 偏移。",
+    canvas_resize_node: "调整节点尺寸。",
+    canvas_delete_nodes: "删除指定节点及相关连线。",
+    canvas_connect_nodes: "批量连接节点。",
+    canvas_select_nodes: "设置当前选中节点。",
+    canvas_set_viewport: "调整画布视口。",
+    canvas_run_generation: "触发指定节点生成，通常用于配置节点或文本/图片/视频/音频节点。",
+    generation_get_status: "查询当前活动网页的生成任务状态。默认返回画布、生图工作台和视频工作台最近任务；可用 scope 过滤来源，用 taskId 查询工作台任务，用 nodeIds 查询画布节点。",
+    workbench_image_get_config: "读取生图工作台的当前参数和可选项（可用模型、质量、分辨率 1k/2k/4k/auto、宽高比、张数范围），在调用 workbench_image_generate 前先了解可选值。",
+    workbench_image_generate: "在生图工作台填入提示词并按需设置 model、quality、size（如 16:9 或 2048x1152）、count，run 默认 true 会自动点击生成按钮。会自动跳转到生图工作台。生成为异步过程，提交后返回 taskId，可用 generation_get_status 查询状态。",
+    workbench_video_get_config: "读取视频创作台的当前参数和可选项（可用模型、清晰度 480/720/1080、比例 1:1/3:4/4:3/16:9/9:16/21:9/auto、时长 4–30 秒、首尾帧或全能参考模式、是否生成声音与水印）。",
+    workbench_video_generate: "在视频创作台填入提示词并按需设置 model、size（1:1、3:4、4:3、16:9、9:16、21:9、auto 或 1280x720）、seconds（4–30）、resolution（480/720/1080）、generateAudio、watermark、mode（frames 首尾帧 / reference 全能参考），run 默认 true 会自动点击生成按钮。会自动跳转到视频创作台。生成为异步过程，提交后返回 taskId，可用 generation_get_status 查询状态。",
+    prompts_search: "搜索提示词库（第三方提示词合集），支持 keyword、category、tags 过滤和 page/pageSize 分页，返回标题、提示词、分类、标签、封面等。",
+    assets_list: "列出用户「我的素材」，支持 kind（text/image/video）过滤、keyword 搜索和 page/pageSize 分页。为控制体积不返回图片/视频原始 data，仅返回封面与元信息。",
+    assets_add: "向「我的素材」新增素材。kind=text 时用 content 传文本内容；kind=image 时用 imageUrl 传图片地址或 dataURL。可附带 title、tags、source、note。",
+};

package/dist/canvas/session.d.ts

@@ -0,0 +1,163 @@
+import type { ServerResponse } from "node:http";
+import type { AgentAttachment } from "../agent/types.js";
+import type { CanvasSnapshot } from "./types.js";
+type TurnAttachment = {
+    clientId: string;
+    id: string;
+    name: string;
+    type: string;
+    size: number;
+    width: number;
+    height: number;
+    dataUrl: string;
+};
+export type CodexState = {
+    busy: boolean;
+    threadId: string;
+    turnId: string;
+};
+export type McpStartupState = "starting" | "ready" | "failed" | "cancelled";
+export type ConversationState = {
+    revision: number;
+    conversationId: string;
+    threadId: string;
+    status: "idle" | "preparing" | "ready" | "warning" | "running" | "failed";
+    mcpStatuses: Record<string, {
+        status: McpStartupState;
+        error?: string | null;
+        failureReason?: string | null;
+    }>;
+    sourceClientId?: string;
+    error?: string;
+};
+type McpInventoryItem = {
+    name: string;
+    authStatus?: string;
+};
+export declare const AGENT_PROTOCOL_VERSION = 6;
+/** 管理网页画布连接、状态、附件和工具请求。 */
+export declare class CanvasSession {
+    private clients;
+    private clientFocusOrder;
+    private pending;
+    private pendingApprovals;
+    private canvasStates;
+    private turnAttachments;
+    private codexReplayEvents;
+    private codexReplayActiveItems;
+    private codexMutationBusy;
+    private activeClientId;
+    private boundClientId;
+    private focusSequence;
+    private codexState;
+    private conversationState;
+    private conversationInventoryComplete;
+    private preparedConversationThreadId;
+    constructor(activeThreadId?: string);
+    /** 获取当前目标网页的画布状态。 */
+    private get canvasState();
+    /** 获取当前 turn 绑定或最近激活的网页客户端。 */
+    private get targetClientId();
+    /** 返回 Canvas Agent 当前连接状态。 */
+    health(): {
+        ok: boolean;
+        protocolVersion: number;
+        hasCanvas: boolean;
+        clients: number;
+        codexBusy: boolean;
+        conversation: ConversationState;
+    };
+    /** 返回 Codex 是否正在执行任务。 */
+    get codexBusy(): boolean;
+    get codexThreadId(): string;
+    /** Return a copy that callers can restore after a temporary Codex operation. */
+    get codexStateSnapshot(): CodexState;
+    /** 返回站点级对话的权威快照。 */
+    get conversationStateSnapshot(): ConversationState;
+    /** 原子开始一次新建或恢复对话流程。 */
+    beginConversation(options?: {
+        threadId?: string;
+        conversationId?: string;
+        sourceClientId?: string;
+    }): ConversationState;
+    /** 记录预热阶段单个 MCP 服务的启动状态。 */
+    updateConversationMcp(name: string, status: McpStartupState, error?: string | null, failureReason?: string | null): ConversationState;
+    /** 用 app-server 的完整 MCP 清单补齐未发送逐项通知的服务。 */
+    completeConversationMcpInventory(services: McpInventoryItem[]): ConversationState;
+    /** MCP 清单读取结束后提交线程和最终可发送状态。 */
+    completeConversationPreparation(threadId: string): ConversationState;
+    /** 将创建线程或读取 MCP 清单的失败保存为不可发送状态。 */
+    failConversationPreparation(error: string): ConversationState;
+    /** 切换到无需重新预热的既有状态，例如删除当前对话后的空状态。 */
+    activateConversation(threadId: string, sourceClientId?: string): ConversationState;
+    markConversationRunning(threadId: string): ConversationState;
+    finishConversationRun(threadId: string): ConversationState;
+    /** 判断网页客户端是否仍连接到当前 Agent。 */
+    hasClient(clientId: string): boolean;
+    /** 读取指定网页上报的画布，避免提炼时受最近焦点或其他标签页影响。 */
+    canvasStateForClient(clientId: string): CanvasSnapshot | null;
+    /** 原子取得 Codex 写操作权限，避免多个网页并发切换或修改会话。 */
+    beginCodexMutation(): boolean;
+    /** 释放 Codex 写操作权限。 */
+    endCodexMutation(): void;
+    /** 返回当前 Codex turn 的线程、turn 和发起网页。 */
+    get codexEventScope(): {
+        threadId: string;
+        turnId: string;
+        sourceClientId: string;
+    };
+    /** 返回刷新后仍需展示的 Codex 权限请求。 */
+    get codexPendingApprovals(): Record<string, unknown>[];
+    /** 跟踪需要跨页面重连恢复的 Codex 权限请求。 */
+    trackCodexEvent(type: string, payload: Record<string, unknown>): void;
+    /** 更新并广播 Codex 运行状态；静默后台活动可保留上一 turn 的断线重放。 */
+    setCodexState(patch: Partial<CodexState>, options?: {
+        preserveReplay?: boolean;
+    }): void;
+    /** 权威历史已覆盖指定 turn 后，清理其断线重放事件。 */
+    acknowledgeCodexHistory(threadId: string, turnIds: string[]): void;
+    /** 建立网页与 Canvas Agent 之间的 SSE 连接。 */
+    openEvents(url: URL, res: ServerResponse, activeThreadId?: string): void;
+    private updateConversation;
+    /** 保存指定网页上报的最新画布快照。 */
+    updateState(body: unknown, clientId?: string): void;
+    /** 将指定网页设为最近激活的工具目标。 */
+    activateClient(clientId: string): void;
+    /** 将当前 Agent turn 固定绑定到指定网页。 */
+    bindClient(clientId: string): void;
+    /** 解除当前 Agent turn 的网页绑定。 */
+    releaseClient(clientId: string): void;
+    /** 保存当前 turn 可用的图片附件并返回安全引用。 */
+    setTurnAttachments(clientId: string, attachments: AgentAttachment[]): {
+        id: string;
+        name: string;
+        type: string;
+        size: number;
+        width: number;
+        height: number;
+    }[];
+    /** 清理指定网页或全部 turn 附件。 */
+    clearTurnAttachments(clientId?: string): void;
+    /** 获取属于指定网页 turn 的图片附件。 */
+    getTurnAttachment(clientId: string, attachmentId: string): TurnAttachment;
+    /** 接收网页返回的工具调用结果。 */
+    resolveResult(clientId: string, body: {
+        requestId?: string;
+        error?: string;
+        result?: unknown;
+    }): boolean;
+    /** 向全部已连接网页广播事件。 */
+    emitAll(type: string, payload: unknown): void;
+    /** 向全部网页广播带线程归属的事件。 */
+    emitThread(type: string, threadId: string, payload?: Record<string, unknown>): void;
+    /** 为断线重连保存完整的最新文本快照，实时连接仍只接收增量。 */
+    private replaySnapshot;
+    private clearReplayActiveTurn;
+    /** 校验工具参数并将调用分派到当前目标网页。 */
+    callTool(name: unknown, rawInput: unknown): Promise<unknown>;
+    /** 将当前 turn 的附件转换为画布图片节点。 */
+    private createAttachmentNodes;
+    /** 向目标网页发送工具请求并等待调用结果。 */
+    private requestCanvasTool;
+}
+export {};