如何用 jcode provider-doctor 分级诊断 OpenAI-compatible Provider 为何不可用offline/catalog/full【免费下载链接】jcodeThe most RAM efficient harness项目地址: https://gitcode.com/GitHub_Trending/jcod/jcode当你配置了一个 OpenAI-compatible Provider例如 cerebras、fpt、nvidia-nim、comtegra、deepseek、groq、openrouter或其他openai-compatibleprofile之后发现模型选不出来、连接失败、或者模型行为异常问题可能出在三个不同层面jcode 侧的路由接线、API key/端点、或模型本身。jcode provider-doctor就是用来回答这一个问题引自 docs/PROVIDER_DOCTOR.mdWhy isnt my provider/model (or the model picker) working?它会按顺序走一遍严格的全链路检查点catalog、picker、model-switch、chat、streaming、tools对每个检查点给出 PASS/FAIL 输出并在第一个失败点给出一条 next step 提示。命令签名是jcode provider-doctor PROVIDER [--tier TIER] [--json]其中--tier默认值为catalog可以用全局--model标志固定具体模型默认使用该 provider 的默认模型或 live catalog 中的第一个模型。该子命令还有一个别名provider-strict-e2e。准备条件已安装并可用jcodeCLI。catalog和fulltier 需要该 provider 的 API key。按 src/cli/provider_doctor.rs 中的实现key 会从该 provider 配置的环境变量或 env 文件中加载找不到时会报错并提示运行jcode login --provider provider或改用--tier offline只检查接线。offlinetier 不需要 key、不产生费用。fulltier 会发起真实的 chat/streaming/tool 请求会消耗账户余额消耗多少会在运行结束时单独报告见下文。按故障现象选择 Tier三个 tier 的设计意图是便宜地调试必要时再升级Pick how much to exercise... so you can debug cheaply and escalate only when needed。文档给出的对照表Tier需要 key是否消耗余额额外验证内容能抓住的问题offline否否针对合成 catalog 验证 jcode 侧接线该 provider 的 catalog reload、picker 渲染、fallback 标注、model-switch 路由 bugcatalog默认是基本无liveGET /modelskey 错误/缺失、端点失效、模型不在 live catalog 中full是是非流式 chat、streaming、tool-call 循环模型能否真正对话、流式响应、支持 tool calling注意只有fulltier 能挣得严格READY覆盖结论。较轻的 tier 会把依赖 API 的检查点记为 skipped不会在 coverage 台账中过度计分。按你观察到的现象选起点对应文档中的 Typical debugging flow模型 picker 坏了 / 显示错误的模型跑--tier offline。如果picker_live_models、picker_fallback_labeling或model_switch_route失败那是 jcode 侧针对该 provider 的路由 bug应捕获输出并提交 issue。连不上 / 报 auth failed跑--tier catalog。如果auth_credential_loaded或model_catalog_live_endpoint失败问题在 key/端点上运行jcode login --provider provider重新存凭据。能连上但模型行为差跑--tier full。如果non_streaming_chat_completion/streaming_chat_completion/ 各tool_*检查点失败问题在模型本身尝试 live catalog 中的其他模型。执行诊断以 cerebras 为例文档 Quick start 原文命令# 验证 jcode 自身的接线不需要 API key、不花钱 jcode provider-doctor cerebras --tier offline # 验证 key live 模型 catalog需要 key消耗可忽略 jcode provider-doctor cerebras --tier catalog # 完整就绪检查含真实 chat、streaming 和 tool call消耗余额 jcode provider-doctor cerebras --tier full # 固定具体模型并输出 JSON便于脚本/CI jcode provider-doctor cerebras --model gpt-oss-120b --tier full --json把cerebras换成你要诊断的 OpenAI-compatible provider id 即可。如果传入的 id 不是已知的 OpenAI-compatible provider命令会直接报错provider is not a known OpenAI-compatible provider. Run jcode provider-test-coverage to see provider ids, or check your spelling.此时按提示运行jcode provider-test-coverage查看正确的 provider id或检查拼写。读懂输出PASS / FAIL / skip 与 Verdict下面是文档给出的 catalog tier 输出示例文档示例实际运行数值会有差异Provider doctor: Cerebras / gpt-oss-120b Tier: catalog (API key, ~no spend: adds live catalog fetch) ... [ PASS] Credential loaded Loaded credential from CEREBRAS_API_KEY [ PASS] Live model catalog endpoint 2 live model(s) returned [ PASS] Catalog hot reload in current session 2 catalog route(s) reloaded [ PASS] Picker shows live models 2 model(s) in picker, selected gpt-oss-120b [ PASS] Picker fallback labeling all routes backed by live catalog (no static fallback) [ PASS] Model switch route switch request cerebras:... routed via openai-compatible:cerebras [ skip] Non-streaming chat completion catalog tier: requires --tier full (spends balance) ... Verdict: tier catalog passed. Run --tier full to confirm full readiness (spends balance).每行是一个检查点状态含义PASS/FAIL检查点实际执行并成功/失败skip当前 tier 不运行该检查点依赖 API 的那些用--tier full才会跑。Verdict 行有几种形态全严格检查点通过时是Verdict: READY. Every strict checkpoint passed for this provider/model.较轻 tier 通过时提示升级--tier full失败时指出第一个失败检查点、失败原因并附上针对该检查点的下一步提示见下一节。验证方式命令在所选 tier 未全部通过时以非零退出码结束因此可以直接作为 CI/脚本门槛使用。--json会把报告序列化为 JSON顶层字段包括provider_id、provider_label、model、tier、tier_passed、strict_passed、spend和checks每个 check 含checkpoint、label、status、detail方便脚本判断tier_passed/strict_passed。每次运行按顺序报告的检查点完整清单见 docs/PROVIDER_DOCTOR.mdauth_credential_loaded、model_catalog_live_endpoint、catalog_hot_reload_current_session、picker_live_models、picker_fallback_labeling、model_switch_route以及 full tier 的non_streaming_chat_completion、streaming_chat_completion、tool_call_parse、tool_execution_loop、tool_result_followup、real_jcode_tool_smoke。需要说明文档的编号清单共列出 12 个检查点名而 coverage 报告将其渲染为 N/11 阶段本文两处均按文档原文保留。失败后按检查点定位下一步命令自带的 Next 提示来源src/cli/provider_doctor.rs 的next_step_hint与文档 Typical debugging flow首个失败检查点含义与下一步auth_credential_loaded未找到该 provider 的凭据。运行jcode login --provider provider存一个可用的凭据登录流程见 OAUTH.md。model_catalog_live_endpointlive/models调用失败。检查 key、网络与 provider 服务状态。catalog_hot_reload_current_session/picker_live_models/picker_fallback_labeling/model_switch_routejcode 侧针对该 provider 的路由/picker bug。带上本次输出提交 issue。non_streaming_chat_completion/streaming_chat_completion模型没有返回可用的补全。尝试 catalog 中的其他模型。tool_call_parse/tool_execution_loop/tool_result_followup/real_jcode_tool_smoke模型没有产生合法 tool call可能对该能力支持不好。一次 full 运行花多少钱消耗余额的 tiercatalog发一次 catalog 调用full发多次 chat/stream/tool 调用会报告精确消耗。文档给出的示例行文档示例Spend this run: 3 billable API calls, 554 tokens (289 in 265 out), cost not reported by providerbillable API calls实际打到 provider 的请求数tokensprovider 返回usage块时跨请求累加的 prompt completion 总数streaming 探测会请求stream_options.include_usage因此流式调用也被计入cost仅当 provider 返回cost字段时才显示为美元数字许多 provider如 cerebras只返回 tokens你会看到 cost not reported by provider可自行按套餐费率折算。文档给出的参考量级一次完整的 cerebras full 运行约 550–620 tokens约 $0.0003。--json的spend对象包含billable_calls、prompt_tokens、completion_tokens、total_tokens、has_token_data、reported_cost_usd字段。消耗会随运行一起持久化进 coverage 台账因此jcode provider-test-coverage底部会显示累计的 Recorded spend。与 provider-test-coverage 的关系每次 doctor 运行都会向 coverage 台账记录一条 live-verification 事件并打上doctor_tier标签。fulltier 跑通全部严格检查点后该 provider/model 对在jcode provider-test-coverage中翻转为 READY较轻 tier 把依赖 API 的检查点记为 skipped不会给 pair 过度计分。coverage 报告中每个 pair 一行READY 或N/11已通过的阶段数未 READY 的行会给出第一个 blocker 以及推动它越过该 blocker 的确切provider-doctor命令。文档示例文档示例READY cerebras / gpt-oss-120b last tested 9 minutes ago (2026-05-30) by developer (dev build) 6/11 nvidia-nim / gemma-4-31b failed at streaming reply; run jcode provider-doctor nvidia-nim --model gemma-4-31b --tier full; last tested 2 days ago ...行尾还会附带新鲜度说明最近一次运行距现在多久、由哪个构建执行便于判断证据是否过期。限制与适用边界本文描述的诊断路径面向 OpenAI-compatible profile。对 claude、antigravity 等 native-runtime providerprovider-doctor会改走各自的 native 驱动见 src/cli/provider_doctor.rs其检查内容不属于本文范围。只有fulltier 通过才能判定 READYoffline/catalog通过仅代表接线与 key/端点层面就绪依赖 API 的检查点在报告中显示为 skip这是设计行为而非故障。fulltier 有真实花费且需要模型支持对应能力tool 类检查点失败可能只是该模型对 tool calling 支持不好不代表 provider 接线有问题。【免费下载链接】jcodeThe most RAM efficient harness项目地址: https://gitcode.com/GitHub_Trending/jcod/jcode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
