mslxdff 0.1.199 → 0.1.203

package/src/logs.js

@@ -1,195 +1,195 @@
-import { appendFileSync, readFileSync, mkdirSync, existsSync, writeFileSync, statSync } from "node:fs";
-import { appendFile, stat, readFile, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import os from "node:os";
-import { defaultStateFile } from "./state.js";
-import { fmtShanghaiYMDHMS } from "./time.js";
-
-// 日志桶体积上限。events.log 是排查主入口（`-log`/`-debug` 都读它），1MB ≈ 1000 行
-// ≈ 3 分钟窗口，事后回溯基本不可用；同时旧的 `slice(-100)` 回退策略与 1MB 阈值严重不匹配
-// ——一次裁剪丢弃 90% 容量（实测 1043 行 → 99 行）。阈值提到 4MB、回退按字节保留末尾 3/4，
-// 两者配平后覆盖窗口约 10 倍于改前，且不再有断崖。
-const MAX_BYTES = 4 * 1024 * 1024;
-const KEEP_RATIO = 3 / 4;
-
-export function logDir() {
-  return process.env.MSLXDFF_DAEMON_DIR || dirname(defaultStateFile());
-}
-
-export function callsFile() {
-  return join(logDir(), "calls.log");
-}
-
-export function errorsFile() {
-  return join(logDir(), "errors.log");
-}
-
-export function eventsFile() {
-  return join(logDir(), "events.log");
-}
-
-export function timelineFile() {
-  return join(logDir(), "timeline.log");
-}
-
-function ensureDir(dir) {
-  mkdirSync(dir, { recursive: true });
-}
-
-/**
- * 按字节从尾部回退（不截半行）：累积整行直到超出预算，丢弃更早的行。
- * 用 `lines.slice(-N)` 之类的**行数**回退无法与**字节**阈值配平——行有长有短（events 行含 detail
- * 对象，实测均值 ~1KB），固定行数等于固定容量，一次裁剪就是断崖。
- */
-function keepTailByBytes(text, maxBytes) {
-  const limit = Math.max(1, Math.floor(maxBytes * KEEP_RATIO));
-  if (Buffer.byteLength(text) <= limit) return text;
-  const lines = text.split("\n");
-  let bytes = 0;
-  let i = lines.length - 1;
-  for (; i >= 0; i--) {
-    const b = Buffer.byteLength(lines[i]) + 1;
-    if (bytes + b > limit) break;
-    bytes += b;
-  }
-  // 至少保留最后一条：单行本身超过 limit 时（超大 detail/堆栈）上面的循环会一路退到第一条内容行之前，
-  // 返回空串 = 整个日志被清空，比截断更糟（一次丢掉全部历史，且看起来像"日志坏了"）。
-  // 判据是「保留结果为空」而不是 `i === lines.length-1`：文件以换行结尾时 split 出来的最后一个元素是
-  // 空串，`lines.length-1` 指向它，与真正的内容行不同（这一处曾写错，实测保底从未生效）。
-  // 宁可让这一条略微超出预算，也要留住"最新发生了什么"。
-  const kept = lines.slice(i + 1).join("\n");
-  if (!kept && lines.length) {
-    const last = lines.filter((l) => l !== "");
-    if (last.length) return last[last.length - 1];
-  }
-  return kept;
-}
-
-function trimIfOversized(file, maxBytes = MAX_BYTES) {
-  try {
-    const st = statSync(file);
-    if (st.size <= maxBytes) return;
-    writeFileSync(file, keepTailByBytes(readFileSync(file, "utf8"), maxBytes));
-  } catch {
-    // ignore
-  }
-}
-
-async function trimIfOversizedAsync(file, maxBytes = MAX_BYTES) {
-  try {
-    const st = await stat(file);
-    if (st.size <= maxBytes) return;
-    await writeFile(file, keepTailByBytes(await readFile(file, "utf8"), maxBytes));
-  } catch {
-    // ignore
-  }
-}
-
-function shouldSync(file) {
-  if (process.env.MSLXDFF_LOGS_SYNC === "1") return true;
-  if (process.env.MSLXDFF_DAEMON_DIR) {
-    const dir = process.env.MSLXDFF_DAEMON_DIR;
-    if (file.startsWith(dir)) return true;
-  }
-  // 显式 tmp 文件（所有 test 的 mkdtemp 前缀）走同步，保证 read-after-write 可见
-  const low = file.toLowerCase();
-  if (low.includes("mslxdff-") || low.includes("tmp") || low.includes("temp")) return true;
-  // 非默认目录的文件一律同步（测试传入的临时路径）
-  try {
-    const def = logDir().toLowerCase();
-    if (!low.startsWith(def)) return true;
-  } catch {}
-  return false;
-}
-
-function appendLine(file, entry) {
-  ensureDir(dirname(file));
-  const line = JSON.stringify({ ts: fmtShanghaiYMDHMS(new Date()), ...entry }) + "\n";
-  if (shouldSync(file)) {
-    appendFileSync(file, line);
-    trimIfOversized(file);
-    return;
-  }
-  // 线上异步：不阻塞事件循环
-  appendFile(file, line)
-    .catch(() => {})
-    .then(() => trimIfOversizedAsync(file).catch(() => {}));
-}
-
-export function recentTimeline(n = 10, { file = timelineFile() } = {}) {
-  try {
-    if (!existsSync(file)) return [];
-    return readFileSync(file, "utf8").split("\n").filter(Boolean).slice(-n);
-  } catch { return []; }
-}
-
-export function appendCall(entry, { file = callsFile() } = {}) {
-  appendLine(file, entry);
-}
-
-export function appendError(entry, { file = errorsFile() } = {}) {
-  appendLine(file, entry);
-}
-
-// Structured debug event stream: one JSON line per request/error/forward
-// step, consumed live by `mslxdff -debug`.
-export function appendEvent(entry, { file = eventsFile() } = {}) {
-  appendLine(file, dropTalk(entry));
-}
-
-// events.log 是 debug 流（1MB 环形），对话正文只准进 talk/*.log。
-// 单点剥掉 detail.talk：任何 relay 路径（含绕过 relay-pipeline 的 exhausted 收尾）都不会
-// 把整段问答灌进 debug 行；留 talkChars 计数，debug 时仍看得出这轮有没有出字。
-function dropTalk(entry) {
-  const t = entry?.detail?.talk;
-  if (!t) return entry;
-  const detail = { ...entry.detail };
-  delete detail.talk;
-  detail.talkChars = (t.content || []).join("").length;
-  detail.talkReasoningChars = (t.reasoning || []).join("").length;
-  return { ...entry, detail };
-}
-
-export function recentEvents(n = 100, { file = eventsFile() } = {}) {
-  return readLines(file).slice(-n);
-}
-
-function readLines(file) {
-  try {
-    if (!existsSync(file)) return [];
-    const text = readFileSync(file, "utf8");
-    return text.split("\n").filter(Boolean).map((l) => {
-      try {
-        return JSON.parse(l);
-      } catch {
-        return null;
-      }
-    }).filter(Boolean);
-  } catch {
-    return [];
-  }
-}
-
-export function recentCalls(n = 5, { file = callsFile() } = {}) {
-  return readLines(file).slice(-n);
-}
-
-export function lastError({ file = errorsFile() } = {}) {
-  const lines = readLines(file);
-  return lines.length ? lines[lines.length - 1] : null;
-}
-
-export function recentErrors(n = 5, { file = errorsFile() } = {}) {
-  return readLines(file).slice(-n);
-}
-
-export function appendTimeline(entry, { file = timelineFile() } = {}) {
-  const line = `${fmtShanghaiYMDHMS(new Date())} ${String(entry || "")}\n`;
-  ensureDir(dirname(file));
-  if (shouldSync(file)) {
-    appendFileSync(file, line);
-    trimIfOversized(file);
-    return;
-  }
-  appendFile(file, line).catch(() => {}).then(() => trimIfOversizedAsync(file).catch(() => {}));
-}
+import { appendFileSync, readFileSync, mkdirSync, existsSync, writeFileSync, statSync } from "node:fs";
+import { appendFile, stat, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import os from "node:os";
+import { defaultStateFile } from "./state.js";
+import { fmtShanghaiYMDHMS } from "./time.js";
+
+// 日志桶体积上限。events.log 是排查主入口（`-log`/`-debug` 都读它），1MB ≈ 1000 行
+// ≈ 3 分钟窗口，事后回溯基本不可用；同时旧的 `slice(-100)` 回退策略与 1MB 阈值严重不匹配
+// ——一次裁剪丢弃 90% 容量（实测 1043 行 → 99 行）。阈值提到 4MB、回退按字节保留末尾 3/4，
+// 两者配平后覆盖窗口约 10 倍于改前，且不再有断崖。
+const MAX_BYTES = 4 * 1024 * 1024;
+const KEEP_RATIO = 3 / 4;
+
+export function logDir() {
+  return process.env.MSLXDFF_DAEMON_DIR || dirname(defaultStateFile());
+}
+
+export function callsFile() {
+  return join(logDir(), "calls.log");
+}
+
+export function errorsFile() {
+  return join(logDir(), "errors.log");
+}
+
+export function eventsFile() {
+  return join(logDir(), "events.log");
+}
+
+export function timelineFile() {
+  return join(logDir(), "timeline.log");
+}
+
+function ensureDir(dir) {
+  mkdirSync(dir, { recursive: true });
+}
+
+/**
+ * 按字节从尾部回退（不截半行）：累积整行直到超出预算，丢弃更早的行。
+ * 用 `lines.slice(-N)` 之类的**行数**回退无法与**字节**阈值配平——行有长有短（events 行含 detail
+ * 对象，实测均值 ~1KB），固定行数等于固定容量，一次裁剪就是断崖。
+ */
+function keepTailByBytes(text, maxBytes) {
+  const limit = Math.max(1, Math.floor(maxBytes * KEEP_RATIO));
+  if (Buffer.byteLength(text) <= limit) return text;
+  const lines = text.split("\n");
+  let bytes = 0;
+  let i = lines.length - 1;
+  for (; i >= 0; i--) {
+    const b = Buffer.byteLength(lines[i]) + 1;
+    if (bytes + b > limit) break;
+    bytes += b;
+  }
+  // 至少保留最后一条：单行本身超过 limit 时（超大 detail/堆栈）上面的循环会一路退到第一条内容行之前，
+  // 返回空串 = 整个日志被清空，比截断更糟（一次丢掉全部历史，且看起来像"日志坏了"）。
+  // 判据是「保留结果为空」而不是 `i === lines.length-1`：文件以换行结尾时 split 出来的最后一个元素是
+  // 空串，`lines.length-1` 指向它，与真正的内容行不同（这一处曾写错，实测保底从未生效）。
+  // 宁可让这一条略微超出预算，也要留住"最新发生了什么"。
+  const kept = lines.slice(i + 1).join("\n");
+  if (!kept && lines.length) {
+    const last = lines.filter((l) => l !== "");
+    if (last.length) return last[last.length - 1];
+  }
+  return kept;
+}
+
+function trimIfOversized(file, maxBytes = MAX_BYTES) {
+  try {
+    const st = statSync(file);
+    if (st.size <= maxBytes) return;
+    writeFileSync(file, keepTailByBytes(readFileSync(file, "utf8"), maxBytes));
+  } catch {
+    // ignore
+  }
+}
+
+async function trimIfOversizedAsync(file, maxBytes = MAX_BYTES) {
+  try {
+    const st = await stat(file);
+    if (st.size <= maxBytes) return;
+    await writeFile(file, keepTailByBytes(await readFile(file, "utf8"), maxBytes));
+  } catch {
+    // ignore
+  }
+}
+
+function shouldSync(file) {
+  if (process.env.MSLXDFF_LOGS_SYNC === "1") return true;
+  if (process.env.MSLXDFF_DAEMON_DIR) {
+    const dir = process.env.MSLXDFF_DAEMON_DIR;
+    if (file.startsWith(dir)) return true;
+  }
+  // 显式 tmp 文件（所有 test 的 mkdtemp 前缀）走同步，保证 read-after-write 可见
+  const low = file.toLowerCase();
+  if (low.includes("mslxdff-") || low.includes("tmp") || low.includes("temp")) return true;
+  // 非默认目录的文件一律同步（测试传入的临时路径）
+  try {
+    const def = logDir().toLowerCase();
+    if (!low.startsWith(def)) return true;
+  } catch {}
+  return false;
+}
+
+function appendLine(file, entry) {
+  ensureDir(dirname(file));
+  const line = JSON.stringify({ ts: fmtShanghaiYMDHMS(new Date()), ...entry }) + "\n";
+  if (shouldSync(file)) {
+    appendFileSync(file, line);
+    trimIfOversized(file);
+    return;
+  }
+  // 线上异步：不阻塞事件循环
+  appendFile(file, line)
+    .catch(() => {})
+    .then(() => trimIfOversizedAsync(file).catch(() => {}));
+}
+
+export function recentTimeline(n = 10, { file = timelineFile() } = {}) {
+  try {
+    if (!existsSync(file)) return [];
+    return readFileSync(file, "utf8").split("\n").filter(Boolean).slice(-n);
+  } catch { return []; }
+}
+
+export function appendCall(entry, { file = callsFile() } = {}) {
+  appendLine(file, entry);
+}
+
+export function appendError(entry, { file = errorsFile() } = {}) {
+  appendLine(file, entry);
+}
+
+// Structured debug event stream: one JSON line per request/error/forward
+// step, consumed live by `mslxdff -debug`.
+export function appendEvent(entry, { file = eventsFile() } = {}) {
+  appendLine(file, dropTalk(entry));
+}
+
+// events.log 是 debug 流（1MB 环形），对话正文只准进 talk/*.log。
+// 单点剥掉 detail.talk：任何 relay 路径（含绕过 relay-pipeline 的 exhausted 收尾）都不会
+// 把整段问答灌进 debug 行；留 talkChars 计数，debug 时仍看得出这轮有没有出字。
+function dropTalk(entry) {
+  const t = entry?.detail?.talk;
+  if (!t) return entry;
+  const detail = { ...entry.detail };
+  delete detail.talk;
+  detail.talkChars = (t.content || []).join("").length;
+  detail.talkReasoningChars = (t.reasoning || []).join("").length;
+  return { ...entry, detail };
+}
+
+export function recentEvents(n = 100, { file = eventsFile() } = {}) {
+  return readLines(file).slice(-n);
+}
+
+function readLines(file) {
+  try {
+    if (!existsSync(file)) return [];
+    const text = readFileSync(file, "utf8");
+    return text.split("\n").filter(Boolean).map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return null;
+      }
+    }).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+export function recentCalls(n = 5, { file = callsFile() } = {}) {
+  return readLines(file).slice(-n);
+}
+
+export function lastError({ file = errorsFile() } = {}) {
+  const lines = readLines(file);
+  return lines.length ? lines[lines.length - 1] : null;
+}
+
+export function recentErrors(n = 5, { file = errorsFile() } = {}) {
+  return readLines(file).slice(-n);
+}
+
+export function appendTimeline(entry, { file = timelineFile() } = {}) {
+  const line = `${fmtShanghaiYMDHMS(new Date())} ${String(entry || "")}\n`;
+  ensureDir(dirname(file));
+  if (shouldSync(file)) {
+    appendFileSync(file, line);
+    trimIfOversized(file);
+    return;
+  }
+  appendFile(file, line).catch(() => {}).then(() => trimIfOversizedAsync(file).catch(() => {}));
+}

package/src/metrics.js

@@ -1,62 +1,62 @@
-import { normalizeFullId, toFullId } from "./providers/model-id.js";
-
-export { normalizeFullId, toFullId };
-
-// 从上游 usage 或文本兜底算 tps / charsPerSec
-export function computeMetrics({ ttfbMs, totalMs, promptTokens, completionTokens, chars }) {
-  const ttfb = Number(ttfbMs);
-  const total = Number(totalMs);
-  const hasTtfb = Number.isFinite(ttfb) && ttfb >= 0;
-  const hasTotal = Number.isFinite(total) && total >= 0;
-  const completionMs = hasTtfb && hasTotal ? Math.max(0, total - ttfb) : hasTotal ? total : null;
-  const comp = Number(completionTokens);
-  const hasComp = Number.isFinite(comp) && comp > 0 && Number.isFinite(completionMs) && completionMs > 0;
-  const tps = hasComp ? Number((comp / (completionMs / 1000)).toFixed(1)) : null;
-  const c = Number(chars);
-  const hasChars = Number.isFinite(c) && c > 0 && Number.isFinite(completionMs) && completionMs > 0;
-  const charsPerSec = !hasComp && hasChars ? Math.round(c / (completionMs / 1000)) : null;
-  return { completionMs, tps, charsPerSec };
-}
-
-// 从 Response 文本或 SSE 末帧提取 usage
-export function extractUsageFromJson(parsed) {
-  if (!parsed || typeof parsed !== "object") return null;
-  const u = parsed.usage;
-  if (!u || typeof u !== "object") return null;
-  const prompt = Number(u.prompt_tokens ?? u.promptTokens ?? u.input_tokens);
-  const comp = Number(u.completion_tokens ?? u.completionTokens ?? u.output_tokens);
-  const total = Number(u.total_tokens ?? u.totalTokens);
-  const out = {};
-  if (Number.isFinite(prompt)) out.prompt_tokens = prompt;
-  if (Number.isFinite(comp)) out.completion_tokens = comp;
-  if (Number.isFinite(total)) out.total_tokens = total;
-  // reasoning_tokens 透传
-  const rt = u.completion_tokens_details?.reasoning_tokens ?? u.reasoning_tokens;
-  if (Number.isFinite(Number(rt))) out.reasoning_tokens = Number(rt);
-  return Object.keys(out).length ? out : null;
-}
-
-export function extractUsageFromSseText(sseText) {
-  if (!sseText) return null;
-  const lines = String(sseText).split("\n");
-  for (let i = lines.length - 1; i >= 0; i--) {
-    const line = lines[i].trim();
-    if (!line.startsWith("data:")) continue;
-    const data = line.slice(5).trim();
-    if (data === "[DONE]") continue;
-    try {
-      const j = JSON.parse(data);
-      if (j.usage) return extractUsageFromJson(j);
-    } catch {}
-  }
-  return null;
-}
-
-// 归一模型全称：provider + raw -> opencode/xxx
-export function resolveFullId(rawModel, providerHint) {
-  const raw = String(rawModel || "").trim();
-  if (!raw) return "";
-  if (raw.includes("/")) return normalizeFullId(raw);
-  const prov = String(providerHint || "opencode").trim() || "opencode";
-  return toFullId(prov, raw);
-}
+import { normalizeFullId, toFullId } from "./providers/model-id.js";
+
+export { normalizeFullId, toFullId };
+
+// 从上游 usage 或文本兜底算 tps / charsPerSec
+export function computeMetrics({ ttfbMs, totalMs, promptTokens, completionTokens, chars }) {
+  const ttfb = Number(ttfbMs);
+  const total = Number(totalMs);
+  const hasTtfb = Number.isFinite(ttfb) && ttfb >= 0;
+  const hasTotal = Number.isFinite(total) && total >= 0;
+  const completionMs = hasTtfb && hasTotal ? Math.max(0, total - ttfb) : hasTotal ? total : null;
+  const comp = Number(completionTokens);
+  const hasComp = Number.isFinite(comp) && comp > 0 && Number.isFinite(completionMs) && completionMs > 0;
+  const tps = hasComp ? Number((comp / (completionMs / 1000)).toFixed(1)) : null;
+  const c = Number(chars);
+  const hasChars = Number.isFinite(c) && c > 0 && Number.isFinite(completionMs) && completionMs > 0;
+  const charsPerSec = !hasComp && hasChars ? Math.round(c / (completionMs / 1000)) : null;
+  return { completionMs, tps, charsPerSec };
+}
+
+// 从 Response 文本或 SSE 末帧提取 usage
+export function extractUsageFromJson(parsed) {
+  if (!parsed || typeof parsed !== "object") return null;
+  const u = parsed.usage;
+  if (!u || typeof u !== "object") return null;
+  const prompt = Number(u.prompt_tokens ?? u.promptTokens ?? u.input_tokens);
+  const comp = Number(u.completion_tokens ?? u.completionTokens ?? u.output_tokens);
+  const total = Number(u.total_tokens ?? u.totalTokens);
+  const out = {};
+  if (Number.isFinite(prompt)) out.prompt_tokens = prompt;
+  if (Number.isFinite(comp)) out.completion_tokens = comp;
+  if (Number.isFinite(total)) out.total_tokens = total;
+  // reasoning_tokens 透传
+  const rt = u.completion_tokens_details?.reasoning_tokens ?? u.reasoning_tokens;
+  if (Number.isFinite(Number(rt))) out.reasoning_tokens = Number(rt);
+  return Object.keys(out).length ? out : null;
+}
+
+export function extractUsageFromSseText(sseText) {
+  if (!sseText) return null;
+  const lines = String(sseText).split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (!line.startsWith("data:")) continue;
+    const data = line.slice(5).trim();
+    if (data === "[DONE]") continue;
+    try {
+      const j = JSON.parse(data);
+      if (j.usage) return extractUsageFromJson(j);
+    } catch {}
+  }
+  return null;
+}
+
+// 归一模型全称：provider + raw -> opencode/xxx
+export function resolveFullId(rawModel, providerHint) {
+  const raw = String(rawModel || "").trim();
+  if (!raw) return "";
+  if (raw.includes("/")) return normalizeFullId(raw);
+  const prov = String(providerHint || "opencode").trim() || "opencode";
+  return toFullId(prov, raw);
+}

