canvas 是一个把图表当作代码来管理的工具。它并不渲染图形，而是保存可编辑的源文件：mermaid 文本，或用于自由白板的 excalidraw 场景 JSON。每个画布是一条命名记录，存放在稳定的 8 字符 id 下；渲染由控制台完成，因此调用 canvas::* 时会在聊天中显示实时图表，画布页面则用于列出和编辑所有已存储内容。由于保存的是源文件而非像素，图表可以随时修改，不会被固化。
用途与核心思路：当一段架构图、调用时序图、状态机或 ER 模型比文字更清楚时，可以创建 mermaid 画布交给控制台绘制。id 在更新前后保持不变，便于随着对话演进修订图表，并让此前对它的引用继续有效。记录持久化在 state worker 中，重启后不会丢失。
主要能力：canvas::create 从 mermaid 文本或 excalidraw 场景 JSON 创建画布，生成稳定 id 并推导 mermaid 图族。canvas::get 按 id 读取单个画布（含可编辑源码）。canvas::list 按最新优先列出所有画布，可按格式过滤，受 max_list 限制。canvas::update 按 id 修订名称和/或源码，id 不变并重新推导 mermaid 图族。canvas::delete 按 id 删除，未知 id 返回 deleted=false 而不报错。canvas::syntax 提供 mermaid 语法参考，包含每个受支持图族的摘要和可用示例，可只查一个图族。canvas::validate 仅解析源码而不存储，报告是否有效、推导出的图族，以及带行号的逐条问题信息。针对 freeform 画布（excalidraw 场景），canvas::element::add 可按绘制步骤逐个追加形状，控制台打开的白板会逐步显示；canvas::element::update 按元素 id 合并属性，用于移动、改色或改标签；canvas::element::delete 按元素 id 删除，未知 id 被忽略并返回删除数量；canvas::element::list 返回白板元素图（id、类型、位置、尺寸、文本），便于在更新或连接形状前查看。
使用方式：写 mermaid 前先调用 canvas::syntax 并缩小到要写的图族；拿到生成的源码后先 canvas::validate，再 canvas::create 或 canvas::update；需要修订时对已有 id 调用 canvas::update，而不是新建画布；需要人工在白板上编辑的空间草图，用 format freeform 和 excalidraw 场景 JSON 作为源码创建；边画边看时先建 freeform 画布，再每次调用 canvas::element::add 添加一个形状或一小群形状。
适用场景与限制：适合用图表替代冗长文字说明的架构、时序、状态机和 ER 模型，也适合需要人工继续编辑的自由白板草图。canvas 不做渲染，无头调用者只能拿到源码，不会得到 SVG 或像素；它不是文件存储，也不是文档编辑器，源码是一张图，受 max_source_bytes 限制，文件应由 shell worker 处理；canvas::validate 只检查源码能否解析，不保证图表内容正确；画布格式在创建时固定，canvas::update 只改名称和源码，不改格式；canvas::delete 幂等（未知 id 返回 deleted=false），其他按 id 操作的函数在未知 id 时会报错；element 系列只适用于 format: freeform 的画布，mermaid 画布通过 canvas::update 以文本方式编辑。