scientific-agent-skills 实战手册：46 个端到端科研工作流示例的提示词工程方法论与安全边界解析

本文基于 scientific-agent-skills 仓库的 docs/examples.md（约 6650 行、36 个学科领域、46 个编号工作流）撰写，系统讲解这套"跨学科技能组合示例"的提示词五原则、统一提示模板与安全门禁设计，并结合仓库中真实存在的技能脚本与参考文档，剖析若干代表性工作流（药物发现、临床药代、实验室硬件 CAD、动物福利评分）的可执行细节与方法学防护。读完后你可以：按文档的骨架把自己的研究任务改写成 Agent 可执行、可审计的提示；理解示例中每个阈值、拆分方式与"负面结果"要求背后防止的具体统计陷阱；并在本地用仓库路径追踪到每个示例所依赖的脚本与参考资料。

一、文档定位：每个技能都必须"在真实工作流里出现一次"

docs/examples.md 的开篇即声明了本文件的组织契约：

• 全技能覆盖：skills/ 目录下的每一个技能都至少出现在一个示例中，且示例中点名的每个技能都真实存在于目录里。文末的 "Complete skill index" 按用途分组列出了全部技能（多数据库检索、化学信息学、基因组学、单细胞、量子、实验室自动化、写作与交付物等二十余个类别），读者可以反向检索：想找一个技能"在真实任务中如何被组合"，直接跳到它所在的工作流。
• 刻意跨学科：每个示例都有一行 Disciplines 标注它实际借用了哪些学科——"药物发现会借用流行病学的生存统计，宏基因组会借用地质学的成分统计，反应器设计会借用实验流体力学的 PIV"。文档认为最有防御力的结果往往来自借用邻近学科的方法。
• 安全与执行声明（原文引用块）：这些工作流是示意性的，必须适配当前 SKILL.md、官方要求、本地策略与用户授权的数据和系统；临床类技能不提供患者级别的诊断、治疗、剂量、分诊或监护；对远端系统的写操作、提交、云作业、采购与物理设备动作，都必须在相应技能的安全门处获得用户或受训操作员的明确授权——规划步骤本身不构成执行许可。

README 在"Quick Examples"与"Use Cases"两处都显式指向该文件（见 README.md），把它作为"从单个技能示例扩展到完整跨领域工作流"的官方入口。

二、提示词五原则：文档方法论的核心

文档 "How to prompt these workflows" 一节是全篇的方法论基石。它开宗明义：下方所有工作流代码块是提示词素材，不是 shell 脚本，其结构本身在做真实的工作。以下五条是"Agent 执行得好"与"执行得含糊"的分界线：

1. 点名你要的技能。技能是按请求与各技能 description 的匹配来选择的。当两个技能可能覆盖同一领域时——文档举了两组例子：phylogenetics 建树、etetoolkit 分析已有树；scanpy 跑分析、anndata 定义格式——直接点名能消除歧义，而不是指望路由器猜对。每个示例把技能清单前置，正是这个原因。
2. 陈述判定标准，而不只是步骤。"过滤一下变异"是欠定的；"保留 QUAL > 30 且 DP > 20，然后报告每个过滤器各删了多少条"才是可执行、可审计的。示例中所有阈值都是占位符，应当替换成针对自己数据有理由的数值——但"写出来的占位符优于没说出口的假设"，因为它摆在那儿可以被质疑。
3. 工作开始前先声明输出契约。Expected Output 块不是事后补的总结，而是提示的一部分。例如提前说清"一张按候选排名的表，每行一个候选，列包含预测 pIC50、其 90% 区间、训练集中最近邻"，是把一个否则会在结尾被草率决定的决策前置。
4. 索要溯源（provenance）与负面结果。检索与推断是两种不同的操作，应当分别标注。要求写明查了哪个库、用什么参数、什么日期，并明确要求分析没找到什么——"只能报告命中的工作流，就只会报告命中"。
5. 把规划与不可逆动作分开。任何写远端系统、花钱、把数据传出本机、移动物理设备的内容，都应放进独立的提示，且在你读完计划之后。多个技能用显式门禁强制这一点；文档建议把这当作模式而非例外。

