@mce/ai 0.24.4

package/dist/aiActions.d.ts

@@ -0,0 +1,102 @@
+/**
+ * AI 画布 Agent 的「带类型 action schema」层（参考 tldraw AI SDK 范式）。
+ *
+ * LLM 不直接改像素，而是产出一组结构化 action；本模块负责**校验 / 清洗**——
+ * 拒绝结构非法项、丢弃不存在的节点 id、强制数值有限——再交由插件在单个 undo 事务内
+ * 映射到现有 exec 命令执行。校验是纯函数，无编辑器耦合，可独立单测。
+ */
+export declare const AI_ALIGN_DIRECTIONS: readonly ["left", "horizontal-center", "right", "top", "vertical-center", "bottom"];
+export type AiAlignDirection = typeof AI_ALIGN_DIRECTIONS[number];
+export type AiAction = {
+    type: 'createText';
+    text: string;
+    x?: number;
+    y?: number;
+    style?: Record<string, any>;
+} | {
+    type: 'createShape';
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    fill?: string;
+    path?: string;
+} | {
+    type: 'setStyle';
+    id: string;
+    style: Record<string, any>;
+} | {
+    type: 'move';
+    id: string;
+    x: number;
+    y: number;
+} | {
+    type: 'delete';
+    ids: string[];
+} | {
+    type: 'select';
+    ids: string[];
+} | {
+    type: 'duplicate';
+    ids: string[];
+} | {
+    type: 'align';
+    direction: AiAlignDirection;
+    ids?: string[];
+};
+export interface AiActionError {
+    index: number;
+    reason: string;
+}
+export interface AiValidationResult {
+    actions: AiAction[];
+    errors: AiActionError[];
+}
+/**
+ * 校验并清洗一批 AI action。
+ * @param input 任意（通常是 LLM 输出解析后的 JSON）。
+ * @param hasNode 判定某节点 id 是否存在于当前文档；默认全部存在（便于纯逻辑测试）。
+ */
+export declare function validateAiActions(input: unknown, hasNode?: (id: string) => boolean): AiValidationResult;
+/**
+ * 供 LLM 提示的 action schema 描述（JSON 可序列化）。消费方把它喂给模型，
+ * 模型据此产出 action 数组，再经 validateAiActions 校验后由 applyAiActions 执行。
+ */
+export declare const AI_ACTION_SCHEMA: {
+    readonly createText: {
+        readonly text: "string (required)";
+        readonly x: "number?";
+        readonly y: "number?";
+        readonly style: "object?";
+    };
+    readonly createShape: {
+        readonly x: "number?";
+        readonly y: "number?";
+        readonly width: "number?";
+        readonly height: "number?";
+        readonly fill: "string?";
+        readonly path: "svg path data string?";
+    };
+    readonly setStyle: {
+        readonly id: "string (required, existing node)";
+        readonly style: "object (required)";
+    };
+    readonly move: {
+        readonly id: "string (required, existing node)";
+        readonly x: "number (required)";
+        readonly y: "number (required)";
+    };
+    readonly delete: {
+        readonly ids: "string[] (required, existing nodes)";
+    };
+    readonly select: {
+        readonly ids: "string[] (required, existing nodes)";
+    };
+    readonly duplicate: {
+        readonly ids: "string[] (required, existing nodes)";
+    };
+    readonly align: {
+        readonly direction: readonly ["left", "horizontal-center", "right", "top", "vertical-center", "bottom"];
+        readonly ids: "string[]? (defaults to current selection)";
+    };
+};

package/dist/aiActions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { plugin } from './plugin';
+export * from './aiActions';
+export * from './plugin';
+export default plugin;

package/dist/index.js

