generating-mermaid-diagrams
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinesegenerating-mermaid-diagrams: Salesforce Diagram Generation
generating-mermaid-diagrams：Salesforce图表生成
Use this skill when the user needs text-based diagrams: Mermaid diagrams for architecture, OAuth, integration flows, ERDs, or Agentforce structure, plus ASCII fallback when plain-text compatibility matters.
当用户需要基于文本的图表时使用此技能：用于架构、OAuth、集成流程、ERD或Agentforce结构的Mermaid图表，以及在需要纯文本兼容性时提供ASCII格式备选。
Scope
适用范围
In Scope
适用场景
Use when the user wants:
generating-mermaid-diagrams- Mermaid output
- ASCII fallback diagrams
- architecture, sequence, flowchart, or ERD views in markdown-friendly form
- diagrams that can live directly in docs, READMEs, or issues
当用户有以下需求时使用：
generating-mermaid-diagrams- Mermaid格式输出
- ASCII格式备选图表
- 兼容Markdown的架构图、序列图、流程图或ERD视图
- 可直接嵌入文档、README或问题中的图表
Out of Scope — Delegate elsewhere when the user wants:
不适用场景 — 当用户有以下需求时请转交其他技能：
- rendered PNG/SVG images or polished mockups → generating-visual-diagrams
- non-Salesforce systems only → use a more general diagramming skill
- object discovery before an ERD → generating-custom-object or generating-custom-field
- 渲染后的PNG/SVG图像或精美的原型图 → generating-visual-diagrams
- 仅针对非Salesforce系统 → 使用更通用的图表生成技能
- 生成ERD前的对象发现 → generating-custom-object 或 generating-custom-field
Supported Diagram Families
支持的图表类型
| Type | Preferred Mermaid form | Typical use |
|---|---|---|
| OAuth / auth flows | | Authorization Code, JWT, PKCE, Device Flow |
| ERD / data model | | object relationships and sharing context |
| integration sequence | | request/response or event choreography |
| system landscape | | high-level architecture |
| role / access hierarchy | | users, profiles, permissions |
| Agentforce behavior map | | agent → topic → action relationships |
| 类型 | 推荐的Mermaid形式 | 典型用途 |
|---|---|---|
| OAuth / 认证流程 | | 授权码、JWT、PKCE、设备流程 |
| ERD / 数据模型 | | 对象关系与共享上下文 |
| 集成序列 | | 请求/响应或事件编排 |
| 系统全景 | | 高层架构 |
| 角色/权限层级 | | 用户、配置文件、权限 |
| Agentforce行为映射 | | Agent→主题→动作关系 |
Required Context to Gather First
需先收集的必要上下文
Ask for or infer:
- diagram type
- scope and entities / systems involved
- output preference: Mermaid only, ASCII only, or both
- whether styling should be minimal, documentation-first, or presentation-friendly
- for ERDs: whether org metadata is available for grounding
询问或推断：
- 图表类型
- 涉及的范围和实体/系统
- 输出偏好：仅Mermaid、仅ASCII，或两者都要
- 样式需求：极简风格、文档优先，或适合演示
- 针对ERD：是否有可用的组织元数据作为基础
Recommended Workflow
推荐工作流程
1. Pick the right diagram structure
1. 选择合适的图表结构
- use for time-ordered interactions
sequenceDiagram - use for ERDs and capability maps
flowchart LR - keep a single primary story per diagram when possible
- 针对按时间顺序的交互使用
sequenceDiagram - 针对ERD和能力映射使用
flowchart LR - 尽可能让每个图表只聚焦一个核心主题
2. Gather data
2. 收集数据
For ERDs and grounded diagrams:
- use generating-custom-object or generating-custom-field when real schema discovery is needed
- optionally use the local metadata helper script for counts / relationship context when appropriate
针对ERD和基于元数据的图表：
- 当需要真实的 schema 发现时，使用generating-custom-object或generating-custom-field
- 必要时可使用本地元数据辅助脚本获取数量/关系上下文
3. Generate Mermaid first
3. 先生成Mermaid图表
Apply:
- accurate labels
- simple readable node text
- consistent relationship notation
- restrained styling that renders cleanly in markdown viewers
遵循以下规则：
- 标签准确
- 节点文本简洁易读
- 关系符号保持一致
- 采用简洁样式，确保在Markdown查看器中清晰渲染
4. Add ASCII fallback when useful
4. 在需要时添加ASCII备选
Provide an ASCII version when the user wants terminal compatibility or plaintext documentation.
当用户需要终端兼容性或纯文本文档时，提供ASCII版本。
5. Explain the diagram briefly
5. 简要解释图表
Call out the key relationships, flow direction, and any assumptions.
指出关键关系、流向以及所有假设前提。
High-Signal Rules
核心规则
For sequence diagrams
针对序列图
- use when step order matters
autonumber - distinguish requests vs responses clearly
- use notes sparingly for protocol detail
- 当步骤顺序重要时使用
autonumber - 清晰区分请求与响应
- 仅在必要时添加协议细节注释
For ERDs
针对ERD
- prefer
flowchart LR - keep object cards simple
- use clear relationship arrows
- avoid field overload unless the user explicitly asks for field-level detail
- color-code object types only when it improves readability
- 优先使用
flowchart LR - 保持对象卡片简洁
- 使用清晰的关系箭头
- 除非用户明确要求字段级细节，否则避免过多字段
- 仅在提升可读性时对对象类型进行颜色编码
For ASCII output
针对ASCII输出
- keep width reasonable
- align arrows and boxes consistently
- optimize for readability over decoration
- 保持宽度合理
- 箭头和方框对齐一致
- 优先优化可读性而非装饰性
Output Format
输出格式
markdown
undefinedmarkdown
undefined<Diagram Title>
<图表标题>
Mermaid Diagram
Mermaid图表
mermaid
<diagram>mermaid
<diagram>ASCII Fallback
ASCII备选
text
<ascii>text
<ascii>Notes
说明
- <key point>
- <assumption or limitation>
---- <关键点>
- <假设或限制>
---Cross-Skill Integration
跨技能集成
| Need | Delegate to | Reason |
|---|---|---|
| real object / field definitions | generating-custom-object / generating-custom-field | grounded ERD generation |
| rendered diagram / image output | generating-visual-diagrams | visual polish beyond Mermaid |
| connected-app auth setup context | configuring-connected-apps | accurate OAuth flows |
| Agentforce logic visualization | developing-agentforce | source-of-truth behavior details |
| Flow behavior diagrams | generating-flow | actual Flow logic grounding |
| 需求 | 转交至 | 原因 |
|---|---|---|
| 真实对象/字段定义 | generating-custom-object / generating-custom-field | 生成基于真实数据的ERD |
| 渲染后的图表/图像输出 | generating-visual-diagrams | 提供超越Mermaid的视觉优化 |
| 连接应用认证设置上下文 | configuring-connected-apps | 生成准确的OAuth流程 |
| Agentforce逻辑可视化 | developing-agentforce | 获取真实的行为细节 |
| Flow行为图表 | generating-flow | 基于真实Flow逻辑生成 |
Gotchas
常见问题
| Issue | Resolution |
|---|---|
| Mermaid renderer not available | Provide ASCII fallback automatically; note that the Mermaid block still carries the diagram for copy-paste into a renderer |
| ERD becomes unreadable with too many objects | Split into sub-diagrams by domain (Sales, Service, etc.) and link them in prose |
| Sequence diagram step order unclear | Use |
| OAuth flow actors differ by grant type | Read the relevant asset template first before generating to avoid actor mismatch |
| 问题 | 解决方案 |
|---|---|
| Mermaid渲染器不可用 | 自动提供ASCII备选；同时说明Mermaid代码块仍可复制到渲染器中使用 |
| ERD因对象过多而难以阅读 | 按领域（销售、服务等）拆分为子图表，并在文本中建立链接 |
| 序列图步骤顺序不清晰 | 使用 |
| OAuth流程参与者因授权类型而异 | 生成前先阅读相关资产模板，避免参与者不匹配 |
Reference File Index
参考文件索引
Conventions & rules — read before generating
约定与规则 — 生成前阅读
- references/diagram-conventions.md — consistency rules for all diagram types
- references/mermaid-reference.md — Mermaid syntax quick reference
- references/usage-examples.md — worked examples per diagram type
- references/diagram-conventions.md — 所有图表类型的一致性规则
- references/mermaid-reference.md — Mermaid语法速查
- references/usage-examples.md — 各图表类型的示例
Styling
样式
- references/mermaid-styling.md — theming and annotation patterns
- references/color-palette.md — color-blind-friendly palette with hex values
- references/erd-conventions.md — ERD-specific layout and notation rules
- references/mermaid-styling.md — 主题与注释模式
- references/color-palette.md — 适合色弱人群的调色板及十六进制值
- references/erd-conventions.md — ERD专属布局与符号规则
Preview
预览
- references/preview-guide.md — how to render Mermaid locally
- scripts/README.md — setup and usage instructions for all scripts in this skill
- scripts/mermaid_preview.py — live-reload preview server; run to preview diagrams in browser
- scripts/query-org-metadata.py — queries org schema to ground ERD generation
- references/preview-guide.md — 如何在本地渲染Mermaid图表
- scripts/README.md — 本技能中所有脚本的安装与使用说明
- scripts/mermaid_preview.py — 实时重载预览服务器；运行后可在浏览器中预览图表
- scripts/query-org-metadata.py — 查询组织schema以生成基于真实数据的ERD
OAuth flow templates — load the matching template when generating OAuth diagrams
OAuth流程模板 — 生成OAuth图表时加载匹配的模板
- assets/oauth/authorization-code.md — Authorization Code grant
- assets/oauth/authorization-code-pkce.md — PKCE variant for mobile/SPA
- assets/oauth/jwt-bearer.md — JWT Bearer server-to-server
- assets/oauth/client-credentials.md — Client Credentials service accounts
- assets/oauth/device-authorization.md — Device Flow for CLI/IoT
- assets/oauth/refresh-token.md — Refresh Token renewal flow
- assets/oauth/user-agent-social-sign-on.md — User-Agent / Social Sign-On
- assets/oauth/authorization-code.md — 授权码授权流程
- assets/oauth/authorization-code-pkce.md — 适用于移动/SPA的PKCE变体
- assets/oauth/jwt-bearer.md — JWT Bearer服务器到服务器流程
- assets/oauth/client-credentials.md — 客户端凭证服务账户流程
- assets/oauth/device-authorization.md — 适用于CLI/IoT的设备流程
- assets/oauth/refresh-token.md — 刷新令牌续期流程
- assets/oauth/user-agent-social-sign-on.md — 用户代理/社交登录流程
Data model ERD templates — load the matching template when generating ERDs
数据模型ERD模板 — 生成ERD时加载匹配的模板
- assets/datamodel/salesforce-erd.md — core Salesforce objects
- assets/datamodel/sales-cloud-erd.md — Sales Cloud objects
- assets/datamodel/service-cloud-erd.md — Service Cloud objects
- assets/datamodel/b2b-commerce-erd.md — B2B Commerce objects
- assets/datamodel/campaigns-erd.md — Campaigns and campaign member model
- assets/datamodel/consent-erd.md — Consent and privacy objects
- assets/datamodel/files-erd.md — Files and ContentDocument model
- assets/datamodel/forecasting-erd.md — Forecasting objects
- assets/datamodel/fsl-erd.md — Field Service Lightning objects
- assets/datamodel/party-model-erd.md — Party model objects
- assets/datamodel/quote-order-erd.md — Quote and Order objects
- assets/datamodel/revenue-cloud-erd.md — Revenue Cloud objects
- assets/datamodel/scheduler-erd.md — Scheduler objects
- assets/datamodel/territory-management-erd.md — Territory Management objects
- assets/datamodel/salesforce-erd.md — 核心Salesforce对象
- assets/datamodel/sales-cloud-erd.md — 销售云对象
- assets/datamodel/service-cloud-erd.md — 服务云对象
- assets/datamodel/b2b-commerce-erd.md — B2B商务对象
- assets/datamodel/campaigns-erd.md — 营销活动及营销活动成员模型
- assets/datamodel/consent-erd.md — 同意与隐私对象
- assets/datamodel/files-erd.md — 文件与ContentDocument模型
- assets/datamodel/forecasting-erd.md — 预测对象
- assets/datamodel/fsl-erd.md — 现场服务闪电（Field Service Lightning）对象
- assets/datamodel/party-model-erd.md — 参与者模型对象
- assets/datamodel/quote-order-erd.md — 报价与订单对象
- assets/datamodel/revenue-cloud-erd.md — 收入云对象
- assets/datamodel/scheduler-erd.md — 调度器对象
- assets/datamodel/territory-management-erd.md — 区域管理对象
Other diagram templates
其他图表模板
- assets/architecture/system-landscape.md — system landscape overview template
- assets/integration/api-sequence.md — API callout sequence template
- assets/agentforce/agent-flow.md — Agentforce agent → topic → action flow
- assets/role-hierarchy/user-hierarchy.md — role and permission hierarchy template
- assets/architecture/system-landscape.md — 系统全景概览模板
- assets/integration/api-sequence.md — API调用序列模板
- assets/agentforce/agent-flow.md — Agentforce Agent→主题→动作流程模板
- assets/role-hierarchy/user-hierarchy.md — 角色与权限层级模板
Output Expectations
输出预期
Deliverables produced by this skill for each request:
- Mermaid code block — fenced block ready to paste into GitHub, Confluence, or any Mermaid-capable renderer
```mermaid - ASCII fallback (when requested or when Mermaid renderer is unavailable) — text-only diagram using box/arrow characters
- Brief explanation — 2-5 bullet points calling out key relationships, flow direction, and any assumptions or limitations in the diagram
- For ERDs: object cards with field labels and relationship type annotations
- For sequence diagrams: numbered steps () with clear actor labels
autonumber
本技能针对每个请求提供以下交付物：
- Mermaid代码块 — 带围栏的代码块，可直接粘贴到GitHub、Confluence或任何支持Mermaid的渲染器中
```mermaid - ASCII备选（当用户要求或Mermaid渲染器不可用时） — 使用方框/箭头字符的纯文本图表
- 简要说明 — 2-5个要点，指出图表中的关键关系、流向以及所有假设或限制
- 针对ERD：包含字段标签和关系类型注释的对象卡片
- 针对序列图：带编号的步骤（）及清晰的参与者标签
autonumber
Score Guide
评分指南
| Score | Meaning |
|---|---|
| 72–80 | production-ready diagram |
| 60–71 | clear and useful with minor polish left |
| 48–59 | functional but could be clearer |
| 35–47 | needs structural improvement |
| < 35 | inaccurate or incomplete |
| 分数 | 含义 |
|---|---|
| 72–80 | 可直接用于生产环境的图表 |
| 60–71 | 清晰有用，仅需少量优化 |
| 48–59 | 可用但可读性有待提升 |
| 35–47 | 需要结构上的改进 |
| < 35 | 不准确或不完整 |