Transaction Screening Skill — 制裁名单搜索

自动从公开 URL 拉取制裁名单，直接在 WorkBuddy 中搜索比对，零部署。

数据源

全部 10 个源共 ~71.8K 条目。HK 为 PDF 格式，首次使用自动安装 pdfplumber。本地 CSV 数据源无需联网。

依赖说明（离线部署必读）

核心脚本（search.py / screen.py）纯 Python 标准库，零第三方依赖。以下三个可选依赖用于特定功能，缺失时会自动尝试安装（需联网）：

离线部署注意：
1. 自动安装本质是 pip install，需要联网；离线环境三者都装不上。
2. 离线使用请预先装齐：python -m pip install openpyxl pypinyin
3. 数据缓存在 data/cache/，load_index() 直接读缓存、不检查有效期，离线可用（数据为上次 fetch 的快照，会随离线时间变旧）。
4. 最省事：联网装齐依赖 + fetch.py 拉满缓存 → 打包整个 skill 目录（含 cache）→ 离线解压即用。

工作流 A：单实体搜索（主要模式）

用户说 "查 XX公司" → 按以下步骤：

Step 1：确保缓存存在

脚本在 <skill_dir>/scripts/ 下，用系统 python3 运行即可。

# 检查缓存状态
python3 <skill_dir>/scripts/search.py --sources

AI 助手会自动定位 skill 目录和 Python 解释器，无需手动指定路径。

如果缓存为空或缺少某个源，先拉取：

python3 <skill_dir>/scripts/fetch.py --source "OFAC SDN (美国制裁名单)"
python3 <skill_dir>/scripts/fetch.py --source "UK FCDO (英国制裁名单)"

Step 2：执行搜索

python3 <skill_dir>/scripts/search.py "用户输入的实体名" --top 10

Step 3：解读结果

• ≥85% 🔴 高置信度 — 很可能命中，列出匹配详情
• 60-84% 🟡 中等 — 可能相关，建议人工确认
• 35-59% 🟢 低 — 大概率是字符串巧合
• 无结果 — 该实体不在制裁名单中

如果用户说 "展示更多" 或 "只显示高置信度"，调整 --top 和 --min-score 参数。

如果有高置信度匹配（≥60%），提示用户注意误报可能（如短音节拼音匹配）。

关于企业名称停用词过滤（v2.5）

中文企业名称中常见通用词（科技、信息技术、有限公司、国际、集团等 80+ 词）在计算相似度时会被自动剔除，避免「南京春雨灌溉科技有限公司」和「保利科技有限公司」因共享「科技有限公司」后缀而产生误报。

• 剔除仅用于 token overlap 和 SequenceMatcher 评分
• 精确匹配和子串匹配保留原文（不影响精准命中）
• 中文→英文拼音桥接受 _STOP_SYLLABLES 独立控制，不受影响

关于拼音桥接（v2.5.1 词边界匹配）

search.py 默认启用拼音桥接，但做了四层过滤：

1. 先剥离再滑窗: 对 pinyin 字符序列先剔除所有停用词跨度（城市名/企业后缀/噪声字），再对剩余有意义字符做滑动窗口
2. 城市/地区名过滤: 北京/上海/深圳等 30+ 城市名 + 中国/香港等地区名的拼音加入 _STOP_SYLLABLES，避免「深圳XX」误匹配「SHENZHEN YY」
3. 词边界匹配（\b）: 拼音 token 必须在英语名中作为独立单词出现，而非词内碎片
   - kunlun 在「BANK OF KUNLUN CO LTD」→ 独立词 ✓
   - shishi 在「tarSHISHI」→ 嵌入长词 ✗
4. 评分上限 0.45: 纯拼音匹配永远进 review 区间，不可能进 hit（≥85%）

批量筛查默认启用拼音，可用 --no-pinyin 关闭。

关于繁简转换（v2.6.2）

search.py 内置繁→简对照表（_T2S，600+ 常用字），查询词与名单名在精确/子串匹配前统一归一化到简体域：

