pixi-board-plugin-mivo 0.1.0

package/dist/index.js

@@ -0,0 +1,463 @@
+// src/index.ts
+import { mkdir as mkdir2 } from "fs/promises";
+import path2 from "path";
+
+// src/mivoCli.ts
+import { execFile } from "child_process";
+import { mkdir, mkdtemp, writeFile } from "fs/promises";
+import os from "os";
+import path from "path";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+var DEFAULT_API_BASE = "https://aigc.xindong.com/api/v1";
+var URL_KEYS = ["signUrl", "sign_url", "url", "uri", "displayUrl", "fileUrl", "downloadUrl", "src", "image"];
+var ID_KEYS = ["fileId", "file_id", "object_id", "_id"];
+function createMivoCliClient(env = process.env) {
+  const command = env.MIVO_CLI_PATH?.trim() || "mivo-cli";
+  let ready = false;
+  async function run(args, options) {
+    const { stdout } = await execFileAsync(command, args, {
+      env: {
+        ...process.env,
+        ...env
+      },
+      input: options?.input,
+      maxBuffer: 10 * 1024 * 1024
+    });
+    return parseJson(stdout);
+  }
+  return {
+    async ensureReady() {
+      if (ready) return;
+      const apiKey = env.MIVO_API_KEY?.trim();
+      if (apiKey) {
+        await run(["config", "set", "api_base", env.MIVO_API_BASE?.trim() || DEFAULT_API_BASE, "--json"]);
+        await run(["login", "--key", apiKey, "--json"]);
+      }
+      ready = true;
+    },
+    async getChatSessionId(chatType) {
+      await this.ensureReady();
+      const value = await run(["message", "chat", "--type", chatType, "--json"]);
+      const record = asRecord(value, "message chat output");
+      const chatSessionId = readStringFromAny(record, ["chatSessionId", "chat_session_id", "id"]);
+      if (!chatSessionId) {
+        throw new Error("mivo-cli message chat did not return a chat session id");
+      }
+      return chatSessionId;
+    },
+    async submitMessage(payload) {
+      await this.ensureReady();
+      const dir = await mkdtemp(path.join(os.tmpdir(), "pixi-board-mivo-"));
+      const payloadPath = path.join(dir, `message-${Date.now()}-${Math.random().toString(16).slice(2)}.json`);
+      await writeFile(payloadPath, JSON.stringify(payload), "utf8");
+      const value = await run(["message", "submit", "--file", payloadPath, "--no-wait", "--json"]);
+      const record = asRecord(value, "message submit output");
+      const messageId = readStringFromAny(record, ["messageId", "message_id", "id"]);
+      if (!messageId) {
+        throw new Error("mivo-cli message submit did not return a message id");
+      }
+      return messageId;
+    },
+    async detailBatch(messageIds) {
+      await this.ensureReady();
+      const value = await run(["message", "detail-batch", ...messageIds, "--json"]);
+      if (Array.isArray(value)) {
+        return value;
+      }
+      const record = asRecord(value, "message detail-batch output");
+      if (Array.isArray(record.messages)) {
+        return record.messages;
+      }
+      if (Array.isArray(record.results)) {
+        return record.results;
+      }
+      if (Array.isArray(record.data)) {
+        return record.data;
+      }
+      throw new Error("mivo-cli message detail-batch returned an unsupported JSON shape");
+    },
+    async downloadFile(fileId, savePath) {
+      await this.ensureReady();
+      await mkdir(path.dirname(savePath), { recursive: true });
+      await run(["file", "download", fileId, savePath, "--json"]);
+    }
+  };
+}
+function extractImageArtifact(message) {
+  const image = message.content?.images?.[0];
+  if (image === void 0 || image === null) return null;
+  if (typeof image === "string") {
+    if (/^https?:\/\//i.test(image)) return { url: image };
+    return { fileId: image };
+  }
+  if (!isRecord(image)) return null;
+  const url = readStringFromAny(image, URL_KEYS);
+  const fileId = readStringFromAny(image, ID_KEYS);
+  if (!url && !fileId) return null;
+  return { fileId, url };
+}
+function mivoFileUrl(fileId) {
+  return `${DEFAULT_API_BASE}/file/image/${encodeURIComponent(fileId)}`;
+}
+async function downloadUrl(url, savePath) {
+  await mkdir(path.dirname(savePath), { recursive: true });
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to download Mivo image URL: ${response.status} ${response.statusText}`);
+  }
+  const buffer = Buffer.from(await response.arrayBuffer());
+  await writeFile(savePath, buffer);
+}
+function parseJson(stdout) {
+  try {
+    return JSON.parse(stdout);
+  } catch (error) {
+    throw new Error(`mivo-cli returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+function readStringFromAny(record, keys) {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim() !== "") {
+      return value;
+    }
+  }
+  return void 0;
+}
+function asRecord(value, label) {
+  if (!isRecord(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value;
+}
+function isRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+// src/index.ts
+var RATIOS = ["1:1", "2:3", "3:2", "9:16", "16:9"];
+var DEFAULT_RATIO = "1:1";
+var DEFAULT_TIMEOUT_MS = 3e5;
+var DEFAULT_POLL_INTERVAL_MS = 2e3;
+var anyOutputSchema = {
+  type: "object",
+  additionalProperties: true
+};
+var mivoPlugin = {
+  name: "pixi-board-plugin-mivo",
+  version: "0.1.0",
+  dependencies: {
+    tools: [
+      "canvas.create_nodes",
+      "canvas.generating_node_install",
+      "canvas.update_nodes",
+      "canvas.read_project_info"
+    ]
+  },
+  register(api) {
+    api.registerTool(createMivoCreateGptImageTool());
+  }
+};
+var plugin = mivoPlugin;
+function createMivoCreateGptImageTool(deps = {}) {
+  const cli = deps.cli ?? createMivoCliClient();
+  const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const downloadRemoteUrl = deps.downloadRemoteUrl ?? downloadUrl;
+  return {
+    name: "mivo.create_gpt_image",
+    description: "Create a generating canvas node, submit a GPT Image 2 Mivo task, poll until the image is ready, then replace the generating node with the downloaded media asset.",
+    kind: "plugin",
+    inputSchema: createGptImageInputSchema,
+    outputSchema: createGptImageOutputSchema,
+    async run(input, ctx) {
+      const args = readInput(input);
+      const projectInfo = await ctx.tools.call("canvas.read_project_info", {
+        projectRoot: args.projectRoot
+      });
+      const projectRoot = projectInfo.projectRoot;
+      let nodeId = null;
+      let messageId = null;
+      try {
+        const createResult = await ctx.tools.call("canvas.create_nodes", {
+          projectRoot,
+          nodes: [
+            {
+              kind: "generating",
+              name: args.name ?? defaultNodeName(args.prompt),
+              options: {
+                mivo: {
+                  status: "generating",
+                  provider: "mivo",
+                  tool: "mivo.create_gpt_image",
+                  prompt: args.prompt,
+                  ratio: args.ratio
+                }
+              }
+            }
+          ]
+        });
+        nodeId = readCreatedNodeId(createResult);
+        const chatSessionId = await cli.getChatSessionId("freeform");
+        messageId = await cli.submitMessage(buildSubmitPayload(args, chatSessionId));
+        const artifact = await pollForImage(cli, messageId, args.timeoutMs, args.pollIntervalMs, sleep);
+        const imagePath = await materializeArtifact(cli, artifact, projectRoot, messageId, downloadRemoteUrl);
+        const installResult = await ctx.tools.call("canvas.generating_node_install", {
+          projectRoot,
+          nodeId,
+          path: imagePath
+        });
+        return {
+          nodeId,
+          messageId,
+          imagePath,
+          imageUrl: artifact.url ?? (artifact.fileId ? mivoFileUrl(artifact.fileId) : void 0),
+          nodes: installResult.nodes,
+          assets: installResult.assets ?? []
+        };
+      } catch (error) {
+        if (nodeId) {
+          await markNodeFailed(ctx, projectRoot, nodeId, error, messageId);
+        }
+        throw error;
+      }
+    }
+  };
+}
+var createGptImageInputSchema = objectSchema({
+  projectRoot: stringSchema('Canvas project root absolute path, or "active" for the current canvas'),
+  prompt: stringSchema("Prompt for GPT Image 2"),
+  ratio: {
+    type: "string",
+    enum: RATIOS,
+    description: "Generated image aspect ratio"
+  },
+  name: stringSchema("Optional display name for the generating node"),
+  referenceFileIds: {
+    type: "array",
+    items: { type: "string" },
+    description: "Optional Mivo file ids to use as image references"
+  },
+  timeoutMs: {
+    type: "number",
+    description: "Maximum time to wait for the Mivo message result"
+  },
+  pollIntervalMs: {
+    type: "number",
+    description: "Delay between Mivo detail-batch polling attempts"
+  }
+}, ["projectRoot", "prompt"]);
+var createGptImageOutputSchema = objectSchema({
+  nodeId: { type: "string" },
+  messageId: { type: "string" },
+  imagePath: { type: "string" },
+  imageUrl: { type: "string" },
+  nodes: {
+    type: "array",
+    items: anyOutputSchema
+  },
+  assets: {
+    type: "array",
+    items: anyOutputSchema
+  }
+}, ["nodeId", "messageId", "imagePath", "nodes", "assets"]);
+function buildSubmitPayload(input, chatSessionId) {
+  const images = input.referenceFileIds ?? [];
+  return {
+    chatSessionId,
+    title: "\u4F5C\u56FE",
+    modelType: "GPT",
+    action: images.length > 0 ? "modal" : "imagine",
+    messageType: "image",
+    modelFormat: {
+      version: "gpt-image-2"
+    },
+    payload: {
+      prompt: input.prompt,
+      images,
+      n: 1,
+      imgRatio: input.ratio,
+      quality: "auto",
+      credentialSource: "personal"
+    }
+  };
+}
+async function pollForImage(cli, messageId, timeoutMs, pollIntervalMs, sleep) {
+  const start = Date.now();
+  while (Date.now() - start <= timeoutMs) {
+    const item = findDetailItem(await cli.detailBatch([messageId]), messageId);
+    const message = readMessageResult(item);
+    const artifact = extractImageArtifact(message);
+    if (artifact) {
+      return artifact;
+    }
+    const status = normalizeStatus(message.content?.status ?? message.status);
+    const error = message.content?.error ?? message.error ?? item.error;
+    if (error || isFailedStatus(status)) {
+      throw new Error(`Mivo GPT image generation failed for ${messageId}: ${error ?? status}`);
+    }
+    if (isCompletedStatus(status)) {
+      throw new Error(`Mivo GPT image generation completed for ${messageId} but returned no image`);
+    }
+    await sleep(pollIntervalMs);
+  }
+  throw new Error(`Mivo GPT image generation timed out for ${messageId} after ${timeoutMs}ms`);
+}
+async function materializeArtifact(cli, artifact, projectRoot, messageId, downloadRemoteUrl) {
+  const outputDir = path2.join(projectRoot, ".canvas-mcp", "mivo");
+  await mkdir2(outputDir, { recursive: true });
+  const imagePath = path2.join(outputDir, `${safeFileName(messageId)}.png`);
+  if (artifact.fileId) {
+    await cli.downloadFile(artifact.fileId, imagePath);
+    return imagePath;
+  }
+  if (artifact.url) {
+    await downloadRemoteUrl(artifact.url, imagePath);
+    return imagePath;
+  }
+  throw new Error(`Mivo GPT image generation returned an image artifact without file id or URL for ${messageId}`);
+}
+async function markNodeFailed(ctx, projectRoot, nodeId, error, messageId) {
+  try {
+    await ctx.tools.call("canvas.update_nodes", {
+      projectRoot,
+      updates: [
+        {
+          id: nodeId,
+          name: "Failed: GPT image",
+          options: {
+            mivo: {
+              status: "failed",
+              messageId,
+              error: errorMessage(error)
+            }
+          }
+        }
+      ]
+    });
+  } catch {
+  }
+}
+function findDetailItem(items, messageId) {
+  const item = items.find((entry) => entry.message_id === messageId) ?? items[0];
+  if (!item) {
+    throw new Error(`Mivo detail-batch returned no result for ${messageId}`);
+  }
+  if (item.ok === false || item.error) {
+    throw new Error(`Mivo detail-batch failed for ${messageId}: ${item.error ?? "unknown error"}`);
+  }
+  return item;
+}
+function readMessageResult(item) {
+  if (!item.message || typeof item.message !== "object") {
+    throw new Error("Mivo detail-batch result did not include a message object");
+  }
+  return item.message;
+}
+function normalizeStatus(status) {
+  return typeof status === "string" ? status.toLowerCase() : "";
+}
+function isFailedStatus(status) {
+  return ["failed", "failure", "error", "errored", "canceled", "cancelled"].includes(status);
+}
+function isCompletedStatus(status) {
+  return ["completed", "complete", "success", "succeeded"].includes(status);
+}
+function readCreatedNodeId(result) {
+  const nodeId = result.nodes[0]?.id;
+  if (typeof nodeId !== "string" || nodeId.trim() === "") {
+    throw new Error("canvas.create_nodes did not return a created node id");
+  }
+  return nodeId;
+}
+function readInput(input) {
+  const record = asRecord2(input);
+  const projectRoot = readString(record, "projectRoot");
+  const prompt = readString(record, "prompt");
+  const ratio = readOptionalRatio(record.ratio);
+  const referenceFileIds = readOptionalStringArray(record.referenceFileIds, "referenceFileIds");
+  const timeoutMs = readOptionalPositiveNumber(record.timeoutMs, "timeoutMs") ?? DEFAULT_TIMEOUT_MS;
+  const pollIntervalMs = readOptionalPositiveNumber(record.pollIntervalMs, "pollIntervalMs") ?? DEFAULT_POLL_INTERVAL_MS;
+  return {
+    projectRoot,
+    prompt,
+    ratio,
+    name: readOptionalString(record.name, "name"),
+    referenceFileIds,
+    timeoutMs,
+    pollIntervalMs
+  };
+}
+function readOptionalRatio(value) {
+  if (value === void 0) return DEFAULT_RATIO;
+  if (typeof value !== "string" || !RATIOS.includes(value)) {
+    throw new Error(`ratio must be one of ${RATIOS.join(", ")}`);
+  }
+  return value;
+}
+function readOptionalStringArray(value, label) {
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an array`);
+  }
+  return value.map((entry, index) => {
+    if (typeof entry !== "string" || entry.trim() === "") {
+      throw new Error(`${label}[${index}] must be a non-empty string`);
+    }
+    return entry;
+  });
+}
+function readOptionalPositiveNumber(value, label) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    throw new Error(`${label} must be a positive finite number`);
+  }
+  return value;
+}
+function readOptionalString(value, label) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return value;
+}
+function readString(record, key) {
+  const value = record[key];
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${key} must be a non-empty string`);
+  }
+  return value;
+}
+function defaultNodeName(prompt) {
+  const normalized = prompt.replace(/\s+/g, " ").trim();
+  const suffix = normalized.length > 48 ? `${normalized.slice(0, 48)}...` : normalized;
+  return `GPT image: ${suffix}`;
+}
+function safeFileName(value) {
+  return value.replace(/[^a-zA-Z0-9._-]/g, "_") || `mivo-${Date.now()}`;
+}
+function objectSchema(properties, required) {
+  return {
+    type: "object",
+    additionalProperties: false,
+    required,
+    properties
+  };
+}
+function stringSchema(description) {
+  return { type: "string", description };
+}
+function asRecord2(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("input must be an object");
+  }
+  return value;
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+export {
+  createMivoCreateGptImageTool,
+  mivoPlugin,
+  plugin
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "pixi-board-plugin-mivo",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --platform node --target node20 --out-dir dist --clean",
+    "prepack": "pnpm build",
+    "test": "tsx --test src/**/*.test.ts"
+  },
+  "devDependencies": {
+    "@canvas/board-plugin-sdk": "workspace:*",
+    "@canvas/board-tool-runtime": "workspace:*",
+    "@types/node": "^24.10.1",
+    "tsup": "^8.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,233 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createBoardToolRuntime } from "@canvas/board-tool-runtime";
+import type { BoardPlugin } from "@canvas/board-plugin-sdk";
+import { createMivoCreateGptImageTool, mivoPlugin } from "./index";
+import type { MivoCliClient, MivoMessageDetailBatchItem } from "./mivoCli";
+
+test("mivo plugin requires canvas tools before registration", async () => {
+  const runtime = createBoardToolRuntime();
+
+  await assert.rejects(
+    () => runtime.registerPlugin(mivoPlugin),
+    /requires missing tool/,
+  );
+});
+
+test("mivo plugin registers after canvas plugin", async () => {
+  const runtime = createBoardToolRuntime();
+  await runtime.registerPlugin(fakeCanvasPlugin());
+  await runtime.registerPlugin(mivoPlugin);
+
+  assert.ok(runtime.listTools().some((tool) => tool.name === "mivo.create_gpt_image"));
+});
+
+test("mivo.create_gpt_image creates placeholder, submits no-wait message, polls, downloads, and installs", async () => {
+  const calls: Array<{ name: string; input: unknown }> = [];
+  const cli = new MockMivoCli([
+    {
+      message_id: "message-1",
+      ok: true,
+      message: {
+        status: "processing",
+        content: {
+          status: "processing",
+          images: [],
+        },
+      },
+    },
+    {
+      message_id: "message-1",
+      ok: true,
+      message: {
+        status: "completed",
+        content: {
+          status: "completed",
+          images: [
+            {
+              fileId: "file-1",
+            },
+          ],
+        },
+      },
+    },
+  ]);
+  const tool = createMivoCreateGptImageTool({
+    cli,
+    sleep: async () => {},
+  });
+
+  const result = await tool.run({
+    projectRoot: "active",
+    prompt: "a small red house",
+    ratio: "16:9",
+    referenceFileIds: ["ref-1"],
+  }, {
+    tools: {
+      async call(name, input) {
+        calls.push({ name, input });
+        if (name === "canvas.read_project_info") {
+          return { projectRoot: "/tmp/canvas-project" };
+        }
+        if (name === "canvas.create_nodes") {
+          return { nodes: [{ id: "node-1" }], assets: [] };
+        }
+        if (name === "canvas.generating_node_install") {
+          return { nodes: [{ id: "node-1", type: "image" }], assets: [{ id: "asset-1" }] };
+        }
+        throw new Error(`Unexpected tool call: ${name}`);
+      },
+    },
+  });
+
+  assert.deepEqual(calls.map((call) => call.name), [
+    "canvas.read_project_info",
+    "canvas.create_nodes",
+    "canvas.generating_node_install",
+  ]);
+  assert.equal(cli.submittedPayload?.chatSessionId, "chat-1");
+  assert.equal(cli.submittedPayload?.modelType, "GPT");
+  assert.equal(cli.submittedPayload?.action, "modal");
+  assert.deepEqual(cli.submittedPayload?.modelFormat, { version: "gpt-image-2" });
+  assert.deepEqual(cli.submittedPayload?.payload, {
+    prompt: "a small red house",
+    images: ["ref-1"],
+    n: 1,
+    imgRatio: "16:9",
+    quality: "auto",
+    credentialSource: "personal",
+  });
+  assert.deepEqual(cli.downloads, [
+    {
+      fileId: "file-1",
+      savePath: "/tmp/canvas-project/.canvas-mcp/mivo/message-1.png",
+    },
+  ]);
+  assert.deepEqual(result, {
+    nodeId: "node-1",
+    messageId: "message-1",
+    imagePath: "/tmp/canvas-project/.canvas-mcp/mivo/message-1.png",
+    imageUrl: "https://aigc.xindong.com/api/v1/file/image/file-1",
+    nodes: [{ id: "node-1", type: "image" }],
+    assets: [{ id: "asset-1" }],
+  });
+});
+
+test("mivo.create_gpt_image marks placeholder failed when generation fails", async () => {
+  const calls: Array<{ name: string; input: unknown }> = [];
+  const cli = new MockMivoCli([
+    {
+      message_id: "message-1",
+      ok: true,
+      message: {
+        status: "failed",
+        error: "bad prompt",
+        content: {
+          status: "failed",
+        },
+      },
+    },
+  ]);
+  const tool = createMivoCreateGptImageTool({
+    cli,
+    sleep: async () => {},
+  });
+
+  await assert.rejects(
+    () =>
+      tool.run({
+        projectRoot: "/tmp/canvas-project",
+        prompt: "bad prompt",
+      }, {
+        tools: {
+          async call(name, input) {
+            calls.push({ name, input });
+            if (name === "canvas.read_project_info") {
+              return { projectRoot: "/tmp/canvas-project" };
+            }
+            if (name === "canvas.create_nodes") {
+              return { nodes: [{ id: "node-1" }], assets: [] };
+            }
+            if (name === "canvas.update_nodes") {
+              return { nodes: [{ id: "node-1" }] };
+            }
+            throw new Error(`Unexpected tool call: ${name}`);
+          },
+        },
+      }),
+    /bad prompt/,
+  );
+
+  const updateCall = calls.find((call) => call.name === "canvas.update_nodes");
+  assert.ok(updateCall);
+  assert.deepEqual(updateCall.input, {
+    projectRoot: "/tmp/canvas-project",
+    updates: [
+      {
+        id: "node-1",
+        name: "Failed: GPT image",
+        options: {
+          mivo: {
+            status: "failed",
+            messageId: "message-1",
+            error: "Mivo GPT image generation failed for message-1: bad prompt",
+          },
+        },
+      },
+    ],
+  });
+});
+
+class MockMivoCli implements MivoCliClient {
+  submittedPayload: Record<string, unknown> | null = null;
+  readonly downloads: Array<{ fileId: string; savePath: string }> = [];
+  private detailIndex = 0;
+
+  constructor(private readonly details: MivoMessageDetailBatchItem[]) {}
+
+  async ensureReady(): Promise<void> {}
+
+  async getChatSessionId(): Promise<string> {
+    return "chat-1";
+  }
+
+  async submitMessage(payload: Record<string, unknown>): Promise<string> {
+    this.submittedPayload = payload;
+    return "message-1";
+  }
+
+  async detailBatch(): Promise<MivoMessageDetailBatchItem[]> {
+    const detail = this.details[Math.min(this.detailIndex, this.details.length - 1)];
+    this.detailIndex += 1;
+    return [detail];
+  }
+
+  async downloadFile(fileId: string, savePath: string): Promise<void> {
+    this.downloads.push({ fileId, savePath });
+  }
+}
+
+function fakeCanvasPlugin(): BoardPlugin {
+  return {
+    name: "@test/canvas",
+    version: "0.1.0",
+    register(api) {
+      for (const name of [
+        "canvas.create_nodes",
+        "canvas.generating_node_install",
+        "canvas.update_nodes",
+        "canvas.read_project_info",
+      ]) {
+        api.registerTool({
+          name,
+          description: name,
+          inputSchema: { type: "object", additionalProperties: true },
+          outputSchema: { type: "object", additionalProperties: true },
+          async run() {
+            return {};
+          },
+        });
+      }
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,418 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import type { BoardPlugin, BoardTool, BoardToolContext, JSONSchema } from "@canvas/board-plugin-sdk";
+import {
+  createMivoCliClient,
+  downloadUrl,
+  extractImageArtifact,
+  mivoFileUrl,
+  type MivoCliClient,
+  type MivoImageArtifact,
+  type MivoMessageDetailBatchItem,
+  type MivoMessageResult,
+} from "./mivoCli";
+
+const RATIOS = ["1:1", "2:3", "3:2", "9:16", "16:9"] as const;
+const DEFAULT_RATIO = "1:1";
+const DEFAULT_TIMEOUT_MS = 300_000;
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+
+type Ratio = (typeof RATIOS)[number];
+
+type CreateGptImageInput = {
+  projectRoot: string;
+  prompt: string;
+  ratio?: Ratio;
+  name?: string;
+  referenceFileIds?: string[];
+  timeoutMs?: number;
+  pollIntervalMs?: number;
+};
+
+type NodeDto = {
+  id: string;
+  [key: string]: unknown;
+};
+
+type NodesAssetsResult = {
+  nodes: NodeDto[];
+  assets?: unknown[];
+};
+
+type ProjectInfoResult = {
+  projectRoot: string;
+};
+
+type CreateGptImageToolDeps = {
+  cli?: MivoCliClient;
+  sleep?: (ms: number) => Promise<void>;
+  downloadRemoteUrl?: (url: string, savePath: string) => Promise<void>;
+};
+
+const anyOutputSchema = {
+  type: "object",
+  additionalProperties: true,
+};
+
+export const mivoPlugin: BoardPlugin = {
+  name: "pixi-board-plugin-mivo",
+  version: "0.1.0",
+  dependencies: {
+    tools: [
+      "canvas.create_nodes",
+      "canvas.generating_node_install",
+      "canvas.update_nodes",
+      "canvas.read_project_info",
+    ],
+  },
+  register(api) {
+    api.registerTool(createMivoCreateGptImageTool());
+  },
+};
+
+export const plugin = mivoPlugin;
+
+export function createMivoCreateGptImageTool(deps: CreateGptImageToolDeps = {}): BoardTool {
+  const cli = deps.cli ?? createMivoCliClient();
+  const sleep = deps.sleep ?? ((ms) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const downloadRemoteUrl = deps.downloadRemoteUrl ?? downloadUrl;
+
+  return {
+    name: "mivo.create_gpt_image",
+    description: "Create a generating canvas node, submit a GPT Image 2 Mivo task, poll until the image is ready, then replace the generating node with the downloaded media asset.",
+    kind: "plugin",
+    inputSchema: createGptImageInputSchema,
+    outputSchema: createGptImageOutputSchema,
+    async run(input, ctx) {
+      const args = readInput(input);
+      const projectInfo = await ctx.tools.call<CreateGptImageInput, ProjectInfoResult>("canvas.read_project_info", {
+        projectRoot: args.projectRoot,
+      });
+      const projectRoot = projectInfo.projectRoot;
+      let nodeId: string | null = null;
+      let messageId: string | null = null;
+
+      try {
+        const createResult = await ctx.tools.call<unknown, NodesAssetsResult>("canvas.create_nodes", {
+          projectRoot,
+          nodes: [
+            {
+              kind: "generating",
+              name: args.name ?? defaultNodeName(args.prompt),
+              options: {
+                mivo: {
+                  status: "generating",
+                  provider: "mivo",
+                  tool: "mivo.create_gpt_image",
+                  prompt: args.prompt,
+                  ratio: args.ratio,
+                },
+              },
+            },
+          ],
+        });
+        nodeId = readCreatedNodeId(createResult);
+
+        const chatSessionId = await cli.getChatSessionId("freeform");
+        messageId = await cli.submitMessage(buildSubmitPayload(args, chatSessionId));
+        const artifact = await pollForImage(cli, messageId, args.timeoutMs, args.pollIntervalMs, sleep);
+        const imagePath = await materializeArtifact(cli, artifact, projectRoot, messageId, downloadRemoteUrl);
+        const installResult = await ctx.tools.call<unknown, NodesAssetsResult>("canvas.generating_node_install", {
+          projectRoot,
+          nodeId,
+          path: imagePath,
+        });
+
+        return {
+          nodeId,
+          messageId,
+          imagePath,
+          imageUrl: artifact.url ?? (artifact.fileId ? mivoFileUrl(artifact.fileId) : undefined),
+          nodes: installResult.nodes,
+          assets: installResult.assets ?? [],
+        };
+      } catch (error) {
+        if (nodeId) {
+          await markNodeFailed(ctx, projectRoot, nodeId, error, messageId);
+        }
+        throw error;
+      }
+    },
+  };
+}
+
+const createGptImageInputSchema = objectSchema({
+  projectRoot: stringSchema('Canvas project root absolute path, or "active" for the current canvas'),
+  prompt: stringSchema("Prompt for GPT Image 2"),
+  ratio: {
+    type: "string",
+    enum: RATIOS,
+    description: "Generated image aspect ratio",
+  },
+  name: stringSchema("Optional display name for the generating node"),
+  referenceFileIds: {
+    type: "array",
+    items: { type: "string" },
+    description: "Optional Mivo file ids to use as image references",
+  },
+  timeoutMs: {
+    type: "number",
+    description: "Maximum time to wait for the Mivo message result",
+  },
+  pollIntervalMs: {
+    type: "number",
+    description: "Delay between Mivo detail-batch polling attempts",
+  },
+}, ["projectRoot", "prompt"]);
+
+const createGptImageOutputSchema = objectSchema({
+  nodeId: { type: "string" },
+  messageId: { type: "string" },
+  imagePath: { type: "string" },
+  imageUrl: { type: "string" },
+  nodes: {
+    type: "array",
+    items: anyOutputSchema,
+  },
+  assets: {
+    type: "array",
+    items: anyOutputSchema,
+  },
+}, ["nodeId", "messageId", "imagePath", "nodes", "assets"]);
+
+function buildSubmitPayload(input: CreateGptImageInput, chatSessionId: string): Record<string, unknown> {
+  const images = input.referenceFileIds ?? [];
+  return {
+    chatSessionId,
+    title: "作图",
+    modelType: "GPT",
+    action: images.length > 0 ? "modal" : "imagine",
+    messageType: "image",
+    modelFormat: {
+      version: "gpt-image-2",
+    },
+    payload: {
+      prompt: input.prompt,
+      images,
+      n: 1,
+      imgRatio: input.ratio,
+      quality: "auto",
+      credentialSource: "personal",
+    },
+  };
+}
+
+async function pollForImage(
+  cli: MivoCliClient,
+  messageId: string,
+  timeoutMs: number,
+  pollIntervalMs: number,
+  sleep: (ms: number) => Promise<void>,
+): Promise<MivoImageArtifact> {
+  const start = Date.now();
+  while (Date.now() - start <= timeoutMs) {
+    const item = findDetailItem(await cli.detailBatch([messageId]), messageId);
+    const message = readMessageResult(item);
+    const artifact = extractImageArtifact(message);
+    if (artifact) {
+      return artifact;
+    }
+
+    const status = normalizeStatus(message.content?.status ?? message.status);
+    const error = message.content?.error ?? message.error ?? item.error;
+    if (error || isFailedStatus(status)) {
+      throw new Error(`Mivo GPT image generation failed for ${messageId}: ${error ?? status}`);
+    }
+    if (isCompletedStatus(status)) {
+      throw new Error(`Mivo GPT image generation completed for ${messageId} but returned no image`);
+    }
+    await sleep(pollIntervalMs);
+  }
+  throw new Error(`Mivo GPT image generation timed out for ${messageId} after ${timeoutMs}ms`);
+}
+
+async function materializeArtifact(
+  cli: MivoCliClient,
+  artifact: MivoImageArtifact,
+  projectRoot: string,
+  messageId: string,
+  downloadRemoteUrl: (url: string, savePath: string) => Promise<void>,
+): Promise<string> {
+  const outputDir = path.join(projectRoot, ".canvas-mcp", "mivo");
+  await mkdir(outputDir, { recursive: true });
+  const imagePath = path.join(outputDir, `${safeFileName(messageId)}.png`);
+  if (artifact.fileId) {
+    await cli.downloadFile(artifact.fileId, imagePath);
+    return imagePath;
+  }
+  if (artifact.url) {
+    await downloadRemoteUrl(artifact.url, imagePath);
+    return imagePath;
+  }
+  throw new Error(`Mivo GPT image generation returned an image artifact without file id or URL for ${messageId}`);
+}
+
+async function markNodeFailed(
+  ctx: BoardToolContext,
+  projectRoot: string,
+  nodeId: string,
+  error: unknown,
+  messageId: string | null,
+): Promise<void> {
+  try {
+    await ctx.tools.call("canvas.update_nodes", {
+      projectRoot,
+      updates: [
+        {
+          id: nodeId,
+          name: "Failed: GPT image",
+          options: {
+            mivo: {
+              status: "failed",
+              messageId,
+              error: errorMessage(error),
+            },
+          },
+        },
+      ],
+    });
+  } catch {
+    // Keep the original generation error as the caller-facing failure.
+  }
+}
+
+function findDetailItem(items: MivoMessageDetailBatchItem[], messageId: string): MivoMessageDetailBatchItem {
+  const item = items.find((entry) => entry.message_id === messageId) ?? items[0];
+  if (!item) {
+    throw new Error(`Mivo detail-batch returned no result for ${messageId}`);
+  }
+  if (item.ok === false || item.error) {
+    throw new Error(`Mivo detail-batch failed for ${messageId}: ${item.error ?? "unknown error"}`);
+  }
+  return item;
+}
+
+function readMessageResult(item: MivoMessageDetailBatchItem): MivoMessageResult {
+  if (!item.message || typeof item.message !== "object") {
+    throw new Error("Mivo detail-batch result did not include a message object");
+  }
+  return item.message;
+}
+
+function normalizeStatus(status: unknown): string {
+  return typeof status === "string" ? status.toLowerCase() : "";
+}
+
+function isFailedStatus(status: string): boolean {
+  return ["failed", "failure", "error", "errored", "canceled", "cancelled"].includes(status);
+}
+
+function isCompletedStatus(status: string): boolean {
+  return ["completed", "complete", "success", "succeeded"].includes(status);
+}
+
+function readCreatedNodeId(result: NodesAssetsResult): string {
+  const nodeId = result.nodes[0]?.id;
+  if (typeof nodeId !== "string" || nodeId.trim() === "") {
+    throw new Error("canvas.create_nodes did not return a created node id");
+  }
+  return nodeId;
+}
+
+function readInput(input: unknown): CreateGptImageInput {
+  const record = asRecord(input);
+  const projectRoot = readString(record, "projectRoot");
+  const prompt = readString(record, "prompt");
+  const ratio = readOptionalRatio(record.ratio);
+  const referenceFileIds = readOptionalStringArray(record.referenceFileIds, "referenceFileIds");
+  const timeoutMs = readOptionalPositiveNumber(record.timeoutMs, "timeoutMs") ?? DEFAULT_TIMEOUT_MS;
+  const pollIntervalMs = readOptionalPositiveNumber(record.pollIntervalMs, "pollIntervalMs") ?? DEFAULT_POLL_INTERVAL_MS;
+  return {
+    projectRoot,
+    prompt,
+    ratio,
+    name: readOptionalString(record.name, "name"),
+    referenceFileIds,
+    timeoutMs,
+    pollIntervalMs,
+  };
+}
+
+function readOptionalRatio(value: unknown): Ratio {
+  if (value === undefined) return DEFAULT_RATIO;
+  if (typeof value !== "string" || !RATIOS.includes(value as Ratio)) {
+    throw new Error(`ratio must be one of ${RATIOS.join(", ")}`);
+  }
+  return value as Ratio;
+}
+
+function readOptionalStringArray(value: unknown, label: string): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an array`);
+  }
+  return value.map((entry, index) => {
+    if (typeof entry !== "string" || entry.trim() === "") {
+      throw new Error(`${label}[${index}] must be a non-empty string`);
+    }
+    return entry;
+  });
+}
+
+function readOptionalPositiveNumber(value: unknown, label: string): number | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    throw new Error(`${label} must be a positive finite number`);
+  }
+  return value;
+}
+
+function readOptionalString(value: unknown, label: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return value;
+}
+
+function readString(record: Record<string, unknown>, key: string): string {
+  const value = record[key];
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${key} must be a non-empty string`);
+  }
+  return value;
+}
+
+function defaultNodeName(prompt: string): string {
+  const normalized = prompt.replace(/\s+/g, " ").trim();
+  const suffix = normalized.length > 48 ? `${normalized.slice(0, 48)}...` : normalized;
+  return `GPT image: ${suffix}`;
+}
+
+function safeFileName(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]/g, "_") || `mivo-${Date.now()}`;
+}
+
+function objectSchema(properties: Record<string, unknown>, required: string[]): JSONSchema {
+  return {
+    type: "object",
+    additionalProperties: false,
+    required,
+    properties,
+  };
+}
+
+function stringSchema(description: string): JSONSchema {
+  return { type: "string", description };
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("input must be an object");
+  }
+  return value as Record<string, unknown>;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/mivoCli.ts

