georgelu-creator/diagram-skills

DiagramSkills

将图表请求转化为完成的视觉交付物，使用内置的 DiagramSpec 渲染器。主要产品是 智能体生成的图表质量：编写可维护的 JSON，渲染 SVG/HTML 和可选的 PNG，检查视觉效果，修复源文件，并返回结果。不要让用户打开编辑器完成普通工作。公开技能 ID 为 $diagram-skills；面向用户的品牌是 DiagramSkills。

默认交付工作流

1. 对于从文本到图表的任务或实质性修订，从 templates/briefs/diagram-brief.json 创建一个简洁的 .brief.json。它记录目标、叙述、范围、优先级、不确定性、内容风险和审查问题——而非私有的思维链。
2. 阅读 references/diagram-thinking-profiles.json 中选定的配置文件，量身定制至少三个质量问题，并在绘图前运行 diagram_brief.py ... --strict。
3. 对于超过 14 个可见概念的分层概览，阅读 references/enterprise-board.md 并使用 layout: board。对于较小的关系图，使用 nodes/edges。
4. 从匹配的模板开始，替换其示例内容，并将简要文档和源 JSON 放在输出旁边。
5. 在请求 PNG 之前运行 png-backend，然后仅在本地支持的光栅化器可用时使用 --png 运行 render ... --strict。源文件本身不是完整的视觉请求。
6. 以全尺寸检查生成的 SVG 或 1920 像素 PNG。检查层次、中文文本、图标一致性、裁剪、拥挤卡片、线条交叉以及简要文档的叙述是否在视觉上占主导。
7. 用具体、清晰的证据回答每个简要文档的质量问题，并运行 diagram_brief.py ... --spec ... --strict --reviewed。然后使用 diagram_skills.py review ... 将已审查的简要文档、源文件和已检查的 SVG 或 PNG 绑定到质量收据中。如果任何检查失败，纠正简要文档、源文件或渲染器并重新渲染。在三个基于证据的修正轮次后停止；然后简化或拆分。
8. 首先生成图像，然后链接简要文档、SVG/HTML/源文件/质量证据。仅在用户要求手动编辑、导入或下钻时提及浏览器编辑器。

路由请求

1. 对于从文本到图表的任务和实质性修订，阅读 references/diagram-thinking.md。不要为了布局对称而编造事实。
2. 当输入为文本、不完整或需要成为可复用提示时，阅读 references/prompt-system.md。
3. 选择恰好一个主要类型并阅读其指南：
   • 系统架构
   • 智能体工作流
   • 数据流
   • 能力地图
   • 用户流程
   • 系统拓扑
   • 决策树
   • 路线图
   • 战略地图
   • 流程流
4. 仅在 references/diagram-thinking-profiles.json 中阅读所选类型的配置文件。
5. 在编写单个图表时阅读 references/spec.md。使用 scripts/diagram_skills.py new 创建生产就绪的初始文件。
6. 对于高密度分层架构信息图、部分网格、侧边列表、流程条和原则卡片，阅读 references/enterprise-board.md。
7. 安装的技能是完整的生成路径。如果完整 DiagramSkills 仓库检出现也存在，references/workspaces.md、references/imports.md 和 references/editor.md 描述了可选的 Studio 工作流。在提供这些功能前检查仓库的 editor/ 目录是否存在；切勿将其作为生成的前提条件。
8. 仅在选择主题、品牌令牌、节点/边语义或中文/英文标签处理时阅读 references/visual-language.md。
9. 应用 references/quality-contract.md。生成的文件只是候选文件，直到内容审查、严格验证和视觉审查通过。

输入合约

接受自然语言或结构化字段。保留用户提供的值；仅推断低风险的遗漏项。

• goal：图表应支持的决策或问题
• diagram_type：一个受支持的 slug；当省略时从意图推断
• audience：例如，高管、产品、工程、客户
• narrative / scope：五秒钟的故事和明确的输入/输出边界
• must_show / emphasize / deemphasize：布局前的内容优先级
• uncertainties / assumptions：未提供的事实和低风险的解释
• content_risks / quality_questions：图表可能误导的方式以及渲染后检查项
• content：参与者、系统、步骤、能力、里程碑或决策
• relationships：数据、控制、成功、错误、异步和反馈链接
• boundaries：所有权、生命周期阶段、层、领域或信任区域
• composition：对于高密度企业概览使用 board；对于较小关系图使用 graph
• lanes：泳道图的有序所有者或角色
• rank：当自动排序不可接受时，显式的非负层级级别
• language：默认优先中文；保留已建立的英文技术术语
• theme：paper、notion、spectrum、blueprint 或 terminal
• brand：覆盖在预设上的许可十六进制颜色令牌
• views：可选的仓库-Studio 概览和详细视图；使用 child_view 连接
• imports：可选的仓库-Studio Mermaid 源或 CSV 表格
• outputs：默认输出完成的 SVG/HTML 加上源 JSON 和诊断信息；本地光栅化器可用时输出 PNG

