Omen

🚀 Omen

你的AI在编写代码时，可能浑然不知潜在的“地雷”（风险）。

Omen为AI助手提供所需的上下文信息，包括复杂度热点、隐藏的依赖关系、易出现缺陷的文件以及自我承认的技术债务。只需一个命令，就能揭示那些不易察觉的问题。

为何叫“Omen”？ “Omen”（预兆）预示着未来之事，有好有坏。你的代码库中充满了各种预兆：低复杂度和简洁的架构预示着后续开发将一帆风顺，而频繁的代码变更、技术债务和代码克隆则警示着潜在的问题。Omen能揭示这些信号，让你在“临时修复”变成长期问题之前采取行动。

🚀 快速开始

# 运行所有分析器
omen analyze

# 查看分析器选项
omen analyze --help

✨ 主要特性

复杂度分析

有两种类型的复杂度：

• 圈复杂度：计算代码中不同执行路径的数量。每个if、for、while或switch语句都会创建一条新路径。圈复杂度为10的函数意味着有10种不同的执行方式。该数值越高，为覆盖所有场景所需的测试用例就越多。
• 认知复杂度：衡量代码对人类而言的阅读难度。它对深度嵌套的代码（如if语句嵌套在for语句中，而for语句又嵌套在另一个if语句中）的惩罚比扁平结构的代码更重。两个函数的圈复杂度可能相同，但嵌套更深的函数认知复杂度更高，因为更难跟踪代码逻辑。

重要性：研究表明，复杂的代码更容易出现漏洞，修复所需的时间也更长。McCabe在1976年的原始论文发现，复杂度超过10的函数维护难度显著增加。SonarSource的认知复杂度在此基础上，进一步衡量了真正让开发者感到困惑的因素。

💡 使用建议

每个函数的圈复杂度应控制在10以下，认知复杂度控制在15以下。

自我承认的技术债务（SATD）

当开发者写下TODO: fix this later或HACK: this is terrible but works之类的注释时，就意味着他们承认采取了捷径，产生了技术债务。Omen会找出这些注释并按类型进行分组：

类别	标记	含义
设计	HACK、KLUDGE、SMELL	需要重新思考的架构捷径
缺陷	BUG、FIXME、BROKEN	已知但尚未修复的漏洞
需求	TODO、FEAT	缺失的功能或未完成的实现
测试	FAILING、SKIP、DISABLED	已损坏或已关闭的测试
性能	SLOW、OPTIMIZE、PERF	能正常工作但需要提高速度的代码
安全	SECURITY、VULN、UNSAFE	已知的安全问题

重要性：Potdar和Shihab在2014年的研究发现，SATD注释往往会在代码库中存在数年之久。它们存在的时间越长，修复难度就越大，因为人们会忘记相关的上下文信息。Maldonado和Shihab（2015）指出，设计债务是最常见且最危险的类型。

💡 使用建议

每周审查一次SATD。如果一个TODO注释存在超过6个月，要么修复问题，要么删除该注释。

死代码检测

死代码包括：

• 从未被调用的函数
• 已赋值但从未使用的变量
• 从未被实例化的类
• return语句之后无法执行的代码

重要性：死代码不仅会造成代码冗余，还会让新开发者误以为其很重要。它会增加构建时间和二进制文件的大小。最糟糕的是，它可能会隐藏漏洞——如果有人“修复”了死代码，却发现它根本不会执行，那就是在浪费时间。Romano等人（2020）发现，死代码是其他代码质量问题的重要预测指标。

💡 使用建议

删除死代码。借助版本控制系统，若后续需要，随时可以恢复。

Git变更分析

变更分析会查看你的git历史记录，并统计以下信息：

• 每个文件被修改的次数
• 添加和删除的行数
• 哪些文件会一起变更

变更频繁的文件是“热点文件”，这可能意味着它们：

• 是系统的核心部分（每个人都需要修改它们）
• 设计不佳（需要不断修复漏洞）
• 缺乏良好的抽象（功能不断被添加）

