jinko-model

Jinkō Model SDK 工作流

将此技能用于通过 SDK 进行技术模型构建和编辑。范围仅限 SDK 机制和模型有效性，不涉及生物学合理性。请先通过 jinko-sdk-setup 初始化连接。

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

必需工作流

1. 如果已提供模型，优先编辑该模型，而不是新建模型。仅在需要时才在专用文件夹中通过 client.create_empty_model() 创建模型。

2. 获取模型，并在提出编辑方案前检查其组件、标签、单位、求解选项和诊断信息。使用 model.get_unit_check() 检查单位检查模式。

3. 使用 model.set_unit_check("UnitCheckAndConvertAllSpeciesToExtentUnits") 设置单位检查模式。除非人工明确指示，并在说明后果后要求使用其他模式，否则不得选择其他模式。

4. 为每个直接声明的数值指定单位：数值参数公式、区室体积和物种初始条件。若参数的值由表达式推导得出，则可省略其声明单位，因为表达式已确定单位。使用 references/units_static_info.json 和诊断信息验证非平凡单位。

5. 在认为模型已完成前，添加内置平台标签：

   • 对随虚拟患者变化的输入使用 i::vpop。
   • 对随方案分组或场景变化的输入使用 i::protocol，包括给药事件的剂量、首次给药时间、给药间隔和给药次数。
   • 对每个适用的、带值的输入添加一个有证据支持的来源标签：s::knowledge、s::arbitrary 或 s::to-calibrate。不确定的输入不要添加标签，并报告以供审核。构建模型时绝不要分配 s::calibrated；该标签表示已接受的校准结果。
   • 对重要的、用于绘图或校准的时间序列输出使用 output。

   其中三项决定模型能否在后续流程中使用，因此要检查整个模型，而不只是单个组件。至少一个组件必须带有 output，否则无法绘图、测量或进行校准：将缺少该标签视为错误。没有任何组件带有 i::protocol，意味着无法为模型指定方案分组；没有任何组件带有 i::vpop，意味着模型无法随虚拟患者变化：分别报告为警告，且仅当模型预期为单组且确定性模型时才进行修正。 python -m jinko.cli.validate_model_readiness --model-sid cm-... 默认运行这三项检查。

6. 为每个带有 s::knowledge 标签的带值输入添加可追溯链接。优先顺序如下：保存该值的 Extract、保存该 Extract 的 Reference，然后是任何其他产生该值的项目条目。仅当项目中没有此类条目时，才使用外部 DOI 或 URL，并报告每个外部链接以供审核。使用 jinko-reference 技能将缺失的来源 PDF 上传为 Reference，并创建其 Extracts，然后再添加链接。将它们放在项目文件夹规范规定的 References 文件夹中。

7. 可选地添加科学范围标签，用于模型导航和可视化：

   • 使用 granularity::* 表示生物或空间尺度；标签颜色为 #0cd95e。
   • 使用 phenomenon::* 表示所描述的物理或生物过程；标签颜色为 #f87171。
   • 使用 module::* 表示已实现的机制或子模型；标签颜色为 #66c09c。
   • 使用 readout::* 表示观测层级；标签颜色为 #da1d1d。 使用已确认的组件定义和来源证据。保留现有标签；对于缺乏依据的分类，不要分配标签。这些自定义标签不是就绪要求。请阅读 科学范围标签，了解选择规则以及 QSP、PBPK 和 PK/PD 示例目录。 将所属标签系列的颜色传递给 model.create_tag(..., color=...)；对齐现有声明时使用 tag.set_color(...)。标签系列颜色与图组件类型颜色彼此独立。

8. 使用高级 SDK 方法和 model.components.batch(version="...") 进行相关组件更改。上述平台标签已存在；不要重新创建。仅为其他自定义标签创建声明。

9. 重新获取模型，确认没有错误诊断，并对有代表性的 output 组件运行 simple_solve()。对于事件，验证预期的事件前后变化。

如需查看方法签名，请对客户端返回的对象调用 help()，例如 help(type(model)) 或 help(model.simple_solve)。SDK 没有 jinko.model 模块。

请使用 scripts/create_minimal_model.py，以及 SDK 的 python -m jinko.cli.tag_model_components 和 python -m jinko.cli.validate_model_readiness，不要使用冗长的临时代码片段。脚本默认以试运行模式运行，只有使用 --apply 才会修改内容。

如需进行透明的 ISO 8601 时长转换，请使用 from jinko.iso8601 import Duration，例如 Duration.parse("P1M").to_timedelta()。求解时间接受 timedelta 或 ISO 字符串：model.set_solving_times(t_max=timedelta(days=28), t_step="P1D", additional_periods=[{"t_max": "P7D", "t_step": timedelta(hours=1)}])。

参考文档索引

• 有关组件批处理、标签、事件、公式和代数规则，请阅读 references/model-components.md。
• 有关单位语义和转换行为，请阅读 references/unit_docs.md。
• 有关诊断和就绪检查，请阅读 references/model-validation.md。
• 调用 combine_with 之前，以及读取或解决 model.conflicts 时，请阅读 references/model-combination.md。
• 选择可选的尺度、现象、模块或读出标签时，请阅读 references/scientific-scoped-tags.md。其中包含丰富且可扩展的 QSP、PBPK 和 PK/PD 示例目录。