complexa-target

complexa-target

在 Proteina-Complexa 中添加或编辑设计目标。目标位于三个 YAML 文件中，每个 complexa design 流水线对应一个：

• configs/targets/targets_dict.yaml — 蛋白质结合体（默认流水线）
• configs/targets/ligand_targets_dict.yaml — 配体结合体
• configs/design_tasks/ame_dict_v2.yaml — AME / 酶支架设计

complexa target CLI 只管理前两个文件。AME 任务使用扩展架构（与配体目标包含相同的核心字段，另加用于手工整理的逐残基基序原子选择的 contig_atoms），只能通过编辑文件来管理。

首选方式：直接编辑 YAML

complexa target add 是对“加载 YAML → 构建字典 → 追加区块”的简单封装（参见 src/proteinfoundation/cli/target_manager.py:add_target_cli 和 append_target_to_dict）。用于 Agent 时，直接编辑目标字典即可——架构简短，现有条目是很好的复制模板，还能省去 14 个 CLI 标志和 SMILES 的 Shell 转义。只有在明确需要自动添加 YAML 引号或覆盖提示安全机制时，才使用 CLI。

因此，本技能介绍了两种方式：

步骤	直接编辑文件（首选）	CLI
查看现有目标	读取 configs/targets/{,ligand_}targets_dict.yaml（AME 则读取 configs/design_tasks/ame_dict_v2.yaml）	complexa target list（仅限蛋白质 / 配体）
查看单个目标	读取字典并搜索对应键	complexa target show NAME
添加新目标	追加一个 YAML 区块（步骤 3a）	complexa target add ...（步骤 3b）
验证 PDB 是否能在磁盘上解析	— （无快捷方式；此操作会检查 Hydra 默认配置）	complexa validate target CONFIG --target NAME

complexa target 只能读取两个蛋白质类型的字典（targets_dict.yaml 和 ligand_targets_dict.yaml）。AME 任务使用不同的架构，只能通过编辑文件来管理——参见下方的步骤 1。

此技能可实现的功能

• 在 configs/targets/targets_dict.yaml 中注册蛋白质目标（链 + 残基范围 + 热点）。
• 在 configs/targets/ligand_targets_dict.yaml 中注册配体目标（PDB 口袋 + 3 字母代码 + SMILES）。
• 为 AME 流水线确定正确的 AME 任务名称（例如 M0024_1nzy、M0096_1chm）——这些任务不能通过 complexa target add 添加（参见步骤 1）。
• 使用 complexa validate target 验证目标能否解析到磁盘上的真实 PDB。
• 生成可重放的产物（target_definition.yaml），供下游设计运行使用。

步骤 1：确定目标类型

目标位于三个不同的文件中，每个 complexa design 流水线对应一个。先确定用户将运行哪个流水线，再选择相应文件添加条目。每个文件仅供一个流水线使用。

用户意图	流水线	目标字典文件	使用此技能？
结合蛋白质表面（PD-L1、IFNAR2、TNF-α 等）——默认	configs/search_binder_local_pipeline.yaml	configs/targets/targets_dict.yaml	是——步骤 2（蛋白质）
结合小分子口袋（FAD、SAM、OQO 等）	configs/search_ligand_binder_local_pipeline.yaml	configs/targets/ligand_targets_dict.yaml	是——步骤 2（配体）
AME / 酶支架设计（基序 + 配体，名称为 M####_<pdb>）	configs/search_ame_local_pipeline.yaml	configs/design_tasks/ame_dict_v2.yaml	部分——参见下方的“AME 任务”

AME 任务（酶流水线）

情况类似——AME 任务位于 configs/design_tasks/ame_dict_v2.yaml 的 motif_target_dict_cfg: 下，使用各自的架构（source、target_filename、ligand、contig_atoms、binder_length、use_bonds_from_file）。contig_atoms 字符串用于编码逐残基的基序原子选择，例如 "A64: [O, C]; A86: [CB, CA, N, C]; ..."——这些内容由人工整理，因此添加新的 AME 任务需要编辑文件，而不是调用 CLI。浏览该文件，复制一个相似条目作为模板，然后向 complexa design configs/search_ame_local_pipeline.yaml 传入 ++generation.task_name=<NAME>。

第 2 步：收集所需信息

使用 AskUserQuestion 收集信息——不要猜测。蛋白质和配体所需字段不同。

蛋白质靶标

字段	问题	示例	必填
name	“靶标名称（用作 dict 键和 task_name）？”	02_PDL1、MyTarget_v1	是
source	“$DATA_PATH/target_data/ 下的源目录？”	bindcraft_targets、custom_targets	是（或 target_path）
target_filename	“PDB 文件名（不含 .pdb 扩展名）？”	PD-L1、IFNAR2	是（或 target_path）
target_input	“链 + 残基范围——语法请参阅参考内容。”	A1-115、A1-50,B1-50	是
hotspot_residues	“热点残基（界面接触残基）？”	["A33", "A95", "A102"]	可选，建议填写
binder_length	“Binder 长度范围 [min, max] 或单个长度 [length]？”	[80, 150]、[100]	可选（默认 [60, 120]）
pdb_id	“参考 PDB ID（可选，仅用于元数据）？”	"2lag"	可选

