mingdao-harness 0.1.54

package/src/permissions.js

@@ -0,0 +1,83 @@
+// 权限引擎（借鉴 codewhale 的 execpolicy 独立分层思想）。
+//
+// 三种模式：
+//  - ask      默认。只读工具自动放行；写文件/执行命令逐次询问。
+//  - auto     全部自动允许（完全自主，注意风险）。
+//  - readonly 只允许只读工具。
+// config.permission 也可以是对象：
+//  { mode: 'ask', allow: ['bash', 'bash:git *'], deny: ['write'] }
+//  规则支持「工具名」或「工具名:参数前缀」模式匹配（* 通配）。
+// check(name, args, label)：label 用于区分执行方（如子代理的「（子任务）」前缀）。
+
+import { style, C } from './ui.js';
+import { READONLY_TOOLS } from './tools/index.js';
+
+function summarize(name, args) {
+  try {
+    if (name === 'bash') return ` ${args.command ?? ''}`;
+    if (args.path) return ` ${args.path}`;
+    return '';
+  } catch {
+    return '';
+  }
+}
+
+function ruleMatches(rule, name, args) {
+  const idx = rule.indexOf(':');
+  if (idx > 0) {
+    const ruleName = rule.slice(0, idx);
+    if (ruleName !== name) return false;
+    const want = rule.slice(idx + 1).trim();
+    const have = summarize(name, args).trim();
+    // bash 前缀规则防链式命令绕过：含 && / ; / | / ` / $( 的复合命令不匹配前缀规则，回落权限确认
+    if (name === 'bash' && /&&|\|\||[;|`]|\$\(|\n/.test(have)) return false;
+    if (want.endsWith('*')) return have.startsWith(want.slice(0, -1));
+    return have === want;
+  }
+  return rule === name;
+}
+
+export function createPermission(rawMode, io) {
+  let mode = 'ask';
+  let allow = [];
+  let deny = [];
+  if (typeof rawMode === 'string') {
+    mode = rawMode;
+  } else if (rawMode && typeof rawMode === 'object') {
+    mode = rawMode.mode ?? 'ask';
+    allow = rawMode.allow ?? [];
+    deny = rawMode.deny ?? [];
+  }
+  if (!['ask', 'auto', 'readonly'].includes(mode)) mode = 'ask';
+
+  return {
+    mode,
+    async check(name, args = {}, label = '') {
+      const askOverride = async (question) => {
+        try {
+          const answer = await io.ask(style(question, C.yellow));
+          return /^y(es)?$/i.test(answer);
+        } catch {
+          return false; // 交互通道不可用（管道 EOF/静默 worker）：按拒绝处理
+        }
+      };
+      // 需要特殊授权时弹出对话框与用户交互，而不是静默拒绝：
+      // 1) 被 deny 规则拦截 → 询问是否本次强制放行
+      if (deny.some((r) => ruleMatches(r, name, args))) {
+        return askOverride(`规则拦截了 ${name}${summarize(name, args)}，是否本次强制放行？[y/N] `);
+      }
+      if (allow.some((r) => ruleMatches(r, name, args))) return true;
+      if (mode === 'auto') return true;
+      if (mode === 'readonly') {
+        // 2) 只读模式下的写操作 → 询问是否本次放行
+        if (READONLY_TOOLS.has(name)) return true;
+        return askOverride(`只读模式将拦截 ${name}${summarize(name, args)}，是否本次放行？[y/N] `);
+      }
+      if (READONLY_TOOLS.has(name)) return true;
+      const answer = await io.ask(
+        style(`是否允许执行 ${label}${C.bold}${name}${C.reset}${summarize(name, args)} ？[y/N] `, C.yellow)
+      );
+      return /^y(es)?$/i.test(answer);
+    },
+  };
+}

package/src/pricing.js

@@ -0,0 +1,156 @@
+// 费用估算：统一计价逻辑（cli /status、/cost 与 ui/web 状态行共用）。
+// DeepSeek V4 缓存感知计价：usage 提供 prompt_cache_hit_tokens / prompt_cache_miss_tokens 时，
+// 命中部分按 cacheHit 价（约为未命中的 1/30），未命中按 input 价；否则按全未命中（保守上界）。
+// 价格覆盖（P3-10）：config.json 的 pricing.overrides.<模型名> 可覆盖内置价格表，
+//   结构 { input, output, cacheHit, peak?: { input, output, cacheHit } }（单位：元/百万 tokens）。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { modelPreset } from './models.js';
+import { mingdaoHome } from './config.js';
+
+// 内置价格表的数据时点（定价可能调整，配置覆盖可随时更新）
+export const PRICE_DATA_AS_OF = '2026-08';
+
+// 峰谷判断锚定北京时间（评估 P0-4：DeepSeek 按北京时间 9:00–14:00 高峰计价，
+// 用本机时区判断会让海外用户计费错位）。config.pricing.timezone 可覆盖，mtime 缓存避免每次读盘。
+let tzCache = { mtime: 0, timezone: 'Asia/Shanghai' };
+function peakTimezone() {
+  try {
+    const file = path.join(mingdaoHome(), 'config.json');
+    const st = fs.statSync(file);
+    if (st.mtimeMs !== tzCache.mtime) {
+      const cfg = JSON.parse(fs.readFileSync(file, 'utf8'));
+      tzCache = { mtime: st.mtimeMs, timezone: String(cfg?.pricing?.timezone || 'Asia/Shanghai') };
+    }
+  } catch {}
+  return tzCache.timezone;
+}
+
+export function isPeakHour(date = new Date()) {
+  try {
+    const parts = new Intl.DateTimeFormat('en-US', {
+      timeZone: peakTimezone(),
+      weekday: 'short',
+      hour: 'numeric',
+      hourCycle: 'h23',
+    }).formatToParts(date);
+    const weekday = parts.find((p) => p.type === 'weekday')?.value;
+    // 周末全天按闲时计价（DeepSeek 官方邮件确认：周六/周日全天闲时低价，批量任务周末更划算）
+    if (weekday === 'Sat' || weekday === 'Sun') return false;
+    const hour = Number(parts.find((p) => p.type === 'hour')?.value);
+    return hour >= 9 && hour < 14;
+  } catch {
+    return date.getHours() >= 9 && date.getHours() < 14; // 非法时区回退本机
+  }
+}
+
+// —— 北京时间墙钟工具（避峰调度/费用护栏按天统计用，零依赖 Intl） ——
+export function beijingParts(date = new Date()) {
+  let tz = 'Asia/Shanghai';
+  try {
+    tz = peakTimezone();
+    new Intl.DateTimeFormat('en-US', { timeZone: tz }).format(); // 非法时区在此抛错
+  } catch {
+    tz = 'Asia/Shanghai'; // 审计 B1：坏时区配置回退北京时间，绝不让计费/护栏崩溃
+  }
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone: tz,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hourCycle: 'h23',
+  }).formatToParts(date);
+  const g = (t) => Number(parts.find((p) => p.type === t)?.value);
+  return { year: g('year'), month: g('month'), day: g('day'), hour: g('hour'), minute: g('minute'), second: g('second') };
+}
+
+// 北京时间墙钟 → Date（UTC+8）
+export function beijingToDate(parts) {
+  return new Date(Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second) - 8 * 3600 * 1000);
+}
+
+// 避峰：当前处于高峰（9:00–14:00）→ 顺延到当天 14:00；否则原时刻
+export function deferToOffpeak(date = new Date()) {
+  if (!isPeakHour(date)) return date;
+  const p = beijingParts(date);
+  return beijingToDate({ ...p, hour: 14, minute: 0, second: 0 });
+}
+
+// 北京时间当日 0 点（费用护栏按自然日累计）
+export function beijingDayStart(date = new Date()) {
+  const p = beijingParts(date);
+  return beijingToDate({ ...p, hour: 0, minute: 0, second: 0 });
+}
+
+// —— Batch API 半价计价：批量任务无缓存语义，按闲时全未命中 × 0.5 ——
+export const BATCH_DISCOUNT = 0.5;
+export function estimateBatchCost(modelName, promptTokens, completionTokens) {
+  const pricing = effectivePricing(modelName);
+  if (!pricing) return 0;
+  return ((promptTokens * pricing.offpeak.input + completionTokens * pricing.offpeak.output) / 1e6) * BATCH_DISCOUNT;
+}
+
+// usage 中的缓存拆分（DeepSeek 返回字段）
+export function cacheSplit(usage) {
+  const hit = usage?.prompt_cache_hit_tokens;
+  const miss = usage?.prompt_cache_miss_tokens;
+  if (Number.isFinite(hit) && Number.isFinite(miss)) {
+    return { hit, miss, rate: hit + miss > 0 ? hit / (hit + miss) : 0 };
+  }
+  return null;
+}
+
+// 合并内置价与用户覆盖：offpeak 字段覆盖 offpeak，over.peak 覆盖 peak（缺省沿用 offpeak）
+let overridesCache = { mtime: 0, overrides: {} };
+function pricingOverrides() {
+  try {
+    const file = path.join(mingdaoHome(), 'config.json');
+    const st = fs.statSync(file);
+    if (st.mtimeMs !== overridesCache.mtime) {
+      const cfg = JSON.parse(fs.readFileSync(file, 'utf8'));
+      overridesCache = { mtime: st.mtimeMs, overrides: cfg?.pricing?.overrides || {} };
+    }
+  } catch {}
+  return overridesCache.overrides;
+}
+function effectivePricing(modelName) {
+  const preset = modelPreset(modelName);
+  if (!preset?.pricing) return null;
+  const over = pricingOverrides()[modelName] || {}; // 审计 Q3：mtime 缓存替代每轮读盘
+  const merge = (base, o = {}) => ({
+    input: Number(o.input ?? base?.input ?? 0),
+    output: Number(o.output ?? base?.output ?? 0),
+    cacheHit: Number(o.cacheHit ?? base?.cacheHit ?? 0),
+  });
+  return {
+    offpeak: merge(preset.pricing.offpeak, over),
+    peak: merge(preset.pricing.peak || preset.pricing.offpeak, over.peak),
+  };
+}
+
+export function estimateCost(modelName, promptTokens, completionTokens, cache = null, date = new Date()) {
+  const pricing = effectivePricing(modelName);
+  if (!pricing) return 0;
+  const price = isPeakHour(date) ? pricing.peak : pricing.offpeak;
+  if (cache && Number.isFinite(cache.hit) && Number.isFinite(cache.miss)) {
+    const hitPrice = price.cacheHit ?? 0;
+    // 网关 hit+miss 与 prompt_tokens 口径不一致时，余量按未命中计价，避免漏计
+    const miss = cache.miss + Math.max(0, promptTokens - cache.hit - cache.miss);
+    return (cache.hit * hitPrice + miss * price.input + completionTokens * price.output) / 1e6;
+  }
+  return (promptTokens * price.input + completionTokens * price.output) / 1e6;
+}
+
+export function estimateCostLabel(modelName, promptTokens, completionTokens, usage = null) {
+  const pricing = effectivePricing(modelName);
+  if (!pricing) return '';
+  const cache = cacheSplit(usage);
+  const yuan = estimateCost(modelName, promptTokens, completionTokens, cache).toFixed(5);
+  const hitPart =
+    cache && cache.hit + cache.miss > 0 ? ` · 缓存命中 ${(cache.rate * 100).toFixed(0)}%` : ' · 未计缓存折扣';
+  return ` ≈¥${yuan}（${isPeakHour() ? '高峰' : '闲时'}${hitPart}）`;
+}

package/src/prompts.js

@@ -0,0 +1,58 @@
+// 系统提示词构建：基础角色 + 用户记忆 + 技能清单 + 项目 AGENTS.md。
+// 借鉴 Claude Code 的记忆文件与 Codex 的技能渐进披露约定。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { skillsRegistryBlock } from './skills.js';
+import { mingdaoHome } from './config.js';
+import { recentJournalBlock } from './memory.js';
+
+const BASE = `你是 MingDao（明道），一个由 MingDao-Harness 驱动的 AI 编程助手。你在用户的电脑上工作：通过工具读写文件、搜索代码、执行命令，帮助用户完成编程、调试与自动化任务。
+
+工作准则：
+1. 先了解再动手：修改或创建代码前，先用 read / ls / glob / grep 查看相关文件，不要凭空猜测。
+2. 精准修改：优先用 edit 做小步精确替换；新建文件用 write；保持改动最小化；改错可用 undo 撤销。
+3. 任务管理：多步骤任务先建 todo 清单并逐项更新；与技能（skill）相关的任务先加载对应 SKILL.md。
+4. 委托与专注：独立、可并行的子问题（调研、复核、独立实现）用 task 委托子代理，把结果拿回来继续主线。
+5. 命令谨慎：执行 bash 前想清楚影响；命令失败时阅读错误输出并修复，同一问题最多重试 3 次。
+6. 回答风格：使用用户的语言（默认中文），简洁直接，先结论后说明。
+7. 诚实可靠：不编造不存在的文件、行号、API 或执行结果。
+8. 善用工具：能用工具确认的事实就用工具确认；多个只读工具可连续调用以提高效率。
+9. 交付收尾：完成工具操作后必须给出简短交付总结——生成了哪些文件（路径）、如何运行/使用（如「浏览器打开 angry-birds.html 即可游玩」或运行命令）、以及未完成或注意事项（若有）。绝不能不声不响结束。`;
+
+function loadFile(p, cap) {
+  try {
+    const s = fs.readFileSync(p, 'utf8');
+    return s.length > cap ? s.slice(0, cap) + '\n…[过长已截断]' : s;
+  } catch {
+    return null;
+  }
+}
+
+export function buildSystemPrompt({ workingDir, withJournal = false }) {
+  // 前缀字节稳定性（评估 P1-1/P1-2，四份评估一致的最高价值项）：
+  // 系统提示不含「当前模型」「当前日期」等易变字段——DeepSeek 上下文缓存按前缀字节匹配，
+  // 路由 pro⇄flash 翻转或跨天会改变前缀 → 整段历史按未命中价重计（命中价的 30 倍）。
+  // 现在同一工作空间内系统提示恒定（记忆/技能/AGENTS.md 只在用户显式改动时变化）。
+  let prompt = `${BASE}
+
+当前工作目录：${workingDir}`;
+
+  // 用户级记忆（~/.mingdao/AGENTS.md，/memory add 手动追加 + 会话结束自动提炼）
+  const memory = loadFile(path.join(mingdaoHome(), 'AGENTS.md'), 8000);
+  if (memory) prompt += `\n\n<user_memory>\n${memory}\n</user_memory>`;
+
+  // 最近会话日志（跨会话连续性）：默认不注入——新会话应当全新开始，避免串到
+  // 上一次会话的上下文（曾出现「新会话却接着给上个会话的游戏升级」的混淆）。
+  // 仅当用户显式开启时注入（WebUI 勾选「带上文」/ CLI --journal）。
+  if (withJournal) prompt += recentJournalBlock(mingdaoHome());
+
+  // 技能清单（渐进披露：仅名称+描述，按需加载全文）
+  prompt += skillsRegistryBlock(workingDir);
+
+  // 项目约定（./AGENTS.md）
+  const agentsMd = loadFile(path.join(workingDir, 'AGENTS.md'), 20000);
+  if (agentsMd) prompt += `\n\n<agents_md>\n${agentsMd}\n</agents_md>`;
+
+  return prompt;
+}

package/src/providers/index.js

@@ -0,0 +1,135 @@
+// Provider 注册表与工厂。
+//
+// 接入模型的三条路：
+// 1. 内置 OpenAI 兼容端点 —— 在 config 里配 baseUrl/apiKey 即可（覆盖绝大多数模型）；
+// 2. 内置服务商预设 —— deepseek / openai / qwen / glm / moonshot / custom；
+// 3. 自定义 Provider 模块 —— 在 <mingdao-home>/providers/<name>.mjs 中
+//    export async function createProvider(cfg)，返回 { chat(opts) }。
+//    适合 Anthropic 原生协议、本地推理框架等非 OpenAI 兼容场景。
+// 详见 docs/PROVIDERS.md。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { chat as openaiChat } from './openai-compatible.js';
+import { modelPreset, providerPreset } from '../models.js';
+import { mingdaoHome } from '../config.js';
+import { resolveApiKey } from '../credentials.js';
+
+export function resolveProviderConfig(cfg, modelName) {
+  // 自定义模型（config.customModels，WebUI 可增删改）：优先于内置预设
+  const cm = cfg?.customModels?.[modelName];
+  if (cm) {
+    const envKeys = [cm.envKey, 'MINGDAO_API_KEY'].filter(Boolean);
+    const apiKey = resolveApiKey(cfg, `custom:${modelName}`, envKeys[0]) || resolveApiKey(cfg, 'custom', envKeys[0]);
+    return {
+      name: `custom:${modelName}`,
+      kind: 'openai-compatible',
+      baseUrl: cm.baseUrl || cfg?.baseUrl || '',
+      apiKey,
+      envHint: envKeys[0] || 'MINGDAO_API_KEY',
+      isCustom: true,
+      modelName,
+    };
+  }
+  const preset = modelPreset(modelName);
+  const name = preset?.provider || cfg?.provider || 'deepseek';
+  const pp = providerPreset(name) || { kind: 'openai-compatible' };
+  const baseUrl = cfg?.baseUrl || pp.baseUrl || '';
+  const apiKey = resolveApiKey(cfg, name, pp.envKey);
+  return {
+    name,
+    kind: pp.kind || 'openai-compatible',
+    baseUrl,
+    apiKey,
+    envHint: pp.envKey || 'MINGDAO_API_KEY',
+    isCustom: !providerPreset(name),
+  };
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function isTransient(err) {
+  const status = err?.status;
+  if (status === 429 || (status >= 500 && status <= 504)) return true;
+  // 注意：不含 abort —— 用户 Ctrl+C 主动中断不应触发重试
+  return /timeout|超时|ECONNRESET|fetch failed/i.test(String(err?.message || ''));
+}
+
+export async function createProvider(cfg, modelName, { timeoutMs = 300000, retries = 2 } = {}) {
+  const pc = resolveProviderConfig(cfg, modelName);
+
+  // 自定义 Provider 模块优先（仅普通自定义端点；custom:<模型名> 走 OpenAI 兼容直连）
+  const customFile = path.join(mingdaoHome(), 'providers', pc.name + '.mjs');
+  if (pc.isCustom && !pc.name.includes(':') && fs.existsSync(customFile)) {
+    const mod = await import(pathToFileURL(customFile).href + `?v=${Date.now()}`);
+    if (typeof mod.createProvider !== 'function') {
+      throw new Error(`自定义 Provider 模块 ${customFile} 未导出 createProvider(cfg)。`);
+    }
+    const custom = await mod.createProvider(pc);
+    return { ...custom, name: pc.name, config: pc };
+  }
+
+  if (!pc.baseUrl) {
+    throw new Error(`服务商 "${pc.name}" 缺少 baseUrl，请运行 mingdao init 重新配置。`);
+  }
+
+  return {
+    name: pc.name,
+    config: pc,
+    async chat(opts) {
+      let attempt = 0;
+      for (;;) {
+        const ac = new AbortController();
+        let timedOut = false; // 审计 P2-6：用标志而非 name/字符串匹配识别内部超时
+        const timer = setTimeout(() => {
+          timedOut = true;
+          ac.abort(new Error('请求超时'));
+        }, timeoutMs);
+        // 转发外部信号（用户 Ctrl+C 中断），避免被内部超时信号覆盖
+        const onUserAbort = () => ac.abort(opts.signal?.reason);
+        if (opts.signal?.aborted) onUserAbort();
+        else opts.signal?.addEventListener('abort', onUserAbort, { once: true });
+        try {
+          return await openaiChat({
+            ...opts,
+            baseUrl: pc.baseUrl,
+            apiKey: pc.apiKey,
+            signal: ac.signal,
+            includeUsage: cfg?.includeUsage !== false,
+          });
+        } catch (err) {
+          // 内部超时经 abort 抛出，用标志识别（审计 P2-6）；用户 Ctrl+C 的中断不算超时、不重试
+          const transient = (timedOut && !opts.signal?.aborted) || isTransient(err);
+          if (!transient || attempt >= retries) throw err;
+          attempt += 1;
+          // 指数退避 + 尊重 Retry-After（评估 P3-1）：基础 1s/2s，服务端指定时取其值（封顶 30s）
+          let backoff = 1000 * attempt;
+          const ra = Number(err?.headers?.get?.('retry-after'));
+          if (Number.isFinite(ra) && ra > 0) backoff = Math.max(backoff, ra * 1000);
+          backoff = Math.min(backoff, 30000);
+          await sleep(backoff);
+        } finally {
+          clearTimeout(timer);
+          opts.signal?.removeEventListener('abort', onUserAbort);
+        }
+      }
+    },
+  };
+}
+
+// 辅助调用（标题生成/记忆提取等）的 provider 解析（评估 P2-2）：辅助模型与当前模型
+// 分属不同服务商时单独创建 provider——避免拿 deepseek-v4-flash 模型名去自定义网关请求
+// 而 404 被静默吞掉（标题缺失、记忆永不沉淀且零感知）。
+export async function helperProvider(cfg, helperModel, currentProvider) {
+  try {
+    const curName = String(currentProvider?.name || '');
+    const helperName = String(resolveProviderConfig(cfg, helperModel)?.name || '');
+    if (curName && curName === helperName) return currentProvider;
+  } catch {}
+  try {
+    return await createProvider(cfg, helperModel);
+  } catch {
+    return currentProvider;
+  }
+}

package/src/providers/openai-compatible.js

@@ -0,0 +1,171 @@
+// OpenAI 兼容协议的 HTTP + SSE 流式客户端。
+// DeepSeek、OpenAI、Qwen、GLM、Moonshot 以及绝大多数模型网关都走这一层。
+
+/**
+ * API 错误：Error 附带 HTTP 状态码与响应头（重试退避读 Retry-After 用）。
+ * @typedef {Error & { status?: number, headers?: Headers }} ApiError
+ */
+
+export async function chat({ baseUrl, apiKey, model, messages, tools, temperature, maxTokens, signal, onDelta, includeUsage = true, responseFormat }) {
+  const url = String(baseUrl).replace(/\/+$/, '') + '/chat/completions';
+  const payload = { model, messages };
+  if (temperature != null) payload.temperature = temperature;
+  if (tools && tools.length) {
+    payload.tools = tools;
+    payload.tool_choice = 'auto';
+  }
+  if (maxTokens) payload.max_tokens = maxTokens;
+  if (responseFormat) payload.response_format = responseFormat;
+  payload.stream = true;
+  // 流式响应默认不带 usage，显式请求以便展示 token/费用统计
+  // （部分网关不支持该字段，可在 config.json 设 "includeUsage": false 关闭）
+  if (includeUsage) payload.stream_options = { include_usage: true };
+
+  let res;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
+      body: JSON.stringify(payload),
+      signal,
+    });
+  } catch (err) {
+    /** @type {ApiError} */
+    const e = new Error(`网络请求失败：${err?.message || err}`);
+    e.status = 0;
+    throw e;
+  }
+
+  if (!res.ok) {
+    const raw = await res.text().catch(() => '');
+    let detail = raw.slice(0, 400);
+    try {
+      const j = JSON.parse(raw);
+      if (j?.error?.message) detail = j.error.message;
+    } catch {}
+    /** @type {ApiError} */
+    const e = new Error(`[${model}] API 错误 ${res.status}: ${detail}`);
+    e.status = res.status;
+    e.headers = res.headers; // 重试退避读取 Retry-After 用
+    throw e;
+  }
+
+  const contentType = res.headers.get('content-type') || '';
+  if (!contentType.includes('text/event-stream')) {
+    const json = await res.json().catch(() => null);
+    if (!json) throw new Error(`[${model}] 响应解析失败。`);
+    return parseNonStream(json, onDelta);
+  }
+  return parseStream(res.body, onDelta);
+}
+
+export function parseNonStream(json, onDelta) {
+  const choice = json?.choices?.[0];
+  const msg = choice?.message ?? {};
+  if (msg.content) onDelta?.({ text: msg.content });
+  if (msg.reasoning_content) onDelta?.({ reasoning: msg.reasoning_content });
+  const toolCalls = msg.tool_calls?.length ? msg.tool_calls : null;
+  return {
+    text: msg.content ?? '',
+    reasoning: msg.reasoning_content ?? '',
+    toolCalls,
+    usage: json?.usage ?? null,
+    finish: choice?.finish_reason ?? null,
+  };
+}
+
+// 解析 SSE 流：处理跨 chunk 断行、增量 content / reasoning_content / tool_calls。
+export async function parseStream(body, onDelta) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buf = '';
+  let content = '';
+  let reasoning = '';
+  const calls = new Map(); // key -> {id, name, args}（优先用 id，无 id 时按 index，再兜底自增）
+  const indexKeys = new Map(); // index -> key（id 只在首片出现，后续分片按 index 找回同一条目）
+  let autoKey = 0;
+  let usage = null;
+  let finish = null;
+
+  let doneFlag = false;
+  const handleLine = (lineRaw) => {
+    const line = lineRaw.trim();
+    if (!line.startsWith('data:')) return;
+    const data = line.slice(5).trim();
+    if (data === '[DONE]') {
+      finish = finish || 'stop';
+      doneFlag = true;
+      return true; // 通知外层终止读取（审计 P2-4：[DONE] 后不再消费残帧、不挂到超时）
+    }
+    let json;
+    try {
+      json = JSON.parse(data);
+    } catch {
+      return;
+    }
+    // 注意：DeepSeek/OpenAI 流式最后一块常是 usage-only（choices 为空），必须先取 usage 再判 choices
+    if (json.usage) usage = json.usage;
+    const choice = json?.choices?.[0];
+    if (!choice) return;
+    const d = choice.delta ?? {};
+    if (d.content && !doneFlag) {
+      content += d.content;
+      onDelta?.({ text: d.content });
+    }
+    if (d.reasoning_content && !doneFlag) {
+      reasoning += d.reasoning_content;
+      onDelta?.({ reasoning: d.reasoning_content });
+    }
+    if (Array.isArray(d.tool_calls)) {
+      for (const tc of d.tool_calls) {
+        let key;
+        if (tc.id) key = `id:${tc.id}`;
+        else if (tc.index != null && indexKeys.has(tc.index)) key = indexKeys.get(tc.index);
+        else key = `idx-${tc.index != null ? tc.index : autoKey++}`;
+        if (tc.index != null) indexKeys.set(tc.index, key);
+        let cur = calls.get(key);
+        if (!cur) {
+          cur = { id: tc.id ?? '', name: '', args: '' };
+          calls.set(key, cur);
+        }
+        if (tc.id) cur.id = tc.id;
+        // 部分网关会重复下发完整 name：保留最长版本，避免重复拼接
+        if (tc.function?.name && tc.function.name.length > cur.name.length) cur.name = tc.function.name;
+        if (tc.function?.arguments) cur.args += tc.function.arguments;
+      }
+    }
+    if (choice.finish_reason) finish = choice.finish_reason;
+  };
+
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buf += decoder.decode(value, { stream: true });
+    let nl;
+    while ((nl = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, nl);
+      buf = buf.slice(nl + 1);
+      if (handleLine(line)) break;
+    }
+  }
+  // 收尾：残行（网关最后一帧不带换行）与多字节字符冲刷
+  content += decoder.decode();
+  if (buf.trim()) handleLine(buf); // [DONE] 后残留 usage 尾帧仍吸收（正文/推理已被 doneFlag 拦截）
+
+  const toolCalls = [...calls.entries()]
+    .sort((a, b) => {
+      const na = Number(String(a[0]).replace(/^idx-/, ''));
+      const nb = Number(String(b[0]).replace(/^idx-/, ''));
+      // 无 id 的 idx-N 按数字排序（审计 P2-5：idx-10 应在 idx-2 之后而非之前）
+      if (Number.isFinite(na) && Number.isFinite(nb)) return na - nb;
+      return String(a[0]).localeCompare(String(b[0]));
+    })
+    .map(([, c]) => ({
+      id: c.id || `call_${c.name || 'x'}`,
+      type: 'function',
+      function: { name: c.name, arguments: c.args || '{}' },
+    }))
+    .filter((c) => c.function.name);
+
+  return { text: content, reasoning, toolCalls: toolCalls.length ? toolCalls : null, usage, finish };
+}