问卷代码本生成器

用途

当用户需要整理心理学、教育学、公共卫生、社会科学或学生研究项目中的问卷条目、量表维度、变量名、计分规则、反向计分条目或数据录入规范时，请使用本技能。

核心输出是一份结构清晰的代码本，可直接复制粘贴至 Word、Excel、SPSS、R、Mplus 或研究方案文档中。

触发时机

当用户提出以下任一请求时，请激活本技能：

• 将问卷条目转换为代码本。
• 为问卷条目生成变量名。
• 标注反向计分条目并推导计分规则。
• 构建包含维度、条目编号、作答锚点及总分计算方式的表格。
• 为 Excel / SPSS / R / Mplus 准备数据录入规范。
• 检验问卷计分是否具备内部一致性。
• 将杂乱的量表描述转化为分析就绪的表格。

必需的输出格式

当用户提供问卷条目时，除非用户明确要求其他格式，否则请按以下顺序输出以下五个部分：

1. 量表代码本 / Codebook
   提供一个 TSV 表格，包含以下列：variable、item_id、dimension、item_text、response_range、reverse_scored、scoring_note、missing_rule。

2. 计分规则 / Scoring rules
   说明如何计算各维度得分与总分；明确指出应采用“总和分”还是“均值分”。若用户未提供缺失值处理规则，则建议采用透明、可复现的规则，例如：“仅当某维度下至少 80% 的条目为有效值时，才计算该维度的均值分”。

3. 反向计分检查 / Reverse-scoring check
   列出所有需反向计分的变量，并给出换算公式。对于 1–5 量表，使用 reversed = 6 - original；对于 0–4 量表，使用 reversed = 4 - original。

4. 分析软件变量建议 / Analysis-ready variable names
   提供简短、易读、符合编程惯例的变量名。避免空格、中文标点、连字符及过长名称。在适用情况下，使用前缀如 dep_（抑郁）、anx_（焦虑）、smu_（社交媒体使用）、sleep_（睡眠）、neuro_（神经质）、eant_（情绪调节）等。

5. 质量控制提示 / QC checklist
   指出潜在问题：重复的条目 ID、不一致的作答范围、缺失的维度标注、反向计分标识模糊等。

变量命名规则

• 仅允许使用小写字母、数字和下划线（_）。
• 必须以字母开头。
• 尽量将变量名控制在 20 个字符以内。
• 保留量表原始顺序，使用两位数字编号，例如：dep_01、dep_02、anx_01。
• 当量表含多个维度时，应在变量名中加入对应维度前缀。
• 若用户明确要求兼容旧版 Mplus（legacy Mplus-safe names），则变量名不得超过 8 个字符。

反向计分公式

对于最小值为 min、最大值为 max 的条目：

reversed_score = min + max - original_score

常见示例：

• 1–5 量表：reverse = 6 - original。
• 1–7 量表：reverse = 8 - original。
• 0–4 量表：reverse = 4 - original。
• 0–10 量表：reverse = 10 - original。

缺失值处理规则建议

优先采用用户已明确指定的缺失值处理规则；若未提供：

• 维度均值分：仅当该维度下至少 80% 的条目为有效值时进行计算。
• 总量表均值分：仅当全量表中至少 80% 的条目为有效值时进行计算。
• 除非用户明确要求插补（imputation），否则禁止静默式填补缺失值。

可选辅助脚本

本技能附带脚本 scripts/make_codebook.py，可将简易 CSV 格式的条目文件自动转换为 Markdown 格式代码本与 TSV 格式变量映射表。该脚本仅依赖 Python 标准库模块，无需额外安装依赖。

输入 CSV 文件需包含以下列：

item_id,item_text,dimension,scale_min,scale_max,reverse

示例命令：

python3 scripts/make_codebook.py examples/demo_items.csv --out-dir output

若系统中不可用 python3，可尝试：

python scripts/make_codebook.py examples/demo_items.csv --out-dir output

安全性与完整性保障

• 不得虚构问卷条目文字或计分规则。
• 对存疑的反向计分判断，须明确标注为“不确定”。
• 缩写条目标签时，不得改变其原始含义。
• 除非用户提供量表手册原文或明确要求核查权威临界值（clinical cutoff），否则不得自行设定临床判定阈值。
• 在转化计分逻辑时，须严格区分：条目级反向计分、维度得分计算、总量表得分计算三类操作。