dsh-tap 0.20.0

package/core/json-store.js

@@ -0,0 +1,91 @@
+/**
+ * core/json-store.js — provider-agnostic JSON file persistence and
+ * environment/credentials-file key resolution.
+ *
+ * Extracted from index.js during the core/providers split. Nothing in this
+ * file knows anything about any specific upstream gateway.
+ */
+
+import { readFileSync, writeFileSync, renameSync, unlinkSync, mkdirSync, existsSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+/** Read a JSON object file; missing/corrupt/non-object all yield {}. */
+export function readJson(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'))
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * Atomic file write: tmp sibling + rename, so a crash mid-write never leaves
+ * a truncated file behind. Truncation is worse than a clean failure here —
+ * a truncated settings.yaml often stays VALID yaml and silently drops config,
+ * and a truncated JSON token store reads back as {} (tokens/keys gone).
+ * Every write lands a fresh inode, so `mode` reliably applies (credentials
+ * and token stores pass 0600 — same discipline as the dsh credentials file).
+ */
+export function writeTextAtomic(path, text, mode) {
+  mkdirSync(dirname(path), { recursive: true })
+  const tmp = `${path}.${process.pid}.tmp`
+  try {
+    writeFileSync(tmp, text, mode ? { mode } : undefined)
+    renameSync(tmp, path)
+  } catch (err) {
+    try {
+      unlinkSync(tmp)
+    } catch {
+      // tmp never created (e.g. mkdir failed) — nothing to sweep
+    }
+    throw err
+  }
+}
+
+/**
+ * Write a JSON object file (pretty, trailing newline) atomically.
+ * These files carry credentials/tokens, so they are written 0600.
+ */
+export function writeJson(path, value) {
+  writeTextAtomic(path, JSON.stringify(value, null, 2) + '\n', 0o600)
+}
+
+/**
+ * Resolve a named secret: process environment first, then a flat YAML-ish
+ * credentials file (`NAME: value` per line — the ~/.dsh/.credentials.yaml
+ * shape dsh uses). Returns null when neither source has it.
+ *
+ * The file is scanned with string operations, NOT a RegExp built from
+ * `envName`: the name is settings-configurable free text, and interpolating
+ * it into a pattern would let a crafted name (regex metachar payloads)
+ * rewrite what the match accepts. Line-wise parsing keeps the exact
+ * previous semantics: a line whose pre-colon part equals envName, with an
+ * optional single quote stripped from either end of the value.
+ *
+ * @param {string|undefined} envName settings-configured reference name
+ * @param {string} credFilePath absolute path of the credentials file
+ */
+export function resolveEnvKey(envName, credFilePath) {
+  if (envName && process.env[envName]) return process.env[envName]
+  if (envName && existsSync(credFilePath)) {
+    for (const line of readFileSync(credFilePath, 'utf8').split(/\r?\n/)) {
+      const trimmed = line.trim()
+      const colon = trimmed.indexOf(':')
+      if (colon <= 0) continue
+      // No trim on the name part: the old pattern required envName
+      // immediately followed by ':'.
+      if (trimmed.slice(0, colon) !== envName) continue
+      let value = trimmed.slice(colon + 1).trim()
+      // Same optional single-quote stripping the old pattern accepted
+      // (asymmetric quotes included), then the same character class:
+      // no whitespace, no quotes inside the value.
+      if (value.length >= 2 && (value[0] === '"' || value[0] === "'")) value = value.slice(1)
+      if (value.length >= 1 && (value.endsWith('"') || value.endsWith("'"))) {
+        value = value.slice(0, -1)
+      }
+      if (value && !/[\s"']/.test(value)) return value
+    }
+  }
+  return null
+}

package/core/rotation.js

@@ -0,0 +1,108 @@
+/**
+ * core/rotation.js — provider-agnostic multi-credential rotation engine.
+ *
+ * Policy: requests round-robin across the key list; a key that answers a
+ * failover status (401/403/429/5xx) or drops the connection is
+ * cooled for cooldownMs, then rejoins on its own. Cooling keys are appended
+ * as last resort when every fresh key is unavailable.
+ *
+ * INSTANCE state (cooldown map + round-robin cursor) lives on the KeyRotator
+ * object, NOT on the module — the composition root creates one instance per
+ * plugin module instance, so test harnesses that import the plugin twice
+ * (scripts/verify-rotation.mjs ?case=provider / ?case=bridge) keep the same
+ * isolation the old module-global state provided.
+ *
+ * Extracted from index.js during the core/providers split. This file knows
+ * nothing about any specific upstream: the "no credential" error for the
+ * empty-candidate case is injected by the caller (`emptyError`).
+ */
+
+/** Statuses that fail a request over to the next key. */
+function isFailoverStatus(status) {
+  return status === 401 || status === 403 || status === 429 || status >= 500
+}
+
+export class KeyRotator {
+  constructor() {
+    /** keyName → cooldown-until epoch ms. */
+    this.cooldowns = new Map()
+    /** Round-robin cursor (advanced once per ordered() call). */
+    this.cursor = 0
+  }
+
+  markCooling(name, cooldownMs) {
+    this.cooldowns.set(name, Date.now() + cooldownMs)
+  }
+
+  /**
+   * Order key entries for one outbound call: every key exactly once,
+   * non-cooling first in round-robin order, cooling keys appended as last
+   * resort. 0/1-key cases are handled by the caller (no rotation state is
+   * touched for them — the cursor must not advance).
+   *
+   * @param {Array<{name: string, key: string}>} keys
+   * @returns {Array<{authorization: string, headers: {}, keyName: string}>}
+   */
+  ordered(keys) {
+    const now = Date.now()
+    const n = keys.length
+    const start = this.cursor % n
+    this.cursor = (this.cursor + 1) % n
+    const rotated = Array.from({ length: n }, (_, i) => keys[(start + i) % n])
+    const fresh = rotated.filter((k) => (this.cooldowns.get(k.name) ?? 0) <= now)
+    const cooling = rotated.filter((k) => (this.cooldowns.get(k.name) ?? 0) > now)
+    return [...fresh, ...cooling].map((k) => ({
+      authorization: `Bearer ${k.key}`,
+      headers: {},
+      keyName: k.name,
+    }))
+  }
+
+  /**
+   * Run `attempt(cred)` over the candidates with failover: a candidate that
+   * throws a network error or answers a failover status is cooled and the
+   * next candidate takes over. The LAST candidate's response/error is
+   * returned as-is (no retry). `attempt(cred)` must return the fetch
+   * Response (body unconsumed on error statuses — it is cancelled before
+   * failing over) or throw.
+   *
+   * Resolves { cred, res, err }: exactly one of res/err is set.
+   *
+   * @param {Array<{authorization: string, headers: Record<string,string>, keyName: string|null}>} candidates
+   * @param {(cred: object) => Promise<Response>} attempt
+   * @param {{ cooldownMs: number, emptyError: Error }} options
+   */
+  async run(candidates, attempt, { cooldownMs, emptyError }) {
+    if (candidates.length === 0) return { cred: null, res: null, err: emptyError }
+    let lastErr = null
+    for (let i = 0; i < candidates.length; i++) {
+      const cred = candidates[i]
+      const isLast = i === candidates.length - 1
+      let res
+      try {
+        res = await attempt(cred)
+      } catch (err) {
+        // Caller-side aborts are not the key's fault: no cooldown, no failover.
+        // The bridge marks a client hangup with err.clientDisconnected; an
+        // upstream first-byte timeout (peer connects but never sends headers)
+        // is also an AbortError but is NOT caller-side — it must cool the key
+        // and fail over, or every key burns its timeout budget in sequence
+        // against a wedged edge. Only clientDisconnected aborts are exempt.
+        if (err?.name === 'AbortError' && err?.clientDisconnected === true) return { cred, res: null, err }
+        // Network-layer failure: cool the key and fail over (unless last).
+        if (cred.keyName) this.markCooling(cred.keyName, cooldownMs)
+        lastErr = err
+        if (isLast) return { cred, res: null, err }
+        continue
+      }
+      if (!isLast && isFailoverStatus(res.status)) {
+        if (cred.keyName) this.markCooling(cred.keyName, cooldownMs)
+        await res.body?.cancel().catch(() => {})
+        lastErr = null
+        continue
+      }
+      return { cred, res, err: null }
+    }
+    return { cred: null, res: null, err: lastErr }
+  }
+}

package/core/usage-meter.js

@@ -0,0 +1,176 @@
+/**
+ * core/usage-meter.js — provider-agnostic usage metering store.
+ *
+ * The upstream reports per-request billing on every chat SSE stream; the
+ * bridge scans for it ALWAYS and accumulates into a JSON file so a settings
+ * card can show live consumption. Tokens/credits only — never message
+ * content. Metering must never break the data path: every failure is
+ * swallowed, writes debounced.
+ *
+ * The recorded usage contract is the OpenAI-style SSE usage object plus an
+ * optional provider `credit` cost field:
+ *   { prompt_tokens, prompt_cache_hit_tokens, prompt_cache_miss_tokens,
+ *     completion_tokens, credit }
+ * Providers whose usage objects lack a field simply record 0 for it.
+ *
+ * Extracted from index.js during the core/providers split. Instance state
+ * lives on the meter object (created once per plugin module instance by the
+ * composition root) — not on this module.
+ */
+
+import { readJson, writeJson } from './json-store.js'
+
+const USAGE_RECENT_CAP = 100
+const USAGE_DAYS_CAP = 31
+const USAGE_FLUSH_MS = 5000
+/** Two requests further apart than this belong to different (approximate) turns. */
+const TURN_GAP_MS = 45_000
+
+/** Local-day key (YYYY-MM-DD) — the display groups by the user's day. */
+function dayKey(ts) {
+  const d = new Date(ts)
+  const mm = String(d.getMonth() + 1).padStart(2, '0')
+  const dd = String(d.getDate()).padStart(2, '0')
+  return `${d.getFullYear()}-${mm}-${dd}`
+}
+
+function normalizeUsageStore(raw) {
+  const store = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {}
+  store.since = typeof store.since === 'number' ? store.since : Date.now()
+  store.totalCredit = typeof store.totalCredit === 'number' ? store.totalCredit : 0
+  store.totalRequests = typeof store.totalRequests === 'number' ? store.totalRequests : 0
+  store.days = store.days && typeof store.days === 'object' && !Array.isArray(store.days) ? store.days : {}
+  store.recent = Array.isArray(store.recent) ? store.recent.slice(-USAGE_RECENT_CAP) : []
+  return store
+}
+
+const roundCredit = (n) => Math.round(n * 10000) / 10000
+
+/**
+ * Group recent requests into approximate turns: entries closer than
+ * TURN_GAP_MS merge into one row (a title call lands in the turn that
+ * triggered it; tool-loop steps are seconds apart by construction). The
+ * bridge cannot see the host's turn boundaries (no session ids on the
+ * wire), so this is a disclosed approximation.
+ */
+function groupTurns(recent) {
+  const turns = []
+  for (const r of recent) {
+    const last = turns[turns.length - 1]
+    if (last && r.ts - last.end <= TURN_GAP_MS) {
+      last.end = r.ts
+      last.requests += 1
+      last.credit = roundCredit(last.credit + r.credit)
+      last.prompt += r.prompt
+      last.hit += r.hit
+      last.miss += r.miss
+      last.completion += r.completion ?? 0
+      if (r.model && !last.models.includes(r.model)) last.models.push(r.model)
+      if (!last.kinds.includes(r.kind)) last.kinds.push(r.kind)
+    } else {
+      turns.push({
+        start: r.ts,
+        end: r.ts,
+        requests: 1,
+        credit: r.credit,
+        prompt: r.prompt,
+        hit: r.hit,
+        miss: r.miss,
+        completion: r.completion ?? 0,
+        models: r.model ? [r.model] : [],
+        kinds: [r.kind],
+      })
+    }
+  }
+  return turns
+}
+
+/**
+ * @param {{ path: string }} options persistence target
+ * @returns {{ record: Function, view: Function, dispose: Function }}
+ */
+export function createUsageMeter({ path }) {
+  const store = normalizeUsageStore(readJson(path))
+  let flushTimer = null
+
+  function flush() {
+    try {
+      writeJson(path, store)
+    } catch {
+      // persistence is best-effort
+    }
+  }
+
+  /** Debounced: a tool-loop burst produces one write, not one per request. */
+  function scheduleFlush() {
+    if (flushTimer) return
+    flushTimer = setTimeout(() => {
+      flushTimer = null
+      flush()
+    }, USAGE_FLUSH_MS)
+    flushTimer.unref?.()
+  }
+
+  /**
+   * Record one billed request. `usage` is the upstream's SSE usage object;
+   * only requests that actually produced one are recorded (failed/error
+   * responses carry no billing signal).
+   * kind: chat | title | compaction | image | search | fetch.
+   */
+  function record({ ts, kind, model, usage }) {
+    if (!usage || typeof usage !== 'object') return
+    try {
+      const credit = typeof usage.credit === 'number' && Number.isFinite(usage.credit) ? usage.credit : 0
+      const entry = {
+        ts,
+        kind,
+        model: typeof model === 'string' ? model : null,
+        prompt: usage.prompt_tokens ?? 0,
+        hit: usage.prompt_cache_hit_tokens ?? 0,
+        miss: usage.prompt_cache_miss_tokens ?? 0,
+        completion: usage.completion_tokens ?? 0,
+        credit,
+      }
+      store.totalCredit = roundCredit(store.totalCredit + credit)
+      store.totalRequests += 1
+      const day = dayKey(ts)
+      const bucket = store.days[day] ?? { credit: 0, requests: 0 }
+      bucket.credit = roundCredit(bucket.credit + credit)
+      bucket.requests += 1
+      store.days[day] = bucket
+      const dayKeys = Object.keys(store.days).sort()
+      while (dayKeys.length > USAGE_DAYS_CAP) delete store.days[dayKeys.shift()]
+      store.recent.push(entry)
+      if (store.recent.length > USAGE_RECENT_CAP) {
+        store.recent = store.recent.slice(-USAGE_RECENT_CAP)
+      }
+      scheduleFlush()
+    } catch {
+      // metering is best-effort
+    }
+  }
+
+  /** The usage-view payload: totals + approximate turns + exact recent rows. */
+  function view() {
+    const today = store.days[dayKey(Date.now())] ?? { credit: 0, requests: 0 }
+    return {
+      since: store.since,
+      totalCredit: store.totalCredit,
+      totalRequests: store.totalRequests,
+      today: { day: dayKey(Date.now()), credit: today.credit, requests: today.requests },
+      recent: store.recent.slice(-20).reverse(),
+      turns: groupTurns(store.recent).slice(-10).reverse(),
+      turnGapMs: TURN_GAP_MS,
+    }
+  }
+
+  function dispose() {
+    if (flushTimer) {
+      clearTimeout(flushTimer)
+      flushTimer = null
+    }
+    flush()
+  }
+
+  return { record, view, dispose }
+}

package/docs/diagnosis-cache-quota.md

@@ -0,0 +1,181 @@
+# 诊断报告：后端重复提问与缓存命中/额度消耗
+
+日期：2026-08-17 ｜ 环境：dsh 0.1.0-rc.6（web profile）+ dsh-codebuddy-plugin 0.6.0 ｜ 网关：copilot.tencent.com
+方法：桥内新增取证日志（`CODEBUDDY_BRIDGE_LOG`，本文 §1.2）+ 受控流量（`scripts/capture-traffic.mjs`）+ 网关对照探测（`scripts/probe-cache.mjs`）+ 83 个历史会话日志挖掘 + dsh rc.3↔rc.6 代码对比。
+预算遵守：真实网关调用共 48 次（上限 50），探测 `max_tokens=16`，主聊天回答按 prompt 约束为 ≤20 token。
+
+**原始数据**：`/tmp/diag/bridge.jsonl`（桥日志）、`/tmp/diag/probe-cache*.jsonl`（探测）、`~/.dsh/sessions/**/session.jsonl.zstd`（会话事件）。
+
+## TL;DR
+
+1. **"同一提问多次出现在后端"的主因不是 bug，是 agent 架构**：每个工具循环 step 都重发全量历史（历史实测 3275 steps / 540 turns ≈ **6.1 次/turn**）；其上是标题生成（每会话 1 次、内嵌首问全文）与子代理派生（独立会话、全量历史）。dsh-llm-retry 重试机制存在且请求体逐字节相同，但 codebuddy 路径 83 会话 0 实例。
+2. **网关缓存是按内容寻址的自动前缀缓存，与会话头/prompt_cache_key 无关**——对照实验全等价。**但按模型分策略：deepseek-v4-pro 缓存工作，deepseek-v3 在 ≤16.3k tokens 全部 0 命中**。插件默认模型是 deepseek-v3——"缓存命中率下降"的首要解释。
+3. **额度（credit）实测**：v4-pro 未命中 ≈0.26 credit/1k tokens，命中 ≈0.011（约 1/24）；v3 ≈0.03/1k 且无缓存折扣。一轮 15.8k token 的 turn：全 miss 4.08 credit vs 全命中 0.17。
+4. **v0.7"请求指纹→稳定会话映射"对缓存恢复无收益**（缓存本就不靠会话亲和），不建议以此为目标立项；杠杆在模型选择。
+
+---
+
+## 1. 重复提问甄别
+
+### 1.1 全局事实：dsh 对 LLM 的出站调用点只有 3 处
+
+全量 grep `llm.stream(` 证实（/usr/local/lib/node_modules/@deepseek-ai/dsh/node_modules/ 下）：
+
+- `dsh-agent-loop/lib/index.js:616` — 主循环 step（含重试重发）
+- `dsh-session-title-llm/lib/index.js:228` — 会话标题
+- `dsh-compaction-basic/lib/index.js:301` — 压缩摘要
+
+主循环每个 step 调 `session.deriveMessages()` 重发**全量历史**（`dsh-agent-loop/lib/index.js:613`；投影规则 `dsh-session/lib/index.js:278-287`）。历史 83 会话实测：3275 step / 540 turn ≈ **6.1 次请求/用户 turn**——一次提问触发 N 个工具轮次，就有 N+1 次含该提问全文的请求。这是"后端多次相同提问"的最大来源，属架构行为而非异常。
+
+### 1.2 取证手段：桥内请求日志（本次新增）
+
+`index.js` 的桥在 `CODEBUDDY_BRIDGE_LOG=<path>` 时每请求落一条 JSONL：入站（头特征、body/消息/系统提示哈希、末条用户消息预览 60 字符、marker 分类）+ 出站（状态、排队/首字节/总耗时、上游 usage 含缓存计数）。不落消息明文；Authorization 只记 `sentinel`/`caller-set` 分类。回归锁在 `scripts/verify-bridge.mjs` 第 7 节。
+
+marker 分类规则（对照 dsh 源码验证）：系统提示以 `Create a concise title for an AI coding-assistant session` 开头 → `session-title`（dsh-session-title-llm/lib/index.js:147-154）；末条 user 以 `You are now acting as a compaction engine` 开头 → `compaction`（dsh-compaction-basic/lib/index.js:218-253）。
+
+### 1.3 受控流量捕获（/tmp/diag/bridge.jsonl）
+
+`scripts/capture-traffic.mjs` 经 dsh web RPC 驱动：会话 A 三轮短问答、会话 B 逐字重发 A 的首问、会话 C 要求派生子代理。10 个 chat 请求全记录（模型 deepseek-v4-pro，用户此前在设置页选定的模型）：
+
+| seq | 间隔 | msgs | bytes | bodySha | marker | prompt_tokens | hit | miss | credit |
+|-----|------|------|-------|---------|--------|-------|------|-------|--------|
+| 1 | — | 2 | 665 | 7bb6f7b9 | session-title | 113 | 0 | 113 | 0.03 |
+| 2 | +26ms | 5 | 64356 | 2da804c8 | — | 15807 | 0 | 15807 | 4.07 |
+| 3 | +6.3s | 7 | 64432 | 1b02fc16 | — | 15820 | 4864 | 10956 | 2.88 |
+| 4 | +3.8s | 9 | 64589 | 1bab4e0f | — | 15831 | 15744 | 87 | 0.16 |
+| 5 | +3.0s | 5 | 64356 | **2da804c8** | — | 15807 | 15744 | 63 | 0.18 |
+| 6 | +2ms | 2 | 665 | **7bb6f7b9** | session-title | 113 | 0 | 113 | 0.03 |
+| 7 | +5.7s | 2 | 711 | e73a0bcb | session-title | 135 | 0 | 135 | 0.05 |
+| 8 | +1ms | 5 | 64398 | 0e25a15d | — | 15829 | 4352 | 11477 | 3.19 |
+| 9 | +6.1s | 5 | 64763 | 95b38492 | — | 15818 | **0** | 15818 | 4.08 |
+| 10 | +3.0s | 7 | 65347 | 5dbfd366 | — | 15972 | 15744 | 228 | 0.27 |
+
+注：seq1 比主请求 seq2 早 26ms 到达——标题调用在主请求路由确定后立即发出（dsh-session-title/lib/index.js:316-352）。
+
+### 1.4 六类候选来源逐项结论
+
+| 候选 | 结论 | 证据 |
+|------|------|------|
+| **dsh-llm-retry 重试** | 机制确认存在；**codebuddy 路径排除为观察期内来源** | 机制：默认 maxRetries=2、可重试码 EMPTY_RESPONSE/RATE_LIMIT/SERVER/TIMEOUT/TRANSPORT、退避 500ms 起（dsh-llm/lib/index.js:356-366）；重试重建请求体**逐字节相同、线上无标记**（agent-loop 回到 buildRequest，失败 chunk 不投影进消息，dsh-session/lib/index.js:278-287；SDK 内重试 maxRetries=0，dsh-llm-pi-ai/lib/index.js:666）。实例：历史 83 会话仅 1 起 2 次，**在 qianwenai provider**（TRANSPORT "stream ended before terminal event"，session-5f800970 seq52-57）；codebuddy 路径 0 起；本次捕获 10 请求无任何相同 bodySha 的亚秒级重复 |
+| **会话标题生成** | **确认** | 桥日志 seq1/6/7 marker=session-title：system+user 形状与 dsh-session-title-llm/lib/index.js:147-158 完全一致，maxTokens=64，模型同主聊天；每会话首条用户消息后 1 次（first-prompt 提供者）。**用户首问全文内嵌标题 prompt**（≤4096B），即在网关出现第二次。历史 75/83 会话有 title-llm-request。seq6 与 seq1 逐字节相同（跨会话同首问 → 同标题请求）。单次 0.03-0.05 credit |
+| **压缩摘要** | 机制确认存在；低频，非当前重复主因 | 触发：≥80% contextWindow 自动（thresholdRatio，dsh-compaction-basic/lib/index.js:13）、CONTEXT_WINDOW_EXCEEDED 溢出、手动 /compact。请求=全量历史+压缩指令，每次压缩 1 次 LLM 调用（pre-step 路径最多 2 次，:71）。历史 2 起：手动 /compact 成功（10.4s）；自动触发一次因 glm-4.6 返回 400 失败（session-21f564ae）。本次捕获未触发（上下文远未及阈值） |
+| **手动重发** | **确认** | 会话 B 首问与 A 首问逐字节相同（seq5 bodySha==seq2 的 2da804c8，间隔 3s）；第二次 99.6% 缓存命中，credit 4.07→0.18。同一文本的跨会话重发在网关侧就是一次完整新请求 |
+| **子代理调用** | **确认** | 会话 C 经 subagent 工具派生子会话 83dd6d24（session 事件：`origin:"subagent"`、`parentSession:session-4c2e6533…`、delegationDepth:1）。桥日志 seq9=子会话首请求（5 msgs、与父**同系统提示** sysSha 879617fd、但 0 命中——15.8k tokens 全量重新计费 4.08 credit）；seq10=父会话 step2。子代理继承父 provider/model 但用独立会话（dsh-subagent/lib/index.js:779-792），其每个 step 同样全量重发 |
+| **其他** | 见下 | ① **工具循环步**（最大放大器，见 §1.1，6.1 次/turn）；② goal 轮驱动/定时任务注入新 turn（dsh-goal-round-driver/lib/index.js:11-18、dsh-schedule/lib/index.js:825-835）：机制确认，历史 27 起 goal/change，本次未触发；③ dsh-time-context 每 step 追加时间戳消息：**默认 profile 未加载**（dsh-base/dsh-web-app/dsh-headless patch 均无），排除；④ dsh-repeat-tool-reminder 只改后续请求内容、不产生额外请求，排除 |
+
+**附带风险提示**：默认可重试码含 `EMPTY_RESPONSE`——网关若返回 200 但空内容（如 content_filter 收尾），dsh 会静默重发同一请求体最多 2 次，桥上表现为"一模一样又问了一遍"。本次未观察到实例，列为隐患。
+
+## 2. 缓存机制实测（scripts/probe-cache.mjs）
+
+### 2.1 缓存信号可观测性
+
+网关 SSE 每 chunk 带 usage，末chunk含完整字段：`prompt_cache_hit_tokens` / `prompt_cache_miss_tokens` / `prompt_tokens_details.cached_tokens` / `cache_read_input_tokens` / `cache_creation_input_tokens` / `prompt_cache_write_tokens` / `credit`（单次计费额度）。实测有效的命中字段是 `prompt_cache_hit_tokens`（= `prompt_tokens_details.cached_tokens`；Anthropic 方言字段恒 0）。**缓存行为可观测，无需依赖延迟推断。**
+
+### 2.2 对照实验（同 payload 连发，各 arm 独立 nonce 防串扰）
+
+| 实验 | 模型 | prompt tokens | 结果 |
+|------|------|------|------|
+| run1：anon/session/cachekey/session+cachekey ×3 | deepseek-v3 | ~883-958 | **12 次全 0 命中** |
+| run2：同上 | deepseek-v3 | ~2611-2830 | **12 次全 0 命中** |
+| run4：anon ×2 | deepseek-v3 | 16300 | **0 命中**（#2 仍 miss 16300） |
+| run3：anon ×3、session ×3 | deepseek-v4-pro | 2684 | 两臂 #1 miss、#2/#3 均 hit 2560，**完全相同** |
+| run5：anon ×2、session ×2 | deepseek-v4-pro | 15859 | 两臂 #2 均 hit 15744、credit 均 4.08→0.17，**完全相同** |
+
+结论：
+
+- **C1 缓存按内容寻址、自动生效**，不需要会话亲和头（openai 三头）也不需要 `prompt_cache_key`；两者对命中**零影响**（2.6k 与 15.8k 两档、anon/session 完全等价）。
+- **C2 缓存策略按模型分**：deepseek-v4-pro 缓存工作（阈值 ≤2684 tokens，粒度 128 tokens——命中值皆为 128 倍数）；**deepseek-v3 在 883/2611/16300 tokens 三档全部 0 命中**——v3 路径上缓存对该账号不可用。插件默认模型 `agent-default-model` 恰为 deepseek-v3（cordis.patch.yml:266-269）。
+- **C3 命中可用性在 15.8k 规模存在网关内部波动**：真实流量样本命中 0/4864/15744/15744/4352/0/15744（seq2-10），非单调；而受控连发（run5）第二次即稳定全命中——波动与并发/后端调度有关，**亲和头无法消除**（run5 对照）。
+- 延迟信号与之一致但噪声大（v4-pro 15.8k：miss ttfb 2653ms vs hit 2453ms；2.6k 档 2313→1903ms），仅作旁证，不作结论依据。
+
+### 2.3 dsh 主聊天出站画像（桥日志实证，seq2）
+
+- 头：`user-agent: deepseek-harness/0.1.0-rc.6 (+…)`（dsh attribution 强制覆盖静态 UA）、`x-ide-*/x-product-version/x-requested-with/x-private-data`（patch 静态头）、`authorization: 哨兵`（桥替换为真实凭据）。**无任何会话亲和头（sessionIn=null）、无 prompt_cache_key**——dsh 内部虽每步设 `sessionId: session.id`（dsh-agent-loop/lib/index.js:734），但 pi-ai 的亲和开关被 dsh-llm-pi-ai 的 compat 白名单剥除（白名单仅 thinkingFormat/supportsReasoningEffort，dsh-llm-pi-ai/lib/index.js:1334-1337），永不上线。
+- 体：`stream:true` + `stream_options.include_usage`、全量 messages、40 个工具、reasoning_effort=max、max_tokens=50000。系统提示 17589B（≈4.3k tokens）+ 工具为主体；**系统提示哈希跨会话/子代理恒定**（879617fd），前缀结构稳定。
+- 放大系数：每 turn ≈ 6.1 次全量请求（§1.1）。
+
+## 3. 额度消耗归因
+
+### 3.1 credit 单价（实测拟合）
+
+| 模型 | 未命中 | 命中 | 证据 |
+|------|--------|------|------|
+| deepseek-v4-pro | ≈0.26 credit/1k tok | ≈0.01 credit/1k tok（两组拟合 1/24–1/29） | 15859 tok 全 miss=4.08；15744 hit+115 miss=0.17（run5）；2684 档 0.70→0.06（run3）；15807 全 miss=4.07（seq2） |
+| deepseek-v3 | ≈0.03 credit/1k tok | —（无缓存可用） | 883→0.03、2611→0.08、16300→0.47（run1/2/4） |
+
+v4-pro 单价约为 v3 的 9 倍，但缓存命中部分再打 ~96% 折扣；v3 便宜但每轮全价。
+
+### 3.2 全量上下文重发与额度页的关系
+
+额度页消耗 = Σ credit（逐请求）。一轮 turn 的输入 ≈ 系统提示+工具（本机 ≈15.7k tokens）+ 累积历史；**每个 step 全量重发**（§1.1）。因此：
+
+- 无缓存（v3，或命中失效时）：10-turn 会话输入成本随历史近似线性→累计近似二次增长。本机规模：每 turn ≈ 15.8k×6.1 steps×0.26/1k ≈ **25 credit/turn**（v4-pro 全 miss）。
+- 稳命中（v4-pro）：同规模 hit 部分按 ~1/24 计价，seq4 实测整轮仅 0.16 credit（vs 全 miss 4.07）。
+- dsh 侧记账与网关一致：session.list 投影 `tokenUsage` 累计值与桥日志逐数吻合（26763=15807+10956；20608=4864+15744），**dsh 无额外放大**。
+- 标题/压缩/子代理为附加项：标题每会话 1 次约 0.03-0.05 credit；子代理首请求全量 miss（本次 4.08）。
+
+## 4. 旧版 dsh 对比（rc.3 ↔ rc.6）
+
+npm 拉取 @deepseek-ai/*@0.1.0-rc.3 逐包对比：请求路径上 6 个关键包中 5 个逐字节相同（dsh-agent-loop、dsh-llm-retry、dsh-time-context、dsh-session-title-llm、dsh-compaction-basic）；唯一差异在 dsh-llm-pi-ai：rc.6 对带思考开关的模型强制 `supportsDeveloperRole:false`（rc.6 lib/index.js:1080）——思考模型的系统提示角色由 rc.3 自动检测的 `developer` 改回 `system`。该差异一次性、版本内恒定，**不构成持续的缓存 miss 机制**。亲和头/prompt_cache_key/重试参数/压缩阈值/标题形状两版全同。**结论：排除"dsh 升级导致缓存命中率下降"**（逐包 diff，/tmp/dsh-old/）。
+
+## 5. v0.7 可行性结论：桥内"请求指纹→稳定会话映射"
+
+- **对缓存命中：收益 ≈ 0，不建议以此立项。** 缓存按内容寻址（C1），会话亲和头对命中零影响（run3/run5 对照，含 15.8k dsh 真实规模）。指纹映射无法恢复"本就不缺的东西"；观察到的命中波动（C3）是网关内部行为，亲和头不能消除。
+- **输入可缓存占比**（若模型有缓存）：本机实测连续 turn 命中 15744/15807 = **99.6%**；下限为系统提示+工具 ≈4.3k+ tokens（命中波动时观察到的部分命中 4352/4864 即该量级）。可缓存性瓶颈不在 dsh 前缀稳定性（sysSha 恒定），而在**模型是否享受缓存策略**。
+- 真正的杠杆（按收益排序）：① 默认/推荐模型切换到缓存可用的模型（v4-pro 实测命中折扣 ~24x；v3 无任何折扣）；② 命中波动属网关侧，插件不可控，但桥日志现已可长期观测命中率（`CODEBUDDY_BRIDGE_LOG`），可据此向网关方反馈；③ 指纹映射仅对 SessionLimiter 并发公平/网关会话分析有残余价值，不值得单独版本。
+
+## 6. 不可观测边界（诚实声明）
+
+- 网关**为什么** v3 不缓存、命中波动的后端原因（分片/复制/淘汰策略）不可从客户端观测；本文只断言可观测行为（usage 字段 + 对照实验）。
+- 额度页本身的口径（credit 与页面数值的映射、日结/周期）未验证；本文 credit 全部取自响应 usage 字段实测。
+- 标题/压缩请求是否享受缓存对总额度影响可忽略（≤135 tokens/次），未单独探测。
+- 子代理首请求 0 命中观察到 1 次（seq9）；系统提示与父相同，miss 原因（新会话路由到冷后端 vs 其他）不可进一步区分，但其计费后果已实测。
+
+## 7. 补遗（2026-08-18）：大上下文真实会话命中率劣化归因（"36%" 事件）
+
+用户报告：同模型 v4-flash、high、极简模式，插件路径 25 步聚合命中 36%，DeepSeek 原生路径 90%+，且"没有做会话管理之前命中合理"。定位与结论如下。
+
+### 7.1 用户会话复核（证据：docs/probes/cache-session-f52c817f-2026-08-18.json）
+
+- 会话 f52c817f：codebuddy / deepseek-v4-flash / high，web 研究任务（web_fetch 大页面），25 步，**平均上下文 ≈55.5k tokens**，dsh 记录口径聚合命中 **34.7%**——即用户所见 36%。
+- UI 口径（dsh-client-ui-conversation/lib/client.js:2777-2788）：`cacheHit% = ΣcacheRead / (Σuncached + ΣcacheRead + ΣcacheWrite)`，projection 来自 dsh-token-meter（uncachedInputTokens=usage.inputTokens）。两条路径记录口径一致，无插件侧记账差异。
+- 逐步形态：cacheRead **吸附于历史快照尺寸**（7424 出现 3 次、32768=恰好 32k、34304、46336），coverage（cacheRead/上一步 prompt）在 21%→100%→20% 间非单调跳动；t1.13 coverage 100% 证明 46k 大前缀可写可读，下一步又回落到 12.4k 化石快照——**网关在 40k+ 规模对真实增长内容的缓存条目保留/驱逐不稳定**。
+
+### 7.2 对照实验（v4-flash high、**直连网关不经插件**，docs/probes/cache-flash-scale-2026-08-18.jsonl）
+
+| 实验 | 条件 | 结果 |
+|------|------|------|
+| scale 连发 | 8k/16k/24k 同 prompt 各 4 发 | 复发 99.1–99.7%（阈值扫描另见 cache-flash-thresh：412 tok 起即缓存） |
+| gap | 16k，间隔 20s×3 + 60s×1 | 全部 99.7%——TTL ≥60s 无影响 |
+| grow | 20k→108k，+10k/轮，15s 间隔 | **coverage≈100%**，观测 hit% 与增长稀释上限逐点吻合（如 24011/35965=66.7% 实测 66.6%）；末轮原样重发 100% |
+
+→ 网关**有能力**在 108k 规模全量缓存增长前缀；用户会话的劣化不由尺寸本身决定，取决于网关内部状态/内容/负载。同一现象此前已在 15.8k 档以直连探测记录（C3），本次把"波动"上限推进到 40k+ 真实内容。
+
+### 7.3 插件链路无责（逐项排除）
+
+- 桥逐字节透明（2.6k 档直连==经桥，命中一致）；usage 数字是网关 SSE 自报，链路无法改写。
+- 会话管理（v0.5.5）对主聊天**不注入任何头**（dsh 出站无 session id，亲和开关被适配器剥除，§2.3）；SessionLimiter 只排队不动内容。"没有会话管理时命中合理"的印象与版本无关——v0.5.5 前后请求内容零变化。
+- 受控 A/B（极简 preset、同任务、小上下文 2–4.5k）：插件 15 步 agg **92.3%** vs 原生 16 步 **97.3%**（dsh 记录口径）——插件路径在小中上下文健康。
+- 用户的原生对照实为 **api.deepseek.com（另一套后端）且 avg ctx 仅 22k**，非同后端同规模；原生亦有 0 命中记录（85969bee，16k，[0,0]）。
+
+### 7.4 实务建议
+
+命中率的主导变量是**后端 × 上下文规模**：≤5k 各缓存模型稳定 95%+；codebuddy 网关 40k+ 真实增长内容当前不可靠（v4-flash 实测 agg 35%）；**v4-pro 在 99k 规模 215 步真实编码会话 agg 93.1%**（cbfaa68e）仍可用；glm-5.1/5.2 秒级失效、v3 恒 0。超大上下文且缓存敏感的场景优先 v4-pro 或 DeepSeek 官方 API。插件侧无可修项。
+
+## 8. 补遗更正（2026-09-03）：§7 与 C3 的"网关侧不稳定"归因已被推翻
+
+> 全量重判见 **docs/diagnosis-cache-decline.md**（证据链完整）。本节只记录对本报告结论的影响。
+
+- §7.1/§7.4 与 §2.2 C3 的"网关内部波动 / 40k+ 真实内容条目保留不稳 / 吸附历史快照"**全部重判为桥缺陷**：`core/bridge.js` 用 `rawBody += c` 逐 TCP 分片隐式 utf8 解码，跨分片中文字符→3×U+FFFD 且损坏位置逐请求随机——出站前缀逐请求漂移，内容寻址缓存忠实地把损坏点当命中边界（hit 值与 dump 分叉字节数定量对应）。上述观察全部取自经桥流量，因此被污染；直连网关受控探测（24 发全 99.3%、16k/32k TTL ≥600s、增长前缀+空闲全命中）证明网关 v4-flash 缓存稳定。
+- §7.2 的直连对照实验（合成内容 grow 至 108k ~100%）本身不经桥，结论不变；§7.3"桥逐字节透明（2.6k 档）"成立但**有边界**——单分片体透明，大体量中文体在分片切断多字节字符时不透明。
+- §7.4"插件侧无可修项"**作废**：主修 = 桥 body 组装改 `Buffer.concat` 一次解码（见 diagnosis-cache-decline.md §6，含同型缺陷 3 处与回归用例建议）。
+- §5"指纹映射无收益"结论不变（缓存按内容寻址的前提未被推翻，反而加强）。
+
+## 附：复现
+
+```sh
+CODEBUDDY_BRIDGE_LOG=/tmp/diag/bridge.jsonl dsh web   # 开取证日志
+node scripts/capture-traffic.mjs                       # 受控流量（约 10 次小调用）
+node scripts/probe-cache.mjs [--model M] [--arms anon,session,cachekey,session+cachekey] [--repeat N] [--calls K]
+node scripts/verify-bridge.mjs                         # 离线回归（含日志断言）
+```

package/docs/diagnosis-qoder-flash.md

@@ -0,0 +1,67 @@
+# 诊断：Qoder CN 的 Qwen3.8-Flash（`qfmodel`）为什么在 Qoder 里能用、在 dsh 里不能用
+
+> 结论日期 2026-09-22（Windows 侧 dsh-tap）。**一句话**：不是 dsh/插件的请求形态问题——`qfmodel` 的上游后端节点 `oa_qwen-plus-main` 在 **04:21:38–04:21:51 之间进入持久失败**，此后**任何客户端**（包括 Qoder 官方客户端自己的签名器/元数据/请求体/版本号）都拿不到正文；"在 Qoder 里能用"是**04:21:38 之前的旧印象**。
+>
+> 复测（幂等，节点恢复即翻绿）：`node scripts/probe-qoder-flash-confirm.mjs`
+
+## 1. 两条报错分别是什么
+
+| 报错 | 归属 | 机制 |
+|---|---|---|
+| `{"code":"400","message":"[FAIL]node:oa_qwen-plus-main msg:Execution failed: null"}` | **上游侧**（Qoder 后端节点内部异常） | qfmodel 被路由到推理节点 `oa_qwen-plus-main`，该节点对任何请求抛 `Execution failed: null`（形似 Java 侧 NPE）；HTTP 仍是 200，错误藏在 SSE 信封的 body 里（"带内失败帧"） |
+| `{"code":"provider_error","message":"Error in upstream response","request_id":"…","details":"{…\"Messages with role 'tool' must be a response to a preceding message with 'tool_calls'…}"}` | **宿主侧真 bug，插件已修**（踩坑 #41 为主因、#39 为次因） | 严格家族（dmodel/kmodel/mmodel）的配对校验器把 **`content` 为 `null`/缺键的消息当"不存在"**：宿主 pi-ai 对**每个纯工具轮**都发 `{role:'assistant',content:null,tool_calls:[…]}`（openai-completions.js:961），声明因此蒸发、其后的 `role:"tool"` 被判孤儿 → 400。次因：pi-ai 还会丢弃 `stopReason=error/aborted` 的 assistant 却保留其 tool 结果（#39），产出真孤儿。首版修复补的桩自己也是 `content:null`，所以"修完仍报同一条错"；0.9.9 起网关出站做可见性归一（null/缺键 → `''`）+ developer→system，实测四形态全部 400 → 200（证据 docs/probes/qoder-null-content-*.json） |
+
+## 2. qfmodel：为什么能断定是上游侧（逐变量排除）
+
+**基准**：最小合法体 = `{model:"qfmodel", stream:true, stream_options:{include_usage:true}, messages:[{role:"user",content:"只回复两个字：收到"}]}`，打 `POST gateway.qoder.com.cn/algo/api/v2/service/pro/sse/agent_chat_generation`（COSY 签名 + 加密 body）。**同一账号、同一线缆路径**，同批请求里 `qmodel_38max`（Qwen3.8-Max）与 `q37fmodel`（Qwen3.7-Flash）稳定出正文。
+
+| # | 假设 | 判定 | 判别证据 |
+|---|---|---|---|
+| 1 | 模型 key 猜错 | **否** | Qoder 客户端自己的日志打印 `model_config={"key":"qfmodel","display_name":"Qwen3.8-Flash",…,"source":"system"}`——客户端发的就是 `qfmodel`；两处 bundle 内**零硬编码模型 key**（key 全部来自服务端目录）。11 个臆造 key 全部被静默改派 auto（响应 `model:"auto"` + `billable:false`，踩坑 #37）→ 只有 `qfmodel` 会打到真实节点 |
+| 2 | 请求体字段差异 | **否** | 复刻客户端 agent 形态（system 提示 + 3~26 个工具 schema + `tool_choice` + `max_tokens` + `temperature`，899B vs 对照 904B）仍失败；另扫 `enable_thinking`/`reasoning_effort`/`scene`+`agent_id`/`stream:false`/`context_window`(1M·200K·1048576·驼峰)/`thinking_config`/空 messages——全部同样失败 |
+| 3 | 头/客户端元数据差异 | **否** | 用**官方 `QoderContext` 类**（wasm 原实现）签同一 body，扫 9 组 clientMetadata（含与客户端 fallback 逐字节一致的组合）——全部同样失败；`Cosy-ClientType` 无论传 `'qoder'`/`5`/缺省，wasm 恒出 **`5`**（已在插件侧对齐，见 §4） |
+| 4 | 版本闸门 / 静默降级 | **否** | 客户端 bundle 里 `minimal_version`/`minimalVersion`/`999.999.999` **零命中**（客户端从不读该字段，目录里的 `minimal_version:{vsc:"999.999.999"}` 是死数据）；把 `cosyVersion` 从 1.1.40 扫到 999.999.999，错误一字不变 → 服务端也没有版本闸门 |
+| 5 | 节点本身坏了 | **是** | `oa_qwen-plus-main` **只被 qfmodel 指名**；同样的坏体（孤儿 tool）打到 `qmodel`/`qmodel_38max`/`q37fmodel` 分别回 70/52/162 个 chunk 的正文——Qwen 节点族活着，只有 Flash 的节点指派坏了 |
+| + | 客户端有重试/降级 | **否** | 客户端 `contractMaxAttempts=3` 只覆盖传输层重试；三次都是 200，环内不换模型 |
+
+**路由是头驱动的**（对将来排错有用）：`X-Model-Key: qfmodel` + body `model:"auto"` → 仍失败；`X-Model-Key: auto` + body `model:"qfmodel"` → **成功**。即服务端按 `X-Model-Key`（= `prepareChat` 传的 `modelKey`）选节点，body 里的 `model` 字段不决定路由。插件正是用 `prepareChat(..., {modelKey: model})` 生成该头，行为与官方一致。
+
+## 3. 时间线（"在 Qoder 里能用"是被推翻的前提）
+
+| 时刻（+08） | 事件 | 证据 |
+|---|---|---|
+| 09-18 / 09-19 | Flash 在 Qoder 客户端**真实可用**：客户端 transcript 里累计 **754 条** `qfmodel` assistant 消息（完整 agent 环：thinking + tool_use + 正文） | `docs/probes/qoder-qfmodel-client-timeline.txt` |
+| **04:21:38** | 客户端最后一次成功：assistant 正文 `"你好！有什么需要帮忙的尽管说。…当前分支是 v0.8.3…"`（`runtime-config model=qfmodel`） | `~/.qoder-cn/projects/…/f3ec00b4-…jsonl` |
+| **04:21:51** | **同一客户端**的下一次运行：`model_config{"key":"qfmodel"}` → POST 同一端点 → `status=200 duration=3322ms` → `model.response.completed … output_tokens=0`、**不写 assistant 消息**（即同一条带内失败） | 原始日志：`~/.qoder-cn/logs/runs/2026-09-22T04-21-51-583+08-00-q2evm7-p26840/qodercli.log`（本机，含会话数据不入库）；本次复核落盘 `docs/probes/qoder-qfmodel-final-confirm.json` |
+| ~04:31 | dsh 侧首次复现同样报错（用户报障） | — |
+| 04:33–05:12 | 本轮 13 次复测（差分矩阵 + 确认探针）**全部失败**，对照模型全绿 | `docs/probes/qoder-matrix-*.json`、`docs/probes/qoder-flash-confirm-*.json` |
+
+→ 节点在 04:21:38–04:21:51 之间坏掉并持续。**用户"Qoder 里能用"的印象来自坏掉之前的体验**；坏掉之后官方客户端同样不能用（客户端表现为"回合结束但没有回复"，因为 HTTP 200，它不会弹错误）。
+
+## 4. 插件侧本轮实际修了什么（都不改变"Flash 属上游故障"的结论）
+
+1. **出站 tool 配对 + 可见性体检**（`providers/tool-pairing.js`，踩坑 #39 → #41）：第一版只修"孤儿 tool"，且在**容错家族 qmodel** 上验证 → 上线后同一条 `provider_error` 照旧。第二版（0.9.9）用单变量差分定出真因：严格家族的校验器把 `content:null`/缺键的消息**当不存在**，而宿主对每个纯工具轮都发 `content:null`，首版补的桩也是 `content:null`（修复自身即坏体）。修法 = 可见性归一（assistant/tool 的 null/缺键 content → `''`，桩用 `''`）+ 孤儿补桩 + 缺结果合成 + 重复结果丢弃，另加出站 developer→system 折叠。**修复前/后对比实测（真实 dmodel 上游，用当前代码起的临时网关）**：`A_call_content_null` / `B_orphan_plain` / `B_orphan_stub_null` / `C_tool_content_null` 四形态全部 400 → 200 出正文；`""`/文本/纯聊天对照行为不变。两个翻译网关（Qoder :3903、Trae :3902）共用该体检。复现与差分：`node scripts/probe-qoder-pairing.mjs --offline`（宿主真实序列化器，不花额度）、`node scripts/probe-qoder-null-content.mjs --models dmodel --gw-local`。
+2. **带内失败帧上抛**（0.9.9 早前提交）：HTTP 200 里的业务错误不再被静默吞，流式给错误 chunk + `[DONE]`、非流式 502 `qoder_upstream_error` 带上游详情——这正是 Flash 故障的**可读表现**。
+3. **`Cosy-ClientType` 头保真**：官方 wasm 恒出 `5`，插件旧值 `'qoder'` 会在所有请求上留下第三方客户端指纹；已改为 `5`（与模型可用性无关，两种值下 Flash 都失败）。
+
+## 5. 未解与下一步
+
+- **未解**：节点内部为什么失败（`Execution failed: null` 形似 Java NPE）、Flash 的节点指派是部署错误还是压根没上线、Qoder 是否另有 Flash 的服务端别名节点。三项都在服务端，客户端不可观测。
+- **下一步**：节点恢复后跑 `node scripts/probe-qoder-flash-confirm.mjs`（3×Flash + 2×对照，自动落证据）；确认恢复再跑 `node scripts/probe-qoder-matrix.mjs --suite flash` 复核全矩阵。
+- **不建议**：在网关目录里把 qfmodel 摘掉"避免选到坏模型"——目录是上游状态的实时镜像，摘除会把**临时**故障固化成配置（且节点恢复后需人工加回）；现有行为（选择器保留 + 可读 502 + 探测脚本可复核）更诚实。
+
+## 6. 证据索引
+
+| 文件 | 内容 |
+|---|---|
+| `docs/probes/qoder-matrix-1790022926057.json` | qfmodel 变量矩阵（baseline/effort/max_tokens/tools/多轮/source） |
+| `docs/probes/qoder-matrix-1790023075879.json` | 模型家族 × 孤儿 tool 拒绝面（dmodel/kmodel/mmodel 400，auto/qmodel/gmodel 容忍） |
+| `docs/probes/qoder-matrix-1790023159490.json` | 修复策略验证（孤儿补桩 / 缺结果合成 / 重复结果） |
+| `docs/probes/qoder-flash-confirm-*.json` | 3×Flash + 2×对照 的当前状态确认（可反复跑） |
+| `docs/probes/qoder-qfmodel-node-map.json` | 节点归属图 + 头驱动路由证明（`X-Model-Key` 决定路由） |
+| `docs/probes/qoder-qfmodel-key-sweep.json` | 11 个候选 key 的静默改派对照 |
+| `docs/probes/qoder-qfmodel-agentshape.json` | agent 形态 body 复刻对照 |
+| `docs/probes/qoder-qfmodel-clientmeta-sweep.json` | 官方 `QoderContext` × 9 组 clientMetadata |
+| `docs/probes/qoder-qfmodel-minimal-version-scan.txt` | 客户端 bundle 无 `minimal_version` 读取点 |
+| `docs/probes/qoder-qfmodel-client-timeline.txt` | 客户端 754 条 Flash 消息 + 最后成功时刻（transcript 扫描产物，含时间戳与正文摘录） |
+| `docs/probes/qoder-qfmodel-final-confirm.json` | 子探测复核（第一次确认 0/3，含原始 SSE 字节） |