AI Skills
genotoxic

genotoxic

熱門

結合程式碼圖譜資訊的突變測試（Mutation testing）結果分流。使用 Trailmark 解析程式碼庫，執行突變測試與 necessist，並利用倖存的突變體（survived mutants）、不必要的測試語句以及呼叫圖（call graph）資料，找出誤報（false positives）、缺失的測試涵蓋率與模糊測試（fuzzing）目標。適用於對倖存突變體進行分流、分析突變測試結果、識別測試缺口、從弱測試中尋找模糊測試目標、執行突變測試框架（包含 circomvent 與 cairo-mutants）或使用 necessist 的場景。

6336星標
545分支
更新於 2026/7/30
獲取技能源代碼

相關技能

observability-and-instrumentation7.9萬nestjs-expert4.4萬webapp-testing6.9萬
SKILL.md
唯讀
名稱
genotoxic
描述

結合程式碼圖譜資訊的突變測試（Mutation testing）結果分流。使用 Trailmark 解析程式碼庫，執行突變測試與 necessist，並利用倖存的突變體（survived mutants）、不必要的測試語句以及呼叫圖（call graph）資料，找出誤報（false positives）、缺失的測試涵蓋率與模糊測試（fuzzing）目標。適用於對倖存突變體進行分流、分析突變測試結果、識別測試缺口、從弱測試中尋找模糊測試目標、執行突變測試框架（包含 circomvent 與 cairo-mutants）或使用 necessist 的場景。

Genotoxic

結合突變測試（Mutation testing）與 necessist（測試語句移除），搭配程式碼圖譜分析，將分析結果分流為具體可執行的類別：誤報（false positives）、缺失的單元測試，以及模糊測試（fuzzing）目標。

何時使用

  • 當突變測試揭露了需要進一步分流處置的倖存突變體（survived mutants）時
  • 識別在何處撰寫單元測試能帶來最高效益
  • 找出需要建立模糊測試框架（fuzz harness）而非單元測試的函數
  • 利用資料流上下文資訊，排定測試改善的優先順序
  • 從可執行的項目中過濾掉無害的突變體
  • 找出代表斷言過弱的不必要測試語句（necessist）

何時不使用

  • 程式碼庫目前完全沒有任何測試套件（請先撰寫測試）
  • 純粹的說明文件或設定檔變更
  • 邏輯極為簡單的單一檔案腳本

事先準備（Prerequisites）

  • 已安裝 trailmark — 若 uv run trailmark 執行失敗，請執行：
    uv pip install trailmark
    切勿以「人工驗證」或「人工分析」替代執行 trailmark。請先完成安裝。若安裝失敗，請回報錯誤，而非直接改用人工分析。
  • 目標語言的突變測試框架 — 若框架命令執行失敗（未找到、未安裝），請依照 references/mutation-frameworks.md 中的指示進行安裝。
    切勿改用「人工突變分析」或跳過突變測試。請先安裝框架。若安裝失敗，請回報錯誤，而非直接改用人工突變分析。
  • necessist（選用，推薦）— 若支援目標語言（Go、Rust、Solidity/Foundry、TypeScript/Hardhat、TypeScript/Vitest、Rust/Anchor），可以 cargo install necessist 進行安裝。詳情請參閱 references/mutation-frameworks.md。
  • 一套目前可正常通過的測試套件
  • macOS 環境：在呼叫任何 mull-runner 前，請先執行 ulimit -n 1024。macOS Tahoe (26+) 預設將檔案描述符（file descriptors）設為無上限，這會導致 Mull 建立子進程時崩潰。詳情請參閱 references/mutation-frameworks.md。

應拒絕的合理化藉口（Rationalizations to Reject）

合理化藉口 為何是錯的 要求的導正行動
「所有倖存的突變體都需要寫測試」 許多突變體是無害或同義的（equivalent） 撰寫測試前應先進行分流
「突變測試的雜訊太多」 雜訊多意味著你沒有進行分流 使用圖譜資料進行過濾
「單元測試已經涵蓋了一切」 複雜的資料流需要模糊測試 檢查入口點（entrypoint）的可達性
「死碼（Dead code）突變體並不重要」 死碼應該被移除 標記以進行清理
「低複雜度 = 低風險」 邊界 Bug 常藏在簡單的程式碼中 檢查突變體所在位置
「工具沒安裝，我用人工分析就好」 人工分析會漏掉工具能抓到的問題 先安裝該工具
「Necessist 不是突變測試，直接跳過」 Necessist 能找出突變測試漏掉的問題：弱測試 只要語言支援，就應同時執行兩者

快速開始

# 1. 建立程式碼圖譜
uv run trailmark analyze --language auto --summary {targetDir}

