@dream-craft/canvas-agent 0.0.0-stage → 0.6.4

package/README.md

@@ -1,3 +1,165 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Infinite Canvas Agent
+
+本地 Canvas Agent 用来连接画布网页和用户电脑上的 Codex / Claude Code。本地开发时优先连接 `http://localhost:3000`，不需要先使用线上站点。
+
+## 启动
+
+```bash
+npx -y @dream-craft/canvas-agent@latest
+```
+
+带上 `@latest` 是因为 npx 会缓存已下载的版本，不加就可能一直运行旧版本。
+
+需要排查连接、线程、Codex app-server 或工具调用问题时，可开启 Debug 模式：
+
+```bash
+npx -y @dream-craft/canvas-agent@latest --debug
+```
+
+Debug 日志会以 `[DEBUG][HH:mm:ss]` 等传统格式输出到终端，并按启动日期保存到 `~/.infinite-canvas/logs/canvas-agent-YYYY-MM-DD.log`。终端日志带级别颜色，文件日志为纯文本；日志包含 HTTP、SSE、线程、turn、Codex app-server 和工具调用事件，token 与图片 Data URL 会自动隐藏。
+
+本仓库开发时也可以直接运行：
+
+```bash
+cd canvas-agent
+npm install
+npm run build
+node dist/index.js
+```
+
+启动后会输出本机地址和 token：
+
+```txt
+Local URL: http://127.0.0.1:17371
+Connect token: xxxxxx
+```
+
+在画布右上角点击 `Agent`，填入地址和 token 后连接。
+
+Codex app 插件会读取启动输出里的 Local URL 和 Connect token，并直接打开画布网页地址；Canvas Agent 不负责生成画布打开 URL。
+
+Canvas Agent 默认只监听 `127.0.0.1`。网页第一次带正确 token 连接后，Canvas Agent 会记录该网页 Origin 并只允许它复用；其他 Origin 不能复用这个本地 Agent，除非用户清理 `~/.infinite-canvas/canvas-agent.json` 里的 `origins`。诊断用的 `/health` 无论来源都只认 token。
+
+MCP 模式（`canvas-agent mcp`）本身只是把工具调用转发到上面这个地址，不会启动服务。服务未运行、或该端口上的服务没有使用同一份 token 时，工具调用返回手动启动指引，MCP 不会自行拉起常驻进程。
+
+## 发布
+
+`canvas-agent` 使用自己的 `package.json` 版本号，不跟仓库根目录 `VERSION` 绑定。发布由维护者手动执行：在 `canvas-agent` 目录确认已登录 npm（账号 `chaoyang2009918`）后运行：
+
+```bash
+npm publish
+```
+
+## Codex MCP
+
+如果希望 Codex 终端能直接操作画布，需要先把 Canvas Agent 注册成 Codex MCP。
+
+直接运行 `npx -y @dream-craft/canvas-agent@latest` 只启动本地 Agent 服务，不会安装 MCP，也不会增加 Codex 工具上下文。只有安装 Codex app 插件，或手动执行 `codex mcp add` 后，`infinite-canvas` 工具才会进入 Codex 上下文；由于工具较多，不使用时建议移除。
+
+通过插件安装时移除插件：
+
+```bash
+codex plugin remove infinite-canvas
+```
+
+手动添加 MCP 时移除 MCP：
+
+```bash
+codex mcp remove infinite-canvas
+```
+
+### Codex app 插件
+
+仓库内提供了 Codex app 插件：`plugins/infinite-canvas`。在 Codex app 中添加本仓库的 marketplace 后，可以安装 `Infinite Canvas` 插件；插件会注册同一个 `infinite-canvas` MCP，并带上画布操作说明。
+
+插件和下面手动 `codex mcp add`、直接写 `~/.codex/config.toml` 注册的是**同名** server，只需要留一种。同时存在时 `config.toml` 会覆盖插件自带的 MCP 配置，插件 `.mcp.json` 里的超时和自动放行会静默失效。
+
+添加本地 marketplace 时建议使用仓库绝对路径，避免 Codex 从其他工作目录解析失败：
+
+```bash
+cd /path/to/infinite-canvas
+codex plugin marketplace add "$(pwd)"
+codex plugin add infinite-canvas@infinite-canvas-local
+```
+
+插件默认通过 npm 启动 MCP；这个命令只提供 MCP 工具，不会把 MCP 写入全局配置，也不会在退出时自动卸载：
+
+```bash
+npx -y @dream-craft/canvas-agent@latest mcp
+```
+
+使用时可以直接在 Codex 里说“打开 Infinite Canvas”，插件会启动本地 Agent，读取 Local URL 和 Connect token，然后在右侧打开 `https://canvas.best/` 并自动新建、连接画布；只有明确要求使用本地项目时才会启动本地前端。
+
+Canvas Agent 启动后，给 Codex 添加 MCP：
+
+```bash
+codex mcp add infinite-canvas -- npx -y @dream-craft/canvas-agent@latest mcp
+```
+
+本仓库开发时可以改成，实际使用建议替换为本机绝对路径：
+
+```bash
+codex mcp add infinite-canvas -- node /path/to/infinite-canvas/canvas-agent/dist/index.js mcp
+```
+
+Canvas Agent 源码使用 TypeScript 编写，MCP 协议层使用官方 `@modelcontextprotocol/sdk`，工具入参使用 `zod` 描述。
+
+只用终端 Codex CLI、没有安装上面的插件时，可以在 `~/.codex/config.toml` 里手动注册并自动放行（插件的 `.mcp.json` 已经带 `default_tools_approval_mode`，装了插件就不需要这段）：
+
+```toml
+[mcp_servers.infinite-canvas]
+command = "npx"
+args = ["-y", "@dream-craft/canvas-agent@latest", "mcp"]
+default_tools_approval_mode = "approve"
+```
+
+可用工具：
+
+- `canvas_get_state`
+- `canvas_get_selection`
+- `canvas_export_snapshot`
+- `canvas_apply_ops`
+- `canvas_create_text_node`
+- `canvas_create_image_prompt_flow`
+
+`canvas_apply_ops` 示例：
+
+```json
+{
+  "ops": [
+    {
+      "type": "add_node",
+      "nodeType": "text",
+      "title": "标题",
+      "position": { "x": 0, "y": 0 },
+      "metadata": { "content": "文本内容" }
+    }
+  ]
+}
+```
+
+## 侧边栏 Codex
+
+本地面板会把提示词发送给 Canvas Agent。Canvas Agent 使用官方 `@openai/codex` CLI 的 `codex app-server --stdio` 启动并复用同一个 Codex thread，启动时会注入 `infinite-canvas` MCP 配置并自动放行 MCP 审批，真正执行画布修改前仍由网页侧边栏二次确认。
+
+侧边栏会展示 Codex 返回的 `thread.started`、`turn.started`、`item.*`、`turn.completed` 等结构化事件；Canvas Agent 会合并短时间内的回复、思考摘要和命令输出增量，网页使用同一条消息持续更新，并把任务进度、计划、搜索、文件修改与工具操作整理为中文过程时间线。
+
+侧边栏上传或粘贴的图片会先在前端一律重编码为 WebP（长边 1536px、质量 0.85）再发到本机 Canvas Agent，由 Canvas Agent 临时写入本机文件并作为 app-server `localImage` 输入传给 Codex，本轮结束后临时文件即删除。附件体积上界因此由像素数决定、与源文件编码无关；Canvas Agent 侧另有兜底闸门：单张 2MB、单次请求总量 8MB，超限返回 413 中文报错。`express` 的请求体上限仍是 30MB，只作为最后一道防线。动图（GIF 等）重编码后只保留首帧。
+
+## Claude Code
+
+Claude Code Adapter 代码暂时保留，但当前网页侧边栏只开放 Codex。后续开放 Claude 入口时，Canvas Agent 会调用本机 `claude -p --output-format stream-json` 并把流式 JSON 事件转发到侧边栏。
+
+如果希望 Claude Code 也能操作画布，需要给 Claude Code 添加同一个 MCP。建议用 user scope，避免 Canvas Agent 从不同目录启动时找不到配置：
+
+```bash
+claude mcp add --scope user --transport stdio infinite-canvas -- npx -y @dream-craft/canvas-agent@latest mcp
+```
+
+本仓库开发时可以改成：
+
+```bash
+claude mcp add --scope user --transport stdio infinite-canvas -- node /path/to/infinite-canvas/canvas-agent/dist/index.js mcp
+```
+
+Canvas Agent 调用 Claude Code 时会默认带上 `--allowedTools mcp__infinite-canvas__*`，画布写操作仍由网页侧边栏确认。

