画布JSON处理工具（免费版）

本工具用于创建、编辑和校验符合JSON Canvas 1.0规范的.canvas文件，帮助AI Agent在没有图形界面的情况下，也能精确操作可视化画布的结构化数据。

概述

JSON Canvas是一种开放的结构化画布格式，文件本质为JSON，顶层包含nodes（节点数组）与edges（边数组）两个可选字段。本工具围绕该规范提供完整的指令集，覆盖从零创建画布、增量追加节点、连接节点、编辑属性到完整校验的全流程。

核心能力

节点操作

• 支持四种节点类型：文本节点（text）、文件节点（file）、链接节点（link）、分组节点（group）
• 自动生成16位十六进制唯一ID，避免碰撞
• 自动坐标布局，按建议尺寸表分配位置，避免重叠
• 支持颜色预设（1-6）与十六进制自定义色

输入: 用户提供节点操作所需的指令和必要参数。 处理: 解析节点操作的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回节点操作的响应数据,包含状态码、结果和日志。

边操作

• 通过fromNode/toNode引用节点ID建立连接
• 支持锚点方向（top/right/bottom/left）与箭头样式
• 支持边标签、颜色定制

输入: 用户提供边操作所需的指令和必要参数。 处理: 解析边操作的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回边操作的响应数据,包含状态码、结果和日志。

校验能力

• 唯一ID校验（节点与边ID全局唯一）
• 引用完整性校验（fromNode/toNode必须指向已存在节点）
• 必填字段校验（按节点类型检查text/file/url等字段）
• JSON语法合法性校验

输入: 用户提供校验能力所需的指令和必要参数。 处理: 解析校验能力的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回校验能力的响应数据,包含状态码、结果和日志。 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：Canvas、文件的轻量级处理、支持节点、分组的创建与编辑、处理工具专注于、规范文件的读写、校验与维护、适用于知识图谱、思维导图、流程编排等可视化、核心能力、Use、when、需要数据分析、报表生成、统计洞察、数据可视化时使用、不适用于实时流数、据处理、适用于独立开发者、企业团队和自动化、工作流场景等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

使用流程

Step 1：创建空画布

输入格式

{
  "nodes": [],
  "edges": []
}

将上述内容写入my-canvas.canvas文件即可获得一个合法的空画布。

Step 2：添加首个文本节点

{
  "id": "6f0ad84f44ce9c17",
  "type": "text",
  "x": 0,
  "y": 0,
  "width": 400,
  "height": 200,
  "text": "# 欢迎使用\n\n这是**Markdown**内容。"
}

Step 3：连接两个节点

{
  "id": "0123456789abcdef",
  "fromNode": "6f0ad84f44ce9c17",
  "fromSide": "right",
  "toNode": "a1b2c3d4e5f67890",
  "toSide": "left",
  "toEnd": "arrow",
  "label": "指向"
}

响应解析: 完成完成后,查看输出响应确认任务状态。成功时输出包含解析摘要和响应数据;失败时根据错误信息排查问题,查阅错误解析章节获取恢复步骤。

示例

节点属性速查表

布局尺寸建议

颜色预设对照

最佳实践

ID生成规范

始终生成16位小写十六进制字符串作为ID。建议使用时间戳与随机数组合，例如timestamp_hex + random_hex，确保跨会话唯一性。

坐标布局原则

• 坐标可为负数，画布无限延伸
• x向右递增，y向下递增，位置为左上角
• 节点间距保持50-100像素，分组内留20-50像素内边距
• 建议对齐到10或20的倍数，获得更整洁的布局

换行符陷阱处理

在JSON字符串中使用\n表示换行，不要使用字面量\\n，否则会被渲染为反斜杠加字母n。

增量编辑流程

1. 读取并解析现有.canvas文件
2. 生成不与现有ID冲突的新ID
3. 选择不与现有节点重叠的坐标
4. 追加新节点到nodes数组
5. 可选添加边连接新节点
6. 重新校验所有ID唯一性与边引用完整性

常见问题

Q1：编辑后画布显示空白怎么办？

A：优先检查JSON语法合法性，再校验所有fromNode/toNode是否引用了已存在的节点ID。悬空引用是导致渲染失败的最常见原因。

Q2：节点ID冲突如何排查？

A：对nodes和edges两个数组的所有id字段做去重统计，重复项即为冲突源。建议在追加节点前先建立现有ID的集合索引。

Q3：文本节点的Markdown不生效？

A：确认换行符使用的是\n而非\\n，并检查Markdown语法是否被JSON转义破坏。例如双星号**在JSON中无需转义，但反斜杠必须写成\\。

Q4：分组节点如何包含子节点？

A：分组节点本身不维护子节点列表，而是通过坐标范围实现视觉包含。将子节点的x/y设置在分组节点的边界内即可。

Q5：颜色预设对应的实际颜色不一致？

A：颜色预设值（1-6）的具体RGB由渲染应用自定义，不同应用可能呈现不同色相。如需精确控制，使用十六进制颜色值如"#FF5733"。

校验清单

完成画布创建或编辑后，逐项核对：

1. 所有id在节点与边中全局唯一
2. 每条边的fromNode与toNode均指向已存在节点
3. 各节点类型的必填字段齐全（text节点有text，file节点有file，link节点有url）
4. type取值属于text/file/link/group
5. fromSide/toSide取值属于top/right/bottom/left
6. fromEnd/toEnd取值属于none/arrow
7. 颜色预设为1-6或合法十六进制
8. JSON整体可被解析器正确解析

已知限制

本免费体验版限制以下高级功能：

• 批量节点处理（单次操作>10个节点）
• 画布模板库与一键套用
• 跨画布合并与差异对比
• 自动布局算法（力导向/树形/层次）
• 引用完整性的智能修复建议

解锁全部功能请使用专业版：canvas-json-handler-pro

• 当前为免费版本,如需完整功能请升级到付费版获取全部能力

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux
• JSON解析: 任意支持JSON.parse的运行时（Node.js / Python / 浏览器）

依赖详情

API Key 配置

• 本skill基于Markdown指令规范，无需额外API Key
• 若需对接外部渲染服务，按对应服务文档配置

可用性分类

• 分类: MD+EXEC（纯Markdown指令，部分功能需要exec命令行执行能力）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent执行画布文件的读写与校验任务

错误处理

输出格式

{
  "success": true,
  "data": {
    "result": "画布JSON处理免费版处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "canvas json handler"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}