SkillSpector Batch Scan 未来工作路线图:从已知限制到优化方向的全景剖析
SkillSpector Batch Scan 未来工作路线图:从已知限制到优化方向的全景剖析
本文以
contrib/batch_scan模块的 FUTURE_WORK.md 为骨架,系统梳理多语言批量扫描器的 12 个已知限制与演进方向,并对照api_pool.py、detection.py、runner.py、gap_fill.py等源码与 164 项测试,讲清每个问题"为什么存在、影响是什么、下一步怎么做"。读完你将掌握该模块的架构取舍、可插手的贡献点,以及评估其稳定性的完整视角。
背景:这份路线图针对什么
contrib/batch_scan 是 SkillSpector(AI Agent 技能安全扫描器)的独立 contrib 子模块,用于并行扫描整个目录树下的技能(每个技能一个含 SKILL.md 的子目录),并针对非英语技能自动做语言检测与 LLM gap-fill 补漏,核心入口与并发模型见 batch_scan.py 与 DESIGN.md。
FUTURE_WORK.md 定位非常明确:诚实评估当前版本未覆盖之处,以及贡献者可以接手的下一步方向。文档最后更新于 2026-06-26(PR #100 评审解决之后),因此文中的"✅"标记代表已经落地并经过测试验证的部分,其余则是对未来工作的具体建议。它既是新贡献者的入场地图,也是评审者评估模块成熟度的参考清单。
1. API Key Pool 覆盖:已完成的"双补丁"接线
当前状态(✅ 已完成)
文档明确:所有 LLM 调用——包括 graph 内部的 20 个分析器(每个技能一次完整扫描)以及 gap-fill 补漏环节——都通过共享的密钥池(set_api_pool())路由。关键实现细节是"双补丁":
- 同时 patch
skillspector.llm_utils.get_chat_model和skillspector.llm_analyzer_base.get_chat_model; - 原因是
llm_analyzer_base内部通过from ... import引入了局部引用,只 patch 单模块会形成绕过池的旁路; test_pool_wiring.py用 3 条路径(graph 分析器、meta 分析器、gap-fill)验证了全部调用都落到PooledChatModel。
这段接线逻辑在 runner.py 中有完整实现:set_api_pool(pool) 保存原始工厂函数 _original_get_chat_model,替换为 _pooled_get_chat_model,并通过 _llm_utils.register_chat_model_provider(pooled_model, "openai") 注册;调用 set_api_pool(None) 则恢复两个模块的原始工厂。
剩余缺口:全局变量 vs 上下文变量
文档指出的剩余缺口是:set_api_pool 使用模块级全局变量持有池引用。更优雅的方案是使用 contextvars.ContextVar 或把池引用穿进 graph state,但当前设计对批处理工作负载足够——因为池在扫描开始前一次性设置,运行期间不会变更。
贡献建议:若未来需要同一进程内并发运行多个扫描任务(各自使用不同的池),可将全局替换为 ContextVar,成本主要在 runner.py 与 api_pool.py 的联动改造。
2. Checkpoint / Resume:大仓库扫描的可靠性短板
问题本质
当前版本不写任何中间状态到磁盘。文档举了一个非常具体的场景:扫描 1000 个技能,在第 847 个技能处失败,此前全部进度丢失,只能从零重扫。在大型仓库上这意味着单次故障的代价是"整轮重来"。
建议方向(文档原话)
- 每个技能完成后,将其结果追加写入
_batch_checkpoint.jsonl; - 重启时跳过已在 checkpoint 中的技能;
- 该文件同时充当进度日志(progress log);
- 文档估算改动量约为
batch_scan.py的 ~50 行。
从源码看落地位置
并发控制集中在 batch_scan.py:ThreadPoolExecutor 提交任务后,在 as_completed 循环里逐个 future.result(timeout=90) 取结果。当前超时/崩溃分支只做 errors += 1 并打印 TIMEOUT (90s) / CRASH,之后 continue——这正是 checkpoint 写入的理想插入点:成功分支写结果行,异常分支记录失败技能路径,重启时按行号去重。
现实影响
对 CI 集成(README 中给出的退出码约定:0=全部安全,1=存在 HIGH/CRITICAL,2=扫描错误)而言,checkpoint 还能把"失败重跑"变成增量行为,显著降低大批量扫描的运维成本。
3. 语言检测覆盖:4 种脚本的局限与扩展路径
当前实现
语言检测使用 Unicode script-ratio(脚本字符占比)启发式,零第三方依赖,只依赖标准库 unicodedata。核心实现见 detection.py:
| 脚本 | 语言 | Unicode 范围 | 判定阈值 |
|---|---|---|---|
| CJK 统一表意文字 | 中文 (zh) | 0x4E00–0x9FFF(含扩展 A 0x3400–0x4DBF) |
CJK 占比 ≥ 10% |
| 平假名 + 片假名 | 日文 (ja) | 0x3040–0x309F、0x30A0–0x30FF |
假名占比 ≥ 5% |
| 谚文音节 | 韩文 (ko) | 0xAC00–0xD7AF |
谚文占比 ≥ 10% |
| 其他 | 英文 (en) | — | 默认 |
注意检测顺序:先判假名(ja),再判谚文(ko),最后判 CJK(zh),这是为了避免高汉字密度的日文被误判为中文。detect_skill_language() 对技能内所有文件的结果做多数投票(majority vote)。
已知缺陷(文档明确指出)
- 日文误判:汉字密度高、假名频率低的日文文本可能被误判为中文;
- 混语言技能:多数投票无置信度输出,无法表达"不确定";
- 覆盖不足:西里尔文、阿拉伯文、拉丁扩展(法语/德语/西语)、天城文、泰文等一律落回
en,导致这些语言的技能失去 gap-fill 覆盖(README 的 Known Limitations 也列了这一点)。
候选扩展语言表(文档原表)
| Script | Language | Unicode range | Difficulty |
|---|---|---|---|
| Cyrillic | Russian (ru) | 0x0400–0x04FF | Low |
| Arabic | Arabic (ar) | 0x0600–0x06FF | Medium — RTL |
| Latin extended | French (fr), German (de), Spanish (es) | 0x00C0–0x024F | Low |
| Devanagari | Hindi (hi) | 0x0900–0x097F | Medium |
| Thai | Thai (th) | 0x0E00–0x0E7F | Low |
(按 AI 采用密度排序。)
建议方向
- 在
detection.py增加对应 Unicode 范围 + 阈值常量; - 返回值附带置信度分数(confidence score),而不是裸语言标签;
- 增加
--confidence-thresholdCLI 参数,低于阈值的技能回退到保守策略。
贡献提示:文档特别强调——语言检测目前没有任何单元测试(detect_language()、script-ratio 阈值均无测试覆盖),因此扩展语言的同时补齐测试是低风险高价值的第一步。
4. 输出格式:SARIF 与安全漂移对比
当前支持
终端(Rich)、JSON、Markdown 三种格式,由 -f terminal | json | markdown 选择,格式化器实现在 reports.py。上游 SkillSpector 本身支持 SARIF。
建议方向
-f sarif:文档指出 SARIF 的runs[].results[].locations[].physicalLocation可以干净地映射到Finding.location/file/start_line。仓库中已有 SARIF 相关基础设施(src/skillspector/sarif_models.py与tests/unit/test_sarif.py、tests/nodes/test_sarif_rules_and_empty_findings.py),迁移成本主要在 reports 层做 schema 转换。--diff report1.json report2.json:对比两份报告的差异,用于追踪安全漂移(security drift over time)——比如同一技能集升级后,风险分是升高还是下降。
从源码看意义
batch 报告的 JSON 结构(见 runner.py 的 entry_from_result())已经包含 skill.language、scan_mode: "multilingual-enhanced"、enhancements.gap_fill_applied、enhancements.english_keyword_rules_skipped 等溯源字段,为 diff 模式提供了天然的比较键(skill.source + scanned_at)。
5. 自动化测试:164 项测试的现状与缺口
已覆盖(✅ 部分完成)
| 测试族 | 数量 | 覆盖内容 | 文件 |
|---|---|---|---|
| 单元测试(随机顺序 seed=42) | 120 | 池 acquire/release/backoff(45)、gap-fill 解析(41)、patch(24)、annotation(10) | tests-pro/ |
| Pool 接线冒烟 | 4 | 3 条路径均走 PooledChatModel | test_pool_wiring.py |
| Monkey-patch 侵入性 | 14 | 线程隔离、import 安全、50 实例并发 | test_monkeypatch_invasiveness.py |
| Monkey-patch 脆弱性 | 26 | 每个 patch 的 guard 验证、深层依赖检测、原子性 | test_monkeypatch_fragility.py |
| 变异测试 | 30 个注入 bug | 捕获 21/30 | mutation_max.py |
剩余缺口(文档明确列出)
- 语言检测无单元测试:
detect_language()与 script-ratio 阈值没有任何测试; - 集成测试仍为手动:针对
tests/fixtures/的集成验证还没有自动化; - 非英语 ground-truth fixtures 不存在:zh/ja/ko 技能样例缺失,无法做自动化精度评估;
- 池级并发竞态未覆盖:snapshot-vs-acquire、key-recovery-vs-new-acquire 这类时序竞态尚无自动化测试。
贡献提示:tests/docs/TEST_DESIGN.md(为何设计每套测试)与 tests/docs/TEST_GUIDE.md(每文件覆盖什么、怎么运行)是理解测试意图的最佳入口;tests/docs/BUGS_FOUND.md 记录了测试过程中发现的 16 个 bug。
6. 非英语 Gap-Fill 质量基线:缺失的量化评估
背景
gap-fill 是批处理扫描器最有价值的部分:当技能被判定为非英语时,25 条英语关键词静态规则会失去召回(annotation._ENGLISH_KEYWORD_RULES),其中 17 条已有语义分析器(SSD/SDI/SQP)兜底,剩余 8 条规则(P5、P6–P8、MP1–MP3、RA1–RA2)没有任何对应发现规则。GapFillAnalyzer 继承自 skillspector.llm_analyzer_base.LLMAnalyzerBase,获得 token 预算感知的批处理、Pydantic 结构化输出与 arun_batches 并行执行能力——见 gap_fill.py。
当前问题
gap-fill 的正确性目前只靠人工检查验证,不存在针对非英语技能的系统性 ground-truth 对比。也就是说:我们知道它"工作",但不知道它的精确率(precision)/召回率(recall)是多少。
建议方向
- 构建非英语 fixtures(覆盖 8 条 gap-fill 规则的 zh/ja/ko 已知漏洞技能);
- 运行 gap-fill,测量 precision/recall;
- 发布基线数据供后续版本对照。
7. Worker 调度:从朴素线程池到自适应调度
当前实现
ThreadPoolExecutor(max_workers=N),N 由 --workers 指定(默认 4),见 batch_scan.py。它对 API 池容量毫无感知。
问题
当 worker 数超过 API 池的有效并发能力时,多余 worker 在 ApiKeyPool.acquire() 上排队(参考 api_pool.py 的阻塞等待逻辑),浪费线程资源。
建议方向
- 根据池的空闲槽位做自适应 worker 数;
- 增加
--auto-workers标志,从池容量推导N。
注意池设计本身已经解耦了 worker 数与 key 数:每个 key 有 max_concurrent(默认 5)个并发槽,采用最不忙碌(least-loaded)调度,只有在所有非限流 key 都满时才阻塞。因此"自适应"主要解决的是 worker 与总槽位的匹配,而不是 1:1 对应。
8. ChatOpenAI 每次调用实例化:开销与失败的缓存尝试
当前状态
PooledChatModel._build_llm() 每次 LLM 调用都会 new ChatOpenAI(...)(见 api_pool.py)。文档给出的实测量级:23 个技能的扫描约产生 800 次调用,每次重建实例带来可测开销。
失败尝试(文档如实记录)
池级实例缓存曾被尝试但反而更慢——因为 ChatOpenAI 内部的 AsyncClient 是 event-loop 绑定的,跨线程复用会引发循环切换开销。
建议方向
按 event-loop 缓存(per-event-loop caching),文档估计可带来约 15–20% 的速度提升。这是一个典型的"知道问题也知道约束"的优化点:想清楚缓存键是哪个 event loop,再动手。
9. 池可观测性:缺命中/未命中计数器
当前状态
ApiKeyPool 已同时实现非阻塞的 try_acquire() 与阻塞的 acquire(),但没有跟踪命中/未命中比率。现有的 snapshot() 方法(api_pool.py)已能输出 keys_configured、total_capacity、active_requests、peak_active_requests、total_requests_served、keys_rate_limited、rate_limits_hit、retry_successes 等指标,唯独缺少 try_acquire_hits / try_acquire_misses。
建议方向
- 在
snapshot()中暴露try_acquire_hits / try_acquire_misses; - 配合 batch_scan.py 末尾的
API Pool: N requests served, peak X/Y slots, Z rate-limit(s), R retried汇总行,可以直观判断"worker 数是否远超池容量"。
这是一个改动量极小的观测性增强,对调优 --workers 很有价值。
10. DeepSeek 特定约束:三条硬事实
文档用三点概括了 DeepSeek 作为后端时的特殊性,这些约束直接塑造了 runner.py 中 7 个兼容补丁的设计:
-
无
response_format支持:DeepSeek API 不支持结构化输出(structured output)。上游无条件调用with_structured_output()会返回 HTTP 400。因此 Patch 1(self.response_schema = None)是必需的——上游若提供response_format的可选关闭开关,就能移除 Patch 1–5(见 runner.py 的补丁注释)。 -
账户级限流:同一 DeepSeek 账户下的多个 key 共享并发预算,因此"10 个 key 的池"无法绕过账户级限流——配置 key 数量时要把这一点考虑进去。
-
API 速度波动:每个技能的单次扫描耗时随时间呈现 2–3 倍波动(高峰/低谷),这解释了为什么要设 90 秒技能级超时以及 HTTP 级超时补丁(Patch 6:
httpx.Timeout(connect=8s, read=30s))。
这些约束的详细机制与"为什么用实例属性而非类属性"的线程安全论证,见 DESIGN.md 与 PITFALLS.md。
11. 自定义池 vs 成熟库:为什么暂时不换
ApiKeyPool 是从零手写的(~640 行,含 ApiKey 数据类、least-loaded 调度、指数退避、PooledChatModel 包装器)。文档列出了 5 个现成替代方案作为对照:
| Library | Pitch |
|---|---|
rotapool |
带 CooldownResource 生命周期的资源池——与本设计最接近 |
apirotater |
轻量 key 轮换,带每 key 速率窗口 |
llm-keypool |
多 provider、能力标签、429 冷却、内置代理 |
envrotate |
极简:从环境变量读 key,随机/轮询 |
pyrate-limiter |
通用限流器——与本设计互补 |
为什么现在不换(文档立场):自定义池"经过实战检验(battle-tested)、完全被理解、已深度集成"。README 中给出的一线数据佐证了它的可用性:10 个 key + 8 workers 扫 23 个 fixture 技能可以稳定完成。文档建议仅当维护负担增长或某个库证明自己时再重新评估。
12. 其他方向:四个未启动的探索点
- MetaAnalyzer 并行化:LLM 调用占每个技能 wall time 的 20–30%。但 MetaAnalyzer 是上游 graph 拓扑的一部分,改动需要修改上游 graph 结构(对"零改动上游"的贡献模块定位构成挑战)。
- 本地模型兼容性:验证并文档化 Ollama / llama.cpp 兼容性——配合
--no-llm之外的本地推理场景。 - 跨文件数据流分析:在批处理构建阶段做文件级 import 依赖分析,为行为分析提供跨文件视野。
- 文件缓存优化:消除冗余磁盘读。文档明确标注为低优先级——瓶颈在 LLM 调用而非 I/O。
汇总:12 项方向一览
| # | Area | Status | Next Step |
|---|---|---|---|
| 1 | Pool coverage | ✅ 双补丁(llm_utils + llm_analyzer_base) | 上下文变量(ContextVar)细化 |
| 2 | Checkpoint | 未实现 | JSONL 进度日志 + 重启跳过 |
| 3 | Language detection | 4 种语言、无置信度 | 扩展到 9+ 语言;返回置信度 |
| 4 | Output formats | Terminal/JSON/Markdown | SARIF + diff 模式 |
| 5 | Testing | ✅ 164 项(120 单元 + 44 主题) | 语言检测测试 + 集成测试 |
| 6 | Gap-fill baseline | 未量化 | 非英语 fixture 集 + precision/recall |
| 7 | Worker scheduling | 朴素 ThreadPoolExecutor | 自适应调度(--auto-workers) |
| 8 | ChatOpenAI caching | 每次调用新建实例 | 按 event-loop 缓存 |
| 9 | Pool observability | 无命中/未命中计数 | 暴露 try_acquire 指标 |
| 10 | DeepSeek constraints | 已文档化 | 上游提供 response_format 关闭开关 |
| 11 | Pool vs. libraries | 自研且经过实战检验 | 维护负担增长时再评估 |
| 12 | Additional directions | 未启动 | MetaAnalyzer、本地模型、数据流、缓存 |
参与指南与代码约定
FUTURE_WORK.md 结尾指向了代码约定文档。从 CONTRIBUTING.md 中可以提炼出贡献者需要遵守的核心约定:
- 每个
.py文件带 SPDX header,首行 import 为from __future__ import annotations; - import 顺序:标准库 → 第三方 →
skillspector.*→ 相对导入; - 类型注解用
| None语法而非Optional[X]; - 模块级常量用
frozenset/Final(UPPER_SNAKE_CASE),私有辅助函数_lower_snake_case; - 每个模块
logger = get_logger(__name__),注释解释"为什么"而非"是什么"; - 提交信息用祈使句现在时(如
fix:/feat:/docs:),需带Signed-off-by(NVIDIA DCO)尾部。
CONTRIBUTING.md 还总结了三条改动前必须理解的设计要点:① 双补丁池接线(from ... import 旁路陷阱);② Patch 1 用实例属性注入而非类属性(类属性变更会导致跨线程竞态,V1 就死在这里);③ _verify_patch_targets() 的 guard-before-apply(上游 API 变化时 fail closed,绝不静默失败)。
从贡献优先级看:文档与 README 共同指向的高价值方向是——checkpoint/resume(防止大扫描数据丢失)、语言检测扩展(9+ 语言,且当前无测试是绝佳切入点)、SARIF 输出、非英语 ground-truth fixtures。这四个方向都在 CONTRIBUTING.md 中被明确点名,且改动面相对可控、可验证路径清晰(164 项既有测试 + 变异测试框架 mutation_max.py 可衡量新代码的抗 bug 能力)。
结语
FUTURE_WORK.md 的价值不在于"承诺完成",而在于它精确画出了模块的能力边界:哪些已经过测试验证(池接线、7 个兼容补丁、164 项测试),哪些是明确缺口(checkpoint、语言覆盖、SARIF、gap-fill 基线),哪些是踩过坑后的清醒认知(DeepSeek 无结构化输出、账户级限流、ChatOpenAI 缓存失败尝试)。对想要为 SkillSpector 生态贡献的开发者来说,这是一份难得的"问题清单 + 实现提示";对使用者来说,它也是一份诚实的能力说明书——知道哪里可靠,哪里需要自己兜底。