重要性：Nagappan和Ball在2005年微软的研究发现，代码变更率是预测漏洞的最佳指标之一。变更频繁的文件往往存在更多缺陷。结合复杂度数据，变更分析可以帮助你找出既复杂又频繁修改的文件，即风险最高的代码。

💡 使用建议

如果一个文件的变更率和复杂度都很高，应优先对其进行重构。

代码克隆检测

有三种类型的代码克隆：

类型	描述	示例
类型1	完全相同的副本（可能只有空格或注释不同）	复制粘贴的代码
类型2	结构相同，但名称不同	变量名不同但功能相同的函数
类型3	经过一些修改的相似代码	功能几乎相同的函数

重要性：当你修复一个副本中的漏洞时，必须记得修复其他所有副本。Juergens等人（2009）发现，克隆代码的漏洞明显更多，因为修复操作往往无法一致地应用到所有副本。克隆代码越多，在更新时遗漏某个副本的可能性就越大。

💡 使用建议

任何复制超过两次的代码都应该封装成一个共享函数。目标是将代码重复率控制在5%以下。

缺陷预测

Omen结合多种信号，使用PMAT加权指标来预测文件中存在漏洞的概率：

• 过程指标（变更频率、所有权分散度）
• 复杂度指标（圈复杂度/认知复杂度）
• 代码年龄（代码的存在时间和稳定性）
• 代码总量（代码行数）

每个文件都会得到一个0%到100%的风险评分。

重要性：你不可能对所有代码进行同等程度的审查。Menzies等人（2007）表明，缺陷预测可以帮助团队将测试和代码审查的重点放在最可能存在问题的文件上。Rahman等人（2014）发现，即使是简单的模型在查找漏洞方面也比随机选择文件更有效。

💡 使用建议

优先审查缺陷概率超过70%的文件。

变更风险分析（JIT）

即时（JIT）缺陷预测会分析最近的提交，在问题出现之前识别出有风险的变更。与文件级别的预测不同，JIT基于提交级别进行分析，使用了Kamei等人（2013）提出的因素：

因素	名称	衡量内容
LA	新增行数	新增行数越多，风险越高
LD	删除行数	删除操作通常更安全
LT	受影响文件的行数	文件越大，风险越高
FIX	漏洞修复	修复漏洞的提交表明存在问题的区域
NDEV	开发者数量	文件涉及的开发者越多，风险越高
AGE	文件平均年龄	文件稳定性指标
NUC	唯一变更	变更熵越高，风险越高
EXP	开发者经验	经验越少，风险越高

基于百分位数的风险分类： 风险等级使用基于百分位数的阈值，遵循JIT缺陷预测的最佳实践。与固定阈值不同，提交会根据仓库自身的分布进行排名：

等级	百分位数	含义
高	前5%	P95+ - 需要额外审查
中	前20%	P80 - P95 - 值得额外关注
低	后80%	低于P80 - 按标准审查流程处理

这种方法符合缺陷预测研究中的80/20规则：大约20%的代码变更包含了大约80%的缺陷。无论仓库的特性如何，它都能确保得到可操作的结果——规范的仓库阈值会较低，而变更频繁的仓库阈值会较高。

重要性：Kamei等人（2013）证明，JIT预测可以在提交时捕获有风险的变更，防止漏洞扩散。他们基于工作量的方法使用排名而非固定阈值，将有限的审查资源集中在约20%风险最高的提交上。Zeng等人（2021）表明，简单的JIT模型在准确性（约65%）上与深度学习模型相当，且具有更好的可解释性。

💡 使用建议

在合并PR之前运行omen analyze changes，以识别需要额外审查的提交。

PR/分支差异风险分析

虽然JIT分析针对单个提交进行审查，但差异分析会评估整个分支相对于目标分支的累积变更。这可以让审查者在深入进行代码审查之前快速了解风险情况。

使用方法：

# 将当前分支与main分支进行比较
omen analyze diff --target main

