Canvas Json Handler

SKILL.md

---
slug: canvas-json-handler
name: canvas-json-handler
version: "1.0.0"
displayName: 画布JSON处理专业版
summary: 企业级JSON Canvas处理工具，支持批量操作、模板库、自动布局、跨画布合并与智能修复。
license: Proprietary
edition: pro
description: |-
  画布JSON处理工具专业版面向团队与企业场景，在免费版基础上扩展批量处理、模板库、自动布局、跨画布合并、智能修复等高级能力。核心能力：单次处理千级节点、内置思维导图/流程图/看板/知识图谱等8类模板、力导向/树形/层次/网格四种自动布局算法、多画布差异对比与合并、悬空引用智能修复、性能基准测试、版本快照与回滚
tags:
- 集成工具
- 画布
- 企业级
- 可视化
tools:
  - - read
- exec
---
# 画布JSON处理专业版

## 核心能力

### 批量处理引擎
- 单次操作支持1000+节点，内置检查点机制
- 断点续传：批处理中断后可从最近检查点恢复
- 幂等保障：同一批处理重复执行结果一致
- 进度可观测：实时输出处理进度与失败明细

**输入**: 用户提供批量处理引擎所需的指令和必要参数。
### 模板库（8类）
| 模板 | 节点规模 | 适用场景 |
|------|----------|----------|
| 思维导图 | 20-80 | 概念发散与收敛 |
| 流程图 | 10-50 | 业务流程编排 |
| 项目看板 | 15-40 | 任务依赖管理 |
| 知识图谱 | 100-500 | 实体关系网络 |
| 组织架构 | 20-100 | 层级关系展示 |
| 教学课件 | 30-60 | 讲义资源整合 |
| 产品路线图 | 15-30 | 里程碑规划 |
| 复盘画布 | 10-25 | 事后总结分析 |

**输入**: 用户提供模板库（8类）所需的指令和必要参数。
**输出**: 返回模板库（8类）的执行结果,包含操作状态和输出数据。### 自动布局算法
- **力导向布局**：适合知识图谱等网状结构，自动优化边交叉
- **树形布局**：适合思维导图与组织架构，按层级展开
- **层次布局**：适合流程图，按流向分层排布
- **网格布局**：适合看板与卡片，规则对齐

**输入**: 用户提供自动布局算法所需的指令和必要参数。
**处理**: 按照skill规范执行自动布局算法操作,遵循单一意图原则。
**输出**: 返回自动布局算法的执行结果,包含操作状态和输出数据。### 跨画布合并
- 节点ID冲突自动重映射
- 边引用跨画布迁移
- 分组节点的边界自适应调整
- 合并前差异预览与冲突标记

**输入**: 用户提供跨画布合并所需的指令和必要参数。
**处理**: 按照skill规范执行跨画布合并操作,遵循单一意图原则。
**输出**: 返回跨画布合并的执行结果,包含操作状态和输出数据。### 智能修复引擎
- 悬空引用：自动定位被引用但缺失的节点，提示重建或删除边
- ID冲突：自动为冲突项生成新ID并更新所有引用
- 必填字段缺失：按节点类型推断并补全默认值
- 坐标重叠：按布局算法重新分配位置

**输入**: 用户提供智能修复引擎所需的指令和必要参数。
**处理**: 按照skill规范执行智能修复引擎操作,遵循单一意图原则。### 版本管理
- 快照机制：每次重要变更前自动创建快照
- 增量对比：对比两个版本的节点/边差异
- 一键回滚：恢复到任意历史快照
- 审计日志：记录所有变更的操作者与时间

**输入**: 用户提供版本管理所需的指令和必要参数。
**处理**: 按照skill规范执行版本管理操作,遵循单一意图原则。
### 思维导图

执行思维导图操作,处理用户输入并返回结果。

**输入**: 用户提供思维导图所需的参数和指令。

**输出**: 返回思维导图的处理结果。

- 执行`思维导图`操作，处理输入数据并返回结果
- 验证执行结果，确认输出符合预期格式
- 参考`思维导图`相关配置参数进行设置
### 能力覆盖范围

本skill还覆盖以下能力场景: 企业级、JSON、Canvas、处理工具、支持批量操作、跨画布合并与智能、处理工具专业版面、向团队与企业场景、在免费版基础上扩、展批量处理、智能修复等高级能、核心能力、单次处理千级节点、内置思维导图、类模板、网格四种自动布局、多画布差异对比与、悬空引用智能修复、性能基准测试、版本快照与回滚。这些能力在上述核心功能中均有对应处理逻辑。
## 适用场景

