心理普查报告质控（psy-report-qa）
对心理普查报告的「生成引导 · 防幻觉审计 · 数据校订」三步全流程质控。本技能不依赖具体量表字面量——量表、列映射、表号、阈值、方法名全部下沉到 config 下的量表配置，脚本零硬编码，切换量表只需改 --scale。
触发条件
- 用户要求生成心理普查报告（需要章节 / 指标 / 提示词引导框架）。
- 用户要求审计 / 核查一份已有心理普查报告（防幻觉、数值一致性、方法学合规）。
- 用户要求校订 / 修正报告中的数值错误，生成数据校订版。
适用量表示例：MHT（心理健康诊断测验）、SCL-90（症状自评量表）、PHQ-9（抑郁筛查）、EPQ（艾森克人格问卷，人格量表、非病理化）。新增量表只需在 config 增加一份量表配置，无需改脚本；配置外的新问卷请按 references/add-new-scale.md（新增量表指引）接入，不要硬套现有量表配置。
输入与依赖
必需输入（由 scripts/cli.py 首步声明，缺失即报错退出，见 AC8）：
- --scale：量表配置名（如 mht / scl90 / phq9 / epq）。
- --data：脱敏数据 xlsx（不含姓名、班级明文；按 config 中 sheet_structure.year_labels 标注学年块）。
- --report：待审报告 docx（审计 / 校订时必需；仅生成引导时可选）。
依赖策略：统计与解析脚本经隔离 Python 执行，解释器按「PSYQA_PYTHON 环境变量 → 随包 venv（若存在且通过依赖健康检查）→ 当前解释器（依赖齐备时回退）→ 明确报错并给出确切修法」解析。随包 venv 形态已预装 numpy、scipy、statsmodels、pandas、python-docx、pyyaml、lxml，开箱即用；若所用分发形态不含 venv（例如市场轻量版），执行一次 pip install -r requirements.txt，或用 PSYQA_PYTHON 指向已装好依赖的 Python 即可。venv 缺失或 scipy 不可用时会显式报错并给出确切修法，不静默失败（AC11）。PyYAML 为可选增强，缺失时配置走内置精简解析器。
工作流程
统一入口：scripts/cli.py --scale <scale> --data <xlsx> --report <docx> --out <dir> --steps <gen,extract,recompute,judge,amend> --auto
- 生成引导（gen）：读 config 的 stat_methods.guide_section 与 generation_slots，聚合出章节框架大纲 guide_outline.json。未补齐的生成槽位显式标记为 empty，不预置任何具体报告文案或提示词（AC10）。mht / scl90 / phq9 / epq 四套配置均已补齐 section_prefs / stat_method_list / prompt_templates / sample_outline（含「量表间相关」关联性分析章节与四阶段防幻觉提示词），均输出 user-supplemented 大纲；新增量表若暂未补齐槽位则自动回落到 empty 框架，不编造。
- 数值提取与溯源（extract）：scripts/extract_nums.py 从报告 docx 提取段落 + 表格全部数值，逐条标注章节 / 位置 / 变量 / 分组 / 计算方式 / 溯源状态（可对应 / 方法学常数 / 文献引用 / 无法确定 / 非统计）。
- 代码重算（recompute）：scripts/recompute.py 按配置建精确重算池 audit_recompute_pool.json，覆盖描述统计、独立样本 t（合并 / Welch 双口径）、单因素 ANOVA（Type II/III）、Tukey HSD / Games-Howell、Pearson/Spearman 相关、偏相关、Fisher z、Bonferroni/FDR 校正、Cohen's d、阈值检出率、计数比例（count_rate）。
- 红黄绿判定（judge）：scripts/judge.py 把提取数值与重算池精确比对，容忍阈值、统计量族（符号翻转族）、方法名校验全部来自配置。红项 100% 带裁决证据字段（AC3），输出第四步审计表 html（判定 / 章节 / 位置三筛选 + 搜索 + 重点清单）、csv、json。
- 数据校订（amend）：scripts/amend_docx.py 采用 zip 手术，仅重写 document.xml（位于 word/ 下），其余 part 字节原样复制，保证仅目标 part 变化（AC4）。红项自动修正为权威重算值，不覆盖原文件，输出数据校订版 docx 与改动逐条记录 csv。审计完成 → 校订前有暂停确认节点（AC6）。
配置层（通用化核心）
- config/schema.yaml：配置结构 schema，加载时校验必填项。
- config/mht.yaml / config/scl90.yaml / config/phq9.yaml：量表配置（数据列、学年块、列映射、表号映射、统计方法清单、阈值口径、班级后缀规则、方法名校验、生成槽位）。mht.yaml 的 stat_methods 含「量表间相关（关联性分析）」（impl: pearson）与可选「偏相关」（impl: partial），generation_slots 已指向 mht_gen_*.txt 四份实战提炼内容；scl90 / phq9 的 generation_slots 仍为 null（empty 框架）。
- config/mht_gen_sections.txt / mht_gen_methods.txt / mht_gen_prompts.txt / mht_gen_outline.txt：mht 的生成引导槽位内容（章节结构、统计方法清单、四阶段防幻觉提示词模板 + 统计审计员提示词、样例大纲），由主理人从 DeepSeek 实战对话导出提炼，gen_guide.py 仅装配不编造。
- scripts/config_loader.py：以脚本自身位置回溯定位 config，优先 PyYAML、缺失走精简解析器；把 stat_methods 的 params.vars 中的 ALL_MEASURES / TOTAL 展开为具体列；提供变量别名映射、测量列、量表枚举接口。
新增量表：复制一份量表配置，改 data_columns / stat_methods / table_map 等，脚本源码零改动即可跑通（AC9）。
脚本与目录结构
- 使用说明.md：面向「拿到技能包的人」的快速上手说明（非技术口吻：讲自然语言用法、准备物、输出物读法与 FAQ；命令行入口见其附录）。随技能包一并分发。
- 手动操作指南.md：面向不用 WorkBuddy、只用 Windows + Office 的同事的手动命令行操作指南（装 Python → 解压 → 开命令行 → 环境准备 → 运行 → 读结果 → 报错对照表）。
- requirements.txt：依赖下限清单（numpy / scipy / statsmodels / pandas / python-docx / PyYAML / lxml）；仅在跨机后随包 venv 失效且对方 Python 亦无依赖时用于自建环境。
- scripts/cli.py：统一编排入口（输入声明、按步调用、暂停确认）；解释器按「PSYQA_PYTHON 环境变量 → 随包 venv（健康检查）→ 当前解释器（回退）→ 明确报错」解析，兼容跨机使用。
- scripts/gen_guide.py、scripts/extract_nums.py、scripts/recompute.py、scripts/judge.py、scripts/amend_docx.py：五步主流程。
- scripts/config_loader.py、scripts/stat_methods.py、scripts/docx_io.py：配置 / 统计口径 / docx 解析公共库。
- templates/audit_table.html：审计表前端模板（接收 AUDIT_JSON / KEY_JSON / ISSUES_JSON 占位）。
- templates/guide_outline.json：生成引导大纲输出 schema 示例。
- references/stat-methods.md、references/docx-surgery.md、references/judge-rubric.md、references/gen-guide-placeholders.md：方法学、docx 手术、判定细则、生成引导占位说明。
- references/add-new-scale.md：新增量表指引（数据里出现配置外问卷时的接入步骤、决策树、验证清单与红线）。
输出物
- guide_outline.json：章节框架（生成引导）。
- audit_step2_rows.json / .csv：提取与溯源结果。
- audit_recompute_pool.json：精确重算池。
- 第四步审计表 html / .csv / .json：红黄绿判定结果（红项含裁决证据）。
- 数据校订版 docx 与改动逐条记录 csv：数据校订产物（仅在校订步骤产出）。
注意事项与边界
- 数据须已脱敏；本技能不处理含姓名 / 班级明文的原始数据。
- 依赖未脱敏学生标识的个体配对计算（如前测后测配对）脱敏数据无法复现，标记为可对应（依赖个体配对）黄项，建议以配对原始数据复核。
- 重算仅覆盖可复算统计量；文献引用、方法学常数、编号、类别标签为非数据断言，不参与比对。
- 阈值口径、方法学标注（如 Games-Howell vs Tukey HSD）以配置为准；报告标注与配置不一致会在审计表给出方法名校验提示。
- 降级诚实性：缺输入、缺依赖、畸形文件均显式报错并给出确切修法，不静默吞错。
验收与自测要点
- AC9：mht / scl90 / phq9 / epq 四套配置下，scripts 源码零改动跑通（同一次代码、仅 --scale 不同）。
- AC11：venv 内 import scipy / import statsmodels 成功，重算（Levene → Welch t、ANOVA、Pearson 等）跑通。
- AC4：校订仅改动 document.xml（位于 word/ 下），part sha256 全量比对其余 part 不变。
- AC3：红项 100% 带裁决证据。AC10：生成引导空槽位标 empty 不编造。AC8：缺必需输入报错退出。AC6：校订前暂停确认。
- 测试 fixtures 见 tests/fixtures/good/（合成脱敏，仅供测试，不含真实信息）。
权限与数据处理声明
- 读取：仅读取用户显式指定的输入文件（--data 的 xlsx、--report 的 docx）与技能自带的配置 / 模板。
- 执行：在本地随包隔离环境内调用 Python 子进程，运行统计与 docx 解析脚本。
- 写入：仅写入用户指定的 --out 输出目录（审计表、重算池、改动记录、数据校订版 docx）；不修改用户原始输入文件。
- 网络：全程本地运行，不联网、无遥测、不上传任何数据。
- 隐私：技能包内不含任何真实学生数据（测试数据均由生成器程序化合成）；输入须已脱敏，扫描到明文姓名 / 班级会主动中止运行并给出提示。
