feat: add agent calibration and content quality workflow

Add blinded calibration sampling, independent reviewer prompts, OpenAI-compatible review execution, consensus and disagreement analysis, resume identity validation, public copy linting, and cross-platform CI coverage.

Author: sherlock0717

.github/workflows/ci.yml

@@ -10,6 +10,8 @@ jobs:
   test:
     name: Public release checks (${{ matrix.os }})
     runs-on: ${{ matrix.os }}
+    env:
+      PYTHONUTF8: "1"
     strategy:
       fail-fast: false
       matrix:
@@ -59,9 +61,43 @@ jobs:
       - name: Ruff - Tests
         run: ruff check tests
 
+      - name: Ruff - Full tree
+        run: ruff check demo/src demo/tests pipeline tools tests
+
+      - name: Public copy P1 gate
+        run: >-
+          python tools/lint_public_copy.py --root . --quality-gate P1
+          --format json --output "${{ runner.temp }}/public_copy_report.json"
+
       - name: Test suite
         run: python -m pytest demo/tests tests -q
 
+      - name: Calibration pipeline smoke (mock, temp dir)
+        shell: bash
+        run: |
+          python tools/calibration/build_calibration_sample.py --config config/calibration/calibration.yaml
+          python tools/calibration/run_agent_reviews.py --provider mock \
+            --input data/calibration/calibration_sample.csv --max-items 30 \
+            --output "$RUNNER_TEMP/cal_reviews"
+          python tools/calibration/build_agent_consensus.py \
+            --input-dir "$RUNNER_TEMP/cal_reviews" --output-dir "$RUNNER_TEMP/cal_consensus"
+          python tools/calibration/analyze_disagreements.py \
+            --input "$RUNNER_TEMP/cal_consensus/consensus_reference.csv" \
+            --output "$RUNNER_TEMP/cal_consensus/disagreement_report.md" \
+            --codebook-output "$RUNNER_TEMP/cal_consensus/codebook_revision_proposals.md"
+
+      - name: Verify calibration outputs and public safety
+        shell: bash
+        env:
+          RUN_REPORT: ${{ runner.temp }}/cal_reviews/run_report.json
+          CONS_REPORT: ${{ runner.temp }}/cal_consensus/calibration_report.json
+        run: |
+          python tools/calibration/verify_mock_outputs.py \
+            --run-report "$RUN_REPORT" \
+            --consensus-report "$CONS_REPORT" \
+            --public-sample data/calibration/calibration_sample.csv
+          git diff --quiet -- data/public docs/files
+
       - name: Normalize public data smoke
         run: python tools/normalize_public_dataset.py --source-dir data/public --output-dir artifacts/normalized_public
 

.github/workflows/pages.yml

@@ -33,6 +33,7 @@ jobs:
         run: |
           python -m compileall demo/src pipeline tools tests demo/tests
           ruff check demo/src demo/tests pipeline tools tests
+          python tools/lint_public_copy.py --root . --quality-gate P1 --format json
           python -m pytest demo/tests tests -q
           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

.gitignore

@@ -11,10 +11,16 @@ __pycache__/
 
 # 环境与凭据（严禁提交）
 .env
+.env*
 *.env
 *cookie*.txt
 *cookies*.txt
 *.key
+local_secrets/
+
+# 自动校准私有映射与原始模型响应（严禁提交）
+artifacts/calibration/private_*
+artifacts/calibration/raw_model_responses/
 
 # 编辑器 / 系统
 .DS_Store

README.md

@@ -1,114 +1,68 @@
 # PsyLens
 
