用 Mermaid 审查 AI Agent：把审批、失败和停止条件画清楚

一张只有“用户→模型→工具→结果”的图，说明不了 Agent 会不会误执行。做设计评审时，真正值得画出来的是审批位置、失败去向和重试出口。下面给出可粘贴的 Mermaid 文本及四类审查路径；它是设计模板，不是已经部署的权限控制系统。

为什么流程图要先画失败路径？

正常路径通常最容易达成共识，超时后是否重发、拒绝后能否绕过、状态未知时是否查询，才容易造成实际事故。把这些边画在同一张图里，可以让开发、产品和审核者讨论同一套条件，而不各自理解“失败重试”。

先阅读生产级 Agent 工程原则确定系统边界，再画一个任务，不要一开始就把整个多代理架构铺满画布。本例选择“模型提出改动，人工批准后执行”，只讨论控制流，不保证模型提案正确。

如何建立一张可复核的最小图？

打开 aiKit 的 Mermaid Live Editor，替换示例为下方代码。flowchart TD 表示纵向排列；节点 ID 使用英文，中文显示文本放在引号中，便于之后稳定修改。Mermaid 官方语法说明了节点、边和方向的写法。

flowchart TD
  A["收到任务"] --> B["生成候选方案"]
  B --> C{"参数与权限检查通过？"}
  C -->|否| R["拒绝并记录原因"]
  C -->|是| D{"人工批准？"}
  D -->|否| R
  D -->|是| E["使用任务幂等键执行一次"]
  E --> F{"结果确定？"}
  F -->|是| G["记录结果并结束"]
  F -->|否| H["查询操作状态"]
  H --> I{"已完成？"}
  I -->|是| G
  I -->|否或未知| J["转人工处理，不盲目重发"]

幂等键只是设计要求，必须由执行端真正支持；在图上写这几个字不会自动产生去重能力。渲染成功也只能证明语法可解析，不能证明路径安全。

评审时应该沿哪些路径走一遍？

逐条走四个场景：参数错误、人工拒绝、正常完成、执行超时。每条都写预期终点，以及外部系统是否已经发生变化。超时最重要：请求没有返回，不等于操作没有发生。查询结果仍未知时，应保留待处理状态，不能重新生成一个任务 ID 再试。

场景：执行接口超时
执行前：任务 task-001 已批准，幂等键固定
执行后：状态未知，不创建第二个执行请求
下一步：查询 task-001；无法确认时转人工
验收：日志能够关联提案、审批、执行与查询记录

这是审查记录格式，不是测试日志。真正验收时，需使用隔离环境中的可控失败响应，确认代码走到了图上的预期分支。

怎样避免图和代码逐渐脱节？

把 .mmd 源文本与相关功能放在同一个版本控制流程中。改审批策略或重试次数时，同时检查图里的边；评审者对照实现中的状态、事件和权限检查，而不是只看布局。对每个危险动作指定一个入口，避免同一工具存在未画出的旁路。

团队可以借鉴统一 AI 配置的工作流管理共同规则，但审批记录不能仅存在于提示词里。服务端应保存批准人、批准范围和有效期，执行参数变更后重新批准，不能把一次批准当作永久授权。

哪些图形与输入安全问题需要注意？

用简单节点和短标签先确认结构，避免过度依赖编辑器最新形状。在线编辑器与本地渲染器可能使用不同版本；出现语法错误先缩小到最小图，再逐段恢复。官方文档特别提醒小写 end 等语法陷阱，节点 ID 用稳定名称更省事。

不要把 API 密钥、客户数据或内部主机名粘贴到公共编辑器、分享链接或截图里。对外展示用合成名称；不信任的 Mermaid 输入也要限制大小，并在受控环境渲染。本篇没有对 aiKit 部署做浏览器安全审计，不能据此承诺所有编辑内容都不出设备。

什么时候应该把大图拆成多张？

当一张图同时出现业务审批、检索、模型推理和部署细节时，读者通常难以确认哪条边有执行权限。可拆成“业务控制流”和“技术调用时序”两张，用统一任务 ID 关联。每张图只回答一个问题，正文补充未画出的约束。

最终交付源文本、路径审查表和对应代码版本。本文未渲染图片、未运行 Agent，也未验证权限系统；读者可以先粘贴模板检查显示，再与自己系统的真实行为逐项对照。图的价值是暴露问题，不是给系统盖安全章。

FAQ

问：图能渲染就说明流程安全吗？ 答：不能，语法正确与权限实现是两回事。

问：超时后可以直接重发执行请求吗？ 答：不能默认重发，应先确认幂等语义和操作状态。

问：可以把客户数据写进图吗？ 答：公开演示应使用合成名称，不暴露敏感信息。

参考来源

核查日期：2026-10-06。语法依据官方文档，控制流与审查步骤为本文原创设计。

• Mermaid 流程图语法
• Mermaid CLI：源文本进入构建流程