Diagram：把解释变成看得见的图形
讨论架构、状态机或数据模型时，让人和 agent 看着同一张图会更容易。Diagram 将图形源内容保留在文件中，并在 Canvas 上显示。你可以请求方案、编辑源内容、查看结果并评审决策，而不必切换上下文。
图形不能替代 Specification：它可以揭示歧义、解释决策或呈现备选方案，契约仍应保留在合适的位置。
图形与 CodingAgent、Sticky Note 参与同一张工作图谱。源内容仍保存在文件中。
创建或添加 Diagram
通过界面创建
- 点击 Canvas 工具栏中的 Diagram，或打开紧接 Specs 的 Diagrams 面板，使用 New diagram。
- 选择格式并输入名称。默认为 Mermaid。
- 创建前检查显示的路径和扩展名。
Enter确认，Escape取消。 - 在 Source 中编写；如果使用 Excalidraw，则可开始绘图。
你也可以将工具栏中的 Diagram 拖到 Canvas 的目标位置。表单会在面板中打开，并在确认前保留该位置；直接点击工具栏时，则在可见区域创建。
表单没有单独的文件夹字段。从工具栏或通用 New diagram 操作创建时，使用 Workspace 配置的目标位置；从文件夹菜单的 New Diagram… 创建时，使用该文件夹。确认前请检查显示路径。重名和失败会留在表单中提示，不覆盖文件。draw.io 使用外部编辑器，因此不在创建格式列表中。
在面板中选择要创建的格式。draw.io 从已有文件打开，因此不出现在此创建列表中。
选择新图表的文件夹
打开 Workspace Settings → Documentation roots。Specifications 和 Diagrams 共享这些根目录；不存在单独的 Diagram 根目录列表。
Diagrams folder 相对于第一项 Documentation root。默认值为 diagrams：根目录为 docs 时，结果是 docs/diagrams/。也可输入 architecture/diagrams 之类的嵌套文件夹，并在保存前检查计算出的目标位置。使用 . 可直接在第一项根目录中创建，不使用子文件夹。
修改此字段或重排 roots，只会改变之后创建文件的目标位置，不会移动已有文件或 Nodes。面板在 Documentation roots 内发现图表；根目录外的文件仍可通过明确路径在 Canvas 打开。发现配置不是新的文件系统权限。
从已有文件添加
在 Diagrams 面板使用 Add to Canvas，或将文件拖到 Canvas。扩展名决定格式，包括 .vl.json 这样的复合扩展名。来源仍留在原处，磁盘上的变更会更新 Node。
SVG 需要明确选择： 打开或拖入 .svg 通常创建 File，而不是 Diagram。让 CodingAgent 添加时，请明确要求 Diagram。如果同一文件已由 File 表示，此操作会转换 Node，并保留身份、位置、大小和 Connections，不修改文件。
每个来源在一个 Workspace 中最多对应一个 Node。重命名 Diagram 会重命名其源文件；移除 Node 不会删除文件。
与 CodingAgent 协作
说明你想传达什么，而不只是格式。“展示这个流程的决策和失败路径”比“画一张漂亮的图”提供的上下文更多。使用小型示例，并确认图形与系统相符。
下文提示词使用虚构数据，供你起步。粘贴到负责的 CodingAgent，发送前调整名称和路径。创建 Node 需要启用 Allow workspace editing；已有资源必须可达，Guardrails 仍然适用。没有结构编辑授权时，只请求源内容或指导。
没有指定路径时，CodingAgent 会查询 Workspace 的 Documentation roots 和 Diagrams folder，使用与界面相同的目标位置——默认配置下为 docs/diagrams/。提示词中的明确路径优先。示例都明确使用 docs/diagrams/；若要保存在另一项已配置根目录内并通过面板找到它们，请相应调整路径。
检查图形，而不只是语法
CodingAgent 可以编写源文件、将 Diagram 添加到 Canvas，并查询当前渲染结果：rendered、failed 或 not_rendered。失败时会收到引擎错误，以及可用时的行号。
源内容看起来有效，不证明已经渲染。not_rendered 表示没有针对磁盘上当前文件的有效观察结果；请打开或定位显示 Diagram，让它实际呈现。其他文件修订的结果、尚未保存的预览，以及重启前的观察，都不能证明当前渲染成功。
如果可达 Diagram 与 agent 的直接 Connection 带有 diagram_read_only，agent 必须保留源内容，不能重命名或删除 Node。不要用提示词或文件系统工具绕过该限制。
从请求到 Canvas 上的图形
观看 CodingAgent 在 Canvas 上创建 CRM 实体图 (在新标签页中打开)。
演示从一个 CodingAgent 和一张提供上下文的 Sticky Note 开始。用户请求基本的 CRM 实体图；agent 使用 Excalidraw 编写源文件，并在 Canvas 添加与自身连接的 Diagram。与下方示例一样，创建 Node 需要 Workspace 编辑权限。
结果包含 Account、Contact、Lead、Opportunity 和 Activity，字段和关系均为虚构。将它用作项目模型前，请先检查图形：它展示的是一项提案，不是对你真实数据库结构的分析。演示覆盖从创建到可视结果的过程；编辑、导出和文件夹整理在本指南中各有操作说明。
录像无声，界面和输入内容为英语。部分输入和等待片段已加速；最终结果以正常速度呈现。以上文字提供了完整的演示说明，无需依赖视频也能理解过程。
按要解释的内容选择格式
所有示例都要求生成源文件并在 Canvas 上检查，不要求执行应用代码。首次下载所需资源可能需要网络；参见下载、隐私与离线使用。
不同格式可以共存于 Canvas。这些图形仅供示意；下文逐一说明格式与限制。
Mermaid — .mmd, .mermaid
适合从流程、时序和状态图开始。可用类型取决于 Kavor 集成的引擎；不要假设 Mermaid 刚增加的语法已经可用。粘贴到 CodingAgent，创建一个小型虚构流程。
用 Mermaid 创建 docs/diagrams/checkout.mmd：购物车 → 支付 → 确认，并包含支付被拒的分支。
将它作为 Diagram 添加到我的图谱，并检查当前渲染结果。
修复报告的错误；不要修改应用，也不要在未观察结果时宣称成功。
预期结果： 一张失败路径清晰可读的流程图，以及渲染结果报告。没有有效观察时，agent 应报告 not_rendered，而不是推定成功。
PlantUML — .puml, .plantuml
适用于 UML、时序图、甘特图、思维导图和线框图。JavaScript 引擎无需安装 Java。包括 C4 在内的标准库按需获取；首次使用 C4 可能需要额外下载。将提示词粘贴到 CodingAgent。
使用 C4 库创建 docs/diagrams/checkout-context.puml：客户、商店和外部支付服务商。
标明关系，将文件添加为 Diagram，并查询当前结果。
如果缺少库或出现错误，先报告原因，不要直接声称图形已就绪。
预期结果： 一张明确显示外部依赖的简单 C4 上下文图。缺少网络或库，不应被当作图形已验证。
Graphviz — .dot, .gv
适合通过顶点布局解释依赖的图。可用布局为集成引擎所包含的布局。将提示词粘贴到 CodingAgent；此处依赖均为虚构，不是从仓库推断的。
创建 docs/diagrams/dependencies.dot：web 依赖 api；api 依赖 billing 和 catalog；后两者都依赖 storage。
从左到右排列图形，添加为 Diagram，并检查当前渲染。
不要编造真实项目的依赖；这里只绘制上述示例。
预期结果： 带标签的依赖图，不把示意图变成对项目的诊断。
D2 — .d2
适合架构和组件关系。Kavor 提供 Dagre 和 ELK 布局；不支持 TALA。粘贴到 CodingAgent；布局选择有影响时，请明确指定。
创建 docs/diagrams/order-service.d2，使用 Dagre 布局：客户端、API、队列和 worker，展示订单路径。
添加为 Diagram 并检查当前渲染。仅使用与 Dagre 或 ELK 兼容的功能，不用 TALA。
报告所有错误，不要修改真实基础设施。
预期结果： 清晰可读的架构图，不依赖 TALA，也不创建图中展示的服务。
SVG — .svg
适合需要直接控制形状、标签和构图的矢量图。使用内置渲染。粘贴到 CodingAgent，并明确要求 Diagram，与普通 File 区分。
创建 docs/diagrams/review-cycle.svg：Builder、Reviewer 和人工决策三个方框，依次连接。
使用自包含 SVG，不含脚本或远程资源，明确添加为 Diagram，而不是 File。
检查当前渲染并报告结果，不修改其他 Nodes。
预期结果： 以 Diagram 呈现的矢量图。仅有 .svg 扩展名，不会改变 File 的类型。
Excalidraw — .excalidraw
适合希望继续以可视方式调整的探索性绘图。文件包含 Excalidraw 场景；这是 Kavor 中提供可视编辑器的格式。粘贴到 CodingAgent，准备一个简单场景。
创建 docs/diagrams/review-workshop.excalidraw，包含有效场景：想法、实现和评审，并添加箭头和标签。
添加为 Diagram 并检查渲染。保持绘图简单，方便我通过 Edit drawing 继续编辑。
不要替换已有文件，也不要声称我已经完成评审。
预期结果： 可以通过 Edit drawing 打开的场景。生成场景本身并不证明所示流程合理；将其用于决策前，请先评审。
draw.io — .drawio
用于查看该格式的图表，包括页面和图层。View only：Kavor 不提供可视编辑器，也不能在 Source 中编辑 XML。请用外部工具生成或编辑文件；获得授权时，CodingAgent 也可通过文件系统操作。粘贴到 agent，生成新示例，不要覆盖自己的已有文档。
创建 docs/diagrams/order-overview.drawio，作为有效的 draw.io 文件，包含一页：客户端 → API → 数据库。
将已存在的文件添加为 Diagram，并检查当前渲染。
不要用 New diagram 创建 draw.io，也不要承诺能在 Kavor 内可视编辑。
预期结果： 可在 Node 中查看的页面。之后修改时，请使用外部应用或获授权的源文件编辑；Kavor 会跟随文件变更。
Vega-Lite / Vega — .vl.json, .vg.json
用于数据图表。.vl.json 选择 Vega-Lite，.vg.json 选择 Vega。两者语法不同，不能仅替换扩展名。要制作不依赖网络的示例，请粘贴到 CodingAgent 并要求内嵌数据。
用 Vega-Lite 创建 docs/diagrams/build-times.vl.json：柱状图显示虚构的构建耗时，分别为 12、18 和 9 秒。
将数据嵌入 JSON，标注坐标轴，不获取外部数据集。
添加为 Diagram 并检查当前渲染。
预期结果： 可进行比较、单位明确的图表。如需使用 Vega，请明确要求该语法及 .vg.json 路径。即使引擎已缓存，远程数据集仍需要网络。
WaveDrom — .wavedrom
用于数字信号时序。Kavor 使用的源内容必须是有效 JSON，而不是 JavaScript 脚本。粘贴到 CodingAgent，展示一个简单握手过程。
创建 docs/diagrams/handshake.wavedrom，使用有效 JSON，展示八个周期中的 clock、request 和 acknowledge。
明确 acknowledge 在何时响应 request；不要执行任何脚本。
添加为 Diagram 并查询当前结果，修复引擎报告的错误。
预期结果： 时间对齐的信号图。图形解释的是示例，不证明任何硬件实测结果。
nomnoml — .nomnoml, .noml
用于简洁的 UML 草图。它有自己的语法，不能与 PlantUML 互换。将提示词粘贴到 CodingAgent。
创建 docs/diagrams/order-model.nomnoml，包含 Order、OrderItem 和 Product，展示关系和少量属性。
使用 nomnoml 语法，添加为 Diagram，并检查当前渲染。
保持模型为虚构示例；不要修改项目的类或数据库结构。
预期结果： 用于讨论的实体草图，不把绘图自动转为实现。
Pikchr — .pikchr
用于 PIC 风格绘图语言的技术构图。使用 Pikchr 语法，不是任意 PIC 程序。粘贴到 CodingAgent，绘制小型处理流程。
创建 docs/diagrams/processing.pikchr，用带标签的方框和箭头表示输入、转换和输出。
使用 Pikchr 语法，添加为 Diagram，并检查当前渲染。
如果引擎拒绝源内容，先修复实际观察到的错误，再报告结果。
预期结果： 简单的矢量构图。看似合理的语法不能替代对引擎结果的观察。
Svgbob — .bob
用于将 ASCII 草图转为矢量图。文本对齐是源内容的一部分。粘贴到 CodingAgent，并在文件中保留对齐。
创建 docs/diagrams/request-path.bob，使用 ASCII：两个分别标为 Client 和 Server 的方框，以箭头连接。
保留对齐，添加为 Diagram，并检查当前渲染。
不要只粘贴图片：保留可编辑的文本草图作为源内容。
预期结果： 由文本草图生成的图形。空格变化可能改变几何形状。
DBML — .dbml
用于讨论表、列和关系。源内容是 DBML，不是 SQL；渲染不会创建表或执行迁移。粘贴到 CodingAgent，并使用虚构模型。
创建 docs/diagrams/shop-schema.dbml，包含 customers、orders 和 order_items，标明键和关系。
添加为 Diagram 并检查当前渲染。
不要连接真实数据库，不生成迁移，也不要把示例当作我项目的数据库结构。
预期结果： 可供评审的数据模型。以后若要呈现真实数据库结构，请提供获授权的来源，并将发现、假设和决策分开。
在图形和源内容之间切换
- Diagram： 优先显示可视结果。已有文件会在此视图打开。
- Source： 显示源内容。可编辑格式使用 Files 的编辑器和保存流程。
- Split： 左侧源内容，右侧预览，方便调整和比较，无需反复切换。
新建的源文本格式在 Source 中打开。Excalidraw 使用 Edit drawing 进入可视编辑器，Finish editing 返回图形。变更使用同一文件和保存流程，不存在单独的第二个 Save。可视编辑和源内容编辑不会同时处于活动状态。
draw.io 的 Source 保持只读。用 Open with default app 在外部编辑器中处理。
在 Diagram 视图中，按住右键拖动可移动内部视图；双指缩放或 Ctrl/⌘ + 滚轮可调整缩放，不会拖动 Canvas。使用缩放控件和 Fit 调整取景。标题栏仍是移动 Node 的区域。Excalidraw 编辑器使用自身的控件。
源文本格式可用 Split 同时查看代码和结果。Excalidraw 还提供对绘图本身的可视编辑。
预览过期时
如果某次编辑无法渲染，最后一次成功结果可能仍然可见，同时显示 Preview out of date 和引擎错误。它属于之前的源内容，不证明新内容成功。若引擎报告了真实行号，可在 Source 中打开该行；从未渲染成功的文件会显示源内容和失败信息。
修复语法、保存并检查当前结果。保存问题和冲突不同于渲染失败；不要因为屏幕上仍有图形就丢弃本地编辑。
导出以便分享
Export 提供完整图形的 SVG 和 PNG，不是截取 Node 可见范围。draw.io 导出活动页面及其图层。预览过期时，导出使用最后一次成功渲染，并明确提示。没有任何已渲染结果时，导出不可用。
不填满 Canvas 也能使用 Diagrams 面板
面板在 Documentation roots 内递归查找图表文件，遵循 .gitignore，支持按名称或路径搜索，并用 All formats 按格式筛选。它不会对 Workspace 中所有文件进行全局搜索。
列表映射磁盘上的真实文件夹层级。没有搜索或格式筛选时，也会包含空文件夹；可展开、折叠目录来导航。有多项 roots 时，树按根目录分组。
Specs 和 Diagrams 显示相同的 Documentation roots。在一个面板创建的文件夹也会出现在另一个面板：这是磁盘上的同一文件夹，不是副本。这不会把 Specification 变成图表，也不改变其生命周期。
- Preview： 打开只读预览，不添加 Node。悬停或选中行不会打开预览。一次仅有一个预览；
Escape关闭并将焦点返回该操作。 - Add to Canvas： 添加来源；若已有 Node，则定位已有项。
- New diagram： 通过内联表单选择格式和名称并创建。
- Show in File Manager： 在系统文件管理器中定位文件或文件夹。
预览可能需要下载该格式的引擎。关闭预览后，迟到的结果不会被当作另一个文件的有效渲染。
Preview 可查看图形而不创建 Node。Add to Canvas 是独立操作。
创建和整理文件夹
打开树中文件夹的上下文菜单：
- New Diagram…： 打开内联表单，在该文件夹内创建，即使它不是 Diagrams folder 中的默认目标。选择格式，输入名称并检查路径。
- New Folder…： 创建真实子文件夹；在需要图表前，可以保持为空。
- Rename Folder…： 修改文件夹名称，不改变其父目录。受影响的 Diagram Nodes 会跟随新路径。
- Show in File Manager： 在系统文件管理器中打开所在位置。
这些操作不能重命名或删除已配置的 Documentation roots。要修改发现根目录或新建文件的默认目标，请使用 Workspace 设置，而不是删除文件夹。
重命名、移动和版本化文件
图表上下文菜单中的 Rename Diagram… 修改文件名，但保留扩展名，包括 .vl.json 这样的复合扩展名。移动文件时，将该行拖到树中的其他文件夹或根目录。如果已被 Git 跟踪，移动使用 git mv；未跟踪文件也可以移动。
重命名文件、重命名其文件夹或移动图表后，Diagram Node 会跟随路径。无需重新添加：Node 身份和 Connections 都会保留。
在 Git 仓库中，Commit Diagram 只提交该文件路径，并显示生成的提交哈希。不包含其他路径已暂存的变更。即使 Canvas 上没有 Node，也可以使用；版本化的是文件，不是图形快照。
若有尚未保存的本地编辑，请在改变来源或提交前处理界面要求的决定。操作失败时，读取面板信息并修复原因；不能仅因操作已发起，就认为移动或提交已完成。
删除时区分文件和 Node
在文件菜单选择 Delete Diagram 并确认后，会删除源文件及其 Diagram Nodes。这不同于仅从 Canvas 移除 Node，后者会保留文件。
Delete Folder and Contents 需要确认，并且只允许删除仅含受识别图表文件和真实目录的子树。若发现 Specification、其他类型文件、隐藏项或符号链接，面板会在作出任何变更前拒绝操作，并提示用 Files 处理混合内容。此检查仅适用于 Diagrams，不改变 Specs 面板的删除规则。
删除单个已跟踪图表时，Kavor 使用 Git 删除流程。如果 Git 因本地变更等原因拒绝，请先处理提示的状态再重试；确认删除不授权强行丢弃这些变更。
将源文件带入图谱
可达 Diagram 为 CodingAgent 的工作提供源内容和可视结果。不必让每个 agent 都直接连接它；若要对该配对应用 diagram_read_only，才需要直接 Connection。
与 File + Terminal 一样，Diagram + Terminal Connection 通过你选择的环境变量提供源文件绝对路径。变量值是路径，不是渲染后的 SVG 或 PNG。请在启动会话前配置，或重启会话以接收参数变更。参见 Connections 矩阵。
下载、隐私与离线使用
图形在 Kavor 内部渲染，不发送到外部渲染服务。引擎、字体和辅助资源按需下载、验证并保存在应用数据缓存中。打开 Kavor 或 Workspace 不会下载所有格式。SVG 使用内置显示功能。
首次使用后，已获取的资源可在离线时复用。Excalidraw 编辑器只有进入编辑时才下载；PlantUML 库（如 C4）和 draw.io 资源也可能需要首次下载。Kavor 更新若替换这些资源，下次使用可能需要重新下载。
首次离线尝试或下载失败时，Node 会显示原因和 Retry。可编辑格式的源内容仍然可用；能够获取资源后再重试。
引擎已缓存不等于完全不使用网络。 内容本身可以引用图片、数据集或其他远程资源。本地 includes 相对于图表所在文件夹解析，其变更也可能更新图形。打开不熟悉的源文件前请先审查；离线使用时，优先选择自包含内容，并提前准备所有所需资源。
图表显示区域与应用的特权界面隔离，但这不会让图表中的引用变成可信来源。如果让 CodingAgent 生成或分析内容，provider 的参与仍遵循所选 harness 的条件；不要把本地渲染与模型在本地处理混为一谈。
继续阅读
- 向 Canvas 添加内容，无需多余地复制来源。
- 将决策保留在 Specification，用图形来解释。
- 查看受支持的 Connections 和 CodingAgents 的上下文边界。