1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | oh-my-mermaid |
| 作者/维护者 | oh-my-mermaid（GitHub 组织，主要维护者 hitkoo） |
| 来源链接 | https://github.com/oh-my-mermaid/oh-my-mermaid |
| 许可证 | MIT（数据来自 GitHub API） |
| GitHub Stars | 1,824（数据来自 GitHub API） |
| Forks | 148（数据来自 GitHub API） |
| 最新版本 | 0.2.0（数据来自 npm registry） |
| 安装方式 | npm install -g oh-my-mermaid && omm setup |
2. 功能介绍与亮点
oh-my-mermaid（简称 omm）是一个“把代码库变成可维护架构文档”的 Agent Skill 套件，由三个协同工作的技能组成：
- omm-scan：分析代码库并生成
.omm/目录下的架构文档。核心机制是“视角驱动的递归分析”——先选定若干“视角”（整体架构、数据流、外部集成、CLI 命令面等 12 种预设视角之一或多个），再对视角图中的每个节点递归下钻：复杂节点展开成带自己图表的子目录，简单节点保留为叶子。文件系统结构直接映射文档的嵌套关系。 - omm-view：启动一个交互式网页查看器，浏览器中查看并按目录结构展开/折叠架构图。
- omm-push：一键登录 GitHub OAuth、关联项目、把生成的文档推送到云端（ohmymermaid.com），方便团队分享。
亮点：核心扫描与查看功能完全本地运行、无需联网；文档以 Mermaid 图 + Markdown 字段（描述、上下文、约束、关注点、待办、备注）组织，可随代码演进反复刷新；界面与生成内容支持中/英/日/韩/土耳其语；npm 近 30 天下载量约 954 次，显示有真实使用而非仅靠 star 数堆砌热度。
3. 适用场景
固定分类：数据分析与可视化
- 工程师接手不熟悉的代码库时，用一条命令生成可点击下钻的架构总览，快速建立心智模型
- 团队在大重构前，先生成现状架构图作为讨论基准，重构后重新扫描对比变化
- 需要把架构文档保持“活文档”状态（随代码变化重新生成）而非一次性画图后就过时
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | ✅ 原生支持 | README 明确列出 omm setup claude 安装路径 |
| Codex | ✅ 原生支持 | README 明确列出 omm setup codex |
| OpenClaw | ✅ 原生支持 | README 明确列出 omm setup openclaw |
| Hermes Agent | ❌ 不支持 | 曾有社区 PR 尝试添加 Hermes 支持，但维护者以“未针对真实 Hermes 环境验证”为由关闭未合并，当前代码库不含 Hermes 适配 |
5. 推荐理由
它把“看代码库架构”从一次性、容易过时的手绘图，变成可以随代码反复重新生成的活文档，且核心功能不依赖任何云服务或 API key，安装门槛只是一条 npm 命令，同时原生覆盖 Claude Code / Codex / OpenClaw 三个生态。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | GitHub 1,824 stars，落在 1k–5k 区间；npm 月下载量约 954，佐证真实使用而非纯 star 堆积 |
| 可用性 | 7 | 安装为单条命令，文档详尽且多语言；但 GitHub issue 中多位用户各自独立反馈 Windows 平台 omm setup 检测不到已安装工具，且最近一次代码合并已是 3 个多月前 |
| 安全性 | 8 | 核心扫描/查看功能纯本地运行、无外联；仅可选的云推送功能涉及网络与 OAuth 登录，且有清晰的错误提示与免费版额度说明；MIT 协议，代码与 SKILL.md 中未发现可疑指令 |
安全检查清单：
① Shell 命令权限范围明确（本地代码扫描、读写 .omm/ 目录，无越权迹象）；
② 默认不联网，仅 omm push 主动联网，目标地址透明（ohmymermaid.com）；
③ 仅云推送功能需要 GitHub OAuth 登录，核心功能不需要任何凭据；
④ 抽查 omm-scan / omm-view / omm-push 三份 SKILL.md，均为清晰步骤说明，未见提示词注入或可疑指令；
⑤ 维护团队规模较小（4 名贡献者），暂无重大信誉负面信号；
⑥ MIT 许可证，条款明确；
⑦ 最近一次代码合并为 2026-04-07，之后仅有 issue/PR 讨论，其中一条 PR 因“暂无维护者可审核”被关闭，维护活跃度较三个月前有所放缓。
7. 跟同类 Skills 相比的优势
| 项目 | 定位 | 与 oh-my-mermaid 的差异 |
|---|---|---|
| drawio-skill | 自然语言生成 draw.io 图表，11 种预设（UML/BPMN/网络拓扑等），支持代码库/CI/基础设施转图、图片转可编辑图、PR 差异图 | 面向“按需生成单张图”，覆盖图表类型更广；不维护随代码演进的目录化文档结构 |
| archify | 生成美观、可验证的架构/工作流/时序/数据流图，导出为带动效的自包含 HTML | 强调单次输出的视觉呈现效果；不提供随代码库变化持续刷新的分层文档体系 |
| drawio-ai-kit | 面向 draw.io 生态的 AI 辅助制图工具包 | 同样是“一次生成一张图”模式，产物是 draw.io 文件而非可浏览的分层文档站点 |
oh-my-mermaid 的差异化在于“活文档”模式：生成物是随文件系统嵌套的目录树（而非单个图片/文件），配套本地网页查看器可逐层下钻，且天生具备“重新扫描即可刷新”的迭代属性，更适合需要长期维护架构文档的团队，而非一次性出图场景。
8. 用户评价
- GitHub 用户 zjf2671 在 issue 中反馈：「Not friendly to windows」，指出 Windows 平台下
omm setup存在兼容性问题。 - GitHub 用户 netsailer 在同一 issue 下补充了变通方案：在 Windows 上改用 Git Bash 执行
omm setup可成功为 Claude Code 安装，但在 cmd 或 PowerShell 下不生效。
9. 其他补充
文档提供英文、韩文、日文、土耳其文、中文五个语言版本；项目采用 Conventional Commits 规范，欢迎社区提交 Issue 与 PR。
10. 安装使用方式
npm install -g oh-my-mermaid && omm setupomm setup 会自动探测已安装的 AI 编程工具并完成技能注册；也可用 omm setup claude / omm setup codex / omm setup openclaw 指定平台安装。安装后在 AI 工具内输入 /omm-scan 即可生成架构文档，omm view 在浏览器打开交互式查看器；如需分享到云端，执行 omm login && omm link && omm push（默认私有，免费版限 1 个项目）。
11. 注意事项
- Windows 平台下
omm setup的工具自动检测存在已知兼容性问题，多位用户反馈失败，可尝试改用 Git Bash 执行 - 最近一次代码合并距今已 3 个多月，一条待审 PR 因维护者精力有限被关闭，社区响应速度较此前放缓
- 云端分享功能免费版仅支持 1 个项目，更多项目或团队分享需付费升级
- 当前不支持 Hermes Agent