-PsyLens 是一套社区反馈分析与可靠性评测工作流。当前案例围绕《英雄联盟》海克斯大乱斗社区讨论展开，将多平台公开反馈整理为样本与证据单元，再从具体话题、体验机制和数据可靠性三个层面分析。
+PsyLens 把分散的玩家反馈整理成可核查的产品线索，并对整条分析链路做可靠性评测。当前案例围绕《英雄联盟》海克斯大乱斗的社区讨论。
 
 - **在线页面**：https://sherlock0717.github.io/PsyLens/
 - **完整项目说明**：[`docs/files/PsyLens_project_brief.docx`](docs/files/PsyLens_project_brief.docx)
 - **公开数据**：[`data/public/`](data/public/)
 - **离线 Demo**：[`demo/`](demo/)
 
-## 当前案例
+## 当前案例与主要结果
 
-| 项目 | 结果 |
-| --- | --- |
-| 数据来源 | NGA、贴吧、B 站公开讨论 |
-| 样本设计 | 三个平台各 120 条，共 360 条 |
-| 证据单元 | 927 条，平均每条样本 2.575 条 |
-| 文本回溯 | 927 条证据均能在对应公开样本中定位 |
-| 结构问题 | 孤立证据 0，平台错配 0，重复文本组 0 |
-| 日期覆盖 | 120 条有日期，240 条日期为空 |
+案例整合 NGA、贴吧、B 站三个平台的公开讨论。每个平台等额保留 120 条样本，共 360 条。样本再切分为 927 条证据单元，平均每条样本约 2.58 条证据，全部能在对应公开样本中逐字定位。
 
-## 主要分析结果
+**证据单元**：从一条完整反馈中切出的、可以单独判断问题类型的短片段。
 
-### 具体话题
+主要分布以 441 条可明确分类的证据为分母：
 
-排除 `other_uncertain` 后，共有 441 条证据能够分配具体话题：
+- 具体话题最集中在平衡与数值：270 条，占 61.2%；其次是匹配与对局分配：82 条，占 18.6%。
+- 体验机制最集中在胜任受挫：308 条，占 69.8%；其次是公平受损：88 条，占 20.0%。
+- 数量较高的交叉组合是平衡与数值 × 胜任受挫，共 138 条。
 
-- 平衡与数值：270 条，占 61.2%；
-- 匹配与对局分配：82 条，占 18.6%；
-- 活动与玩法设计：24 条，占 5.4%；
-- 成长与养成：20 条，占 4.5%；
-- 社区冲突与氛围：18 条，占 4.1%。
+**体验机制**：玩家在表达中呈现的主要体验方向，例如觉得难以发挥、觉得规则不公平，或觉得官方说明不清楚。
 
-### 体验机制
-
-排除 `uncertain` 后，共有 441 条证据能够分配主要体验机制：
-
-- 胜任受挫：308 条，占 69.8%；
-- 公平受损：88 条，占 20.0%；
-- 信任与沟通落差：24 条，占 5.4%；
-- 归属感下降：11 条，占 2.5%；
-- 规范与安全风险：10 条，占 2.3%。
-
-### 话题与机制交叉
-
-数量较高的具体组合包括：
+完整分布由 [`tools/summarize_public_analysis.py`](tools/summarize_public_analysis.py) 从公开数据计算，页面读取 [`docs/assets/data/analysis_summary.json`](docs/assets/data/analysis_summary.json) 展示。
 
-- 平衡与数值 × 胜任受挫：138 条；
-- 平衡与数值 × 公平受损：35 条；
-- 匹配与对局分配 × 胜任受挫：22 条；
-- 匹配与对局分配 × 公平受损：16 条；
-- 沟通与透明度 × 信任与沟通落差：13 条。
+## 分析方法
 
-完整分布由 [`tools/summarize_public_analysis.py`](tools/summarize_public_analysis.py) 从公开数据计算，页面读取 [`docs/assets/data/analysis_summary.json`](docs/assets/data/analysis_summary.json) 展示。
+项目采用双层编码。表层话题记录反馈在谈什么，体验机制记录文本呈现的心理体验方向。两层分开记录，使产品问题、心理机制和证据来源可以分别核对。
 
