splider/spec.md

项目定位

豆瓣滑块验证码检测器使用 Node.js + Sharp，对静态截图中的滑块缺口进行自动定位。当前版本聚焦豆瓣样式的双滑块图片，要求识别 1~2 个滑块并输出带标注的结果图。

数据输入

• images/douban/：待检测图片，命令行默认扫描该目录。
• images/douban-target/：对应图片的人工红框标注，用于准确性验证。
• images/output/：检测结果输出目录（自动生成，蓝框标注）。
• 自定义目录可通过 npm run detect -- --pic-dir=<relative-path> 指定。

检测要求

1. 支持 1~2 个滑块的定位，允许图片存在缺失或额外背景元素。
2. 输出的边界框应与人工标注的中心点偏差 ≤ 10 px，IoU ≥ 0.1 视为可接受匹配。
3. 允许算法返回多个候选框；验证阶段会进行一对一匹配并统计准确率、召回率。
4. 结果需在原图上以蓝色矩形绘制并写入 images/output/。

算法概览

1. 预处理：同时读取原始图与归一化图，生成原始 RawImage、增强版图像。
2. 候选生成（src/detection/candidate-search.ts）：
   • 多阈值暗/亮区域扫描 → 连通域过滤
   • Sobel 边缘图 → 形态学闭运算补全边界
   • 颜色量化 + LAB 色差检测 → 识别低对比度候选
   • IoU 去重后，依据正方形程度、颜色一致性、内部边缘稀疏度、外部梯度平滑度重新评分。
3. 框体精炼：使用边缘投影收紧候选框边界。
4. 自学习扩展（src/detector-self-learning.ts）：将最佳候选作为模板，在同一水平带上搜索第二个滑块。
5. 结果绘制：SliderDetector.annotate 在输出图片上渲染所有有效框体。

验证流程

• CLI (src/cli.ts) 会加载 ground-truth.json，对默认目录进行逐图检测。
• 使用 SliderValidator 计算匹配情况，终端输出每张图与总体的准确率、召回率。
• 若指定 --pic-dir，仍会先运行 ground-truth 评估（若文件存在），再处理目标目录。

开发约定

• 代码组织遵循模块划分：detector.ts（主检测器）、detection/（候选策略）、utils/（基础工具）、validator.ts（验证）。
• 新增检测策略时建议在 candidate-search.ts 中扩展，对应评分指标需保持可调节权重。
• 所有新增图像应放入 images/douban / images/douban-target 并更新 ground-truth.json。
• 运行 npm run build 进行类型检查；npm run detect 验收算法表现。