AI 自动化分析
概述
ivdtools-analysis是面向体外诊断（IVD）评价数据的人工智能分析
Skill（当前版本 0.1.0）。它以 R 包ivdtools为统计引擎，从
CSV、TSV、Excel 或 RDS 数据出发，完成数据质量检查、统计分析，
并生成可复现的中文 HTML 报告、R 代码、结果表和图形。它适用于 Claude
Code（/ivdtools-analysis） 与 OpenAI
Codex（$ivdtools-analysis）等对话式代理环境。
边界声明：本 Skill
用于统计分析和证据整理，不代表临床验证、产品放行或监管批准。涉及临床、
监管或放行决策时，应由合适的专业人员独立复核。
在对话中使用 Skill
的价值不是"替代统计判断"，而是把重复的技术步骤标准化：数据预检、参数确认、
统计计算、结果核验与中文报告生成按固定工作流执行，并把数据来源、参数、排除记录、警告、结果表、
图形与软件环境一起保存，降低遗漏和手工复制错误的风险。
适用的分析任务
Skill 覆盖 10 类分析任务，均以ivdtools的对应模块为统计引擎：
分析类别 典型任务
方法学比对 描述统计、相关、OLS/WLS/Deming/加权
Deming/Passing–Bablok、Bland–Altman、医学决定水平偏倚
ROC 分析 单/多指标 ROC、AUC、截断值、灵敏度/特异度、多变量 Logistic
定性一致性 2×2 表、灵敏度/特异度/预测值、总符合率、Kappa、McNemar
精密度 方差分量、SD/CV、置信区间、剖面结果
分析灵敏度 sadler拟合、空白限/检出限/定量限建立
参考区间 百分位法、参数法、稳健法及其置信区间
稳定性 条件趋势、试验/参考比较、稳定时间、MKT、Arrhenius、稳定性设计
质量控制 Levey–Jennings 图、Westgard 规则违反识别
方程拟合 方程检索、非线性/加权拟合、模型比较、残差诊断
数据检查 离群值候选、正态性检验、瓶间 ANOVA、Youden 图
样本量 Bland–Altman、比例检验、比例置信区间、稳定性设计样本量
标准工作流
Skill 的分析遵循固定流程，输出目录结构固定，便于核验与追溯。
创建独立输出目录
默认目录名为<输入文件名>-ivdtools-analysis-YYYYMMDD-HHMMSS，位于
Skill 目录之外，且不覆盖 已有目录。原始数据始终保持只读，不作改写。
数据预检
用inspect_data.R生成数据检查 JSON：
Rscript scripts/inspect_data.R\--input/data/example.csv\--encodingUTF-8\--output/output/data-inspection.json预检报告行列数、重复行/列名、每列类型与缺失比例、唯一值数、候选二分类字段与候选
ID 字段、 类别水平与数值范围，帮助在分析前发现数据质量问题。
确定分析方案
根据研究目的选择分析类型，并确认不能从数据安全推导的参数。Skill
不会自行编造临床截断值、
允许偏倚、稳定性限值或接受标准；若这些参数影响结论且无法从数据或方案安全推导，会请求用户确认。
执行分析并渲染报告
Skill 把assets/report-template.Rmd复制到输出目录，创建带显式参数与ivdtools::命名空间调用 的analysis.R完成分析，再渲染中文 HTML
报告。渲染过程保留警告与消息，不静默屏蔽。
核验结果
交付前核验输入总行数与各步排除行数能否对应、缺失/非数值/重复记录是否已报告、阳性类别与方向是否
正确、模型是否收敛、HTML 数值是否与results/*.csv一致、是否记录了sessionInfo()与实际包版本。
输出内容
标准交付目录包含：
analysis.R # 可复用的分析代码 report.Rmd # 报告源文件 report.html # 中文 HTML 报告 analysis-manifest.json # 数据来源、参数和产物清单 session-info.txt # R 环境和包版本 results/*.csv # 机器可读的结果表 figures/*.png # 分析图形中文报告至少包含分析目的、数据来源、数据质量发现、方法和参数、结果表、图形、排除与警告、结果解释、
局限性和可复现性信息。
安装与使用
运行环境
R ≥ 4.1.0、对应版本的ivdtools、Pandoc，以及ggplot2、VCA、VFP、rmarkdown、knitr等依赖包。先运行环境检查：
Rscript scripts/check_environment.R输出STATUS: READY表示就绪；否则列出缺失项。安装/补齐依赖写入 R
库，只能在用户明确授权后执行
（Rscript scripts/install_ivdtools.R --yes）。
在 Claude Code 中使用
Skill 已注册为可调用技能，在对话中直接调用：
/ivdtools-analysis 分析 /data/method_comparison.xlsx 的 Results 工作表。 样本 ID 为 sample_id，候选方法为 candidate，参考方法为 reference。 按研究方案进行 Deming 回归（lambda=1）与差值型 Bland–Altman 分析， 置信水平 95%，输出可复现的中文 HTML 报告。在 OpenAI Codex 中使用
在对话中点名$ivdtools-analysis，并附上数据与分析要求：
请使用 $ivdtools-analysis 分析 /data/roc.csv。 sample_id 是样本 ID，truth 是二分类参考结果，其中 positive 为阳性； marker1 和 marker2 是待评价指标。请输出 AUC、截断值、敏感度、 特异度、ROC 图和中文 HTML 报告。数据选出的截断值只作探索性结果。提交任务时建议说明
- 数据文件路径（Excel 工作簿还应指定工作表）；
- 分析目的与研究设计；
- 样本 ID、候选/参考方法、结局、时间、批号等字段对应关系；
- 阳性类别、方向、配对/重复结构、精密度设计公式；
- 置信水平、效能、统计方法及方案规定的参数；
- 医学决定水平、允许偏倚、稳定性限值、QC 目标均值/SD 等接受标准。
数据处理原则
- 保留原始列名，不自动调用
make.names()改名； - 不默认填补缺失值、删除离群值、平均重复测量或反转结局方向；
- 离群值检验只产生待复核的候选记录，不构成自动删除依据；
- 对排除记录保留依据，并在适用时报告包含/不包含的敏感性分析；
- 任何数据转换、排除、聚合与事后分析选择都说明操作与理由；
- 统计显著不等于临床可接受，只能依据方案或用户提供的接受限得出可接受性结论。
常见问题
- 版本不符：环境检查提示
ivdtools
版本不符时，不要直接覆盖已安装的新版；选择新的可写 R 库，
授权后将目标版本安装到该目录，并用--library检查。 - Excel 无法预检：确认已安装
readxl；多工作表时用--sheet
明确选择。 - HTML 无法渲染：确认
rmarkdown、knitr已安装且rmarkdown::pandoc_available()为TRUE； 查看report.Rmd
中记录的实际警告或错误，不静默忽略。 - 二分类方向反了：检查阳性类别、因子水平、指标方向及试验/参考映射，在重新分析前记录更改方向
与理由。 - 有离群值或重复测量：不自动删除或平均，先按原始记录、实验设计与预设规则确定处理方式。