-## 心理学分析框架
+编码顺序是先判断证据是否能独立成立，再分别标注话题与机制。当文本过短、依赖上下文或同时指向多个方向时，标签保留为 uncertain，避免牵强归类。
 
-项目采用双层编码：
+## 心理学思路
 
-1. **表层话题**记录反馈正在讨论的问题；
-2. **体验机制**记录文本呈现的心理体验方向。
+机制层参考胜任需要、公平判断、组织信任、社群归属与规范安全五个方向的研究，并把这些方向转化为可观察的文本判据。体验类型、操作性定义和参考文献见 [`docs/methodology/PSYCHOLOGY_FRAMEWORK.md`](docs/methodology/PSYCHOLOGY_FRAMEWORK.md)。
 
-机制层参考胜任需要、公平判断、组织信任、社群归属与规范安全研究，并通过固定纳入、排除和相邻标签区分规则转化为文本编码。详细构念、操作性定义和参考文献见 [`docs/methodology/PSYCHOLOGY_FRAMEWORK.md`](docs/methodology/PSYCHOLOGY_FRAMEWORK.md)。
+交叉组合用于提出可验证的产品问题，再由问卷、访谈、行为日志或实验继续检验。
 
-## 数据处理流程
+## 数据处理
 
-```text
-候选讨论登记
-→ 页面与回复采集
-→ 原始缓存
-→ 规则预清洗
-→ 内容筛选与字段规整
-→ 平台等额抽样
-→ 公开脱敏
-→ 证据单元切分
-→ 话题与机制编码
-→ 完整性与分布审计
-```
+处理流程从候选讨论登记开始，依次经过采集、规则预清洗、内容筛选、平台等额抽样、公开脱敏、证据切分与双层编码，最后做完整性与分布审计。
 
-关键操作包括：删除回复头、引用残留、图片路径和多余空白；移除空文本与低信息噪声；删除来源链接和账号定位字段；按标点切分证据；检查证据文本是否能在父样本中逐字定位；扫描重复、空值、URL 和非法标签。
+关键操作包括删除回复头与引用残留、移除低信息文本、删除来源链接和账号定位字段、按标点切分证据，并检查每条证据能否在父样本中逐字定位。字段、清洗规则和复现命令见 [`docs/methodology/DATA_CLEANING_AND_CODING.md`](docs/methodology/DATA_CLEANING_AND_CODING.md)。
 
-详细字段、清洗规则和复现命令见 [`docs/methodology/DATA_CLEANING_AND_CODING.md`](docs/methodology/DATA_CLEANING_AND_CODING.md)。
+日期字段覆盖 120 / 360 条样本。当前版本聚焦当前样本的整体分布，时间维度在日期覆盖扩展后启用。
 
 ## 可靠性评测
 
-评测分为五组：
-
-- **结构完整性**：ID、父样本、平台和文本定位；
-- **清洗与隐私**：字段白名单、URL、重复、空值和文件哈希；
-- **编码可用性**：合法标签、不确定比例、标签边界和编码来源；
-- **分析支撑**：结论是否带有证据、样本量、分母和平台范围；
-- **运行复现**：同输入输出一致、manifest 完整、跨平台 CI。
+评测把"结果看起来合理"拆成可检查的条件，分为五组：结构完整性、清洗与隐私、编码可用性、分析支撑、运行复现。当前结构完整性全部通过，公开数据 URL 命中为 0，重复文本组为 0。完整方法见 [`docs/evaluation/EVALUATION_METHOD.md`](docs/evaluation/EVALUATION_METHOD.md)。
 
-当前最明显的质量风险是机制不确定率较高：486 / 927，约 52.4%。这项结果提示短文本、上下文依赖和标签边界仍需要更细的编码设计。完整评测方法见 [`docs/evaluation/EVALUATION_METHOD.md`](docs/evaluation/EVALUATION_METHOD.md)。
+编码可用性的校准重点是暂时保留为不确定的证据：486 条证据的体验机制标注为 uncertain，主要涉及短文本、上下文依赖和多种解释并存。这批样本是下一步标签边界校准的重点材料。
 
