蛋白位点证据整备
输入一个目标蛋白序列，输出一份能直接拿去做实验的位点表：每个位点改什么、为什么、证据多强、谁验证过、映射是否可靠、哪些维度还缺。
这个技能不设计蛋白，不做结构预测，不算能量。它只做一件事：把散落在比对、文献、模型打分、模拟和参数预测里的位点证据，对齐到同一个坐标系上，并把不能替你决定的地方挑出来问你。
核心主张
计算只能说明"这个位置长什么样"，不能说明"改它有没有用"。真实可用性来自别人已经做过的实验。所以五类证据必须并置，缺哪类就标哪类，不允许用计算结论顶替实验结论。
| 源 | 内容 | 获取方式 | 证据级别上限 |
|---|---|---|---|
| S1 进化 | 列守恒、有效序列数、gap、共识偏离 | 用户提供比对文件 | 推断 |
| S2 他人实验 | 同源酶已发表或专利中的改造记录 | 用户提供数据表 | 已验证 |
| S3 序列设计 | 位点氨基酸概率分布 | 配 SciMiner 调用或用户上传 | 推断 |
| S4 动力学 | 逐残基 RMSF、RMSD、氢键占有率 | 只接受用户上传 | 推断 |
| S5 参数预测 | Kcat、Km、kcat/Km | 用户上传 | 推断 |
S2 是唯一能给出"已验证"的源。其余四类无论多一致，都只能到"推断"。
开工：硬前置与索取
必须同时具备以下三项，缺任一项就停下来索取，不得自行补足：
- 目标序列，单条 FASTA，与后续所有编号基准一致
- 多序列比对，且目标序列本身在比对内
- 同源酶改造数据表，序列 ID 与比对中的 ID 可对应
条件输入，按 D1 至 D3 询问后再决定是否等待：
- 目标结构 PDB 或 mmCIF，用于埋藏与表面的粗略判断
- ProteinMPNN 位点分布表
- MD 逐残基指标表
- Kcat、Km 预测表
禁止用自建比对替代用户提供的比对。 自行检索若干同源序列拼出的比对，样本量、分类学覆盖和对齐参数全都不可控，用它算出的守恒度会被误读成进化结论。缺比对时的标准话术：
> 这份分析需要一份包含你这条序列的多序列比对。没有比对，守恒度、共识偏离、序列加权这些结论全部不成立，只剩结构几何可用。请提供比对文件（aligned FASTA、Clustal、Stockholm 或 a3m 均可），或者告诉我你想先只做结构部分。
编号基准必须显式声明。 每条输入表都要说明编号起点：是否含信号肽、是否含纯化标签、是否是截短构建、是否 1-based。同一份数据里出现两套编号是这类分析最常见的错误来源，见 @references/gotchas.md。
流程
第一步：环境检查
运行 python scripts/check_environment.py --json，按返回状态路由，见「环境检查与路由」。
第二步：比对诊断
python scripts/analyze_msa.py --msa <比对文件> --target <目标序列.fasta> --out <输出目录>
输出 msa_diagnostics.json 与 columns.csv。必须先读诊断，再谈位点。判定门槛：
| 指标 | 可用 | 降级 | 停止 |
|---|---|---|---|
| 有效序列数 n_eff（Henikoff 加权） | ≥ 10 | 5—9 | < 5 |
| 平均两两一致性 | < 0.85 | 0.85—0.95 | > 0.95 |
| 目标序列是否在比对内 | 是 | — | 否 |
| 有效列占比（gap < 50%） | ≥ 0.70 | 0.50—0.70 | < 0.50 |
n_eff 是加权后的有效序列数，不是比对里的行数。20 条序列里有 15 条是同种不同株，n_eff 可能只有 4。用 n_eff 判断，不用行数判断。
目标序列不在比对内时停止，不要手工插入：插入位置差一列，后面所有位点全部错位。让用户重新导出包含目标序列的比对。
第三步：逐位点进化指标
columns.csv 每列给出：列号、gap 占比、加权熵、共识残基、加权共识频次、目标残基、是否偏离共识。
解读规则，按顺序套用：
- 埋藏（邻域残基 ≥ 12）且加权熵 < 0.3：结构与功能必需，默认不动，只在 S2 有明确反证时才考虑
- 表面（邻域残基 < 8）且加权熵 > 0.6：可改，优先看 S2 与 S3
- 目标残基 ≠ 共识且共识频次 ≥ 0.70：共识回复候选。中温酶序列局部次优的主要来源就在这一类
- gap 占比 > 0.30 的列：该位置在同源中长度可变，插入缺失频繁，任何位点结论都要额外标注
共进化不在本技能范围。n_eff 远小于列数时，共进化分析的假阳性率极高，把噪声当耦合关系会直接误导实验。需要共进化时改用专门的 DCA 工具，并保证 n_eff ≥ 5 倍列数。
第四步：他人工作映射
python scripts/merge_evidence.py --msa <比对> --target <序列> --prior-work <数据表> --out <输出目录>
映射按列号走，不按残基编号走。每个突变依次经过：序列 ID 匹配、供体残基号定位、比对列号、目标序列在该列是否为残基、目标残基号。
六种映射状态，逐条写入 mapping_failures.csv，不得静默丢弃：
| 状态 | 含义 | 处理 |
|---|---|---|
| ok | 完整映射到目标位点 | 进入位点表 |
| unmatched_id | 表里的序列 ID 不在比对中 | 报告全部候选近似 ID，等用户确认，不猜 |
| numbering_mismatch | 表里最大突变号与该序列长度不符 | 判定编号基准不同，整行不映射 |
| wt_mismatch | 表里写的野生型与该列实际残基不符 | 判定编号偏移或物种差异，整行不映射 |
| target_gap | 目标序列在该列为 gap | 该位点在目标中不存在，不映射 |
| out_of_range | 突变号超出该序列长度 | 整行不映射 |
同一份表里 ID 大小写、空格、版本后缀不一致是常态。 脚本先精确匹配，再按去空格、忽略大小写、去版本后缀归一化后匹配，仍失败才算 unmatched_id。归一化匹配成功的行要在报告里标出来，因为归一化本身可能引入误配。
第五步：接入其余三源
S3 位点分布：两条路，见 D1。若走 SciMiner，转 protein-design 技能执行，把返回的位点概率整理成本技能要求的字段；若用户上传，校验每个位点 20 种氨基酸概率之和在 1.00 ± 0.02 内，不满足则整位点作废并记录。
S4 动力学指标：校验残基号范围。最大残基号大于目标序列长度，或显著小于长度的 90%，判定编号基准不一致，整表退回。逐残基指标按副本求均值，报告副本数；单副本结果标注"未做重复统计"。
只有动力学指标支持的位点默认不进入候选表。RMSF 高只说明该处在动，不说明该改；需要完整柔性谱时显式加 --include-md-only。
S5 参数预测：校验四件事——参数名、单位、底物、预测器与版本。Km 没有底物标识直接拒收该行，原因见 @references/gotchas.md。不同预测器、不同版本的结果分组输出，不合并、不平均、不换算。
第六步：合流与分级
merge_evidence.py 输出 site_evidence.csv，每位点一行，字段固定：
position, wt, msa_column, gap_frac, entropy, consensus, consensus_freq,
is_deviation, neighbors, exposure, prior_work_hits, prior_work_directions,
prior_work_sources, p_wt, p_best_alt, md_rmsf, kcat_km_direction,
evidence_level, mapping_status, conflict, note
证据分级与冲突判定见「证据分级」。
第七步：走决策点
按 D1 至 D5 逐条检查。命中就停下来问，问法见 @references/decision-rules.md。不许把多个决策点合并成一句"需要补充什么数据吗"。
第八步：出报告
报告结构与验收标准见「输出与验收」。
环境检查与路由
运行 python scripts/check_environment.py --json，四种状态：
| 状态 | 条件 | 动作 |
|---|---|---|
| ready | Python 版本满足，给定文件全部可读且格式可识别 | 直接执行，不讲配置 |
| partial | 核心可用，可选源缺失或不可解析 | 继续，报告标注受影响维度 |
| needs_setup | 必需输入缺失或 Python 版本不足 | 只展示缺失项与获取方式 |
| unavailable | 文件存在但格式无法解析、编码损坏、比对未对齐 | 说明原因与修复方式，不尝试猜测 |
配置齐全时不重复讲配置。SciMiner 属于可选依赖，配不配由用户在 D1 决定，不得自动安装、自动配置或代为注册。
决策点
| 编号 | 触发条件 | 必须问的内容 | 用户不答时的默认 |
|---|---|---|---|
| D1 | 开工前，S3 无从判断 | 位点分布走哪条路：配置 SciMiner 由我调用，还是你上传自己跑的结果 | 跳过 S3，位点表该列留空并标"缺序列设计证据" |
| D2 | 开工前，S4 无从判断 | 有没有 MD 分析结果（RMSF、RMSD、氢键占有率） | 跳过 S4，柔性只能用邻域残基数代理，可信度降一级 |
| D3 | 活性或稳定性维度没有任何定量依据时 | 要不要上传 Kcat、Km 预测数据来补这个维度 | 不追问第二遍，结论标"无定量依据" |
| D4 | 同一位点出现方向相反的证据 | 按实验证据优先，还是保守不动 | 不做裁决，两方并列，冲突列标记 |
| D5 | 任一源解析失败或覆盖率低于 50% | 补数据，还是带缺口出表 | 带缺口出表，逐项标未验证 |
D3 的完整问法：
> 现在活性和稳定性这两个维度没有定量依据，只有结构和进化层面的推断。你之前提到可能有 Kcat、Km 的预测数据——要现在上传吗？如果上传，请一并给出预测器名称与版本、底物、单位。缺这些我没法判断数据能不能横向比较。
证据分级
| 级别 | 判定条件 |
|---|---|
| 已验证 | S2 映射状态为 ok，且该行带实验效应值与条件 |
| 推断 | S1、S3、S4、S5 中至少一源支持，且与已验证证据不冲突 |
| 未验证 | 仅单一计算源支持，且无 S2 对照 |
优先级：已验证 > 推断 > 未验证。但当 S2 来源酶与目标序列一致性低于 0.40 时，该条降为推断——远缘同源上的突变效应不能直接外推。
冲突判四类，全部写入 conflicts.csv：
| 类型 | 条件 |
|---|---|
| direction_conflict | 同一位点，S2 内部效应方向相反 |
| experiment_vs_model | S2 支持改，而 S3 对该位点野生型概率 ≥ 0.50 |
| origin_disagreement | 不同来源酶对同一位点给出相反结论 |
| kcat_km_tradeoff | Kcat 上升而 Km 同时恶化，或反之 |
kcat_km_tradeoff 不作冲突处理，转为提示：该位点应看 kcat/Km 而非单参数。
输出与验收
固定六个文件：msa_diagnostics.json、columns.csv、site_evidence.csv、mapping_failures.csv、conflicts.csv、gaps.csv，加一份 report.md。
报告顺序固定，不得调整：
- 结论可信度：n_eff、平均一致性、有效列占比、目标序列是否在比对内，以及哪些维度缺失
- 位点表：按证据级别排序，已验证在前
- 冲突清单：逐条给出两方证据与原始条件
- 映射失败清单：逐行给出失败原因
- 缺口与下一步：缺什么、补了之后能支撑什么结论
验收标准，逐条可判定：
- 每个位点都有证据级别和映射状态，无空值
conflicts.csv覆盖全部四类冲突，条数与位点表一致mapping_failures.csv行数等于输入表行数减去成功映射行数- 报告开头出现全部降级项，且与
msa_diagnostics.json一致 - 提到"保守"时必须同时给出 n_eff 与平均一致性，不得单独使用
- 任何 S5 数据都不得出现在"已验证"行
交棒
需要位点饱和打分或序列重设计时，转 protein-design 技能：
- 蛋白单体、无配体：ProteinMPNN
- 有配体或需要固定侧链：LigandMPNN
- 需要骨架重设计：不属于本技能产出范围，转 RFdiffusion 系列
交棒时把 site_evidence.csv 的位点清单与 msa_diagnostics.json 一起带过去，位点分布的解读必须结合 n_eff，否则会被误当成独立证据。
边界
不做：
- 不自行检索同源序列拼比对
- 不按残基编号直接套用他人突变
- 不把 n_eff 低于 10 的守恒度写成保守性结论
- 不算 ΔΔG、不跑 MD、不做结构预测、不调结构生成模型
- 不把预测值升为已验证
- 不自动配置 SciMiner 或安装任何包
- 不修改用户原始文件
遇到以下情况停止：
- 比对未对齐或行长度不等
- 目标序列不在比对内且用户无法重新导出
- S2 全部行映射失败
- 用户要求跳过比对直接给位点
自查清单
出报告前逐项确认：
- 目标序列编号与所有输入表的编号基准一致，且已在报告中声明
- 比对诊断的每一项降级都写进了报告开头
- 映射失败行全部有原因，没有静默丢弃
- 冲突位点两方证据都保留了原始条件，没有取平均
- S5 数据全部标为推断
- 报告里没有出现无 n_eff 支撑的"保守"表述
- 补数据建议具体到文件名和字段，不是"提供更多数据"
