aho-corasick

Aho-Corasick Skill

高效能多 pattern 同時比對，適合關鍵字過濾、敏感詞偵測、文件掃描與 redact。

依賴安裝

pip install ahocorasick-rs --break-system-packages

環境若已安裝可跳過。

四種核心功能

功能	說明	對應 script
search	在文字/檔案中找出所有 pattern 的出現位置	scripts/ac_search.py
filter	判斷文字是否包含任何 pattern（回傳 True/False + 命中清單）	scripts/ac_filter.py
scan	批次掃描多個檔案，回傳每個檔案的命中結果	scripts/ac_scan.py
redact	將命中的 pattern 替換成指定字串（預設 ***）	scripts/ac_redact.py

使用方式

1. Search — 找出所有命中位置

# 從文字輸入
python scripts/ac_search.py --patterns "apple,banana,cherry" --text "I like apple pie and banana bread"

# 從檔案讀取 patterns（每行一個）
python scripts/ac_search.py --patterns-file patterns.txt --text "some text here"

# 搜尋檔案內容
python scripts/ac_search.py --patterns "error,warning,critical" --file /var/log/app.log

輸出範例：

{
  "matches": [
    {"pattern": "apple", "start": 7, "end": 12},
    {"pattern": "banana", "start": 21, "end": 27}
  ],
  "total": 2
}

2. Filter — 敏感詞/關鍵字過濾

python scripts/ac_filter.py --patterns-file blocklist.txt --text "This contains badword here"

輸出範例：

{
  "flagged": true,
  "matched_patterns": ["badword"],
  "count": 1
}

3. Scan — 批次掃描多個檔案

# 掃描目錄下所有 .txt 檔
python scripts/ac_scan.py --patterns-file keywords.txt --dir ./docs --ext .txt

# 掃描指定多個檔案
python scripts/ac_scan.py --patterns "TODO,FIXME,HACK" --files file1.py file2.py file3.py

輸出範例：

{
  "summary": {"files_scanned": 3, "files_with_matches": 2, "total_matches": 7},
  "results": [
    {"file": "file1.py", "matches": [{"pattern": "TODO", "line": 12, "context": "# TODO: fix this"}]},
    {"file": "file2.py", "matches": []},
    {"file": "file3.py", "matches": [{"pattern": "FIXME", "line": 5, "context": "# FIXME broken"}]}
  ]
}

4. Redact — 替換/遮蔽命中內容

# 預設替換成 ***
python scripts/ac_redact.py --patterns "John,secret,password" --text "John knows the secret password"

# 自訂替換字串
python scripts/ac_redact.py --patterns-file pii.txt --text "Call John at 0912-345-678" --replacement "[REDACTED]"

# 替換檔案內容並輸出
python scripts/ac_redact.py --patterns-file pii.txt --file input.txt --output redacted.txt

輸出範例：

{
  "redacted_text": "*** knows the *** ***",
  "replacements_made": 3
}

在 Python 中直接呼叫

Claude 也可以直接在 code execution 中使用，不需要走 CLI：

import subprocess, json

result = subprocess.run(
    ["python", "scripts/ac_search.py", "--patterns", "error,warning", "--text", log_text],
    capture_output=True, text=True
)
data = json.loads(result.stdout)

或直接 import：

import ahocorasick_rs

ac = ahocorasick_rs.AhoCorasick(["apple", "banana", "cherry"])
matches = ac.find_matches_as_indexes("I like apple and banana")
# [(0, 7, 12), (1, 17, 23)]  → (pattern_index, start, end)

注意事項

• 大小寫：預設區分大小寫。如需 case-insensitive，在 patterns 前處理（如全轉小寫）並對 haystack 同步處理。
• 空 pattern：ahocorasick_rs 不支援空字串 pattern，會拋 ValueError，script 已做防護。
• 大檔案：scan 模式對每個檔案逐行處理，避免一次載入超大檔案進記憶體。
• Overlapping：若需要找出重疊的命中（例如 pattern "ab" 和 "abc" 在同一位置），加上 --overlapping flag。