# PsyLens 可靠性评测方法

PsyLens 的评测对象包括公开数据、编码结果、分析结论和运行产物。评测不使用单一总分，而是分别记录结构错误、解释风险与复现问题，便于定位返修环节。

## 1. 评测对象

| 层级 | 主要对象 | 核心问题 |
| --- | --- | --- |
| 样本层 | `samples_public.csv` | 样本是否唯一、字段是否完整、公开文本是否经过最小化处理 |
| 证据层 | `evidence_public.csv` | 证据是否存在父样本、文本是否可定位、标签是否合法 |
| 分析层 | 页面与项目说明中的统计 | 数字是否从公开数据计算、是否写明分母与解释范围 |
| 运行层 | Demo、文件校验记录、CI | 相同输入是否得到一致输出、文件是否可解析、哈希是否匹配 |

## 2. 五组评测维度

### A. 结构完整性

硬性检查：

- `sample_id` 唯一；
- `evidence_id` 唯一；
- 每条证据的 `sample_id` 在样本表中存在；
- 证据与父样本的平台字段一致；
- `unit_text` 能在对应 `public_text` 中定位；
- 表层话题与机制标签属于编码手册；
- 必填字段非空。

当前公开结果：样本编号 360 / 360 唯一，证据编号 927 / 927 唯一，孤立证据 0，平台错配 0，文本回溯率 100%。

### B. 清洗与隐私

检查内容：

- 公开字段是否符合白名单；
- 是否包含来源 URL、账号、UID 或联系方式；
- 规范化文本是否存在重复组；
- 文件校验记录的行数、字段与文件 SHA-256 是否对应；
- 样本日期等可选字段的缺失量是否被记录。

当前公开结果：URL 扫描命中 0，样本重复组 0，证据重复组 0；240 条样本日期为空。

### C. 编码可用性

编码质量不能只用“有标签”衡量，还需要检查：

- `other_uncertain` 与 `uncertain` 的比例；
- 不同编码来源的分布差异；
- 相邻标签是否有明确的纳入、排除与裁决规则；
- 证据是否因为缺少上下文而被过度解释；
- 规则提案是否出现标签塌缩或关键词误触发。

当前机制标签 `uncertain` 为 486 / 927，约 52.4%。该比例表明编码覆盖并非当前主要问题，机制判定的区分度和上下文充分性更需要改进。

### D. 分析支撑

页面与文档中的每条数量结论需要具备：

- 明确的数据文件；
- 分子与分母；
- 统计口径；
- 平台与样本范围；
- 对抽样、切分和编码来源的解释边界。

例如，“平衡与数值占 61.2%”使用的是 270 / 441，分母为排除 `other_uncertain` 后能够分配具体话题的证据，不能写成全部玩家反馈的 61.2%。

产品方向需要继续附带验证方法，例如访谈、问卷、行为日志、A/B 测试、上线前后反馈变化或任务完成率。

### E. 运行复现

运行评测包括：

- Python 文件可编译；
- Ruff 静态检查通过；
- 数据、页面和 DOCX 测试通过；
- Demo 同输入输出一致；
- 文件校验记录保存产物哈希；
- Ubuntu 与 Windows 均完成 CI；
- Pages 部署前重新执行公开发布校验。

## 3. 阻断与诊断

### 阻断问题

出现以下情况时，公开数据或页面不能发布：

- ID 重复；
- 孤立证据；
- 证据文本无法回到父样本；
- 非法标签；
- 公开文件包含来源 URL 或身份定位字段；
- 页面关键数字与公开数据不一致；
- 文件校验记录与文件哈希不一致；
- Demo 或页面测试失败。

### 诊断问题

以下问题需要记录并解释，不必自动阻断：

- 日期等可选字段的覆盖情况；
- 样本未切出证据；
- 不确定标签比例偏高；
- 平台证据密度差异较大；
- 不同编码来源的分布不一致；
- 某个结论只由单一平台支撑。

## 4. 当前评测结果

| 指标 | 当前值 | 判定 |
| --- | ---: | --- |
| 样本 ID 唯一率 | 100% | 通过 |
| 证据 ID 唯一率 | 100% | 通过 |
| 父样本关联率 | 100% | 通过 |
| 证据文本回溯率 | 100% | 通过 |
| 平台字段错配 | 0 | 通过 |
| 公开 URL 命中 | 0 | 通过 |
| 样本重复组 | 0 | 通过 |
| 证据重复组 | 0 | 通过 |
| 未切出证据的样本 | 2 | 记录 |
| 机制不确定率 | 52.4% | 重点诊断 |
| 缺失日期样本 | 240 | 限制时间分析 |

## 5. 编码一致性与错误分析（扩展方法）

编码一致性评测从当前数据中分层抽取样本，至少覆盖平台、主要话题、主要机制和不确定类别，由两名编码者独立完成证据纳入、表层话题和机制标签判断。

建议记录：

- 原始证据；
- 两名编码者的独立标签；
- 是否一致；
- 争议类型；
- 裁决结果与理由；
- 是否修改编码手册。

名义变量可以使用 Krippendorff’s alpha 等指标评估一致性。数值本身需要与争议样本、混淆矩阵和返修成本一起解释，避免把一致性指标当作唯一质量结论。

## 6. 复现入口

```bash
python tools/normalize_public_dataset.py \
  --source-dir data/public \
  --output-dir artifacts/normalized_public

python tools/summarize_public_analysis.py \
  --public-dir data/public \
  --output artifacts/public_analysis_summary.json

python tools/run_demo.py --provider mock --output artifacts/demo/run

python -m pytest demo/tests tests -q
```

指标语义见 `evaluation/metrics.yaml`，发布门槛见 `evaluation/thresholds.yaml`，失败类型见 `evaluation/failure_taxonomy.yaml`。