# 与特定提交进行比较
omen analyze diff --target abc123

# 以markdown格式输出，用于PR评论
omen analyze diff --target main -f markdown

风险因素：

因素	衡量内容	风险贡献
新增行数	引入的新代码总量	代码越多，潜在漏洞越多
删除行数	删除的代码	通常会降低风险（代码减少）
修改文件数	变更的范围	修改的文件越多，级联问题的可能性越大
提交数	分支中的提交数量	提交数多可能表明范围扩大
熵	变更的分散程度	熵值高意味着变更分散在各处

风险评分解读：

评分	等级	建议操作
< 0.2	低	按标准审查流程处理
0.2 - 0.5	中	仔细审查，考虑额外测试
> 0.5	高	全面审查，确保有全面的测试覆盖

示例输出：

分支差异风险分析
==========================

源分支:   feature/new-api
目标分支:   main
基础提交:   abc123def

风险评分: 0.31 (中)

变更情况:
  新增行数:    63
  删除行数:  2
  修改文件数:  2
  提交数:        1

风险因素:
  熵:        0.084
  新增行数:    0.118
  删除行数:  0.003
  文件数:      0.050
  提交数:        0.005

需要关注的点：

• 新增行数多，删除行数少 - 新功能，需要全面审查
• 新增和删除行数平衡 - 重构，验证行为是否未改变
• 净代码减少 - 清理/简化，通常是积极的
• 熵值高 - 变更分散，检查是否有不相关的修改
• 修改文件数多 - 影响范围广，确保进行集成测试

CI/CD集成：

# 添加到GitHub Actions工作流
- name: PR风险评估
  run: |
    omen analyze diff --target ${{ github.base_ref }} -f markdown >> $GITHUB_STEP_SUMMARY

重要性：代码审查时间有限。差异分析可以帮助审查者优先关注重点——低风险的PR（变更10行代码）所需的审查力度小于中风险的PR（涉及17个文件）。熵指标对于发现包含不相关变更的PR特别有用，这些PR更难审查，也更容易引入漏洞。

💡 使用建议

在创建PR之前运行omen analyze diff，了解审查者对变更的看法。考虑将高风险的PR拆分为更小、更有针对性的变更。

技术债务梯度（TDG）

TDG将多个指标综合为一个分数（范围为0 - 100，分数越高越好）：

组件	最高分	衡量内容
结构复杂度	20	圈复杂度和嵌套深度
语义复杂度	15	认知复杂度
代码重复	15	克隆代码的数量
耦合度	15	对其他模块的依赖关系
热点	10	变更率与复杂度的交互作用
时间耦合	10	与其他文件的共同变更模式
一致性	10	代码风格和模式的遵循情况
熵	10	模式熵和代码一致性
文档	5	注释覆盖率

重要性：技术债务就像财务债务，少量的债务可以接受，但过多就会带来问题。Cunningham在1992年提出了这个术语，Kruchten等人（2012）对如何衡量和管理技术债务进行了规范。TDG为你提供了一个单一的指标，用于跟踪随时间的变化并比较不同文件。

💡 使用建议

在添加新功能之前，先修复分数低于70的文件。跟踪平均TDG分数随时间的变化，分数应呈上升趋势。

依赖关系图

Omen会构建一个图，展示哪些文件导入了其他哪些文件，然后计算以下指标：

• PageRank：哪些文件是最“核心”的（许多其他文件依赖它们）
• 中介中心性：哪些文件是代码库不同部分之间的“桥梁”
• 耦合度：模块之间的相互连接程度

重要性：高度耦合的代码很脆弱——修改一个文件可能会破坏许多其他文件。Parnas在1972年关于模块化的论文指出，良好的软件设计应尽量减少模块之间的依赖关系。依赖关系图可以帮助你了解代码架构的清晰程度和复杂程度。

💡 使用建议

PageRank分数高的文件应特别稳定并经过充分测试。考虑拆分那些在各处都充当“桥梁”的文件。

