llm-api-gateway-cli 1.0.0

package/lib/hub.js

@@ -0,0 +1,1494 @@
+/**
+ * 统一的本地 Web 服务（模式四 聊天 + 模式五 任务，同一个端口）
+ *
+ * 原来聊天和任务各是一个进程、各占一个端口（3100 / 3101），两个页面之间靠写死端口号互相跳转。
+ * 现在合成一个服务：
+ *   /        → 聊天页（模式四）
+ *   /task    → 任务页（模式五）
+ * 两页共用一套静态资源与 /api/config、/api/models，各自的业务接口按前缀分发。
+ *
+ * 这样只需要起一个进程、开一个端口，页面之间的跳转也变成同源相对路径。
+ */
+
+import http from 'node:http';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { existsSync, statSync, createReadStream } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import {
+  DEFAULT_BASE_URL,
+  loadDotEnv,
+  parseArgs,
+  strArg,
+  resolveKey,
+  resolveBaseUrl,
+  resolvePort,
+  sendJson,
+  readBody,
+  maskKey,
+  errorText,
+  openSse,
+  isLoopbackHost,
+  resolveStatic,
+  sessionBaggage,
+} from './common.js';
+import { availableTools, checkWorkDir, browseDir, listRoots, describeCall, setBashEnabled, isBashEnabled } from './tools.js';
+// MCP 工具清单按**当次密钥**从网关取：页面上的工具列表与任务运行共用这一份缓存
+import { refreshMcpTools } from './mcp.js';
+import { readMemory, initInstructions } from './memory.js';
+import {
+  runAgent,
+  resumeWithApproval,
+  saveRun,
+  takeRun,
+  dropRun,
+  runStats,
+  listRuns,
+  setRunPersistence,
+  normalizeMode,
+  toolsForMode,
+  MODES,
+  MODE_LABELS,
+  AGENT_LIMITS,
+  resolveMaxSteps,
+} from './agent.js';
+import { buildTaskSystemPrompt, pushUser } from './runner.js';
+import { savePlanDoc, lastAssistantText, firstUserText } from './plandoc.js';
+import { TaskStore, resolveStoreDir, isSafeId, TTL_MS as TASK_TTL_MS } from './taskstore.js';
+import { createRunStore } from './runstore.js';
+import {
+  createTaskSessionStore,
+  loadOrCreateTaskSession,
+  prepareTaskSession,
+  refreshSessionContext,
+  TASK_SESSION_MAX_BYTES,
+  HISTORY_MAX_CHARS,
+  HISTORY_KEEP_RECENT_TURNS,
+  HISTORY_READ_FILE_DIGEST,
+} from './tasksession.js';
+import {
+  resolveSettings,
+  writeSettings,
+  settingsFilePath,
+  listSettings,
+  restartKeysIn,
+  isSettingKey,
+  isUiStateKey,
+  isSecretKey,
+  parseSettingValue,
+  unknownKeyError,
+} from './settings.js';
+import { commandRows } from './commands.js';
+import { estimateCost, formatCost } from './pricing.js';
+/**
+ * 密钥的唯一实现：环境里没给密钥时，兜底读 `<数据根>/credentials.json`。
+ * 密钥**不进 config.json**（那条红线没变），界面 / CLI 配的就是这个文件。
+ */
+import {
+  keyRow,
+  readSecret,
+  resolveSecretKey,
+  secretFilePath,
+  secretSourceText,
+  writeSecret,
+  clearSecret,
+} from './secrets.js';
+/**
+ * 任务页的指令表（public/task-slash.js）是给浏览器用的经典脚本，`import` 它的**副作用**就是把表挂到
+ * `globalThis.TaskSlash`（模块里那句 `root.TaskSlash = factory()`；测试 tests/task-slash.test.mjs 用的是同一手法）。
+ * 这样 `/api/commands`、任务页面板、手册页三处读的是**同一张表** —— 手册再也不会"少几条"。
+ */
+import '../public/task-slash.js';
+
+const taskSlash = globalThis.TaskSlash;
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+// 本文件在 lib/ 下，而 .env、public/ 以及存储目录的兜底位置都以项目根为基准
+const ROOT_DIR = path.join(SCRIPT_DIR, '..');
+const PUBLIC_DIR = path.join(ROOT_DIR, 'public');
+const DEFAULT_PORT = 3100;
+// 任务消息里会带上工具读过的文件正文，可能很大；比默认的 8MB 放宽
+const TASK_BODY_LIMIT = 32 * 1024 * 1024;
+// 先加载 .env，再算默认模型 —— 否则 GATEWAY_MODEL 赶不上参与默认值计算
+loadDotEnv(ROOT_DIR);
+
+const DEFAULT_MODEL = process.env.GATEWAY_MODEL || 'qwen3:8b';
+
+/** 存储目录是怎么选出来的，启动时打给人看 */
+const STORE_SOURCE_TEXT = {
+  explicit: '--store 指定',
+  'user-data': '用户主目录下的 .llm-api-gateway-cli',
+  legacy: '旧位置（主目录不可写，见下面的警告）',
+  temp: '主目录不可写，退到系统临时目录',
+};
+
+const HELP = `用法：node server.js [选项]
+
+本地 Web UI：聊天（模式四）与任务（模式五）跑在同一个端口上。
+
+    http://127.0.0.1:${DEFAULT_PORT}/        聊天
+    http://127.0.0.1:${DEFAULT_PORT}/task    任务（选目录，模型真读写）
+
+选项：
+      --port <端口>           监听端口（默认 ${DEFAULT_PORT}，也可用 WEB_PORT / TASK_WEB_PORT）
+      --host <地址>           监听地址（默认 127.0.0.1，仅本机可访问）
+  -m, --model <模型>          默认模型（默认 ${DEFAULT_MODEL}）
+  -k, --key <sk-密钥>         网关密钥（也可用环境变量 SK/GATEWAY_KEY 或 .env）
+      --base-url <地址>       网关地址（默认 ${DEFAULT_BASE_URL}）
+      --store <目录>          任务数据存储目录（默认用户主目录下的 .llm-api-gateway-cli，也可用 TASK_STORE_DIR）
+      --mode <模式>           任务默认审批模式：manual 手动 / auto 自动 / plan 计划（默认 manual）
+      --max-steps <轮数>      单个任务最多几轮模型调用（默认 ${AGENT_LIMITS.MAX_STEPS}，也可用 TASK_MAX_STEPS）
+      --allow-remote-fs       允许非本机访问时开放目录浏览与任务记录接口（危险）
+      --allow-bash            开启 bash 工具，让任务页的模型能真的执行命令（默认关闭；危险）
+      --verbose               打印每个请求的转发日志
+  -h, --help                  显示帮助
+
+三种审批模式（任务页可随时切换）：
+  manual  每次写入都要你在界面上点确认（默认）
+  auto    写入直接执行，不再打断你；界面仍逐条显示改了什么
+          （加了 --allow-bash 时命令也走这条路：不再逐个确认）
+  plan    只给模型只读工具，先出计划、不动文件；确认后再执行
+
+单个任务默认最多 ${AGENT_LIMITS.MAX_STEPS} 轮模型调用（--max-steps / TASK_MAX_STEPS 可调）。撞到上限不会「干到一半就停」：先自动走一轮不带工具的收尾把结论给你，页面再给一个「继续执行」按钮接着干。待批准的挂起态保留 ${AGENT_LIMITS.APPROVAL_TTL_MS / 60000} 分钟、最多 ${AGENT_LIMITS.MAX_RUNS} 个，且会落盘 —— 刷新页面或重启服务后仍可批准。
+`;
+
+const VALUE_FLAGS = {
+  '--port': 'port',
+  '--host': 'host',
+  '--model': 'model',
+  '-m': 'model',
+  '--key': 'key',
+  '-k': 'key',
+  '--base-url': 'base-url',
+  '--store': 'store',
+  '--mode': 'mode',
+  '--max-steps': 'max-steps',
+};
+const BOOL_FLAGS = { '--verbose': 'verbose', '--allow-remote-fs': 'allow-remote-fs', '--allow-bash': 'allow-bash', '--help': 'help', '-h': 'help' };
+
+/* ---------- 静态文件 ---------- */
+
+/**
+ * 正在跑的任务（进程内、不落盘）。两个用途：
+ *   1. 侧边栏显示「进行中 / 已完成」；
+ *   2. **同一条任务的互斥** —— 会话改成服务端持有之后，两个标签页同时对一条任务发指令
+ *      会并发写同一个会话文件。无状态时代没这个问题，有状态之后必须有。
+ * 丢了这个状态只是少一个标记（第 1 点），但互斥是正确性要求，不能省。
+ */
+const runningTasks = new Map();
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.png': 'image/png',
+};
+
+/** 路径 → public/ 下的文件。每个页面各有自己的入口 */
+function pageFile(urlPath) {
+  if (urlPath === '/' || urlPath === '/index.html') return 'index.html';
+  if (urlPath === '/task' || urlPath === '/task/' || urlPath === '/task.html') return 'task.html';
+  if (urlPath === '/manual' || urlPath === '/manual/' || urlPath === '/manual.html') return 'manual.html';
+  return null;
+}
+
+function serveStatic(req, res, urlPath) {
+  const file = resolveStatic(PUBLIC_DIR, pageFile(urlPath) ? `/${pageFile(urlPath)}` : urlPath);
+  if (!file) return sendJson(res, 403, { error: '禁止访问' });
+  if (!existsSync(file) || !statSync(file).isFile()) return sendJson(res, 404, { error: `未找到 ${urlPath}` });
+  res.writeHead(200, {
+    'content-type': MIME[path.extname(file).toLowerCase()] || 'application/octet-stream',
+    'cache-control': 'no-cache',
+  });
+  createReadStream(file).pipe(res);
+}
+
+/* ---------- 聊天（模式四） ---------- */
+
+async function fetchModels(cfg) {
+  const resp = await fetch(`${cfg.baseUrl}/v1/models`, {
+    headers: { authorization: `Bearer ${cfg.key}` },
+    signal: AbortSignal.timeout(8000),
+  });
+  if (!resp.ok) throw Object.assign(new Error(await errorText(resp)), { status: resp.status });
+  const json = await resp.json();
+  return (json.data || []).map((m) => (typeof m === 'string' ? m : m.id)).filter(Boolean);
+}
+
+/** 组装发往网关的 OpenAI 格式请求体 */
+function buildChatPayload(body, cfg) {
+  const messages = [];
+  if (typeof body.system === 'string' && body.system.trim()) messages.push({ role: 'system', content: body.system });
+  for (const m of Array.isArray(body.messages) ? body.messages : []) {
+    if (!m || typeof m.content !== 'string') continue;
+    if (m.role !== 'user' && m.role !== 'assistant' && m.role !== 'system') continue;
+    if (!m.content) continue;
+    messages.push({ role: m.role, content: m.content });
+  }
+  const stream = body.stream !== false;
+  const payload = { model: typeof body.model === 'string' && body.model.trim() ? body.model.trim() : cfg.model, messages, stream };
+  if (stream) payload.stream_options = { include_usage: true };
+  if (Number.isFinite(body.temperature)) payload.temperature = body.temperature;
+  if (Number.isFinite(body.maxTokens) && body.maxTokens > 0) payload.max_tokens = body.maxTokens;
+  return payload;
+}
+
+/** POST /api/chat：把上游 SSE 归一化成 {type:delta|usage|done|error} 后转发给浏览器 */
+async function handleChat(req, res, cfg) {
+  let body;
+  try {
+    body = await readBody(req);
+  } catch (e) {
+    return sendJson(res, e.status || 400, { error: e.message });
+  }
+
+  const payload = buildChatPayload(body, cfg);
+  if (!payload.messages.length) return sendJson(res, 400, { error: 'messages 为空：至少需要一条 user 消息' });
+
+  const controller = new AbortController();
+  req.on('close', () => controller.abort()); // 前端点「停止」或断开时，同时掐断上游请求
+
+  // 聊天页同样有「一次对话」的概念（前端 state.activeId），一并告诉网关。
+  // 拿不到合法 id 就不发这个头，退回网关的推断口径，功能照常。
+  const headers = { 'content-type': 'application/json', authorization: `Bearer ${cfg.key}` };
+  const baggage = sessionBaggage(body.sessionId);
+  if (baggage) headers.baggage = baggage;
+
+  let upstream;
+  try {
+    upstream = await fetch(`${cfg.baseUrl}/v1/chat/completions`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+  } catch (e) {
+    if (controller.signal.aborted) return;
+    return sendJson(res, 502, { error: `连接网关失败（${cfg.baseUrl}）：${e?.message || e}` });
+  }
+
+  if (!upstream.ok) {
+    const message = await errorText(upstream);
+    if (cfg.verbose) console.error(`[web] 上游 ${upstream.status}: ${message.slice(0, 200)}`);
+    return sendJson(res, upstream.status, { error: message, status: upstream.status });
+  }
+
+  // 非流式：直接回一个 JSON
+  if (!payload.stream) {
+    const data = await upstream.json();
+    const message = data?.choices?.[0]?.message ?? {};
+    return sendJson(res, 200, {
+      text: message.content ?? '',
+      reasoning: message.reasoning_content ?? '', // 思考模型的思维链（网关不并入 content）
+      usage: data?.usage ?? null,
+    });
+  }
+
+  // 流式：逐个上游 chunk 归一化后以 SSE 推给浏览器
+  const send = openSse(res);
+  const usage = { prompt: null, completion: null, total: null };
+  let sawContent = false;
+  let sawReasoning = false;
+
+  try {
+    const reader = upstream.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = '';
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      const parts = buf.split('\n');
+      buf = parts.pop() ?? '';
+      for (const line of parts) {
+        const t = line.trim();
+        if (!t.startsWith('data:')) continue;
+        const data = t.slice(5).trim();
+        if (!data || data === '[DONE]') continue;
+        let chunk;
+        try {
+          chunk = JSON.parse(data);
+        } catch {
+          continue;
+        }
+        // 思考模型（如 deepseek-v4-*）把思维链放在 delta.reasoning_content，
+        // 正文要等思考结束才出现在 delta.content —— 两者都要转发，否则前端长时间空白。
+        const delta = chunk?.choices?.[0]?.delta;
+        if (delta?.reasoning_content) {
+          sawReasoning = true;
+          send({ type: 'reasoning', text: delta.reasoning_content });
+        }
+        if (delta?.content) {
+          sawContent = true;
+          send({ type: 'delta', text: delta.content });
+        }
+        if (chunk?.usage) {
+          usage.prompt = chunk.usage.prompt_tokens ?? null;
+          usage.completion = chunk.usage.completion_tokens ?? null;
+          usage.total = chunk.usage.total_tokens ?? null;
+        }
+        const finish = chunk?.choices?.[0]?.finish_reason;
+        if (finish && !sawContent) {
+          send({
+            type: 'notice',
+            text: sawReasoning
+              ? `上游只返回了思维链、未产出正文（finish_reason=${finish}）—— 通常是 max_tokens 太小被思考过程耗尽，调大后再试`
+              : `上游结束但未返回正文（finish_reason=${finish}）`,
+          });
+        }
+      }
+    }
+    if (usage.total !== null || usage.prompt !== null) send({ type: 'usage', usage });
+    send({ type: 'done' });
+  } catch (e) {
+    if (controller.signal.aborted) send({ type: 'done', aborted: true });
+    else send({ type: 'error', message: `读取上游流失败：${e?.message || e}` });
+  } finally {
+    res.end();
+  }
+}
+
+/* ---------- 任务（模式五） ---------- */
+
+/**
+ * **旧格式专用**：从「前端回传的全量对白」重建上下文。
+ *
+ * 这条路径没有工具历史可言 —— 模型只能看到历轮的正文，看不到任何 `role:"tool"`，
+ * 于是每轮都得重新 `list_dir` / `grep`。它现在只服务兼容期的老前端与外部脚本
+ * （`compat.legacyTaskApi`），新前端一律走「服务端持有会话」那条路，见 `handleTask`。
+ */
+function buildTaskMessages(body, workDir, mode) {
+  const messages = [{ role: 'system', content: buildTaskSystemPrompt(workDir, body.system, mode) }];
+  for (const m of Array.isArray(body.messages) ? body.messages : []) {
+    if (!m || typeof m.content !== 'string' || !m.content.trim()) continue;
+    if (m.role !== 'user' && m.role !== 'assistant') continue;
+    messages.push({ role: m.role, content: m.content });
+  }
+  return messages;
+}
+
+/** 会话落盘：失败也不能影响这一轮的对话结果，最多是下次少一点上下文 */
+function persistTaskSession(cfg, run) {
+  if (!run?.taskId) return null;
+  try {
+    run.touchedAt = Date.now();
+    return cfg.taskSessions.write(run);
+  } catch (e) {
+    if (cfg.verbose) console.error(`[task] 会话落盘失败：${e?.message || e}`);
+    return null;
+  }
+}
+
+/**
+ * 会话级别的限制。都可以从配置覆盖（见 `lib/settings.js`），默认值等于原常量 ——
+ * 加配置不改变默认行为。
+ */
+function sessionLimits(cfg) {
+  const t = cfg.taskTuning || {};
+  return {
+    maxBytes: Number(t.sessionMaxBytes) > 0 ? Number(t.sessionMaxBytes) : TASK_SESSION_MAX_BYTES,
+    maxMessages: Number(t.sessionMaxMessages) > 0 ? Number(t.sessionMaxMessages) : undefined,
+    historyMaxChars: Number(t.historyMaxChars) > 0 ? Number(t.historyMaxChars) : HISTORY_MAX_CHARS,
+    keepRecentTurns: Number(t.historyKeepRecentTurns) >= 0 ? Number(t.historyKeepRecentTurns) : HISTORY_KEEP_RECENT_TURNS,
+    // 默认开：这条清单正是「别重复读」的关键，关掉是给「模型太啰嗦」的人留的后门
+    readFileDigest: t.readFileDigest === undefined ? HISTORY_READ_FILE_DIGEST : Boolean(t.readFileDigest),
+  };
+}
+
+/** 删任务 / 淘汰过期任务时，把它名下的会话文件一并删掉，否则会变成孤儿泄漏 */
+function dropTaskSessions(cfg, ids) {
+  let dropped = 0;
+  for (const id of Array.isArray(ids) ? ids : []) {
+    try {
+      if (cfg.taskSessions.drop(id)) dropped++;
+    } catch {
+      /* 单个删不掉不影响其他 */
+    }
+  }
+  return dropped;
+}
+
+/**
+ * 把解析好的配置套到运行态上。
+ *
+ * 单独抽出来是为了「改完立刻生效」：`PUT /api/settings` 之后再调一次，
+ * 不必重启进程（`store.dir` / `retention.*` 这类启动时就被读走的不算，
+ * 它们在 restartKeysIn 里标出来告诉用户）。
+ *
+ * `onlyMissing` 给「被别人构造出来的 cfg」用（测试、嵌入）：那时调用方显式传的
+ * baseUrl / model / maxSteps 才是权威，不能拿配置文件去盖掉它。
+ */
+function applySettings(cfg, resolved, { onlyMissing = false } = {}) {
+  const v = resolved.values;
+  cfg.settings = resolved;
+  const put = (field, value) => {
+    if (onlyMissing && cfg[field] !== undefined) return;
+    cfg[field] = value;
+  };
+  put('model', v.model);
+  // 与 resolveBaseUrl 的既有口径一致：去掉尾部斜杠
+  put('baseUrl', String(v.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, ''));
+  put('defaultMode', normalizeMode(v.mode));
+  put('maxSteps', resolveMaxSteps(v.maxSteps));
+  put('compatLegacyTaskApi', v.compat.legacyTaskApi !== false);
+  // sessionLimits() 读的就是这几个扁平键，保持形状不变
+  if (!onlyMissing || cfg.taskTuning === undefined) {
+    cfg.taskTuning = {
+      sessionMaxBytes: v.session.maxBytes,
+      historyMaxChars: v.history.maxChars,
+      historyKeepRecentTurns: v.history.keepRecentTurns,
+      readFileDigest: v.history.readFileDigest !== false,
+    };
+  }
+  put('uiPersist', v.ui.persist === 'browser' ? 'browser' : 'server');
+  return cfg;
+}
+
+/** 环境变量来源：测试/嵌入使用时可以传一个空对象，把 env 层整个关掉 */
+const envOf = (cfg) => cfg.env || process.env;
+
+/**
+ * 重新解析配置。
+ *
+ * - 服务端自己拥有运行态时（runHub，`settingsAuthoritative`），顺带套用上去，
+ *   于是「手改 config.json 后刷新页面」也能生效；
+ * - 被别人构造出来的 cfg（测试、嵌入）只更新快照，不动调用方显式设置的字段。
+ *
+ * 每次 GET 都重读文件是有意的：用户改了配置却没看到变化时，第一个怀疑对象就是
+ * 「页面上还是旧值」，而原因可能就是他手写坏了文件 —— 那要以 warning 的形式显示出来。
+ */
+function refreshSettings(cfg) {
+  const next = resolveSettings({ file: cfg.settingsFile, env: envOf(cfg), args: cfg.settingsArgs || null });
+  if (cfg.settingsAuthoritative) applySettings(cfg, next);
+  else cfg.settings = next;
+  // 密钥：环境 / 启动参数给的时候文件不参与；否则每次重读文件 ——
+  // 于是「界面里填完」与「手工编辑 credentials.json 后刷新页面」两条路都立刻生效。
+  // 判据写成 `=== false` 而不是 `!keyFromEnv`：宿主/测试自己构造的 cfg 往往不带这个字段，
+  // 那种情况下**不能**因为文件里没有密钥就把调用方给的 cfg.key 抹掉。
+  if (cfg.secretFile && cfg.keyFromEnv === false) {
+    const read = readSecret({ file: cfg.secretFile, env: envOf(cfg) });
+    cfg.key = read.key;
+    if (cfg.keySource !== undefined) cfg.keySource = read.key ? 'file' : '';
+    if (read.warning) next.warnings = [...(next.warnings || []), read.warning];
+  }
+  return next;
+}
+
+/**
+ * 无密钥时的统一回执。
+ * 不用 401（那是「你给的凭据不对」），这里的前提是**根本还没配** —— 409 + needsKey 让页面
+ * 能识别出「该引导去设置面板」而不是弹一个红色错误就完事。
+ */
+function requireKey(res, cfg) {
+  if (cfg.key) return false;
+  sendJson(res, 409, {
+    error:
+      '还没有配置密钥：打开「设置」填 sk-xxx（会存到 credentials.json，仅本用户可读），'
+      + '或命令行执行 gateway-agent config set key sk-xxx，也可以设环境变量 GATEWAY_KEY / SK。',
+    needsKey: true,
+  });
+  return true;
+}
+
+/** /api/settings 的响应体：值 + 来源 + 白名单，页面据此渲染设置面板而不用各抄一份 */
+function settingsPayload(cfg) {
+  const r = cfg.settings || resolveSettings({ file: cfg.settingsFile, env: envOf(cfg) });
+  // 密钥行排在最前：它在页面上最该被先看到（没有它聊天与任务都用不了），
+  // 而它**不在** SETTINGS_SCHEMA 里 —— 所以永远不会被写进 config.json。
+  const keyEntry = keyRow({ env: envOf(cfg), file: cfg.secretFile || secretFilePath(envOf(cfg)), args: cfg.settingsArgs || null });
+  // 运行态为准：宿主（或测试）直接塞进 cfg.key、而文件/环境里没有时，页面不能显示「未配置」
+  if (cfg.key && !keyEntry.hasKey) {
+    keyEntry.hasKey = true;
+    keyEntry.mask = maskKey(cfg.key) || keyEntry.mask;
+    keyEntry.source = cfg.keySource || (cfg.keyFromEnv ? 'env' : 'file');
+    keyEntry.sourceText = secretSourceText(keyEntry.source);
+  }
+  return {
+    file: r.file,
+    exists: r.exists,
+    // fresh：服务端还没有配置 —— 页面据此决定要不要把浏览器里那份搬上来
+    fresh: !r.exists,
+    values: r.values,
+    sources: r.sources,
+    warnings: [...(r.warnings || []), ...[keyEntry.warning].filter(Boolean)],
+    uiPersist: cfg.uiPersist || 'server',
+    key: { hasKey: keyEntry.hasKey, mask: keyEntry.mask, file: keyEntry.file, source: keyEntry.source, sourceText: keyEntry.sourceText },
+    rows: [keyEntry].concat(listSettings(r).map((row) => ({
+      key: row.key,
+      value: row.value,
+      source: row.source,
+      def: row.def,
+      env: row.env,
+      flag: row.flag,
+      desc: row.desc,
+      restart: row.restart,
+      // 渲染所需的类型信息也一并给页面：它按 type 决定控件形状，不再自己判值类型
+      type: row.type,
+      values: row.values,
+      min: row.min,
+      max: row.max,
+    }))),
+  };
+}
+
+/** GET/PUT /api/settings —— 与 CLI 的 `gateway-agent config` 共用 lib/settings.js 的同一份白名单 */
+async function handleSettings(req, res, cfg) {
+  if (req.method === 'GET') {
+    refreshSettings(cfg);
+    return sendJson(res, 200, settingsPayload(cfg));
+  }
+
+  if (req.method !== 'PUT' && req.method !== 'POST') {
+    return sendJson(res, 405, { error: `/api/settings 只支持 GET / PUT，收到 ${req.method}` });
+  }
+
+  let body;
+  try {
+    body = await readBody(req);
+  } catch (e) {
+    return sendJson(res, e.status || 400, { error: e.message });
+  }
+  // 允许 { values: {...} } 或直接给一层扁平对象；忽略未知的外层包装
+  const patch = body && typeof body.values === 'object' && body.values !== null ? body.values : body;
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+    return sendJson(res, 400, { error: '请求体需要是 { "键": 值 } 形式的对象（键用点号路径，如 session.maxBytes）' });
+  }
+  // keys 在密钥分支**之后**再算：密钥要从 patch 里摘出去，摘之前算会把 'key' 当成
+  // 「密钥类配置项」再拒一次（同一次 PUT 里带密钥 + 别的键就会莫名其妙 400）
+
+  // 密钥走**单独一条路**：写 credentials.json（仅本用户可读）并立刻热更新，不写 config.json。
+  // 它必须排在「密钥红线」判断之前 —— 否则页面里那个输入框永远保存不了。
+  // 空串 = 清掉（页面上「清空密钥」的语义）；null / 未给 = 不动。
+  let keyNote = null;
+  let keyCleared = false;
+  if (Object.prototype.hasOwnProperty.call(patch, 'key')) {
+    const raw = patch.key;
+    delete patch.key;
+    if (raw === null || (typeof raw === 'string' && raw.trim() === '')) {
+      // 环境变量给的密钥不受这里影响：那种情况下文件本来就只是摆设
+      const cleared = clearSecret({ file: cfg.secretFile });
+      keyCleared = cleared.removed;
+      cfg.key = cfg.keyFromEnv ? cfg.key : '';
+      if (cfg.keyFromEnv) {
+        keyNote = '已清掉密钥文件，但当前进程的密钥来自环境变量 / --key，仍然生效。';
+      } else {
+        keyNote = cleared.removed ? '已清掉保存的密钥。' : '本来就没有保存过密钥。';
+      }
+    } else {
+      try {
+        const w = writeSecret(String(raw), { file: cfg.secretFile });
+        cfg.key = String(raw).trim();
+        cfg.keyFromEnv = false;
+        cfg.keySource = 'file';
+        keyNote = `密钥已保存到 ${w.file}${w.mode ? `（权限 ${w.mode.toString(8)}）` : ''}，立即生效。`
+          + (w.warning ? ` ${w.warning}` : '');
+      } catch (e) {
+        return sendJson(res, 400, { error: e.message, needsKey: true });
+      }
+    }
+    // 换了密钥，MCP 工具清单的缓存立即作废（与 /api/config 的刷新同一条路）
+    try {
+      await refreshMcpTools({ force: true, baseUrl: cfg.baseUrl, key: cfg.key });
+    } catch {
+      /* best-effort：网关没开 MCP / 断网都不该让「保存密钥」失败 */
+    }
+    if (!Object.keys(patch).length) {
+      refreshSettings(cfg);
+      return sendJson(res, 200, {
+        ok: true,
+        file: cfg.settingsFile,
+        applied: ['key'],
+        restart: [],
+        note: keyNote,
+        keyCleared,
+        ...settingsPayload(cfg),
+      });
+    }
+  }
+
+  // keys 在密钥分支**之后**再算：密钥已经从 patch 里摘掉了，这里不该再看到它
+  const keys = Object.keys(patch);
+
+  // 密钥放在最前面判：否则会先被报成「未知配置项」，用户看不到真正的原因
+  const secretKeys = keys.filter((k) => isSecretKey(k));
+  if (secretKeys.length) {
+    return sendJson(res, 400, { error: secretKeys.map((k) => parseSettingValue(k, patch[k]).error).join('\n') });
+  }
+  const unknown = keys.filter((k) => !isSettingKey(k) && !isUiStateKey(k));
+  if (unknown.length) {
+    return sendJson(res, 400, { error: unknown.map((k) => unknownKeyError(k)).join('\n') });
+  }
+
+  let result;
+  try {
+    result = writeSettings(patch, { file: cfg.settingsFile, allowUiState: true });
+  } catch (e) {
+    // 校验失败是 400（用户改错了）；文件坏了拒绝覆盖是 409（得先去修文件）
+    return sendJson(res, e.validation ? 400 : 409, { error: e.message });
+  }
+
+  // 立刻生效（除了要重启的那几个）
+  refreshSettings(cfg);
+  const restart = restartKeysIn(result.applied);
+  const notes = [keyNote, restart.length ? `以下配置要重启服务才生效：${restart.join('、')}` : null].filter(Boolean);
+  return sendJson(res, 200, {
+    ok: true,
+    file: result.file,
+    applied: keyNote ? ['key', ...result.applied] : result.applied,
+    restart,
+    note: notes.length ? notes.join(' ') : null,
+    keyCleared,
+    ...settingsPayload(cfg),
+  });
+}
+
+/** 建好 SSE 响应头并返回 send；任务与批准两条路径共用 */
+function startTaskStream(res) {
+  const send = openSse(res);
+  const controller = new AbortController();
+  res.on('close', () => controller.abort());
+  return { send, signal: controller.signal };
+}
+
+/** 一轮任务跑完后的收尾：挂起则登记运行态，最后统一发用量与结束事件 */
+async function finishOutcome({ outcome, run, send, res, cfg }) {
+  if (outcome.status === 'awaiting-approval') {
+    saveRun(run);
+    send({
+      type: 'approval_required',
+      runId: run.id,
+      callId: outcome.pending.id,
+      name: outcome.pending.name,
+      label: describeCall(outcome.pending.name, outcome.pending.args),
+      preview: outcome.preview,
+      note: `待批准状态保留 ${AGENT_LIMITS.APPROVAL_TTL_MS / 60000} 分钟（已落盘，刷新页面也不会丢）`,
+    });
+  }
+  // 计划模式的产物必须落盘：先写文件再报「计划已就绪」，页面拿到的路径一定是真的
+  const saved = savePlanDocIfNeeded({ run, outcome, cfg });
+  if (saved) {
+    send({ type: 'plan_saved', path: saved.relPath, bytes: saved.bytes, action: saved.action, summary: saved.summary });
+  }
+  send({ type: 'usage_total', usage: run.usage });
+  // 计划模式跑完就是「计划已就绪」，页面据此给出「按计划执行」
+  send({
+    type: 'done',
+    status: outcome.status,
+    planReady: Boolean(outcome.planReady),
+    planFile: saved?.relPath || run.planFile || '',
+    hitLimit: Boolean(outcome.hitLimit),
+  });
+  res.end();
+}
+
+/**
+ * 计划模式收尾：把模型给出的计划写进 `<workDir>/docs/YYYYMMDD-<概要>.md`。
+ *
+ * 为什么由服务端写、而不是给模型一个「写计划」的工具：
+ *   · 计划模式下写入工具**根本不发给模型**（见 `lib/agent.js` 的 toolsForMode），
+ *     为了让模型自己写而开一个写入口，那道「只读」闸门就漏了；
+ *   · 「计划必须落盘」是硬要求，不能寄希望于模型记得调工具。
+ *
+ * 落盘失败只是「这次没落盘」：记日志照常发 done，绝不让整轮任务因为磁盘问题失败。
+ * 路径与命名规则见 `lib/plandoc.js`。
+ */
+function savePlanDocIfNeeded({ run, outcome, cfg }) {
+  if (normalizeMode(run?.mode) !== 'plan') return null;
+  if (!outcome?.planReady && !outcome?.wrappedUp) return null;
+  const plan = lastAssistantText(run.messages);
+  if (!plan) return null;
+  try {
+    const saved = savePlanDoc({
+      workDir: run.workingDir,
+      plan,
+      // 计划里没有 `# 标题` 时拿首条用户消息兜底，总之文件名必须有概要
+      title: firstUserText(run.messages),
+    });
+    run.planFile = saved.relPath;
+    if (cfg?.verbose) console.log(`[task] 计划已落盘：${saved.relPath}（${saved.action}，${saved.bytes} 字节）`);
+    return saved;
+  } catch (e) {
+    if (cfg?.verbose) console.error(`[task] 计划落盘失败（本轮照常结束）：${e?.message || e}`);
+    return null;
+  }
+}
+
+/**
+ * 存储目录是否落在工作目录之内。
+ * 工具被沙箱限制在工作目录里，所以一旦存储目录也在里面，模型就能读到自己（以及别的任务）
+ * 的历史记录 —— 甚至改掉待批准调用。这不影响安全边界（本来就在授权范围内），
+ * 但属于「模型能看到不该看的东西」，必须提示用户。
+ */
+function storeInsideWorkDir(storeDir, workDir) {
+  if (!storeDir || !workDir) return false;
+  const rel = path.relative(path.resolve(workDir), path.resolve(storeDir));
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+/**
+ * 旧格式的 `/api/task`：前端把全量对白发上来，服务端跑完即弃。
+ *
+ * 保留它是为了兼容期的老前端与外部脚本，**不是**推荐路径：这条路上服务端没有会话，
+ * 工具结果进不了下一轮的上下文，模型会重复读文件。响应里会带一条 notice 说清楚。
+ */
+async function handleLegacyTask({ res, cfg, body, workDir, mode, model }) {
+  const messages = buildTaskMessages(body, workDir, mode);
+  if (messages.length < 2) return sendJson(res, 400, { error: 'messages 为空：至少需要一条 user 消息' });
+
+  const run = {
+    id: randomUUID(),
+    taskId: isSafeId(body.taskId) ? body.taskId : null,
+    mode,
+    messages,
+    model,
+    workingDir: workDir,
+    temperature: Number.isFinite(body.temperature) ? body.temperature : undefined,
+    maxTokens: Number.isFinite(body.maxTokens) && body.maxTokens > 0 ? body.maxTokens : undefined,
+    usage: { prompt: 0, completion: 0 },
+    pending: null,
+    touchedAt: Date.now(),
+  };
+
+  const { send, signal } = startTaskStream(res);
+  send({
+    type: 'started',
+    runId: run.id,
+    taskId: run.taskId,
+    workDir,
+    mode,
+    modeLabel: MODE_LABELS[mode],
+    tools: toolsForMode(mode).map((t) => t.function.name),
+    storeExposed: storeInsideWorkDir(cfg.store.dir, workDir),
+    legacy: true,
+    // 旧格式没有会话，也就没有跨轮次记住计划的地方：本轮照常落盘，但不回填这里
+    planFile: '',
+  });
+  send({
+    type: 'notice',
+    text:
+      '这次用的是旧的无状态格式（只发了对白、没发 taskId）：服务端无法在下一轮保留工具结果，' +
+      '模型可能会重复读取已经读过的文件。请改用「taskId + prompt」的新格式。',
+  });
+
+  try {
+    const outcome = await runAgent({ cfg, run, send, signal });
+    await finishOutcome({ outcome, run, send, res, cfg });
+  } catch (e) {
+    if (signal.aborted) return res.end();
+    if (cfg.verbose) console.error(`[task] 失败：${e?.message || e}`);
+    send({ type: 'error', message: e?.message || String(e), status: e?.status });
+    res.end();
+  }
+}
+
+async function handleTask(req, res, cfg) {
+  let body;
+  try {
+    body = await readBody(req, TASK_BODY_LIMIT);
+  } catch (e) {
+    return sendJson(res, e.status || 400, { error: e.message });
+  }
+
+  // 任务模式的工作目录是必需项 —— 没有它就退化成普通聊天了
+  let workDir;
+  try {
+    workDir = checkWorkDir(body.workDir);
+  } catch (e) {
+    return sendJson(res, e.status || 400, { error: e.message });
+  }
+
+  const mode = normalizeMode(body.mode);
+  const model = typeof body.model === 'string' && body.model.trim() ? body.model.trim() : cfg.model;
+  const prompt = typeof body.prompt === 'string' ? body.prompt : '';
+
+  // 旧格式：没给 prompt、却给了有内容的全量对白
+  const legacy =
+    !prompt.trim() &&
+    cfg.compatLegacyTaskApi !== false &&
+    Array.isArray(body.messages) &&
+    body.messages.some((m) => m && typeof m.content === 'string' && m.content.trim());
+  if (legacy) return handleLegacyTask({ res, cfg, body, workDir, mode, model });
+
+  /* ---------- 新格式：服务端持有会话（方案 C） ---------- */
+
+  const taskId = body.taskId;
+  if (!isSafeId(taskId)) {
+    return sendJson(res, 400, { error: 'taskId 非法：任务模式需要它来定位服务端持有的会话（必须是 UUID）' });
+  }
+  if (!prompt.trim()) return sendJson(res, 400, { error: 'prompt 为空：这一轮要做什么？' });
+  if (runningTasks.has(taskId)) {
+    const info = runningTasks.get(taskId) || {};
+    const secs = Math.max(1, Math.round((Date.now() - (info.startedAt || Date.now())) / 1000));
+    return sendJson(res, 409, {
+      error: `这条任务正在执行中（已 ${secs} 秒）。同一任务不允许并发 —— 否则两个请求会同时改写同一份会话文件。请等它结束，或先点停止。`,
+    });
+  }
+
+  const system = buildTaskSystemPrompt(workDir, body.system, mode);
+  let loaded;
+  try {
+    loaded = loadOrCreateTaskSession({
+      sessions: cfg.taskSessions,
+      taskId,
+      workDir,
+      model,
+      mode,
+      system,
+      renderTask: () => cfg.store.get(taskId),
+      limits: sessionLimits(cfg),
+    });
+  } catch (e) {
+    return sendJson(res, e.status || 500, { error: `会话载入失败：${e?.message || e}` });
+  }
+  const session = loaded.session;
+  session.workingDir = workDir;
+  session.model = model;
+  session.mode = mode;
+  session.temperature = Number.isFinite(body.temperature) ? body.temperature : undefined;
+  session.maxTokens = Number.isFinite(body.maxTokens) && body.maxTokens > 0 ? body.maxTokens : undefined;
+  session.pending = null;
+  // 这条任务已经有落盘的计划（上一轮计划模式写的，或刷新/重启后从磁盘读回来的）：
+  // 把「按这份计划执行」的约束重新拼进 system。换模式必须换 system 这件事
+  // 本来就由 refreshSessionContext 处理，这里只是把计划路径喂进去。
+  if (session.planFile) {
+    refreshSessionContext(session, {
+      workDir,
+      model,
+      mode,
+      system: buildTaskSystemPrompt(workDir, body.system, mode, { planFile: session.planFile }),
+    });
+  }
+  pushUser(session, prompt);
+
+  const { send, signal } = startTaskStream(res);
+  const storeExposed = storeInsideWorkDir(cfg.store.dir, workDir);
+  if (storeExposed) {
+    console.warn(`[task] 警告：存储目录 ${cfg.store.dir} 在工作目录 ${workDir} 之内，模型可以读到任务历史`);
+  }
+  // 开跑前统一准备：按预算压缩较早的工具正文，再把「已读文件清单」拼进 system。
+  // 必须在这里做、而不是每轮重建：压缩与清单一变，前缀就变，上游的 prompt 缓存全废。
+  const limits = sessionLimits(cfg);
+  const compaction = prepareTaskSession(session, {
+    limits,
+    cwd: workDir,
+    readFileDigest: limits.readFileDigest,
+  });
+  if (compaction.pruned && cfg.verbose) {
+    console.log(`[task] 历史预算：压缩 ${compaction.pruned} 条较早的工具结果（${compaction.before} → ${compaction.after} 字符）`);
+  }
+
+  send({
+    type: 'started',
+    runId: session.id,
+    taskId,
+    workDir,
+    mode,
+    modeLabel: MODE_LABELS[mode],
+    tools: toolsForMode(mode).map((t) => t.function.name),
+    storeExposed,
+    // 这条任务已落盘的计划文档（相对工作目录）：页面据此显示「本次依据哪份计划执行」
+    planFile: session.planFile || '',
+    session: {
+      created: loaded.created,
+      migrated: session.migrated,
+      degradedTurns: session.degradedTurns,
+      messages: session.messages.length,
+      compacted: compaction.pruned,
+    },
+  });
+  if (loaded.created && session.migrated === 'partial') {
+    send({
+      type: 'notice',
+      text:
+        `已完成旧数据迁移：这条任务历史里有 ${session.degradedTurns} 轮工具记录来自旧版本，` +
+        `调用参数已不可恢复（结果正文保留了下来）。之后不会再出现「重复读同一个文件」了。`,
+    });
+  }
+
+  runningTasks.set(taskId, { runId: session.id, startedAt: Date.now() });
+  try {
+    const outcome = await runAgent({ cfg, run: session, send, signal });
+    await finishOutcome({ outcome, run: session, send, res, cfg });
+  } catch (e) {
+    if (signal.aborted) {
+      res.end();
+      return;
+    }
+    if (cfg.verbose) console.error(`[task] 失败：${e?.message || e}`);
+    send({ type: 'error', message: e?.message || String(e), status: e?.status });
+    res.end();
+  } finally {
+    // 无论正常结束、报错、挂起还是用户中断，会话都要留下来 ——
+    // 这正是原来丢掉的那一半：工具结果从来没有跨轮次活下来过。
+    persistTaskSession(cfg, session);
+    runningTasks.delete(taskId);
+  }
+}
+
+async function handleApprove(req, res, cfg) {
+  let body;
+  try {
+    body = await readBody(req);
+  } catch (e) {
+    return sendJson(res, e.status || 400, { error: e.message });
+  }
+
+  const run = takeRun(String(body.runId || ''));
+  if (!run) {
+    const mins = AGENT_LIMITS.APPROVAL_TTL_MS / 60000;
+    return sendJson(res, 410, { error: `该任务已过期或不存在（挂起态保留 ${mins} 分钟），请重新发起任务` });
+  }
+  if (!run.pending || run.pending.id !== body.callId) {
+    return sendJson(res, 409, { error: '待批准的工具调用不匹配，可能已被处理' });
+  }
+
+  const { send, signal } = startTaskStream(res);
+  // 批准后的续跑同样会写会话文件，所以要跟新起一轮一样占住互斥
+  const taskId = isSafeId(run.taskId) ? run.taskId : null;
+  if (taskId) {
+    if (runningTasks.has(taskId)) {
+      return sendJson(res, 409, { error: '这条任务正在执行中，请等它结束再处理这次批准。' });
+    }
+    runningTasks.set(taskId, { runId: run.id, startedAt: Date.now() });
+  }
+  try {
+    // 续跑前同样要过一遍预算与清单：挂起态可能已经落盘很久（默认 60 分钟），
+    // 期间用户完全可能改过配置或手改过那些文件
+    prepareTaskSession(run, {
+      limits: sessionLimits(cfg),
+      cwd: run.workingDir,
+      readFileDigest: sessionLimits(cfg).readFileDigest,
+    });
+    const outcome = await resumeWithApproval({ cfg, run, send, signal, approved: Boolean(body.approved) });
+    // 这一轮已经做完（或被中止）就把挂起态彻底丢掉：否则磁盘上那份还留着 pending，
+    // 页面刷新后会冒出一张「已经决定过」的批准卡片，点下去只会得到 409。
+    // 如果又挂起了，finishOutcome 里会重新 saveRun，所以这里不能无脑删。
+    if (outcome.status !== 'awaiting-approval') dropRun(run.id);
+    await finishOutcome({ outcome, run, send, res, cfg });
+  } catch (e) {
+    dropRun(run.id);
+    if (signal.aborted) {
+      res.end();
+      return;
+    }
+    if (cfg.verbose) console.error(`[task] 批准后续跑失败：${e?.message || e}`);
+    send({ type: 'error', message: e?.message || String(e), status: e?.status });
+    res.end();
+  } finally {
+    // 续跑用的 run 来自挂起态落盘（另一个对象），跑完必须把模型态会话写回任务会话
+    persistTaskSession(cfg, run);
+    if (taskId) runningTasks.delete(taskId);
+  }
+}
+
+/** 任务数据存到磁盘后，服务端就是唯一真相；这里把增删改查都收口 */
+async function handleStore(req, res, cfg, p) {
+  const store = cfg.store;
+
+  if (p === '/api/store') {
+    if (req.method !== 'GET') return sendJson(res, 405, { error: `/api/store 只支持 GET，收到 ${req.method}` });
+    return sendJson(res, 200, {
+      ...store.stats(),
+      warnings: store.warnings,
+      source: cfg.storeSource,
+      // 模型态会话（方案 C）占用：用户要能看见它长到多大了
+      sessions: cfg.taskSessions.stats(),
+    });
+  }
+
+  if (p === '/api/tasks') {
+    if (req.method === 'GET') {
+      const removed = store.prune(); // 列表时顺手清一次，用户不必手动点清理
+      dropTaskSessions(cfg, removed); // 任务没了，它的模型态会话也要一起走，否则是孤儿泄漏
+      // running 是进程内的即时状态，不入库：侧边栏据此显示「进行中 / 已完成」
+      const tasks = store.list().map((t) => ({ ...t, running: runningTasks.has(t.id) }));
+      return sendJson(res, 200, { tasks, removed, ...store.stats() });
+    }
+    if (req.method === 'POST') {
+      let body;
+      try {
+        body = await readBody(req, TASK_BODY_LIMIT);
+      } catch (e) {
+        return sendJson(res, e.status || 400, { error: e.message });
+      }
+      try {
+        const task = store.create({
+          id: body.id,
+          title: body.title,
+          workDir: body.workDir,
+          mode: body.mode,
+          messages: body.messages,
+          // 任务树：带上 parentId 就是「在某条任务下派生」，服务端会校验父任务同目录且存在
+          parentId: body.parentId,
+        });
+        return sendJson(res, 201, { task });
+      } catch (e) {
+        return sendJson(res, e.status || 400, { error: e.message });
+      }
+    }
+    return sendJson(res, 405, { error: `/api/tasks 不支持 ${req.method}` });
+  }
+
+  if (p === '/api/tasks/prune') {
+    if (req.method !== 'POST') return sendJson(res, 405, { error: `/api/tasks/prune 只支持 POST，收到 ${req.method}` });
+    const removed = store.prune();
+    dropTaskSessions(cfg, removed);
+    return sendJson(res, 200, { removed, ...store.stats() });
+  }
+
+  // 剩下的都是 /api/tasks/<id>
+  let id;
+  try {
+    id = decodeURIComponent(p.slice('/api/tasks/'.length));
+  } catch {
+    return sendJson(res, 400, { error: '任务 id 编码非法' });
+  }
+  if (!isSafeId(id)) return sendJson(res, 400, { error: '任务 id 非法' });
+
+  if (req.method === 'GET') {
+    const task = store.get(id);
+    if (!task) return sendJson(res, 404, { error: '任务不存在或已过期' });
+    return sendJson(res, 200, { task });
+  }
+
+  if (req.method === 'PUT' || req.method === 'PATCH') {
+    let body;
+    try {
+      body = await readBody(req, TASK_BODY_LIMIT);
+    } catch (e) {
+      return sendJson(res, e.status || 400, { error: e.message });
+    }
+    const task = store.save(id, {
+      title: body.title,
+      workDir: body.workDir,
+      mode: body.mode,
+      messages: body.messages,
+      renamed: body.renamed,
+    });
+    if (!task) return sendJson(res, 404, { error: '任务不存在或已过期' });
+    return sendJson(res, 200, { task });
+  }
+
+  if (req.method === 'DELETE') {
+    const okDel = store.remove(id);
+    if (!okDel) return sendJson(res, 404, { error: '任务不存在' });
+    dropTaskSessions(cfg, [id]);
+    return sendJson(res, 200, { ok: true, ...store.stats() });
+  }
+
+  return sendJson(res, 405, { error: `/api/tasks/<id> 不支持 ${req.method}` });
+}
+
+/* ---------- 路由 ---------- */
+
+/**
+ * 清掉「任务已经不在了」的会话文件：任务被删时我们会顺手删会话，但服务没跑的时候
+ * 用户可能直接改过存储目录，或者上次删到一半崩了。启动时扫一遍最省心（最多 20 条任务）。
+ */
+function sweepOrphanSessions(cfg) {
+  let removed = 0;
+  try {
+    const live = new Set(cfg.store.list().map((t) => t.id));
+    for (const rec of cfg.taskSessions.list()) {
+      if (live.has(rec.taskId)) continue;
+      if (cfg.taskSessions.drop(rec.taskId)) removed++;
+    }
+  } catch {
+    /* 扫不动就算了，不阻塞启动 */
+  }
+  return removed;
+}
+
+export function createHubServer(cfg) {
+  // 允许被直接构造（测试、嵌入使用）：没给配置就自己解析一次，缺的字段从默认值补齐。
+  // runHub 会先解析好再传进来，这里只是兜底，不改变那条路径的行为。
+  if (!cfg.settingsFile) cfg.settingsFile = settingsFilePath(envOf(cfg));
+  if (!cfg.settings) applySettings(cfg, resolveSettings({ file: cfg.settingsFile, env: envOf(cfg), args: null }), { onlyMissing: true });
+
+  // 目录浏览与任务记录接口会把本机目录结构与文件正文暴露给调用方，
+  // 只在仅本机监听（或显式放行）时开放
+  const fsAllowed = () => cfg.fsEnabled;
+
+  return http.createServer(async (req, res) => {
+    const url = new URL(req.url, `http://${req.headers.host || '127.0.0.1'}`);
+    const p = url.pathname;
+    if (cfg.verbose) console.log(`[web] ${req.method} ${p}`);
+
+    try {
+      // 两个页面共用一个配置：聊天只读前几个字段，任务还要读 store / modes / limits
+      if (p === '/api/config' && req.method === 'GET') {
+        const allowed = fsAllowed();
+        // 先按磁盘重算一次：手工编辑了 config.json / credentials.json 之后，刷新页面就该生效，
+        // 而不是要重启服务（密钥那条尤其明显 —— 它现在也能由界面写）
+        refreshSettings(cfg);
+        // 先刷一次 MCP 清单再报工具：不刷的话，「页面刷新」这个动作在网关控制台里看不到任何
+        // GET /v1/mcp/tools，页面上的工具列表也只有内置那几个（缓存要等某次任务开跑才被填）。
+        // best-effort：网关没开 MCP / 断网 / 密钥无效时静默失败，行为与改动前一致；
+        // 60 秒 TTL 内不会重复出网（频繁刷新页面不会变成洪水）。
+        // 没密钥时直接跳过：拿空 Bearer 去撞网关只会白等一轮，页面本来就会显示「未配置」。
+        if (cfg.key) await refreshMcpTools({ baseUrl: cfg.baseUrl, key: cfg.key });
+        const info = {
+          baseUrl: cfg.baseUrl,
+          model: cfg.model,
+          hasKey: Boolean(cfg.key),
+          keyMask: maskKey(cfg.key),
+          // 密钥从哪来：页面据此说「环境变量给的，改配置文件没用」还是「在设置里填」
+          keySource: cfg.keySource || '',
+          keySourceText: secretSourceText(cfg.keySource || ''),
+          keyFile: cfg.secretFile || '',
+          mode: 'hub',
+          fsEnabled: allowed,
+          modes: MODES.map((m) => ({ id: m, label: MODE_LABELS[m], tools: toolsForMode(m).map((t) => t.function.name) })),
+          defaultMode: cfg.defaultMode,
+          limits: { maxSteps: resolveMaxSteps(cfg.maxSteps), runs: runStats() },
+          // 这里给的是「当前真正可用的工具」：bash 未由宿主开启时不会出现在列表里
+          tools: availableTools().map((t) => ({ name: t.function.name, description: t.function.description })),
+        };
+        // 存储目录是本机路径，只在放行（仅本机监听或 --allow-remote-fs）时才下发；
+        // 未放行时任务相关接口本来就全是 403，页面拿不到路径也不影响使用。
+        if (allowed) info.store = { ...cfg.store.stats(), warnings: cfg.store.warnings, source: cfg.storeSource };
+        return sendJson(res, 200, info);
+      }
+
+      // `default` 是「配置里没写 model 时服务端会用哪个」——设置面板拿它给下拉的第一项起名，
+      // 两个分支都回：拉不到列表时页面更要说清"默认是谁"。
+      if (p === '/api/models' && req.method === 'GET') {
+        // 没密钥就别去撞上游了：页面拿 needsKey 直接引导到设置面板，比回一句 401 明白
+        if (!cfg.key) {
+          return sendJson(res, 200, {
+            models: [],
+            default: cfg.model,
+            needsKey: true,
+            error: '还没有配置密钥：在「设置」里填 sk-xxx，或 gateway-agent config set key sk-xxx',
+          });
+        }
+        try {
+          return sendJson(res, 200, { models: await fetchModels(cfg), default: cfg.model });
+        } catch (e) {
+          return sendJson(res, e.status && e.status >= 400 ? 200 : 502, { models: [], default: cfg.model, error: e.message });
+        }
+      }
+
+      // ---------- 手册页（/manual）的数据源：三端指令对照 ----------
+      // 清单**不手写**：CLI 行来自 lib/commands.js，任务页行来自 public/task-slash.js（同一份表），
+      // 手册页拿到什么画什么 —— 谁少了一条，tests/manual.test.mjs 会当场抓住。
+      if (p === '/api/commands' && req.method === 'GET') {
+        return sendJson(res, 200, {
+          surfaces: [
+            {
+              id: 'cli',
+              label: '命令行 REPL（gateway-agent）',
+              where: '在终端跑 gateway-agent；命令表见 lib/commands.js',
+              commands: commandRows(),
+            },
+            {
+              id: 'hub',
+              label: '任务页（/task）',
+              where: '本服务的 /task：模型真读写你选的目录',
+              commands: taskSlash.commandRows(),
+            },
+            {
+              id: 'web',
+              label: '本机聊天页（/）',
+              where: '本服务的 /：纯对话，不碰文件',
+              commands: [],
+              note: '这一端没有斜杠指令：聊天页只把消息发给模型。（网关自带的 Web 对话页是另一个仓库的产品，另有它自己的一套。）',
+            },
+          ],
+          manual: '/manual',
+        });
+      }
+
+      // 费用粗估：单价表只有一份（lib/pricing.js），任务页 /cost 与 CLI /cost 因此同口径
+      if (p === '/api/cost' && req.method === 'GET') {
+        const usage = {
+          prompt: Number(url.searchParams.get('prompt')) || 0,
+          completion: Number(url.searchParams.get('completion')) || 0,
+        };
+        const model = url.searchParams.get('model') || cfg.model || '';
+        return sendJson(res, 200, { ...estimateCost(usage, model), text: formatCost(usage, model) });
+      }
+
+      // ---------- 聊天 ----------
+      if (p === '/api/chat') {
+        if (req.method !== 'POST') return sendJson(res, 405, { error: `/api/chat 只支持 POST，收到 ${req.method}` });
+        if (requireKey(res, cfg)) return;
+        return await handleChat(req, res, cfg);
+      }
+
+      // ---------- 任务 ----------
+      // 页面刷新后用它把「待批准」的卡片恢复出来（挂起态已落盘，重启服务也还在）
+      if (p === '/api/task/pending' && req.method === 'GET') {
+        if (!fsAllowed()) return sendJson(res, 403, { error: '待批准查询已禁用：服务未绑定在本机地址' });
+        const taskId = url.searchParams.get('taskId');
+        const all = listRuns();
+        return sendJson(res, 200, {
+          runs: taskId ? all.filter((r) => r.taskId === taskId) : all,
+          ttlMinutes: AGENT_LIMITS.APPROVAL_TTL_MS / 60000,
+        });
+      }
+
+      if (p === '/api/fs/roots' && req.method === 'GET') {
+        if (!fsAllowed()) return sendJson(res, 403, { error: '目录浏览已禁用：服务未绑定在本机地址' });
+        return sendJson(res, 200, { roots: listRoots() });
+      }
+
+      if (p === '/api/fs/list' && req.method === 'GET') {
+        if (!fsAllowed()) return sendJson(res, 403, { error: '目录浏览已禁用：服务未绑定在本机地址' });
+        const target = url.searchParams.get('path');
+        if (!target) return sendJson(res, 400, { error: '缺少 path 参数' });
+        try {
+          return sendJson(res, 200, browseDir(target));
+        } catch (e) {
+          return sendJson(res, e.status || 400, { error: e.message });
+        }
+      }
+
+      // ---------- 项目记忆（任务页指令 /instructions、/init） ----------
+      // 和目录浏览同一道闸门：这两个接口会回传本机路径与文件正文
+      if (p === '/api/memory' && req.method === 'GET') {
+        if (!fsAllowed()) return sendJson(res, 403, { error: '项目记忆已禁用：服务未绑定在本机地址' });
+        try {
+          return sendJson(res, 200, readMemory(checkWorkDir(url.searchParams.get('path'))));
+        } catch (e) {
+          return sendJson(res, e.status || 400, { error: e.message });
+        }
+      }
+
+      // 服务端自己决定内容的写入：**不经过审批闸门**（内容里没有模型给的东西），
+      // 所以它只做两件事：工作目录沙箱校验 + 已存在就不覆盖（除非显式 force）。
+      if (p === '/api/init' && req.method === 'POST') {
+        if (!fsAllowed()) return sendJson(res, 403, { error: '初始化已禁用：服务未绑定在本机地址' });
+        let body;
+        try {
+          body = await readBody(req);
+        } catch (e) {
+          return sendJson(res, 400, { error: `请求体不是合法 JSON：${e.message}` });
+        }
+        try {
+          const workDir = checkWorkDir(body.workDir);
+          const r = initInstructions({ workDir, force: Boolean(body.force) });
+          return sendJson(res, 200, { ...r, memory: readMemory(workDir) });
+        } catch (e) {
+          return sendJson(res, e.status || 400, { error: e.message });
+        }
+      }
+
+      // 任务记录里含工具读过的文件正文，属于本机数据：和目录浏览一样只对本机开放
+      if (p === '/api/store' || p === '/api/tasks' || p.startsWith('/api/tasks/')) {
+        if (!fsAllowed()) {
+          return sendJson(res, 403, { error: '任务记录存储已禁用：服务未绑定在本机地址（可用 --allow-remote-fs 放行）' });
+        }
+        return await handleStore(req, res, cfg, p);
+      }
+
+      // 配置里含本机路径（lastWorkDir / store.dir），与任务记录同级看待
+      if (p === '/api/settings') {
+        if (!fsAllowed()) {
+          return sendJson(res, 403, { error: '配置读写已禁用：服务未绑定在本机地址（可用 --allow-remote-fs 放行）' });
+        }
+        return await handleSettings(req, res, cfg);
+      }
+
+      if (p === '/api/task') {
+        if (req.method !== 'POST') return sendJson(res, 405, { error: `/api/task 只支持 POST，收到 ${req.method}` });
+        if (requireKey(res, cfg)) return;
+        return await handleTask(req, res, cfg);
+      }
+
+      if (p === '/api/task/approve') {
+        if (req.method !== 'POST') return sendJson(res, 405, { error: `/api/task/approve 只支持 POST，收到 ${req.method}` });
+        if (requireKey(res, cfg)) return;
+        return await handleApprove(req, res, cfg);
+      }
+
+      if (p === '/api/task/cancel' && req.method === 'POST') {
+        const body = await readBody(req).catch(() => ({}));
+        dropRun(String(body.runId || ''));
+        return sendJson(res, 200, { ok: true });
+      }
+
+      if (p.startsWith('/api/')) return sendJson(res, 404, { error: `未知接口 ${p}` });
+
+      if (req.method === 'GET' || req.method === 'HEAD') return serveStatic(req, res, p);
+      return sendJson(res, 405, { error: `不支持的方法 ${req.method}` });
+    } catch (e) {
+      if (!res.headersSent) sendJson(res, 500, { error: e?.message || String(e) });
+      else res.end();
+    }
+  });
+}
+
+/* ---------- 主流程 ---------- */
+
+export function runHub(argv, { entry = 'web' } = {}) {
+  const args = parseArgs(argv, VALUE_FLAGS, BOOL_FLAGS);
+  if (args.help) {
+    console.log(HELP);
+    return null;
+  }
+
+  // 密钥：--key > 环境变量 > .env > credentials.json（见 lib/secrets.js）。
+  // 环境里给了密钥时，文件不参与 —— 优先级与改动前完全一致。
+  const secretFile = secretFilePath();
+  const secret = resolveSecretKey({ args, env: process.env, file: secretFile });
+  const key = secret.key;
+  const keyFromEnv = Boolean(resolveKey(args));
+  for (const w of [secret.warning].filter(Boolean)) console.warn(`[警告] ${w}`);
+  // 配置的唯一解析口径（lib/settings.js）：--flag > 环境变量 > config.json > 内置默认
+  const settingsFile = settingsFilePath();
+  const settings = resolveSettings({ file: settingsFile, env: process.env, args });
+  for (const w of settings.warnings) console.warn(`[警告] ${w}`);
+  const baseUrl = resolveBaseUrl(args);
+  const model = strArg(args.model) || DEFAULT_MODEL;
+  // 老的两个服务各用各的环境变量名，这里都认
+  const port =
+    resolvePort(args, process.env, 'WEB_PORT', null) ??
+    resolvePort({}, process.env, 'TASK_WEB_PORT', DEFAULT_PORT);
+  const host = strArg(args.host) || strArg(process.env.WEB_HOST) || strArg(process.env.TASK_WEB_HOST) || '127.0.0.1';
+
+  // 没有密钥**不再退出**：以前这里 exit(1)，用户连界面都进不去，只能去手写 .env。
+  // 现在照常起服务，页面能打开、设置面板能填密钥 —— 缺密钥的请求由各接口回 409 needsKey。
+  if (!key) {
+    console.warn('[警告] 还没有配置密钥：页面能打开，但聊天与任务会提示缺少密钥。');
+    console.warn('       三种给法（任选其一）：');
+    console.warn('         ① 在页面「设置」里填（存到 credentials.json，仅本用户可读）');
+    console.warn('         ② gateway-agent config set key sk-xxx');
+    console.warn('         ③ 环境变量 GATEWAY_KEY / SK，或启动参数 --key sk-xxx');
+  }
+  if (port === null) {
+    console.error(`[错误] 端口非法：${strArg(args.port) || process.env.WEB_PORT || process.env.TASK_WEB_PORT}`);
+    process.exit(1);
+  }
+
+  const loopback = isLoopbackHost(host);
+  const fsEnabled = loopback || Boolean(args['allow-remote-fs']);
+  if (!loopback && !fsEnabled) {
+    console.warn(`[警告] 绑定在 ${host} 且未加 --allow-remote-fs：目录浏览与任务记录接口将返回 403。`);
+  } else if (!loopback) {
+    console.warn('[警告] 已用 --allow-remote-fs 开放目录浏览与任务记录，任何能访问该端口的人都能浏览本机目录、读取任务历史。');
+  }
+
+  // bash 与 --allow-remote-fs 是同一性质：显式、危险、默认关。
+  // 必须在建服务之前打开 —— /api/config 与每轮请求的工具清单都由 availableTools() 现算，
+  // 关着的时候 bash 压根不在清单里（模型连试都不会试）。这正是「任务模式跑不了测试、
+  // 只能反复说已静态复核」的根因：不是权限被拒，是这支笔从没发给过它。
+  setBashEnabled(Boolean(args['allow-bash']));
+  if (isBashEnabled()) {
+    console.warn(
+      '[警告] 已用 --allow-bash 开启命令执行：任务页「自动」模式下模型跑命令不会再逐个问你'
+      + '（手动模式仍会挂起等你批准）。命令仍在工作目录内执行，风险请自行评估。',
+    );
+  }
+
+  // 任务数据落盘。即使只用聊天页也要初始化 —— 任务页随时能打开
+  let resolved;
+  try {
+    // args/env 已经被 settings 合并过了（flag > env > config.json），这里再传一次也无妨
+    resolved = resolveStoreDir(strArg(settings.values['store.dir']) || args.store || null, ROOT_DIR);
+  } catch (e) {
+    console.error(`[错误] ${e.message}`);
+    process.exit(1);
+  }
+  let store;
+  try {
+    store = new TaskStore(resolved.dir).init();
+  } catch (e) {
+    console.error(`[错误] 任务存储初始化失败：${e.message}`);
+    process.exit(1);
+  }
+  if (resolved.notice) console.log(`[提示] ${resolved.notice}`);
+  if (resolved.warning) console.warn(`[警告] ${resolved.warning}`);
+  for (const w of store.warnings) console.warn(`[警告] ${w}`);
+
+  const mode = normalizeMode(args.mode || process.env.TASK_MODE || 'manual');
+  // 挂起态落盘：刷新页面、甚至重启服务后，待批准的写入都还在
+  setRunPersistence(createRunStore(path.join(store.dir, 'pending')));
+
+  const cfg = {
+    baseUrl,
+    model,
+    key,
+    verbose: Boolean(args.verbose),
+    fsEnabled,
+    store,
+    storeSource: resolved.source,
+    defaultMode: mode,
+    // 单次任务的模型轮次上限：--max-steps / TASK_MAX_STEPS 可覆盖
+    maxSteps: resolveMaxSteps(args['max-steps'] ?? process.env.TASK_MAX_STEPS),
+    // 旧的无状态 /api/task 是否继续接受（兼容期默认开，见 docs/20260916 的 7.1）
+    compatLegacyTaskApi: true,
+    taskTuning: {},
+    settingsFile,
+    env: process.env,
+    // 密钥文件与「密钥是不是环境给的」：refreshSettings() 靠这两个字段决定要不要重读文件
+    secretFile,
+    keyFromEnv,
+    keySource: secret.source,
+    // 运行态归服务端所有：配置文件改了要能立刻套上来
+    settingsAuthoritative: true,
+    settingsArgs: args,
+  };
+  // 把 config.json 里的值套上去（含 model / mode / maxSteps / 会话与历史预算 / 兼容开关）
+  applySettings(cfg, settings);
+  // 模型态会话落盘（方案 C）。限制传函数而不是对象：配置改了立刻生效，不必重建 store
+  // 会话（模型态上下文）默认跟着任务目录走；想单独放一份（比如任务目录在被同步的盘上、
+  // 会话想留在本机快盘）可以用 store.sessionDir 指到别处
+  const sessionDirSetting = strArg(settings.values['store.sessionDir']);
+  cfg.taskSessions = createTaskSessionStore(sessionDirSetting ? path.resolve(ROOT_DIR, sessionDirSetting) : path.join(store.dir, 'sessions'), () =>
+    sessionLimits(cfg),
+  );
+  const orphans = sweepOrphanSessions(cfg);
+  const server = createHubServer(cfg);
+
+  server.on('error', (e) => {
+    if (e.code === 'EADDRINUSE') console.error(`[错误] 端口 ${port} 已被占用：换一个 --port，或先关掉占用进程`);
+    else console.error(`[错误] 服务启动失败：${e.message}`);
+    process.exit(1);
+  });
+
+  server.listen(port, host, () => {
+    const s = store.stats();
+    console.log('LLM API Gateway · 本地 Web UI');
+    console.log(`  聊天   http://${host}:${port}/`);
+    console.log(`  任务   http://${host}:${port}/task`);
+    console.log(`  网关   ${baseUrl}`);
+    console.log(`  模型   ${model}`);
+    // 密钥一行要能回答「配没配、从哪来」——来源是环境时，credentials.json 不参与，这一点要说清
+    console.log(`  密钥   ${key ? `${maskKey(key)}（${secretSourceText(secret.source)}）` : '未配置'}`);
+    if (!key) {
+      console.log('         填法：页面「设置」里填（存 credentials.json，仅本用户可读）');
+      console.log('               或 gateway-agent config set key sk-xxx；或环境变量 GATEWAY_KEY / --key');
+    }
+    console.log(`  工具   ${availableTools().map((t) => t.function.name).join(' / ')}（计划模式只给只读工具）`);
+    console.log(`  模式   默认 ${MODE_LABELS[mode]}（${mode}）· 任务页可随时切换`);
+    console.log(`  存储   ${s.dir}`);
+    console.log(`         （${STORE_SOURCE_TEXT[resolved.source] || resolved.source}，当前 ${s.taskCount}/${s.maxTasks} 条，滑动保留 ${s.ttlDays} 天）`);
+    const sess = cfg.taskSessions.stats();
+    console.log(`  会话   ${sess.count} 条 / ${(sess.bytes / 1024).toFixed(0)}KB（模型态消息，让模型不必重复读文件）`);
+    if (orphans) console.log(`         启动时清掉了 ${orphans} 个没有任务的孤儿会话`);
+    console.log(`  配置   ${settingsFile}${settings.exists ? '' : '（还没有，用默认值；gateway-agent config set 可改）'}`);
+    console.log(`  密钥文件 ${secretFile}${secret.source === 'file' ? '' : '（当前没用它：密钥来自环境变量或启动参数）'}`);
+    console.log('  停止   Ctrl+C');
+    console.log('');
+    console.log(`  轮次   单个任务最多 ${cfg.maxSteps} 轮模型调用（--max-steps 可调）；撞到上限会先收尾给结论，再给「继续执行」`);
+    console.log('         写入按当前模式处理：手动逐个批准 / 自动直接执行 / 计划只读先出方案。');
+    if (entry === 'task') {
+      console.log('  提示   任务模式与聊天已合并到同一端口，/task 是任务页、/ 是聊天页。');
+    }
+  });
+
+  for (const sig of ['SIGINT', 'SIGTERM']) {
+    process.on(sig, () => {
+      console.log('\n[web] 正在关闭…');
+      server.close(() => process.exit(0));
+      setTimeout(() => process.exit(0), 1500).unref();
+    });
+  }
+
+  return server;
+}