docs: define supported captcha version scope

Document that the checkpoint is trained only for the four-digit captcha images from the target deployment footer label v0.7β, and mark other PHPWind releases, forks, themes, and generators as unverified.

README.md

@@ -2,6 +2,7 @@
 language:
   - en
 license: agpl-3.0
+library_name: onnxruntime
 tags:
   - captcha
   - ocr
@@ -11,91 +12,109 @@ tags:
 pipeline_tag: image-to-text
 model_type: phpwind-captcha-ocr
 metrics:
-  - name: "validation accuracy"
+  - name: validation accuracy
     type: accuracy
-    value: 0.886
-  - name: "per-attempt login success"
-    type: accuracy
-    value: 0.876
-  - name: "login success with retries"
-    type: accuracy
-    value: 0.999997
+    value: 0.8861
 ---
 
 # PHPWind Captcha OCR
 
-An OCR model for the built-in **PHPWind forum captcha** (4 digits). Fully local inference, no external API, 4 MB ONNX model.
+[![Hugging Face Model](https://img.shields.io/badge/Hugging%20Face-Model-FFD21E?logo=huggingface&logoColor=000)](https://huggingface.co/FlanChanXwO/phpwind-captcha-ocr)
+[![ONNX](https://img.shields.io/badge/Runtime-ONNX-005CED?logo=onnx&logoColor=fff)](https://onnx.ai/)
+[![PHPWind](https://img.shields.io/badge/Target-PHPWind-3776AB)](https://github.com/alibaba/phpwind)
+[![License: AGPL--3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)
 
-**中文版**: [README_zh.md](README_zh.md)
+An ONNX OCR model trained on four-digit numeric captcha images from one legacy
+PHPWind deployment. It runs entirely on the local machine: no external API or
+GPU is required.
 
-![example captcha](assets/example_captcha.png)
+**PHPWind reference implementation**: [alibaba/phpwind](https://github.com/alibaba/phpwind)
+contains the `PwVerifyCode` and `PwGDCode` classes targeted by this model.
 
-```
-Example input  →  Model output: 9125
-```
+**中文文档**: [README_zh.md](README_zh.md)
+
+![Example PHPWind captcha](assets/example_captcha.png)
+
+> **Answer for the captcha shown above:** `9125`
+
+## Scope and responsible use
+
+This model is intended for PHPWind site operators, developers, and researchers
+working with PHPWind deployments they own or are explicitly authorized to test.
+Use it for local integration tests, accessibility research, or evaluation of
+your own captcha implementation. Do not use it to automate account logins or
+bypass access controls.
+
+Different PHPWind versions and custom themes can generate visually different
+captchas. Validate on representative, authorized samples before deployment.
 
-This captcha is PHPWind's built-in component (`PwVerifyCode` / `PwGDCode`). Colored digits, noise lines and distortion are its standard features.
+## Version support
 
-## Quick Start
+This checkpoint was trained only on four-digit captcha images from a target
+deployment whose footer displayed `v0.7β`. This is an observed deployment
+label, **not** a claim about an official PHPWind release version.
 
-### Python (onnxruntime)
+| Deployment or version label | Status | Evidence | Notes |
+|---|---|---|---|
+| Target deployment — footer label `v0.7β` | Training scope | 997 manually labelled images; 88.61% held-out validation accuracy | The only visual configuration represented in the training and reference evaluation data. |
+| Other PHPWind releases, forks, themes, or captcha generators | Unverified | No version-specific evaluation | Validate with authorized representative samples; fine-tune if the visual distribution differs. |
+
+## Quick start
+
+Install the runtime:
 
 ```bash
 pip install onnxruntime pillow numpy
 ```
 
+Run local inference on a captcha image you are authorized to process:
+
 ```python
 import numpy as np
 import onnxruntime as ort
 from PIL import Image
 
-sess = ort.InferenceSession("model.onnx", providers=["CPUExecutionProvider"])
+session = ort.InferenceSession("model.onnx", providers=["CPUExecutionProvider"])
 
-def solve(path):
-    im = Image.open(path).convert("RGB").resize((160, 64), Image.BILINEAR)
-    x = np.asarray(im, dtype=np.float32).transpose(2, 0, 1)[None] / 255.0
-    logits = sess.run(None, {"input": x})[0]
-    return "".join(str(int(logits[0, p].argmax())) for p in range(4))
+def predict_captcha(path: str) -> str:
+    image = Image.open(path).convert("RGB").resize((160, 64), Image.BILINEAR)
+    inputs = np.asarray(image, dtype=np.float32).transpose(2, 0, 1)[None] / 255.0
+    logits = session.run(None, {"input": inputs})[0]
+    return "".join(str(int(logits[0, position].argmax())) for position in range(4))
 
-print(solve("captcha.png"))   # e.g. "9125"
+print(predict_captcha("captcha.png"))
 ```
 
-### Go (onnxruntime_go)
-
-See [docs/en/INFERENCE.md](docs/en/INFERENCE.md).
-
-## I/O Specification
+## Model interface
 
-| Item | Spec |
+| Item | Value |
 |---|---|
-| Input `input` | `[batch, 3, 64, 160]` float32, RGB, values in `[0, 1]` |
-| Output `logits` | `[batch, 4, 10]`, argmax per position → digit |
-| ONNX opset | 18 |
-| Preprocessing | RGB → resize 160x64 (BILINEAR) → divide by 255 |
+| Input | `input`: `[batch, 3, 64, 160]`, `float32`, RGB values in `[0, 1]` |
+| Output | `logits`: `[batch, 4, 10]`; argmax per position gives one digit |
+| Preprocessing | RGB → resize to `160 × 64` (bilinear) → divide by `255` |
+| Format | ONNX, opset 18 |
+| Runtime | CPU supported; no GPU requirement |
 
 ## Evaluation
 
-Evaluated against **real forum logins** (login success = correct recognition). Details in [docs/en/EVALUATION.md](docs/en/EVALUATION.md).
-
-| Metric | Value |
-|---|---|
-| Validation accuracy | 88.6% |
-| Per-attempt login success | **87.6%** (85/97) |
-| Login success with retries | ≈99.9997% |
-
-## Training & Fine-tuning
-
-997 manually-labeled captchas, CNN trained from scratch with a position-preserving architecture.
+The published checkpoint reached **88.61% validation accuracy** on a held-out
+split of 997 manually labelled images from the target `v0.7β` footer-label
+deployment. This is a model-card reference metric, not a guarantee for another
+PHPWind version, theme, or deployment. See [the evaluation
+protocol](docs/en/EVALUATION.md) for the scope and reproducibility requirements.
 
-- Dataset (997 labeled images): [FlanChanXwO/phpwind-captcha-dataset](https://huggingface.co/datasets/FlanChanXwO/phpwind-captcha-dataset)
-- Script: `scripts/train_fixed.py`
-- Guide: [docs/en/TRAINING.md](docs/en/TRAINING.md)
+## Documentation
 
-## Notes
+- [Inference guide](docs/en/INFERENCE.md) — Python and Go integration details
+- [Training and fine-tuning](docs/en/TRAINING.md) — data preparation and model training
+- [Evaluation](docs/en/EVALUATION.md) — offline validation protocol
+- [Documentation index](docs/en/README.md)
 
-- The captcha is PHPWind's built-in component (not site-custom).
-- Different PHPWind versions may differ; compare samples before using on another site.
+## Training data and license
 
-## License
+The checkpoint was trained from scratch with a position-preserving CNN on 997
+manually labelled images. For adaptation, use only captcha images from PHPWind
+deployments you operate or are authorized to evaluate.
 
-GNU AGPL-3.0 — free to use, modify and distribute (including commercial use), provided modified/derivative works stay AGPL-licensed; network-server use must offer source. See [LICENSE](LICENSE).
+This project is licensed under [GNU AGPL-3.0](LICENSE). Modified or networked
+derivative works must meet the license's corresponding-source requirements.

README_zh.md

@@ -2,6 +2,7 @@
 language:
   - zh
 license: agpl-3.0
+library_name: onnxruntime
 tags:
   - captcha
   - ocr
@@ -10,82 +11,103 @@ tags:
   - phpwind
 pipeline_tag: image-to-text
 model_type: phpwind-captcha-ocr
+metrics:
+  - name: validation accuracy
+    type: accuracy
+    value: 0.8861
 ---
 
 # PHPWind 验证码识别
 
-识别 **PHPWind 论坛内置验证码**（4 位数字）的 OCR 模型。完全本地推理、无外部 API 依赖、ONNX 模型仅 4 MB。
+[![Hugging Face 模型](https://img.shields.io/badge/Hugging%20Face-Model-FFD21E?logo=huggingface&logoColor=000)](https://huggingface.co/FlanChanXwO/phpwind-captcha-ocr)
+[![ONNX](https://img.shields.io/badge/Runtime-ONNX-005CED?logo=onnx&logoColor=fff)](https://onnx.ai/)
+[![PHPWind](https://img.shields.io/badge/Target-PHPWind-3776AB)](https://github.com/alibaba/phpwind)
+[![许可证：AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)
+
+针对一个旧版 PHPWind 部署的四位数字验证码图片训练的 ONNX OCR 模型。模型完全在本地运行，
+不依赖外部 API，也不需要 GPU。
+
+**PHPWind 参考实现源码**：[alibaba/phpwind](https://github.com/alibaba/phpwind)，其中包含本模型
+对应的 `PwVerifyCode` 与 `PwGDCode` 类。
 
 **English version**: [README.md](README.md)
 
-![验证码样例](assets/example_captcha.png)
+![PHPWind 验证码样例](assets/example_captcha.png)
 
-```
-示例输入  →  模型输出: 9125
-```
+> **上图验证码的正确答案：** `9125`
+
+## 适用范围与负责任使用
+
+本模型面向 PHPWind 站点的运营者、开发者及研究者，用于其自有或已获明确授权的
+PHPWind 部署。适合本地集成测试、无障碍研究，或评估自身验证码实现；不得用于
+自动化账户登录或绕过访问控制。
+
+不同 PHPWind 版本及自定义主题可能生成外观不同的验证码。部署前请以有授权的代表性
+样本验证实际效果。
+
+## 版本支持
 
-这是 PHPWind 论坛软件的内置验证码组件（`PwVerifyCode` / `PwGDCode`），彩色数字、干扰线、扭曲都是它的标准特征。
+此 checkpoint 仅使用目标部署页脚显示为 `v0.7β` 的四位数字验证码图片训练。该页脚内容
+只是观测到的部署标识，**不能**视为 PHPWind 官方发布版本号。
 
-## 快速使用
+| 部署或版本标识 | 状态 | 依据 | 说明 |
+|---|---|---|---|
+| 目标部署——页脚标识 `v0.7β` | 已训练范围 | 997 张人工标注图片；留出验证集准确率 88.61% | 训练数据和参考评估数据中唯一包含的验证码视觉配置。 |
+| 其他 PHPWind 发行版、分支、主题或验证码生成器 | 未验证 | 无按版本划分的评估 | 请先使用有授权的代表性样本验证；视觉分布不同时需进行微调。 |
 
-### Python (onnxruntime)
+## 快速开始
+
+安装运行时：
 
 ```bash
 pip install onnxruntime pillow numpy
 ```
 
+对已获授权处理的验证码图片执行本地推理：
+
 ```python
 import numpy as np
 import onnxruntime as ort
 from PIL import Image
 
-sess = ort.InferenceSession("model.onnx", providers=["CPUExecutionProvider"])
+session = ort.InferenceSession("model.onnx", providers=["CPUExecutionProvider"])
 
-def solve(path):
-    im = Image.open(path).convert("RGB").resize((160, 64), Image.BILINEAR)
-    x = np.asarray(im, dtype=np.float32).transpose(2, 0, 1)[None] / 255.0
-    logits = sess.run(None, {"input": x})[0]
-    return "".join(str(int(logits[0, p].argmax())) for p in range(4))
+def predict_captcha(path: str) -> str:
+    image = Image.open(path).convert("RGB").resize((160, 64), Image.BILINEAR)
+    inputs = np.asarray(image, dtype=np.float32).transpose(2, 0, 1)[None] / 255.0
+    logits = session.run(None, {"input": inputs})[0]
+    return "".join(str(int(logits[0, position].argmax())) for position in range(4))
 
-print(solve("captcha.png"))   # 例如 "9125"
+print(predict_captcha("captcha.png"))
 ```
 
-### Go (onnxruntime_go)
-
-见 [docs/zh/INFERENCE.md](docs/zh/INFERENCE.md)。
-
-## 输入 / 输出规格
-
-| 项 | 规格 |
-|---|---|
-| 输入 `input` | `[batch, 3, 64, 160]` float32，RGB，取值 `[0, 1]` |
-| 输出 `logits` | `[batch, 4, 10]`，每位置 argmax → 数字 |
-| ONNX opset | 18 |
-| 预处理 | RGB → 缩放到 160x64（双线性）→ 除以 255 |
-
-## 评估结果
-
-用**真实论坛登录**作为 ground truth（登录成功 = 识别正确）。详见 [docs/zh/EVALUATION.md](docs/zh/EVALUATION.md)。
+## 模型接口
 
-| 指标 | 数值 |
+| 项目 | 规格 |
 |---|---|
-| 验证集精度 | 88.6% |
-| 真实登录单次命中 | **87.6%** (85/97) |
-| 带重试登录成功率 | ≈99.9997% |
+| 输入 | `input`：`[batch, 3, 64, 160]`，`float32`，RGB 值域 `[0, 1]` |
+| 输出 | `logits`：`[batch, 4, 10]`；逐位置 argmax 得到一位数字 |
+| 预处理 | RGB → 缩放至 `160 × 64`（双线性）→ 除以 `255` |
+| 格式 | ONNX，opset 18 |
+| 运行环境 | 支持 CPU，无 GPU 依赖 |
 
-## 训练 / 微调
+## 评估
 
-997 张人工标注验证码，CNN 从零���练（位置保留架构）。
+已发布 checkpoint 在来自目标页脚标识 `v0.7β` 部署的 997 张人工标注图片留出集上达到
+**88.61% 验证集准确率**。该值仅是模型卡参考指标，不保证其他 PHPWind 版本、主题或
+部署环境中的表现。评估范围与复现要求见[评估说明](docs/zh/EVALUATION.md)。
 
-- 数据集（997 张已标注图片）：[FlanChanXwO/phpwind-captcha-dataset](https://huggingface.co/datasets/FlanChanXwO/phpwind-captcha-dataset)
-- 脚本：`scripts/train_fixed.py`
-- 指南：[docs/zh/TRAINING.md](docs/zh/TRAINING.md)
+## 文档
 
-## 说明
+- [推理指南](docs/zh/INFERENCE.md) —— Python 与 Go 集成细节
+- [训练与微调](docs/zh/TRAINING.md) —— 数据准备及模型训练
+- [评估说明](docs/zh/EVALUATION.md) —— 离线验证方法
+- [文档索引](docs/zh/README.md)
 
-- 验证码为 PHPWind 内置组件（非站点定制）。
-- 不同 PHPWind 版本参数可能有差异，换站使用前建议对比样例确认风格。
+## 训练数据与许可证
 
-## 许可证
+该 checkpoint 使用位置保留 CNN 从零训练，训练数据为 997 张人工标注图片。需要适配时，
+请只使用自有或已获授权的 PHPWind 部署所产生的验证码图片。
 
-GNU AGPL-3.0 —— 可自由使用、修改、分发（含商用），但修改版/衍生作品必须同样以 AGPL 开源；网络服务使用也需提供源码。详见 [LICENSE](LICENSE)。
+本项目采用 [GNU AGPL-3.0](LICENSE) 许可。修改版或通过网络提供服务的衍生作品须满足
+许可证的对应源码提供义务。

docs/en/EVALUATION.md

@@ -10,6 +10,17 @@ Evaluate only images from PHPWind deployments you own or are explicitly
 authorized to test. Keep the evaluation dataset separate from the training
 dataset, and do not publish captcha images or labels that contain private data.
 
+## Version boundary
+
+The published checkpoint was trained on four-digit numeric captcha images from
+one target deployment whose footer displayed `v0.7β`. This footer text is an
+observed deployment label, not an official PHPWind release version claim.
+
+| Deployment or version label | Status | Evidence | Notes |
+|---|---|---|---|
+| Target deployment — footer label `v0.7β` | Training and reference-evaluation scope | 997 manually labelled images; 88.61% held-out validation accuracy | The only visual configuration represented in the reported data. |
+| Other PHPWind releases, forks, themes, or captcha generators | Unverified | No version-specific evaluation | Evaluate with authorized representative samples and fine-tune when the image distribution differs. |
+
 ## Reference metric
 
 The published checkpoint reports the following held-out validation result:
@@ -19,11 +30,11 @@ The published checkpoint reports the following held-out validation result:
 | Validation accuracy | 88.61% |
 | Labelled image count | 997 |
 | Validation split | 8% |
-| Task | Four-digit numeric PHPWind captcha recognition |
+| Task | Four-digit numeric captcha recognition for the target `v0.7β` footer-label deployment |
 
 This metric is a historical reference for this checkpoint. It is not a
-production guarantee: PHPWind versions, themes, fonts, and generator settings
-can change the image distribution.
+production guarantee: other PHPWind versions, themes, fonts, and generator
+settings can change the image distribution.
 
 ## Reproducible protocol
 

docs/zh/EVALUATION.md

@@ -8,6 +8,16 @@
 仅评估来自自有或已获明确授权测试的 PHPWind 部署的图片。评估数据必须与训练数据分离，
 也不要公开可能包含私有信息的验证码图片或标签。
 
+## 版本边界
+
+已发布 checkpoint 使用一个目标部署的四位数字验证码图片训练；该部署页脚显示为 `v0.7β`。
+此页脚文字只是观测到的部署标识，不是对 PHPWind 官方发布版本的判断。
+
+| 部署或版本标识 | 状态 | 依据 | 说明 |
+|---|---|---|---|
+| 目标部署——页脚标识 `v0.7β` | 训练和参考评估范围 | 997 张人工标注图片；留出验证集准确率 88.61% | 已报告数据中唯一包含的验证码视觉配置。 |
+| 其他 PHPWind 发行版、分支、主题或验证码生成器 | 未验证 | 无按版本划分的评估 | 请用有授权的代表性样本评估；图片分布不同时进行微调。 |
+
 ## 参考指标
 
 已发布 checkpoint 的留出验证结果如下：
@@ -17,9 +27,9 @@
 | 验证集准确率 | 88.61% |
 | 已标注图片数量 | 997 |
 | 验证集比例 | 8% |
-| 任务 | PHPWind 四位数字验证码识别 |
+| 任务 | 目标页脚标识 `v0.7β` 部署的四位数字验证码识别 |
 
-该指标仅是当前 checkpoint 的历史参考值，并非生产环境保证。PHPWind 版本、主题、字体及
+该指标仅是当前 checkpoint 的历史参考值，并非生产环境保证。其他 PHPWind 版本、主题、字体及
 验证码生成设置都可能改变图片分布。
 
 ## 可复现流程