接入百度千帆 Token Plan 个人版：完整配置 + 思考档实测矩阵 + 「获取模型」404 的源码修复

[columforge]

TL;DR

把百度千帆 Token Plan 个人版完整接进了 DSH：纯配置层接入 + 全部 11 个模型的「获取模型」/思考档/视觉实测，顺手修了手工声明路由「获取模型」对千帆必 404 的源码问题。社区里还没搜到千帆相关讨论（千帆/qianfan/token plan 均零命中），把完整踩坑记录分享出来。核心结论：千帆的「获取模型」404 是 DSH 通用问题不是千帆专属，已在 master 本地修复并实测；思考档方面 8/11 模型支持真实的 关/开，glm-5.3 系和 ernie-5.5 网关侧不支持任何开关。

一、接入配置（不动源码的部分）

Token Plan 个人版专属端点（与千帆常规服务不同）：

• OpenAI 协议：https://qianfan.baidubce.com/v2/tokenplan/personal（chat 路径 = {baseURL}/chat/completions）
• Anthropic 协议：https://qianfan.baidubce.com/anthropic/tokenplan/personal（DSH 单路由单协议，选 OpenAI 即可）

凭据走 ~/.dsh/.credentials.yaml 的 refs 表（文件有 watch，改完即生效），key 用 Token Plan 专属 API Key：

refs:
  QIANFAN_TOKEN_PLAN_API_KEY: <你的 Token Plan 专属 API Key>

profile patch（cordis.patch.yml 的 llm-pi-ai entry）声明手工路由——完整的 11 模型声明见文末附录，这里给骨架：

- id: llm-pi-ai
  name: "@deepseek-ai/dsh-llm-pi-ai"
  config:
    providers:
      qianfan-token-plan:
        displayName: Qianfan Token Plan
        api: openai-completions
        baseURL: https://qianfan.baidubce.com/v2/tokenplan/personal
        apiKeyEnv: QIANFAN_TOKEN_PLAN_API_KEY
        models:
          # 全部 11 个模型清单见附录；带视觉的三个见下节

可选：把主力路由加进子代理白名单（subagent-model-selection-settings 的 allowedModels）。注意坑：该 policy 在 agent/created 时整份快照 append 进会话，改白名单只对新建会话生效，旧会话永远保持创建时的清单——这是设计不是故障。

实测能力备注：glm-5.3-flash / deepseek-v4.1-flash / deepseek-v4.1-flash-1017 实测可吃 vision（1×1 png base64 data URL 验证）；模型清单接口在 {baseURL}/v1/models（/models 404，见第三节）；ernie 两模型上下文官方未给数，走 DSH 默认 1M/128k。

二、思考强度：网关真实能力矩阵（重点）

千帆网关对「思考控制」的支持非常不统一，逐模型实测（探针 = 固定概率题，对比 usage.completion_tokens_details.reasoning_tokens）：

模型	thinking:{type:'disabled'}	reasoning_effort: low/high	结论
deepseek-v4.1-flash / -1017 / v4-pro / pro-0813 / flash-0731	✅ rt 归零	rt 平坦（无调制）	真实 关/开
glm-5.2 / glm-5.1	✅ rt 归零（709/981 → ABSENT）	—	真实 关/开
ernie-light-dt-1.0	✅ rt 归零	—	真实 关/开
glm-5.3 / glm-5.3-flash	❌ 无视（151→209 噪声区间）	⚠️ 方向反：high 三次采样 rt=4764 一致低于 low 的 105195	无诚实档位可声明
ernie-5.5-flash-preview	❌ 无视（qwen 式 enable_thinking 同样无效）	—	无诚实档位可声明

声明方法（model 级）：

reasoningEfforts:
  off: null      # 必须是 null（无值键），空串会被 resolution 拒绝
  high: high
compat:
  thinkingFormat: deepseek          # 发 thinking:{type:'enabled'/'disabled'}
  supportsReasoningEffort: false    # 必须显式 false！

三个坑：

1. supportsReasoningEffort 必须显式 false。千帆 baseURL 不匹配 pi-ai 的任何厂商特征（detectCompat 全 miss），supportsReasoningEffort 默认 true，会附发网关不解析的 reasoning_effort。关掉后 wire 干净到只剩 thinking:{type}。
2. off 必须写 null 不能写空串：resolution 报 reasoningEfforts.off must not be an empty string；null materialize 后 thinkingLevelMap 键缺席，恰好让 pi-ai 的 off !== null 判定通过、发出 disabled。
3. low/medium/high 在这条 wire 上完全同义（都只发 thinking:{type:'enabled'}），声明出来就是假旋钮——所以只声明 关/开 两档。另外 deepseek 格式下「不选档」默认发 disabled（思考关），和接入前「网关默认思考开」行为不同，介意见仁见智。

三、「获取模型」404：根因与源码修复

根因：手工声明路由（不在 pi-ai 内置 catalog）的模型发现会真实发网络探测，URL 固定拼 {baseURL}/models（packages/llm/llm-pi-ai/src/discovery.ts 的 listingUrl）。千帆把清单放在 {baseURL}/v1/models——chat 路径符合惯例、清单路径偏离——于是探测必 404（... answered 404 就是 discovery 的报错文案）。catalog 路由（zai/deepseek 官方等）从内置目录回答、从不发这个请求，所以只有手工路由踩中。

修复思路：listingUrl → listingUrls 候选序列，OpenAI 协议 404 时回退探测 {baseURL}/v1/models，语义保守：

