generate-codebook

生成代码簿技能

将原始表格数据集转换为结构化、可引用的数据字典（代码簿）。这是字典优先工作流中的生成器部分：它会生成供 /define-variables 和后续字典优先 QC 使用的产物。分布、类型和缺失情况都可以观测到，随附的脚本会对其进行分析；编码值的含义（fatty_liver_grade = 0）无法从数据中观测到，只存在于权威数据字典中。你负责生成代码并审查输出——不得臆造编码值的含义。

确定性脚本

运行随附的分析脚本，而不是凭记忆描述列：

python "${CLAUDE_SKILL_DIR}/scripts/generate_codebook.py" data.csv --out-dir .

支持 .csv/.tsv/.xlsx/.parquet/.dta/.sas7bdat。标志：--max-levels N （分类变量的阈值，默认为 20）、--json-only、--md-only。该脚本仅依赖 pandas，在本地运行，绝不会向任何地方发送数据。

工作流

第 1 步：分析（确定性）

对数据集运行 generate_codebook.py。它会生成 codebook.json（机器可读）和 codebook.md（审查表格），并报告各变量的：角色（id / 连续 / 分类 / 二元 / 日期 / 文本）、数据类型、缺失情况、唯一值数量、各类别频数或分位数摘要，以及 needs_dictionary 标志。

第 2 步：与研究人员审查（关卡）

在解读输出之前，先阅读 ${CLAUDE_SKILL_DIR}/references/codebook_schema.md（其中包含 codebook.json 的架构、角色推断启发规则和 needs_dictionary 规则）。向用户展示 codebook.md，并逐项讲解。**关卡：**角色推断是一种启发式判断，因此需要用户确认推断出的角色（例如，被误读为连续变量的整数编码量表，或 id 列）。在用户批准角色分配之前，不得继续进行变量定义工作。

第 3 步：处理 [NEEDS DICTIONARY] 项（关卡）

对于每个标记为 needs_dictionary: true 的变量，如果没有权威来源，就无法解读其各类别编码。**关卡：**请用户提供真实数据字典中每个编码的含义（文件/工作表/行），或确认不存在数据字典。只能根据该来源，将 label、units 和各类别含义填入代码簿，并引用文件 > 工作表 > 行——不得根据推断填写。如果用户无法提供，请保留 [NEEDS DICTIONARY] 标记；不得将其删除。

示例：在一个队列文件中，sex（类别 1/2）和 fatty_liver_grade（0..4）会被标记，因为其类别只是编码；smoking_status（never/former/current）则不会。绝不能写 sex: 1 = male，理由是“通常都是这样编码的”——如果无法取得数据字典，就必须保留标记。

第 4 步：交接

已完成的 codebook.json 将作为 /define-variables（操作化）的输入字典，并作为字典优先 QC 的引用来源。**关卡：**确认用户已解决所有 needs_dictionary 标志，然后才能将代码簿视为下游分析的权威依据。

在将代码簿对外共享之前，先对原始数据运行 /deidentify。清理或转换数据请使用 /clean-data。

已知限制

• 不会将超过 3 个字符且不是数字的代码（C50.9、S001）识别为代码，因此相应的列不会被标记为 needs_dictionary。
• 如果整数编码列的不同值数量超过 --max-levels，则会被归类为 continuous，且不会被标记。第 2 步的角色审查可以发现此类列。
• 对存储数字字符串的 text 列也是如此：任何数值（45、88）都会被视为测量值，因此以字符串形式导出的整数代码若有超过 --max-levels 个值，就不会被标记。

输出格式

codebook.json（架构见 references）和 codebook.md（审查表格，含“需要查阅字典的列”部分）。在对话中总结行数、列数和 needs_dictionary_count；不要粘贴完整 JSON。