热点分析

热点文件是那些既复杂又频繁修改的文件。一个简单但经常修改的文件可能问题不大，因为易于处理；一个复杂但很少修改的文件也可以管理，因为可以暂时不管它。但一个复杂且不断修改的文件，往往是漏洞滋生的地方。

Omen使用归一化的变更率和复杂度的几何平均值来计算热点分数：

热点分数 = sqrt(变更率百分位数 * 复杂度百分位数)

这两个因素都使用经验累积分布函数（CDF）相对于行业基准进行归一化，因此分数在不同项目之间具有可比性：

• 变更率百分位数 - 该文件的提交数量在典型开源项目中的排名
• 复杂度百分位数 - 平均认知复杂度在行业基准中的排名

热点分数	严重程度	操作
>= 0.6	关键	立即优先处理
>= 0.4	高	安排审查
>= 0.25	中	监控
< 0.25	低	健康

重要性：Adam Tornhill的《Your Code as a Crime Scene》引入了热点分析，作为寻找最有影响力的重构目标的方法。他的研究表明，一小部分文件（通常为4 - 8%）包含了大部分的漏洞。Graves等人（2000）和Nagappan等人（2005）证明，相对代码变更率是缺陷的重要预测指标。

💡 使用建议

从排名前三的热点文件开始重构。降低高变更率文件的复杂度，投资回报率最高。

时间耦合

当两个文件在相同的提交中始终一起变更时，它们就存在时间耦合。这通常揭示了：

• 导入语句中不可见的隐藏依赖关系
• 一个文件的变更需要另一个文件相应变更的逻辑耦合
• 由于复制粘贴或不一致的抽象导致的意外耦合

Omen会分析你的git历史记录，找出一起变更的文件对：

耦合强度	含义
> 80%	几乎总是一起变更 - 可能存在紧密的依赖关系
50 - 80%	频繁耦合 - 调查它们之间的关系
20 - 50%	中度耦合 - 可能是巧合
< 20%	弱耦合 - 可能相互独立

重要性：Ball等人（1997）首次在AT&T研究了共同变更模式，发现它们揭示了静态分析无法发现的架构违规。Beyer和Noack（2005）表明，时间耦合可以预测未来的变更——如果文件之前一起变更过，那么它们很可能会再次一起变更。

💡 使用建议

如果两个文件的时间耦合度超过50%，但没有导入关系，考虑提取一个共享模块或将它们合并。

代码所有权/关键人员因素

关键人员因素（Bus factor）的问题是：“需要多少人离开，代码就会变得无法维护？”较低的关键人员因素意味着知识集中在少数人手中。

Omen使用git blame来计算以下指标：

• 主要所有者 - 编写了大部分代码的人
• 所有权比例 - 一个人拥有的代码百分比
• 贡献者数量 - 接触过该文件的人数
• 关键人员因素 - 主要贡献者（贡献超过5%代码）的数量

所有权比例	风险等级	含义
> 90%	高风险	单点故障
70 - 90%	中风险	知识共享有限
50 - 70%	低风险	健康的分布
< 50%	极低风险	广泛的所有权

重要性：Bird等人（2011）发现，有许多小贡献者的代码比有明确所有权的代码有更多漏洞，但由单一人员拥有的代码会给组织带来风险。每个模块有2 - 4个重要贡献者是比较理想的情况。Nagappan等人（2008）表明，组织指标（如所有权）比代码指标本身更能预测缺陷。

💡 使用建议

单一所有权超过80%的文件应进行知识转移记录。关键文件至少应有两个人能够理解。

CK指标

Chidamber - Kemerer（CK）指标套件用于衡量面向对象设计的质量：

指标	名称	衡量内容	阈值
WMC	类加权方法数	方法复杂度之和	< 20
CBO	对象间耦合度	使用的其他类的数量	< 10
RFC	类响应度	可以调用的方法	< 50
LCOM	方法内聚性不足	不共享字段的方法	< 3
DIT	继承树深度	继承链长度	< 5
NOC	子类数量	直接子类	< 6