@@ -0,0 +1,173 @@
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const DEFAULT_API_BASE = "https://aigc.xindong.com/api/v1";
+const URL_KEYS = ["signUrl", "sign_url", "url", "uri", "displayUrl", "fileUrl", "downloadUrl", "src", "image"];
+const ID_KEYS = ["fileId", "file_id", "object_id", "_id"];
+
+export type MivoCliClient = {
+  ensureReady(): Promise<void>;
+  getChatSessionId(chatType: string): Promise<string>;
+  submitMessage(payload: Record<string, unknown>): Promise<string>;
+  detailBatch(messageIds: string[]): Promise<MivoMessageDetailBatchItem[]>;
+  downloadFile(fileId: string, savePath: string): Promise<void>;
+};
+
+export type MivoMessageDetailBatchItem = {
+  message_id?: string;
+  ok?: boolean;
+  error?: string | null;
+  message?: MivoMessageResult;
+};
+
+export type MivoMessageResult = {
+  status?: string;
+  error?: string | null;
+  content?: {
+    status?: string;
+    error?: string | null;
+    images?: unknown[];
+  };
+};
+
+export type MivoImageArtifact = {
+  fileId?: string;
+  url?: string;
+};
+
+export function createMivoCliClient(env: NodeJS.ProcessEnv = process.env): MivoCliClient {
+  const command = env.MIVO_CLI_PATH?.trim() || "mivo-cli";
+  let ready = false;
+
+  async function run(args: string[], options?: { input?: string }): Promise<unknown> {
+    const { stdout } = await execFileAsync(command, args, {
+      env: {
+        ...process.env,
+        ...env,
+      },
+      input: options?.input,
+      maxBuffer: 10 * 1024 * 1024,
+    });
+    return parseJson(stdout);
+  }
+
+  return {
+    async ensureReady() {
+      if (ready) return;
+      const apiKey = env.MIVO_API_KEY?.trim();
+      if (apiKey) {
+        await run(["config", "set", "api_base", env.MIVO_API_BASE?.trim() || DEFAULT_API_BASE, "--json"]);
+        await run(["login", "--key", apiKey, "--json"]);
+      }
+      ready = true;
+    },
+    async getChatSessionId(chatType) {
+      await this.ensureReady();
+      const value = await run(["message", "chat", "--type", chatType, "--json"]);
+      const record = asRecord(value, "message chat output");
+      const chatSessionId = readStringFromAny(record, ["chatSessionId", "chat_session_id", "id"]);
+      if (!chatSessionId) {
+        throw new Error("mivo-cli message chat did not return a chat session id");
+      }
+      return chatSessionId;
+    },
+    async submitMessage(payload) {
+      await this.ensureReady();
+      const dir = await mkdtemp(path.join(os.tmpdir(), "pixi-board-mivo-"));
+      const payloadPath = path.join(dir, `message-${Date.now()}-${Math.random().toString(16).slice(2)}.json`);
+      await writeFile(payloadPath, JSON.stringify(payload), "utf8");
+      const value = await run(["message", "submit", "--file", payloadPath, "--no-wait", "--json"]);
+      const record = asRecord(value, "message submit output");
+      const messageId = readStringFromAny(record, ["messageId", "message_id", "id"]);
+      if (!messageId) {
+        throw new Error("mivo-cli message submit did not return a message id");
+      }
+      return messageId;
+    },
+    async detailBatch(messageIds) {
+      await this.ensureReady();
+      const value = await run(["message", "detail-batch", ...messageIds, "--json"]);
+      if (Array.isArray(value)) {
+        return value as MivoMessageDetailBatchItem[];
+      }
+      const record = asRecord(value, "message detail-batch output");
+      if (Array.isArray(record.messages)) {
+        return record.messages as MivoMessageDetailBatchItem[];
+      }
+      if (Array.isArray(record.results)) {
+        return record.results as MivoMessageDetailBatchItem[];
+      }
+      if (Array.isArray(record.data)) {
+        return record.data as MivoMessageDetailBatchItem[];
+      }
+      throw new Error("mivo-cli message detail-batch returned an unsupported JSON shape");
+    },
+    async downloadFile(fileId, savePath) {
+      await this.ensureReady();
+      await mkdir(path.dirname(savePath), { recursive: true });
+      await run(["file", "download", fileId, savePath, "--json"]);
+    },
+  };
+}
+
+export function extractImageArtifact(message: MivoMessageResult): MivoImageArtifact | null {
+  const image = message.content?.images?.[0];
+  if (image === undefined || image === null) return null;
+  if (typeof image === "string") {
+    if (/^https?:\/\//i.test(image)) return { url: image };
+    return { fileId: image };
+  }
+  if (!isRecord(image)) return null;
+  const url = readStringFromAny(image, URL_KEYS);
+  const fileId = readStringFromAny(image, ID_KEYS);
+  if (!url && !fileId) return null;
+  return { fileId, url };
+}
+
+export function mivoFileUrl(fileId: string): string {
+  return `${DEFAULT_API_BASE}/file/image/${encodeURIComponent(fileId)}`;
+}
+
+export async function downloadUrl(url: string, savePath: string): Promise<void> {
+  await mkdir(path.dirname(savePath), { recursive: true });
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to download Mivo image URL: ${response.status} ${response.statusText}`);
+  }
+  const buffer = Buffer.from(await response.arrayBuffer());
+  await writeFile(savePath, buffer);
+}
+
+function parseJson(stdout: string): unknown {
+  try {
+    return JSON.parse(stdout);
+  } catch (error) {
+    throw new Error(`mivo-cli returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function readStringFromAny(record: Record<string, unknown>, keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim() !== "") {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+function asRecord(value: unknown, label: string): Record<string, unknown> {
+  if (!isRecord(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}