统一提示模板

五条原则凝练成的提示模板（原文 text 代码块，完整保留以便复制改写）：

Use the <skills> skills. Keep the output organized and save intermediates.

Goal: <one sentence, with the decision the result will inform>
Data: <where it is, what authorization covers it, what may not leave the machine>
Criteria: <thresholds, filters, what counts as a hit, what would falsify the result>
Deliver: <exact artifacts, formats, and the columns/figures they must contain>
Report: <provenance for every retrieved fact; uncertainty for every estimate;
         what you could not determine and why>
Do not: <the irreversible actions reserved for a separate, explicit approval>

模板之后还有两个在长任务中持续受益的习惯：Checkpoint——把中间产物落盘并命名，让第 9 步的失败不损失第 1–8 步；用便宜的、已可信的东西做校验——一个恰好可解的情形、阳性对照、已发表基准、数量级估计——然后再相信昂贵结果。多个示例把这种校验写成了编号步骤（后文 Example 6、Example 11 都有体现）。

三、示例的固定骨架：Objective / Disciplines / Skills Used / 工作流 / Expected Output

46 个示例共用同一结构，便于机器解析与人工套用：

• Objective：一句话说清产出什么、边界在哪（例如"不推断治疗安全性或有效性"）；
• Disciplines：跨学科标注；
• Skills Used：带短描述的具名技能清单；
• Starting prompt：按第二节模板写好的起始提示；
• Workflow：10–13 个编号步骤，其中大量步骤是"反方法学"注释（为什么这么拆、为什么不能那么做）；
• Expected Output：输出契约，即提示中声明过的交付物清单。

文档目录覆盖 36 个领域：药物发现与药物化学、癌症基因组与精准医学、单细胞转录组学、蛋白结构与功能、化学安全与毒理、临床试验分析、代谢组学与系统生物、材料科学与化学、数字病理、实验室自动化与方案设计、临床前体内研究、农业基因组学、神经科学与脑影像、环境微生物、传染病研究、多组学整合、调控基因组学、实验物理、化学工程、流体力学与生物过程、科学插图、量子计算化学、开放量子系统、科研基金写作、流式细胞术、地理空间与对地观测、时间序列预测、云规模生物信息学、功能基因组学与知识图谱、分子建模与模拟、蛋白工程与云端湿实验、医学影像与临床 AI、研究构思与方案规划、文献与知识管理、法规与质量管理、科学传播与工具链。

四、药物发现：Example 1 的 EGFR 抑制剂候选发现

第一个示例展示了最典型的"多技能串联 + 负面结果前置"。目标是为临床前 EGFR 研究找出值得合成的候选小分子短名单，并给出每个候选的证据与失败理由。起始提示的核心句（原文）：

Use the database-lookup, rdkit, datamol, medchem, deepchem, diffdock, and
scientific-writing skills. Keep the output organized and save every intermediate.

Goal: a research-prioritized shortlist of EGFR inhibitor scaffolds worth
synthesizing, with the evidence for each and the reasons it might fail.
Criteria: below. Deliver: a ranked table plus a cited report.
Report: for every predicted value, the model, its held-out error, and the
nearest training-set neighbour by Tanimoto — so I can see what is interpolation
and what is extrapolation. Say plainly which candidates the models cannot score.

10 步工作流中值得展开的方法学决策：

