@huicai/cli 0.5.1

package/src/agent.js

@@ -0,0 +1,348 @@
+// 客户端 Agent 循环：以平台 /v1 为模型后端，模型决定调哪个工具，工具在本机执行，结果回灌，直至无工具调用。
+// 核心机制：循环与工具都在客户端，平台只做模型推理与计费。
+//
+// 两种运行形态（按 config.model 自动判定）：
+//  - 原始模型：本机工具循环（内置文件/命令工具 + todo_write + memory_write + extraTools[MCP/子智能体]）；
+//  - 伪模型 agent-/workflow-/datahuman-：平台编排直连（不传 tools，纯流式多轮）——即智能体/数字人/工作流
+//    分享页的对话能力，CLI/扩展/REPL/TUI 全部可用。
+//
+// 关键机制：
+//  - 连续的只读工具调用并行执行（结果仍按原顺序回灌）；
+//  - 工具输出截断保头尾注入上下文；工具参数 JSON 解析失败时把错误回灌模型（而非静默空参数）；
+//  - 中断时为未执行的 tool_calls 合成占位结果（协议配对完整）；
+//  - pullQueued：用户回合中排队的消息在工具轮间隙/回合末注入；
+//  - 思考过程（reasoning）流式上抛（events.onReasoning / REPL 灰字），config.showReasoning=false 关闭；
+//  - 上下文压缩为**非破坏式**：摘要存 compaction 状态（随会话持久化），原消息/页面显示不受影响，
+//    仅发给模型时经 buildModelMessages 组装视图；
+//  - 文本化工具调用防泄漏（与平台侧同款）：模型把工具调用写成纯文本标记时（DeepSeek 系退化）
+//    过滤不显示、不进会话，并注入纠正指令重试（一次要求改走 tool_calls 通道，二次禁工具强制作答）。
+
+import { streamChat } from './api.js';
+import { MarkupFilter, stripMarkup } from './markup-filter.js';
+import { TOOL_SPECS, READONLY_TOOLS, runTool } from './tools.js';
+import { toolLabel, indent } from './render.js';
+import { compactIfNeeded, buildModelMessages } from './compaction.js';
+import { makeTodoTool, formatTodos, TODO_TOOL_NAME } from './todo.js';
+import { makeMemoryTool } from './memory.js';
+import * as ide from './ide.js';
+import { c } from './colors.js';
+
+const DEFAULT_MAX_ITERS = 60;
+const MAX_TOOL_RESULT_CHARS = 20_000;
+const CAP_HEAD = 16_000;
+const CAP_TAIL = 3_000;
+
+// 「文本化工具调用」被拦截后的纠正指令：与平台侧 ToolCallingOrchestrator 同款两级策略。
+// 第一次：要求改走规范 tool_calls 通道重试；第二次：禁用工具、强制直接作答（保证用户拿到干净答复）。
+const MARKUP_RETRY_PROMPT =
+  '你刚才的输出把工具调用写成了文本标记，工具并未被执行，该内容也不会展示给用户。'
+  + '请重新处理：若需调用工具，必须使用规范的函数调用（tool_calls）通道发起，'
+  + '绝不要以任何文本形式书写工具调用标记；若无需工具，请直接用中文输出面向用户的最终答复。';
+const MARKUP_FORCE_ANSWER_PROMPT =
+  '请停止调用任何工具。基于目前已获得的全部信息，直接用中文输出面向用户的完整最终答复，'
+  + '不要输出任何工具调用或协议标记。';
+
+/** 伪模型（平台编排）判定：agent-/workflow-/datahuman- 前缀。 */
+export function isPlatformModel(model) {
+  return /^(agent|workflow|datahuman)-/.test(String(model || ''));
+}
+
+function shortLine(s, max = 200) {
+  const first = String(s).split('\n')[0];
+  return first.length > max ? first.slice(0, max) + '…' : first;
+}
+
+/** 工具输出超长时截断（保头尾），防止单条结果撑爆上下文。 */
+export function capToolResult(text) {
+  const s = String(text);
+  if (s.length <= MAX_TOOL_RESULT_CHARS) return s;
+  const omitted = s.length - CAP_HEAD - CAP_TAIL;
+  return s.slice(0, CAP_HEAD) + `\n…【工具输出过长，中间已省略 ${omitted} 字符】…\n` + s.slice(-CAP_TAIL);
+}
+
+/**
+ * 跑一个用户回合：mutate messages（追加 assistant/tool 消息），流式打印正文与工具进展。
+ *
+ * @param {object} p
+ * @param {{spec:object,run:Function,readOnly:boolean}[]} [p.extraTools] 动态外部工具（MCP / 子智能体）
+ * @param {number} [p.depth] 子智能体递归深度（0=顶层；todo/memory 仅顶层提供）
+ * @param {{write:(s:string)=>void}} [p.io] 输出通道（子智能体传静默通道）
+ * @param {object} [p.events] 结构化事件：onDelta/onReasoning/onAssistantText/onToolStart/onToolResult/onSkip/onInfo/onTodo/onMemory/onTurnEnd
+ * @param {{list:any[]}} [p.todoState] 任务清单状态（调用方持有可跨轮保留）
+ * @param {{upTo?:number, summary?:string}} [p.compaction] 压缩状态（随会话持久化；原消息不被修改）
+ * @param {() => (string|null)} [p.pullQueued] 取一条用户排队消息（无则 null）
+ * @param {number} [p.maxIters] 本回合最大工具轮数（默认 config.maxTurns 或 60）
+ * @returns {Promise<{aborted?:boolean, error?:string, usage:{prompt:number,completion:number}, lastPromptTokens:number}>}
+ */
+export async function runTurn({
+  config, messages, permissions, cwd, ask, signal,
+  extraTools = [], depth = 0, io, events, todoState, compaction, pullQueued, maxIters,
+}) {
+  const out = (io && io.write) || ((s) => process.stdout.write(s));
+  const ev = events || null; // 结构化事件（ink TUI / 扩展用）；为空则走 out() 字符串输出（普通 REPL）
+  const info = (t) => {
+    if (ev) ev.onInfo?.(t);
+    else out(c.gray('  · ' + t) + '\n');
+  };
+  let prompt = 0;
+  let completion = 0;
+  let lastPromptTokens = 0;
+  const iterMax = Number(maxIters || config.maxTurns) || DEFAULT_MAX_ITERS;
+  const platformMode = isPlatformModel(config.model);
+  const compState = compaction || {}; // 未传则本回合内独立生效（不持久化）
+
+  // 顶层注入 todo_write / memory_write（平台编排模式无本机工具，均不注入）
+  const dynamicTools = [...extraTools];
+  if (depth === 0 && !platformMode && !dynamicTools.some((t) => t.spec?.function?.name === TODO_TOOL_NAME)) {
+    const state = todoState || { list: [] };
+    dynamicTools.push(
+      makeTodoTool({
+        state,
+        emit: (list) => {
+          if (ev) {
+            if (ev.onTodo) ev.onTodo(list.map((t) => ({ ...t })));
+            else ev.onInfo?.('任务清单：\n' + formatTodos(list));
+          } else {
+            out(c.gray(indent(formatTodos(list), '  ')) + '\n');
+          }
+        },
+      }),
+    );
+  }
+  if (depth === 0 && !platformMode && config.memoryEnabled !== false
+    && !dynamicTools.some((t) => t.spec?.function?.name === 'memory_write')) {
+    dynamicTools.push(
+      makeMemoryTool({
+        cwd,
+        emit: (t) => {
+          if (ev) {
+            if (ev.onMemory) ev.onMemory(t);
+            else ev.onInfo?.('已记入长期记忆：' + shortLine(t, 80));
+          } else {
+            out(c.gray('  ✎ 已记入长期记忆：' + shortLine(t, 80)) + '\n');
+          }
+        },
+      }),
+    );
+  }
+
+  const extraByName = new Map();
+  for (const t of dynamicTools) extraByName.set(t.spec.function.name, t);
+  const specs = platformMode ? undefined : [...TOOL_SPECS, ...dynamicTools.map((t) => t.spec)];
+
+  let markupRetries = 0; // 「文本化工具调用」纠正次数（首次要求改走 tool_calls 通道，二次禁工具收敛）
+  let toolsDisabled = false;
+  let correction = null; // 待注入的纠正指令：仅随本轮请求发给模型，不进会话记录（与平台侧临时 convo 等价）
+
+  for (let iter = 0; iter < iterMax; iter++) {
+    // 非破坏式上下文压缩：仅更新 compState（摘要独立存储），messages/页面内容不动
+    const compacted = await compactIfNeeded(messages, config, { state: compState, lastPromptTokens });
+    if (compacted > 0) info(`已压缩上下文（${compacted} 条较早消息已摘要，页面与会话记录不受影响）`);
+
+    let streamedAny = false;
+    let streamedReason = false;
+    const mf = new MarkupFilter(); // 文本化工具标记防泄漏：每轮模型输出独立实例
+    const emitDelta = (t) => {
+      if (!t) return;
+      if (!streamedAny && streamedReason && !ev) out('\n'); // 思考→正文换行
+      streamedAny = true;
+      if (ev) ev.onDelta?.(t);
+      else out(t);
+    };
+    const modelMessages = buildModelMessages(messages, compState);
+    let res;
+    try {
+      res = await streamChat(
+        {
+          baseUrl: config.baseUrl,
+          apiKey: config.apiKey,
+          model: config.model,
+          messages: correction ? [...modelMessages, { role: 'user', content: correction }] : modelMessages,
+          tools: toolsDisabled ? undefined : specs,
+          // 对话落库审计：来源与会话号（由 config 透传；扩展侧为 vscode）
+          client: config.client,
+          sessionId: config.sessionId,
+        },
+        {
+          onContent: (t) => emitDelta(mf.feed(t)),
+          onReasoning: (t) => {
+            if (config.showReasoning === false) return;
+            if (ev) {
+              ev.onReasoning?.(t);
+            } else {
+              if (!streamedReason) out(c.gray('\n[思考] '));
+              out(c.gray(t));
+            }
+            streamedReason = true;
+          },
+          onRetry: (n, waitMs, reason) => info(`模型响应异常，${Math.round(waitMs / 1000)}s 后自动重试（第 ${n} 次）：${reason}`),
+        },
+        signal,
+      );
+    } catch (e) {
+      if (e.name === 'AbortError') {
+        if (ev) ev.onInfo?.('已中断');
+        else out(c.gray('\n[已中断]\n'));
+        return { aborted: true, usage: { prompt, completion }, lastPromptTokens };
+      }
+      if (ev) ev.onInfo?.('✗ 模型调用失败：' + e.message);
+      else out('\n' + c.red('✗ 模型调用失败：') + e.message + '\n');
+      return { error: e.message, usage: { prompt, completion }, lastPromptTokens };
+    }
+    emitDelta(mf.flush()); // 放行轮末仍持有的未确认内容（吞噬中则丢弃）
+
+    if (res.usage) {
+      prompt += res.usage.prompt_tokens || 0;
+      completion += res.usage.completion_tokens || 0;
+      lastPromptTokens = res.usage.prompt_tokens || lastPromptTokens;
+    }
+
+    // 全量内容按同一状态机二次清洗（与流式放行结果一致）：协议标记绝不进入会话记录与后续上下文
+    const { text: cleanText, sawMarkup: sawInFull } = stripMarkup(res.content);
+    const markupRound = sawInFull || mf.sawMarkup;
+    correction = null; // 上一轮注入的纠正指令已被消费
+
+    const toolCalls = platformMode ? [] : res.toolCalls;
+    if (!toolCalls.length) {
+      // 「文本化工具调用」拦截后的纠正：本轮"正文"实为协议标记（已被过滤，未显示，工具也未执行）。
+      // 平台编排模式（伪模型）由服务端过滤与纠正，客户端不再重试。
+      if (markupRound && !cleanText.trim() && !platformMode) {
+        if (markupRetries < 2) {
+          markupRetries++;
+          if (markupRetries === 2) toolsDisabled = true;
+          correction = markupRetries === 1 ? MARKUP_RETRY_PROMPT : MARKUP_FORCE_ANSWER_PROMPT;
+          info(`已拦截模型的文本化工具调用标记（工具未被执行），纠正重试中（第 ${markupRetries} 次）`);
+          continue;
+        }
+        info('模型持续输出无效的工具调用标记，已全部拦截；本轮无有效答复（可换个说法重试或更换模型）');
+      }
+      if (streamedAny && !ev) out('\n');
+      // 记录最终答复进上下文，使后续用户回合能看到助手上一次回复（多轮对话记忆）
+      if (cleanText) messages.push({ role: 'assistant', content: cleanText });
+      if (ev) ev.onTurnEnd?.(cleanText);
+      // 用户在回合中排队了新消息 → 直接续跑，无需重新发起回合
+      const queued = pullQueued?.();
+      if (queued) {
+        messages.push({ role: 'user', content: queued });
+        continue;
+      }
+      return { usage: { prompt, completion }, lastPromptTokens };
+    }
+
+    if (streamedAny && !ev) out('\n');
+    if (ev && cleanText) ev.onAssistantText?.(cleanText); // 工具轮前的正文先落定
+    messages.push({ role: 'assistant', content: cleanText, tool_calls: toolCalls });
+
+    // 预解析全部调用（名称/参数/只读性）；参数 JSON 解析失败记录错误（回灌模型重试，而非静默空参数）
+    const parsed = toolCalls.map((tc, idx) => {
+      const name = tc.function?.name || '';
+      let args = {};
+      let argsError = null;
+      const raw = tc.function?.arguments || '';
+      if (raw) {
+        try {
+          args = JSON.parse(raw);
+        } catch (e) {
+          argsError = `工具参数不是合法 JSON（${e.message}）：${String(raw).slice(0, 200)}…请修正参数后重新调用。`;
+        }
+      }
+      const extra = extraByName.get(name);
+      // IDE 集成下，write_file/edit_file 的批准发生在编辑器的内联 diff 审阅里，跳过 CLI 自身的 y/n（避免双重确认）
+      const deferToIde = ide.isActive() && (name === 'write_file' || name === 'edit_file');
+      const readOnly = extra ? !!extra.readOnly : READONLY_TOOLS.has(name);
+      return { tc, idx, name, args, argsError, extra, readOnly, deferToIde };
+    });
+
+    // 中断时为剩余未执行的 tool_calls 合成占位结果，保证 assistant.tool_calls 配对完整（协议要求）
+    const abortRest = (from) => {
+      for (let k = from; k < parsed.length; k++) {
+        messages.push({ role: 'tool', tool_call_id: parsed[k].tc.id || `call_${k}`, content: '（用户中断，该工具未执行）' });
+      }
+      if (ev) ev.onInfo?.('已中断');
+      else out(c.gray('\n[已中断]\n'));
+      return { aborted: true, usage: { prompt, completion }, lastPromptTokens };
+    };
+
+    const execOne = async (item) => {
+      if (item.argsError) return item.argsError;
+      let result;
+      try {
+        result = item.extra ? await item.extra.run(item.args) : await runTool(item.name, item.args, cwd);
+      } catch (e) {
+        result = `工具执行失败：${e.message}`;
+      }
+      return capToolResult(String(result));
+    };
+    const emitStart = (item) => {
+      if (ev) ev.onToolStart?.(item.name, item.args);
+      else out(c.cyan('  ⏺ ') + toolLabel(item.name, item.args) + '\n');
+    };
+    const emitResult = (item, result) => {
+      if (ev) ev.onToolResult?.(item.name, String(result));
+      else out(c.gray('     ' + shortLine(result)) + '\n');
+      messages.push({ role: 'tool', tool_call_id: item.tc.id, content: String(result) });
+    };
+    const emitSkip = (item, reason) => {
+      if (ev) ev.onSkip?.(item.name, item.args);
+      else out(c.gray(`  ⊘ ${toolLabel(item.name, item.args)} — 已跳过\n`));
+      messages.push({ role: 'tool', tool_call_id: item.tc.id, content: reason || '未授权，未执行。' });
+    };
+
+    let i = 0;
+    while (i < parsed.length) {
+      if (signal?.aborted) return abortRest(i);
+      const cur = parsed[i];
+
+      // 参数损坏：不请求授权、不执行，直接把解析错误回灌（模型可修正后重试）
+      if (cur.argsError) {
+        emitStart(cur);
+        emitResult(cur, cur.argsError);
+        i++;
+        continue;
+      }
+
+      if (cur.readOnly) {
+        // 连续只读段：并行执行（权限对只读即时放行），结果按原顺序回灌
+        let j = i;
+        while (j < parsed.length && parsed[j].readOnly && !parsed[j].argsError) j++;
+        const batch = parsed.slice(i, j);
+        const settled = await Promise.all(
+          batch.map(async (item) => {
+            const perm = await permissions.request(item.name, item.args, cwd, true);
+            if (!perm.allow) return { item, denied: perm.reason || '未授权，未执行。' };
+            emitStart(item);
+            return { item, result: await execOne(item) };
+          }),
+        );
+        for (const s of settled) {
+          if (s.denied != null) emitSkip(s.item, s.denied);
+          else emitResult(s.item, s.result);
+        }
+        i = j;
+        if (signal?.aborted) return abortRest(i);
+        continue;
+      }
+
+      // 写/执行类：顺序执行，逐个审批
+      const perm = await permissions.request(cur.name, cur.args, cwd, cur.readOnly || cur.deferToIde);
+      if (signal?.aborted) return abortRest(i);
+      if (!perm.allow) {
+        emitSkip(cur, perm.reason);
+        i++;
+        continue;
+      }
+      emitStart(cur);
+      const result = await execOne(cur);
+      emitResult(cur, result);
+      i++;
+    }
+
+    // 工具轮之间注入用户排队消息（协议合法：tool 配对已完整），模型下一轮即可看到
+    const queued = pullQueued?.();
+    if (queued) messages.push({ role: 'user', content: queued });
+  }
+
+  if (ev) ev.onInfo?.('已达最大工具轮数，停止');
+  else out(c.yellow('\n[已达最大工具轮数，停止]\n'));
+  return { usage: { prompt, completion }, lastPromptTokens };
+}

