Canvas Json Handler Free

SKILL.md

---
slug: canvas-json-handler-free
name: canvas-json-handler-free
version: 1.0.0
displayName: 画布JSON处理免费版
summary: 面向JSON Canvas(.canvas)文件的轻量级处理工具，支持节点、边、分组的创建与编辑校验。
license: Proprietary
edition: free
description: 画布JSON处理工具专注于JSON Canvas规范文件的读写、校验与维护，适用于知识图谱、思维导图、流程编排等可视化场景。核心能力：遵循JSON
  Canvas 1。Use when 需要数据分析、报表生成、统计洞察、数据可视化时使用。不适用于实时流数据处理。适用于独立开发者、企业团队和自动化工作流场景。
tags:
- 集成工具
- 画布
- 可视化
- JSON
tools:
- - read
- exec
homepage: https://skillhub.cn
pricing_tier: L3
pricing_model: per_use
suggested_price: 29.9
tools: ["read", "write", "exec"]
tags: "工具,效率,自动化"
---
# 画布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：创建空画布

## 输入格式
| 参数名 | 类型 | 必填 | 说明 |
|:-----|:-----|:-----|:-----|
| input | string | 是 | 画布JSON处理免费版处理的输入数据或指令 |
| options | object | 否 | 附加配置选项,如模式选择、格式偏好等 |
| callback_url | string | 否 | 异步处理完成后的回调通知URL |

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

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

### Step 2：添加首个文本节点

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

### Step 3：连接两个节点

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

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

## 示例

### 节点属性速查表

| 属性 | 必填 | 类型 | 说明 |
|---:|---:|---:|---:|
| `id` | 是 | string | 16位十六进制唯一标识 |
| `type` | 是 | string | text/file/link/group |
| `x` | 是 | integer | 横坐标（像素） |
| `y` | 是 | integer | 纵坐标（像素） |
| `width` | 是 | integer | 宽度（像素） |
| `height` | 是 | integer | 高度（像素） |
| `color` | 否 | canvasColor | 预设1-6或十六进制 |
| `text` | text必填 | string | Markdown文本 |
| `file` | file必填 | string | 文件路径 |
| `url` | link必填 | string | 外部链接 |
| `label` | group可选 | string | 分组标签 |

### 布局尺寸建议

| 节点类型 | 建议宽度 | 建议高度 |
|:---:|:---:|:---:|
| 小文本 | 200-300 | 80-150 |
| 中文本 | 300-450 | 150-300 |
| 大文本 | 400-600 | 300-500 |
| 文件预览 | 300-500 | 200-400 |
| 链接预览 | 250-400 | 100-200 |

### 颜色预设对照

| 预设值 | 颜色 |
|:------|------:|
| `"1"` | 红 |
| `"2"` | 橙 |
| `"3"` | 黄 |
| `"4"` | 绿 |
| `"5"` | 青 |
| `"6"` | 紫 |

## 最佳实践

### 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 / 浏览器）

### 依赖详情
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|---:|:---|---:|---:|
| LLM API | API | 必需 | 由Agent平台内置LLM提供 |
| JSON解析器 | 运行时 | 必需 | Node.js/Python内置 |
| Obsidian | 应用 | 可选 | 用于可视化渲染与交互 |

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

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

## 错误处理

| 错误场景 | 原因 | 处理方式 |
|:------:|--------|:-------|
| 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 |
| 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 |
| 网络错误 | 连接超时或不可达 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案 |

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