• Step 1（ChEMBL 检索）：按单一、明确声明的 assay 类型与靶点置信度过滤 pChEMBL >= 7，不把 IC50、Ki、Kd 混进同一活性列；并要求记录同一化合物跨实验室常有的 >1 个 log 单位的活性离散——这为任何在该数据上训练的模型设定了性能上界。
• Step 2（SAR 分析）：先做母盐剥离、电荷、互变异构标准化再算描述符；Morgan 指纹（radius=2, 2048 bits）；用 Butina（Tanimoto 距离）聚类并按 Bemis-Murcko 骨架分组——两种视角的信息性分歧本身是有价值的；把活性悬崖（结构近乎相同、效价差距巨大）当 SAR 去解释，而不是当噪声。
• Step 3（COSMIC 耐药突变）：区分机制而不是打包——T790M 是恢复 ATP 亲和力的"守门人"替换，C797S 移除第三代抑制剂共价结合的半胱氨酸；同一化合物系列可以对一个稳健、被另一个击败。
• Step 6（DeepChem 预测）：按 Bemis-Murcko 骨架拆分，绝不随机拆分——随机拆分让近类似物跨越折边界泄漏、虚增表观精度；把留出误差与两个基线比：训练集均值、1-最近邻 Tanimoto 预测器——"赢不了最近邻的模型，就是一张多绕几步的查找表"；适用域之外的类似物标记为 unscored，而不是给一个自信的数。
• Step 7（DiffDock 虚拟筛选）：DiffDock 的置信度分数衡量构象合理性而非结合力，用它分诊，再对存活构象用 GNINA/MM-GBSA 做亲和导向重打分；信任任何新构象之前，先重对接一个共晶配体并测量对实验坐标的 pose RMSD。

Expected Output：10–20 个研究优先级排序的候选、预测活性与 ADMET、对接构象与结合分析、证据可溯源的科学报告。这条示例所依赖的技能（rdkit、datamol、diffdock、deepchem、medchem、uncertainty-and-units 等）在 skills/ 下均有独立目录与 SKILL.md，可在仓库内直接查阅各自的方法学约束。

五、Example 40：从首个人体剂量到可辩护的二期方案（脚本级最细的示例）

"临床试验分析"领域下的 Example 40 是全部示例中唯一给出真实命令行的工作流，值得作为"文档 ↔ 源码可互证"的范本。它把口服小分子从临床前 NOAEL 带到二期方案建议：起始剂量、结构模型、暴露-响应、制剂桥接、相互作用风险——每个决定答案的选择都在看到数据之前写定。文档明确边界："工作流不替人选择剂量；它产出的是临床药理学家与申办方团队做决定所需的分析。"

其 10 个步骤全部映射到仓库中存在的脚本（目录 skills/pkpd-modeling/scripts/）：

步骤	文档给出的命令	仓库对应文件
Step 1 起始剂量	python3 allometry_and_fih.py --fih --noael rat=50,dog=10 --safety-factor 10（激动型免疫调节剂需另算 MABEL 并取较低值）	allometry_and_fih.py
Step 3 NCA	python3 nca.py -i sad.csv --dose 100 --route extravascular --auc-method linup-logdown --blq-rule <prespecified> --lambda-z-points 3	nca.py
Step 4 结构模型比较	python3 fit_compartmental.py -i pooled.csv --dose 500 --route iv-bolus --compare 1cmt,2cmt,3cmt	fit_compartmental.py
Step 5 PopPK 数据检查	python3 check_popk_dataset.py -i nmdata.csv --covariates WT,CRCL,ALB --time-varying WT	check_popk_dataset.py
Step 6 暴露-响应 / C-QTc	python3 exposure_response.py --emax -i er.csv --sigmoid；--cqtc -i qt.csv --cmax 250	exposure_response.py
Step 7 制剂桥接 / 功效	python3 bioequivalence.py -i tablet_vs_solution.csv --design 2x2 --metric AUC	bioequivalence.py
Step 8 ICH M12 DDI	python3 ddi_static.py --basic --ki 0.5 --imax 2.0 --fu 0.05 --dose 0.4	ddi_static.py
Step 9 人群方案模拟	python3 simulate_regimen.py --cl 5 --v 40 --dose 500 --interval 12 --n-doses 10 --simulate 2000 --omega-cl 0.35 --omega-v 0.25 --target-trough 4.0	simulate_regimen.py

