omm-scan

omm-scan — 基于视角的架构扫描器

用途

使用由视角驱动的递归分析来分析代码库，并生成 .omm/ 架构文档。

• 视角是顶层元素——一种审视架构的独特方式。
• 图表中的每个元素都会递归分析。如果它具有内部结构，就会成为一个子元素（拥有自身图表的子目录）。否则，它会保留为叶节点。
• 嵌套关系由文件系统决定。图表中的元素 ID 与子目录名称一致。查看器会根据文件系统解析分组。

前提条件

command -v omm || npm install -g oh-my-mermaid

如果安装失败，请告诉用户：“请在终端中运行 npm install -g oh-my-mermaid，然后重试。”

---

步骤 0：检查语言

omm config language

字段内容（description、context、constraint、concern、todo、note）使用配置的语言撰写。默认为英语。元素 ID、目录名称和图表节点 ID 始终使用英文 kebab-case。

步骤 1：探索代码库

使用 Glob 和 Read 了解项目：

• 阅读 package.json、pyproject.toml 或同等清单文件
• 列出顶层目录，以确定模块边界
• 阅读关键入口文件（main、index、app 文件）
• 查找路由定义、服务层、数据库连接和外部集成

步骤 2：选择视角

从下面的目录中，选择对该代码库有意义的视角。

视角目录

视角	适用情形	回答的问题
overall-architecture	始终适用	有哪些内容，各部分如何关联
request-lifecycle	任何服务器/API	请求如何进入并得到端到端处理
data-flow	任何数据处理或数据库使用场景	数据从哪里来，如何转换，最终存放在哪里
dependency-map	复杂的模块图	模块之间的依赖关系是什么，哪些内容会共享
external-integrations	外部 API/服务	系统连接到什么，以及连接的原因
state-transitions	有状态功能（前端或后端）	状态如何变化，哪些因素会触发变化
route-page-map	带路由的前端	页面结构和导航流程
command-surface	CLI 工具	命令层级和分发方式
extension-points	插件/扩展系统	扩展架构和注册表
pipeline	ML/数据管道	阶段拓扑和数据流
orchestration	事件驱动/队列系统	发布者、订阅者和代理的拓扑
storage	使用 2 个或更多存储系统	存储拓扑（数据库、缓存、队列、对象存储）

不要强行加入代码中不存在的视角。

步骤 3：递归生成视角并深入分析

针对每个选定的视角，遵循以下递归流程：

3a. 编写视角图表

元素 ID 与子目录名称一致。查看器会根据文件系统解析嵌套关系。

omm write <perspective> diagram - <<'MERMAID'
graph LR
    renderer["Renderer\nsrc/renderer/"]
    renderer -->|"IPC invoke/on"| main-process["Main Process\nsrc/main/"]
    main-process -->|"spawn PTY"| engine-system["Engine System\nsrc/main/engine/"]
    main-process -->|"read/write JSON"| data-store["Data Store\nsrc/main/store.ts"]
    main-process -->|"xterm.js"| terminal-dock["Terminal Dock\nsrc/renderer/src/panel/"]
MERMAID

3b. 编写其他 6 个字段

分别使用单独的 omm write 命令编写：description、context、constraint、concern、todo、note。

3c. 递归深入分析：分析每个元素

对于图表中的每个元素：

1. 分析它所代表的代码（使用 Glob + Read 阅读相关文件/目录）

2. 为每个节点编写 description，不得遗漏。 这会创建元素目录。也可以根据需要编写其他字段（context、constraint、concern、todo、note）——使用配置的语言撰写。

   omm write <perspective>/<element-name> description - <<'EOF'
   (what this element does, which files/dirs it covers)
   EOF
   

3. 判断它是叶节点还是分组：

   • 发现了独立的内部组件 → 编写图表并继续递归（它将成为一个分组）
   • 没有有意义的子组件（单个文件、简单封装、外部系统）→ 仅编写剩余字段（它将保留为叶节点）

4. 如果是分组——编写图表并继续递归：

   omm write <perspective>/<element-name> diagram - <<'MERMAID'
   graph LR
       (internal elements)
   MERMAID
   

   然后对该图表中的每个元素重复步骤 3c。

递归示例

overall-architecture (perspective)
  elements: renderer, main-process, engine-system, data-store, terminal-dock

  → analyze renderer (src/renderer/)
    → finds: App.tsx, components/, hooks/, stores/, world/
    → group → write diagram with: components, stores, world
      → analyze components → 15 .tsx files, no sub-structure → leaf
      → analyze stores → 4 zustand stores → leaf
      → analyze world → OfficeCanvas + PixiJS logic → leaf

  → analyze main-process (src/main/)
    → finds: ipc.ts, auth/, engine/, terminal-session-service.ts, store.ts
    → group → write diagram with: auth, engine, terminal-session
      → analyze auth → auth-service.ts, callback-server.ts → leaf
      → analyze engine → claude-code.ts, codex.ts → leaf

  → analyze data-store (src/main/store.ts)
    → single file → leaf

  → analyze terminal-dock (src/renderer/src/panel/)
    → TerminalDock.tsx, DockManager → leaf

步骤 4：总结

报告已创建/更新的内容，并建议使用 omm view 查看。

图表规则

• 元素 ID 必须与子目录名称一致。 使用 kebab-case：main-process、data-store、terminal-dock。

• 元素标签采用两行格式：名称 + 文件路径，以 \n 分隔：

  main-process["Main Process\nsrc/main/"]
  auth-service["Auth Service\nsrc/auth/service.ts"]
  

• 每条边都必须带有有意义的标签：A -->|"why this connection exists"| B

• 单个图表中的元素越多，就越应该深入递归。

• 大多数图表使用 graph LR，层级结构使用 graph TD。

• 在有助于区分视觉样式时使用 classDef：

  样式	颜色	用途
  external	#585b70	代码库之外的第三方服务
  concern	#f38ba8	已知风险或瓶颈
  entry	#89b4fa	入口点（HTTP 处理程序、CLI、队列使用者）
  store	#a6e3a1	持久化存储（数据库、缓存、文件系统）

  classDef external fill:#585b70,stroke:#585b70,color:#cdd6f4
  classDef concern fill:#f38ba8,stroke:#f38ba8,color:#1e1e2e
  classDef entry fill:#89b4fa,stroke:#89b4fa,color:#1e1e2e
  classDef store fill:#a6e3a1,stroke:#a6e3a1,color:#1e1e2e
  

通用规则

• 每个字段都要单独使用一条 omm write 命令编写。 每条 omm write 都必须单独调用一次 Bash 工具。
• 不要重写未发生变化的元素。
• 不要创建循环引用。子元素不得引用其父元素。