language-conditioned-psychometric-harmonization-model/Document/research-workflow.md

# 语言条件化心理测量协调模型：研究工作流

版本：1.0｜日期：2026-09-20｜状态：工作流设计完成，研究执行尚未开始。

## 1. 目标与设计依据

本流程依据同目录下的《项目的正式定位》和《language-conditioned-psychometric-harmonization-model》设计。用户所称 `/Documents` 在当前项目中对应 `E:\Model\Document`。

核心目标是：用官方题目语义、调查背景与真实回答，估计题目参数、差异项目功能（DIF）、可比较的潜在表型及其不确定性；检验这种映射能否迁移到未见题目、问卷版本和国家。

优先检验的研究假设：在相同回答数据、调查设计处理和测试划分下，题目语义相对于无文本层级模型及人工构念标签，可以改善跨域测量与校准。研究必须允许该假设不成立；完成工作流不等于保证模型优于基线或达到发表标准。

第一版称为 **language-conditioned psychometric harmonization model**。只有获得充分的跨构念、跨数据集和跨任务迁移证据，再讨论 foundation model 的称谓。

本次完整阅读了两份项目文件，浏览了当前会话的全部技能目录，重点核对了学术研究、论文、审稿、SEM/IRT 与 PyMC 技能的职责和适用流程；同时抽查数据说明、质量报告及 NSDUH 构念映射表。尚未逐行审计个体数据、复核所有官方问卷或拟合模型。下文的“现有报告”与“建议验收条件”均不能当作本次重新计算的结果。

## 2. 当前材料如何影响路线

| 已观察到的材料 | 当前证据及限制 | 工作流中的处理 |
|---|---|---|
| 两份项目定位文件 | 目标清楚；详细文件中的若干数学公式存在转换缺损 | 以自然语言要求为依据，在模型规格中重新写清公式和识别约束 |
| GSHS 质量报告 | 现有报告记载 673,499 行、165 项调查、191 个非重叠组件，另有 10 项调查需范围复核；本次未重算 | 主开发候选；先核对组件、适用总体、官方文本、设计变量和题目共现 |
| GSHS 变量说明 | 同名 `raw_` 列不保证同义；权重、PSU、stratum 是待确认的候选字段 | 建立调查特异的题目版本 ID 与设计字典，不能直接按列名合并 |
| YRBS 全国原始库 | README 记载 1991–2023 年原始文件 | 原始文件存在与可直接分析是两个状态 |
| NSDUH/YRBS 整理包 | README 表明 YRBS 可分析表覆盖 1991–2019；2021、2023 等待导入布局验证 | 先审计是否已有后续修复；若没有，按官方导入程序验证后再解封 |
| NSDUH 构念映射 | 成人题、青少年题、COVID 条件题及派生变量混在候选表中；部分行没有原问题 | 回到完整字典及问卷核对青少年模块，不以 selected 表作为最终题目全集 |
| NSDUH 标签示例 | 2021 年 `YUSUITHK`、`SUICTHNK` 的候选构念同时包含 ideation 与 attempt；`SUIPLANYR` 标题明确为成人题 | 这是需要人工核实的映射问题；自动构念标签不能直接成为训练真值 |
| WHO/World Bank 背景表 | README 说明部分指标稀疏，WHO 资源数据不是完整年度面板 | 在题目模型建立后再加入；按可用时间匹配，避免未来信息泄漏 |
| LLM Agent 论文目录 | 从文件名看主要涉及规划、工具调用与多智能体 | 可供后续工程参考；本次未全文阅读，不能充当心理测量方法的核心文献依据 |