package/src/api.js

@@ -0,0 +1,326 @@
+// HuiCai_AI 平台 OpenAI 兼容 /v1 客户端（零依赖，用 Node 内置 fetch + Web Streams）。
+//
+// 对「原始模型 id」，平台 /v1/chat/completions 为透明代理：透传 tools、原样回传 tool_calls 与流式增量。
+// 因此本客户端把平台当作「会做函数调用决策」的模型后端，工具在本机执行的智能体模式。
+//
+// 可靠性：首字节前的 429/5xx/网络错自动指数退避重试（尊重 Retry-After）；流中途长时间无数据由
+// 停滞看门狗中止，避免挂死。一旦开始收到增量则不再重试（防止重复输出/重复计费）。
+
+const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504]);
+const MAX_RETRIES = 2; // 共尝试 1+2 次
+const STALL_TIMEOUT_MS = 90_000; // 流中无任何字节超过该时长视为停滞
+const REQUEST_TIMEOUT_MS = 15_000; // 非流式小请求超时
+
+/** 从 Authorization 组装请求头。 */
+function authHeaders(apiKey) {
+  return {
+    'Content-Type': 'application/json',
+    Authorization: `Bearer ${apiKey}`,
+  };
+}
+
+/** 读取错误响应体并抽出可读信息与 OpenAI error.type（供识别用量窗口超限等终态）。 */
+async function readError(res) {
+  let text = '';
+  try {
+    text = await res.text();
+  } catch {
+    /* ignore */
+  }
+  try {
+    const j = JSON.parse(text);
+    const type = j?.error?.type || j?.type || '';
+    if (j?.error?.message) return { message: j.error.message, type };
+    if (j?.message) return { message: j.message, type };
+    if (j?.msg) return { message: j.msg, type };
+  } catch {
+    /* not json */
+  }
+  return { message: text || `HTTP ${res.status}`, type: '' };
+}
+
+/** 把一批 tool_calls 增量按 index 累加到 acc。 */
+function mergeToolCalls(acc, deltas) {
+  for (const tc of deltas) {
+    const i = typeof tc.index === 'number' ? tc.index : acc.length;
+    if (!acc[i]) acc[i] = { id: '', type: 'function', function: { name: '', arguments: '' } };
+    if (tc.id) acc[i].id = tc.id;
+    if (tc.type) acc[i].type = tc.type;
+    if (tc.function?.name) acc[i].function.name += tc.function.name;
+    if (tc.function?.arguments) acc[i].function.arguments += tc.function.arguments;
+  }
+}
+
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(abortError());
+    const t = setTimeout(() => {
+      signal?.removeEventListener?.('abort', onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(t);
+      reject(abortError());
+    };
+    signal?.addEventListener?.('abort', onAbort, { once: true });
+  });
+}
+
+function abortError() {
+  const e = new Error('已中断');
+  e.name = 'AbortError';
+  return e;
+}
+
+/** 由重试次数与 Retry-After 头计算退避时长（毫秒）。 */
+function backoffMs(attempt, res) {
+  const ra = res?.headers?.get?.('retry-after');
+  const raSec = ra != null ? Number(ra) : NaN;
+  if (Number.isFinite(raSec) && raSec >= 0) return Math.min(raSec * 1000, 30_000);
+  return Math.min(500 * 2 ** attempt + Math.floor(Math.random() * 250), 8_000);
+}
+
+/**
+ * 流式对话补全。逐块解析 SSE：content/reasoning 经 handlers 实时下发，tool_calls 累积后返回。
+ *
+ * @param {{baseUrl:string, apiKey:string, model:string, messages:any[], tools?:any[], temperature?:number, stallTimeoutMs?:number}} opts
+ * @param {{onContent?:(t:string)=>void, onReasoning?:(t:string)=>void, onRetry?:(attempt:number, waitMs:number, reason:string)=>void}} [handlers]
+ * @param {AbortSignal} [signal]
+ * @returns {Promise<{content:string, toolCalls:any[], finishReason:string|null, usage:any}>}
+ */
+export async function streamChat(opts, handlers = {}, signal) {
+  const url = `${opts.baseUrl}/v1/chat/completions`;
+  const payload = {
+    model: opts.model,
+    messages: opts.messages,
+    stream: true,
+    stream_options: { include_usage: true },
+  };
+  if (opts.tools && opts.tools.length) {
+    payload.tools = opts.tools;
+    payload.tool_choice = 'auto';
+  }
+  if (typeof opts.temperature === 'number') payload.temperature = opts.temperature;
+  // 对话落库审计标识：来源(cli/vscode) + 会话号（平台按此归并同会话多轮，供后台审计）
+  const chatHeaders = authHeaders(opts.apiKey);
+  if (opts.client) chatHeaders['X-Huicai-Client'] = opts.client;
+  if (opts.sessionId) chatHeaders['X-Huicai-Session'] = opts.sessionId;
+  const body = JSON.stringify(payload);
+
+  // 重试仅发生在「拿到可读响应体之前」：状态可重试或网络错。开始读流后不再重试。
+  for (let attempt = 0; ; attempt++) {
+    let res;
+    try {
+      res = await fetch(url, { method: 'POST', headers: chatHeaders, body, signal });
+    } catch (e) {
+      if (e?.name === 'AbortError' || signal?.aborted) throw abortError();
+      if (attempt < MAX_RETRIES) {
+        const wait = backoffMs(attempt, null);
+        handlers.onRetry?.(attempt + 1, wait, '网络错误：' + (e?.message || e));
+        await sleep(wait, signal);
+        continue;
+      }
+      throw new Error('网络错误：' + (e?.message || e));
+    }
+    if (!res.ok || !res.body) {
+      const err = await readError(res);
+      // 用量窗口超限（5小时/7天滚动窗）为终态：不重试，直接抛出清晰提示（含重置时间），避免无谓退避重试
+      const usageLimited = err.type === 'usage_limit_exceeded';
+      if (!usageLimited && RETRYABLE_STATUS.has(res.status) && attempt < MAX_RETRIES) {
+        const wait = backoffMs(attempt, res);
+        handlers.onRetry?.(attempt + 1, wait, `HTTP ${res.status}：${err.message}`);
+        await sleep(wait, signal);
+        continue;
+      }
+      throw new Error(err.message);
+    }
+    return readStream(res, handlers, signal, opts.stallTimeoutMs ?? STALL_TIMEOUT_MS);
+  }
+}
+
+/** 读取 SSE 响应体：外部 signal 可中断；停滞看门狗防挂死。 */
+async function readStream(res, handlers, signal, stallMs) {
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let content = '';
+  const toolCalls = [];
+  let finishReason = null;
+  let usage = null;
+
+  let stalled = false;
+  let stallTimer = null;
+  const armStall = () => {
+    if (stallTimer) clearTimeout(stallTimer);
+    stallTimer = setTimeout(() => {
+      stalled = true;
+      reader.cancel().catch(() => {});
+    }, stallMs);
+  };
+  const onAbort = () => reader.cancel().catch(() => {});
+  signal?.addEventListener?.('abort', onAbort, { once: true });
+
+  try {
+    armStall();
+    while (true) {
+      let chunk;
+      try {
+        chunk = await reader.read();
+      } catch (e) {
+        if (signal?.aborted) throw abortError();
+        if (stalled) throw new Error(`响应停滞超过 ${Math.round(stallMs / 1000)}s，已中止（可重试）`);
+        throw e;
+      }
+      if (signal?.aborted) throw abortError();
+      if (stalled) throw new Error(`响应停滞超过 ${Math.round(stallMs / 1000)}s，已中止（可重试）`);
+      const { done, value } = chunk;
+      if (done) break;
+      armStall();
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split('\n');
+      buffer = lines.pop() ?? '';
+      for (const raw of lines) {
+        const line = raw.trim();
+        if (!line.startsWith('data:')) continue;
+        const data = line.slice(5).trim();
+        if (data === '[DONE]' || data === '') continue;
+        let json;
+        try {
+          json = JSON.parse(data);
+        } catch {
+          continue; // 半个 JSON（跨块），忽略；完整帧下轮再来
+        }
+        if (json.usage) usage = json.usage;
+        const choice = json.choices?.[0];
+        if (!choice) continue;
+        const delta = choice.delta || {};
+        const rc = delta.reasoning_content ?? delta.reasoning;
+        if (rc) handlers.onReasoning?.(rc);
+        if (delta.content) {
+          content += delta.content;
+          handlers.onContent?.(delta.content);
+        }
+        if (Array.isArray(delta.tool_calls)) mergeToolCalls(toolCalls, delta.tool_calls);
+        if (choice.finish_reason) finishReason = choice.finish_reason;
+      }
+    }
+  } finally {
+    if (stallTimer) clearTimeout(stallTimer);
+    signal?.removeEventListener?.('abort', onAbort);
+  }
+  return { content, toolCalls: toolCalls.filter(Boolean), finishReason, usage };
+}
+
+/** 列出可用模型（含平台已发布智能体伪模型 agent-/workflow-/datahuman-）。 */
+export async function listModels(baseUrl, apiKey) {
+  const res = await fetch(`${baseUrl}/v1/models`, {
+    headers: authHeaders(apiKey),
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+  if (!res.ok) throw new Error((await readError(res)).message);
+  const j = await res.json();
+  return Array.isArray(j?.data) ? j.data : [];
+}
+
+/**
+ * 读取客户端相关的平台默认配置（GET /v1/config）。
+ * @returns {Promise<{vision_bridge_model?:string}>} 失败时返回 {}（客户端自行回退）
+ */
+export async function getPlatformConfig(baseUrl, apiKey) {
+  try {
+    const res = await fetch(`${baseUrl}/v1/config`, {
+      headers: authHeaders(apiKey),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!res.ok) return {};
+    const j = await res.json();
+    return j && typeof j === 'object' ? j : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * 拉取某已发布智能体的人格（供 --agent 本机执行模式采用）。
+ * @param {string} ref 分享令牌，或伪模型ID agent-{token}
+ * @returns {Promise<{name:string,description:string,systemPrompt:string,model:string,temperature:number,maxTokens:number}>}
+ */
+export async function getAgentPersona(baseUrl, apiKey, ref) {
+  const res = await fetch(`${baseUrl}/v1/agents/${encodeURIComponent(ref)}/persona`, {
+    headers: authHeaders(apiKey),
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+  if (!res.ok) throw new Error((await readError(res)).message);
+  return res.json();
+}
+
+/**
+ * 查询当前令牌用户的 Token 用量窗口（5小时/7天滚动窗，GET /v1/usage）。
+ * @returns {Promise<{allowed:boolean,used5h:number,limit5h:number,used7d:number,limit7d:number,resetAtEpochMs?:number|null,message?:string}>}
+ */
+export async function fetchUsage(baseUrl, apiKey) {
+  const res = await fetch(`${baseUrl}/v1/usage`, {
+    headers: authHeaders(apiKey),
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+  if (!res.ok) throw new Error((await readError(res)).message);
+  return res.json();
+}
+
+/**
+ * 解析文档附件为纯文本（POST /v1/files/extract：PDF/Word/Excel/PPT/RTF 及各类文本，Base64 传输）。
+ * 服务端与 Web 分享页同源解析（knowledge DocumentParser），扫描件/二进制会得到明确报错。
+ * 大文件解析较慢，超时放宽到 2 分钟。
+ * @param {{filename:string, data:string, maxChars?:number}} payload data=文件内容 Base64
+ * @returns {Promise<{name:string,ext:string,category:string,chars:number,truncated:boolean,pages?:number|null,text:string}>}
+ */
+export async function extractDocument(baseUrl, apiKey, payload) {
+  const res = await fetch(`${baseUrl}/v1/files/extract`, {
+    method: 'POST',
+    headers: authHeaders(apiKey),
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(120_000),
+  });
+  if (!res.ok) throw new Error((await readError(res)).message);
+  return res.json();
+}
+
+/**
+ * 列出平台上我的文档技能（GET /v1/skills，云端技能库；供 huicai skills pull）。
+ * @returns {Promise<{id:number,name:string,description:string,version:string,updateTime:string}[]>}
+ */
+export async function listPlatformSkills(baseUrl, apiKey) {
+  const res = await fetch(`${baseUrl}/v1/skills`, {
+    headers: authHeaders(apiKey),
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+  if (!res.ok) throw new Error((await readError(res)).message);
+  const j = await res.json();
+  return Array.isArray(j?.data) ? j.data : [];
+}
+
+/** 平台技能详情（含 SKILL.md 全文与附件，GET /v1/skills/{id}）。 */
+export async function getPlatformSkill(baseUrl, apiKey, id) {
+  const res = await fetch(`${baseUrl}/v1/skills/${encodeURIComponent(id)}`, {
+    headers: authHeaders(apiKey),
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+  if (!res.ok) throw new Error((await readError(res)).message);
+  return res.json();
+}
+
+/**
+ * 推送本地技能到平台（POST /v1/skills/import；同名冲突 skip/overwrite）。
+ * @param {{content:string,filename?:string,conflict?:string,files?:{path:string,content:string}[]}} payload
+ * @returns {Promise<{id:number,status:'imported'|'overwritten'|'skipped',warnings?:string[]}>}
+ */
+export async function pushPlatformSkill(baseUrl, apiKey, payload) {
+  const res = await fetch(`${baseUrl}/v1/skills/import`, {
+    method: 'POST',
+    headers: { ...authHeaders(apiKey), 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+  if (!res.ok) throw new Error((await readError(res)).message);
+  return res.json();
+}