omni-scanner

🔱 Omni — 全视之眼

联邦治理三叉戟 — 一款模块化、可扩展的观测引擎，可在星系级规模扫描、绘制代码库地图并守护代码库。

“永远不要相信文档，要相信现实。” — ACE

Omni 是一个由 Python 驱动的被动观测平台，用于发现代码的真实状况。它不会修改文件或破坏构建，只会观察、绘制地图并生成报告。可以把它看作代码库的三叉戟：将它指向任意目录，它就能在几秒内揭示代码结构、依赖关系、健康状况、偏差和合规性。

---

✨ 一览

维度	数值
🔍 扫描器类别	12（从静态分析到 Git 考古）
📦 扫描器总数	所有类别共 55 个扫描工具
⚡ CLI 命令	14 个动词，满足各种观测需求
🧠 MCP 服务	将所有扫描器作为可由 AI 调用的工具提供
🏛️ 支柱	4 个编排子系统（制图、情报、守门人、注册表）
🔌 联邦模式	可选与治理后端深度集成
🦴 独立模式	随处可用——无需后端

---

🚀 快速开始

新手？ 请查看 新手指南：从零到高手，了解分步设置教程。

安装

# Recommended: Install from PyPI
pip install omni-governance

# Or install from source:
# pip install -e .

首次扫描

# Scan the current directory with all static scanners
omni scan .

# Run a specific scanner
omni scan . --scanner surfaces

# See what Omni knows about itself
omni introspect

探索生态系统

# Map your entire project constellation
omni map

# Check governance compliance
omni gate .

# Generate a full report
omni report . --format markdown

---

🏗️ 架构 — 三位一体

Omni 遵循三位一体架构——三个职责严格分离的层：

                    ┌──────────────────────────┐
                    │        CLI (cli.py)       │  ← User interface
                    │     14 verbs, 1 brain     │
                    └────────────┬─────────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              │                  │                  │
    ┌─────────▼──────┐  ┌───────▼────────┐  ┌──────▼───────┐
    │  🧠 CORE       │  │  🏛️ PILLARS    │  │  📚 LIB      │
    │  Identity      │  │  Cartography   │  │  I/O, Render │
    │  Registry      │  │  Intel         │  │  Reporting   │
    │  Gate          │  │  Gatekeeper    │  │  Tree, TAP   │
    │  Paths         │  │  Registry      │  │  Requirements│
    └─────────┬──────┘  └───────┬────────┘  └──────────────┘
              │                 │
    ┌─────────▼─────────────────▼──────────────────────────┐
    │              🔍 SCANNERS (55 Instruments)            │
    │   12 categories • Dynamic plugin loading             │
    │   Each scanner: scan(target: Path) → dict            │
    └──────────────────────────────────────────────────────┘
              │
    ┌─────────▼──────┐
    │  🔧 BUILDERS   │  ← The only layer that writes
    │  Registry Gen  │
    │  Report Gen    │
    └────────────────┘

只读保证：扫描器绝不会修改源文件。只有构建器会写入，而且只会写入指定的制品目录。

如需深入了解完整架构，请参阅 ARCHITECTURE.md。

---

🔍 扫描器类别

Omni 的 55 个扫描器分为 12 个类别。每个扫描器都实现了通用的 scan(target: Path) → dict 契约，并通过 SCANNER_MANIFEST.yaml 文件自动发现。

开源扫描器（包含在构建版本中）

类别	扫描器	用途
📁 静态分析	9	文件系统分析——契约、依赖项、文档、事件、钩子、导入、表面、工具、UUID
🏗️ 架构	4	结构约束——导入边界、耦合检测、偏差分析、合规性
🔎 发现	8	组件编目——项目、CLI 命令、核心、MCP 服务、归档、普查
🌐 多语言	4	语言生态系统——Python 包、Node.js、Rust crate、通用（Go/Java/.NET/Docker）
📚 知识库	6	文档智能——凝聚度分析、内容深度、知识图谱、惯例
🔀 Git	5	仓库智能——状态、活跃度、提交历史、PR 遥测、实用工具
🔍 搜索	3	模式匹配——文件搜索、文本搜索、带上下文的正则表达式模式搜索
🗄️ 数据库	1	由通用配置驱动的数据库扫描

Federation 专属扫描器（不包含在开源构建版本中）

这些扫描器需要 Federation Heart 后端，是专有治理层的一部分。Heart 可用时，它们会显示在 omni introspect 中，但不会随开源版本分发。

类别	扫描器	用途
🛡️ 健康状况	6	运行时健康状况——Federation、CMP、支柱、站点、隧道和系统状态
🗃️ 数据库	5	CMP 实体扫描——Agent、制品、对话、实体、项目
⚓ 机群	1	机群注册表的生成与验证
🔥 Phoenix	3	Git 历史复原——归档扫描、孤立项检测、时间间隔分析

每个类别都有自己的 README，其中包含扫描器的详细文档。完整参考请参阅扫描器架构指南。

---

🏛️ 四大支柱

支柱是用于协调多个扫描器并生成更高层次智能信息的编排子系统：