LCOM（方法内聚性不足） 尤其重要。低LCOM意味着类中的方法使用相似的实例变量，说明类的功能集中；高LCOM意味着类在做不相关的事情，可能需要拆分。

重要性：Chidamber和Kemerer在1994年的论文确立了这些指标作为面向对象质量测量的基础。Basili等人（1996）通过实证验证了这些指标，发现WMC和CBO与易出错性密切相关。这些指标已被引用数千次，仍然是面向对象设计分析的标准。

💡 使用建议

违反多个CK阈值的类是重构的候选对象。高WMC + 高LCOM通常表明存在一个“上帝类”，应该进行拆分。

仓库映射

仓库映射提供了代码库中重要符号的简洁摘要，使用PageRank根据结构重要性对符号进行排名。这是为大语言模型（LLM）的上下文窗口设计的，你可以首先获取最重要的函数和类型。

对于每个符号，映射包括：

• 名称和类型（函数、类、方法、接口）
• 文件位置和行号
• 签名，便于快速理解
• PageRank分数，基于有多少其他符号依赖它
• 入度/出度，显示依赖关系

重要性：LLM的上下文窗口有限。将整个文件填充到其中会浪费令牌在不太重要的代码上。PageRank由Brin和Page（1998）开发，用于识别图中结构重要的节点。应用于代码时，它可以揭示对于理解代码库最核心的符号。

可扩展性：Omen使用稀疏幂迭代算法计算PageRank，其时间复杂度与边的数量O(E)呈线性关系，而不是与节点数量O(V^2)呈二次关系。这使得它能够在30秒内快速分析包含25,000个以上符号的大型单体仓库。

示例输出：

# 仓库映射（按PageRank排名前20的符号）

## parser.ParseFile (函数) - pkg/parser/parser.go:45
  PageRank: 0.0823 | 入度: 12 | 出度: 5
  func ParseFile(path string) (*Result, error)

## models.TdgScore (结构体) - pkg/models/tdg.go:28
  PageRank: 0.0651 | 入度: 8 | 出度: 3
  type TdgScore struct

💡 使用建议

使用omen context --repo-map --top 50为LLM提示生成上下文。前50个符号通常能概括代码库的基本架构。

特性标志检测

特性标志功能强大，但也存在风险。它们允许你在不启用代码的情况下发布代码、进行A/B测试并逐步推出功能。但它们会不断累积。2019年添加的“临时”标志可能仍在生产环境中使用。为为期一周的实验添加的标志可能已成为关键基础设施。

Omen可以检测流行提供商的特性标志使用情况：

提供商	支持的语言	检测内容
LaunchDarkly	JS/TS、Python、Go、Java	variation()、boolVariation()调用
Split	JS/TS、Python、Go	getTreatment()调用
Unleash	JS/TS、Go	isEnabled()、getVariant()调用
PostHog	JS/TS、Python、Go、Java、Ruby	isFeatureEnabled()、getFeatureFlag()调用
Flipper	Ruby	enabled?()、Flipper.enabled?()调用

对于每个标志，Omen会报告：

• 标志键 - 代码中使用的标识符
• 提供商 - 使用的SDK
• 引用位置 - 检查标志的所有位置
• 陈旧性 - 标志首次和最后修改的时间（通过git历史记录）

自定义提供商：对于内部的特性标志系统，可以在omen.toml中定义自定义的tree - sitter查询：

[[feature_flags.custom_providers]]
name = "feature"
languages = ["ruby"]
query = '''
(call
  receiver: (constant) @receiver
  (#eq? @receiver "Feature")
  method: (identifier) @method
  (#match? @method "^(enabled\\?|get_feature_flag)$")
  arguments: (argument_list
    .
    (simple_symbol) @flag_key))
'''