# 2. 執行突變測試（依語言而定）
# Python:
uv run mutmut run --paths-to-mutate {targetDir}/src
uv run mutmut results

# 2b. 執行 necessist（若支援該語言）
necessist

# 3. 依本 Skill 工作流程分析結果（Phase 3）

工作流程總覽（Workflow Overview）

Phase 1: 建立圖譜 (Graph Build)      → 使用 trailmark 解析程式碼庫
      ↓
Phase 2: 執行突變測試 (Mutation Run) → 執行突變測試框架
Phase 2b: 執行 Necessist (Necessist Run) → 移除測試語句（選用，可平行執行）
      ↓
Phase 3: 結果分流 (Triage)          → 利用圖譜資料對結果進行分類
      ↓
Output: 分類報告 (Categorized Report)
  ├── 相互印證 (Corroborated)         （兩工具皆標示同一函數 — 價值最高）
  ├── 誤報 (False Positives)         （無害，跳過）
  ├── 缺失的測試 (Missing Tests)       （撰寫單元測試）
  └── 模糊測試目標 (Fuzzing Targets)   （建立模糊測試 harness）

決策樹（Decision Tree）

├─ 需要為某語言設定突變測試？
│  └─ 請閱讀：references/mutation-frameworks.md
│
├─ 需要設定 necessist 或尋找弱測試語句？
│  └─ 請閱讀：references/mutation-frameworks.md（Necessist 章節）
│
├─ 需要深入瞭解分流的判斷標準？
│  └─ 請閱讀：references/triage-methodology.md
│
├─ 需要瞭解圖譜資料如何指引分流？
│  └─ 請閱讀：references/graph-analysis.md
│
└─ 已經取得結果與圖譜？請直接使用下方的 Phase 3。

Phase 1：建立程式碼圖譜並執行預分析

在進行突變測試之前，先使用 trailmark 解析目標程式碼庫並執行預分析。預分析會計算影響範圍（blast radius）、入口點（entry points）、權限邊界（privilege boundaries）與污點傳播（taint propagation），供 Phase 3 分流時使用。

uv run trailmark analyze --language auto --summary {targetDir}

使用 QueryEngine API 建立圖譜並執行預分析：

  1. QueryEngine.from_directory("{targetDir}", language="auto")
  2. 呼叫 engine.preanalysis() — 分流前必做
  3. 使用 engine.to_json() 匯出，以便與突變測試結果進行交叉比對

若自動偵測的語言不正確，請使用明確指定語言或以逗號分隔的列表（如 python,rust）重新執行。

完整 API（包含節點映射、可達性查詢、影響範圍與預分析子圖查詢）請參閱 references/graph-analysis.md。

Phase 2：執行突變測試

選擇並執行適當的框架。各語言的具體設定請參閱 references/mutation-frameworks.md。

擷取倖存的突變體。 雖然各框架的報告格式不同，但請針對每個突變體擷取以下欄位：

欄位 說明
檔案路徑 (File path) 包含突變體的原始碼檔案
行號 (Line number) 施加突變的行號
突變類型 (Mutation type) 變更了什麼內容（運算符、數值等）
狀態 (Status) survived（倖存）、killed（被擊殺）、timeout（超時）、error（錯誤）

進入 Phase 3 時，請僅過濾出**倖存（survived）**的突變體。

Phase 2b：執行 Necessist（選用）

若支援目標語言（Go、Rust、Solidity/Foundry、TypeScript/Hardhat、TypeScript/Vitest、Rust/Anchor），請執行 necessist 以尋找不必要的測試語句。此步驟獨立於 Phase 2，可平行執行。

# 自動偵測框架
necessist

# 或指定特定的測試檔案
necessist tests/test_parser.rs

# 匯出結果
necessist --dump

請過濾出移除語句後測試仍通過的項目。框架特定設定與標準化紀錄格式請參閱 references/mutation-frameworks.md。

依照 references/graph-analysis.md 中的演算法，將每次移除對應回生產環境的函數。

Phase 3：結果分流 (Triage Findings)

針對每個倖存的突變體與 necessist 的移除項目，利用圖譜資料確定其分流類別。Necessist 移除項目必須先映射到生產環境函數（參閱 references/graph-analysis.md）。

快速分類（突變測試）

