mcpField
C
canvas

canvas

github.com/agricidaniel生产力16.0k455 次安装1 周前更新
代码仓库

关于 canvas

用于 Obsidian vault 的 JSON Canvas 工作流技能，面向创建和编辑画布的用户。它通过校验与可审阅事务管理变更，并保留画布现有结构。

主要功能

  1. 01读取画布并报告节点与链接问题
  2. 02创建和替换画布文件
  3. 03通过事务预览并应用变更
  4. 04校验节点、边及文件路径
  5. 05支持画布目录索引同步

适用场景

  1. 01查看画布节点数和缺失文件
  2. 02向现有画布添加节点或边
  3. 03创建画布并更新目录
  4. 04预览删除节点等破坏性编辑

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/agricidaniel/claude-obsidian --skill canvas

安装后在 Claude Code 中输入/canvas确认已加载。

附带文件references/canvas-spec.md

详细介绍

Canvas

将画布视为限定在知识库范围内的 JSON Canvas 文档。读取操作保持只读，并将所有请求的修改通过一笔可恢复的事务完成。

根据此技能自身的位置解析已安装的产品根目录，而不是根据知识库或当前工作目录：

PRODUCT_ROOT=/absolute/path/to/installed/claude-obsidian
CORE="$PRODUCT_ROOT/scripts/claude-obsidian.py"
test -f "$CORE"

本文件中的每个 ../wiki/references/ 链接都以相同方式解析：相对于 $PRODUCT_ROOT 下此技能自身的目录，而不是相对于所选知识库的 wiki/ 目录。

选择语法来源

格式细节优先参考单独安装的 kepano/obsidian-skills json-canvas 技能。否则，请阅读 references/canvas-spec.md。 开放标准为 JSON Canvas 1.0。

即使有上游语法技能可用，也要使用此技能处理知识库工作流和事务安全。

范围

  • 读取前先解析用户的知识库。切勿从插件文件推断知识库。
  • 将画板存放在 wiki/canvases/ 下；仅当用户未指定画板时，才默认使用 wiki/canvases/main.canvas。
  • 将 wiki/canvases/_index.md 视为可选目录。如果目录存在，请在同一事务中将新画板添加到目录。修改现有画板中的节点或边无需更改目录。
  • 事务引擎仅支持创建和替换文件。无法通过此技能删除或重命名画板文件。如果用户请求删除或重命名文件，请说明此限制并提供单独的清理计划；不要改用宿主文件工具，也不要悄悄将重命名替换为复制。
  • file 和 background 使用相对于知识库的路径；拒绝绝对路径、.. 路径遍历、主目录快捷方式，以及通过符号链接越界的路径。
  • 仅引用知识库内已有的文件，或在同一笔经审查的事务中创建的文件。如果检测到可选的捕获或媒体功能，请与其配合，并使用其返回的知识库相对路径。不要假定存在特定插件、命令或会话日志，也不要在此技能中下载或复制资源。
  • URL 使用 link 节点。仅接受 HTTPS URL；link 节点不代表获准抓取页面。创建其 JSON 不会发起请求，但在 Obsidian 中打开它时，可能会从该 URL 的主机获取 Open Graph 元数据。请披露渲染时的外发网络请求并确认用户接受；否则使用包含该 URL 的文本节点。

只读操作

对于状态或列表请求，解析所选的 .canvas 文件，并报告节点数量、分组标签、损坏的边端点，以及缺失的知识库相对文件目标。如果默认画布不存在，请报告此情况并提供创建预览；状态请求期间不要创建画布。

起草修改

  1. 读取整个画布和任何目录目标。记录每个文件的预期 SHA-256；对于必须不存在的文件，记录 null。
  2. 保留未知 JSON 字段和现有数组顺序。节点数组按从下到上的 z 轴顺序排列。
  3. 起草请求的节点或边：
    • 为每个节点和边分配唯一 ID。优先使用随机的 16 位小写十六进制 ID，并验证其尚未使用。
    • 每个节点的 x、y、width 和 height 都必须是整数。
    • 严格按 JSON Canvas 的定义使用 text、file、link 或 group。
    • 要求每个 fromNode 和 toNode 都引用一个现有节点或新起草的节点。
  4. 有意安排新内容的位置。分组是视觉容器，不是父级。使用 20 px 内边距和 40 px 间距；需要时换到新行，并预览任何分组扩展。
  5. 序列化为有效的 UTF-8 JSON，顶层包含 nodes 和 edges 数组。

最简节点示例：

{
  "nodes": [
    {
      "id": "6f0ad84f44ce9c17",
      "type": "text",
      "text": "# Research map\n\nA concise orientation card.",
      "x": 0,
      "y": 0,
      "width": 400,
      "height": 180
    },
    {
      "id": "a1b2c3d4e5f67890",
      "type": "file",
      "file": "wiki/concepts/Contextual Retrieval.md",
      "x": 460,
      "y": 0,
      "width": 400,
      "height": 240
    }
  ],
  "edges": []
}

对于笔记、图片、PDF 和其他知识库文件，使用 file，并可选添加 subpath: "#Heading"。仅在 link 节点上使用 url。在 JSON 字符串中，将换行符转义为 \n，而不是写成字面上的反斜杠加 n。

预览并应用

展示预览前先验证：

  • JSON 能够解析，且使用受支持的节点类型。
  • ID 唯一，边的端点均存在。
  • 尺寸为正整数；
  • 文件和背景路径安全、相对于 vault，且文件存在；
  • 新节点不会意外重叠或超出其指定分组的范围。

构建一个操作类型为 canvas 的 claude-obsidian.transaction.v1 bundle。 如果目录有变更，请将画布和目录一并纳入同一个 bundle。 阅读 operation-transactions.md， 然后在应用前检查 bundle：

python3 "$CORE" transaction inspect BUNDLE --vault VAULT
# Set APPROVAL_SHA256 to the inspect result's approval_sha256 after review.
python3 "$CORE" transaction apply BUNDLE --vault VAULT \
  --approved-plan-sha256 "$APPROVAL_SHA256"

对于画布内的破坏性编辑，包括移除节点或边，展示预览后须取得明确同意。这些编辑会通过事务引擎替换画布文件。报告操作 ID、确切的变更路径、画布名称、节点 ID 和最终位置。不要提交 Git。

评论

支持 Markdown