支柱	职责	核心能力
🗺️ 制图	生态系统映射器	绘制项目星群和依赖关系网络
🕵️ 情报	情报收集器	汇总多个扫描器的数据，生成可执行的洞见
⚖️ 守门人	策略执行者	验证合规性、发现偏差、标记违规行为
📋 注册表	注册表操作员	解析、验证并管理 PROJECT_REGISTRY_V1.yaml

深入了解请参阅支柱架构。

---

⚡ CLI 命令参考

命令	用途
omni scan	对目标目录运行扫描器
omni inspect	深入检查单个项目
omni gate	执行策略并进行合规性检查
omni map	绘制生态系统图谱并映射依赖项
omni tree	可视化目录树
omni audit	审计来源、依赖项和锁定状态
omni registry	执行注册表操作并扫描事件
omni library	Grand Librarian 文档智能
omni canon	验证并发现 Canon
omni report	生成结构化报告
omni init	搭建符合 Federation 规范的新项目
omni introspect	自检 — 显示所有扫描器、偏移和功能
omni interpret	解读并说明扫描结果
omni inspect-tree	结合目录树与检查

---

🔌 Federation 模式与独立模式

Omni 以两种模式运行，可透明切换：

独立模式（默认）

无需外部依赖。配置来自 omni.yml 和环境变量。所有开源扫描器均可正常运行。非常适合个人开发者和开源项目。

Federation 模式（可选）

安装 federation_heart 后，Omni 将获得以下功能：

• CartographyPillar — 在整个 Federation 中解析规范路径
• Constitution — 执行来自中央权威机构的治理规则
• CMP 集成 — 根据 Canonical Master Project 数据库解析项目身份
• 运行时健康状况 — 实时查看 Federation 服务、站点和隧道的状态

该集成由单个 shim（omni/config/settings.py）处理：可用时连接 Heart，不可用时则平稳回退。

---

🧠 MCP 服务

Omni 内含一个 Model Context Protocol（MCP）服务，将全部 55 个扫描器作为 AI 可调用的工具提供。任何兼容 MCP 的 AI 助手都可以通过编程方式调用 Omni 的扫描器。

快速开始（npx）

使用 MCP 服务最简单的方式是通过 npx（需要 Node.js）：

npx -y @modelcontextprotocol/inspector mcp-server-omni-governance

从源代码运行

# The MCP server auto-discovers all registered scanners
python -m mcp_server.omni_mcp_server

有关设置和配置，请参阅 MCP 服务文档。

---

📁 项目结构

omni/
├── README.md              ← You are here
├── ARCHITECTURE.md        ← Full architectural deep-dive
├── CONTRIBUTING.md        ← How to add scanners and contribute
├── CHANGELOG.md           ← Version history
├── ROADMAP.md             ← Future plans
├── pyproject.toml         ← Package definition
├── omni/
│   ├── cli.py             ← CLI entry point (14 commands)
│   ├── core/              ← Brain — identity, registry, gate, paths
│   ├── config/            ← Configuration & Federation Heart bridge
│   ├── scanners/          ← 55 scanners across 12 categories
│   ├── pillars/           ← 4 orchestration subsystems
│   ├── lib/               ← Shared utilities (I/O, rendering, reporting)
│   ├── builders/          ← Registry and report generators
│   ├── scaffold/          ← Project templates
│   └── templates/         ← Jinja2 report templates
├── mcp_server/            ← MCP server exposing scanners as AI tools
├── scripts/               ← Operational scripts
├── tests/                 ← Test suite (pytest)
├── docs/                  ← Historical docs and plans
└── contracts/             ← Crown Contracts (C-TOOLS-OMNI-*)

---

🔧 配置

Omni 遵循严格的配置优先级（优先级最高者生效）：

1. CLI 标志（例如 --scanner surfaces）
2. 环境变量（例如 OMNI_ROOT）
3. omni.yml（项目级配置）
4. 内置默认值（合理的回退值）

主要环境变量：

变量	用途
OMNI_ROOT	覆盖扫描根路径
OMNI_REPO_INVENTORY	仓库清单 JSON 的路径
OMNI_WORKSPACES	工作区根路径
OMNI_DB_CONFIG_PATH	数据库配置目录

完整详情请参阅配置指南。

---

🧪 测试

# Run all tests
pytest tests/ -v

# With coverage
pytest tests/ --cov=omni --cov-report=html

有关测试夹具、标准和 CI 设置，请参阅测试套件文档。

---

🤝 贡献

欢迎添加扫描器、支柱并改进项目。扫描器插件系统让添加新的观测能力变得简单：

1. 创建一个扫描器文件，其中包含 scan(target: Path) → dict 函数
2. 在相应类别的 SCANNER_MANIFEST.yaml 中注册该扫描器
3. 添加测试和文档

完整指南请参阅 CONTRIBUTING.md。

---

📜 要求

• Python：3.8+
• 依赖项：pyyaml、pydantic（核心）；federation_heart（可选，用于联邦模式）
• 操作系统：Windows、macOS、Linux

---

📋 许可证

开源。详情请参阅 LICENSE。

---

全视之眼注视着一切。代码编写代码。
Omni v0.7.0 — Pantheon LadderWorks