文档同时指向了配套资产：分析计划模板 popk-analysis-plan.md 与报告清单 nca-reporting-checklist.md，参考文档 population-pk.md（BLQ M1–M7 规则、协变量建模、可接受性诊断）与 dataset-standards.md（CDISC PC/PP、ADPC/ADPP 数据集标准）。这些路径我在仓库中逐一核实存在。

示例中最有信息量的"嵌入式警示"：

• Step 3：AUCinf 外推超过 20% 时，数字由 lambda_z 拟合而非数据驱动；稳态期可报告指标是 AUC(0-tau) 而非 AUCinf；ng/mL 与 µg/mL 混淆会产生"错 1000 倍且看起来完全合理"的清除率。
• Step 4：AIC、BIC、F 检验会相互矛盾；"Q3 的 RSE 达 98% 就是不可估，无论 AIC 偏好什么"；残差符号非随机说明模型形态错（重加权只会掩盖它），异方差但符号随机说明加权错。
• Step 5：PopPK 数据集里"重要但不会让运行失败"的缺陷——BLQ 被读成真 0、空协变量变 0 kg 患者、缺 II 的 ADDL 不落额外剂量、同时间戳记录按文件行序应用。文档明确该技能只负责数据集检查与计划起草，估计本身交给 NONMEM/nlmixr2/Pharmpy，"它不重实现 NLME"。
• Step 6：若最高暴露只达到估计 Emax 的三分之一，"线性"暴露-响应只是低浓度段；患者随机化到的是剂量而非暴露，暴露-响应在随机试验内部仍是观察性的。
• Step 9：确定性模拟回答的是"典型患者长什么样"，几乎从不是真正的问题；只含个体间变异的达标率估计是乐观的。
• Step 10 的决策门：分析支持剂量决策但不替人做；治疗药物监测（tdm_bayes.py，脚本同样存在于该目录）是另一临床场景，方案调整属于主管临床医生。

Do not 行（原文）：不在看到数字之后再选暴露指标、不宣布生物等效、不替试验选剂量、不给任何患者推荐剂量。

六、Example 43：实验室硬件 CAD——"规划即交付，物理执行在门外"

"实验室自动化"领域的 Example 43 演示了一个不同性质的组合：设计一个要与你未设计的仪器（标准微孔板 + 厂商成像台）双向啮合的可制造零件。技能清单为 lab-hardware-cad、uncertainty-and-units、pylabrobot、opentrons-integration、protocolsio-integration、scientific-schematics、scientific-writing，对应的可执行工具在 skills/lab-hardware-cad/scripts/：check.py、gen.py、snapshot.py、_common.py（均已核实存在）。

工作流的九步中，文档把"检查"设计成了门禁而非建议：

• Step 2（先写接口，再写几何）：每个配合接口记录三件事——尺寸来源（标准 ID / 厂商图纸 / 用户测量）、名义值带公差、预期间隙及理由。查数用 check.py standards --list 和 check.py standards --show slas-microplate-footprint；"绝不凭记忆写接口尺寸——猜错的接口数字是这个工作流最昂贵的失败"。承接标准件的腔体要按该标准件的最大材料条件（名义值加上正公差）加间隙定尺寸，而不是按名义值——按名义值定尺寸的腔体只能容纳合格板的一半。
• Step 4（参数化源码是权威产物）：每个可变尺寸是模块级带单位命名的常量，分 INTERFACE 块（被标准固定、标注 ID）与 DESIGN 块（自由选择）；派生尺寸在函数内计算，让 --param 覆盖真正生效；gen.py 会 import 并运行模型文件，因此只运行本会话编写或可信来源的模型。
• Step 5（生成后过检）：gen.py 输出 STEP（权威）、STL（预览/打印）与 manifest（源码哈希、解析后参数、声明接口、库版本、包围盒/体积/有效性）；check.py facts 必须报告 is_valid: true；制造的门是 check.py interfaces 而非 check.py fit——腔体、孔、槽不出现在外包围盒里，对一个完全正确的载体用 fit 会量到壁外轮廓并误判失败。
• Step 6（看一眼）：数值通过不豁免目检——模型可以满足全部声明接口，但腔体开错面、凸台落在板裙位置。
• Step 7（用单位关闭公差论证）：公差叠加链包含板公差、打印公差、所选聚合物在 assay 温度区间的热膨胀、台面螺栓组不确定性；报告"腔体接受合格板的比例"，而不是 pass/fail。
• Step 8（离线接入自动化层）：把载体作为资源放进 PyLabRobot 台面布局并模拟接触它的动作；"模拟通过不是移动硬件的授权；物理试验需要受训操作员与明确批准"。

