@artflo-ai/artflo-openclaw-plugin 0.0.10 → 0.0.12

package/dist/src/core/plan/validate-plan.js

@@ -8,18 +8,54 @@ const VALID_NODE_TYPES = new Set([
     'video',
     'batch',
 ]);
+/**
+ * Fallback map: canvas numeric node types → PlanDSL string types.
+ * LLMs sometimes emit raw canvas codes instead of the PlanDSL strings.
+ */
+const NUMERIC_TYPE_MAP = {
+    100000: 'process', // EDGE — unlikely but safe fallback
+    110000: 'input',
+    110001: 'image',
+    110004: 'video',
+    110006: 'selector',
+    130000: 'process',
+    130500: 'refine',
+    190000: 'crop',
+};
 function isRecord(value) {
     return typeof value === 'object' && value !== null;
 }
+/**
+ * Attempt to coerce a raw node type (number or unknown string) into a valid
+ * PlanDSL NodeType.  Returns the mapped type or `null` if unrecoverable.
+ */
+function coerceNodeType(raw) {
+    if (typeof raw === 'string') {
+        const lower = raw.toLowerCase().trim();
+        if (VALID_NODE_TYPES.has(lower)) {
+            return lower;
+        }
+        // Try parsing stringified number ("110000")
+        const num = Number(lower);
+        if (!Number.isNaN(num) && NUMERIC_TYPE_MAP[num]) {
+            return NUMERIC_TYPE_MAP[num];
+        }
+        return null;
+    }
+    if (typeof raw === 'number' && NUMERIC_TYPE_MAP[raw]) {
+        return NUMERIC_TYPE_MAP[raw];
+    }
+    return null;
+}
 export function parsePlanV2(value) {
     if (!isRecord(value)) {
-        throw new Error('Plan must be an object');
+        throw new Error('Plan must be an object. See artflo_canvas SKILL.md for the PlanDSL V2 schema.');
     }
     if (!Array.isArray(value.nodes)) {
-        throw new Error('Plan nodes must be an array');
+        throw new Error('Plan nodes must be an array. See artflo_canvas SKILL.md for the PlanDSL V2 schema.');
     }
     if (!Array.isArray(value.edges)) {
-        throw new Error('Plan edges must be an array');
+        throw new Error('Plan edges must be an array. See artflo_canvas SKILL.md for the PlanDSL V2 schema.');
     }
     const nodes = value.nodes.map((node, index) => parseNodeSpec(node, index));
     const edges = value.edges.map((edge, index) => parseEdgeSpec(edge, index));
@@ -44,15 +80,25 @@ function parseNodeSpec(value, index) {
     if (!isRecord(value)) {
         throw new Error(`Node at index ${index} must be an object`);
     }
-    if (typeof value.ref !== 'string' || value.ref.length === 0) {
+    // Accept "ref" or fall back to "id" (canvas format)
+    const ref = typeof value.ref === 'string' && value.ref.length > 0
+        ? value.ref
+        : typeof value.id === 'string' && value.id.length > 0
+            ? value.id
+            : '';
+    if (ref.length === 0) {
         throw new Error(`Node at index ${index} is missing ref`);
     }
-    if (typeof value.type !== 'string' || !VALID_NODE_TYPES.has(value.type)) {
-        throw new Error(`Node ${value.ref} has invalid type`);
+    const resolvedType = coerceNodeType(value.type);
+    if (!resolvedType) {
+        throw new Error(`Node ${ref} has invalid type "${String(value.type)}". ` +
+            `Valid types: ${[...VALID_NODE_TYPES].join(', ')}. ` +
+            `Do NOT use numeric canvas types (110000, 130000, etc.). ` +
+            `See artflo_canvas SKILL.md for the PlanDSL V2 schema.`);
     }
     return {
-        ref: value.ref,
-        type: value.type,
+        ref,
+        type: resolvedType,
         data: isRecord(value.data) ? value.data : {},
         dependsOn: typeof value.dependsOn === 'string' ? value.dependsOn : undefined,
     };
@@ -61,15 +107,31 @@ function parseEdgeSpec(value, index) {
     if (!isRecord(value)) {
         throw new Error(`Edge at index ${index} must be an object`);
     }
-    if (typeof value.from !== 'string' || typeof value.to !== 'string') {
-        throw new Error(`Edge at index ${index} must include from and to`);
+    // Accept "from"/"to" or fall back to "source"/"target" (canvas format)
+    const from = typeof value.from === 'string'
+        ? value.from
+        : typeof value.source === 'string'
+            ? value.source
+            : '';
+    const to = typeof value.to === 'string'
+        ? value.to
+        : typeof value.target === 'string'
+            ? value.target
+            : '';
+    if (from.length === 0 || to.length === 0) {
+        throw new Error(`Edge at index ${index} must include from and to. ` +
+            `See artflo_canvas SKILL.md for the PlanDSL V2 schema.`);
     }
     return {
         ref: typeof value.ref === 'string' ? value.ref : undefined,
-        from: value.from,
-        to: value.to,
-        fromHandle: typeof value.fromHandle === 'string' ? value.fromHandle : undefined,
-        toHandle: typeof value.toHandle === 'string' ? value.toHandle : undefined,
+        from,
+        to,
+        fromHandle: typeof value.fromHandle === 'string' ? value.fromHandle
+            : typeof value.sourceHandle === 'string' ? value.sourceHandle
+                : undefined,
+        toHandle: typeof value.toHandle === 'string' ? value.toHandle
+            : typeof value.targetHandle === 'string' ? value.targetHandle
+                : undefined,
     };
 }
 export function validateAndFixPlan(plan) {

package/dist/src/tools/register-tools.js

@@ -27,7 +27,7 @@ export function registerArtfloTools(api, context) {
     api.registerTool({
         name: ARTFLO_TOOL_NAMES.getNode,
         label: 'Artflo Canvas Get Node',
-        description: 'Read one node or edge from the current Artflo canvas session by id.',
+        description: '⚠️ Before using this tool, you MUST read the artflo_canvas SKILL.md for usage rules and constraints. Read one node or edge from the current Artflo canvas session by id.',
         parameters: Type.Object({
             canvasId: Type.String({ minLength: 1 }),
             id: Type.String({ minLength: 1 }),
@@ -52,7 +52,7 @@ export function registerArtfloTools(api, context) {
     api.registerTool({
         name: ARTFLO_TOOL_NAMES.connect,
         label: 'Artflo Canvas Connect',
-        description: 'Register or warm a direct Artflo canvas WebSocket session for a canvas id using preconfigured plugin credentials.',
+        description: '⚠️ Before using this tool, you MUST read the artflo_canvas SKILL.md for usage rules and constraints. Register or warm a direct Artflo canvas WebSocket session for a canvas id using preconfigured plugin credentials.',
         parameters: Type.Object({
             canvasId: Type.String({ minLength: 1 }),
         }),
@@ -79,7 +79,7 @@ export function registerArtfloTools(api, context) {
     api.registerTool({
         name: ARTFLO_TOOL_NAMES.connectionStatus,
         label: 'Artflo Canvas Connection Status',
-        description: 'Inspect current plugin-level Artflo WebSocket session state and config readiness.',
+        description: '⚠️ Before using this tool, you MUST read the artflo_canvas SKILL.md for usage rules and constraints. Inspect current plugin-level Artflo WebSocket session state and config readiness.',
         parameters: Type.Object({
             canvasId: Type.Optional(Type.String()),
         }),
@@ -107,7 +107,7 @@ export function registerArtfloTools(api, context) {
     api.registerTool({
         name: ARTFLO_TOOL_NAMES.getState,
         label: 'Artflo Canvas State',
-        description: 'Return scaffold plugin state and planned runtime capabilities for Artflo execution.',
+        description: '⚠️ Before using this tool, you MUST read the artflo_canvas SKILL.md for usage rules and constraints. Return scaffold plugin state and planned runtime capabilities for Artflo execution.',
         parameters: Type.Object({
             canvasId: Type.Optional(Type.String()),
         }),
@@ -143,7 +143,7 @@ export function registerArtfloTools(api, context) {
     api.registerTool({
         name: ARTFLO_TOOL_NAMES.getConfig,
         label: 'Artflo Canvas Get Config',
-        description: 'Return available models, subscription status, and prompt refine categories for the connected canvas. Call this before planning a workflow so you know which models and resolutions are available.',
+        description: '⚠️ Before using this tool, you MUST read the artflo_canvas SKILL.md for usage rules and constraints. Return available models, subscription status, and prompt refine categories for the connected canvas. Call this before planning a workflow so you know which models and resolutions are available.',
         parameters: Type.Object({
             canvasId: Type.String({ minLength: 1 }),
         }),
@@ -179,7 +179,7 @@ export function registerArtfloTools(api, context) {
     api.registerTool({
         name: ARTFLO_TOOL_NAMES.findNodes,
         label: 'Artflo Canvas Find Nodes',
-        description: 'Find nodes or edges in the connected Artflo canvas by ids, type, status, label text, or runnable state.',
+        description: '⚠️ Before using this tool, you MUST read the artflo_canvas SKILL.md for usage rules and constraints. Find nodes or edges in the connected Artflo canvas by ids, type, status, label text, or runnable state.',
         parameters: Type.Object({
             canvasId: Type.String({ minLength: 1 }),
             ids: Type.Optional(Type.Array(Type.String())),
@@ -237,7 +237,7 @@ export function registerArtfloTools(api, context) {
     api.registerTool({
         name: ARTFLO_TOOL_NAMES.changeElements,
         label: 'Artflo Canvas Change Elements',
-        description: 'Apply direct structured element changes to an existing Artflo canvas session.',
+        description: '⚠️ Before using this tool, you MUST read the artflo_canvas SKILL.md for usage rules and constraints. Apply direct structured element changes to an existing Artflo canvas session. Do NOT use this tool to create new workflows from scratch — use artflo_canvas_execute_plan instead.',
         parameters: Type.Object({
             canvasId: Type.String({ minLength: 1 }),
             changes: Type.Array(Type.Any(), { minItems: 1 }),
@@ -264,7 +264,7 @@ export function registerArtfloTools(api, context) {
     api.registerTool({
         name: ARTFLO_TOOL_NAMES.deleteElements,
         label: 'Artflo Canvas Delete Elements',
-        description: 'Delete nodes or edges from the current Artflo canvas session.',
+        description: '⚠️ Before using this tool, you MUST read the artflo_canvas SKILL.md for usage rules and constraints. Delete nodes or edges from the current Artflo canvas session.',
         parameters: Type.Object({
             canvasId: Type.String({ minLength: 1 }),
             ids: Type.Array(Type.String(), { minItems: 1 }),
@@ -289,7 +289,7 @@ export function registerArtfloTools(api, context) {
     api.registerTool({
         name: ARTFLO_TOOL_NAMES.runNodes,
         label: 'Artflo Canvas Run Nodes',
-        description: 'Run one or more executable Artflo nodes by id.',
+        description: '⚠️ Before using this tool, you MUST read the artflo_canvas SKILL.md for usage rules and constraints. Run one or more executable Artflo nodes by id.',
         parameters: Type.Object({
             canvasId: Type.String({ minLength: 1 }),
             ids: Type.Array(Type.String(), { minItems: 1 }),
@@ -314,7 +314,7 @@ export function registerArtfloTools(api, context) {
     api.registerTool({
         name: ARTFLO_TOOL_NAMES.waitForCompletion,
         label: 'Artflo Canvas Wait For Completion',
-        description: 'Wait for one or more executable nodes to reach completion status.',
+        description: '⚠️ Before using this tool, you MUST read the artflo_canvas SKILL.md for usage rules and constraints. Wait for one or more executable nodes to reach completion status.',
         parameters: Type.Object({
             canvasId: Type.String({ minLength: 1 }),
             ids: Type.Array(Type.String(), { minItems: 1 }),
@@ -341,7 +341,7 @@ export function registerArtfloTools(api, context) {
     api.registerTool({
         name: ARTFLO_TOOL_NAMES.executePlan,
         label: 'Artflo Execute Plan',
-        description: 'Execute a structured Artflo plan through deterministic runtime logic. In scaffold phase, validates request shape and returns the next integration milestone.',
+        description: '⚠️ Before using this tool, you MUST read the artflo_canvas SKILL.md for the PlanDSL V2 schema and valid node types. Execute a structured Artflo plan through deterministic runtime logic. Node types must be strings: "input", "process", "refine", "selector", "crop", "image", "video", "batch". Edges must use "from"/"to" fields (not "source"/"target"). Do NOT use numeric canvas types (110000, 130000, etc.).',
         parameters: Type.Object({
             canvasId: Type.String({ minLength: 1 }),
             plan: Type.Object({
@@ -410,7 +410,7 @@ export function registerArtfloTools(api, context) {
     api.registerTool({
         name: ARTFLO_TOOL_NAMES.createCanvas,
         label: 'Artflo Canvas Create',
-        description: 'Create a new Artflo canvas project. Returns the canvas id and project URL. Use this when no canvas id is available or the user requests a new canvas.',
+        description: '⚠️ Before using this tool, you MUST read the artflo_canvas SKILL.md for usage rules and constraints. Create a new Artflo canvas project. Returns the canvas id and project URL. Use this when no canvas id is available or the user requests a new canvas.',
         parameters: Type.Object({
             name: Type.Optional(Type.String({ description: 'Canvas name, defaults to "Untitled"' })),
         }),
@@ -436,7 +436,7 @@ export function registerArtfloTools(api, context) {
     api.registerTool({
         name: ARTFLO_TOOL_NAMES.getLastCanvas,
         label: 'Artflo Canvas Get Last',
-        description: 'Get the last used canvas id. Use this when user requests last used canvas.',
+        description: '⚠️ Before using this tool, you MUST read the artflo_canvas SKILL.md for usage rules and constraints. Get the last used canvas id. Use this when user requests last used canvas.',
         parameters: Type.Object({}),
         async execute(_id, params) {
             return runWithToolTrace(ARTFLO_TOOL_NAMES.getLastCanvas, params, async () => {
@@ -457,7 +457,7 @@ export function registerArtfloTools(api, context) {
     api.registerTool({
         name: ARTFLO_TOOL_NAMES.listModels,
         label: 'Artflo Canvas List Models',
-        description: 'List all available AI models. When presenting results to the user, you MUST show ALL of these fields in a table: ' +
+        description: '⚠️ Before using this tool, you MUST read the artflo_canvas SKILL.md for usage rules and constraints. List all available AI models. When presenting results to the user, you MUST show ALL of these fields in a table: ' +
             '1) Model name (use model_name, NEVER expose model_key to user) ' +
             '2) Credits (base price; if resolutionPricing exists, show per-resolution prices) ' +
             '3) Supported resolutions ' +
@@ -567,7 +567,7 @@ export function registerArtfloTools(api, context) {
     api.registerTool({
         name: ARTFLO_TOOL_NAMES.uploadFile,
         label: 'Artflo Upload File',
-        description: 'Upload a local file or a remote URL to Artflo OBS storage. Returns the CDN URL and object key. Use this to upload reference images before creating workflows with image-to-image or image-to-video nodes.',
+        description: '⚠️ Before using this tool, you MUST read the artflo_canvas SKILL.md for usage rules and constraints. Upload a local file or a remote URL to Artflo OBS storage. Returns the CDN URL and object key. Use this to upload reference images before creating workflows with image-to-image or image-to-video nodes.',
         parameters: Type.Object({
             source: Type.String({
                 description: 'Local file path or remote https URL to upload.',
@@ -592,7 +592,7 @@ export function registerArtfloTools(api, context) {
     api.registerTool({
         name: ARTFLO_TOOL_NAMES.getUserStatus,
         label: 'Artflo Get User Status',
-        description: 'Get the current user subscription plan and remaining credits. Does not require a canvas connection.',
+        description: '⚠️ Before using this tool, you MUST read the artflo_canvas SKILL.md for usage rules and constraints. Get the current user subscription plan and remaining credits. Does not require a canvas connection.',
         parameters: Type.Object({}),
         async execute(_id, params) {
             return runWithToolTrace(ARTFLO_TOOL_NAMES.getUserStatus, params, async () => {
@@ -621,7 +621,7 @@ export function registerArtfloTools(api, context) {
     api.registerTool({
         name: ARTFLO_TOOL_NAMES.setApiKey,
         label: 'Artflo Set Config',
-        description: 'Save Artflo plugin config (apiKey and/or env). Call this when the user provides their API Key or wants to switch environment. Both parameters are optional — only provided values will be updated.',
+        description: '⚠️ Before using this tool, you MUST read the artflo_canvas SKILL.md for usage rules and constraints. Save Artflo plugin config (apiKey and/or env). Call this when the user provides their API Key or wants to switch environment. Both parameters are optional — only provided values will be updated.',
         parameters: Type.Object({
             apiKey: Type.Optional(Type.String({ minLength: 1, description: 'Artflo API Key.' })),
             env: Type.Optional(Type.String({ enum: ['release', 'test'], description: 'Environment: release or test.' })),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artflo-ai/artflo-openclaw-plugin",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "type": "module",
   "description": "OpenClaw plugin that connects directly to Artflo canvas WebSocket runtime.",
   "keywords": [
@@ -13,6 +13,7 @@
   "files": [
     "README.md",
     "dist",
+    "!dist/logs",
     "openclaw.plugin.json",
     "skills",
     "package.json"

package/skills/artflo-canvas/SKILL.md

@@ -58,7 +58,7 @@ metadata:
 - 将插件配置视为 WebSocket 凭证和连接默认值的唯一真实来源。
 - **禁止编造 API URL**：不要自行拼接或猜测 Artflo API 路径。所有 API 交互必须通过插件提供的 tool 完成（如 `artflo_canvas_get_last`、`artflo_canvas_create`、`artflo_upload_file` 等）。不要使用 `fetch` 或 `curl` 直接调用 Artflo API。
 - **model_key 保密**：`model_key`（如 `Praline_2`、`ToffeeV1-Lite`）是内部标识，仅供构建 plan 使用。向用户展示模型时只使用 `model_name`（显示名称），绝不向用户暴露 `model_key`。
-- **资源保存路径**：画布生成完成后需要下载保存的资源（图片、视频等），必须保存到 `/artflo/outbound` 目录。不要使用 `/tmp` 或其他临时目录。
+- **资源保存路径**：画布生成完成后需要下载保存的资源（图片、视频等），必须保存到 `artflo/outbound` 目录。不要使用 `/tmp` 或其他临时目录。
 - **环境设置保密**：不要主动向用户提及或暴露环境切换功能（release/test）。只有当用户明确提到要切换环境、设置 test 环境时，才使用 `artflo_set_api_key` 的 `env` 参数。
 - **品牌名称规范**：产品名称是 **Artflo**（A 大写，其余小写）。不要写成 ArtFlo、ARTFLO、artFlo 或其他变体。所有面向用户的文字中必须使用正确的大小写。
 - **模型列表展示规范**：当用户查看模型列表时，必须展示以下字段，不要省略：
@@ -94,6 +94,7 @@ metadata:
 8. 调用 `artflo_canvas_execute_plan` 执行该 plan。
 9. 如果是检查现状，使用 `artflo_canvas_get_state`、`artflo_canvas_get_node` 或 `artflo_canvas_find_nodes`。
 10. 如果是定向修复，使用 `artflo_canvas_change_elements`、`artflo_canvas_delete_elements`、`artflo_canvas_run_nodes` 和 `artflo_canvas_wait_for_completion`。
+11. 生成成功必须告知用户源文件的资源链接，与生成文件分开发送
 
 ## 规划核心要点
 
@@ -137,19 +138,3 @@ metadata:
 4. 如果错误是 "invalid model"（error_code=402），说明选择的模型不可用。调用 `artflo_canvas_get_config` 确认可用模型列表，选择一个 `available: true` 的模型，然后 change + rerun。
 5. **绝对不要删除已成功执行的上游节点**。只修复出错的那个节点。
 6. 如果需要重建整个工作流分支，先向用户确认，不要自行决定。
-
-## Channel 适配规则
-
-向用户发送 Artflo 生成结果时，必须根据当前 Channel 的限制选择合适的发送方式。
-
-### 企业微信（WeCom）
-
-| 资源大小 | 发送方式 |
-|---------|---------|
-| 图片 ≤ 2 MB | 以图片形式发送 |
-| 图片 > 2 MB 且 ≤ 20 MB | 以文件形式发送 |
-| 文件 > 20 MB | 直接发送图片/文件的 URL 链接 |
-
-### 其他 Channel
-
-（待补充）