特徵訊號 類別 原因判斷
圖譜中無呼叫者 誤報 (False Positive) 死碼（Dead code），突變體不可達
僅有測試呼叫者 誤報 (False Positive) 測試基礎設施，非生產程式碼
日誌/顯示字串 誤報 (False Positive) 僅涉及外觀展示，無行為影響
同義突變體 (Equivalent mutant) 誤報 (False Positive) 雖然經過突變，但行為未改變
簡單函數、低 CC、無入口點路徑 缺失測試 (Missing Tests) 單元測試建置相當直接
錯誤處理路徑 缺失測試 (Missing Tests) 應具備負面測試案例（negative test cases）
邊界條件 (Off-by-one) 缺失測試 (Missing Tests) 適合進行基於屬性的測試 (Property-based test)
純函數 (Pure function)，具確定性 缺失測試 (Missing Tests) 容易測試且效益高
高 CC (>10)，可達入口點 模糊測試目標 (Fuzzing Target) 複雜 + 曝露 = 進行模糊測試
解析器/驗證器/解序列化器 模糊測試目標 (Fuzzing Target) 處理結構化輸入
呼叫者眾多 (>10) + 中度 CC 模糊測試目標 (Fuzzing Target) 影響範圍（blast radius）大
二進位/網路通訊協定處理 模糊測試目標 (Fuzzing Target) 模糊測試器擅長格式測試

快速分類（Necessist）

特徵訊號 類別 原因判斷
冗餘的 setup 或除錯呼叫 誤報 (False Positive) 該語句確實不必要
無法映射至生產函數 誤報 (False Positive) 缺少圖譜上下文無法進行分流
呼叫被移除，但無斷言檢查其效果 缺失測試 (Missing Tests) 測試的斷言強度不足
斷言被移除，測試依然通過 缺失測試 (Missing Tests) 涵蓋率冗餘或不足
映射至高 CC 且入口點可達的函數 模糊測試目標 (Fuzzing Target) 複雜 + 曝露 + 測試過弱

當突變測試與 necessist 同時標示同一生產函數時，請標記為相互印證 (corroborated) — 此為可信度最高的發現。

詳細判定標準請參閱 references/triage-methodology.md。

分流用的圖譜查詢

針對每個突變體，將其映射至包含它的圖譜節點，並利用 Phase 1 產生的預分析子圖（tainted, high_blast_radius, privilege_boundary）進行分類。分類邏輯檢查：無呼叫者 → 誤報；權限邊界 → 模糊測試；高 CC + 受污染(tainted) → 模糊測試；高影響範圍 → 模糊測試；其他 → 缺失測試。

batch_triage 的實作與節點映射函數請參閱 references/graph-analysis.md。

輸出格式

生成 Markdown 格式的報告：

# Genotoxic Triage Report

## Summary
- Total survived mutants: N
- Total necessist removals: N
- Corroborated findings: N
- False positives: N (N%)
- Missing test coverage: N (N%)
- Fuzzing targets: N (N%)

## Corroborated Findings
| File | Line | Function | Mutation Signal | Necessist Signal | Action |
|------|------|----------|----------------|------------------|--------|

## False Positives
| File | Line | Mutation | Reason | Source |
|------|------|----------|--------|--------|

## Missing Test Coverage
| File | Line | Function | CC | Callers | Suggested Test | Source |
|------|------|----------|----|---------|----------------|--------|

## Fuzzing Targets
| File | Line | Function | CC | Entrypoint Path | Blast Radius | Source |
|------|------|----------|----|-----------------|--------------|--------|

Source 欄位可為 mutation、necessist 或 corroborated。

請將報告寫入工作目錄中的 GENOTOXIC_REPORT.md。

品質檢查清單 (Quality Checklist)

交付前請確認：

  • [ ] 已針對目標語言建立 Trailmark 圖譜
  • [ ] 突變測試框架已執行完畢
  • [ ] 已執行 Necessist（若支援該語言）或已註明不適用
  • [ ] 所有倖存的突變體皆已完成分流（無未分類項目）
  • [ ] 所有 necessist 移除項目皆已完成分流（若適用）
  • [ ] 已識別出相互印證的發現（若兩工具皆有執行）
  • [ ] 誤報項目皆具備明確的理據說明
  • [ ] 缺失測試項目皆包含建議的測試類型
  • [ ] 模糊測試目標皆包含入口點路徑與影響範圍
  • [ ] 報告檔案已寫入至 GENOTOXIC_REPORT.md
  • [ ] 已向使用者通報摘要統計數據

整合 (Integration)

trailmark skill:

  • Phase 1：建立程式碼圖譜，查詢複雜度與入口點
  • Phase 3：呼叫者分析、可達性、影響範圍

property-based-testing skill:

  • 涉及邊界條件的缺失測試涵蓋率項目
  • 針對序列化突變體的來回轉換/等冪性（Roundtrip/idempotence）屬性

testing-handbook-skills (fuzzing):

  • Fuzzi

<!-- truncated for translation batch; full body continues in source -->