重要性：Meinicke等人（2020）研究了开源项目中的特性标志，发现标志所有权（引入标志的开发者也负责移除它）与较短的标志生命周期相关，有助于控制技术债务。Rahman等人（2018）研究了谷歌Chrome的12,000多个特性开关，发现虽然它们支持快速发布和灵活部署，但也会引入技术债务和额外的维护负担。定期审核标志可以防止代码库变成未使用开关的迷宫。

💡 使用建议

每月审核一次特性标志。删除实验标志中使用超过90天的标志，以及发布标志中使用超过14天的标志。在CI管道中跟踪标志的陈旧性。

仓库评分

Omen计算一个综合的仓库健康评分（范围为0 - 100），该评分结合了多个分析维度。这可以快速了解代码库的质量，并在CI/CD中设置质量门限。

评分组件：

组件	权重	衡量内容
复杂度	25%	超过复杂度阈值的函数百分比
代码重复	20%	代码克隆率，采用非线性惩罚曲线
SATD	10%	每1000行代码中按严重程度加权的TODO/FIXME密度
TDG	15%	技术债务梯度综合得分
耦合度	10%	循环依赖、SDP违规和不稳定性
代码异味	5%	相对于代码库大小的架构异味
内聚性	15%	面向对象代码库的类内聚性（LCOM）

归一化原则： 每个组件指标都归一化为0 - 100的范围，分数越高越好。归一化函数的设计遵循以下原则：

1. 公平 - 不同但严重程度相似的指标产生相似的分数
2. 校准 - 基于SonarQube、CodeClimate和CISQ的行业基准
3. 非线性 - 对小问题进行轻微惩罚，对严重问题进行严厉惩罚
4. 考虑严重程度 - 根据影响对项目进行加权，而不仅仅是计数

例如，SATD（自我承认的技术债务）使用按严重程度加权的评分：

• 关键（SECURITY、VULN）：4倍权重
• 高（FIXME、BUG）：2倍权重
• 中（HACK、REFACTOR）：1倍权重
• 低（TODO、NOTE）：0.25倍权重

这可以防止低严重程度的项目（如文档TODO）不公平地拉低分数。

TDG（技术债务梯度）通过分析每个文件的结构复杂度、语义复杂度、重复模式和耦合度，提供了一个补充视角。

使用方法：

# 计算仓库评分
omen score .

# 以JSON格式输出，用于CI集成
omen score . -f json

调整阈值： 对于实际的代码库，要达到100分几乎是不可能的。根据你的代码库在omen.toml中设置合理的阈值：

[score.thresholds]
score = 80        # 总体评分最低值
complexity = 85   # 函数复杂度
duplication = 65  # 代码克隆率（通常最难改善）
defect = 80       # 缺陷概率
debt = 75         # 技术债务密度
coupling = 70     # 模块耦合度
smells = 90       # 架构异味

运行omen score查看当前分数，然后将阈值设置为略低于当前值。随着时间的推移逐步提高阈值。

使用Lefthook在提交时强制执行： 添加到lefthook.yml：

pre-push:
  commands:
    omen-score:
      run: omen score

这可以防止推送不符合质量阈值的代码。

重要性：单一的健康评分可以设置质量门限、跟踪随时间的趋势并快速评估代码库。加权综合评分确保关键问题（缺陷、复杂度）比表面问题具有更大的影响。

💡 使用建议

从可实现的阈值开始，随着代码库的改进逐步提高。在遗留代码中，代码重复率通常是最难改善的指标。

MCP服务器

Omen包含一个模型上下文协议（MCP）服务器，它将所有分析器作为工具暴露给像Claude这样的大语言模型。这使得AI助手可以通过标准化的工具调用直接分析代码库。

可用工具：