| 场景 | 角色 | 价值 | 推荐能力 |
|------|------|------|----------|
| 知识库可视化重构 | 知识工程师 | 千级节点批量整理 | 批量处理+力导向布局 |
| 企业流程图批量生成 | 流程分析师 | 从规范文档自动生成画布 | 模板库+批量处理 |
| 团队协作画布治理 | 项目经理 | 多人画布合并与冲突解决 | 跨画布合并+版本管理 |
| 跨项目画布迁移 | 运维工程师 | 画布数据迁移与引用修复 | 智能修复+ID重映射 |
| 历史版本审计 | 合规专员 | 变更追溯与回滚 | 版本快照+审计日志 |
| 自动化画布生成 | 开发者 | 接入CI/CD自动产出画布 | 模板库+批处理检查点 |

## 使用流程

### 场景1：从模板生成思维导图画布

向Agent发送指令：
```
使用思维导图模板生成画布，主题为"机器学习知识体系"，包含5个一级分支，每个分支3-5个二级节点，应用树形布局，颜色按分支区分。
```

Agent将：
1. 从模板库加载思维导图骨架
2. 按主题填充节点文本
3. 应用树形布局算法分配坐标
4. 按分支分配颜色预设
5. 校验引用完整性后输出`.canvas`文件

### 场景2：批量追加节点并自动布局

```json
// 输入：待追加节点列表
{
  "target_canvas": "knowledge.canvas",
  "nodes_to_add": [
    {"type": "text", "text": "深度学习"},
    {"type": "text", "text": "强化学习"},
    {"type": "text", "text": "迁移学习"}
  ],
  "layout": "force-directed",
  "checkpoint_interval": 50
}
```

Agent将按检查点机制分批追加，每50个节点创建一次检查点，全部完成后应用力导向布局重排。

### 场景3：跨画布合并

```
将team-a.canvas与team-b.canvas合并为unified.canvas，自动解决ID冲突，合并后应用层次布局。
```

## 输入格式

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| content | string | 是 | 相关说明 |
| content | string | 否 | 相关说明, 默认: 默认值 |
| content | string | 否 | 相关说明, 可选值: json/text/markdown |
| style | string | 否 | 输出风格, 参考 `references/style.md` |

## 输出格式

```json
{
  "success": true,
  "data": {
    result: "相关说明",
    result: "相关说明",
    result: "相关说明",
    "metadata": {
      "template_used": "reviewer",
      "word_count": 0,
      "style": "专业"
    }
  },
  "error": null
}
```

输出模板参考: `assets/output.json`

## 异常处理

| 现象 | 可能原因 | 解决步骤 | 优先级 |
|------|----------|----------|--------|
| 批处理卡住不推进 | 检查点文件损坏 | 删除最近检查点，从上一检查点恢复 | 高 |
| 布局后节点重叠 | 算法参数不匹配 | 调整link_distance/charge参数 | 中 |
| 合并后引用缺失 | ID重映射未应用 | 重新运行合并流程，确认重映射表 | 高 |
| 快照恢复失败 | 快照文件损坏 | 从更早快照恢复，或使用增量日志重建 | 高 |
| 缓存命中率下降 | 大量随机变更 | 全量重建缓存，调整失效策略 | 低 |
| 智能修复误操作 | 激进模式误启用 | 切换保守模式，从快照回滚 | 高 |

## 依赖说明

### 运行环境
- **Agent平台**: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
- **操作系统**: Windows / macOS / Linux
- **Node.js**: 16+（用于批处理与布局算法的命令行工具）
- **Python**: 3.8+（用于版本管理与审计脚本）

### 依赖说明
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:-------|:-----|:---------|:---------|
| LLM API | API | 必需 | 由Agent平台内置LLM提供 |
| JSON解析器 | 运行时 | 必需 | Node.js/Python内置 |
| 布局算法库 | npm包 | 必需 | `d3-force`/`dagre`等 |
| 快照存储 | 文件系统 | 必需 | 本地磁盘或网络存储 |
| Obsidian | 应用 | 可选 | 用于可视化渲染与交互 |

### API Key 配置
- 本Skill基于指令驱动，无需额外API Key
- 批处理与布局算法为本地执行，不依赖外部API
- 若需对接企业版渲染服务，按对应服务文档配置

### 可用性分类
- **分类**: MD+EXEC（纯Markdown指令，批处理与布局功能需要exec命令行执行能力）
- **说明**: 基于Markdown的AI Skill，通过自然语言指令驱动Agent执行企业级画布治理任务，高级功能通过命令行工具实现

