Skill 实践：技术图表演示与选型

讲解一个 Skill 时，我们可能同时遇到几个问题：它经过哪些步骤？谁调用谁？失败后能否重试？运行记录又存在哪里？

这些问题不能只靠一张流程图回答。步骤适合用流程图，调用先后适合用时序图，数据关系则适合用 ER 图。先确定读者需要理解什么，再选择图形，通常比先画一个大框图更有效。

下面展示本专栏当前接入的全部八类 Mermaid 图表。示例围绕 Skill 的调用、建模和开发展开，均为教学模型，不代表某个产品的真实架构、执行策略或统计数据。点击任意图形可全屏查看，支持缩放、拖动和滚动。

图形边框占满正文宽度，图面水平居中。长图默认限制在 560px 高度内，可在图内滚动；移动端最高 420px。以下示例穿插使用技术蓝、自然绿与手绘风，展示同一套语法如何适配不同的教学内容。主题只改变视觉呈现，不改变图中的执行关系。

先按问题选图复制标题链接

只有第一类是严格意义上的流程图。其他图形分别表达交互、结构、状态、关系、分类、计划和比例；它们可以组合使用，而不是互相替代。

流程图：表达步骤、条件与回路复制标题链接

适用场景： 解释业务处理流程、Skill 匹配、输入校验、构建与发布步骤。读者最关心的是“下一步是什么”和“条件不满足怎么办”。

下面的例子从用户请求开始，区分“找到 Skill”和“没有匹配项”，再检查执行结果。矩形表示处理，菱形表示判断，箭头表示执行方向。

这里的回路表示一次可选择的调整过程，不代表系统应该无限自动重试。设计真实流程时，需要补充重试上限、人工确认和终止条件。

写作要点： TD 表示从上到下，LR 表示从左到右；--> 连接步骤，{条件} 表示判断，-->|是| 为分支添加说明。节点里只放关键动作，细节留在正文中。

当你需要解释“执行器先调用工具，工具再访问外部服务”，换成下面的时序图会更清楚。

时序图：表达参与方之间的调用复制标题链接

适用场景： API 请求链路、认证流程、Agent 工具调用、异步消息交互。它重点回答“谁发起请求、谁等待结果、失败由谁接收”。

从上往下读消息顺序，横向看消息的发送方与接收方。participant 定义参与者，->> 表示发送消息，-->> 常用于画返回消息；alt / else / end 表示条件分支。

图中的上下距离不是实际耗时。若要说明延迟，应补充测量数据，不能只根据箭头间距判断性能。异步调用也应明确标注，不要仅靠虚线暗示。

类图：表达对象结构与职责复制标题链接

适用场景： 讨论领域对象、接口职责、类之间的依赖，或者向 AI 说明准备实现的代码结构。

同样是一个 Skill，可以把“定义信息”“执行动作”“执行结果”分成三个职责，而不是放进一个对象里。

class 定义对象，花括号内列出属性或方法；..> 在这里表示依赖。读者可以据此讨论：定义是否包含执行逻辑？执行器怎样返回失败？哪些字段必须存在？

类图不等于数据库设计，也不要求代码必须采用面向对象实现。函数和 TypeScript 类型同样可以承接这些职责，但实现前要另行确认字段类型和接口契约。

状态图：表达生命周期与合法迁移复制标题链接

适用场景： 任务执行、订单处理、文件上传、连接状态和会话生命周期。当问题是“这个对象现在是什么状态，还能做什么”时，状态图比流程图更直接。

stateDiagram-v2 声明状态图，state "中文名称" as 标识 为状态取别名，[*] 表示起点或终点。箭头上的文字描述触发事件或迁移条件。

这个模型把“失败”和“最终结束”分开：失败后可能重试，也可能结束。真实实现还要保证取消确实传播到执行中的任务，而不只是把界面改成“已取消”。

ER 图：表达实体、主外键与关联复制标题链接

适用场景： 设计数据库、解释一对多关系、评审关联记录的归属。ER 是实体关系（Entity Relationship）的缩写。

下面以执行记录连接用户与 Skill：一个用户可以产生多条执行记录，一个 Skill 也可以被执行多次。

