第1章 代码库使用说明与 Agent 执行契约

现行主案例执行入口（2026-09-19）

Myocardial_Infarction_Complications的唯一执行根位于仓库 04_Cases/Myocardial_Infarction_Complications/，参数由analysis_config.R维护。按案例运行指南执行，不能复制本章技术Demo的变量、折数或数值替代主案例。

任务 主案例脚本
读取与描述、固定成员 L01_Read_Check_Demo.R、L02_Data_Preparation.R
LASSO lambda.min按原始变量筛选、普通Logistic L03_Feature_Selection_Logistic.R
完整训练内筛选/调参的外层OOF L04_Internal_Validation.R
共享特征的RF/XGBoost/SVM与SHAP L05_ML_Comparison_SHAP.R
第5课集中纠错、Kappa冻结与留出对照 L06_Data_Audit_T0_Correction.R
单变量整体LRT与AIC机制展示 Teacher_Selection_Demonstrations.R
冻结系数列线图及验证 Export_Classroom_Artifacts.R、Validate_Review_Run.R、Check_Separation.py
Python完整统计主链快速展示 Export_Python_Raw.R、Python_Statistical_Workflow.py

Python演示保留原始缺失与固定成员，在各训练范围独立筛查、插补和选择lambda.min，再按原始变量拟合普通Logistic，训练OOF最大Kappa阈值冻结后用于测试。使用scikit-learn 1.9的SAGA，与R glmnet内层实现不同，不要求数值完全一致；R维护正式四模型比较。完整脚本课前预跑，最后一课仅快速展示数据→描述→筛选→拟合→评价，课后可依据代码与浓缩讲义复现。

All111是异常教学反例；Corrected执行已确认的时间、稀疏/零格、无变异和极低观测比例筛查。旧版T0_102不是最终纠正版。不要用已全训练插补的矩阵做CV，不从测试选变量、调参或选阈值。具体统计边界见教学契约。

通用技术Demo与原有代码片段

以下Demo_R_Project及其数值属于独立技术示范，保留作为片段查阅；本节默认值不覆盖上面的主案例配置。

本章解决什么问题：这本 Code Library 是什么、怎么按任务检索、怎么运行配套 Demo、怎么把任务交给 AI Agent 执行、Prompt 契约怎么写、输入输出如何验收，以及六章分别管哪一段流程。读完本章，你应该能独立找到需要的章节与 Prompt，把一次分析任务完整交代给 Agent 并核对它的产物。

注记本章定位

本章只讲”怎么用”，不讲统计方法本身。方法原理见课程讲义，Agent 与环境操作见工具手册；从第 2 章起，每一章针对一个具体任务给出代码、真实运行结果与核对方法。

Code Library 是什么

本书是一本按问题与方法检索的长期代码库，不是课程讲义的重排，也不是某次直播的笔记。它回答的是实际动手时的五个问题：该调用什么代码、该怎样向 Agent 描述任务、输入和输出是什么、结果如何检查、R 与 Python 之间如何迁移。

全书内容按四层分工维护，每层只放一类东西：

  • 数值结果 → Demo_R_Project/results/tables/（CSV）与 Demo_R_Project/results/book_fragments/（脚本自动生成的摘要片段）；
  • 图片 → Demo_R_Project/results/figures/；
  • 完整代码 → Demo_R_Project/R/ 与 Demo_R_Project/python/；
  • QMD 正文 → 只负责解释、展示关键片段、索引产物、给出核对方法。

由此引出本书最重要的纪律：正文不手抄大表、不复制完整脚本。你在正文看到的每一组关键数字，都能追溯到某个 CSV、某个片段和生成它的脚本；每一段代码摘录，都来自 Demo_R_Project/ 里真实可运行的文件。

重要Demo 的定位

本书全部统计结果由 Demo_R_Project/ 真实运行生成并冻结。Demo 使用 R 内置数据 MASS::Pima.tr2（二分类结局），定位是技术演示：验证本书所述统计契约能被代码严格执行。它不是第三个正式教学 Case，不进入正式教学的结果口径。正式教学数据只有两套：Myocardial Infarction Complication（直播主案例）与 Early Stage Diabetes Risk Prediction（Mini Project），见正式案例目录。

怎么检索

按你手头的任务查下表，直接跳到对应章节；每章末尾的”复用时替换什么”告诉你换成自己的数据要改哪里。

任务 章节 配套脚本 配套 Prompt
数据读取、字典、缺失核查 第2章 Demo_R_Project/R/01_prepare_data.R 01_数据读取与核查
清理、Table 1、固定划分 第2章 Demo_R_Project/R/02_clean_table1_split.R 02_清理Table1与划分
LASSO 筛变量、Logistic 建模、Nomogram 第3章 Demo_R_Project/R/03_lasso_logistic_nomogram.R 03_LASSO与Logistic
内部验证、ROC / 校准 / DCA 第4章 Demo_R_Project/R/04_internal_validation.R 04_完整内部验证
机器学习比较、SHAP、最终测试 第5章 Demo_R_Project/R/05_ml_compare_final_test.R 05_ML比较与最终测试
Python 迁移 第6章 Demo_R_Project/python/01_contract_migration_demo.py 06_Python迁移
调用 Agent 的契约与验收 本章 Demo_R_Project/run_all.R prompts/ 目录

