@sema-agent/client-core 0.63.2 → 0.64.0

package/dist/modelCapabilityProbe.js

@@ -0,0 +1,291 @@
+/**
+ * src/modelCapabilityProbe.ts — 一条 OpenAI-completions 车道的模型**会不会思考、关不关得掉**
+ * 的三端公共探测(0.64.0 件①)。
+ *
+ * -- 它答的是哪一问 ---------------------------------------------------------------------------
+ * 一台 vLLM/Qwen 类网关**默认就在思考**,而「关掉」这件事各家拼法不同:有的读顶层
+ * `enable_thinking`,有的只认模板参数 `chat_template_kwargs.enable_thinking`,有的要
+ * `thinking:{type:"disabled"}`。目录条目上那一格 `compat.thinkingFormat` 就是告诉引擎该用哪种
+ * 拼法 —— 而**没有人能靠看一眼型号名答出它是哪一种**。本模块把这一问变成一次可复现的探测:
+ * 发一发最小请求看它思不思考,思考就按序把每一种拼法试一遍,记下第一种真关得掉的。
+ *
+ * -- 🔴 网络那半场不在包里 --------------------------------------------------------------------
+ * 本模块**零 fetch、零 URL、零凭证**:调用方注入一只 {@link ProbeSend},自己去做鉴权与传输,
+ * 只把「答了多长的正文 / 有没有思考通道 / 什么 finish 位 / 什么状态码」交回来。理由与本包
+ * `model/catalogLoader.ts` 的 `CatalogFetchJson` 同一条:三端的凭证轨、代理、超时策略各不相同,
+ * 而**判定**是同一份 —— 判定归包,传输归端。凭证因此一个字节都不会经过本包。
+ *
+ * -- 🔴 方言闭集是**抄件**,不是本包的意见 ---------------------------------------------------
+ * 七个词的属主是引擎:`@sema-agent/core` 的 `dist/engine/llm/types.d.ts` 里
+ * `OpenAICompletionsCompat.thinkingFormat`(7.10.0 = 七词)。而 core **不是本包消费者的依赖**
+ * (既非 peer 也非 runtime dep),`.d.ts` 一旦引用它,装了本包却没装 core 的下游会当场编译不过
+ * ⇒ 与 `engineNoticeCodes.ts` / `autoModeUnavailable.ts` 同一条处置:**按真字节镜像,把代价交给
+ * 门** —— `run-model-capability-probe-test.mjs` 的 A 段对实装 devDep core 双向等值对账,
+ * 上游加一个方言这里当天先红。
+ * ⚠️ **settings-schema 那边取不到这张表,别去那儿找**:`ModelEntry.compat` 在 1.10.0 上是
+ *    **parse-transparent 的 `z.unknown()`**,它的 JSDoc 逐字写着「the SHAPE and the VOCABULARY …
+ *    are the consuming side's single point — this package deliberately does NOT restate that table」。
+ *    那一格刻意不复述词表,所以「从 settings-schema import 闭集」这条路在型面上不存在。
+ *
+ * -- 🔴 试关序是**公面承诺**,不是实现细节 ---------------------------------------------------
+ * 每多试一种拼法就是对那台网关多烧一次真钱与真时延,所以「先试哪一种」必须成文、必须被门钉死
+ * ({@link THINKING_DISABLE_PROBE_ORDER})。排序的理由是观测到的真实序列:一台 Qwen 类网关收到
+ * **顶层** `enable_thinking:false` 时,思考照旧、而正文变空 —— 换成模板参数才真的关掉。把模板形
+ * 排在前面,绝大多数这类网关一发即中。
+ * 🔴 **`openai` 不在试关序里**:它的「关」拼法是 `reasoning_effort:<thinkingLevelMap.off>`,而那张
+ *    映射表是**条目上的声明**,探针手里没有 ⇒ core 在这一形上什么都不写,发出去等于把 baseline
+ *    那一发原样再烧一次。它在本模块里的角色只有一个:关不掉时补一发 `reasoning_effort:"low"`,
+ *    看这台网关**收不收**低档旋钮({@link ModelProbeEvidence.lowEffortAccepted})。
+ * 🔴 **线上同形的两个词不各占一臂**:`zai` 与 `qwen` 铸出的请求体逐字节相同(顶层
+ *    `enable_thinking`),`together` 与 `openrouter` 同理(`reasoning:{enabled:false}`)——
+ *    再烧一次往返证明不了任何新东西。对照表在 {@link THINKING_FORMAT_WIRE_TWINS};铸出的词取
+ *    每对里线上更常见的那一个,而**它们在这条轴上真的可以互换**(不是近似)。
+ */
+/**
+ * 引擎的**思考拼法闭集**(core `OpenAICompletionsCompat.thinkingFormat`,7.10.0 = 七词;
+ * 顺序同源)。🔴 这是一份抄件,不是本包的意见 —— 改它必须同 commit 附 core 坐标,且门会先红。
+
+ * 🔴 形制:`Object.freeze` 的数组,**不是**只在类型面只读的 `readonly T[]` —— 后者一行 `.splice()`
+ *    就能改,而公面消费者拿到的正是这个实例(本仓已定谳的病形,同 `RESUME_RETRY_LATER_CODES`)。
+ */
+export const THINKING_FORMATS = Object.freeze([
+    'openai',
+    'openrouter',
+    'deepseek',
+    'together',
+    'zai',
+    'qwen',
+    'qwen-chat-template',
+]);
+/**
+ * 线上**逐字节同形**的方言对(`键` ⇒ 探针实际会试的那一个)。它们在这条轴上可以互换:
+ * `zai` 与 `qwen` 都写顶层 `enable_thinking`,`together` 与 `openrouter` 都写 `reasoning.enabled`。
+ * ⚠️ 只对**思考开关**这一条轴成立 —— 别把它读成「这两个词处处等价」。
+ */
+export const THINKING_FORMAT_WIRE_TWINS = Object.freeze({
+    zai: 'qwen',
+    together: 'openrouter',
+});
+/**
+ * **试关序**(公面承诺,见模块顶注)。四臂覆盖全部四种线上不同形的关拼法;`openai` 刻意不在其中。
+ * 🔴 顺序承重:模板形排第一,因为观测到的真实序列是「顶层形关不掉且把正文答空、模板形才真关掉」。
+ */
+export const THINKING_DISABLE_PROBE_ORDER = Object.freeze([
+    'qwen-chat-template',
+    'qwen',
+    'deepseek',
+    'openrouter',
+]);
+/**
+ * 一次探测的四个判词。
+ *   · `no_reasoning`   —— 这台网关本来就不思考(一发即知,不再烧往返);
+ *   · `disabled_via`   —— 会思考,而 {@link ModelProbeResult.thinkingFormat} 那一种拼法真关掉了;
+ *   · `cannot_disable` —— 会思考,四种拼法**逐臂给出正面反证**(每一臂都看见思考还开着)⇒ 关不掉;
+ *   · `inconclusive`   —— **问不出来**(baseline 没有证据力,或**任一**试关臂没有证据力)。
+ * 🔴 `cannot_disable` 与 `inconclusive` 的边界是本模块最要紧的一条,而它锚的是**证据力**
+ *    (见 `forceOf`)而不是「有没有被拒」:一臂超时、或一臂答了一条「零思考 + 正文空」的合法空
+ *    回执,那一种拼法都**没被证伪**,唯一诚实的判词是「问不出来」。这一条不是洁癖:
+ *    `cannot_disable` 是 {@link applyProbeToEntry} **删掉**条目上原有 `thinkingFormat` 的唯一触发,
+ *    而那一删是**持久**的。
+ */
+export const MODEL_PROBE_VERDICTS = Object.freeze([
+    'no_reasoning',
+    'disabled_via',
+    'cannot_disable',
+    'inconclusive',
+]);
+/** 固定题面 —— 短、无歧义、任何模型都答得出,且答案长度可判。 */
+export const PROBE_PROMPT = 'Reply with exactly OK';
+/** 输出上限:够答一句 `OK`,又不至于让一台在思考的网关烧掉一整个预算。 */
+export const PROBE_MAX_TOKENS = 64;
+/**
+ * 铸一只探测请求体。
+ * @param entry  被探测的条目(只取 `id`)
+ * @param format 关拼法;缺席 ⇒ baseline(不带任何方言位)
+ * @param opts   `reasoningEffort` = low 档探测那一发(与关拼法互斥使用)
+ *
+ * 🔴 **逐次新对象**:调用方(与门)拿到的每一只都是新的,改一只不会污染下一只。
+ * 🔴 拼法逐字同 core `dist/brain/openai.js` 的 `applyThinking` 关分支;表外词 ⇒ 不写任何方言位
+ *    (**不猜**:一个猜出来的旋钮会让判定去读一台网关根本没被要求过的行为)。
+ */
+export function probeRequestBody(entry, format, opts) {
+    const body = {
+        model: entry.id,
+        messages: [{ role: 'user', content: PROBE_PROMPT }],
+        max_tokens: PROBE_MAX_TOKENS,
+        stream: false,
+    };
+    switch (format) {
+        case 'qwen':
+        case 'zai':
+            body.enable_thinking = false;
+            break;
+        case 'qwen-chat-template':
+            body.chat_template_kwargs = { enable_thinking: false };
+            break;
+        case 'deepseek':
+            body.thinking = { type: 'disabled' };
+            break;
+        case 'openrouter':
+        case 'together':
+            body.reasoning = { enabled: false };
+            break;
+        default:
+            break;
+    }
+    if (opts?.reasoningEffort !== undefined)
+        body.reasoning_effort = opts.reasoningEffort;
+    return body;
+}
+/** 正文里有没有思考开标签(没有 `reasoning_content` 通道的网关把思考写在正文里)。 */
+function sawThinkTagIn(content) {
+    return content.includes('<think>') || content.includes('<thinking>');
+}
+/** 一发的观测(零正文)。`refused` = 抛错或状态码 ≥400。 */
+function observe(r) {
+    const content = typeof r.content === 'string' ? r.content : '';
+    const reasoning = typeof r.reasoningContent === 'string' ? r.reasoningContent : '';
+    return {
+        contentLen: content.length,
+        hasText: content.trim().length > 0,
+        reasoningLen: reasoning.length,
+        sawThinkTag: sawThinkTagIn(content),
+        ...(typeof r.finishReason === 'string' && r.finishReason.length > 0 ? { finishReason: r.finishReason } : {}),
+        ...(typeof r.status === 'number' && Number.isFinite(r.status) ? { status: r.status } : {}),
+        refused: typeof r.status === 'number' && Number.isFinite(r.status) && r.status >= 400,
+    };
+}
+/** 被拒的一发(`send` 抛了)——长度位如实为零,`refused` 为真。 */
+function refusedObservation() {
+    return { contentLen: 0, hasText: false, reasoningLen: 0, sawThinkTag: false, refused: true };
+}
+/** 发一发,把抛错折成一次被拒的观测(🔴 探针答的是一个判词,不是一次崩)。 */
+async function sendOnce(send, body) {
+    try {
+        return observe(await send(body));
+    }
+    catch {
+        // 🔴 刻意不留错误对象:它可能带 URL、请求头、乃至凭证片段([credential-error-path-leak]),
+        //    而本模块的证据面承诺过「可以整只进日志与工单」。归因靠端自己的传输日志。
+        return refusedObservation();
+    }
+}
+function forceOf(o) {
+    if (o.refused)
+        return 'moot';
+    // 思考的正面证据一到手就成立 —— 截断与否都不影响(见上面的 ⚠️)。
+    if (o.reasoningLen > 0 || o.sawThinkTag)
+        return 'on';
+    // 🔴 **正文空 / 纯空白 ⇒ moot,不是 off**:观测到的真实序列里,一台 Qwen 网关收到不认识的顶层
+    //    旋钮时会把思考留着、正文答空;而「零思考 + 正文空」同样出现在一次被截断的应答上。一个把话
+    //    答没了的旋钮不是「关掉了思考」—— 收它进来会让探针假阳,而假阳的代价是条目上落一个错的
+    //    `thinkingFormat`,此后每一次真对话都发一种这台网关不认的拼法。
+    if (!o.hasText)
+        return 'moot';
+    // 🔴 **被截断 ⇒ moot**:`finish_reason: "length"` 说的是「这一发没答完」。本探针的 `max_tokens`
+    //    只有 64,一台在思考的网关很容易先烧完额度再被截掉 —— 那时思考通道可能一个字都没送出来。
+    //    **按开集读**:只认上游明说的这一个词,别的词(含缺席 —— 端没报)一律不当截断,否则不报
+    //    finish 位的宿主会永远拿不到 `off`。
+    if (o.finishReason === 'length')
+        return 'moot';
+    return 'off';
+}
+/**
+ * 探测一个条目:会不会思考、关不关得掉、用哪种拼法关。
+ *
+ * 步骤(每一步都可能是最后一步 —— 能少烧一次往返就少烧一次):
+ *   ① baseline:最小请求,不带任何方言位。
+ *      · **没有证据力**(被拒,或「零思考 + 正文也空」的合法空回执)⇒ `inconclusive`,
+ *        **结果里没有 `reasoning` 这一格**(问不出来 ≠ 不思考);
+ *      · **正面证据**「正文非空且零思考」⇒ `no_reasoning`,收工(不再烧任何往返)。
+ *   ② 按 {@link THINKING_DISABLE_PROBE_ORDER} 逐臂试关,第一个 {@link thinkingIsOff} 成立的
+ *      拼法就是答案 ⇒ `disabled_via`,收工。
+ *   ③ 四臂都没关掉:
+ *      · **每一臂都给出正面反证**(都看见思考还开着)⇒ `cannot_disable`,并补一发
+ *        `reasoning_effort:"low"` 记下这台网关收不收低档旋钮(端据此渲「会思考、当前关不掉;
+ *        席位将按 low 档运行」);
+ *      · **任一臂没有证据力**(被拒,或空回执)⇒ `inconclusive` —— 那一种拼法没被证伪,
+ *        「问不出来」不是「关不掉」。这一形上 `reasoning` 那一格**在场且为真**(baseline 是
+ *        问出来了的),而证据里逐臂留着每一发的长度与状态,端可以据此只重试那一臂。
+ *
+ * @param entry 被探测的条目
+ * @param send  网络端口(端自备鉴权与传输;本包零 fetch)
+ */
+export async function probeModelCapability(entry, send) {
+    const baseline = await sendOnce(send, probeRequestBody(entry));
+    const baseForce = forceOf(baseline);
+    // 🔴 **`moot` 的 baseline 什么都不写**:被拒、或一条「零思考 + 正文空」的合法回执 —— 后者
+    //    (`{content:'', finishReason:'length'}`)修前被判 `no_reasoning` 并把 `reasoning:false`
+    //    写进条目,等于用一次空回执覆盖一份原本正确的能力声明(异源复审 r1 finding② 的真病)。
+    if (baseForce === 'moot') {
+        return { verdict: 'inconclusive', evidence: { baseline, attempts: [] } };
+    }
+    if (baseForce === 'off') {
+        return { reasoning: false, verdict: 'no_reasoning', evidence: { baseline, attempts: [] } };
+    }
+    const attempts = [];
+    const forces = [];
+    for (const format of THINKING_DISABLE_PROBE_ORDER) {
+        const o = await sendOnce(send, probeRequestBody(entry, format));
+        attempts.push({ format, ...o });
+        const f = forceOf(o);
+        forces.push(f);
+        if (f === 'off') {
+            return { reasoning: true, thinkingFormat: format, verdict: 'disabled_via', evidence: { baseline, attempts } };
+        }
+    }
+    // 🔴 「四种拼法都试过、都关不掉」这句话要成立,四臂就得**逐臂给出正面反证**(每一臂都真的看见
+    //    思考还开着)—— 不只是「没被拒」(异源复审 r1 finding① 的两个形):一臂超时,那一种拼法
+    //    压根没被证伪;四臂全是空回执,那四发一个字都没证明。这一条不是洁癖:`cannot_disable` 是
+    //    `applyProbeToEntry` **删掉**条目上原有 `thinkingFormat` 的唯一触发,而那一删是**持久**的
+    //    —— 让一次偶发的超时或空回执去抹掉一份正确配置,是本探针能犯的最贵的错。
+    if (!forces.every((f) => f === 'on')) {
+        return { reasoning: true, verdict: 'inconclusive', evidence: { baseline, attempts } };
+    }
+    const low = await sendOnce(send, probeRequestBody(entry, undefined, { reasoningEffort: 'low' }));
+    return {
+        reasoning: true,
+        verdict: 'cannot_disable',
+        evidence: { baseline, attempts, lowEffortAccepted: !low.refused },
+    };
+}
+/**
+ * 把一次探测的结论落到条目上 —— **纯函数**:入参一个字节不动,返回一只新条目。
+ *
+ * 只写两键:`reasoning` 与 `compat.thinkingFormat`。条目上别的键(`name` / `tier` / `cost` /
+ * `extraBody` / `compat` 里别的位……)逐字原样带过去。
+ *
+ * 🔴 **`inconclusive` ⇒ 原样退回同一只条目**(连拷贝都不做,`===` 成立):问不出来的时候写什么
+ *    都是编。端要渲「这次没探到」就去读 `verdict`。
+ * 🔴 **`cannot_disable` ⇒ 把条目上原有的 `thinkingFormat` 删掉**,而不是留着不管。留着的后果是
+ *    双重的:引擎会继续发一种**已被实测证伪**的拼法,而目录/卡面会照那一格渲一句「思考已关」的
+ *    假话。删的只是那一键 —— `compat` 里别的位一个不动。
+ * 🔴 **`compat` 不是对象时不 spread**(wire 上什么都可能来):铸一只只带 `thinkingFormat` 的
+ *    干净新 `compat`,而不是把一段字符串摊进对象里。
+ */
+export function applyProbeToEntry(entry, result) {
+    if (result.verdict === 'inconclusive')
+        return entry;
+    const compatIn = typeof entry.compat === 'object' && entry.compat !== null && !Array.isArray(entry.compat)
+        ? entry.compat
+        : undefined;
+    if (result.verdict === 'no_reasoning') {
+        return { ...entry, reasoning: false };
+    }
+    if (result.verdict === 'disabled_via' && typeof result.thinkingFormat === 'string') {
+        return { ...entry, reasoning: true, compat: { ...compatIn, thinkingFormat: result.thinkingFormat } };
+    }
+    if (result.verdict === 'cannot_disable') {
+        if (compatIn === undefined)
+            return { ...entry, reasoning: true };
+        // 🔴 **不用 `rest[k] = v` 裸下标**(异源对抗复审 r1 采纳的真病):`compat` 是从配置/wire 来的,
+        //    而 `JSON.parse('{"__proto__":{}}')` 造得出一个**自有** `__proto__` 键 —— 裸下标赋值会命中
+        //    `Object.prototype` 上的 setter:那一键被静默丢掉,**而新对象的原型被换掉**。
+        //    `Object.fromEntries` 走 CreateDataProperty,建的是自有属性,两个后果都不会发生
+        //    (同理,本文件别处的对象展开 `{...}` 也是安全的 —— 出问题的只有下标赋值这一种写法)。
+        const rest = Object.fromEntries(Object.entries(compatIn).filter(([k]) => k !== 'thinkingFormat'));
+        return { ...entry, reasoning: true, compat: rest };
+    }
+    // 表外判词(一个比这一端新的词)⇒ 什么都不写,与 `inconclusive` 同一条纪律。
+    return entry;
+}