进阶 mermaid.ai 2026-11-12 20:48:10 · 23 阅读

第22章 GitHub App:Mermaid 图表同步助手使用指南

第22章 GitHub App

Mermaid 图表同步助手

让 Mermaid 图表在 PR 中随源代码变更自动保持同步。

Mermaid 图表同步助手是一款智能 GitHub App,它会监控你的 pull request,并在相关源文件被修改时更新 Mermaid 图表。当 PR 被打开、同步或重新打开时,该 App 会扫描变更文件,找到与之关联的图表,重新生成受影响的图表,并以明确的机器人署名将更新提交回 PR——让你的文档在代码评审过程中始终保持最新。

快速开始:关联 Mermaid Chart 账户

GitHub App 安装与 OAuth 配置

使用 Mermaid 图表同步助手前,需要将你的 Mermaid Chart 账户关联到该 GitHub App:

第一步:安装 GitHub App

1. 访问 GitHub 上的 Mermaid Diagram Sync Assistant 页面 2. 点击 "Install",选择你的组织或个人账户 3. 选择需要启用图表同步功能的仓库(全部或指定仓库) 4. GitHub 会引导你完成 OAuth 关联

第二步:关联 Mermaid Chart 账户

安装完成后,你会被引导进入 OAuth 流程:

- 如果已登录 Mermaid Chart:GitHub 安装会立即完成关联,并跳转到你的 GitHub 控制面板 - 如果尚未登录:需要先登录 Mermaid Chart,之后两个账户会自动完成关联

第三步:验证关联

关联完成后,访问 Mermaid Chart 的 GitHub 控制面板(/app/github),可以:

- 查看已关联的 GitHub 安装 - 管理仓库访问权限 - 监控图表更新所消耗的 AI 额度

账户管理与切换

更换已关联的 Mermaid Chart 账户

如需登出或切换到其他 Mermaid Chart 账户,必须完整执行一次重新安装流程:

必需步骤:

1. 卸载 GitHub App——进入 GitHub 设置 → Applications → Installed GitHub Apps,移除 "Mermaid Diagram Sync Assistant" 2. 清除已有的关联——确保没有残留的 OAuth 缓存令牌 3. 重新安装 GitHub App——再次访问 Mermaid Diagram Sync Assistant 页面 4. 用新账户完成 OAuth——在 OAuth 流程中登录你想使用的 Mermaid Chart 账户 5. 验证新关联——在新账户的 GitHub 控制面板中确认安装已正确关联

注意事项:

- App 目前不提供"登出"或"切换账户"功能 - 每个 GitHub 安装同一时间只能关联一个 Mermaid Chart 账户 - 卸载并重新安装不会影响你已有的图表或仓库 - AI 额度使用记录分别归属各自的 Mermaid Chart 账户

图表评审流程

当某个 PR 的图表被重新生成时:

- 机器人会将更新后的 .mmd 文件提交到 PR 的 head 分支 - 针对每个图表在 PR 中发布评论,内容包括: - 简要摘要 - 变更前后的 Mermaid 预览 - 指向 Mermaid Chart 的 "Review Diagram" 链接 - 评审者登录后(必要时通过 GitHub OAuth),在编辑器中打开图表,选择接受或拒绝变更,然后推送到 GitHub - 访问权限仅限 GitHub App 安装的所有者,以及安装评审者白名单中的用户

评审者(Mermaid Chart 设置)

仓库/安装的管理员可以在 Mermaid Chart 网页应用中管理评审者:

设置 → GitHub Integration → Reviewers

- 通过邮箱添加 Mermaid Chart 用户,允许他们打开评审链接并推送已接受的图表更新 - 需要撤销权限时移除相应评审者 - 该设置适用于该 GitHub App 安装下所有仓库的评审(包括公开和私有仓库)

.mermaidignore 配置

通过 .mermaidignore 文件(类似 .gitignore)控制哪些文件和图表会被处理:

核心功能:

- 源文件过滤——排除不触发图表更新的源文件 - 图表文件过滤——完全排除指定的 .mmd 文件 - 标准 gitignore 语法——支持 * 通配符、 递归匹配、? 单字符匹配 - 取反模式——用 !pattern 创建例外,重新包含之前被排除的文件 - 模式优先级——靠后的模式会覆盖靠前的模式,便于编写复杂的过滤规则

.mermaidignore 示例:

``` # 忽略临时文件和构建产物 *.log *.tmp build/ node_modules/

# 忽略测试文件,但保留集成测试 /*test* !src/tests/integration.test.js

# 忽略草稿图表,但保留重要的 draft//*.mmd !temp-important.mmd ```

Mermaid 图表同步助手配置

通过 .smart-mermaid-updates.yml 控制机器人处理哪些 PR 分支:

核心功能:

- 分支过滤——按精确名称或通配符模式排除 PR head 分支 - 灵活的模式——支持精确匹配(main)、通配符(feature/*)和取反(!pattern) - 多种写法——同时支持 excludeBranches(驼峰命名)和 exclude-branches(短横线命名) - 智能处理——如果分支命中排除规则,整个 PR 会被跳过

配置示例:

``` # 基础排除 excludeBranches: - experimental - draft/* - temp/* - wip/*

# 高级用法:排除所有分支,仅保留指定分支 excludeBranches: - '*' # 排除所有分支 - '!feature/*' # 但保留 feature/* 分支 - '!main' # 以及 main 分支 ```

实际应用示例

场景: 你修改了 src/auth/UserService.js 以添加双因素认证,并更新了 src/api/AuthController.js 以支持新接口。

机器人处理流程:

1. 检测到 PR 中的变更 2. 发现 docs/authentication-flow.mmd 引用了这两个被修改的文件 3. 分析代码变更,理解新的双因素认证流程 4. 结合新的认证步骤和 API 调用重新生成 Mermaid 图表 5. 提交更新后的图表:"Automated diagram update"

结果: 在 PR 评审开始之前,你的架构文档就已经准确反映了最新实现。

评论 (0)