PK 表示主键，FK 表示外键；|| 表示恰好一个，o{ 表示零个或多个。因此图中的每条执行记录对应一个用户和一个 Skill，用户与 Skill 可以暂时没有执行记录。

这只是逻辑关系示意。数据库是否真正建立外键约束、如何隔离租户、删除后是否保留历史记录，都需要单独设计。如果一次执行需要冻结 Skill 的版本，还应保存版本引用或快照。

脑图：表达主题分类与拆解复制标题链接

适用场景： 学习笔记、需求讨论、知识分类、Skill 编写清单。脑图适合在方案还没有形成确定流程时，先把问题展开。

mindmap 之后用缩进表达父子层级，root((主题)) 定义中心主题。上图中的分支是分类，不表示“先确定用户，再处理权限”的固定执行顺序。

如果分支之间存在大量跨级依赖，脑图会变得难以阅读。可以先用脑图梳理范围，再为关键链路单独画流程图或时序图。

甘特图：表达排期与前置依赖复制标题链接

适用场景： 项目计划、迁移安排、发布准备。读者需要知道“何时做、做多久、前一项没完成会影响什么”。

dateFormat 指定输入日期格式，tickInterval 1day 让时间轴按天显示刻度；section 划分阶段，after 表达前置任务，milestone 标记里程碑。这里的日期和工期仅用于演示，不能直接当作真实项目估算。

甘特图展示计划，不展示执行器的实时运行状态。任务进度变化后，需要更新数据；仅把任务画在时间轴上，并不能证明依赖、人员或资源已经落实。

饼图：表达同一整体中的组成比例复制标题链接

适用场景： 少量分类的占比说明，例如同一批任务的最终结果分布。各项应采用相同统计口径，避免重复计数。

pie 声明饼图，showData 同时展示数值，分类名后填写数值。上图假设统计的是已经结束的 100 次任务，每个任务只计入一个最终结果。

这里的 72、18、10 都是示意数字，不是产品成功率。如果同一任务的每次重试都计一次，分母就变成了“执行尝试次数”，不能继续称为“任务数”。

分类过多、需要比较细小差异，或需要观察每天的变化时，不宜使用饼图。可以改用表格；柱状图和折线图不在当前页面接入的八类语法范围内。

在 Markdown 中怎样编写复制标题链接

以上图形都来自 Markdown 正文中的 mermaid 代码围栏，不是图片。最小写法如下：

```mermaid title="示例流程" theme="ocean" maxHeight="560"
flowchart LR
  A(输入):::accent --> B(处理) --> C(输出):::success
```

title 用作图注和全屏标题，theme 可选 ocean（技术蓝）、forest（自然绿）、sketch（手绘风）。maxHeight 可填写 240–960 的整数，用于正文预览；全屏不受此高度限制。图形本身的结构由围栏内的 Mermaid 语法决定。修改正文后，预览会重新渲染。

流程图节点还可以引用内置语义色：:::accent 强调入口，:::warning 标记判断，:::success 标记成功，:::danger 标记异常，:::muted 弱化辅助说明；默认节点使用主色。无需手写颜色或 CSS，也应保留分支文字，让读者不依赖颜色就能理解图形。

本专栏的写作限制如下：

• 当前支持本页展示的八类图形，不等于开启 Mermaid 的全部图表类型。
• 单图最多 24000 字符、500 行；连线预算配置为 100，复杂图应拆分。
• 使用受控主题、语义色与系统字体，不额外上传字体文件；手绘风只改变图形笔触，不加载手写字体。
• 不接受 HTML、外部资源、点击脚本、init 配置，以及 classDef、style、linkStyle 样式指令。
• 图形语法出错时，仅当前图显示错误和可展开源码，其余正文仍可阅读。

这些限制是本项目的渲染策略，不是 Mermaid 本身的全部限制。组件接入与维护说明位于仓库的 packages/docs/docs/mermaid.md。

怎样让 AI 帮忙画对图复制标题链接

比起只说“画一张架构图”，更有效的输入是：你要解释的问题、已有事实，以及不能省略的边界。例如：

请根据下面的 Skill 调用记录生成 Mermaid 时序图。参与者只包含用户、Agent、执行器和业务工具；明确标注成功与失败分支。没有日志证据的调用不要补画，也不要把消息顺序解释为耗时。输出使用本项目支持的 mermaid 围栏，不使用 HTML、外部资源或自定义样式指令。

图生成后，再核对三件事：箭头方向是否符合真实调用，判断分支是否有出口，图中对象和字段是否能在代码或需求中找到依据。图能渲染只是第一步，表达的关系正确才有教学价值。

需要继续扩展语法时，可查阅 Mermaid 官方图表目录。先检查本项目是否支持对应类型，再把示例放进正文。