仅在一个未决的选择对含义、发布安全性或所需输出产生实质影响时才提问。否则，从类型指南中选择常规布局并说明假设。

命令

从技能文件夹运行：

python3 scripts/diagram_brief.py work/architecture.brief.json --strict
python3 scripts/diagram_skills.py types
python3 scripts/diagram_skills.py png-backend
python3 scripts/diagram_skills.py new system-architecture --output work/architecture.json
python3 scripts/diagram_skills.py validate work/architecture.json --strict
python3 scripts/diagram_skills.py render work/architecture.json --output-dir output --strict
python3 scripts/diagram_brief.py work/architecture.brief.json --spec work/architecture.json --strict --reviewed
python3 scripts/diagram_skills.py review work/architecture.json --quality output/architecture.quality.json --brief work/architecture.brief.json --artifact output/architecture.svg

render 总是写入 .svg、.html 和哈希绑定的 .quality.json 收据；当提供 --png 且 png-backend 报告支持的光栅化器时，它也写入 .png。结构上有效的渲染保持 pending-review 状态，直到 review 验证源文件、已检查的产物、已审查的简要文档及其哈希值。失败的 PNG 请求永远不会留下通过的收据。

安装的技能在生成方面是自包含的。浏览器工作区、Mermaid/CSV 导入和多视图编辑是仓库的伴生组件，仅从包含 editor/ 的完整检出中可用。

不可协商的行为

• 在编写重要图表之前，构建并验证简洁的 Diagram Brief。分享设计决策和证据，而不是私有的思维链。
• 优先选择一个主要信息和一个阅读方向。将超过 14 个节点的图图拆分；结构化的企业 board 可以有目的地包含 20–45 张简洁卡片，分布在 3–6 个扫描带中。
• 使用有序的 lanes 表示所有权，使用节点 rank 表示手动层次。使用 groups 表示语义封装；不要使一个字段同时表示两者。
• 将密集的概览链接到聚焦的 child_view 详细信息，而不是缩小标签。
• 将有意的返回路径标记为 feedback；未标记的循环会导致验证失败。
• 使用语义化边类型，而非装饰性颜色。当两个或更多边含义需要解释时显示图例。
• 仅允许节点链接到 https、http、mailto 或页面片段。可执行的 URL 方案被拒绝。
• 保持中文标签简洁，并将稳定的英文技术术语放在副标题中。拆分过载节点而不是缩小文本。
• 对于管道、路线图、拓扑和反馈循环，优先使用 LR；对于层次、决策、策略和用户旅程，优先使用 TB。
• 运行简要文档和图表的严格验证。检查 SVG 或全尺寸 PNG，用清晰的证据回答每个类型配置文件的每个问题，并使用 review 完成哈希绑定的质量收据。
• 当用户要求图表时，不要仅编写 Mermaid/JSON 就声称完成。渲染并返回实际的视觉效果。
• 将 .brief.json 和源 JSON 放在交付物旁边，以确保含义和像素保持可重现和可审查。
• 当完整仓库检出提供 Studio 导入时，将导入的内容视为不受信任的。Mermaid 在严格模式下渲染，CSV 变为类型化字段，任意 CSS 或可执行链接被拒绝。

输出选择

• PNG：当 png-backend 报告支持本地光栅化器时的首选预览；否则首先显示 SVG。
• Diagram Brief JSON：内容意图、范围、不确定性、优先级、风险和审查证据。
• SVG：可扩展的文档和源控制。
• HTML：响应式查看、平移/缩放、主题切换、下载和可点击节点。
• Quality JSON：机器可读的验证证据。
• Workspace JSON：可选的仓库-Studio 格式，用于浏览器编辑、混合 Mermaid/原生视图、离线持久化和下钻。

扩展

仅当新类型具有不同的信息模型或布局合约时才添加新的图表类型。将其 slug 添加到 DIAGRAM_TYPES、schema 枚举、templates/<slug>.json、references/diagram-types/<slug>.md 和 references/diagram-thinking-profiles.json；然后添加严格的渲染和思考配置文件测试。在一个适配器中扩展 CSV 映射，并在 Zod 和 JSON Schema 中扩展 workspace 字段。新主题必须跨浅色/深色渲染保留节点和边语义。