用途:把 Jinkō 计算模型导出为 SimBiology 可用的工作簿与设置,在 MATLAB 中按相同配置运行仿真,再与 Jinkō simple_solve 的结果做一致性对比(parity)。
前置条件:需要已初始化的 jinko-sdk 连接,且 SDK 版本满足元数据 requires_sdk 范围。须先运行 jinko-sdk-setup(../jinko-sdk-setup/SKILL.md),其检查通过后再继续。会话码只能兑换一次,调用本技能自身的 SDK 进程前需重新调用 get_session_code;若找不到该技能,从 novainsilico/jinko-skills 安装。
主要方式:流程由技能引导,但确定性的文件处理与对比计算由 scripts/jinko_matlab_parity.py 完成。该脚本属实现细节,不作为需要用户学习的 CLI。
MATLAB MCP 能力门禁:启动 MATLAB、运行 MATLAB 代码或声称 MATLAB/SimBiology MCP 不可用之前,必须显式检查完整的可调用工具注册表,包括可延迟发现的工具;在暴露 ALL_TOOLS 的环境查询 matlab 或 simbiology,否则使用平台工具发现机制。找到可调用的 MATLAB 执行类 MCP 工具即表示服务可用,应使用该 MCP 做检查、执行与取回结果;只有完整检查后无合适 MCP 操作,才使用本地 MATLAB CLI 并简要记录该回退。发现结果不明确时不得继续。
使用流程:只需 CM 短 ID(Jinkō CM 链接亦可,提取其 ID);先导出再询问要对比的输出。在专用运行目录(如 /tmp/jinko-to-matlab/<cm-sid>/)调用导出命令,脚本解包、要求恰好一个工作簿及其匹配的 SimulationSettings_<model_name>.yaml,校验设置并写出 parity-manifest.json(含内容哈希)。访问、导出、清单校验成功后无需重复确认。
复用导入项目:先读 reuse.workbook_unchanged。若有可发现的已保存 .sbproj 且工作簿未变,则复用;每次对比都应用当前导出设置,仅更新设置无需重新导入。若项目不存在、工作簿变化或存在多个候选项目,只问一个简短问题;此时需用户手动在 Model Builder 新建空白模型、删除默认无名 compartment,再用 Home → Model → Import Model Components from Excel 导入并在运行目录保存项目(SimBiology 无 Excel 组件导入 API,故这是唯一强制手动步骤)。不得覆盖提供的 .sbproj,配置与剂量改动仅在内存中进行。
对比选择:用 list-series 命令取得静态时间相关 ID,展示为可选输出,让用户选 1 到 10 个;列表中不含 Time,也不计入数量限制。用户选定后调用 solve 命令,传入精确载荷 ['Time', *selected_ids],Time 大小写敏感且未请求时不返回;须传入 parity-manifest.json,并要求响应包含所有请求序列与 Time。脚本把 Jinkō 返回的秒转换为导出 TimeUnits 并写出 matlab_output_times,用作 MATLAB OutputTimes,不能自行推导均匀网格。
MATLAB 运行:加载已保存项目,解析模型(多模型时询问),使用其活动配置集,应用清单中的 CompileOptions、SolverOptions、SolverType、TimeUnits、StopTime、OutputTimes 等设置。仿真前检查剂量,若有未激活剂量,告知名称并询问本次内存 parity 运行是否激活、保持保存状态或停止,该选择不持久化。运行 sbiosimulate,仅收集选定序列及其单位,写出紧凑的 MATLAB 结果 JSON(含 dose_decision、time.unit、time.values 及每个序列的 id、unit、values),序列 ID 必须与 Jinkō 选定 ID 完全一致。缺失组件或不支持的单位转换属映射失败,不得猜测。
对比与报告:调用 compare 命令,按阿伏伽德罗常数转换 mole/substance_count,转换常见时间单位后对齐;重复的 Jinkō 时间戳保留最后值(事件后状态)用于逐点匹配,再在唯一递增时间上积分;以 abs <= 1e-8 + 1e-6 * abs(jinko) 为诊断阈值报告逐点最大绝对/相对误差与不匹配数;计算梯形 AUC,相对 AUC 误差超过 1% 标为 WARN;参考 AUC 为零时报告绝对 AUC 误差且 AUC 状态为 N/A;任一选定序列参考 AUC 为零则整体状态也为 N/A,不得给出无条件 PASS。以 comparison.md 作为紧凑结果表,AUC 状态为头条,说明逐点不匹配可能来自求解器或事件时间差异;comparison.json 与 comparison.csv 作为运行产物保留。
限制与失败处理:设置、输出 ID 或时间对齐缺失时以具体前置条件停止,不得用推断值继续;要求显式且兼容的单位与有限数值;缺失单位、NaN 或无穷即视为对比输入失败;保持 1 到 10 个输出选择,Time 内部必需;不得修改 Jinkō 模型、求解选项或源项目;无 MATLAB MCP 时仅给出当前项目的最小命令并索取脚本所需的结果 JSON,不建立新的持久用户流程。