cx-viewer 1.0.3 → 1.0.4

package/scripts/check-no-control-bytes.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * Guard: reject raw C0 control bytes (except TAB / LF / CR) and DEL in tracked text source.
+ *
+ * Why this exists: a single stray control byte — most notably NUL (0x00) — makes the ENTIRE file
+ * be classified as "binary" by grep/ripgrep (so `grep -I` / `rg` silently skip it), by editor
+ * global-search, and by code-review diff tools. A file can then become invisible to search while
+ * looking completely normal when opened. We hit exactly this: a NUL used as a delimiter in
+ * `ChatView.jsx` hid the whole file from grep for an entire debugging session.
+ *
+ * The fix is free: write control characters as escapes in the source (e.g. `\x00`, `\x01`, `\x1b`).
+ * The JS parser turns the escape into the same byte at runtime, so behaviour is byte-identical,
+ * but the source file stays pure text and remains searchable by every tool.
+ *
+ * Scans git-tracked files with a code/text extension; skips build output and binary assets.
+ * If git is unavailable or this is not a git work tree (extracted tarball, clean-room CI), the
+ * check skips gracefully (exit 0) rather than breaking `npm test`.
+ * Exit 0 = clean (or skipped), exit 1 = violations (printed as path:line:col (offset) + byte).
+ *
+ * Invoked as a pretest hook via package.json "pretest" to ensure the codebase stays
+ * grep-friendly.
+ */
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+// Only scan real source / docs / config. Binary assets (mp3, png, icns, fonts, …) are excluded by
+// simply not being on this list, so we never false-positive on legitimately-binary files.
+export const TEXT_EXT = new Set([
+  'js', 'jsx', 'mjs', 'cjs', 'ts', 'tsx',
+  'css', 'scss', 'less',
+  'json', 'jsonc', 'html', 'htm',
+  'md', 'markdown', 'txt',
+  'sh', 'bash', 'zsh',
+  'yml', 'yaml', 'vue',
+]);
+
+// Build output / generated dirs are not source — don't scan them.
+export const SKIP_PREFIX = ['dist/', 'build/', 'node_modules/'];
+
+// Allowed control bytes: TAB (0x09), LF (0x0a), CR (0x0d). Forbidden: every other C0 byte + DEL.
+export const isForbidden = (b) =>
+  b <= 0x08 || b === 0x0b || b === 0x0c || (b >= 0x0e && b <= 0x1f) || b === 0x7f;
+
+export const extOf = (f) => {
+  const m = f.toLowerCase().match(/\.([^./]+)$/);
+  return m ? m[1] : '';
+};
+
+/**
+ * @returns {string[]|null} source text files to scan (tracked + untracked-but-not-ignored),
+ *   or null if not a git work tree / git missing.
+ */
+export function listScannableTextFiles() {
+  let tracked, untracked;
+  try {
+    tracked = execSync('git ls-files', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    // Also scan untracked-but-not-ignored files: a stray control byte is almost always introduced
+    // in a NEW or freshly-edited file, and `git ls-files` (tracked only) would skip it until the
+    // file is `git add`-ed — exactly the case this guard most needs to catch.
+    untracked = execSync('git ls-files --others --exclude-standard', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch {
+    return null; // git unavailable or not inside a git work tree
+  }
+  const all = (tracked + '\n' + untracked).split('\n').filter(Boolean);
+  return [...new Set(all)]
+    .filter((f) => !SKIP_PREFIX.some((p) => f.startsWith(p)))
+    .filter((f) => TEXT_EXT.has(extOf(f)));
+}
+
+/**
+ * @returns {{line:number, col:number, offset:number, byte:number}[]} forbidden-byte hits in a file.
+ */
+export function scanFile(path) {
+  let buf;
+  try {
+    buf = readFileSync(path);
+  } catch {
+    return [];
+  }
+  const hits = [];
+  let line = 1;
+  let col = 0;
+  for (let i = 0; i < buf.length; i++) {
+    const b = buf[i];
+    if (b === 0x0a) {
+      line++;
+      col = 0;
+      continue;
+    }
+    col++;
+    if (isForbidden(b)) hits.push({ line, col, offset: i, byte: b });
+  }
+  return hits;
+}
+
+function main() {
+  const files = listScannableTextFiles();
+  if (files === null) {
+    console.warn('⚠ check-no-control-bytes: not a git work tree / git unavailable — skipping.');
+    process.exit(0);
+  }
+
+  const violations = [];
+  for (const f of files) {
+    for (const h of scanFile(f)) {
+      const hex = h.byte.toString(16).padStart(2, '0').toUpperCase();
+      violations.push(`${f}:${h.line}:${h.col} (offset ${h.offset}) raw byte 0x${hex}`);
+    }
+  }
+
+  if (violations.length > 0) {
+    console.error('✗ raw control byte(s) found in tracked source:');
+    for (const v of violations) console.error('  ' + v);
+    console.error(
+      `\n${violations.length} violation(s). A NUL/control byte makes the file be treated as binary ` +
+        `(grep -I / ripgrep / editor search will silently skip it).\n` +
+        `Write the character as an escape instead — e.g. \\x00, \\x01, \\x1b — same runtime value, searchable source.`,
+    );
+    process.exit(1);
+  }
+
+  console.log(`✓ no raw control bytes in ${files.length} tracked text files`);
+}
+
+// Run the check only when invoked directly (e.g. `node scripts/check-no-control-bytes.js`),
+// so unit tests can import the helpers above without triggering the scan / process.exit.
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {
+  main();
+}

package/scripts/check-sign-config.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+
+# 签名配置检查工具
+
+echo "🔍 CX Viewer 签名配置检查"
+echo "================================"
+echo ""
+
+# 检查证书
+echo "1️⃣ 检查代码签名证书..."
+IDENTITIES=$(security find-identity -v -p codesigning | grep "Developer ID Application")
+
+if [ -z "$IDENTITIES" ]; then
+  echo "   ❌ 未找到 Developer ID Application 证书"
+  echo "   📖 请在 Apple Developer 账户中申请 Developer ID Application 证书"
+  echo ""
+else
+  echo "   ✅ 找到证书:"
+  echo "$IDENTITIES" | sed 's/^/      /'
+  echo ""
+fi
+
+# 检查环境变量
+echo "2️⃣ 检查环境变量配置..."
+echo ""
+
+check_env() {
+  local var_name=$1
+  local display_name=$2
+  local is_required=$3
+
+  if [ -n "${!var_name}" ]; then
+    echo "   ✅ $display_name: 已设置"
+  else
+    if [ "$is_required" = "true" ]; then
+      echo "   ❌ $display_name: 未设置 (必需)"
+    else
+      echo "   ⚠️  $display_name: 未设置 (可选，用于公证)"
+    fi
+  fi
+}
+
+echo "   签名配置:"
+check_env "CSC_LINK" "CSC_LINK (证书路径)" "true"
+check_env "CSC_KEY_PASSWORD" "CSC_KEY_PASSWORD (证书密码)" "true"
+
+echo ""
+echo "   公证配置:"
+check_env "APPLE_ID" "APPLE_ID" "false"
+check_env "APPLE_APP_SPECIFIC_PASSWORD" "APPLE_APP_SPECIFIC_PASSWORD" "false"
+check_env "APPLE_TEAM_ID" "APPLE_TEAM_ID" "false"
+
+echo ""
+
+# 检查证书文件
+if [ -n "$CSC_LINK" ]; then
+  echo "3️⃣ 检查证书文件..."
+  if [ -f "$CSC_LINK" ]; then
+    echo "   ✅ 证书文件存在: $CSC_LINK"
+  else
+    echo "   ❌ 证书文件不存在: $CSC_LINK"
+  fi
+  echo ""
+fi
+
+# 总结
+echo "================================"
+echo ""
+
+if [ -n "$IDENTITIES" ] && [ -n "$CSC_LINK" ] && [ -n "$CSC_KEY_PASSWORD" ]; then
+  echo "✅ 签名配置完成！可以执行:"
+  echo "   npm run electron:build  # 仅签名"
+
+  if [ -n "$APPLE_ID" ] && [ -n "$APPLE_APP_SPECIFIC_PASSWORD" ] && [ -n "$APPLE_TEAM_ID" ]; then
+    echo "   npm run electron:sign   # 签名 + 公证 (推荐)"
+  else
+    echo ""
+    echo "⚠️  公证配置未完成，应用将仅签名"
+    echo "   要启用公证，请设置 APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID"
+  fi
+else
+  echo "❌ 配置未完成，请设置 CSC_LINK / CSC_KEY_PASSWORD 等环境变量后重试"
+fi
+
+echo ""

package/scripts/gen-default-voicepack.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// Generate a chiptune mascot voice pack ("default-pixel-buddy") — 8-bit-style cues
+// covering every voice-pack event — into public/voice-packs/default/.
+//
+// ⚠️ The pack CURRENTLY shipped in that dir is a different, hand-maintained one
+// ("default-butler", recorded .MP3s). Running this script overwrites it with the
+// chiptune set + rewrites pack.json's name to default-pixel-buddy. To avoid an
+// accidental clobber, this script REFUSES to run when the dir already holds a
+// differently-named pack.json — pass --force to regenerate the chiptune pack anyway.
+//
+// Usage:
+//   node scripts/gen-default-voicepack.js [--force]
+
+import { writeFileSync, mkdirSync, existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { EVENT_KEYS } from '../server/lib/voice-pack-events.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const OUT_DIR = join(__dirname, '..', 'public', 'voice-packs', 'default');
+
+const SAMPLE_RATE = 22050;
+const BITS = 16;
+const CHANNELS = 1;
+const ATTACK_SECONDS = 0.005;   // very fast attack — gives chiptune "pluck" character
+const RELEASE_SECONDS = 0.025;  // slightly longer release with quadratic curve below
+
+// Each pattern is an array of segments:
+//   { wave: 'sine'|'square', freq, freqEnd?, ms, vol }
+// freqEnd (optional) glides the pitch linearly from `freq` to `freqEnd` over the
+// segment's duration — that's how "Bi-poop?" gets its rising inquiry inflection
+// and how "Wee-doo~" gets its falling tail.
+//
+// Volumes are deliberately low (≈ 0.20-0.28). Square waves are harmonic-rich
+// and read louder than sines at the same numeric volume.
+const PATTERNS = {
+  // "Bi-poop?" — short low chirp, gap, rising "poop?" inquiry
+  planApproval: [
+    { wave: 'square', freq: 587, ms: 120, vol: 0.22 },
+    { freq: 0, ms: 50, vol: 0 },
+    { wave: 'square', freq: 659, freqEnd: 880, ms: 200, vol: 0.22 },
+  ],
+  // "Pip pip!" — two identical bouncy chirps, high pitch
+  askQuestion: [
+    { wave: 'square', freq: 1175, ms: 75, vol: 0.24 },
+    { freq: 0, ms: 70, vol: 0 },
+    { wave: 'square', freq: 1175, ms: 75, vol: 0.24 },
+  ],
+  // "Wee-doo~ ♪" — descending arpeggio with a glide tail for the satisfied finish.
+  // 659Hz 起点是历史值（曾为避让已删除的 timeoutWarning60s 880Hz 警报刻意降调），
+  // 现可自由调整；保留是因为现有 default-pack 音色已稳定，不必无故 churn。
+  turnEnd: [
+    { wave: 'square', freq: 659, ms: 110, vol: 0.24 },
+    { freq: 0, ms: 30, vol: 0 },
+    { wave: 'square', freq: 523, ms: 110, vol: 0.24 },
+    { freq: 0, ms: 30, vol: 0 },
+    { wave: 'square', freq: 440, freqEnd: 330, ms: 280, vol: 0.24 },
+  ],
+};
+
+// Defensive: PATTERNS must cover every EVENT_KEYS entry so the bundled default
+// pack is complete. If someone adds a new event to voice-pack-events.js but
+// forgets to add a pattern here, fail loudly at script run time.
+{
+  const missing = EVENT_KEYS.filter((k) => !(k in PATTERNS));
+  if (missing.length > 0) {
+    console.error(`[voice-pack] gen-default-voicepack.js missing PATTERNS for: ${missing.join(', ')}`);
+    process.exit(1);
+  }
+}
+
+// Phase-accumulating oscillator with linear pitch glide + AR envelope (fast
+// linear attack, quadratic release). Phase carries across frequency changes
+// inside a segment so glides don't pop at the boundary.
+function buildPcm(pattern) {
+  const totalSamples = pattern.reduce((n, seg) => n + Math.round(SAMPLE_RATE * seg.ms / 1000), 0);
+  const pcm = Buffer.alloc(totalSamples * 2);
+  let cursor = 0;
+  let phase = 0;
+  for (const seg of pattern) {
+    const count = Math.round(SAMPLE_RATE * seg.ms / 1000);
+    const attackSamples = Math.min(Math.floor(SAMPLE_RATE * ATTACK_SECONDS), Math.floor(count / 8));
+    const releaseSamples = Math.min(Math.floor(SAMPLE_RATE * RELEASE_SECONDS), Math.floor(count / 3));
+    const wave = seg.wave || 'sine';
+    const freqStart = seg.freq;
+    const freqEnd = seg.freqEnd != null ? seg.freqEnd : seg.freq;
+    for (let i = 0; i < count; i++) {
+      const t = count > 1 ? i / (count - 1) : 0;
+      const currentFreq = freqStart + (freqEnd - freqStart) * t;
+      // Silence segments still advance the cursor but contribute zero amplitude.
+      if (freqStart === 0 && freqEnd === 0) {
+        pcm.writeInt16LE(0, cursor); cursor += 2;
+        continue;
+      }
+      phase += (2 * Math.PI * currentFreq) / SAMPLE_RATE;
+      let sample;
+      if (wave === 'square') {
+        sample = ((phase % (2 * Math.PI)) < Math.PI) ? 1 : -1;
+      } else {
+        sample = Math.sin(phase);
+      }
+      // AR envelope — linear attack, quadratic release (cubic feels too quick;
+      // linear release has audible cutoff). Sustain is implicit at peak volume.
+      let env = seg.vol;
+      if (i < attackSamples) {
+        env *= i / attackSamples;
+      } else if (i > count - releaseSamples) {
+        const rt = (count - i) / releaseSamples;
+        env *= rt * rt;
+      }
+      const v = Math.max(-1, Math.min(1, sample * env)) * 0x7FFF;
+      pcm.writeInt16LE(v | 0, cursor);
+      cursor += 2;
+    }
+  }
+  return pcm;
+}
+
+function buildWav(pcm) {
+  const byteRate = SAMPLE_RATE * CHANNELS * BITS / 8;
+  const blockAlign = CHANNELS * BITS / 8;
+  const header = Buffer.alloc(44);
+  header.write('RIFF', 0);
+  header.writeUInt32LE(36 + pcm.length, 4);
+  header.write('WAVE', 8);
+  header.write('fmt ', 12);
+  header.writeUInt32LE(16, 16);
+  header.writeUInt16LE(1, 20);
+  header.writeUInt16LE(CHANNELS, 22);
+  header.writeUInt32LE(SAMPLE_RATE, 24);
+  header.writeUInt32LE(byteRate, 28);
+  header.writeUInt16LE(blockAlign, 32);
+  header.writeUInt16LE(BITS, 34);
+  header.write('data', 36);
+  header.writeUInt32LE(pcm.length, 40);
+  return Buffer.concat([header, pcm]);
+}
+
+// 防误覆盖：若目标目录已存在「异名」pack.json（如随仓发布的 default-butler），需显式 --force 才覆盖。
+const FORCE = process.argv.includes('--force');
+const existingPackPath = join(OUT_DIR, 'pack.json');
+if (!FORCE && existsSync(existingPackPath)) {
+  let existingName = '';
+  try { existingName = JSON.parse(readFileSync(existingPackPath, 'utf-8')).name || ''; } catch { /* 坏文件视为无名，放行 */ }
+  if (existingName && existingName !== 'default-pixel-buddy') {
+    console.error(`[voice-pack] public/voice-packs/default/ 已存在异名默认包「${existingName}」，本脚本会用 default-pixel-buddy 覆盖它。`);
+    console.error('[voice-pack] 如确需重新生成 chiptune 占位包，请加 --force：node scripts/gen-default-voicepack.js --force');
+    process.exit(1);
+  }
+}
+
+mkdirSync(OUT_DIR, { recursive: true });
+const manifest = {
+  name: 'default-pixel-buddy',
+  displayName: 'Pixel Buddy · 像素小宠物 (默认)',
+  // Intentional chiptune SFX (not silent placeholders); placeholder:false marks them as real audio.
+  // Note: the dir's currently-shipped pack is default-butler, not this one (see header).
+  placeholder: false,
+  events: {},
+  // Onomatopoeia table — what each cue is meant to sound like, for anyone
+  // generating their own replacements.
+  cues: {
+    planApproval:       'Bi-poop?  (短低 + 上扬"问"句)',
+    askQuestion:        'Pip pip!  (两短促跳跳)',
+    turnEnd:            'Wee-doo~ ♪  (下行小调，满足)',
+  },
+};
+for (const [eventKey, pattern] of Object.entries(PATTERNS)) {
+  const wav = buildWav(buildPcm(pattern));
+  const path = join(OUT_DIR, `${eventKey}.wav`);
+  writeFileSync(path, wav);
+  manifest.events[eventKey] = { file: `${eventKey}.wav`, size: wav.length };
+  console.log(`[voice-pack] wrote ${path} (${wav.length} bytes)`);
+}
+writeFileSync(join(OUT_DIR, 'pack.json'), JSON.stringify(manifest, null, 2));
+console.log(`[voice-pack] wrote ${join(OUT_DIR, 'pack.json')}`);

package/scripts/mac-sign.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+
+# macOS 应用签名和公证脚本
+# 使用前请先运行 scripts/check-sign-config.sh 检查证书与环境变量配置
+
+set -e
+
+echo "🔐 macOS 应用签名和公证流程"
+echo "================================"
+echo ""
+
+# 检查必需的环境变量
+if [ -z "$CSC_LINK" ]; then
+  echo "❌ 错误: 缺少 CSC_LINK 环境变量"
+  echo "   请设置为你的 .p12 证书文件路径"
+  exit 1
+fi
+
+if [ -z "$CSC_KEY_PASSWORD" ]; then
+  echo "❌ 错误: 缺少 CSC_KEY_PASSWORD 环境变量"
+  echo "   请设置为你的 .p12 证书密码"
+  exit 1
+fi
+
+echo "✅ 证书配置检查通过"
+echo ""
+
+# 可选：公证配置检查
+if [ -n "$APPLE_ID" ] && [ -n "$APPLE_APP_SPECIFIC_PASSWORD" ] && [ -n "$APPLE_TEAM_ID" ]; then
+  echo "✅ 公证配置检查通过"
+  echo "   应用将在签名后自动公证"
+else
+  echo "⚠️  未配置公证参数，将仅签名不公证"
+  echo "   如需公证，请设置: APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID"
+fi
+
+echo ""
+echo "📦 开始构建和签名..."
+echo ""
+
+# 执行构建
+npm run build && electron-builder --mac
+
+echo ""
+echo "✅ 完成！"
+echo ""
+echo "输出目录: electron-dist/"

package/scripts/npm-pack-dry-run.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const cacheDir = process.env.NPM_CONFIG_CACHE || join(tmpdir(), 'cx-viewer-npm-cache');
+
+// Keep package previews independent from a maintainer's global npm cache state.
+// This avoids false release-check failures caused by root-owned files in ~/.npm.
+const result = spawnSync(
+  'npm',
+  ['pack', '--dry-run', '--cache', cacheDir],
+  {
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+  },
+);
+
+process.exit(result.status ?? 1);

package/server/lib/approval-modal-prefs.js

@@ -0,0 +1,72 @@
+// CLIENT-SAFE: no node deps. Imported by src/ — do not add fs/process/node: imports.
+// Approval-modal preferences merge logic.
+//
+// Lives here (not in voice-pack-manager) because it merges *generic* approvalModal
+// fields (modalEnabled, soundEnabled, notifyOnlyWhenHidden) plus the voicePack subtree.
+// voice-pack-manager.js stays focused on the file/audio backing store.
+//
+// Both server/routes/preferences.js (handles POST /api/preferences) and src/AppBase.jsx (hydrate +
+// handleVoicePackChange) use this so the merge contract is single-sourced.
+
+import { EVENT_KEYS } from './voice-pack-events.js';
+
+// Whitelist guard: only keys from EVENT_KEYS land in the merged events map.
+// Defense-in-depth against a malicious/buggy client posting `{ events: { constructor: ... } }`
+// or other unexpected keys that would persist to preferences.json and surface in
+// dropdown rendering().
+function _filterEvents(events) {
+  if (!events || typeof events !== 'object') return {};
+  const out = {};
+  for (const k of EVENT_KEYS) {
+    if (k in events) out[k] = events[k];
+  }
+  return out;
+}
+
+/**
+ * Deep-merge an incoming voicePack patch into the base voicePack subtree.
+ * Pure function — no I/O, no reconcile. Caller decides whether to run a
+ * reconcile pass over the result.
+ *
+ * Contract:
+ *   - top-level fields (enabled, volume, …) shallow-merged
+ *   - events map merged key-by-key, filtered through EVENT_KEYS whitelist
+ *   - returns a new object; inputs untouched
+ */
+export function mergeVoicePackInto(baseVP, incVP) {
+  const base = (baseVP && typeof baseVP === 'object') ? baseVP : {};
+  if (!incVP || typeof incVP !== 'object') {
+    // Still pass base.events through the whitelist so persisted-but-stale keys
+    // get cleaned up on the next save.
+    return { ...base, events: _filterEvents(base.events) };
+  }
+  const { events: incEvents, ...incRest } = incVP;
+  const mergedEvents = {
+    ..._filterEvents(base.events),
+    ..._filterEvents(incEvents),
+  };
+  return { ...base, ...incRest, events: mergedEvents };
+}
+
+/**
+ * Deep-merge an incoming approvalModal patch into the base approvalModal subtree.
+ * Top-level approvalModal fields shallow-merge; the voicePack subtree goes
+ * through mergeVoicePackInto.
+ *
+ * `reconcile` is an optional callback `(voicePack) => voicePack` — typically
+ * voice-pack-manager.reconcileVoicePackPrefs(logDir, …) — applied to the
+ * merged voicePack to strip references to audio ids that no longer exist on disk.
+ */
+export function mergeApprovalModalPrefs(baseAM, incAM, { reconcile = null } = {}) {
+  if (!incAM || typeof incAM !== 'object') return baseAM;
+  const base = (baseAM && typeof baseAM === 'object') ? baseAM : {};
+  const { voicePack: incVP, ...incAMRest } = incAM;
+  const merged = { ...base, ...incAMRest };
+  if (incVP && typeof incVP === 'object') {
+    merged.voicePack = mergeVoicePackInto(base.voicePack, incVP);
+    if (typeof reconcile === 'function') {
+      merged.voicePack = reconcile(merged.voicePack);
+    }
+  }
+  return merged;
+}

package/server/lib/context-rules.js

@@ -0,0 +1,70 @@
+// CLIENT-SAFE: no node deps. Imported by src/ — do not add fs/process/node: imports.
+//
+// 上下文相关规则唯一事实源(前后端同源):
+//   - 血条总量固定为 CODEX_CONTEXT_WINDOW_TOKENS
+//   - 模型窗口 helper 仅供 workflow 等非血条视图展示模型能力标签
+//
+export const CODEX_CONTEXT_WINDOW_TOKENS = 258000;
+
+// [Nk]/[Nm] 显式窗口后缀,如 gpt-5[1m]、codex-large[200k]、[500k]。
+// 显式 opt-in 优先级最高,胜过一切家族规则。
+const SIZE_SUFFIX_RE = /\[(\d+)([km])\]/i;
+
+/**
+ * 解析模型名里的 [Nk]/[Nm] 窗口后缀。
+ * @param {string} modelName
+ * @returns {number|null} 解析出的窗口 token 数,无后缀返回 null
+ */
+export function parseContextSizeSuffix(modelName) {
+  if (!modelName || typeof modelName !== 'string') return null;
+  const m = modelName.match(SIZE_SUFFIX_RE);
+  if (!m) return null;
+  const num = parseInt(m[1], 10);
+  return m[2].toLowerCase() === 'm' ? num * 1000000 : num * 1000;
+}
+
+// 模型家族 → 窗口档位表(有序,首条命中)。后缀解析在表外先行(见 getModelMaxTokens)。
+// 仅保留稳定且通用的公开模型族粗略估算,避免从旧项目模型名推断 Codex 窗口。
+const MODEL_CONTEXT_SIZES = [
+  { match: /codex/i, tokens: 200000 },
+  { match: /gpt-4o|o1|o3|o4/i, tokens: 128000 },
+  { match: /gpt-4/i, tokens: 128000 },
+  { match: /gpt-3/i, tokens: 16000 },
+  { match: /deepseek/i, tokens: 128000 },
+];
+
+/**
+ * 模型名 → 上下文窗口 token 数。后缀优先,其次家族档位表,默认 200K。
+ * @param {string|null|undefined} modelName
+ * @returns {number}
+ */
+export function getModelMaxTokens(modelName) {
+  if (!modelName) return 200000;
+  const suffix = parseContextSizeSuffix(modelName);
+  if (suffix) return suffix;
+  for (const entry of MODEL_CONTEXT_SIZES) {
+    if (entry.match.test(modelName)) return entry.tokens;
+  }
+  return 200000;
+}
+
+/**
+ * 输入侧上下文用量(不含 output_tokens)。
+ * @param {object|null|undefined} usage
+ * @returns {number}
+ */
+export function sumUsageInputTokens(usage) {
+  if (!usage) return 0;
+  return usage.input_tokens || 0;
+}
+
+/**
+ * 血条分子统一口径:输入侧 + 末轮 output_tokens,对齐 Codex /context 的
+ * "当前上下文占用"语义(末轮回复已进入下一轮上下文)。
+ * @param {object|null|undefined} usage
+ * @returns {number}
+ */
+export function sumUsageContextTokens(usage) {
+  if (!usage) return 0;
+  return sumUsageInputTokens(usage) + (usage.output_tokens || 0);
+}