package/agent-instructions.md

@@ -0,0 +1,20 @@
+# Infinite Canvas Agent
+
+你正在帮助用户操作 Infinite Canvas 网站。
+
+- 用户要求操作画布时，默认目标就是网页当前已经打开的画布。需要了解内容时先使用 `canvas_get_state`；读取成功后直接在该画布执行任务，不要调用 `canvas_list_projects`，也不要用 `site_navigate` 重复进入画布。
+- 只有用户明确要求查看、选择或切换其他画布，或者 `canvas_get_state` 明确提示当前没有已连接画布时，才使用 `canvas_list_projects` 和 `site_navigate`。`site_navigate` 可跳转 `/`、`/canvas`、`/canvas/:id`、`/image`、`/video`、`/prompts`、`/assets`、`/config`。
+- 修改当前画布时根据任务使用已配置的 infinite-canvas MCP 工具；复杂批量改动使用 `canvas_apply_ops`。
+- 用户要求把上传附件放入画布或作为生成参考图时，必须先用 `canvas_create_attachment_nodes` 创建真实图片节点，再把节点 ID 传给生成流程，不要创建空图片占位节点。
+- 生图与视频工作台分别使用 `workbench_image_*`、`workbench_video_*` 工具；提示词和素材分别使用 `prompts_search`、`assets_*` 工具。
+- 用户要求生成图片、视频、音频或文本时，默认调用对应的 `canvas_generate_image`、`canvas_generate_video`、`canvas_generate_audio`、`canvas_generate_text`，通过当前画布的生成节点完成任务。**优先级（最高）例外**：开放式/高成本创作任务（如"生成一个某某主题的视频短片"、搭完整生成链、批量产出，特征是含多个未指定的自由决策点）必须先按 `task-briefing` 技能发对齐问卷并结束本轮，用户确认口径前禁止调用任何生成、建链或触发工具——本条与下一条的"直接调用生成工具"默认指令都让位于该技能。
+- 只有用户明确要求使用“Codex 内置生图”“ImageGen 技能”或意思明确相同的能力时，才使用 Codex 自带的 `imagegen`；不要因为用户只说“生成图片”就自行改用内置生图。内置生图完成后，其结果会由 Canvas Agent 自动展示到对话并插入当前画布，无需再创建空节点或重复生成。
+- 只有用户明确说要在生图/视频工作台生成时，才使用 `workbench_image_*`、`workbench_video_*`。生成任务提交后应说明已经在画布或工作台开始生成，不要在实际没有结果时声称“已生成”。
+- 需要生成内容时直接调用对应生成工具，不要绑定特定业务场景，不要模拟鼠标点击，不要要求用户手动复制 JSON。
+- 需要获取、保存或核对生成结果图片时，使用画布节点元数据里的资源地址（`canvas_get_state` 读取）或工具返回的文件路径；不要用浏览器自动化（js/browser 工具）从页面 DOM 抓取或下载图片，也不要在网页 DOM 里查找画布内容。
+
+## Windows shell 与工具缺失行为
+
+- 沙箱环境是 Windows PowerShell 5.1。shell 只用于三类用途：读取文件（`Get-Content`）、等待（`Start-Sleep`）、文件搜索（`Get-ChildItem` / `Select-String`）。不要使用 bash/Unix 语法（`ls -la`、`head`、`grep`、`/dev/null` 等）；`python3`、`pwsh` 在本机不存在，python 在沙箱 shell 的 PATH 里调不到——不要用脚本语言生成 JSON 参数，直接把 JSON 写进工具参数。
+- 当工具清单中没有 `canvas_*` 前缀工具（infinite-canvas MCP 未注册或未连接）时，立即向用户报告「画布工具不可用，请检查 Canvas Agent 连接」并停止执行任务；不要把工具名当命令执行，不要在文件系统里搜索画布状态或 MCP 配置。
+- 同一 shell 命令因环境类错误（命令不存在、语法错误、权限拒绝）连续失败 2 次后，停止更换写法，向用户说明具体缺口；不要继续用其他脚本语言或管道方式重试。画布工具返回的业务错误（如「当前没有已连接画布」）按前文切换画布的规则处理，不属于此类。

