| name | compute-molecular-features |
| description | 对已标准化化合物确定性计算受控二维描述符、Morgan/RDKit/MACCS 指纹和数据集质量画像。用于准备分子特征、生成指纹，或检查特征缺失、常数、异常和分布。 |
分子二维特征与数据集质量画像
消费已经通过结构标准化契约的化合物，使用固定版本 RDKit 生成可复验特征。始终区分结构计算、经验描述符、数据集统计、实验测量和模型预测。
执行流程
- 确认输入来自
standardize-chemical-structures JSON，或直接 CSV/JSON 中明确提供 standardized_structure。
- 阅读标准化 Artifact 消费合同。
带
workflow 或 result_fingerprint 的 JSON 必须作为正式 Artifact
独立验证，失败时不得降级为 direct JSON；direct JSON/CSV 不具有正式
standardize provenance。
- 确认计算视图：
- 默认
standardized，保留用户选择的盐型、组分和电荷表示；
- 只有用户明确要求时才用
parent，且必须说明 parent 不是物理样品。
- 在隔离环境安装固定依赖：
python -m pip install -r scripts/requirements.txt
- 运行确定性计算：
python scripts/compute_features.py \
--input standardized-structures.json \
--calculation-view standardized \
--output molecular-features.json \
--csv-matrix molecular-features.csv
- 校验输出：
python scripts/validate_output.py molecular-features.json
- 阅读输入输出与科学边界，向用户报告计算视图、成功/部分/失败数量、缺失值、统计异常、指纹 profile 和人工复核项。
固定首版能力
- RDKit
2025.9.2，不调用模型、数据库或网络；
- 受控二维描述符集
rdkit-2d-core-v1；
- Morgan bit fingerprint：默认 radius 2、2048 bit、启用手性和键类型；
- RDKit topological bit fingerprint：默认 path 1–7、2048 bit、每特征 2 bit；
- RDKit 公共 MACCS 166 keys 兼容表示；
- 每个指纹输出 profile、参数、
on_bits、bit count、density 和确定性哈希；
- 数据集级缺失率、非有限值、常数/近常数、范围、分位数、IQR 异常、重复结构和指纹密度。
上游状态规则
- 上游
rejected、解析失败或标准化失败：保留记录，calculation_status=not_run，不得生成特征。
- 上游
review_required：允许对明确视图生成审计特征，但结果继续为 review_required，并完整传播上游原因。
parent_structure 为空且选择 parent 视图：保留记录并 not_run/review_required。- 非法、空或不可解析的选定结构：不自动修复，不补立体化学，不生成伪特征。
- 描述符异常、NaN 或 Inf：转换为
null，列入 missing_features，结果为 partial/review_required。
与其他化学 Skill 的边界
- 第一个
standardize-chemical-structures 负责解析、标准化、parent、结构 QC 和重复分组；本 Skill 不重复这些规则。
- 第二个
resolve-chemical-identities 负责名称/标识符到候选记录及来源对齐；本 Skill 不联网、不做身份解析。
- 本 Skill 只产出特征和描述性统计，不计算结构间相似度，不设阈值，不做子结构检索、聚类、索引或库治理。
- 第四个
search-and-curate-chemical-libraries 才消费本 Skill 的固定 profile，执行相似性、子结构、聚类和化合物库治理。
强制科学边界
- 二维描述符不是实验测量值。
MolLogP、TPSA、HBD/HBA 等是基于结构规则或经验片段的计算量。- 指纹相同或相近不表示功能、活性、机制、毒性或可合成性相同。
- 数据集画像只描述当前输入，不能自动给出模型适用性结论。
- 盐型与 parent 的特征必须保留为不同计算视图，不得覆盖或解释为同一物理样品。
- 不预测药效、活性、毒性、可合成性、实验安全或临床效果。
- 不训练模型，不生成分子，不做对接、逆合成、知识图谱或真实实验。
- 不输出 API Key、Authorization、Cookie、Token 或其他凭证。
退出码
0：结果已写出且没有 rejected 记录；2：结果已写出，但至少一条记录 rejected；3：依赖、输入或参数错误，未形成有效结果。
退出码仅表示软件流程状态；必须检查逐记录状态、数据画像和人工复核项。