CDC 当前页面列出了 2021、2023 年的 SAS 导入及格式程序，可作为修复本地 YRBS 导入状态的来源；是否与本地文件匹配仍需验证。[CDC 年度数据与文档](https://www.cdc.gov/yrbs/data/national-yrbs-datasets-documentation.html)

## 3. 总体流程和分支

```mermaid
flowchart TD
    A[目标与数据版本登记] --> B[官方题库与回答字典]
    B --> C[可识别性与题目多样性审计]
    C --> D{证据支持哪条路线}
    D -->|连接充分且可识别| E[IRT / 层级测量模型]
    D -->|题目少或阶段结构更合适| F[多结局 / 潜类别 / 阶段模型]
    D -->|缺乏可靠连接| G[直接协调与分调查分析]
    E --> H[冻结划分与模拟验证]
    F --> H
    G --> H
    H --> I[直接协调与传统基线]
    I --> J[题目语义增益实验]
    J --> K{是否支持语义模型}
    K -->|支持| L[语言条件化模型与少样本适配]
    K -->|不足| M[补充桥接数据或形成边界性结果]
    L --> N[外部验证与完整消融]
    M --> N
    N --> O[可复现成果与论文审查]
```

文献定位可与题库整理同时推进；模型开发必须等待相应数据与识别条件满足。技术验收通过后，在已授权的执行范围内继续，不把每次常规检查变成用户确认。

## 4. 阶段 0：冻结研究问题、范围与版本

**目的：** 明确哪些证据能够支持核心主张，以及数据适用总体。

工作：

1. 建立文件清单、来源、哈希、重复及组件关系，选定唯一分析入口；保留原始文件。
2. 将 GSHS 设为跨国开发候选，YRBS 设为问卷及时间迁移候选，NSDUH 青少年模块设为外部候选。实际角色以审计结果为准。
3. 定义年龄、在校状态、地域覆盖和调查年份。主分析优先限定在能够可靠识别的共同年龄与总体范围；无法统一的总体分层报告，不把学校样本直接外推到全部青少年。
4. 分开记录测量构念：意念、计划、尝试、自伤、悲伤/绝望。后两者是否进入共同测量模型必须有理论和数据支持。
5. 将欺凌、孤独、睡眠、物质使用、家庭与同伴支持、暴力暴露放在解释层。解释层首先报告关联，不能凭横断面数据得出因果或个体纵向预测结论。
6. 进行聚焦文献定位：跨调查协调、语义预测 IRT 参数、跨语言 DIF、复杂抽样下的层级模型、新题目校准。建立与最接近方法的贡献比较表，不能预设“首创”。
7. 检查实际运行环境、软件版本、可用内存/GPU、存储、嵌入获取方式和许可；本流程不预设已经具备全部依赖。

**技能：** `deep-research` 的文献与方法设计模块；`self-improving-agent` 记录已验证的工程问题。

**交付物：** `project_charter.md`、`data_manifest.csv`、`literature_matrix.csv`、`environment_audit.md`。

**Gate 0：** 有明确的目标总体、主要迁移任务、数据来源及待验证列表。文献不必无限扩展，先覆盖支撑研究定位与识别方案的关键问题。

## 5. 阶段 1：建立有来源证据的题库和回答层

**目的：** 把原始调查转为可以审计的测量资料。

### 5.1 必要的数据实体

| 实体 | 最少字段 |
|---|---|
| 调查/组件 | `survey_id, component_id, country, year, scope, population, language, questionnaire_version` |
| 题目实例 | `item_version_id, item_family_id, source_variable, question_text, construct, time_window, response_type, language` |
| 回答字典 | `item_version_id, raw_code, raw_label, canonical_code, missing_type, derivation_rule` |
| 回答长表 | `respondent_id, survey_id, component_id, item_version_id, raw_response, canonical_response, eligibility, observed_status` |
| 抽样设计 | `survey_id, weight_field, psu_field, stratum_field, variance_method, design_source` |
| 来源和审核 | `source_file, source_url, page_or_section, text_hash, reviewer_1, reviewer_2, review_status` |
| 候选连接 | `item_pair, relation_type, semantic_evidence, population_overlap, anchor_status, exclusion_reason` |

`item_family_id` 连接同一题目的改写、翻译和版本；`item_version_id` 区分实际措辞、时间窗口、答案选项和适用条件。调查中的题目实例另保留来源身份。原始回答、派生指标、插补版本不得伪装为多个独立题目。

长表是保存回答和缺失状态的主格式；按调查生成稀疏的 person × item 矩阵及共现矩阵，避免创建大而稀疏的全库密集矩阵。

### 5.2 必须处理的事项

- 官方问题、答案标签、年龄范围和跳题逻辑逐项核对；只获得变量标题时标为待核实，不补写成“官方原文”。
- 官方译文、实际施测语言、研究者翻译分别记录；仅有英语参考问卷不能证明实际以英语施测。
- 区分未施测、不适用、合法跳题、拒答、不知道、普通缺失和真实阴性。合法跳题能否推导为阴性只能按明确的官方规则处理。
- 主要结局由两名实际审核者复核并记录；AI 的两次检查可作预审，不能登记成两名人类审核者。尚无人类复核的条目标为 provisional，先用于流程开发。
- 主要结局不能仅从自动筛选的 selected 表收集，应与完整字典核对，防止遗漏尝试次数等关键字段。
- 多调查合并时为 PSU/stratum 增加调查或组件命名空间，并按官方设计保留必要关联，防止相同编号误合并。
- YRBS 的原始文件、导入程序、标签、样本数和官方描述性结果需相互核对后才标为 ready。

**技能：** 执行时按需加载 `pdf`、`documents:documents` 读取问卷，`spreadsheets:Spreadsheets` 生成供审核的字典。本阶段仍需要项目专用的数据解析和检查代码；文档技能本身不执行统计协调。

**交付物：** `item_bank.csv`、`response_dictionary.csv`、`survey_design.csv`、`construct_ontology.yaml`、`responses_long.parquet`、`item_links.csv`、`source_conflicts.csv`。

**Gate 1：** 正式分析题目均有来源、编码、总体及缺失规则；主要结局完成所要求的双重核查。待核实题目保留在候选库，不能静默进入确认性分析。

## 6. 阶段 2：可行性、可识别性和连接审计

**这是全项目最先应完成的科学交付。**

按国家 × 年份 × 工具 × 组件 × 构念统计：有效题目数、共同作答人数、阳性事件数、答案分布、缺失/跳题比例、设计变量完整性，以及考虑设计后的精度指标。权重推导的有效样本量可作筛查，但不能替代完整抽样设计方差。

同时生成：

- person × item 回答矩阵及 item × item 共现矩阵；
- 调查—题目二部图、候选锚题图、连通分量和薄弱桥接点；
- 去重后的题目家族数、措辞版本数、语言数、时间窗口与回答形式多样性；
- 国家、工具、语言、年份与样本人群的混杂/秩亏表；
- 跨组件重复或重叠样本风险表。

### 6.1 审计决策

| 路线 | 需要的证据 | 不足时如何处理 |
|---|---|---|
| IRT / 多维测量 | 理论支持、实际共答、足够回答变化、明确标度与识别约束，且参数恢复可靠 | 简化维度、限制参数、改用其他观测模型或直接协调 |
| 层级跨组链接 | 可靠的锚定/桥接及足够连接，潜在均值与 DIF 可被区分 | 分连通分量分析；增加桥接样本；将无法识别的部分标为模型外推 |
| 阶段/潜类别/多结局 | 相应结构有证据支持 | 不强制假设“意念→计划→尝试”严格嵌套，检查无计划尝试等回答 |
| 直接二分类/频数协调 | 官方定义、时间范围、选项和总体足够相近 | 保留多个定义层级或分调查报告，不强行二元合并 |

语义相近只产生候选锚题，不证明测量不变性；图连通也是必要线索而非充分的可识别性证明。允许少数部分不变锚题、锚题替换和留锚敏感性分析，但选择只能依据训练/开发资料。

国家潜在均值、国家题目阈值平移和无约束 DIF 可能混淆。模型规格必须写明参考组/标度、锚题约束及 DIF 约束。跨调查没有经验连接时，语义先验不能自动证明共同标度被数据识别。

**特别注意：** 语义到题目参数的学习，独立信息单位主要是题目家族与版本。受访者数量大不能弥补题目种类少。阈值不凭经验随意定为“每组至少多少人”，而应结合预期精度、设计效应、事件稀疏度和模拟参数恢复制定。

**技能：** `alterlab-sem-psychometrics`、`pymc-modeling`。前者引用的 `alterlab-ssci-measurement-gate`、`alterlab-statistical-analysis` 和 `alterlab-ssci-inference-gate` 不在当前可用技能目录；不能将这些依赖写成已经执行。其职责在本项目中转为显式审计清单和代码检查。

**交付物：** `feasibility_audit.md`、`construct_feasibility.csv`、`item_cooccurrence.parquet`、`anchor_graph.graphml`、`identification_spec.md`、`item_diversity_report.md`。

**Gate 2：** 每个构念得到“可进入潜变量模型 / 有条件可进入 / 仅可直接协调 / 暂不纳入”的判定与依据。最小可行实验的调查、构念及题目集合在此确定。

## 7. 阶段 3：冻结验证协议并做已知真值模拟

**目的：** 在查看最终测试表现前，定义成功、失败和计算可靠性的含义。

### 7.1 外层测试任务

| 任务 | 训练时必须留出什么 | 测试时允许使用什么 |
|---|---|---|
| 未见题目家族 | 同一家族所有目标回答与监督信号；训练不能混入其翻译/近重复版本 | 新题目正文、选项、时间窗口及预先允许的背景 |
| 未见问卷版本 | 指定版本及泄漏等价版本 | 版本元数据与题目文本；few-shot 时另给支持集 |
| 未见国家 | 该国全部年份和组件的回答 | 预先允许的国家背景；未知国家效应从层级分布预测并传播不确定性 |
| 未见地区 | 整个预定地区的回答 | 与未见国家任务一致；国家/地区定义预先冻结 |
| 时间外 | 截点后的回答和后验信息 | 截点前训练资料；背景变量按预测时点可得性匹配 |
| 跨工具 | 整个目标工具的回答 | 经总体与定义审计后的外部问卷信息 |

未见题目家族与已知家族的新措辞是不同难度的任务，分别报告。所有预处理、降维、文本模型选择、先验调优和锚题筛选在内层训练/验证中完成。

Zero-shot 明确指“不使用目标题目/目标域的回答来拟合其参数”。对测试受访者使用其他允许的回答推断 θ 时，必须遮蔽正在评分的回答；没有可用回答时，对 θ 的预测分布积分。不能用某个回答推断 θ 后又对同一回答报 held-out 得分。

Few-shot 将目标域分成支持集和查询集；按 PSU 或独立受访者分离，依据实际设计避免聚类泄漏。可预设 0、25、100、500 个支持受访者的学习曲线，具体预算由审计和抽样单元决定，这些数值是候选实验设置而非样本充分性标准。

### 7.2 模拟实验

用已知参数生成：无 DIF/弱 DIF/强 DIF、少锚题、稀有事件、不同维度、结构性缺失与跳题、组间均值不同、抽样权重差异、国家与语言混杂等场景。

检查 a、b、DIF、群体分布及区间覆盖；必要时进行 scoped SBC。SBC 检验推断算法在生成模型下的校准，不证明真实数据符合模型。调查加权伪后验还需另做设计型重复抽样评估，不能直接套用普通生成模型的 SBC 作为充分证据。[Stan：Simulation-Based Calibration Checking](https://mc-stan.org/docs/stan-users-guide/simulation-based-calibration.html)

真实数据的完整样本 IRT 参数不是已知真值，只能是带不确定性的参照。真实数据参数比较需保持共同标度；对齐不能使用已留出题目的真值信息。

**交付物：** `analysis_protocol.md`、`split_manifest.csv`、`simulation_plan.yaml`、`simulation_report.md`、`metrics_spec.yaml`。

**Gate 3：** 测试集身份、允许信息、主指标及报告方式冻结；简化模型能够在已知真值场景中可靠恢复。存在不可识别或计算问题时先修复，不通过提高模型复杂度掩盖问题。

## 8. 阶段 4：建立直接协调和传统基线

采用两条相互关联但不混淆的基线轨道。

| 轨道 | 模型 | 作用 |
|---|---|---|
| 测量 M0 | 官方定义下的直接协调 | 结局定义、设计加权比例及不确定性的基线；不能虚构其没有的 θ 或 a/b |
| 测量 M1 | Rasch/2PL/有序 IRT 或审计通过的替代形式 | 不使用语义的测量参照 |
| 测量 M2 | 层级 IRT/层级替代模型，有限 DIF | 检验层级共享本身能带来的迁移改善 |
| 预测 P0/P1 | Logistic、XGBoost；TabPFN 可选 | 检验一般表格预测能否解释附加收益，属于辅助任务 |
| 语义辅助 P2 | 嵌入 + 普通分类/回归模型 | 区分“文本对预测有帮助”和“文本对测量参数迁移有帮助” |

传统 item-ID 模型无法 zero-shot 生成新题目参数时，明确标为不支持；另提供构念均值/层级先验预测作为可计算的冷启动基线，并报告 few-shot 曲线。不同模型只比较共同支持的估计目标。

先验证加权描述性结果与同一总体、同一分母下的官方报告相容；不能通过调整编码“对齐”不匹配的官方总体。

复杂抽样处理分为三层：描述性估计及设计方差；模型内声明权重归一化和伪似然等选择；对关键群体估计使用合适的复制权重或设计一致的重抽样检查。权重直接乘进似然不等于区间已经正确。跨国训练权重与各调查群体估计权重分别定义。

**技能：** `alterlab-sem-psychometrics`、`pymc-modeling`，以及项目专用复杂抽样代码。SEM 技能中的连续指标 CFA 模板、omega 简式和拟合经验阈值不能不加判断地用于二元、稀有或多维条目。

**交付物：** `baseline_results.parquet`、`design_validation.md`、`model_diagnostics.md`、基线参数和预测文件。

**Gate 4：** 基线可复现，设计变量保留，主要参数收敛/精度和后验预测检查合格，评估未发生回答或调查泄漏。

## 9. 阶段 5：低成本语义增益实验

先回答“文本是否包含可迁移的测量信息”，再训练完整模型。

1. 分别编码题目正文、时间窗口、选项、整体模板；语言/国家/工具背景单独保存。
2. 比较可复现的开源多语言嵌入、高性能通用嵌入、领域嵌入；具体模型在执行时按许可、可得性、成本及训练内性能确定并冻结。
3. 固定编码器起步，采用低维/正则化映射。文本样本少时不默认微调大模型。
4. 只用训练折拟合题目参数或相关结构，再评估语义是否解释这些测量属性；用参数后验样本或误差模型传播估计不确定性，不能把拟合参数当无误差标签。
5. 对 item–item correlation 的比较使用共同作答证据，并考虑国家与总体差异；同国相关结构相似不一定是题目语义造成的。

**最低限度对照：** 人工构念标签；item-ID；TF–IDF；随机向量；在题目之间打乱嵌入对应关系；打乱词序；删除时间窗口；删除回答标签；单语/多语对照；只有背景无题目文本的模型。

词序打乱并不是严格无语义对照，因为部分编码器仍可保留词义；题目—嵌入对应关系置乱更直接检验监督关系。全部置乱遵守题目家族分组，避免只扰动部分重复版本。

**交付物：** `item_embeddings.parquet`、`embedding_manifest.json`、`semantic_increment_report.md`、`semantic_controls.parquet`。

**Gate 5：** 依据预先冻结的跨题目家族指标、效应区间与实际意义判定增益，不能只凭 UMAP 图或训练相关系数。

若语义没有稳定增益：先检查题目多样性、文本/编码错误和任务天花板；扩充真实题目或桥接资料后重新开展明示为新版本的研究，或报告语义增益的适用边界。不能在最终测试集上反复挑模型。

## 10. 阶段 6：语言条件化层级测量模型

第一版只选审计通过的构念和观测形式。二元模型的示意为：

\[
Y_{ijg}\sim\mathrm{Bernoulli}\{\operatorname{logit}^{-1}[a_j(\theta_{ig}-b_j-\delta_{jg})]\},
\]

\[
\log a_j=\alpha_a+f_a(e_j)+r_{aj},\qquad
b_j=\alpha_b+f_b(e_j)+r_{bj}.
\]

其中 e_j 来自题目语义，r 为有正则化的题目残差；δ 为有约束的组别 DIF。组别可由调查背景定义，但不能将完全混杂的国家、语言和工具效应当作分别可解释的因果效应。

这只是结构示意，实施前必须补齐 θ 的参考标度、锚题限制、残差及 DIF 先验、组间分布、权重方式和缺失/跳题的观测机制。有序题目使用有序阈值；不同构念经理论和数据支持后才增加维度，不直接将所有题目塞进单维模型。

开发顺序：

1. **M3a：语义预测阈值。** 固定嵌入，以简单线性/低维映射起步。
2. **M3b：语义同时预测区分度和阈值。** 与 M3a 比较，判断额外复杂度是否被数据支持。
3. **M3c：加入有约束的语义 × 背景 DIF。** 与无交互或单纯层级 DIF 比较。
4. **M4：新题目、新国家和 few-shot 适配。** 更新被允许的局部参数，报告支持集大小与成本；查询集保持封存。

新题目的残差、未见国家效应和 DIF 均需从后验预测分布抽取/积分，不能简单设为 0 后给出过窄区间。Zero-shot 的具体国家 DIF 是模型预测，不是已经从该国回答识别出的参数。

先在小规模可诊断样本上完成可靠推断，再评估扩展方式。大数据近似推断应在可运行的子集上与高质量采样结果比较。报告采样发散、R-hat、有效样本量、MCSE、先验/后验预测检查；诊断未解决不能作为确认性推断发布。

**技能：** `pymc-modeling` 为主要实现依据，`alterlab-sem-psychometrics` 提供测量检查。PyMC/ArviZ 等 API 按实际安装版本核对，不照搬技能文件的版本假设。

**交付物：** 模型代码、冻结配置、参数后验、预测文件、`model_card.md`、`adaptation_protocol.md`。

**Gate 6：** 计算可靠，复杂度有支持，新域区间包含未见效应的不确定性，且 M3/M4 的结果可与相应传统基线公平比较。

## 11. 阶段 7：最终验证、消融和主张判定

### 11.1 指标层次

| 层次 | 指标与解释 |
|---|---|
| 共同主指标 | 未见题目家族的 held-out log score；未见国家/工具的预先指定共同目标上的校准或分布误差。对每个主张预先指定指标，不能挑表现最好的域 |
| 模拟确认 | 已知真值下 a/b/DIF 及群体量的恢复误差，预设区间的重复覆盖率 |
| 真实数据测量 | 后验预测、局部依赖、DIF 效应与不确定性、锚题敏感性；可靠性指标按模型类型报告 |
| 群体估计 | 设计加权比例/分位数、标准误、共同定义下的差异；参考比例也有抽样误差 |
| 辅助预测 | Brier、校准截距/斜率、AUPRC、AUROC；不以 AUC 单独证明测量协调成功 |
| 迁移成本 | 支持集规模、计算时间、内存、适配稳定性 |

θ 的任意阈值不能自动叫作患病率。没有经验证的诊断阈值时，报告潜在分布、分位数或指定参考题目上的模型推导阳性比例。

真实数据潜变量与参数没有普遍已知的真值，因此不能宣称已经测得“真实 θ 区间覆盖率”。真实数据依靠独立查询回答、设计估计及敏感性分析；参数覆盖率主要由模拟支撑。

### 11.2 最低限度消融

- M0 → M1 → M2 → M3a → M3b → M3c → M4，区分每项增益来源。
- 去题目正文、时间窗口、答案标签；去国家/年份背景。
- 无文本、构念标签、随机/置乱嵌入与背景专用模型。
- 无 DIF、替换/删除锚题、删除一个调查工具、排除低频题目。
- 加权与不加权、不同合理权重缩放；PSU/stratum 完整与受限样本。
- 严格同定义题目与较宽协调定义；缺失/跳题的合理替代假设。
- 固定嵌入与微调仅在有效题目量足够时比较。

按国家/调查等外层独立单元报告配对差异和区间，避免把大量相关回答当作独立的迁移重复。以预先定义的国家宏平均为主时，另报告样本加权结果；国家数少则明确精度有限。

亚组按性别、年龄、地区、语言、收入组及可靠可用的其他字段评估。测量 DIF 与预测性能差异分开；本研究没有临床筛选或资源分配决策时，不额外声称已验证政策公平性。

**成功判定：** 语义模型在预设迁移任务上相对最佳适用传统基线具有稳定且有实际意义的改善，同时校准/区间质量没有重要退化，并经关键消融支持。最小有意义改善和非劣界限在开发/模拟阶段设定并冻结。

某个任务失败时限制对应主张。例如未见国家改善而未见题目不改善，只能支持相应范围的迁移结论。完整验证流程即使得到阴性结果也可形成有价值的基准或方法边界成果。

**交付物：** `external_validation_report.md`、`ablation_results.parquet`、`subgroup_results.parquet`、`claims_evidence_matrix.csv`、最终表图。

## 12. 阶段 8：可复现交付与论文审查

先冻结分析版本，再把结果转换为论文。可提前写引言和方法草稿，结果与结论必须来自已冻结输出。

1. `academic-paper`：构建“研究问题—方法—证据—限制”的论证结构。
2. 完整性审计：核查文献、正文主张、表图数字和分析文件对应关系，注明检查分母、抽样范围及未核实项。
3. `academic-paper-reviewer`：先方法学审查，再完整审查；角色覆盖心理测量、调查抽样、跨文化迁移与机器学习。多角色 AI 意见不能替代人类专家验证。
4. `academic-paper` revision：按问题清单修订；复审检查问题是否解决，之后再次进行完整性核查。
5. 根据目标期刊使用 `apa-style` 或对应引用规范；`humanizer:humanizer` 只改善表达，不改变证据强度或隐藏 AI 使用记录。
6. 按需用 `documents:documents`、`pdf`、`presentations:Presentations` 输出并检查版式；科研图表使用可复现绘图工具。

`academic-pipeline` 适合管理研究到论文的交付、审稿和状态记录。其默认“已有数据→写作”的路由不适合直接用于本项目，必须先经过上述数据、识别和实验门槛。本次仅设计流程，并未启动其完整执行状态机；若后续选择按原版执行，其中阶段确认机制须按用户授权和实际技能规则处理。

**最终成果包：** 可追溯题库、数据处理代码、冻结划分、模拟基准、传统与语义模型、参数/预测与区间、实验记录、数据/模型说明卡、论文及补充材料。能否分发原始或衍生个体数据按来源许可另行确认，默认优先交付代码和聚合结果。

## 13. 技能分工与真实缺口

| 技能/类别 | 使用位置 | 能力边界 |
|---|---|---|
| `deep-research` | 文献定位、方法与证据核验 | 不替代逐题官方字典核对和实际统计分析 |
| `alterlab-sem-psychometrics` | 测量结构、IRT、不变性与可靠性 | 不自带本项目的语义条件化模型或完整复杂抽样实现；若干上游技能未安装 |
| `pymc-modeling` | 分层建模、模拟、诊断、预测 | 不自动保证可识别性、设计一致性和计算可扩展性 |
| `academic-pipeline` | 阶段状态、交付、论文审查编排 | 学术生产管理层，需要接入本项目的实验工作流 |
| `academic-paper` / `academic-paper-reviewer` | 写作、审稿、修订、复核 | 不把模拟审稿当作方法或结果已获外部认可 |
| `pdf` / `documents` / `spreadsheets` | 官方文件提取、审核字典、成果输出 | 提取文字不等于完成官方语义确认 |
| `apa-style` / `humanizer` | 引用与文字质量 | 不生成证据，不提升未经支持的科学主张 |
| `visualize` / `presentations` | 后续展示进展和模型机制 | 科研结果图另用标准可复现绘图；本次用静态流程图已足够 |
| `self-improving-agent` | 记录复现环境和错误修复 | 仅沉淀已核实经验，不作为研究证据 |
| `skill-creator` | 流程跑通后可封装项目技能 | 本次先交付工作流，不提前把未验证流程固化成技能 |

其余网站、插件管理、图像生成、应用控制及来源标记移除等技能不进入核心研究路线。当前缺口主要是项目专用的题库解析、锚定图审计、复杂抽样评估、无泄漏划分和语义条件化测量模型代码，不是缺少更多通用写作技能。

## 14. 实施批次、资源和停机条件

### 第一批：拿到可行性答案

完成阶段 0–2。优先交付八项：数据版本清单、主要结局来源表、总体/年龄适用表、共现矩阵、锚定图、题目多样性表、构念可行性判定、下一步最小实验定义。完成后才能给出可信的训练规模、硬件需求和工期估计。

### 第二批：最小科学闭环

从已通过审计的一个构念或明确的多结局结构起步，使用题目来源完整、设计资料完整的连通子集。完成一个已知真值模拟、M0/M1/M2、固定嵌入到阈值的简单映射，以及一个未见题目家族和一个未见国家任务。有效版本不足时如实报告，不能用随机个体划分替代。

### 第三批：扩展与正式交付

在最小实验和语义增益门槛通过后，再扩展到更多国家、年份、工具、DIF 和 few-shot。第二构念扩展放在主要 benchmark 稳定以后。

### 资源策略

先读取元数据和小规模样本做验证，不直接在全量受访者上拟合最复杂模型。嵌入按文本哈希和模型版本缓存；中间数据保存为列式表。实测单个基线、单个模拟和单个外层折的时间/内存后估算总预算，不在未审计前承诺固定完成天数。

### 停机或降级条件

| 条件 | 动作 |
|---|---|
| 官方文本、适用总体或编码无法确认 | 题目暂不进入正式分析，继续可确认部分 |
| 锚定不足、图不连通或标度不可识别 | 分组件报告、直接协调或提出桥接数据方案 |
| 独立题目家族太少 | 简化语义映射并限制泛化主张，优先寻找真实题目多样性 |
| 收敛或参数恢复失败 | 简化/重新参数化，保留失败记录，不发布不可靠推断 |
| 语义收益只出现在随机个体划分 | 判定核心迁移主张未获支持 |
| 最终测试反复被用于调参 | 将该测试集降为开发集，并重新确定独立测试证据 |
| 权重/PSU/stratum 不完整 | 标记推断限制，采用有依据的可用设计方法，不宣称完整设计校正 |

## 15. 文件与状态管理约定

建议执行时在项目中新增以下目录；它们在本次尚未创建：

```text
E:\Model\
  Document\research-workflow.md
  research\protocol\       研究问题、识别规格、验证协议
  research\audit\          题库来源、连接审计、可行性报告
  research\metadata\       题库、字典、构念本体
  research\processed\      派生回答表与矩阵
  research\splits\         冻结测试划分
  research\embeddings\     版本化嵌入与清单
  research\models\         基线与语义模型
  research\experiments\    模拟、配置、诊断、运行日志
  research\results\        已冻结结果与表图
  research\manuscript\     论文、审稿及修订记录
```

每个阶段记录：`status, input_hashes, config_version, outputs, checks, unresolved_issues, next_action`。状态使用 `not_started / in_progress / passed / conditional / blocked / failed`；只有交付物和检查证据满足要求才标为 passed。证据不足时可以完成一个“有条件”或“不可行”的审计结论，不能把它记为模型已经验证。

每次新任务只加载本流程、阶段状态和当前所需输入，避免重复全文读取整个资料库。若后续启用多代理，按官方题库、测量方法和验证审计等清晰边界分工，交接文件并记录来源；多代理不是本工作流成立的必要条件。

## 16. 本次查阅的主要依据

本地研究目标：

- [项目的正式定位](E:/Model/Document/项目的正式定位.md)
- [模型定位与输入输出](E:/Model/Document/language-conditioned-psychometric-harmonization-model.md)

本地数据状态：

- [整理包说明](E:/Model/Dataset/可直接分析数据包_NSDUH_YRBS/README.md)
- [候选构念映射](E:/Model/Dataset/可直接分析数据包_NSDUH_YRBS/harmonization/construct_crosswalk.csv)
- [GSHS 变量注意事项](E:/Model/Dataset/GSHS-全球学生健康调查数据/GSHS/02_documentation/变量使用注意事项.md)
- [GSHS 现有质量报告](E:/Model/Dataset/GSHS-全球学生健康调查数据/GSHS/04_quality_control/数据质量检查摘要.md)
- [YRBS 原始库说明](E:/Model/Dataset/YRBS_National_1991_2023/README.md)
- [国家背景资料说明](E:/Model/Dataset/WHO-country_context/README.md)

关键技能：

- [academic-pipeline](C:/Users/Jino/.codex/skills/academic-pipeline/SKILL.md)
- [deep-research](C:/Users/Jino/.codex/skills/deep-research/SKILL.md)
- [SEM 与心理测量](C:/Users/Jino/.codex/skills/alterlab-sem-psychometrics/SKILL.md)
- [PyMC 建模](C:/Users/Jino/.codex/skills/pymc-modeling/SKILL.md)
- [academic-paper](C:/Users/Jino/.codex/skills/academic-paper/SKILL.md)
- [academic-paper-reviewer](C:/Users/Jino/.codex/skills/academic-paper-reviewer/SKILL.md)

官方技术来源：

- [CDC 年度 YRBS 数据与导入文档](https://www.cdc.gov/yrbs/data/national-yrbs-datasets-documentation.html)：用于确认 2021/2023 官方导入资料入口存在。
- [Stan SBC 指南](https://mc-stan.org/docs/stan-users-guide/simulation-based-calibration.html)：用于推断计算验证的设计；并非真实数据可识别性的替代证据。

以上为针对现有项目材料提出的工作流，不是已完成的数据审计或统计研究报告。

## 17. GitHub 组件选型补充（2026-09-20）

已完成首轮外部仓库检索与静态检查，详见 [GitHub 借用评估](E:/Model/Document/github-reuse-assessment.md) 和 [仓库版本登记表](E:/Model/Document/github-repository-registry.json)。优先试验 Harmony、Sentence Transformers、mirt、PyMC 与 R survey 的组合；Rmonize 作为可追溯协调流程的可选组件。

接入时先隔离 Harmony 与新版语义编码环境，遵守原有官方题库、可识别性和迁移验证门槛。仓库审阅不代表本地依赖已安装或统计验证已通过。建议后续将文档、代码、配置及数据哈希纳入本地 Git，原始个体数据和大型模型文件另行管理。