jinko-protocol

Jinkō Protocol SDK 工作流

使用此技能通过 SDK 进行协议设计。明确区分职责：模型定义治疗方案函数及其输入；协议针对每个组实例化这些输入。

前提条件： 此技能需要已初始化的 jinko-sdk 连接，且 SDK 满足其 metadata.requires_sdk 范围。运行 jinko-sdk-setup 技能（../jinko-sdk-setup/SKILL.md），并且只有在检查通过后才继续。会话代码只能兑换一次，因此在此技能自身的 SDK 进程启动前，请再次调用 get_session_code。如果找不到该技能，请从 novainsilico/jinko-skills 安装。

职责分离

• 协议设计只覆盖组件值，每个组可以使用不同的覆盖值。
• 给药功能在模型级别定义：给药计划参数化、剂量参数化、通过类别参数激活或停用治疗、通过类别参数指定给药途径或给药方式，以及解释这些输入的任何公式。
• 在模型中定义治疗方案函数及其输入组件。
• 在协议中为这些输入赋值，相当于为每个组实例化该函数。
• 如果所需的覆盖键不存在于模型输入中，请先切换到 jinko-model，在那里添加模型组件或给药逻辑。

核心规则

• 有可用模型时，优先使用 client.create_protocol_design(arms, model=model)。
• 如果组数据来自电子表格，请使用 client.create_protocol_design_from_csv(csv_file_path=...)。使用规范的元数据列 arm、control、active 和 weight。平台会将所有其他列映射为覆盖值。此方式不接受 model 参数；如果需要关联模型，请改用 client.create_protocol_design(...)。示例文件见 assets/toy_protocol_arms.csv，SDK 调用见 references/protocol-design.md。
• 尽可能将协议设计关联到模型，这样协议设计就会携带模型快照引用。
• 覆盖项 key 必须指向可用于协议运行的模型输入，例如玩具模型中的 Dose 或 route。
• 可通过 tMax 和 tStep 键为每个组分别覆盖求解时间，示例见 assets/protocol.json。当不同组需要不同的时间范围或输出分辨率时，请使用此方式；例如，一张报告图的时间范围为 7 天、分辨率为每小时一次，而另一张图的时间范围为 56 天、分辨率为每天一次。
• 将公式写作字符串，例如 "1.0"、"iv" 或 "PT24H"，具体取决于目标组件。
• 比较各组时，请包含对照关系；使用 armControl 指定比较组。
• 在现有设计上使用 protocol.arms（get、create、set_control、set_active、set_weight、set_override、delete、compare_overrides）编辑单个组，不要替换原始设计载荷。
• 创建或更新项目条目前，必须取得明确确认，或在脚本中使用 --apply。

项目文件夹管理

• 优先在专用的 Jinkō 文件夹中创建协议设计，而不是放在项目根目录。工作流开始时，请询问或建议文件夹名称，例如 YYYY-MM-DD-<experiment-name>。
• 尽可能复用名称完全匹配的现有文件夹：client.get_folder_by_name(name, exact_match_only=True)。
• 如果文件夹不存在，只能在用户确认后，或脚本使用 --apply 运行时创建。
• 确定一个文件夹对象或文件夹 ID，然后将 folder=folder 传给支持此参数的 SDK 创建调用。

随附资源

• assets/toy_protocol_arms.json：包含三个组、两种给药途径和三个剂量。其中 iv 给药途径在两个组中重复出现。
• assets/toy_protocol_arms.csv：同样的三个组，以 CSV 格式呈现，每个组占一行，可用于 create_protocol_design_from_csv。
• assets/protocol.json：协议组结构的 OpenAPI 模式子集。

SDK 脚本

安装 SDK 后，这些脚本会作为控制台脚本出现在 PATH 中，也可以通过 python -m 按下文所示运行。

• jinko.cli.create_protocol_design：创建包含三个组别的方案设计，可选择关联模型。
• jinko.cli.create_protocol_design_from_csv：根据包含各组别的 CSV 文件创建方案设计。
• jinko.cli.edit_protocol_design_arms：通过 arms 修改器服务，对现有方案设计中的组别和覆盖项执行插入或更新。输入中未提及的组别和覆盖项会保留；如需删除，请显式调用 protocol.arms.delete(...) 或 arm.remove_override(...)。
• jinko.cli.inspect_protocol_design：输出方案内容或简明的组别摘要。

示例：

python -m jinko.cli.create_protocol_design --model-sid cm-...
python -m jinko.cli.create_protocol_design --model-sid cm-... --apply
python -m jinko.cli.create_protocol_design --model-sid cm-... --folder 2026-06-15-regimens --create-folder --apply
python -m jinko.cli.create_protocol_design_from_csv --csv skills/jinko-protocol/assets/toy_protocol_arms.csv --apply
python -m jinko.cli.edit_protocol_design_arms --protocol-design-sid pd-... --arms skills/jinko-protocol/assets/toy_protocol_arms.json --apply
python -m jinko.cli.inspect_protocol_design --protocol-design-sid pd-... --summary

组别结构

每个组别都应包含：

• armName：稳定的组别标识符。
• armOverrides：{ "key": "<model-input-id>", "formula": "<arm-specific-value>" } 条目的列表。
• armIsActive：活动组别通常设为 true。
• armWeight：除非有意使用加权模拟（用于校准），否则通常设为 1。
• armControl：对照组设为 null；与某个对照组进行比较的其他组别则设为该对照组的名称。

默认示例组别：

• iv_low_dose：Dose=1.0，route=iv，无对照组。
• po_mid_dose：Dose=2.0，route=po，以 iv_low_dose 为对照组。
• iv_high_dose：Dose=3.0，route=iv，以 iv_low_dose 为对照组。

参考资料路由

• 阅读 references/protocol-design.md，了解职责划分和 SDK 模式。
• 验证组别载荷结构时，阅读 assets/protocol.json。