• base 以 /v1 结尾 → 只探一处（不拼出 /v1/v1/models）
• 非 404（401/403/5xx）→ 立即返回不回退，鉴权/服务端错误语义与报错文案逐字不变
• 被拒拼法的响应体先 cancel 再移动；Anthropic / Gemini / 不支持协议路径零改动

核心 diff（commit bd43492adb，2 文件 +103/−21，含 4 个回归测试）

function listingUrls(baseURL: string, api: string): readonly string[] {
  const base = baseURL.replace(/\/+$/, '')
  if (api === 'google-generative-ai') return [`${base}/models?pageSize=${String(GEMINI_MODEL_LIMIT)}`]
  if (api !== 'anthropic-messages') {
    return base.endsWith('/v1')
      ? [`${base}/models`]
      : [`${base}/models`, `${base}/v1/models`]
  }
  const root = base.endsWith('/v1') ? base.slice(0, -3) : base
  return [`${root}/v1/models?limit=${String(ANTHROPIC_MODEL_LIMIT)}`]
}

discoverModels 侧把单次 fetch 改为按候选循环：response.ok || response.status !== 404 即 break，404 继续、被拒拼法 body.cancel() 后移动；错误路径保持原文案。测试加 4 个回归：回退命中 / 双 404 报错 / /v1 base 单探 / 非 404 不回退；套件 36/36 过，oxlint 干净，lefthook pre-commit 三门禁过。已对真实千帆网关验证：/models 404 → 回退 /v1/models → 11 模型完整返回。

四、值得讨论的两件事

1. 是否把 qianfan-token-plan 收进 pi-ai 内置 catalog？ qwen-token-plan / qwen-token-plan-cn / xiaomi-token-plan-* 已有先例。收录后大家零配置拿到路由（含默认端点/模型/reasoningEfforts），发现也从「网络探测」变「catalog 回答」，本文第三节的 404 对千帆用户直接消失。缺的只是 catalog 数据（模型清单/上下文窗口/成本）——本文附录可当草稿。
2. glm-5.3 的 reasoning_effort 语义：千帆网关接受该参数但方向与 OpenAI 语义相反（high 想得比 low 少，非重叠采样 3/3）。不确定是千帆映射到了自家 thinking budget 还是别的，建议有千帆渠道的伙伴确认——这决定了 glm-5.3/5.3-flash 能不能给出诚实的档位声明。

附录：完整 11 模型声明（可直接粘贴）

providers 路由完整 YAML（视觉/上下文窗口为实测或同系推断，ernie 未给规格走默认）

      qianfan-token-plan:
        displayName: Qianfan Token Plan
        api: openai-completions
        baseURL: https://qianfan.baidubce.com/v2/tokenplan/personal
        apiKeyEnv: QIANFAN_TOKEN_PLAN_API_KEY
        models:
          - id: deepseek-v4.1-flash-1017
            name: DeepSeek V4.1 Flash 1017
            contextWindow: 1000000
            maxTokens: 131072
            input: [text, image]
            reasoningEfforts: { off: null, high: high }
            compat: { thinkingFormat: deepseek, supportsReasoningEffort: false }
          - id: deepseek-v4.1-flash
            name: DeepSeek V4.1 Flash
            contextWindow: 1000000
            maxTokens: 131072
            input: [text, image]
            reasoningEfforts: { off: null, high: high }
            compat: { thinkingFormat: deepseek, supportsReasoningEffort: false }
          - id: deepseek-v4-pro
            name: DeepSeek V4 Pro
            contextWindow: 1000000
            maxTokens: 131072
            input: [text]
            reasoningEfforts: { off: null, high: high }
            compat: { thinkingFormat: deepseek, supportsReasoningEffort: false }
          - id: deepseek-v4-pro-0813
            name: DeepSeek V4 Pro 0813
            contextWindow: 1000000
            maxTokens: 131072
            input: [text]
            reasoningEfforts: { off: null, high: high }
            compat: { thinkingFormat: deepseek, supportsReasoningEffort: false }
          - id: deepseek-v4-flash-0731
            name: DeepSeek V4 Flash 0731
            contextWindow: 1000000
            maxTokens: 131072
            input: [text]
            reasoningEfforts: { off: null, high: high }
            compat: { thinkingFormat: deepseek, supportsReasoningEffort: false }
          - id: glm-5.3
            name: GLM-5.3
            contextWindow: 1000000
            maxTokens: 131072
            input: [text]
          - id: glm-5.3-flash
            name: GLM-5.3 Flash
            contextWindow: 1000000
            maxTokens: 131072
            input: [text, image]
          - id: glm-5.2
            name: GLM-5.2
            contextWindow: 1000000
            maxTokens: 131072
            input: [text]
            reasoningEfforts: { off: null, high: high }
            compat: { thinkingFormat: deepseek, supportsReasoningEffort: false }
          - id: glm-5.1
            name: GLM-5.1
            contextWindow: 1000000
            maxTokens: 131072
            input: [text]
            reasoningEfforts: { off: null, high: high }
            compat: { thinkingFormat: deepseek, supportsReasoningEffort: false }
          - id: ernie-5.5-flash-preview
            name: ERNIE 5.5 Flash Preview
            input: [text]
          - id: ernie-light-dt-1.0
            name: ERNIE Light DT 1.0
            input: [text]
            reasoningEfforts: { off: null, high: high }
            compat: { thinkingFormat: deepseek, supportsReasoningEffort: false }

环境：DSH 0.2.2-rc.2（master e8f7b93a34 + 修复 bd43492adb），pi-ai 1.3.0。欢迎补充其他网关的实测数据。