该示例与 skills/relsa-severity-assessment/ 这类技能共享同一条仓库级原则（见 AGENTS.md 对技能目录结构与测试位置的约定）：技能目录只交付 Agent 需要的东西，测试放在仓库级 tests/<skill-name>/ 下；例如 tests/pkpd-modeling/ 下带有 test_scripts.py 与两份 CSV 夹具，tests/lab-hardware-cad/ 下同样有 test_scripts.py，与 Example 40、Example 43 演示的脚本一一对应。

七、跨领域复现的方法学防护：文档总结的七类失败

文档 Summary 一节（"Recurring methodological failures these examples guard against"）指出，同一批错误反复出现在互不相干的领域，所以示例逐一点名而不是合并成一张清单：

• 分析单元错误——用细胞代替供体、用图块代替患者、用重叠窗口代替受试者，n 被膨胀、显著性被制造出来（Example 5 明言：跨细胞检验会把 n 从约 20 抬到约 200,000，噪声也能给出 p < 1e-50；Example 11 要求 bootstrap 置信区间在患者层面做，否则 40 位患者的 100,000 张关联裁剪被当成 100,000 个独立样本）。
• 乐观拆分——对含同系系列、空间自相关、重复测量的数据做随机拆分；骨架拆分、空间块拆分、患者拆分、化学族拆分存在的理由就是"随机拆分会说谎"（Example 1 骨架拆分、Example 10 整个化学族留出、Example 11 先按患者拆分再切图块）。
• 把成分数据当绝对量——微生物丰度、细胞类型比例、流式频率；一个组分上升会强制其他全部下降（Example 5 要求 scCODA/propeller/Dirichlet-multinomial/centered-log-ratio 类方法并声明参照种群；Example 42 把区室分数当成分处理）。
• 从其他领域照搬阈值——作物面板里的人类 5e-8 GWAS 阈值、快进化病原体的结核 SNP 截断、B 很小时的 S/√B（Example 13 要求为面板实证推导阈值，说明 5e-8 来自欧洲血统人类基因组约百万个独立检验，作物面板 LD 块更长、有效检验数更少）。
• 坐标与单位的静默失配——基因组 build、chr 前缀、Hartree 对 eV、meV/atom 对 kJ/mol、Web Mercator 面积；"join 成功了，答案是错的"（Example 3 的 Step 0 坐标契约：先记录 assembly/contig 命名/坐标约定，左对齐 indels，核对 REF 等位基因；Example 10 明确 meV/atom、eV/f.u.、kJ/mol 全程区分，"这里一个 96.5 的静默因子会使整个筛选作废"）。
• 把预测当测量——对接分数当结合力、CFD 剪切当实测剪切、序列模型输出当调控功能、SHAP 当机制（Example 7 专门区分：SHAP 高归因说明该子结构驱动了预测，不识别机制，且会归因于仅与训练集化学系列相关的特征；Example 42 要求把每个数值标注为 predicted 而非 measured）。
• Double dipping（重复使用）——先聚类再用定义该簇的基因去检验、在信号区上调切点、推导亚型后在同一队列里检验其生存差异（Example 5 Step 5 明言：簇由同一表达数据定义，空假设按构造被违反，p 值反保守，因此该步的 marker q 值不该作为证据进入结果表）。