@@ -0,0 +1,295 @@
+import { createShapeElement, definePlugin } from "mce";
+//#region src/aiActions.ts
+/**
+* AI 画布 Agent 的「带类型 action schema」层（参考 tldraw AI SDK 范式）。
+*
+* LLM 不直接改像素，而是产出一组结构化 action；本模块负责**校验 / 清洗**——
+* 拒绝结构非法项、丢弃不存在的节点 id、强制数值有限——再交由插件在单个 undo 事务内
+* 映射到现有 exec 命令执行。校验是纯函数，无编辑器耦合，可独立单测。
+*/
+var AI_ALIGN_DIRECTIONS = [
+	"left",
+	"horizontal-center",
+	"right",
+	"top",
+	"vertical-center",
+	"bottom"
+];
+function isObject(v) {
+	return !!v && typeof v === "object" && !Array.isArray(v);
+}
+function finiteNumber(v) {
+	return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+}
+function sanitizeIds(ids, hasNode) {
+	if (!Array.isArray(ids)) return [];
+	return ids.filter((id) => typeof id === "string" && hasNode(id));
+}
+/**
+* 校验并清洗一批 AI action。
+* @param input 任意（通常是 LLM 输出解析后的 JSON）。
+* @param hasNode 判定某节点 id 是否存在于当前文档；默认全部存在（便于纯逻辑测试）。
+*/
+function validateAiActions(input, hasNode = () => true) {
+	const actions = [];
+	const errors = [];
+	(Array.isArray(input) ? input : []).forEach((raw, index) => {
+		if (!isObject(raw)) {
+			errors.push({
+				index,
+				reason: "不是合法对象"
+			});
+			return;
+		}
+		switch (raw.type) {
+			case "createText":
+				if (typeof raw.text !== "string" || raw.text === "") {
+					errors.push({
+						index,
+						reason: "createText 需要非空 text"
+					});
+					return;
+				}
+				actions.push({
+					type: "createText",
+					text: raw.text,
+					x: finiteNumber(raw.x),
+					y: finiteNumber(raw.y),
+					style: isObject(raw.style) ? raw.style : void 0
+				});
+				return;
+			case "createShape":
+				actions.push({
+					type: "createShape",
+					x: finiteNumber(raw.x),
+					y: finiteNumber(raw.y),
+					width: finiteNumber(raw.width),
+					height: finiteNumber(raw.height),
+					fill: typeof raw.fill === "string" ? raw.fill : void 0,
+					path: typeof raw.path === "string" ? raw.path : void 0
+				});
+				return;
+			case "setStyle":
+				if (typeof raw.id !== "string" || !hasNode(raw.id)) {
+					errors.push({
+						index,
+						reason: `setStyle 引用了不存在的 id: ${String(raw.id)}`
+					});
+					return;
+				}
+				if (!isObject(raw.style)) {
+					errors.push({
+						index,
+						reason: "setStyle 需要 style 对象"
+					});
+					return;
+				}
+				actions.push({
+					type: "setStyle",
+					id: raw.id,
+					style: raw.style
+				});
+				return;
+			case "move": {
+				if (typeof raw.id !== "string" || !hasNode(raw.id)) {
+					errors.push({
+						index,
+						reason: `move 引用了不存在的 id: ${String(raw.id)}`
+					});
+					return;
+				}
+				const x = finiteNumber(raw.x);
+				const y = finiteNumber(raw.y);
+				if (x === void 0 || y === void 0) {
+					errors.push({
+						index,
+						reason: "move 需要有限数值 x, y"
+					});
+					return;
+				}
+				actions.push({
+					type: "move",
+					id: raw.id,
+					x,
+					y
+				});
+				return;
+			}
+			case "delete":
+			case "select":
+			case "duplicate": {
+				const ids = sanitizeIds(raw.ids, hasNode);
+				if (ids.length === 0) {
+					errors.push({
+						index,
+						reason: `${raw.type} 需要至少一个存在的 id`
+					});
+					return;
+				}
+				actions.push({
+					type: raw.type,
+					ids
+				});
+				return;
+			}
+			case "align":
+				if (!AI_ALIGN_DIRECTIONS.includes(raw.direction)) {
+					errors.push({
+						index,
+						reason: `align 的 direction 非法: ${String(raw.direction)}`
+					});
+					return;
+				}
+				actions.push({
+					type: "align",
+					direction: raw.direction,
+					ids: raw.ids === void 0 ? void 0 : sanitizeIds(raw.ids, hasNode)
+				});
+				return;
+			default: errors.push({
+				index,
+				reason: `未知 action 类型: ${String(raw.type)}`
+			});
+		}
+	});
+	return {
+		actions,
+		errors
+	};
+}
+/**
+* 供 LLM 提示的 action schema 描述（JSON 可序列化）。消费方把它喂给模型，
+* 模型据此产出 action 数组，再经 validateAiActions 校验后由 applyAiActions 执行。
+*/
+var AI_ACTION_SCHEMA = {
+	createText: {
+		text: "string (required)",
+		x: "number?",
+		y: "number?",
+		style: "object?"
+	},
+	createShape: {
+		x: "number?",
+		y: "number?",
+		width: "number?",
+		height: "number?",
+		fill: "string?",
+		path: "svg path data string?"
+	},
+	setStyle: {
+		id: "string (required, existing node)",
+		style: "object (required)"
+	},
+	move: {
+		id: "string (required, existing node)",
+		x: "number (required)",
+		y: "number (required)"
+	},
+	delete: { ids: "string[] (required, existing nodes)" },
+	select: { ids: "string[] (required, existing nodes)" },
+	duplicate: { ids: "string[] (required, existing nodes)" },
+	align: {
+		direction: AI_ALIGN_DIRECTIONS,
+		ids: "string[]? (defaults to current selection)"
+	}
+};
+//#endregion
+//#region src/plugin.ts
+function plugin() {
+	return definePlugin((editor) => {
+		const { root, getNodeById, addElement, selection, exec } = editor;
+		/** 收集当前文档所有节点 id，用于校验 action 引用的 id 是否存在。 */
+		function collectIds() {
+			const ids = /* @__PURE__ */ new Set();
+			root.value?.findOne((node) => {
+				ids.add(node.id);
+				return false;
+			});
+			return ids;
+		}
+		function findById(id) {
+			return getNodeById(id);
+		}
+		function selectByIds(ids) {
+			selection.value = ids.map(findById).filter((n) => Boolean(n));
+		}
+		function applyAiActions(input) {
+			const ids = collectIds();
+			const { actions, errors } = validateAiActions(input, (id) => ids.has(id));
+			const created = [];
+			actions.forEach((action) => {
+				switch (action.type) {
+					case "createText": {
+						const el = exec("addTextElement", {
+							content: action.text,
+							style: {
+								left: action.x ?? 0,
+								top: action.y ?? 0,
+								...action.style
+							}
+						});
+						created.push(el.id);
+						break;
+					}
+					case "createShape": {
+						const el = addElement(createShapeElement(action.path ? [{ data: action.path }] : void 0, action.fill), { position: {
+							x: action.x ?? 0,
+							y: action.y ?? 0
+						} });
+						if (action.width !== void 0) el.style.width = action.width;
+						if (action.height !== void 0) el.style.height = action.height;
+						created.push(el.id);
+						break;
+					}
+					case "setStyle": {
+						const node = findById(action.id);
+						if (node?.style) Object.assign(node.style, action.style);
+						break;
+					}
+					case "move": {
+						const node = findById(action.id);
+						if (node?.style) {
+							node.style.left = action.x;
+							node.style.top = action.y;
+						}
+						break;
+					}
+					case "select":
+						selectByIds(action.ids);
+						break;
+					case "delete":
+						selectByIds(action.ids);
+						exec("delete");
+						break;
+					case "duplicate":
+						selectByIds(action.ids);
+						exec("duplicate");
+						break;
+					case "align":
+						if (action.ids) selectByIds(action.ids);
+						exec("align", action.direction);
+						break;
+				}
+			});
+			return {
+				created,
+				errors
+			};
+		}
+		return {
+			name: "mce:ai",
+			commands: [{
+				command: "applyAiActions",
+				handle: applyAiActions
+			}, {
+				command: "getAiActionSchema",
+				handle: () => AI_ACTION_SCHEMA
+			}]
+		};
+	});
+}
+//#endregion
+//#region src/index.ts
+var src_default = plugin;
+//#endregion
+export { AI_ACTION_SCHEMA, AI_ALIGN_DIRECTIONS, src_default as default, plugin, validateAiActions };