-## 两种不确定性
+## 自动校准计划
 
-公开数据包含两个含义不同的字段：
+v1.1 通过三个互不查看彼此结果的代理，对分层样本做独立复检，输出一致结果、争议标签和重复运行稳定性。
 
-- `mechanism_label=uncertain`：486 条，表示无法明确判断体验机制；
-- `analysis_inclusion_status=included_flagged_uncertain`：163 条，表示证据仍被保留，但纳入时存在上下文或解释风险。
+**自动校准参考集**：由多个互不查看彼此结果的代理独立判断后形成的参考标签，用于发现稳定结果和争议案例。它定位为自动校准参考，人工金标准另行建立。流程见 [`docs/evaluation/AGENT_CALIBRATION_WORKFLOW.md`](docs/evaluation/AGENT_CALIBRATION_WORKFLOW.md)。
 
-两者分别统计，不能合并为同一“不确定率”。
+## 运行与复现
 
-## 离线 Demo
+离线 Demo 默认使用本地固定示例模式，不联网，也不调用外部模型：
 
 ```bash
 python tools/run_demo.py
 ```
 
-Demo 默认使用确定性 mock provider，不联网，也不调用外部模型。输出写入 `artifacts/`，包括 JSON、Markdown、HTML 和 manifest。
-
 生成公开分析汇总：
 
 ```bash
@@ -117,31 +71,17 @@ python tools/summarize_public_analysis.py \
   --output artifacts/public_analysis_summary.json
 ```
 
-规范化公开数据到独立目录：
+检查公开文案表达：
 
 ```bash
-python tools/normalize_public_dataset.py \
-  --source-dir data/public \
-  --output-dir artifacts/normalized_public
+python tools/lint_public_copy.py --root . --format markdown
 ```
 
-## 仓库结构
-
-```text
-data/public/                           公开脱敏样本、证据与字段说明
-demo/                                  离线分析示例
-docs/index.html                        GitHub Pages 展示页
-docs/methodology/                      心理框架、编码与清洗方法
-docs/evaluation/                       评测方法
-evaluation/                            指标与失败类型配置
-pipeline/                              采集、配置和 Prompt 模板
-tools/                                 公开数据规范化、统计与 Demo 入口
-tests/                                 数据、页面与文档校验
-```
+## 结果使用说明
 
-## 解释边界
+三个平台采用等额抽样，编码来源包含历史 AI 结果与离线规则提案。证据数量也会受文本长度和切分粒度影响。当前分布用于方法审计、探索性分析和研究设计。它为访谈、问卷、行为分析和实验提供问题线索。总体占比与因果结论由这些后续研究继续检验。
 
-三个平台采用等额抽样，编码来源包含历史 AI 结果与离线规则提案，且证据数量会受到文本长度和切分粒度影响。因此当前分布用于方法审计、探索性分析和后续研究设计，不直接代表总体玩家意见占比，也不构成产品效果或心理状态的因果结论。
+公开数据还包含两个含义不同的字段，各统计一次即可：`mechanism_label=uncertain` 有 486 条，表示机制暂时无法明确归类；`analysis_inclusion_status=included_flagged_uncertain` 有 163 条，表示证据仍被保留但纳入时需要提醒。
 
 ## 权利与使用
 

config/calibration/calibration.yaml

