sf-diagram-mermaid
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinesesf-diagram-mermaid: Salesforce Diagram Generation
sf-diagram-mermaid: Salesforce架构图生成工具
Expert diagram creator specializing in Salesforce architecture visualization. Generate clear, accurate, production-ready diagrams using Mermaid syntax with ASCII fallback for terminal compatibility.
专注于Salesforce架构可视化的专业图表生成工具。使用Mermaid语法生成清晰、准确、可用于生产环境的图表,同时支持ASCII格式备选以兼容终端环境。
Core Responsibilities
核心职责
- Diagram Generation: Create Mermaid diagrams from requirements or existing metadata
- Multi-Format Output: Provide both Mermaid code and ASCII art fallback
- sf-metadata Integration: Auto-discover objects/fields for ERD diagrams
- Validation & Scoring: Score diagrams against 5 categories (0-80 points)
- 图表生成:根据需求或现有元数据创建Mermaid图表
- 多格式输出:同时提供Mermaid代码和ASCII艺术图作为备选
- sf-metadata集成:自动发现对象/字段以生成ERD图表
- 验证与评分:从5个维度对图表进行评分(0-80分)
Supported Diagram Types
支持的图表类型
| Type | Mermaid Syntax | Use Case |
|---|---|---|
| OAuth Flows | | Authorization Code, JWT Bearer, PKCE, Device Flow |
| Data Models | | Object relationships with color coding (preferred) |
| Integration Sequences | | API callouts, event-driven flows |
| System Landscapes | | High-level architecture, component diagrams |
| Role Hierarchies | | User hierarchies, profile/permission structures |
| Agentforce Flows | | Agent → Topic → Action flows |
| 类型 | Mermaid语法 | 使用场景 |
|---|---|---|
| OAuth流程 | | 授权码、JWT Bearer、PKCE、设备授权流程 |
| 数据模型 | | 带颜色编码的对象关系图(推荐格式) |
| 集成序列 | | API调用、事件驱动流程 |
| 系统架构 | | 高层级架构、组件图 |
| 角色层级 | | 用户层级、配置文件/权限结构 |
| Agentforce流程 | | Agent → Topic → Action 流程 |
Workflow (5-Phase Pattern)
工作流(5阶段模式)
Phase 1: Requirements Gathering
阶段1:需求收集
Ask the user to gather:
- Diagram type (OAuth, ERD, Integration, Landscape, Role Hierarchy, Agentforce)
- Specific flow or scope (e.g., "JWT Bearer flow" or "Account-Contact-Opportunity model")
- Output preference (Mermaid only, ASCII only, or Both)
- Any custom styling requirements
Then:
- If ERD requested, check for sf-metadata availability
- Create a task list for multi-diagram requests
向用户询问以下信息:
- 图表类型(OAuth、ERD、集成、架构、角色层级、Agentforce)
- 具体流程或范围(例如:“JWT Bearer流程”或“Account-Contact-Opportunity模型”)
- 输出偏好(仅Mermaid、仅ASCII或两者都要)
- 任何自定义样式要求
之后:
- 如果请求生成ERD,检查sf-metadata是否可用
- 为多图表请求创建任务列表
Phase 2: Template Selection
阶段2:模板选择
Select template based on diagram type:
| Diagram Type | Template File |
|---|---|
| Authorization Code Flow | |
| Authorization Code + PKCE | |
| JWT Bearer Flow | |
| Client Credentials Flow | |
| Device Authorization Flow | |
| Refresh Token Flow | |
| Data Model (ERD) | |
| Integration Sequence | |
| System Landscape | |
| Role Hierarchy | |
| Agentforce Flow | |
Template Path Resolution (try in order):
- Marketplace folder (always available):
~/.claude/plugins/marketplaces/sf-skills/sf-diagram-mermaid/assets/[template] - Project folder (if working in sf-skills repo):
[project-root]/sf-diagram-mermaid/assets/[template] - Cache folder (if installed individually):
~/.claude/plugins/cache/sf-diagram-mermaid/*/sf-diagram-mermaid/assets/[template]
Example: To load JWT Bearer template:
Read: ~/.claude/plugins/marketplaces/sf-skills/sf-diagram-mermaid/assets/oauth/jwt-bearer.md根据图表类型选择模板:
| 图表类型 | 模板文件 |
|---|---|
| 授权码流程 | |
| 授权码+PKCE | |
| JWT Bearer流程 | |
| 客户端凭证流程 | |
| 设备授权流程 | |
| 刷新令牌流程 | |
| 数据模型(ERD) | |
| 集成序列 | |
| 系统架构 | |
| 角色层级 | |
| Agentforce流程 | |
模板路径解析顺序:
- 市场文件夹(始终可用):
~/.claude/plugins/marketplaces/sf-skills/sf-diagram-mermaid/assets/[template] - 项目文件夹(如果在sf-skills仓库中工作):
[project-root]/sf-diagram-mermaid/assets/[template] - 缓存文件夹(如果单独安装):
~/.claude/plugins/cache/sf-diagram-mermaid/*/sf-diagram-mermaid/assets/[template]
示例:加载JWT Bearer模板:
读取: ~/.claude/plugins/marketplaces/sf-skills/sf-diagram-mermaid/assets/oauth/jwt-bearer.mdPhase 3: Data Collection
阶段3:数据收集
For OAuth Diagrams:
- Use standard actors (Browser, Client App, Salesforce)
- Apply CloudSundial-inspired styling
- Include all protocol steps with numbered sequence
For ERD/Data Model Diagrams:
- If org connected, query record counts for LDV indicators:
bash
python3 scripts/query-org-metadata.py --objects Account,Contact --target-org myorg - Identify relationships (Lookup vs Master-Detail)
- Determine object types (Standard, Custom, External)
- Generate with color coding (preferred format)
flowchart LR
For Integration Diagrams:
- Identify all systems involved
- Capture request/response patterns
- Note async vs sync interactions
对于OAuth图表:
- 使用标准参与者(浏览器、客户端应用、Salesforce)
- 采用CloudSundial风格的样式
- 包含所有带编号的协议步骤
对于ERD/数据模型图表:
- 如果已连接组织,查询记录数以识别LDV(大数据量)指标:
bash
python3 scripts/query-org-metadata.py --objects Account,Contact --target-org myorg - 识别关系类型(Lookup vs 主从关系)
- 确定对象类型(标准、自定义、外部)
- 生成带颜色编码的图(推荐格式)
flowchart LR
对于集成图表:
- 识别所有涉及的系统
- 捕获请求/响应模式
- 标记异步与同步交互
Phase 4: Diagram Generation
阶段4:图表生成
Generate Mermaid code:
- Apply color scheme from
references/color-palette.md - Add annotations and notes where helpful
- Include autonumber for sequence diagrams
- For data models: Use with object-type color coding
flowchart LR - Keep ERD objects simple - show object name and record count only (no fields)
Generate ASCII fallback:
- Use box-drawing characters:
┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ - Use arrows:
──><──────┼─ - Keep width under 80 characters when possible
Run Validation:
Score: XX/80 ⭐⭐⭐⭐ Rating
├─ Accuracy: XX/20 (Correct actors, flow steps, relationships)
├─ Clarity: XX/20 (Easy to read, proper labeling)
├─ Completeness: XX/15 (All relevant steps/entities included)
├─ Styling: XX/15 (Color scheme, theming, annotations)
└─ Best Practices: XX/10 (Proper notation, UML conventions)生成Mermaid代码:
- 应用中的配色方案
references/color-palette.md - 在需要的地方添加注释和说明
- 为序列图添加自动编号
- 对于数据模型:使用带对象类型颜色编码的格式
flowchart LR - 简化ERD对象:仅显示对象名称和记录数(不显示字段)
生成ASCII备选格式:
- 使用方框绘制字符:
┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ - 使用箭头:
──><──────┼─ - 尽可能将宽度控制在80字符以内
运行验证:
评分: XX/80 ⭐⭐⭐⭐ 评级
├─ 准确性: XX/20 (参与者、流程步骤、关系正确)
├─ 清晰度: XX/20 (易于阅读、标签规范)
├─ 完整性: XX/15 (包含所有相关步骤/实体)
├─ 样式: XX/15 (配色方案、主题、注释)
└─ 最佳实践: XX/10 (规范符号、UML约定)Phase 5: Output & Documentation
阶段5:输出与文档
Delivery Format:
markdown
undefined交付格式:
markdown
undefined📊 [Diagram Title]
📊 [图表标题]
Mermaid Diagram
Mermaid图表
mermaid
[Generated Mermaid code]mermaid
[生成的Mermaid代码]ASCII Fallback
ASCII备选格式
[Generated ASCII diagram][生成的ASCII图表]Key Points
关键点
- [Important note 1]
- [Important note 2]
- [重要说明1]
- [重要说明2]
Diagram Score
图表评分
[Validation results]
undefined[验证结果]
undefinedPhase 5.5: Preview (Optional)
阶段5.5:预览(可选)
Offer localhost preview for real-time diagram iteration. See references/preview-guide.md for setup instructions.
提供本地预览功能以实现实时图表迭代。设置说明请参考references/preview-guide.md。
Mermaid Styling Guide
Mermaid样式指南
Use Tailwind 200-level pastel fills with dark strokes. See references/mermaid-styling.md for complete color palette and examples.
Quick reference:
%%{init: {"flowchart": {"nodeSpacing": 80, "rankSpacing": 70}} }%%
style A fill:#fbcfe8,stroke:#be185d,color:#1f2937使用Tailwind 200级柔和填充色搭配深色描边。完整配色方案和示例请参考references/mermaid-styling.md。
快速参考:
%%{init: {"flowchart": {"nodeSpacing": 80, "rankSpacing": 70}} }%%
style A fill:#fbcfe8,stroke:#be185d,color:#1f2937Scoring Thresholds
评分阈值
| Rating | Score | Meaning |
|---|---|---|
| ⭐⭐⭐⭐⭐ Excellent | 72-80 | Production-ready, comprehensive, well-styled |
| ⭐⭐⭐⭐ Very Good | 60-71 | Complete with minor improvements possible |
| ⭐⭐⭐ Good | 48-59 | Functional but could be clearer |
| ⭐⭐ Needs Work | 35-47 | Missing key elements or unclear |
| ⭐ Critical Issues | <35 | Inaccurate or incomplete |
| 评级 | 分数 | 说明 |
|---|---|---|
| ⭐⭐⭐⭐⭐ 优秀 | 72-80 | 可用于生产环境、内容全面、样式规范 |
| ⭐⭐⭐⭐ 非常好 | 60-71 | 内容完整,仅需少量改进 |
| ⭐⭐⭐ 良好 | 48-59 | 功能可用,但可提升清晰度 |
| ⭐⭐ 需要改进 | 35-47 | 缺少关键元素或内容模糊 |
| ⭐ 严重问题 | <35 | 内容不准确或不完整 |
OAuth Flow Quick Reference
OAuth流程快速参考
| Flow | Use Case | Key Detail | Template |
|---|---|---|---|
| Authorization Code | Web apps with backend | User → Browser → App → SF | |
| Auth Code + PKCE | Mobile, SPAs, public clients | code_verifier + SHA256 challenge | |
| JWT Bearer | Server-to-server, CI/CD | Sign JWT with private key | |
| Client Credentials | Service accounts, background | No user context | |
| Device Authorization | CLI, IoT, Smart TVs | Poll for token after user auth | |
| Refresh Token | Extend access | Reuse existing tokens | |
Templates in .
assets/oauth/| 流程 | 使用场景 | 关键细节 | 模板 |
|---|---|---|---|
| 授权码流程 | 带后端的Web应用 | 用户 → 浏览器 → 应用 → SF | |
| 授权码+PKCE | 移动应用、SPA、公共客户端 | code_verifier + SHA256挑战 | |
| JWT Bearer流程 | 服务器到服务器、CI/CD | 使用私钥签署JWT | |
| 客户端凭证流程 | 服务账户、后台任务 | 无用户上下文 | |
| 设备授权流程 | CLI、IoT、智能电视 | 用户授权后轮询令牌 | |
| 刷新令牌流程 | 延长访问权限 | 重用现有令牌 | |
模板位于目录下。
assets/oauth/Data Model Notation Reference
数据模型符号参考
Preferred Format: flowchart LR
flowchart LR推荐格式:flowchart LR
flowchart LRUse (left-to-right) for data model diagrams. This format supports:
flowchart LR- Individual node color coding by object type
- Thick arrows () for Master-Detail relationships
==> - Left-to-right flow for readability
使用(从左到右)格式绘制数据模型图。该格式支持:
flowchart LR- 按对象类型为单个节点添加颜色编码
- 使用粗箭头()表示主从关系
==> - 从左到右的流向提升可读性
Relationship Arrows
关系箭头
--> Lookup (LK) - optional parent, no cascade delete
==> Master-Detail (MD) - required parent, cascade delete
-.-> Conversion/special relationship (e.g., Lead converts)--> Lookup(查找关系)- 可选父对象,无级联删除
==> 主从关系(MD)- 必填父对象,级联删除
-.-> 转换/特殊关系(例如:Lead转换)Object Node Format
对象节点格式
ObjectName["ObjectName<br/>(record count)"]Example:
Account["Account<br/>(317)"]ObjectName["ObjectName<br/>(记录数)"]示例:
Account["Account<br/>(317)"]Enhanced ERD Features
增强型ERD功能
Object Type Color Coding
对象类型颜色编码
When using the flowchart-based ERD format, objects are color-coded by type:
| Object Type | Color | Fill | Stroke |
|---|---|---|---|
| Standard Objects | Sky Blue | | |
Custom Objects ( | Orange | | |
External Objects ( | Green | | |
当使用基于流程图的ERD格式时,对象按类型进行颜色编码:
| 对象类型 | 颜色 | 填充色 | 描边色 |
|---|---|---|---|
| 标准对象 | 天蓝色 | | |
自定义对象( | 橙色 | | |
外部对象( | 绿色 | | |
LDV (Large Data Volume) Indicators
LDV(大数据量)指标
For orgs with large datasets, query record counts and display LDV indicators:
bash
python3 ~/.claude/plugins/marketplaces/sf-skills/sf-diagram-mermaid/scripts/query-org-metadata.py \
--objects Account,Contact,Opportunity \
--target-org myorgObjects with >2M records display:
LDV[~4M]对于拥有大型数据集的组织,查询记录数并显示LDV指标:
bash
python3 ~/.claude/plugins/marketplaces/sf-skills/sf-diagram-mermaid/scripts/query-org-metadata.py \
--objects Account,Contact,Opportunity \
--target-org myorg记录数>2M的对象将显示:
LDV[~4M]OWD (Org-Wide Defaults)
OWD(组织级默认设置)
Display sharing model on entities: , ,
OWD:PrivateOWD:ReadWriteOWD:Parent在实体上显示共享模型:、、
OWD:PrivateOWD:ReadWriteOWD:ParentRelationship Types
关系类型
| Label | Type | Arrow Style | Behavior |
|---|---|---|---|
| Lookup | | Optional parent, no cascade |
| Master-Detail | | Required parent, cascade delete |
In flowchart format:
- Lookup: (single arrow)
--> - Master-Detail: (thick double arrow)
==>
| 标签 | 类型 | 箭头样式 | 行为 |
|---|---|---|---|
| 查找关系 | | 可选父对象,无级联删除 |
| 主从关系 | | 必填父对象,级联删除 |
在流程图格式中:
- 查找关系:(单箭头)
--> - 主从关系:(粗双箭头)
==>
Data Model Templates
数据模型模板
| Template | Objects | Path |
|---|---|---|
| Core | Account, Contact, Opportunity, Case | |
| Sales Cloud | Account, Contact, Lead, Opportunity, Product, Campaign | |
| Service Cloud | Case, Entitlement, Knowledge, ServiceContract | |
| Campaigns | Campaign, CampaignMember, CampaignInfluence | |
| Territory Management | Territory2, Territory2Model, UserTerritory2Association | |
| Party Model | AccountContactRelation, ContactContactRelation | |
| Quote & Order | Quote, QuoteLineItem, Order, OrderItem | |
| Forecasting | ForecastingItem, ForecastingQuota, OpportunitySplit | |
| Consent (GDPR) | Individual, ContactPointEmail, DataUsePurpose | |
| Files | ContentDocument, ContentVersion, ContentDocumentLink | |
| Scheduler | ServiceAppointment, ServiceResource, ServiceTerritory | |
| Field Service | WorkOrder, ServiceAppointment, TimeSheet | |
| B2B Commerce | WebStore, WebCart, BuyerGroup, BuyerAccount | |
| Revenue Cloud | ProductCatalog, ProductSellingModel, PriceAdjustment | |
| 模板 | 对象 | 路径 |
|---|---|---|
| 核心模型 | Account, Contact, Opportunity, Case | |
| 销售云 | Account, Contact, Lead, Opportunity, Product, Campaign | |
| 服务云 | Case, Entitlement, Knowledge, ServiceContract | |
| 营销活动 | Campaign, CampaignMember, CampaignInfluence | |
| 区域管理 | Territory2, Territory2Model, UserTerritory2Association | |
| 参与方模型 | AccountContactRelation, ContactContactRelation | |
| 报价与订单 | Quote, QuoteLineItem, Order, OrderItem | |
| 预测 | ForecastingItem, ForecastingQuota, OpportunitySplit | |
| 合规(GDPR) | Individual, ContactPointEmail, DataUsePurpose | |
| 文件 | ContentDocument, ContentVersion, ContentDocumentLink | |
| 调度器 | ServiceAppointment, ServiceResource, ServiceTerritory | |
| 现场服务 | WorkOrder, ServiceAppointment, TimeSheet | |
| B2B商务 | WebStore, WebCart, BuyerGroup, BuyerAccount | |
| 收入云 | ProductCatalog, ProductSellingModel, PriceAdjustment | |
ERD Conventions Documentation
ERD约定文档
See for complete documentation of:
references/erd-conventions.md- Object type indicators (,
[STD],[CUST])[EXT] - LDV display format
- OWD display format
- Relationship type labels
- Color palette details
完整文档请参考,包括:
references/erd-conventions.md- 对象类型标识(、
[STD]、[CUST])[EXT] - LDV显示格式
- OWD显示格式
- 关系类型标签
- 配色方案详情
Best Practices
最佳实践
Sequence Diagrams
序列图
- Use for OAuth flows (step tracking)
autonumber - Use for requests,
->>for responses-->> - Use /
activatefor long-running processesdeactivate - Group related actors with blocks
box - Add for protocol details (tokens, codes)
Note over
- 为OAuth流程使用(步骤跟踪)
autonumber - 使用表示请求,
->>表示响应-->> - 为长时间运行的流程使用/
activatedeactivate - 使用块对相关参与者进行分组
box - 为协议细节(令牌、代码)添加注释
Note over
Data Model Diagrams
数据模型图
- Use format (left-to-right flow)
flowchart LR - Keep objects simple: name + record count only (no fields)
- Color code by object type: Blue=Standard, Orange=Custom, Green=External
- Use for Lookup,
-->for Master-Detail relationships==> - Add LDV indicator for objects >2M records
- Use API names, not labels (e.g., not "Accounts")
Account
- 使用格式(从左到右流向)
flowchart LR - 简化对象:仅显示名称+记录数(不显示字段)
- 按对象类型颜色编码:蓝色=标准、橙色=自定义、绿色=外部
- 使用表示查找关系,
-->表示主从关系==> - 为记录数>2M的对象添加LDV指标
- 使用API名称,而非标签(例如:而非“账户”)
Account
Integration Diagrams
集成图
- Show error paths with /
altblockselse - Include timeout handling for external calls
- Mark async calls with notation
-) - Add system icons for clarity (☁️ 🔄 🏭 💾)
- 使用/
alt块显示错误路径else - 包含外部调用的超时处理
- 使用标记异步调用
-) - 添加系统图标以提升清晰度(☁️ 🔄 🏭 💾)
ASCII Diagrams
ASCII图表
- Keep width ≤80 characters
- Use consistent box sizes
- Align arrows clearly
- Add step numbers for sequences
- 宽度保持≤80字符
- 使用一致的方框大小
- 清晰对齐箭头
- 为序列图添加步骤编号
Cross-Skill Integration
跨技能集成
| Skill | When to Use | Example |
|---|---|---|
| sf-metadata | Get real object/field definitions for ERD | Use the sf-metadata skill: "Describe Lead object" |
| sf-connected-apps | Link OAuth flow to Connected App setup | "Generate JWT Bearer diagram for this Connected App" |
| sf-ai-agentscript | Visualize Agentforce agent architecture | "Create flow diagram for FAQ Agent" |
| sf-flow | Document Flow logic as flowchart | "Diagram the approval process flow" |
| 技能 | 使用场景 | 示例 |
|---|---|---|
| sf-metadata | 为ERD获取真实的对象/字段定义 | 使用sf-metadata技能:“描述Lead对象” |
| sf-connected-apps | 将OAuth流程与Connected App设置关联 | “为该Connected App生成JWT Bearer图表” |
| sf-ai-agentscript | 可视化Agentforce代理架构 | “为FAQ Agent创建流程图” |
| sf-flow | 将Flow逻辑文档化为流程图 | “绘制审批流程的图表” |
Dependencies
依赖
Optional: sf-metadata (for ERD auto-discovery)
可选:sf-metadata(用于ERD自动发现)
Example Usage
使用示例
1. OAuth Flow Request
1. OAuth流程请求
User: "Create a JWT Bearer OAuth flow diagram"
You should:
1. Load assets/oauth/jwt-bearer.md
2. Generate Mermaid sequenceDiagram
3. Generate ASCII fallback
4. Score and deliver用户: "创建一个JWT Bearer OAuth流程图表"
你需要:
1. 加载assets/oauth/jwt-bearer.md
2. 生成Mermaid sequenceDiagram
3. 生成ASCII备选格式
4. 评分并交付2. Data Model Request
2. 数据模型请求
User: "Create an ERD for Account, Contact, Opportunity, and Case"
You should:
1. If org connected: Query record counts via query-org-metadata.py
2. Load assets/datamodel/salesforce-erd.md (or cloud-specific template)
3. Generate Mermaid flowchart LR with:
- Object nodes (name + record count, no fields)
- Color coding by object type (Standard=Blue, Custom=Orange)
- Relationship arrows (LK=-->, MD===>)
4. Generate ASCII fallback
5. Score and deliver用户: "为Account、Contact、Opportunity和Case创建ERD图"
你需要:
1. 如果已连接组织:通过query-org-metadata.py查询记录数
2. 加载assets/datamodel/salesforce-erd.md(或云特定模板)
3. 生成Mermaid flowchart LR图,包含:
- 对象节点(名称+记录数)
- 按对象类型颜色编码(蓝色=标准、橙色=自定义)
- 关系箭头(查找关系=-->, 主从关系===>)
4. 生成ASCII备选格式
5. 评分并交付3. Integration Diagram Request
3. 集成图请求
User: "Diagram our Salesforce to SAP integration flow"
You should:
1. Ask clarifying questions (sync/async, trigger, protocol)
2. Load assets/integration/api-sequence.md
3. Generate Mermaid sequenceDiagram
4. Generate ASCII fallback
5. Score and deliver用户: "绘制我们的Salesforce到SAP的集成流程图表"
你需要:
1. 询问澄清问题(同步/异步、触发器、协议)
2. 加载assets/integration/api-sequence.md
3. 生成Mermaid sequenceDiagram
4. 生成ASCII备选格式
5. 评分并交付Notes
注意事项
- Mermaid Rendering: Works in GitHub, VS Code, Notion, Confluence, and most modern tools
- ASCII Purpose: Terminal compatibility, documentation that needs plain text
- Color Accessibility: Palette designed for color-blind accessibility
- Template Customization: Templates are starting points; customize per requirements
- Mermaid渲染:支持在GitHub、VS Code、Notion、Confluence及大多数现代工具中渲染
- ASCII用途:终端兼容性、纯文本文档
- 色彩可访问性:配色方案专为色弱用户设计
- 模板自定义:模板仅作为起点,可根据需求自定义
License
许可证
MIT License.
Copyright (c) 2024-2025 Jag Valaiyapathy
MIT许可证。
版权所有 (c) 2024-2025 Jag Valaiyapathy