## 案例展示

### 批处理检查点配置

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `checkpoint_interval` | integer | 50 | 每处理N个节点创建一次检查点 |
| `max_retries` | integer | 3 | 单节点处理失败最大重试次数 |
| `idempotent` | boolean | true | 是否启用幂等模式 |
| `parallel_workers` | integer | 4 | 并行处理工作线程数 |

### 自动布局参数

| 算法 | 参数 | 说明 |
|------|------|------|
| 力导向 | `link_distance` | 节点间期望距离，默认150 |
| 力导向 | `charge` | 节点斥力，默认-300 |
| 树形 | `direction` | 展开方向LR/RL/TB/BT |
| 树形 | `level_gap` | 层间距，默认200 |
| 层次 | `rank_gap` | 层级间距，默认150 |
| 网格 | `cell_width` | 单元格宽，默认250 |

### 缓存策略配置

| 缓存层级 | 内容 | 命中率指标 |
|----------|------|------------|
| L1-ID索引 | 节点/边ID到对象映射 | >95% |
| L2-坐标索引 | 坐标范围到节点映射 | >85% |
| L3-引用图 | 节点到关联边映射 | >90% |

## 常见问题

### Q1：批处理中途失败如何恢复？
A：专业版内置检查点机制，从最近检查点恢复即可。检查点文件位于`.canvas-checkpoints/`目录，包含已完成节点的ID清单与状态。恢复命令会跳过已完成节点，仅处理未完成部分。

### Q2：力导向布局对1000节点太慢？
A：力导向算法复杂度为O(n²)，1000节点确实较慢。建议：(1) 启用并行工作线程（parallel_workers=8）；(2) 降低迭代次数（iterations=300）；(3) 改用层次或网格布局作为初始位置，再用力导向微调。

### Q3：跨画布合并后边引用混乱？
A：合并时必须先建立ID重映射表，将两个画布的冲突ID统一重映射后再合并边数组。专业版的合并流程会自动完成这一步，但若手动合并遗漏该步骤，会出现悬空引用。运行智能修复引擎可自动修复。

### Q4：快照占用空间过大？
A：快照采用增量存储，仅记录与上一版本的差异。若仍觉过大，可配置快照压缩（gzip）并调整保留策略。日快照7天后自动转为周快照，周快照4周后转为月快照。

### Q5：智能修复误删了有效边？
A：智能修复默认采用保守策略，对悬空引用优先标记而非删除。若启用了激进模式（`repair_mode=aggressive`），会自动删除悬空边。建议生产环境使用保守模式，删除操作由人工确认。

### Q6：模板库如何扩展？
A：专业版支持自定义模板，将符合规范的`.canvas`文件放入`templates/`目录并编写`template.json`元数据即可。元数据包含模板名、节点规模、适用场景、推荐布局算法等信息。

### Q7：如何集成到CI/CD流水线？
A：专业版提供命令行接口，支持`--template`、`--layout`、`--merge`、`--validate`等参数。在CI/CD中调用命令行接口，结合版本快照能力，可实现画布的自动化生成与审计。

### Q8：多级缓存的失效策略？
A：L1-ID索引在节点/边增删时增量失效；L2-坐标索引在坐标变更时按区域失效；L3-引用图在边变更时按节点失效。所有缓存均支持手动清除（`cache.invalidate()`）与全量重建。

### Q9：并发编辑如何避免冲突？
A：专业版采用乐观锁机制，每次保存前校验版本号。若版本号不匹配，触发合并流程，由跨画布合并引擎自动解决冲突。冲突无法自动解决时，提示人工介入。

### Q10：版本快照能跨画布共享吗？
A：可以。快照存储在独立的版本库中，通过画布ID关联。多个画布的快照可统一管理与审计，便于跨项目对比与迁移。

## 错误处理


| 错误场景 | 原因 | 处理方式 |
|---------|------|---------|
| LLM响应超时或无响应 | 网络延迟或模型负载过高 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接，执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令请求；确认Agent平台LLM服务正常 |
| 输入内容格式不正确 | 用户输入不符合skill预期格式 | 检查输入是否符合skill使用说明中的格式要求，参考示例章节 |
| 执行结果与预期不符 | 指令描述不够明确或上下文不足 | 提供更详细的指令描述，补充必要的上下文信息 |
| 命令执行失败 | 运行环境不满足要求或权限不足 | 确认运行环境符合依赖说明中的要求；检查命令权限设置 |

## 已知限制

- 
- 
-