package/dist/agent/claude.d.ts

@@ -0,0 +1,3 @@
+import type { AgentEmit } from "./types.js";
+/** 使用 Claude CLI 执行一次带 Canvas Agent 工具的任务。 */
+export declare function runClaudeTurn(prompt: string, emit: AgentEmit): void;

package/dist/agent/claude.js

@@ -0,0 +1,54 @@
+import { spawn } from "node:child_process";
+import { AGENT_PROMPT } from "../config.js";
+import { createAgentLogWriter } from "../utils/agent-runtime.js";
+import { errorMessage } from "../utils/value.js";
+/** 使用 Claude CLI 执行一次带 Canvas Agent 工具的任务。 */
+export function runClaudeTurn(prompt, emit) {
+    const fullPrompt = withAgentPrompt(prompt);
+    if (!fullPrompt)
+        return;
+    const child = spawnAgent("claude", ["-p", "--output-format", "stream-json", "--verbose", "--include-partial-messages", "--allowedTools", "mcp__infinite-canvas__*", fullPrompt], emit);
+    if (child)
+        pipeJsonLines(child, emit, "claude");
+}
+/** 为 Claude CLI 请求拼接 Canvas Agent 指令。 */
+function withAgentPrompt(prompt) {
+    return prompt.trim() ? `${AGENT_PROMPT}\n\n用户请求：${prompt}` : "";
+}
+/** 将 Claude CLI 的 JSON Lines 输出转换为 Agent 事件。 */
+function pipeJsonLines(child, emit, agent) {
+    let out = "";
+    const stderr = createAgentLogWriter((text) => emit("agent_log", { text }));
+    child.stdout?.on("data", (chunk) => {
+        out += chunk.toString();
+        const lines = out.split(/\r?\n/);
+        out = lines.pop() || "";
+        lines.filter(Boolean).forEach((line) => {
+            try {
+                emit("agent_event", { agent, ...JSON.parse(line) });
+            }
+            catch {
+                emit("agent_event", { agent, type: "raw", text: line });
+            }
+        });
+    });
+    child.stderr?.on("data", (chunk) => stderr.write(chunk.toString()));
+    child.on("error", (error) => {
+        stderr.flush();
+        emit("agent_error", { message: error.message });
+    });
+    child.on("close", (code) => {
+        stderr.flush();
+        emit("agent_done", { agent, code });
+    });
+}
+/** 启动外部 Agent CLI，并将同步启动异常转换为事件。 */
+function spawnAgent(name, args, emit) {
+    try {
+        return spawn(name, args, { stdio: ["ignore", "pipe", "pipe"], shell: process.platform === "win32", windowsHide: true });
+    }
+    catch (error) {
+        emit("agent_error", { message: errorMessage(error) });
+        return null;
+    }
+}