package/src/model-capabilities/context-lookup.js

@@ -1,65 +1,65 @@
-// 模型上下文窗口的四级解析（ADR-0054）：/v1/models 富化时唯一真相源。
-// 旧状：顶层 context_length（provider 自报）与 capabilities.context（models.dev）两套并行可能矛盾，
-// 且四层全空时什么都不报；本模块把优先级收死，并保证"双层同源同值"。
-// 纯函数 + env，无 IO 无网络（L1/L2/L4 不依赖目录，冷缓存/目录挂掉照常生效）。
-// L4 方向沿上游 workbuddy2api-hub："未知报 1M——高估比低估安全"（只作元数据，网关转发不读它）。
-
-export const DEFAULT_CONTEXT_FALLBACK = 1_000_000;
-
-/** L4 兜底值：`MSLXDFF_MODEL_CONTEXT_FALLBACK` 覆盖；0/负数 = 关闭兜底（回"未知不报"旧口径）；非法值按默认 1M。 */
-export function contextFallback() {
-  const raw = String(process.env.MSLXDFF_MODEL_CONTEXT_FALLBACK ?? "").trim();
-  if (raw === "") return DEFAULT_CONTEXT_FALLBACK;
-  const n = Number(raw);
-  if (!Number.isFinite(n)) return DEFAULT_CONTEXT_FALLBACK;
-  if (n <= 0) return 0;
-  const f = Math.floor(n);
-  return f > 0 ? f : DEFAULT_CONTEXT_FALLBACK; // (0,1) 被.floor 成 0 会静默变"关兜底"，按非法回默认
-}
-
-function positiveInt(v) {
-  if (typeof v !== "number" && typeof v !== "string") return null; // boolean/数组/对象 = 未自报，不猜
-  const n = Number(v);
-  return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
-}
-
-/** L1 条目自报（first-party 最准）。键序覆盖现网全部自报形状；非数字/0/负数 = 未自报，丢弃而非钳制。 */
-export function firstPartyContextOf(entry) {
-  if (!entry || typeof entry !== "object") return null;
-  for (const v of [entry.context_length, entry.maxInputTokens, entry.max_input_tokens]) {
-    const n = positiveInt(v);
-    if (n) return n;
-  }
-  const cw = entry.contextWindow;
-  return positiveInt(cw && typeof cw === "object" ? cw.defaultLength : cw);
-}
-
-// L2 内置知识表：给"provider 目录不自报窗口、且值有官方/上游文档出处"的模型补一手。
-// 准入红线（评审过：无据值不得进表——traework 硬编码 131072 正是反面教材，本次已删）：
-//   - key = **实际传入解析器的条目 id 小写**（现网含裸 id 与 `-free` 后缀形态；填表前必须按此对键，
-//     跨 provider 撞名靠带前缀的 id 天然区分），别照 ADR 初稿的 `prov/raw` canonical 形去猜；
-//   - 每条必须带 source 出处注释（文档/上游字段 + 核对日期），给不出出处就让它落 L4 兜底。
-// 首期为空是盘点结论：raccoon/qoder/codearts/workbuddy/globalworkbuddy/qwenwork 系的有据值全部已被 L1 覆盖，
-// 把 L1 复制进表只会制造第二个真相源。等出现"只回 id 的极简目录 provider"之类的真缺口再填。
-export const KNOWN_CONTEXT = Object.freeze({});
-
-/** L2 查表（按条目 id 小写）；未命中或值非法返回 null。`table` 为测试注入口（缺省用内置表）。 */
-export function knownContextOf(id, table = KNOWN_CONTEXT) {
-  const e = table[String(id || "").trim().toLowerCase()];
-  return e ? positiveInt(e.context) : null;
-}
-
-/**
- * 四级解析：L1 自报 > L2 内置表 > L3 models.dev caps > L4 兜底。
- * 返回正整数；env 关闭兜底且 L1–L3 全空时返回 null（调用方两层都不写）。
- * `knownTable` 仅供测试注入假表锁 L2>L3 顺序，生产调用方不传。
- */
-export function resolveContextLength({ entry, id, caps, knownTable } = {}) {
-  const fp = firstPartyContextOf(entry);
-  if (fp) return fp;
-  const known = knownContextOf(id, knownTable);
-  if (known) return known;
-  const c = positiveInt(caps?.context);
-  if (c) return c;
-  return contextFallback() || null;
-}
+// 模型上下文窗口的四级解析（ADR-0054）：/v1/models 富化时唯一真相源。
+// 旧状：顶层 context_length（provider 自报）与 capabilities.context（models.dev）两套并行可能矛盾，
+// 且四层全空时什么都不报；本模块把优先级收死，并保证"双层同源同值"。
+// 纯函数 + env，无 IO 无网络（L1/L2/L4 不依赖目录，冷缓存/目录挂掉照常生效）。
+// L4 方向沿上游 workbuddy2api-hub："未知报 1M——高估比低估安全"（只作元数据，网关转发不读它）。
+
+export const DEFAULT_CONTEXT_FALLBACK = 1_000_000;
+
+/** L4 兜底值：`MSLXDFF_MODEL_CONTEXT_FALLBACK` 覆盖；0/负数 = 关闭兜底（回"未知不报"旧口径）；非法值按默认 1M。 */
+export function contextFallback() {
+  const raw = String(process.env.MSLXDFF_MODEL_CONTEXT_FALLBACK ?? "").trim();
+  if (raw === "") return DEFAULT_CONTEXT_FALLBACK;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return DEFAULT_CONTEXT_FALLBACK;
+  if (n <= 0) return 0;
+  const f = Math.floor(n);
+  return f > 0 ? f : DEFAULT_CONTEXT_FALLBACK; // (0,1) 被.floor 成 0 会静默变"关兜底"，按非法回默认
+}
+
+function positiveInt(v) {
+  if (typeof v !== "number" && typeof v !== "string") return null; // boolean/数组/对象 = 未自报，不猜
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+}
+
+/** L1 条目自报（first-party 最准）。键序覆盖现网全部自报形状；非数字/0/负数 = 未自报，丢弃而非钳制。 */
+export function firstPartyContextOf(entry) {
+  if (!entry || typeof entry !== "object") return null;
+  for (const v of [entry.context_length, entry.maxInputTokens, entry.max_input_tokens]) {
+    const n = positiveInt(v);
+    if (n) return n;
+  }
+  const cw = entry.contextWindow;
+  return positiveInt(cw && typeof cw === "object" ? cw.defaultLength : cw);
+}
+
+// L2 内置知识表：给"provider 目录不自报窗口、且值有官方/上游文档出处"的模型补一手。
+// 准入红线（评审过：无据值不得进表——traework 硬编码 131072 正是反面教材，本次已删）：
+//   - key = **实际传入解析器的条目 id 小写**（现网含裸 id 与 `-free` 后缀形态；填表前必须按此对键，
+//     跨 provider 撞名靠带前缀的 id 天然区分），别照 ADR 初稿的 `prov/raw` canonical 形去猜；
+//   - 每条必须带 source 出处注释（文档/上游字段 + 核对日期），给不出出处就让它落 L4 兜底。
+// 首期为空是盘点结论：raccoon/qoder/codearts/workbuddy/globalworkbuddy/qwenwork 系的有据值全部已被 L1 覆盖，
+// 把 L1 复制进表只会制造第二个真相源。等出现"只回 id 的极简目录 provider"之类的真缺口再填。
+export const KNOWN_CONTEXT = Object.freeze({});
+
+/** L2 查表（按条目 id 小写）；未命中或值非法返回 null。`table` 为测试注入口（缺省用内置表）。 */
+export function knownContextOf(id, table = KNOWN_CONTEXT) {
+  const e = table[String(id || "").trim().toLowerCase()];
+  return e ? positiveInt(e.context) : null;
+}
+
+/**
+ * 四级解析：L1 自报 > L2 内置表 > L3 models.dev caps > L4 兜底。
+ * 返回正整数；env 关闭兜底且 L1–L3 全空时返回 null（调用方两层都不写）。
+ * `knownTable` 仅供测试注入假表锁 L2>L3 顺序，生产调用方不传。
+ */
+export function resolveContextLength({ entry, id, caps, knownTable } = {}) {
+  const fp = firstPartyContextOf(entry);
+  if (fp) return fp;
+  const known = knownContextOf(id, knownTable);
+  if (known) return known;
+  const c = positiveInt(caps?.context);
+  if (c) return c;
+  return contextFallback() || null;
+}