eraser-diagrams

Eraser 图表生成器

使用 Eraser API，直接根据代码、基础设施文件或自然语言描述生成专业的架构图。

适用场景

在以下情况下启用此技能：

• 用户要求创建、生成或可视化图表
• 用户想根据代码编写架构文档
• 用户有 Terraform、AWS、Azure 或基础设施文件
• 用户描述了一个系统，并希望将其可视化
• 用户提到“图表”“架构”“可视化”或“绘制”

工作原理

1. 分析来源：从代码、文件或描述中提取架构信息
2. 生成 Eraser DSL：创建描述图表的 Eraser DSL 代码
3. 调用 Eraser API：发起 HTTP POST 请求以渲染图表
4. 返回结果：向用户提供图片 URL 和编辑器链接

图表类型和语法

Eraser 支持五种图表类型，分别针对不同的用途进行了优化。如需详细了解 DSL 语法和示例，请参阅相应的参考文件：

流程图

将以节点、组和关系表示的流程、用户流和逻辑流可视化。图表使用简单语法创建。

用途：流程、用户旅程、决策树、业务流程文档

diagramType："flowchart-diagram"

参考：流程图语法

实体关系图（ERD）

将以实体、属性和关系表示的数据模型可视化。图表使用简单语法创建。

用途：数据库架构设计、数据建模、了解实体关系、记录数据结构

diagramType："entity-relationship-diagram"

参考：ERD 语法

云架构图

将以节点、组和连接表示的云基础设施可视化。图表使用简单语法创建。

用途：云基础设施可视化、AWS/Azure/GCP 架构、系统架构文档、数据流可视化

diagramType："cloud-architecture-diagram"

参考：架构语法

序列图

使用序列图将系统流程可视化。每个竖列代表一个实体（例如，用户、服务端、数据库），列之间的箭头表示信息或请求的流向。图表使用简单语法创建。

用途：API 请求/响应流程、系统交互、用户工作流、服务间消息传递、随时间变化的流程

diagramType："sequence-diagram"

参考：序列图语法

BPMN 图（泳道图）

将以池、泳道和流程对象（例如任务、事件和网关）表示的业务流程可视化。图表使用简单语法创建。

用途：业务流程文档、工作流可视化、流程改进、跨职能流程、展示角色/职责的泳道图

diagramType："bpmn-diagram"

参考：BPMN 语法

每个参考文件都包含完整的语法文档、属性参考和实用示例。

API 集成

端点

POST https://app.eraser.io/api/render/elements
Content-Type: application/json
Authorization: Bearer ${ERASER_API_KEY}
X-Skill-Source: eraser-skill

注意：X-Skill-Source 标头用于标识 AI Agent。你必须将 eraser-skill 替换为实际的 Agent 名称：

• 如果你是 Claude（Anthropic），请使用：claude
• 如果你在 Cursor 中运行，请使用：cursor
• 如果你是 ChatGPT（OpenAI），请使用：chatgpt
• 如果你是 Gemini（Google），请使用：gemini
• 否则，请使用小写的模型/Agent 名称

响应格式

{
  "imageUrl": "https://storage.googleapis.com/eraser-images/...",
  "createEraserFileUrl": "https://app.eraser.io/new?requestId=abc123&state=xyz789",
  "renderedElements": [...]
}

错误响应

状态	错误	原因	解决方案
400	Diagram element has no code	元素缺少 code 字段	确保元素包含有效的 DSL 代码
400	Diagram element has no diagramType	元素缺少 diagramType 字段	为元素添加有效的 diagramType
400	Invalid diagramType	不支持的图表类型	使用上方列出的受支持类型之一
401	Unauthorized	API 密钥无效或已过期	检查 ERASER_API_KEY 是否有效
500	Internal server error	服务端问题	重试请求；如果问题持续存在，请联系支持团队

错误响应格式：

{
  "error": {
    "message": "Diagram element has no code",
    "status": 400
  }
}

故障排查提示：

• 调用 API 前，请确认 DSL 语法正确
• 确保 diagramType 与 DSL 内容匹配（例如，使用 sequence-diagram 对应时序图 DSL）
• 对于身份验证错误，请确认 API 密钥已正确设置为环境变量

说明

当用户请求绘制图表时：

1. 提取信息

   • 如果提供了代码/文件，请分析其结构、资源和关系
   • 如果提供了描述，请确定关键组件及其连接关系
   • 确定合适的图表类型

