Upload docs/EVALUATION.md with huggingface_hub

docs/EVALUATION.md

@@ -1,3 +1,98 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:9e82488c89202d7e1e48ce03d54244408b52351392ed8cc84558f7dc3cdca987
-size 3376
+# 评估方法 (EVALUATION.md)
+
+> **English summary**: The 87.6% login rate comes from real forum logins, not offline guessing.
+> Each attempt: fetch login page → fetch captcha → model inference → submit → the forum's
+> response is the ground truth ("login success" = correct, "code incorrect" = wrong). 100
+> attempts, 97 valid (3 rate-limited), 85 successes = 87.6%. Validation-set accuracy (held out,
+> 79 images) was 88.6%, cross-confirming the result.
+
+本文档说明 **87.6% 登录命中率** 是如何测量的，保证结果可复现、可信。
+
+## 核心原则
+
+南+ 验证码的 ground truth 没有公开数据集，因此我们使用**真实论坛登录**作为唯一的、100% 可靠的判定标准：
+
+> **论坛返回"登录成功" = 模型识别正确**
+> **论坛返回"认证码不正确或已过期" = 模型识别错误**
+
+每次判定都是干净的二元结果，不依赖任何主观估计。
+
+## 测试流程 (逐次尝试)
+
+对每一次尝试，严格按登录流程执行：
+
+1. **抓取登录页** → 解析表单与验证码 URL（带会话 cookie）
+2. **抓取验证码图片**（带时间戳防缓存，150x60 PNG）
+3. **模型推理** → 输出 4 位数字
+4. **提交登录**（带会话 cookie + 表单隐藏字段 + 识别结果）
+5. **读论坛响应** → 成功 / "认证码不正确"
+6. **清空本地会话** → 下一次以全新游客身份开始
+
+关键保证：
+- 每张验证码绑定独立会话，识别结果与提交严格一一对应，**不存在会话错位**
+- 失败响应用 `SP_DEBUG_LOGIN` 落盘逐条核对，确认是真实"认证码不正确"，而非网络错误/风控页
+- 网络层干扰（连接超时、挑战页）不计入统计
+
+## 测试环境
+
+| 项 | 值 |
+|---|---|
+| 站点 | south-plus.net |
+| 网络 | 家庭 IP + Cloudflare IP 钉定（绕过 DNS 污染） |
+| 请求间隔 | 7 秒（尊重论坛限流） |
+| 账号 | 真实有效账号，密码经登录成功确认 |
+| 模型 | captcha_1000_raw.onnx (88.6% val) |
+
+## 结果
+
+### 100 次登录 (最终正式测试)
+
+| 结果 | 次数 |
+|---|---|
+| 登录成功 | **85** |
+| 认证码不正确 | 12 |
+| 被论坛风控拦截 (不计入) | 3 |
+| **合计有效** | **97** |
+
+**单次命中率 = 85/97 = 87.6%**
+
+### 早期小样本 (供参考)
+
+| 测试 | 结果 | 命中率 |
+|---|---|---|
+| 15 次 | 13/15 | 86.7% |
+
+### 重试收益
+
+论坛登录流程支持多次重试（每次抓新验证码）：
+
+```
+P(6次内至少成功1次) = 1 - (1 - 0.876)^6 = 99.9997%
+```
+
+即：**平均 10000 次登录中，约 3 次会在 6 次重试内全部失败。**
+
+## 置信度
+
+- 100 次大样本 + 每次二元硬判定 → 统计置信度高
+- 与 15 次小样本 (86.7%) 高度一致 → 结果稳定
+- 留出验证集 (79 张, 8%) 精度 88.6% 与登录命中率 (87.6%) 接近 → 交叉印证
+
+## 复现
+
+评估使用的工具链（harness）在 `scripts/` 下，核心逻辑：
+
+```
+tmp_captest/main.go   登录测试 harness（抓取→识别→提交→判定→清会话）
+scripts/onnx_ocr_raw.py  模型推理（RGB 160x64 /255 → argmax）
+```
+
+真实测试命令：
+```bash
+go run ./tmp_captest -mode login -n 100 -gap 7 \
+  -user <USER> -pass <PASS> -variant onnx \
+  -ocr scripts/onnx_ocr_raw.py -ip 104.21.43.10 \
+  -out /tmp/sp_test
+```
+
+> 注意：南+ 对登录有风控，测试请控制节奏并尊重论坛规则。