用途：把带判断的“往 pi 的 models.json 加模型”操作固化为可复用规程。关键概念是对应 provider——模型实际被托管/调用的 provider，以 baseUrl/api 为准，而非模型厂商（如火山方舟托管 MiniMax/Kimi，参数必须取自托管端点）。
流程：1) 确认目标 pi provider 与模型清单；2) 源定位，读 provider 的 baseUrl+api，用 models-dev-query 查 models.dev 匹配同 api/baseUrl 的 provider，未命中则回退抓官方 API 文档；3) 适配为 pi 的 model 条目，id、name、reasoning、thinkingLevelMap、input（schema 仅接受 text/image）、contextWindow/maxTokens（以官方文档为准，冲突时取官方）、cost（订阅制省略）；4) 思考三层合成：Provider 机制查 api-adapters.md 对应节，模型能力来自源，pi 处理通过 thinkingLevelMap 把 off/minimal/low/medium/high/xhigh/max 七档映射为端点接受值，null 表示不支持，off 语义因 api 而异，勿假设 off=不发；5) Checkpoint 产出 brief 经用户确认后写入并 jq empty 校验。
验证阶段：用 PI_CAPTURE_LOG=/tmp/pi-verify-<provider>.jsonl pi --extension <skill-dir>/scripts/capture.ts --print --model <provider>/<model> 执行 agentic 任务，日志为 JSONL，用 jq 按 assistant 块检查基础链路、思考参数、tool 格式、缓存四个维度；存在问题则回退、调整、重测，上限 3 轮，超限暂停并向用户报告。最后固定：确认无 capture.ts 依赖、jq empty 校验、pi --list-models | grep <provider> 确认可见、删除临时日志并简报。
限制：日志不脱敏（含 system prompt 与 messages），调试后须删除；before_provider_headers 事件拿不到 Authorization。