• analyze_complexity - 圈复杂度和认知复杂度分析
• analyze_satd - 自我承认的技术债务检测
• analyze_deadcode - 未使用的函数和变量检测
• analyze_churn - Git文件变更频率分析
• analyze_duplicates - 代码克隆检测
• analyze_defect - 文件级缺陷概率（PMAT）分析
• analyze_changes - 提交级变更风险（JIT）分析
• analyze_tdg - 技术债务梯度得分分析
• analyze_graph - 依赖关系图生成
• analyze_hotspot - 高变更率 + 高复杂度文件分析
• analyze_temporal_coupling - 一起变更的文件分析
• analyze_ownership - 代码所有权和关键人员因素分析
• analyze_cohesion - CK面向对象指标分析
• analyze_repo_map - PageRank排名的符号映射生成
• analyze_smells - 架构异味检测
• analyze_flags - 特性标志检测和陈旧性分析
• score_repository - 综合健康评分（0 - 100）
• get_context - 特定文件或符号的深度上下文信息

每个工具都包含详细的描述和解释指南，帮助大语言模型理解指标的含义以及何时使用每个分析器。

工具输出默认采用TOON（面向令牌的对象表示法）格式，这是一种为大语言模型工作流程设计的紧凑序列化格式，与JSON相比，可减少30 - 60%的令牌使用量，同时保持较高的理解准确率。也支持JSON和Markdown格式。

重要性：大语言模型在访问结构化工具时效果最佳，而不是解析非结构化输出。MCP是大语言模型工具集成的新兴标准，得到了Claude Desktop和其他AI助手的支持。TOON输出可以在上下文窗口内最大化信息密度。

💡 使用建议

在你的AI助手中将omen配置为MCP服务器，以支持自然语言查询，如“查找最复杂的函数”或“显示技术债务热点”。

📦 安装指南

Homebrew（macOS/Linux）

brew install panbanda/omen/omen

Go Install

go install github.com/panbanda/omen/cmd/omen@latest

下载二进制文件

从发布页面下载预构建的二进制文件。

从源代码构建

git clone https://github.com/panbanda/omen.git
cd omen
go build -o omen ./cmd/omen

远程仓库扫描

无需手动克隆，即可分析任何公开的GitHub仓库：

# GitHub简写形式
omen analyze complexity facebook/react
omen analyze satd kubernetes/kubernetes

# 指定特定引用（分支、标签或提交SHA）
omen analyze agentgateway/agentgateway@v0.1.0
omen analyze owner/repo --ref feature-branch

# 完整URL
omen analyze github.com/golang/go
omen analyze https://github.com/vercel/next.js

# 浅克隆以加快分析速度（仅适用于静态分析器）
omen analyze facebook/react --shallow

Omen会将仓库克隆到临时目录，运行分析，然后自动清理。--shallow标志使用git clone --depth 1进行快速克隆，但会禁用基于git历史记录的分析器（变更率、所有权、热点、时间耦合、变更分析）。

配置

创建omen.toml或.omen/omen.toml（支持yaml、json和toml格式）：

omen init

查看以了解所有选项。

💡 使用建议

如果你使用Claude Code，可以运行setup-config技能来分析你的仓库，并生成一个包含针对你的技术栈智能默认配置的omen.toml文件，其中包括检测到的特性标志提供商和特定语言的排除模式。

MCP服务器

Omen包含一个模型上下文协议（MCP）服务器，它将所有分析器作为工具暴露给像Claude这样的大语言模型。这使得AI助手可以直接分析代码库。

Claude Desktop

添加到你的Claude Desktop配置文件（macOS上为~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "omen": {
      "command": "omen",
      "args": ["mcp"]
    }
  }
}

Claude Code

claude mcp add omen -- omen mcp

示例用法

配置完成后，你可以向Claude提问：

• "分析这个代码库的复杂度"
• "查找src目录中的技术债务"
• "哪些热点文件需要重构？"
• "显示这个项目的关键人员因素风险"
• "查找应该删除的陈旧特性标志"

Claude Code插件

Omen作为Claude Code插件提供，它提供基于分析的技能，指导Claude完成代码分析工作流程。

安装

/plugin install panbanda/omen

使用/skills验证安装，查看可用的Omen技能。

前提条件

技能需要配置Omen MCP服务器（请参阅上面的MCP服务器部分）。