@@ -0,0 +1,37 @@
+# PsyLens 自动校准抽样配置（config/calibration/calibration.yaml）
+# 供 tools/calibration/build_calibration_sample.py 读取。
+# 校准结果为“自动校准参考”，不是人工金标准，也不覆盖公开数据的现有标签。
+
+sample_size: 300
+retest_size: 30
+reviewer_count: 3
+random_seed: 20260720
+
+# 分层维度：从公开证据的下列字段构造分层，保证覆盖。
+stratify_by:
+  - platform_source
+  - surface_topic
+  - mechanism_label
+  - label_source
+  - analysis_inclusion_status
+
+# 文本长度分桶（依据公开证据文本字符数）。
+length_buckets:
+  - short
+  - medium
+  - long
+
+# 长度阈值（字符数）：short <= short_max；medium <= medium_max；其余为 long。
+length_short_max: 15
+length_medium_max: 40
+
+# 每个分层值至少保证的样本数（保证稀有标签也被覆盖）。
+min_per_stratum_value: 2
+
+# 输入公开数据（只读，不覆盖）。
+input_evidence: data/public/evidence_public.csv
+input_samples: data/public/samples_public.csv
+
+# 输出目录：公开校准样本写入 data/calibration，私有映射与运行产物写入 artifacts/calibration。
+public_output: data/calibration/calibration_sample.csv
+artifact_dir: artifacts/calibration

config/calibration/prompts/reviewer_a.md

@@ -0,0 +1,58 @@
+# Reviewer A · 严格编码手册优先
+
+prompt_version: a-1.0
+
+你是一名独立的证据复检代理。你依据一条脱敏证据文本和可选的父样本上下文独立判断。
+你不会获得平台字段、来源编号、当前标签、编码来源或重测关系，也看不到其他代理的判断。公开脱敏文本按原貌保留。
+
+## 任务
+
+严格依据编码手册对证据分类。当证据不足以明确归入某一体验机制时，保留 uncertain，
+不要为了提高覆盖率而牵强归类。
+
+## 体验机制标签（固定六项）
+
+- competence_frustration：玩家觉得难以发挥、投入难以见效。
+- fairness_threat：玩家觉得规则、匹配或分配本身不合理。
+- trust_communication_gap：玩家觉得官方说明、回应或承诺执行不足。
+- belonging_drop：玩家表达疏离、退出或与社区的距离感。
+- norm_safety_risk：涉及外挂、辱骂、骚扰、误封等秩序与安全问题。
+- uncertain：文本过短、依赖上下文或同时指向多个机制。
+
+## 边界判断
+
+先判断 boundary_status：complete、needs_parent_context、over_segmented、under_segmented、not_evidence。
+若边界不完整，倾向保留 uncertain 并说明 abstain_reason。
+
+## 模型输出契约
+
+只输出一个 JSON 对象，字段见下。不要输出 run_id、model_name、prompt_version、prompt_sha256、created_at、evidence_text，这些由程序补充。不要输出多余文字或注释。
+
+字段与允许值：
+
+- surface_topic：balance、matchmaking、event_design、progression、community_conflict、communication_transparency、rewards、new_player_onboarding、other_uncertain。
+- mechanism_label：competence_frustration、fairness_threat、trust_communication_gap、belonging_drop、norm_safety_risk、uncertain。
+- boundary_status：complete、needs_parent_context、over_segmented、under_segmented、not_evidence。
+- confidence_band：high、medium、low。
+- abstain_reason：none、insufficient_context、multiple_mechanisms、unclear_topic、unclear_boundary、other。
+- evidence_phrase：从证据文本中原样摘取的短语，必须是原文子串；无法摘取时留空。
+- decision_basis：用普通中文说明依据。
+
+约束：
+
+- mechanism_label 为 uncertain 时，abstain_reason 不能为 none。
+- evidence_phrase 非空时必须是证据文本的子串。
+
+JSON 示例（模型实际需要填写的内容）：
+
+```json
+{
+  "surface_topic": "matchmaking",
+  "mechanism_label": "fairness_threat",
+  "boundary_status": "complete",
+  "confidence_band": "high",
+  "abstain_reason": "none",
+  "evidence_phrase": "连胜连败",
+  "decision_basis": "文本强调匹配结果不公平，偏向公平受损。"
+}
+```