Eraser 圖表產生器

透過 Eraser API，直接從程式碼、基礎架構檔案或自然語言描述產生專業的架構圖表。

使用時機

在以下情況啟用此技能：

使用者要求建立、產生或視覺化圖表
使用者想要從程式碼記錄架構
使用者有 Terraform、AWS、Azure 或基礎架構檔案
使用者描述一個系統並希望將其視覺化
使用者提及「圖表」、「架構」、「視覺化」或「繪製」

運作方式

分析來源：從程式碼、檔案或描述中提取架構資訊
產生 Eraser DSL：建立描述圖表的 Eraser DSL 程式碼
呼叫 Eraser API：發出 HTTP POST 請求以渲染圖表
回傳結果：向使用者呈現圖片 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 代理。你必須將 eraser-skill 替換為你的實際代理名稱：

如果你是 Claude (Anthropic)，使用：claude
如果你在 Cursor 中執行，使用：cursor
如果你是 ChatGPT (OpenAI)，使用：chatgpt
如果你是 Gemini (Google)，使用：gemini
否則，使用你的模型/代理名稱（小寫）

回應格式

{
  "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 內容相符（例如序列 DSL 搭配 sequence-diagram）
若遇驗證錯誤，請確認 API 金鑰已正確設定為環境變數

操作說明

當使用者要求圖表時：

提取資訊
- 若提供程式碼/檔案，分析其結構、資源和關係
- 若提供描述，識別關鍵元件和連線
- 決定適當的圖表類型
產生 Eraser DSL
- 建立代表架構的 Eraser DSL 程式碼
- 關鍵：標籤格式規則
  - 標籤必須在同一行——絕不要在標籤屬性中使用換行
  - 保持標籤簡單易讀——偏好使用獨立標籤，而非串接過多元資料
  - 使用適當的換行格式化 DSL（每個節點/群組一行，但標籤保持單行）
- 詳細的 DSL 語法和範例，請參閱上方圖表類型與語法章節的參考檔案連結
建立元素定義
- 建立一個元素物件，包含：
  - type: "diagram"
  - id: "diagram-1"（或產生唯一 ID）
  - code: "<your generated DSL code>"
  - diagramType: "<appropriate type>"

發出 HTTP 請求

重要：產生 DSL 後，你必須執行此 curl 指令。絕不要在產生 DSL 後停止而不呼叫 API。

關鍵：將 X-Skill-Source 標頭中的 eraser-skill 替換為你的實際 AI 代理名稱（參閱上方 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
  }'

分析期間追蹤來源

在分析檔案和資源以產生圖表時，追蹤：
- 內部檔案：記錄你讀取的每個檔案路徑以及提取的資訊（例如 infra/main.tf - VPC 和子網路定義）
- 外部參考：記錄參考的任何文件、範例或 URL（例如 AWS VPC 最佳實務文件）
- 註解：對於每個來源，記錄它對圖表的貢獻
處理回應

關鍵：最小輸出格式

你的回應必須始終包含以下元素，並附上清晰的標題：
1. 圖表預覽：以標題顯示
```
## 圖表
![{Title}]({imageUrl})
```
  使用 API 回應中的實際 imageUrl。
2. 編輯器連結：以標題顯示
```
## 在 Eraser 中開啟
[在 Eraser 編輯器中編輯此圖表]({createEraserFileUrl})
```
  使用 API 回應中的實際 URL。
3. 來源章節：簡要列出分析的檔案/資源（若適用）
```
## 來源
- `path/to/file` - 提取的內容
```
4. 圖表程式碼章節：使用 eraser 語言標籤的程式碼區塊中的 Eraser DSL
```
## 圖表程式碼
```eraser
  {DSL code here}
```
5. 了解更多連結：You can learn more about Eraser at https://docs.eraser.io/docs/using-ai-agent-integrations
其他內容規則：
- 如果使用者只要求圖表，則僅包含上述 5 個元素
- 如果使用者明確要求更多（例如「解釋架構」、「建議改進」），你可以包含該額外內容
- 絕不新增未要求的章節，例如概覽、安全性考量、測試等
預設輸出應簡短。圖表圖片本身已足夠說明。
錯誤處理
- 如果 API 呼叫失敗，解釋錯誤
- 如果驗證失敗，建議檢查 API 金鑰
- 提供重新產生 DSL 程式碼作為備援方案

最佳實務

產生有效的 DSL：在呼叫 API 前確保 DSL 語法正確
正確引用標籤：始終引用包含空格、特殊字元或數字的標籤
單行標籤：標籤必須在同一行——絕不要在標籤屬性中使用換行
格式化以提升可讀性：將每個節點、群組和連線放在單獨一行（但標籤保持單行）
包含中繼資料：如果包含 CIDR 區塊、執行個體類型等，將它們放在同一個引用的標籤字串中：[label: "VPC 10.0.0.0/16"]
使用適當的圖表類型：為內容選擇正確的 diagramType
分組相關項目：使用容器（VPC、模組）來分組相關元件
指定連線：顯示資料流、相依性和關係
處理大型系統：將非常大的系統分解為重點圖表
包含來源標頭：始終包含 X-Skill-Source 標頭，並填入你的 AI 代理名稱（claude、cursor、chatgpt 等）

備註

免費方案圖表包含浮水印，但功能完整
createEraserFileUrl 始終回傳（適用於免費和付費方案），允許使用者在 Eraser 網頁編輯器中編輯圖表
DSL 程式碼可用於重新產生或修改圖表
API 回應會快取，因此相同請求會快速回傳

eraser-diagrams

相關技能