• 解决「简体查询 vs 繁体名单」的字面差异漏报（如简体「腾讯控股」能命中繁体「騰訊控股」）
• 纯 stdlib 字典映射，零依赖、离线可用
• 仅转换一对一确定的繁简映射，歧义字保留原样，避免误转换引入误报

关于实体类型识别（v2.6.3，规则版）

search.py 内置 _guess_entity_type() 规则版实体类型提示（非 NER，无模型、零依赖），识别查询词为三类：

原则：宁少标不多标——无法判断时返回「未知」（如 2 字简称「华为」、2 字人名「马云」都返回未知，避免误判）。仅做提示，不参与命中判定。

关于简称/缩写展开（v2.6.4）

data/aliases.json 内置简称→全称对照表（~280 条，覆盖高校/央企/国企/银行/知名民企 + 英文缩写 + 地名单字），search.py 的 _expand_aliases() 在筛查前把查询词中的简称展开成全称再比对：

• 精确简称：「工行」→「中国工商银行」「ICBC」
• 包含替换：「哈工大深圳」→「哈尔滨工业大学深圳」
• 单字地名单字（京/沪/穗…）仅精确匹配时展开，避免「京东」误替换成「北京东」
• 数据在 data/aliases.json，可自行增补；纯字典规则、零依赖

局限：只能展开表内收录的简称，表外的简称（生僻缩写、非标简称）仍识别不了。

关于类型维度交叉验证（v2.6.5）

search.py 内置 _dimension_conflict()，当查询词类型与命中对象类型维度不一致时降级置信度 + 提示人工复查（不直接放过、也不判死）：

• 地址识别扩展：中文街道后缀（街/路/巷/弄…）+ 英文街道词（street/road/avenue…）+ 门牌号模式（12号/No.12）
• 降级规则：命中（hit）→ 待复核（review）；命中对象类型未知时，仅靠「查询为地名」单边信号降级
• 呈现：HTML 报告卡片加醒目标记「⚠️ 类型维度不匹配…建议人工复查」，CSV 加 dimension_conflict 列

关于子串匹配约束（v2.6.6）

子串匹配加 A+B 过滤，避免「长查询词碰巧含短名单名」的纯字面巧合误报（如「华润」简称展开成「China Resources」后，resources 含 eso、china 含 ina 撞上名单名）：

• A 比例约束：子串长度 / 较长方长度 ≥ 0.5 才给分（过滤长串里嵌短串）
• B 短名单名保护：名单名 < 5 字符不参与子串匹配（过滤 Eso/INA 这类 3 字符名）
• 效果：修复后「华润」不再误命中 Eso/INA（review 从 10 条降到 8 条）

工作流 C：批量筛查（Excel → CSV + HTML 报告）

输入 Excel 文件（.xlsx），自动提取所有名称列，逐条搜索并输出：

<managed_python> <skill_dir>/scripts/batch_screen.py <input.xlsx> --html

输出：
- CSV：每实体一行，含 verdict/score/matched_name/sources/top_matches
- HTML 报告（--html）：含统计面板、来源概览、逐实体匹配卡片、可折叠匹配详情

常用参数：

工作流 B：添加新名单源

用户提供了新名单 URL → 用 fetch.py --add-url 拉取，会自动合并到搜索索引：

# 基本用法
<managed_python> <skill_dir>/scripts/fetch.py \
  --add-url "<URL>" --name "自定义名单名"

# CSV 需要指定参数时
<managed_python> <skill_dir>/scripts/fetch.py \
  --add-url "<URL>" --name "我的名单" \
  --name-field "entity_name" --delimiter "," --skip-rows 0

# 无 header 的 CSV
<managed_python> <skill_dir>/scripts/fetch.py \
  --add-url "<URL>" --name "无头CSV" \
  --csv-columns "id,name,type" --name-field "name"

自动合并： 新名单拉取后，后续所有 search.py 调用自动包含它。不需要额外操作。

本地文件也支持： 把 URL 换成本地路径即可，如 /path/to/my_list.csv。

参数速查

search.py

fetch.py