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支持的語言）