真实世界的仓库分析示例

目录包含了流行开源项目的全面健康报告，展示了Omen在不同语言和项目类型中的能力。

分析的仓库

仓库	语言	健康评分	关键洞察
[gin - gonic/gin](examples/repos/gin - gonic - gin.md)	Go	95/100	非常健康的Web框架，零代码重复，架构简洁
[excalidraw/excalidraw](examples/repos/excalidraw - excalidraw.md)	TypeScript	86/100	得分最高的仓库，耦合度评分为100%；App.tsx需要重构
[BurntSushi/ripgrep](examples/repos/burntSushi - ripgrep.md)	Rust	76/100	成熟的代码库，架构优秀；测试中的代码重复是有意为之
[tiangolo/fastapi](examples/repos/tiangolo - fastapi.md)	Python	74/100	复杂度评分很高（98/100）；文档中的版本化示例导致代码重复
[discourse/discourse](examples/repos/discourse - discourse.md)	Ruby	69/100	最大的代码库（10000多个文件）；尽管规模大，但缺陷管理出色

报告展示的内容

1. 健康评分分解 每个报告展示了综合评分是如何由各个组件（复杂度、代码重复、SATD、耦合度等）计算得出的，并解释了某些评分的原因。

2. 热点分析 报告识别出变更率和复杂度都很高的文件，这些是最有影响力的重构目标。例如，gin的tree.go由于其基数树路由的复杂度，热点分数为0.54。

3. 技术债务梯度（TDG） 文件根据累积的技术债务被评为A - F级。报告解释了导致低评分的原因，并确定清理工作的优先级。

4. PR风险分析 每个报告都包含一个真实的PR分析示例，展示了omen analyze diff的使用：

omen analyze diff --target main -f markdown

以gin - gonic/gin (#4420 - 添加转义路径选项)为例：

风险评分: 0.31 (中)
新增行数:    63
删除行数:  2
修改文件数:  2

风险因素:
  熵:        0.084
  新增行数:    0.118
  文件数:      0.050

理解风险因素：

• 风险评分 - 低 (< 0.2)、中 (0.2 - 0.5)、高 (> 0.5)
• 熵 - 变更的分散程度（0 = 集中，1 = 分散在各处）
• 新增/删除行数比例 - 净代码减少通常是好迹象
• 修改文件数 - 修改的文件越多，级联问题的可能性越大

5. CI/CD集成 报告包含GitHub Actions工作流示例，用于设置质量门限和进行PR风险评估。

生成你自己的报告

对任何仓库进行全面分析：

# 本地仓库
omen score .
omen analyze hotspot
omen analyze tdg

# 远程仓库
omen score facebook/react
omen analyze hotspot kubernetes/kubernetes

# 合并前的PR风险分析
omen analyze diff --target main

# 跟踪评分随时间的趋势
omen analyze trend --period monthly --since 6m

贡献代码

1. Fork仓库
2. 创建你的特性分支 (git checkout -b feature/amazing - feature)
3. 提交你的更改 (git commit -am 'Add amazing feature')
4. 将分支推送到远程 (git push origin feature/amazing - feature)
5. 创建Pull Request

致谢

Omen深受[paiml - mcp - agent - toolkit](https://github.com/paiml/paiml - mcp - agent - toolkit/)的启发，这是一个出色的CLI工具和用于大语言模型工作流程的综合代码分析工具套件。如果你正在进行严肃的AI辅助开发，值得一试。Omen作为一个精简的替代方案，为那些希望使用专注的分析器子集而无需额外依赖的团队提供服务。如果你正在寻找一个以Rust为重点的MCP/代理生成器来替代Python，它绝对值得一看。

📄 许可证

本项目采用Apache License 2.0许可协议，请参阅LICENSE了解详细信息。

支持的语言

Go、Rust、Python、TypeScript、JavaScript、TSX/JSX、Java、C、C++、C#、Ruby、PHP、Bash（以及其他tree - sitter支持的语言）