其中 LASSO（Least Absolute Shrinkage and Selection Operator，最小绝对收缩与选择算子）负责筛变量，Logistic 回归负责重拟合出可解释的效应量，ROC（Receiver Operating Characteristic，受试者工作特征曲线）与 AUC（Area Under the Curve，曲线下面积）、校准、DCA（Decision Curve Analysis，决策曲线分析）负责评价——这条主线在第 3、4 章展开。

怎么运行 Demo

Demo_R_Project/ 是一个自包含的 R 项目，run_all.R 是唯一总入口。运行方法（摘自 Demo_R_Project/README.md）：

在 Demo_R_Project 目录下执行
# 从本目录（Demo_R_Project）执行；R 4.5+，依赖包见 R/00_setup.R
Rscript run_all.R

# 每个 R 脚本也可单独从项目根运行（依赖前序脚本已落盘的产物）
Rscript R/04_internal_validation.R

# Python 迁移 Demo 在 R 全流程完成后可独立运行
python python/01_contract_migration_demo.py

run_all.R 按固定顺序执行六个阶段脚本，最后做产物核验并写出运行摘要。阶段定义直接摘自 Demo_R_Project/run_all.R：

run_all.R（摘录：阶段清单）
stages <- file.path("R", c("01_prepare_data.R", "02_clean_table1_split.R",
                           "03_lasso_logistic_nomogram.R", "04_internal_validation.R",
                           "05_ml_compare_final_test.R", "06_export_python_bridge.R"))
timings <- vapply(stages, run_stage, numeric(1))

所有分析参数——种子、结局变量名与正类、训练比例、交叉验证（Cross-Validation, CV）折数、LASSO 选 lambda 的规则、阈值规则——只存在于单一配置源 Demo_R_Project/config/config.R，任何脚本不另存第二份：

config/config.R（摘录）
config <- list(
  project_id     = "pima_demo",
  dataset        = "MASS::Pima.tr2",
  seed           = 20260918L,
  outcome        = "type",
  positive_class = "Yes",
  train_prop     = 0.70,
  outer_folds    = 5L,
  inner_folds    = 5L,
  lasso_lambda   = "lambda.min",
  threshold_rule = "youden"
)

实际运行结果

本书引用的是一次真实运行的冻结产物（Demo_R_Project/results/run_summary.md，R 4.5.2，seed = 20260918）：

  • 样本 n = 300，事件 106（35.3%）；划分 Training 211 / Holdout Test 89，outer 5 折、inner 5 折；
  • 内部验证（Logistic，OOF）AUC = 0.8437（95% CI 0.7921–0.8954，DeLong），Brier = 0.1600；
  • Holdout Test AUC = 0.7442（95% CI 0.6362–0.8521），仅评价一次；
  • 产物计数：artifact_manifest.csv 共 52 条记录且全部 status = ok——图 14 张、表 22 个、模型 4 个、教材片段 7 个、日志 2 份。

这里 OOF 指 out-of-fold（折外）预测：每一折的样本由”不含该折”的流程预测，是第 4 章内部验证的核心。这些数字只是 Demo 的能力证明，各章会用自己的片段展开细节；不要把它们当作任何正式案例的结论。

怎么调用 Agent

本书假设的执行方式是：你描述任务，Coding Agent 写代码并运行，你按契约验收。标准动作只有四步：

  1. 选 Prompt：按任务检索表找到对应章节，打开 prompts/ 里的同名文件；
  2. 替换占位符：把 <数据路径>、<结局变量> 等占位符换成你的实际值（见下文”复用时替换什么”）；
  3. 交给 Agent 执行：Agent 的基础操作见工具手册第 3 章与第 5 章；
  4. 按”验收”节核对：对照 Prompt 里的验收清单逐项检查产物，出错时的处理见工具手册第 6 章。
提示为什么不让 Agent 自由发挥

Prompt 把方法主线钉死（例如”LASSO 只用于筛选、Logistic 必须无惩罚重拟合”、“折内重新学习全部预处理”），Agent 只负责实现与执行。方法决策留在人手里，这正是 Demo 项目契约要点在提示词层面的翻版。

Prompt 契约

每个 Prompt 文件都可以独立复制给 Agent，固定为八个部分，顺序不可换：

  1. 背景：任务在项目流程中的位置与定位声明；
  2. 数据说明：输入文件、字典、结局与正类编码、成员清单等输入契约；
  3. 当前任务：这一阶段要完成什么、不做什么；
  4. 方法：钉死的方法主线与禁止事项；
  5. 输出：必须落盘的文件清单（路径、格式、关键列）；
  6. 约束：统计纪律与工程纪律（只读原始数据、单一配置源等）；
  7. 验收：逐条可核对的检查项；
  8. 暂停条件：命中即停止并报告、等待人工决定的情形。