package/dist/agent/codex-client.d.ts

@@ -0,0 +1,139 @@
+import { type JsonRecord } from "../utils/value.js";
+import type { CodexPlanUpdate, CodexReasoningEffort, CodexRequestParams, CodexSkillSelector } from "./codex-protocol.js";
+import type { AgentEmit, AgentPermissionMode } from "./types.js";
+/** 表示错误已经通过 app-server 终态或进程事件通知过网页。 */
+export declare class CodexReportedError extends Error {
+    name: string;
+}
+/** 封装 Codex app-server 的 JSON-RPC 通信与事件转换。 */
+export declare class CodexAppClient {
+    private child;
+    private emit;
+    private eventHistory;
+    private nextId;
+    private buffer;
+    private currentThreadId;
+    private currentTurnId;
+    private pendingTurnStart?;
+    private startedTurnKeys;
+    private textByItem;
+    private reasoningTextByItem;
+    private lastUsage;
+    private pending;
+    private activeTurns;
+    private completedTurns;
+    private completedTurnResults;
+    private pendingDeltas;
+    private startedItems;
+    private itemSequences;
+    private nextItemSequences;
+    private plansByTurn;
+    private approvalRequests;
+    private finalizingTurns;
+    private skillReloads;
+    private silentThreadIds;
+    private structuredOutputByTurn;
+    private pendingSilentThreadStarts;
+    private pendingThreadStartedNotifications;
+    private pendingPreheatThreadStarts;
+    private preheatingThreadIds;
+    private failing;
+    private failureMessage;
+    /** 保存 app-server 子进程和事件出口。 */
+    private constructor();
+    /** 启动并初始化 Codex app-server。 */
+    static start(emit: AgentEmit, onExit: () => void): Promise<CodexAppClient>;
+    /** 创建新的 Codex 线程。 */
+    startThread(cwd?: string, permissionMode?: AgentPermissionMode, preheat?: boolean): Promise<import("./codex-protocol.js").CodexThread>;
+    /** 创建不会持久化或向网页广播的草稿线程。 */
+    startSkillDraftThread(cwd: string): Promise<import("./codex-protocol.js").CodexThread>;
+    /** 从指定对话派生不会持久化或向网页广播的草稿线程。 */
+    forkSkillDraftThread(threadId: string, cwd: string): Promise<import("./codex-protocol.js").CodexThread>;
+    /** 恢复已有 Codex 线程。 */
+    resumeThread(threadId: string, cwd?: string, permissionMode?: AgentPermissionMode, preheat?: boolean): Promise<import("./codex-protocol.js").CodexThread>;
+    /** 以 app-server 的权威 MCP 清单响应作为预热完成边界。 */
+    private completeMcpPreheat;
+    /** 查询 Codex 线程列表。 */
+    listThreads(params: CodexRequestParams<"thread/list">): Promise<{
+        data: import("./codex-protocol.js").CodexThread[];
+        nextCursor: string | null;
+        backwardsCursor: string | null;
+    }>;
+    /** 读取指定 Codex 线程。 */
+    readThread(threadId: string, includeTurns?: boolean): Promise<{
+        thread: import("./codex-protocol.js").CodexThread;
+    }>;
+    /** 归档指定 Codex 线程。 */
+    archiveThread(threadId: string): Promise<Record<string, never>>;
+    /** 释放临时草稿线程的 App Server 订阅和进程内缓存。 */
+    closeSkillDraftThread(threadId: string): Promise<void>;
+    /** 查询当前账号可用的 Codex 模型。 */
+    listModels(): Promise<{
+        data: import("./codex-protocol.js").CodexModel[];
+        nextCursor: string | null;
+    }>;
+    /** 查询指定工作空间可发现的 Codex Skills。 */
+    listSkills(cwd: string, forceReload?: boolean): Promise<{
+        data: import("./codex-protocol.js").CodexSkillsListEntry[];
+    }>;
+    /** 修改一个已发现 Skill 的启用状态。 */
+    setSkillEnabled(path: string, enabled: boolean): Promise<{
+        effectiveEnabled: boolean;
+    }>;
+    /** 返回指定线程在当前进程中收到的最新任务计划。 */
+    planUpdates(threadId: string): CodexPlanUpdate[];
+    /** 清理已归档线程的任务计划缓存。 */
+    clearPlanUpdates(threadId: string): void;
+    /** 启动一个 Codex turn 并等待完成通知。 */
+    startTurn(threadId: string, prompt: string, images: string[], permissionMode: AgentPermissionMode, model?: string, effort?: CodexReasoningEffort, onTurn?: (turnId: string) => void, skill?: CodexSkillSelector, messageText?: string, outputSchema?: JsonRecord): Promise<unknown>;
+    /** 在静默线程中生成结构化输出。 */
+    generateSkillDraft(threadId: string, prompt: string, outputSchema: JsonRecord, model?: string, effort?: CodexReasoningEffort): Promise<string>;
+    /** 中断当前正在运行且属于指定线程的 Codex turn。 */
+    interruptCurrentTurn(requestedThreadId?: string): Promise<boolean>;
+    /** 回复网页端已经确认的 Codex 权限请求。 */
+    resolveApproval(requestId: string, decision: string): boolean;
+    /** 标记下一次临时线程创建，使早于请求响应到达的通知也不会外泄。 */
+    private startSilentThread;
+    /** 发送 JSON-RPC 请求并保存待处理 Promise。 */
+    private request;
+    /** 发送无需响应的 JSON-RPC 通知。 */
+    private notify;
+    /** 将 JSON-RPC 消息写入 app-server 标准输入。 */
+    private write;
+    /** 按行解析 app-server 标准输出。 */
+    private read;
+    /** 分派单条 JSON-RPC 响应、请求或通知。 */
+    private handle;
+    /** 转换并广播 app-server 通知。 */
+    private handleNotification;
+    /** 草稿线程存续期间隐藏 app-server 自身输出，避免混入网页诊断日志。 */
+    private get skillDraftActive();
+    /** 消化临时草稿线程事件，不广播、不落补充历史。 */
+    private handleSilentNotification;
+    /** 请求响应确定静默线程 ID 后，重新分流早到的启动通知。 */
+    private flushPendingThreadStartedNotifications;
+    /** 补充历史落盘后再广播 turn 终态，确保界面完成状态可跨 Agent 重启恢复。 */
+    private completeTurn;
+    /** 合并并广播 Agent 文本或执行输出增量。 */
+    private emitDelta;
+    /** 合并短时间内的文本增量，减少 SSE 传输和前端渲染次数。 */
+    private flushDelta;
+    /** 按 Codex summaryIndex 保存 reasoning 分段，顺序与线程历史一致。 */
+    private appendReasoningText;
+    /** turn 结束时发送最后一批增量并清理未收到 item.completed 的缓存。 */
+    private finishTurnDeltas;
+    /** 为一个 turn 内的 item 固定开始顺序，完成通知只更新内容。 */
+    private assignItemSequence;
+    /** 在通知或 turn/start 响应到达时回调一次 turn 启动状态。 */
+    private notifyTurnStarted;
+    /** 自动回复 app-server 发起的授权或交互请求。 */
+    private answerServerRequest;
+    /** 完成指定 JSON-RPC 请求。 */
+    private resolve;
+    /** 拒绝指定 JSON-RPC 请求。 */
+    private reject;
+    /** 拒绝进程退出时仍未完成的请求与 turn。 */
+    private failAll;
+}
+/** 合并单个 reasoning 分段增量并按 summaryIndex 输出。 */
+export declare function appendReasoningDelta(segments: Map<number, string>, summaryIndex: number | undefined, delta: string): string;