配体靶标——包含以上蛋白质字段（不含 target_input），另加：

字段	问题	示例	必填
ligand	“3 字母 PDB 配体残基代码？”	FAD、OQO、SAM	是（此字段存在即表示靶标是配体）
smiles	“配体的 SMILES 字符串？”	"O=C2C3=Nc1cc(c(...)..."	建议填写
ligand_only	“是否仅在配体周围生成结合口袋（不包含蛋白质-蛋白质界面）？”	true / false	可选（默认 true）
use_bonds_from_file	“是否使用输入 PDB/CIF 中的键合信息？”	true / false	可选（默认 true）
target_input	配体靶标不需要	—	否

通过读取 dict（rg '^ NEW_NAME:' configs/targets/targets_dict.yaml）或运行 complexa target list -v --ligand / --protein 检查名称是否冲突。

第 3a 步：直接追加 YAML 块（首选）

打开 configs/targets/targets_dict.yaml（配体靶标则打开 ligand_targets_dict.yaml），找到一个相似的现有条目作为样式模板，并将新块追加到 target_dict_cfg: 下。缩进两个空格，条目之间空一行。

蛋白质模板

  02_PDL1:
    source: bindcraft_targets
    target_filename: PD-L1
    target_input: "A1-115"
    hotspot_residues: ["A37", "A39", "A49", "A98"]
    binder_length: [64, 155]
    pdb_id: "4z18"

遵循现有文件的样式规则（与 complexa target add 生成的内容一致）：

• 为链/残基范围加引号（"A1-115"、"A33"），SMILES 也要加引号——否则流式字符串可能会因 : 和方括号而解析出错。
• 使用流式列表（["A33", "A95"]、[64, 155]）——这是磁盘转储生成的格式。
• 蛋白质靶标必须包含 target_input、source、target_filename。如果 PDB 位于 $DATA_PATH/target_data/ 之外，可以使用 target_path（绝对路径）替代 source + target_filename。

配体模板

  41_7BKC_LIGAND:
    source: ligand_targets
    target_filename: 7BKC_ligand_centered
    hotspot_residues: [null]
    binder_length: [100]
    pdb_id: 7BKC
    ligand: 'FAD'
    ligand_only: True
    SMILES: "O=C2C3=Nc1cc(c(cc1N(C3=NC(=O)N2)CC(O)C(O)C(O)COP(=O)(O)OP(=O)(O)OCC6OC(n5cnc4c(ncnc45)N)C(O)C6O)C)C"
    use_bonds_from_file: True

存在 ligand: 键即会将靶标切换为配体模式——无需单独的 is_ligand 标志。配体不需要 target_input。

保存后，跳到第 4 步进行验证。

第 3b 步：CLI 替代方案（complexa target add）

如果需要 CLI 自动为链/残基加引号、覆盖确认提示，或将靶标创建流程接入非 Python 脚本，请使用 CLI。Agent 使用时优先采用非交互模式（-i / --editor 会打开编辑器并阻塞）。

已确认的标志（来自 src/proteinfoundation/cli/target_cli.py）

标志	类型	适用于	说明
name（位置参数）	str	两者	字典键
--dict PATH	path	两者	覆盖目标字典路径
-i, --interactive	flag	两者	打开 $EDITOR
-e, --editor NAME	str	两者	code、nano、vim、cursor，……
--source NAME	str	两者	$DATA_PATH/target_data/ 下的目录
--target-filename NAME	str	两者	PDB 主文件名（不含 .pdb）
--target-path PATH	str	两者	完整路径；覆盖 source 和 filename
--target-input SPEC	str	蛋白质	链／残基范围，例如 A1-115
--hotspot-residues R [R ...]	list	两者	例如 A33 A95
--binder-length N [N ...]	int list	两者	[min, max] 或 [length]
--pdb-id ID	str	两者	仅用于元数据
--ligand CODE	str	配体	存在此项即表示目标为配体
--ligand-only	flag	配体	仅口袋模式
--smiles STR	str	配体	配体的 SMILES
--use-bonds-from-file	flag	配体	使用 PDB 键
-f, --force	flag	两者	覆盖现有内容，不提示

蛋白质示例

complexa target add 02_PDL1 \
  --source bindcraft_targets \
  --target-filename PD-L1 \
  --target-input A1-115 \
  --hotspot-residues A37 A39 A49 A98 \
  --binder-length 64 155 \
  --pdb-id 4z18

配体示例