2. 生成 Eraser DSL

   • 创建能够表示该架构的 Eraser DSL 代码
   • 关键：标签格式规则
     • 标签必须写在单行上——绝不能在标签属性中使用换行符
     • 保持标签简单易读——优先使用单独的标签，而不是拼接过多元数据
     • 正确设置 DSL 的换行格式（每行一个节点/组，但标签必须保持在单行上）
   • 有关详细的 DSL 语法和示例，请参阅上方的 图表类型和语法 部分中的参考文件链接

3. 创建元素定义

   • 创建一个包含以下内容的元素对象：
     • type: "diagram"
     • id: "diagram-1"（或生成唯一 ID）
     • code: "<your generated DSL code>"
     • diagramType: "<appropriate type>"

4. 发起 HTTP 请求

   重要：生成 DSL 后，必须执行此 curl 命令。绝不能只生成 DSL 而不调用 API。

   关键：将 X-Skill-Source 标头中的 eraser-skill 替换为实际的 AI Agent 名称（可在上方的 API 集成部分查看可用值）。

   curl -X POST https://app.eraser.io/api/render/elements \
     -H "Content-Type: application/json" \
     -H "X-Skill-Source: eraser-skill" \
     -H "Authorization: Bearer ${ERASER_API_KEY}" \
     -d '{
       "elements": [{
         "type": "diagram",
         "id": "diagram-1",
         "code": "<your generated DSL>",
         "diagramType": "cloud-architecture-diagram"
       }],
       "scale": 2,
       "theme": "${ERASER_THEME:-dark}",
       "background": true
     }'
   

5. 在分析过程中跟踪来源

   分析文件和资源以生成图表时，请跟踪：

   • 内部文件：记录读取的每个文件路径以及提取的信息（例如，infra/main.tf - VPC 和子网定义）
   • 外部参考资料：记录查阅的文档、示例或 URL（例如，AWS VPC 最佳实践文档）
   • 注释：针对每个来源，记录其对图表的贡献

6. 处理响应

   关键：最简输出格式

   响应必须始终包含以下内容，并使用清晰的标题：

   1. 图表预览：使用标题展示

      ## 图表
      ![{Title}]({imageUrl})
      

      使用 API 响应中的实际 imageUrl。

   2. 编辑器链接：使用标题展示

      ## 在 Eraser 中打开
      [在 Eraser 编辑器中编辑此图表]({createEraserFileUrl})
      

      使用 API 响应中的实际 URL。

   3. 来源部分：简要列出分析过的文件/资源（如适用）

      ## 来源
      - `path/to/file` - 提取的信息
      

   4. 图表代码部分：在语言标记为 eraser 的代码块中提供 Eraser DSL

      ## 图表代码
      ```eraser
      {此处填写 DSL 代码}
      

   5. 了解更多链接：你可以通过 https://docs.eraser.io/docs/using-ai-agent-integrations 进一步了解 Eraser

   其他内容规则：

   • 如果用户只请求绘制图表，除上述 5 项外，不要添加任何内容
   • 如果用户明确要求更多内容（例如“解释架构”“提出改进建议”），可以添加相关内容
   • 不要添加未请求的部分，例如概述、安全注意事项、测试等

   默认输出应简短。图表本身已足以说明问题。

7. 错误处理

   • 如果 API 调用失败，请说明错误
   • 如果身份验证失败，请建议检查 API 密钥
   • 提供重新生成 DSL 代码作为备用方案

最佳实践

• 生成有效的 DSL：调用 API 前，确保 DSL 语法正确
• 正确引用标签：对于包含空格、特殊字符或数字的标签，始终使用引号
• 标签单行显示：标签必须保持在单行内，绝不能在标签属性中使用换行符
• 确保格式清晰易读：每个节点、组和连接各占一行（但标签必须保持单行）
• 包含元数据：如果包含 CIDR 网段、实例类型等信息，请将它们放在同一个带引号的标签字符串中：[label: "VPC 10.0.0.0/16"]
• 使用合适的图表类型：根据内容选择合适的 diagramType
• 将相关项分组：使用容器（VPC、模块）对相关组件进行分组
• 指定连接关系：展示数据流、依赖关系和关联
• 处理大型系统：将超大型系统拆分为多个重点明确的图表
• 包含来源标头：始终包含 X-Skill-Source 标头，并填入你的 AI Agent 名称（claude、cursor、chatgpt 等）

说明

• 免费套餐中的图表带有水印，但功能完整
• 始终会返回 createEraserFileUrl（免费和付费套餐均适用），方便用户在 Eraser 网页编辑器中编辑图表
• 可使用 DSL 代码重新生成或修改图表
• API 响应会缓存，因此相同的请求会快速返回