English | Türkçe | 한국어 | 日本語 | 中文 | தமிழ்

本文档翻译自英文 README。部分表述可能不够自然。

快速开始

在终端中粘贴：

npm install -g @rsrini/omnimap && omm setup

打开你的 AI 编码工具，使用 /omm-scan 技能：

/omm-scan

就这样。查看结果：

omm view

示例

omm 扫描了自己。这是它发现的结果。

工作原理

AI 分析代码库并生成 视角（perspective） — 观察架构的不同镜头（结构、数据流、外部集成等）。每个视角包含 Mermaid 图表和文档字段。

每个节点都会被递归分析。复杂的节点会成为具有自己图表的嵌套子元素。简单的节点保持为叶子节点。文件系统直接反映树结构：

.omm/
├── overall-architecture/           ← 视角
│   ├── description.md
│   ├── diagram.mmd
│   ├── context.md
│   ├── main-process/               ← 嵌套元素
│   │   ├── description.md
│   │   ├── diagram.mmd
│   │   └── auth-service/           ← 更深层嵌套
│   │       └── ...
│   └── renderer/
│       └── ...
├── data-flow/
└── external-integrations/

查看器自动从文件系统检测嵌套 — 有子元素的元素渲染为可展开的组，其他渲染为节点。

每个元素最多包含 7 个字段：description、diagram、context、constraint、concern、todo、note。

CLI

omm setup                          # 向 AI 工具注册技能
omm view                           # 打开交互式查看器
omm config language zh             # 设置内容语言
omm format <element>               # Show diagram format (mermaid/plantuml)
omm config plantuml-status         # Check PlantUML status
omm incremental                    # 基于 git diff 规划增量重新扫描
                                   # stale 原因: source_file, source_glob, orphaned_source,
                                   #   glob_coverage_changed, no_source_tracking
omm update                         # 更新到最新版本
omm analyze [--format md|json]     # 基于 tree-sitter 的结构分析（依赖图、API、模块）
omm analyze --validate             # 比较文档化的架构 vs 实际代码结构
omm analyze --impact <file>        # 分析文件变更的影响范围
omm search <query>                 # 模糊搜索元素名称/描述/路径
omm sync [--search <query>]        # 将 .omm/ 同步到 SQLite（FTS5 搜索）
omm tour [dir] [--limit n]         # 按依赖顺序的引导式导览
omm wiki                           # 生成可爬取的 Markdown wiki（默认: .omm/.wiki/）
omm affected [files...] [--staged] # 查找受变更影响的测试文件
omm mcp [--port <port>]            # 启动 AI 代理的 MCP 服务器
omm watch [dir]                    # 文件变更时自动运行 omm analyze
omm merge <source>                 # 将另一个 .omm/ 合并到当前
omm view --share                   # 打开网络共享查看器
omm treecode                       # 源代码 ↔ .omm/ 覆盖率映射
omm signature --check              # 结构签名漂移检测
omm reconcile                      # .omm/ 与源代码同步
omm links <element>                # 管理外部文档链接
omm inspect <element>              # 详细元素检查

完整命令列表请运行 omm help。

技能

技能是在 AI 编码工具内部运行的命令（不是终端）。以 / 开头。

| 技能 | 功能 | | --- | --- | | /omm-scan | 分析代码库 → 生成架构文档 | | /omm-push | 一步完成登录 + 链接 + 推送到云端 |

项目选择器

在架构仓库中运行 omm view 时，如果该仓库包含多个项目，页面会在 http://localhost:3000/ 自动显示项目选择器，而不是直接加载某个项目。

选择器列出每个项目的信息：

• 视角数量
• 元素数量
• 最后更新时间

点击任意项目卡片即可在查看器中打开该项目。如果配置了多个架构仓库（omm org add），选择器顶部会出现组织切换器。

已有行为保持不变：omm view --project <name> 仍会直接打开指定项目，跳过选择器。

云端

通过 ohmymermaid.com 将架构存储在云端。

omm login && omm link && omm push

默认为私有。可以与团队共享，或像这个示例一样公开。

支持的 AI 工具

| 平台 | 设置 | | --- | --- | | Claude Code | omm setup claude | | Codex | omm setup codex | | Cursor | omm setup cursor | | OpenClaw | omm setup openclaw | | Antigravity | omm setup antigravity | | OpenCode | omm setup opencode | | pi (pi.dev) | omm setup pi | | Oh my Pi (omp) | omm setup omp |

运行 omm setup 自动检测并配置所有已安装的工具。

路线图

请参阅 docs/ROADMAP.md。

开发 & 贡献

git clone https://github.com/@rsrini/omnimap.git
cd omnimap
npm install && npm run build
npm test

欢迎提交 Issue 和 PR。请使用 Conventional Commits。

许可证

MIT