同一节的 "How to use these examples" 给出七条使用守则：在契约内修改参数、跨类别组合技能、把工作流当示意并核对当前 API/版本/许可证、替换每一个占位阈值（"它们写下来是为了让你可以与之辩论，不是为了让你继承它们"）、生成可审查输出（源 manifest、claim/evidence 映射、显式假设、草稿标签优先于未支持的就绪声明）、引用并核实来源（标识符、搜索摘要、流畅草稿都不构成来源验证）、保持人类问责。

八、安全门禁与"有界"临床技能：文档的边界语言

贯穿 46 个示例的一致模式，是把"规划 / 本地验证 / 远端写 / 物理执行 / 临床审查 / 受监管决策"保持为不同阶段：

• 临床技能只产有界草稿：Example 3 中 treatment-plans 被显式隔离到"Step 13（独立、下游、临床医生门禁）"——它只格式化与结构校验一位执业者已经做出并提供、验证过的决定记录，"它不会选择、排序、比较或推荐疗法，也不会读证据矩阵然后推断出一个"。clinical-reports 只用于从已验证源事实 manifest 填充、显著标注的草稿结构；clinical-decision-support 仅用于聚合/合成研究的评估与治理。
• 物理与云动作门禁：Example 12 的 Do not 行（原文）："不连接、不指挥、不移动任何仪器。产出协议文件才是交付物；运行它是另一项由操作员门禁的独立决定。"其 Step 8 要求受训操作员核对校准、台面状态、耗材、体积、危害、废弃物、急停/恢复，并明确批准具体协议版本、监督小规模 dry-run 后才决定是否执行。Example 42 的 DeepSpot-M 则叠加了许可证门禁：代码为 PolyForm Noncommercial 1.0.0、权重为 CC-BY-NC-SA-4.0，"确认工作——以及从输出衍生的一切——都是非商业的"。
• 动物福利技能的边界：Example 44（RELSA 严重度评分）在 Step 9 把边界写进报告本身：RELSA 是严重度评估的辅助而非决定性参数；ARIMA 预测不是安乐死决定；KDE 区不是 EU Directive 2010/63/EU 的监管严重度分级；分数脱离其参照集就没有意义；"低估是危险的错误，因为它会削弱关注度、可能拖延决定"。支撑脚本 relsa_score.py、forecast_relsa.py、kde_thresholds.py 与示例队列 example_cohort.csv 均在仓库中可查证。

九、如何在仓库中继续深入

• 以 docs/examples.md 为索引起点：先按你的领域定位 H2 章节，读其 "Skills Used" 清单，再逐个进入 skills/<name>/SKILL.md 查看该技能自身的范围、安全边界与代码示例；
• 验证工作流背后的脚本与夹具：凡带编号命令行（如 Example 40 的 pkpd 系列）都能映射到 skills/<skill>/scripts/ 下同名文件，测试在 tests/<skill>/test_scripts.py，例如 tests/ 目录与技能目录一一对应；
• 了解仓库如何保证"技能 ↔ 测试 ↔ 文档"一致：AGENTS.md 定义了技能目录布局（SKILL.md 必需，references/、scripts/、assets/ 可选且保持一级深度）、"测试绝不出现在 skills/ 下"、以及测试通过显式锚点而非相对遍历定位技能；CONTRIBUTING.md 覆盖同样的内容并说明 PR 流程；
• 适用前提与限制：docs/examples.md 自身声明这些工作流是示意性的——包版本、数据库 API、期刊规则、标准与许可证都会演进，落地前需以当前 SKILL.md、官方文档与本地策略为准；所有数值阈值应替换为对自身数据有论证的取值；所有涉及远端写、采购、物理执行的步骤，均需你在相应安全门处显式授权。

这套示例库的真正价值，不在于 46 条流水线本身，而在于它把"什么样的提示能换来可审计的科研输出"写成了可检查的结构：点名的技能、写明的判据、前置的输出契约、强制的溯源与负面结果、隔离的不可逆动作——以及一个在 36 个领域里反复被点名防堵的错误清单。