package/dist/plugin.d.ts

@@ -0,0 +1,22 @@
+import type { AiActionError } from './aiActions';
+import { AI_ACTION_SCHEMA } from './aiActions';
+declare global {
+    namespace Mce {
+        interface AiApplyResult {
+            /** 新建元素的 id（按动作顺序）。 */
+            created: string[];
+            /** 被校验拒绝的动作及原因。 */
+            errors: AiActionError[];
+        }
+        interface Commands {
+            /**
+             * 应用一批 AI action（通常来自 LLM 输出）。先校验/清洗，再在单个 undo 步骤内
+             * 映射到现有命令执行。非法项被跳过并在返回值的 errors 中报告。
+             */
+            applyAiActions: (actions: unknown) => AiApplyResult;
+            /** 返回供 LLM 提示的 action schema 描述。 */
+            getAiActionSchema: () => typeof AI_ACTION_SCHEMA;
+        }
+    }
+}
+export declare function plugin(): import("mce").Plugin;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@mce/ai",
+  "type": "module",
+  "version": "0.24.4",
+  "description": "AI plugin for mce",
+  "author": "wxm",
+  "license": "MIT",
+  "homepage": "https://github.com/qq15725/mce",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qq15725/mce.git"
+  },
+  "bugs": {
+    "url": "https://github.com/qq15725/mce/issues"
+  },
+  "keywords": [
+    "mce",
+    "ai",
+    "plugin"
+  ],
+  "sideEffects": true,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./*.mjs": "./*.js",
+    "./*": "./*"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "browser": "./dist/index.js",
+  "typings": "dist/index.d.ts",
+  "types": "dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "*",
+        "dist/*",
+        "dist/*.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "mce": "0.24.4"
+  },
+  "peerDependencies": {
+    "mce": "^0"
+  },
+  "scripts": {
+    "build:code": "vite build",
+    "build:tsc": "NODE_ENV=production tsc --emitDeclarationOnly --project tsconfig.json",
+    "build": "pnpm build:code && pnpm build:tsc",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit --project tsconfig.json"
+  }
+}