技能介绍

要解决什么问题

技术文档几乎离不开图表：README 里的架构概览、API 文档中的请求流程、状态机的转移图、甚至论文里的 Transformer 结构图。手动用设计工具画图有两个痛点：一是产出是二进制或编辑器专有格式，团队协作时难以版本控制；二是调整一次布局可能要拖十几个节点，改起来比写代码还累。直接手写 SVG 虽然可控，但 <path> 坐标、stroke 样式、<text> 定位这些细节会消耗大量时间，而且画出来的图往往缺乏一致性。diagrammer 把这个问题拆成两半：用结构化 JSON 描述图的结构，再由渲染器统一出图，既保留了文本可审查、可 diff 的优势，又省去了手动调坐标的负担。

核心能力与工作流程

整个流程分三步：

解析需求：把用户用自然语言描述的图表（比如"画一个登录流程的状态机，包含未登录、已登录、锁定三个状态"）转成结构化 JSON spec。
保存 spec：将 JSON 写入临时文件或项目目录，方便审查和迭代。
渲染 SVG：通过本地安装的渲染器生成最终 SVG 文件，返回路径给用户。

JSON spec 支持多种内置节点类型：box（矩形）、circle（圆形）、text（文本）、database（数据库）、stack（堆叠）、group（分组）、note（注释）和 custom（自定义）。边的属性也可以精细控制，比如 direction 设为 "LR" 或 "TB" 控制流向，router 选 "straight" 或 "ortho" 控制连线样式，边的 style 和 weight 分别支持 "solid"/"dashed" 和 "thin"/"thick"。

适用边界与注意点

这个技能的定位是"精确的、可入库的 SVG 产物"。以下场景优先用它：README 图表、架构草图、请求流程、状态机、神经网络或 Transformer 结构图、简单数据管道。

但有两类情况应该换工具：如果用户明确要 Mermaid 语法或 Markdown 平台自动渲染，优先用 Mermaid；如果需要可编辑的手绘风格画布文件，优先用 Excalidraw。

另外，diagrammer 的使用范围严格限定在业务流程、架构与关系图生成场景。它不会主动读取任务范围外的文件，信息不足时会标记缺口并等待确认，不会用猜测填补事实。涉及联网检索或调用接口时，需要先说明目标和用途并取得明确同意。命令和脚本默认作为可审查的参考方案，只有在用户明确要求执行、目标路径清楚且预检通过后才运行必要的最小步骤。交付前还会复核事实依据、隐私、版权和平台规则，发现高风险请求时停止动作并给出合规替代方案。