complexa target add 41_7BKC_LIGAND \
  --source ligand_targets \
  --target-filename 7BKC_ligand_centered \
  --pdb-id 7BKC \
  --ligand FAD \
  --ligand-only \
  --use-bonds-from-file \
  --smiles "O=C2C3=Nc1cc(c(cc1N(C3=NC(=O)N2)CC(O)C(O)C(O)COP(=O)(O)OP(=O)(O)OCC6OC(n5cnc4c(ncnc45)N)C(O)C6O)C)C" \
  --binder-length 100

默认值说明：--source 默认为 custom_targets（蛋白质）或 ligand_targets（配体），--target-filename 默认为 name，因此当 PDB 主文件名与目标名称不同时，请明确指定。对于配体目标，字典默认设置 ligand_only: true 和 use_bonds_from_file: true——可传入标志以明确指定，也可省略并接受默认值。

第 4 步：验证

按顺序运行两项检查。遇到首个失败时停止并修复。

# 1. Confirm the entry landed and looks right.
#    Direct read works just as well: `rg -A 7 '^  02_PDL1:' configs/targets/targets_dict.yaml`
complexa target show 02_PDL1

# 2. Resolve the PDB path and validate it exists on disk.
#    No shortcut for this — it traverses Hydra defaults to find the target dict.
complexa validate target configs/search_protein_local_pipeline.yaml --target 02_PDL1

complexa validate target（来自 src/proteinfoundation/cli/validate.py::validate_target）会检查：

• 已设置 DATA_PATH，且 target_data/ 存在。
• 目标名称可在 target_dict_cfg 中解析。
• target_path 存在，或者 $DATA_PATH/target_data/<source>/<target_filename>.pdb 存在。
• 返回 target_input、hotspot_residues、binder_length，供人工检查是否合理。

对于配体目标，请将 --target 指向配体流水线配置（例如配体结合剂搜索配置）。

第 5 步：生成产物

在 ./target_<name>/ 下保存一份可重放的记录：

mkdir -p target_02_PDL1
complexa target show 02_PDL1 > target_02_PDL1/target_show.txt

然后使用 Write 工具，将追加的 YAML 片段（complexa target add 在 target_dict_cfg: 下写入的行）写入 target_02_PDL1/target_definition.yaml。这份产物可让用户对比不同运行中的目标定义，并通过 complexa target add ... --force 在另一份检出中重新创建条目。

硬件要求

目标定义无需硬件——这只是编辑 YAML，不涉及训练／推理步骤。磁盘占用仅为追加到目标字典的几 KB 内容（以及 save_targets_dict 自动写入的 .yaml.bak 备份）。

对于使用该目标的后续设计／评估运行，请参照 complexa-design 和 _shared/reference/hardware.md。

故障排除

症状	原因	修复方法
运行 validate target 时提示 Target PDB file: File not found	$DATA_PATH/target_data/ 下不存在 <source>/<target_filename>.pdb	确认 PDB 主文件名和源目录。如果文件位于 target_data/ 之外，请使用 --target-path /full/path.pdb。
"Target 'X' already exists! Overwrite? (y/N)"	字典中存在名称冲突	选择一个新名称，或传入 -f / --force 以覆盖。
PDB 中不存在热点残基	链或残基编号错误	打开 PDB，重新检查链字母（区分大小写）和残基索引。热点采用 <CHAIN><RESNUM> 格式——参见参考资料。
未找到链	target_input 引用了 PDB 中不存在的链	使用 grep "^ATOM" target.pdb | awk '{print $5}' | sort -u 检查 PDB。
PDB 中缺少配体代码	文件中没有作为 HETATM 残基名称出现的 3 个字母的 ligand 代码	打开 PDB 并检查 HETATM 行；你可能需要使用 PDB 的 _ligand_centered 变体。
下游 SMILES 解析失败	SMILES 字符串有误	添加前使用 rdkit.Chem.MolFromSmiles(smiles) 验证。请在 shell 中用引号括住 SMILES，以转义方括号和圆括号。
以数字开头的目标名称导致 Hydra 插值失败	YAML 可以将 02_PDL1 正常视为字符串；某些覆盖语法需要加引号	使用 ++generation.task_name=02_PDL1；如果 shell 会移除字符，请加引号。
配体目标的 target_input 似乎未生效	这是设计如此——配体目标不使用 target_input；口袋由配体定义	配体目标请将其留空。

参考资料

• reference/target_schema.md — 包含所有字段、链规格语法、AME 任务名称语法和 3 个完整示例。
• configs/targets/targets_dict.yaml — 当前的蛋白质条目（可复制一个已验证的条目作为模板）。
• configs/targets/ligand_targets_dict.yaml — 当前的配体条目。
• configs/design_tasks/ame_dict_v2.yaml — AME 任务定义（仅编辑文件，不通过 complexa target CLI 提供）。
• src/proteinfoundation/cli/target_cli.py — argparse 的权威来源。
• src/proteinfoundation/cli/target_manager.py — add_target_cli、list_targets、show_target，以及 TARGET_FIELDS 中的架构。
• src/proteinfoundation/cli/validate.py — validate_target 的实现。