这八段对应教学实施与分析规范的口径：背景 → 数据说明 → 当前任务 → 方法 → 输出 → 约束 → 验收，先列计划、只执行指定阶段、命中暂停条件才停。每个 Prompt 都逐字包含下面这句执行指令：

先检查输入并给出简要计划，然后继续执行指定任务；不要在计划后等待用户再次确认。只有输入冲突、字典冲突、必须改变方法或命中暂停条件时停止。

也就是说：Agent 先列计划让你看到它要做什么，但不等你二次确认就直接执行；只有输入冲突、数据字典冲突、必须改变方法或命中暂停条件时才停下来报告，由人做决定后再继续。

输入输出如何验收

验收分三层，全部可以机械核对，不依赖”看起来差不多”：

输入验收（执行前）

  • 数据文件、数据字典存在且可读；结局变量与正类编码与说明一致；
  • 若已有划分：成员 ID 在训练与测试间无交叠，fold 成员恰好划分训练集；
  • 分析范围明确（本阶段只用哪部分数据）。

输出验收（执行后）

  • 输出清单中的每个文件存在且非空——Demo 用 artifact_manifest.csv 把 52 个产物逐行登记并核验，全部 status = ok 才算通过；
  • 关键数字可追溯：正文/报告引用的数字能在 CSV 或片段中找到同一值；
  • 运行记录完整：日志与 session 信息已保存（Demo 对应 results/logs/run.log 与 results/logs/sessionInfo.txt）。

纪律验收（统计契约）

  • 测试集未参与筛选、预处理学习、调参与阈值选择；
  • 内部验证的每个 outer fold 内重新学习预处理与变量集合；
  • 锁定产物（选模记录、锁定配置、模型文件）先于任何测试集访问落盘，测试后未返回重选；
  • Python 端直接读取 R 导出的成员与契约，未重新抽样。

这套口径与教学实施与分析规范的交接与验收表一致：接收成果时核对版本、人数、事件编码、成员无交叠与分析范围。

六章如何导航

  1. 本章：使用说明与 Agent 执行契约；
  2. 第2章 R 数据读取、清理、Table 1 与固定划分：数据字典、类型与编码核查、缺失概览、清理日志、Table 1、训练/测试固定划分与 fold 成员清单；
  3. 第3章 LASSO、Logistic 与 Nomogram：仅训练集内的主线建模——LASSO 筛选、映射回原始变量、Logistic 无惩罚重拟合、OR 与置信区间、Nomogram；
  4. 第4章 完整内部验证与评价图：折内独立重学的完整流程验证，OOF 预测上的 ROC、校准与 DCA；
  5. 第5章 机器学习比较、解释与最终测试：Logistic、随机森林（Random Forest, RF）、XGBoost（eXtreme Gradient Boosting）、支持向量机（Support Vector Machine, SVM）同台比较，先锁后测，SHAP（SHapley Additive exPlanations）解释，Holdout Test 一次性评价；
  6. 第6章 Python 迁移与通用片段：Python 直接读取 R 导出的成员与特征契约，记录实现差异，不为对齐 AUC 反复调参。

常见错误

  • 把 Demo 当正式案例：Demo 数字只证明流程可执行，任何正式分析必须用正式案例数据重跑；
  • 让 Agent 重新划分数据：划分与 fold 成员一旦生成即冻结，后续阶段只读 split_manifest.csv / fold_manifest.csv，Python 端同样禁止重新抽样；
  • 用 Table 1 筛变量：描述与筛选分离，Table 1 只做描述；
  • 先全训练集筛变量再做 CV：这是泄漏，内部验证必须折内重选，见第 4 章；
  • 测完不满意再换一个模型：锁定先于测试，测试后不返回选优，见第 5 章；
  • 把 run_summary 的数字手抄进新分析：换新数据后所有数字必须重新运行生成。

复用时替换什么

把本书流程搬到自己的数据时，改动集中在三处：

  • Prompt 占位符：<数据路径>、<结局变量>、<正类>、<训练比例>、<折数> 等，按你的项目填；
  • 配置：Demo 中所有参数集中在 config/config.R，复用时只改这一处，不在脚本里另存第二份种子或折数；
  • 变量与契约：预测变量集合、因子水平与参照、缺失处理规则，按你的数据字典重新定义，并同步写进特征契约。

方法主线（LASSO → 原始变量 → Logistic 重拟合；折内重学；先锁后测；Python 读 manifest）不替换——它是本书要复用的东西本身。

相关资源

  • 课程讲义（Book 1）：概念与判断，对应章节为数据准备、Logistic 建模、模型评价、机器学习与最终评价；
  • 工具手册（Book 2）：Agent 上手与任务交接；
  • prompts/README.md：六个可直接复制的阶段 Prompt 及使用说明；
  • Demo_R_Project/README.md：Demo 的运行方法与统计契约要点；
  • 正式教学案例：Myocardial Infarction Complication 与 Early Stage Diabetes Risk Prediction。