llm-api-gateway-cli 1.0.0

package/lib/jsonstore.js

@@ -0,0 +1,49 @@
+/**
+ * JSON 原子写入（taskstore / runstore / sessionstore 共用）
+ *
+ * 为什么要单独抽一份：runstore 与 sessionstore 都需要「先写 .tmp 再 rename」，
+ * 而原来的写入函数是 runstore 的模块私有函数，sessionstore 根本拿不到，
+ * 只能各抄一遍 —— 那就等于把 Windows 上一次踩过的坑（rename 偶发 EPERM）再踩一次。
+ */
+
+import { writeFileSync, renameSync, unlinkSync } from 'node:fs';
+
+/** 同步睡一会儿（rename 重试用）。Atomics.wait 不占 CPU，比忙等好 */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * 先写 .tmp 再 rename —— 进程被杀也不会留下半截 JSON。
+ *
+ * Windows 上 rename 覆盖已存在的目标会偶发 EPERM（杀软或索引器短暂占用文件句柄），
+ * 短时间连续写时尤其容易撞上，所以重试几次；实在不行退回直接覆盖写，
+ * 宁可牺牲这一轮的原子性，也不能让保存整个失败。
+ *
+ * @param {string} file
+ * @param {*} value
+ * @param {{pretty?: boolean}} opts pretty=true 时按 2 空格缩进（便于人工查看）
+ */
+export function writeJsonAtomic(file, value, { pretty = false } = {}) {
+  const tmp = `${file}.tmp`;
+  const text = pretty ? JSON.stringify(value, null, 2) : JSON.stringify(value);
+  writeFileSync(tmp, text, 'utf8');
+  for (let i = 0; i < 5; i++) {
+    try {
+      renameSync(tmp, file);
+      return;
+    } catch (e) {
+      if (e.code !== 'EPERM' && e.code !== 'EACCES' && e.code !== 'EBUSY') throw e;
+      sleepSync(5 * (i + 1));
+    }
+  }
+  try {
+    writeFileSync(file, text, 'utf8');
+  } finally {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* 忽略 */
+    }
+  }
+}

package/lib/mcp.js

@@ -0,0 +1,375 @@
+/**
+ * MCP 工具源（客户端自助执行）
+ *
+ * 网关的 MCP 有两种「谁执行工具」的分工，各有一个说不通的地方：
+ *  · `loop`   —— 网关代执行：调用链全在网关里跑完，客户端只拿到最终回答。
+ *                代价是那几轮**没有真流式**（网关必须整读响应才能判断是不是工具轮），
+ *                而且工具调用**绕过客户端**：工具卡片、人工批准、计划模式的只读约束全部失效。
+ *  · `inject` —— 只把工具定义注入「网关 → 上游」那一跳：客户端会收到 `tool_calls`，
+ *                但**看不到清单**（名字、参数 schema 都只在那一跳里），也没有执行通道。
+ *
+ * 本模块走第三条路，把「拿清单」和「执行」两件事交给 CLI：
+ *   GET  /v1/mcp/tools  → 本密钥绑定范围内的工具（名字 + schema）
+ *   → 当成 CLI 自己的工具声明给模型（同名会抑制网关注入，模型只看到一份定义）
+ *   → 模型调用时 POST /v1/mcp/call，由网关转发到第三方（限流与审计仍在网关侧统一做）
+ * 于是流式照常、工具卡片与批准流程照常，而出网那一跳仍归网关管。
+ *
+ * 三条硬约束（都体现在实现里，改动时别丢）：
+ *  1. **best-effort**：网关没开 MCP / 网络不通 / 密钥无效时静默降级成「没有这些工具」。
+ *     绝不能因为 MCP 把一次正常对话搞挂——这是本模块唯一不可让步的性质。
+ *  2. **同步读缓存**：`availableTools()` 是同步函数且在请求路径上被调用，
+ *     所以清单只能提前刷新进内存，不能在请求路径上 await。
+ *  3. **不覆盖内置工具**：同名以内置为准。内置工具带沙箱语义，不能被远端工具顶掉
+ *     （`mcpToolSpecs(reserved)` 的 reserved 就是为此传入的）。
+ */
+import { sessionBaggage } from './common.js';
+
+/**
+ * 「这次调用属于哪个任务节点」的头。
+ *
+ * 由**网关**在对话响应里回带（`X-DSH-Plan-Node: log<账本行 id>`），CLI 原样回带在
+ * `/v1/mcp/call` 上，网关据此把这次工具调用**精确**挂到触发它的那一步。
+ * 没有它，网关只能靠会话标识挂到任务级（或干脆不挂）——同任务多步并发时，
+ * 想知道"这个工具是哪一步调的"就只能按时间猜，而那是编造。
+ *
+ * 只回带**形状合法**的值：这个值来自响应头（外部输入），网关那边也会校验，
+ * 但掺进一个畸形值没有任何好处，不如根本不发（网关随即退回会话级口径）。
+ */
+const PLAN_NODE_HEADER = 'x-dsh-plan-node';
+const PLAN_NODE_RE = /^log[0-9]+$/;
+
+/** 清单缓存：一次会话内复用，过期或显式刷新时重取 */
+const DEFAULT_TTL_MS = 60 * 1000;
+/** 拉清单的超时。必须短：它在会话开场路径上，网关不可达时不能让人干等 */
+const FETCH_TIMEOUT_MS = 4000;
+/**
+ * 失败后的冷却。
+ *
+ * 为什么需要：CLI 现在**启动时就会先拉一次**（横幅要显示真实工具清单），紧接着第一轮
+ * 对话开场还会走同一段逻辑。没有冷却的话，网关没开 MCP / 断网时，一次对话要白等两个
+ * 4 秒超时 —— 而这两个请求注定都失败。冷却期内状态与文案照旧（仍报同一个原因），
+ * 只是不再重复出网；超时后会自然重试，网关修好了不必重启 CLI。
+ */
+const FAIL_TTL_MS = 30 * 1000;
+
+let conn = { baseUrl: '', key: '', fetchImpl: null, ttlMs: DEFAULT_TTL_MS };
+let cache = emptyCache();
+let inflight = null;
+
+/** 排障开关：GATEWAY_MCP_DEBUG=1 时把清单/调用打到 stderr（默认完全闭嘴）。
+ *  「CLI 到底有没有请求工具接口」必须能自己看出来，不能只靠翻网关日志推断。 */
+const debugOn = () => Boolean(process.env.GATEWAY_MCP_DEBUG);
+function debug(...parts) {
+  if (debugOn()) console.error('[mcp]', ...parts);
+}
+
+function emptyCache() {
+  return {
+    tools: [], servers: [], skipped: [], mode: '', enabled: false,
+    at: 0, failedAt: 0,
+    // 真正向网关发出过请求的时间戳（0 = 一次都没发）。
+    // 「本密钥到底有没有去问过工具清单」必须能从 CLI 自己看出来：
+    // 只看 loaded/error 区分不了「压根没发请求」（GATEWAY_MCP=off / 密钥配置不全 / 密钥被污染）
+    // 与「发了但失败」（网关 404 / 断网），而这两种情况的下一步完全不同。
+    attemptedAt: 0,
+    error: '', loaded: false,
+  };
+}
+
+/** 记下网关地址与密钥（每次 runAgent 用当次 cfg 覆盖，避免跨会话串味） */
+export function configureMcp({ baseUrl, key, fetchImpl, ttlMs } = {}) {
+  conn = {
+    // 两端去空白：从文件/环境变量里读来的值常常带换行或尾随空格
+    baseUrl: String(baseUrl || '').trim().replace(/\/+$/, ''),
+    key: String(key || '').trim(),
+    fetchImpl: fetchImpl || conn.fetchImpl,
+    ttlMs: Number.isFinite(ttlMs) && ttlMs >= 0 ? ttlMs : DEFAULT_TTL_MS,
+  };
+  if (cache.baseUrl !== conn.baseUrl || cache.key !== conn.key) {
+    // 换了网关或换了密钥：旧清单可能属于另一把密钥的绑定范围，必须作废
+    cache = emptyCache();
+  }
+  cache.baseUrl = conn.baseUrl;
+  cache.key = conn.key;
+  return conn;
+}
+
+/** 复位（测试与「换会话」用） */
+export function resetMcpTools() {
+  cache = emptyCache();
+  inflight = null;
+}
+
+const pickFetch = () => (typeof conn.fetchImpl === 'function' ? conn.fetchImpl : globalThis.fetch);
+
+function timeoutSignal() {
+  // 老 Node 没有 AbortSignal.timeout：退化成不带超时，而不是抛错
+  return typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function'
+    ? AbortSignal.timeout(FETCH_TIMEOUT_MS)
+    : undefined;
+}
+
+/**
+ * 刷新工具清单（best-effort，**永不抛**）。
+ * 失败时保留上一次的清单并记下原因：陈旧的清单通常还能用，而清空会让工具
+ * 在会话中途无声消失——那比一个 404 更难排查。
+ */
+export async function refreshMcpTools({ force = false, baseUrl, key } = {}) {
+  if (baseUrl || key) configureMcp({ baseUrl, key });
+  // GATEWAY_MCP=off：客户端完全不参与 MCP —— 不拉清单、不声明工具、不执行，
+  // 工具的注入与执行全交给网关（后台把该密钥的绑定模式设成 loop）。
+  // 这条路 CLI「不需要知道 tools」，代价是那几轮没有真流式、且绕过 CLI 的批准。
+  if (String(process.env.GATEWAY_MCP || '').toLowerCase() === 'off') {
+    const kept = { baseUrl: cache.baseUrl, key: cache.key };
+    cache = { ...emptyCache(), ...kept };
+    cache.error = '已按 GATEWAY_MCP=off 关闭（MCP 交给网关处理）';
+    debug('GATEWAY_MCP=off：不拉清单、不声明 MCP 工具');
+    return cache;
+  }
+  if (!conn.baseUrl || !conn.key) {
+    // attemptedAt 归零：这两个早退分支要说清「压根没发请求」，别把上一轮的记录留在这儿
+    cache = { ...cache, error: '未配置网关地址或密钥', attemptedAt: 0 };
+    return cache;
+  }
+  // 环境变量/配置文件被污染时（混进中文、换行、多行输出），Node 的 fetch 只会抛
+  // 「Cannot convert argument to a ByteString」——完全指不到病根。而 CLI 是静默降级，
+  // 用户最终只看到「工具莫名没了」。所以在发请求之前先拦下来说清楚。
+  const badChar = [...conn.key].find((ch) => ch.charCodeAt(0) > 255);
+  if (badChar) {
+    cache = {
+      ...cache,
+      error: '密钥里有非 ASCII 字符（' + JSON.stringify(badChar)
+        + '），多半是环境变量/配置文件被污染：值应当是纯 ASCII 的网关密钥',
+      loaded: false,
+      attemptedAt: 0, // 同上：这是「没发出去」，不是「发了失败」
+    };
+    debug('密钥含非 ASCII 字符，已放弃请求网关（检查存放密钥的环境变量是否混入了别的输出）');
+    return cache;
+  }
+  // 两种情况都不再出网：① 拉成功过且在 TTL 内；② 刚失败过（冷却，见 FAIL_TTL_MS）。
+  // 注意冷却只挡「重复出网」，不挡 force —— 显式刷新永远真的发请求。
+  const fresh = cache.loaded && Date.now() - cache.at < conn.ttlMs;
+  const cooled = !cache.loaded && cache.failedAt > 0 && Date.now() - cache.failedAt < FAIL_TTL_MS;
+  if (!force && (fresh || cooled)) {
+    debug(cooled
+      ? '上次拉清单失败在 ' + Math.round((Date.now() - cache.failedAt) / 1000) + 's 前，冷却期内不重试（原因照旧：' + cache.error + '）'
+      : '清单命中缓存（' + Math.round((Date.now() - cache.at) / 1000) + 's 前拉的），本次不请求网关');
+    return cache;
+  }
+  if (inflight) return inflight; // 并发请求合并成一次
+
+  inflight = (async () => {
+    try {
+      const f = pickFetch();
+      if (typeof f !== 'function') throw new Error('当前 Node 没有 fetch（需要 Node 18+）');
+      cache = { ...cache, attemptedAt: Date.now() }; // 记下「真的发过」——成功/失败分支都会继承
+      const resp = await f(`${conn.baseUrl}/v1/mcp/tools`, {
+        method: 'GET',
+        headers: { authorization: `Bearer ${conn.key}` },
+        signal: timeoutSignal(),
+      });
+      if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+      const data = await resp.json();
+      const tools = Array.isArray(data?.tools) ? data.tools : [];
+      cache = {
+        ...cache,
+        tools,
+        servers: Array.isArray(data?.servers) ? data.servers : [],
+        skipped: Array.isArray(data?.skipped) ? data.skipped : [],
+        mode: String(data?.mode || ''),
+        enabled: data?.enabled !== false,
+        at: Date.now(),
+        failedAt: 0, // 成功一次就把冷却清掉，别让旧失败影响后面
+        error: '',
+        loaded: true,
+      };
+      debug('GET ' + conn.baseUrl + '/v1/mcp/tools → HTTP ' + resp.status + ' · ' + tools.length
+        + ' 个工具 · 服务器 ' + cache.servers.length + ' 台 · 模式 ' + (cache.mode || '未报'));
+    } catch (e) {
+      // 这里刻意只记不抛：网关没开 MCP、断网、密钥错，都不该影响对话本身
+      cache = { ...cache, error: e?.message || String(e), at: Date.now(), failedAt: Date.now(), loaded: cache.loaded };
+      debug('GET ' + conn.baseUrl + '/v1/mcp/tools 失败：' + cache.error + '（本次不启用 MCP 工具，对话照常）');
+    } finally {
+      inflight = null;
+    }
+    return cache;
+  })();
+  return inflight;
+}
+
+/**
+ * 内置工具名（由 `lib/tools.js` 在模块加载时登记）。
+ *
+ * 远端工具与内置**同名时必须让位**：内置工具带工作目录沙箱语义，
+ * 被同名远端工具顶掉，等于把「受限的本机读文件」换成「任意远端调用」。
+ * 这不是洁癖，是权限边界——而且撞名时**报错**比默默换实现更难发现，
+ * 所以这里在做任何分派之前就把它们剔除干净。
+ */
+let reservedNames = new Set();
+
+export function setMcpReserved(names) {
+  reservedNames = names instanceof Set ? new Set(names) : new Set(names || []);
+}
+
+/** 真正可用的 MCP 工具（已剔除与内置同名的） */
+const usableTools = () => cache.tools.filter((t) => t && t.name && !reservedNames.has(t.name));
+
+/** 工具名 → 清单条目（同步；未加载/不存在/与内置同名都返回 null） */
+export function mcpToolInfo(name) {
+  const n = String(name || '');
+  return usableTools().find((t) => t.name === n) || null;
+}
+
+export const isMcpTool = (name) => Boolean(mcpToolInfo(name));
+
+export const mcpToolCount = () => usableTools().length;
+
+/**
+ * 给 UI 列清单用（`/mcp` 命令与启动横幅）：可用工具的简要信息。
+ * 与 `availableTools()` 同一份来源、同一套剔除规则，所以「页面/终端上看到的」
+ * 一定就是「声明给模型的」，不会各说各的。
+ */
+export function mcpToolList() {
+  return usableTools().map((t) => ({
+    name: t.name,
+    server: t.server || '',
+    tool: t.tool || t.name,
+    description: t.description || '',
+  }));
+}
+
+/**
+ * 转成 CLI 内置工具的同一形状（OpenAI function spec）。
+ * `reserved` 是内置工具名集合：同名的一律丢掉，内置优先（约束 3）。
+ */
+export function mcpToolSpecs(reserved) {
+  const taken = reserved instanceof Set ? reserved : new Set(reserved || []);
+  return usableTools()
+    .filter((t) => !taken.has(t.name))
+    .map((t) => ({
+      type: 'function',
+      function: {
+        name: t.name,
+        description: `[MCP·${t.server || '远端'}] ${t.description || ''}`.trim(),
+        parameters: t.input_schema && typeof t.input_schema === 'object'
+          ? t.input_schema
+          : { type: 'object', properties: {} },
+      },
+    }));
+}
+
+/** 参数摘要：审批弹窗与工具卡片都要一眼看出「这次要查什么」 */
+function argBrief(args = {}) {
+  const a = args && typeof args === 'object' ? args : {};
+  const first = Object.values(a).find((v) => typeof v === 'string' && v.trim());
+  const text = first || JSON.stringify(a);
+  return String(text || '').replace(/\s+/g, ' ').slice(0, 60);
+}
+
+/** 工具卡片上的一行说明 */
+export function describeMcpCall(name, args = {}) {
+  const info = mcpToolInfo(name);
+  const where = info?.server ? `${info.server} · ` : '';
+  const what = info?.tool || name;
+  const brief = argBrief(args);
+  return `MCP ${where}${what}${brief ? `（${brief}）` : ''}`;
+}
+
+/**
+ * 审批弹窗的预览。MCP 工具没有本地文件，返回一个「文件式预览」形状但内容是参数 JSON——
+ * 复用既有的批准面板，不为了一个新工具类别去改前端渲染。
+ *
+ * **注意：它现在不在批准路径上了。** MCP 调用不再走人工审批闸门（见 tools.js 的
+ * `isFileWriteTool`：逐个批准会让调研类任务的十几次地图查询全被拒，而放开只能靠 `--yes`，
+ * 那会把任意文件写入一起放开）。所以 `writePreview` 里分发到这里的那个分支目前不可达；
+ * 保留它是为了不改动既有测试，也为了万一将来需要重新收紧时有个现成的面板。
+ * 那句「结果会进入对话上下文（不可信输入）」的提醒**依然成立**，它现在写在 README 里。
+ */
+export function mcpPreview(name, args = {}) {
+  const info = mcpToolInfo(name);
+  const body = JSON.stringify(args && typeof args === 'object' ? args : {}, null, 2);
+  return {
+    path: `${info?.server || 'MCP'} · ${info?.tool || name}`,
+    exists: false,
+    bytes: Buffer.byteLength(body),
+    lines: body.split('\n').length,
+    content: body,
+    old: null,
+    patch: false,
+    note: '远端 MCP 工具调用：由网关转发给第三方服务器，结果会进入对话上下文（不可信输入）。',
+  };
+}
+
+/** 会话开场/排障用的一行状态 */
+export function mcpStatusText() {
+  const usable = usableTools();
+  if (!cache.loaded && !cache.error) return 'MCP：未加载';
+  if (cache.error) return `MCP：不可用（${cache.error}）`;
+  if (!usable.length) return 'MCP：本密钥未绑定任何可用工具';
+  const names = cache.servers.map((s) => `${s.name}(${s.tool_count})`).join('、');
+  return `MCP：${usable.length} 个工具 · ${names}${cache.mode ? ` · 模式 ${cache.mode}` : ''}`;
+}
+
+/**
+ * 对话请求要带的 MCP 头。
+ *
+ * 只有一种情况需要干预：网关那边绑定模式是 `loop`，而 CLI 这边也拿到了工具
+ * ——两边都会执行同一个工具，等于**一次提问跑两遍第三方**（地图类会白烧配额）。
+ * 这时让网关这一轮别插手；`off` 只作用于本次请求，不改后台配置，也不影响
+ * 别的客户端。模式是 `inject`/`off` 时 CLI 执行才是唯一执行方，不需要这个头。
+ */
+export function mcpHeadersForChat() {
+  if (cache.loaded && cache.mode === 'loop' && usableTools().length) {
+    return { 'x-mcp-tools': 'off' };
+  }
+  return {};
+}
+
+/**
+ * 执行一个 MCP 工具（交给网关转发）。
+ * 返回 CLI 统一的 `{ok, summary, content}`；**工具自身报错也算成功返回**——
+ * 把那句错误文本回灌给模型，它才能换个查法把活干完。
+ * 只有传输层/协议层失败（网关 401、超时、5xx）才抛，由 safeExec 转成失败结果。
+ *
+ * `ctx.planNode` / `ctx.sessionId`：这次调用属于哪一步、哪个会话（见上面
+ * PLAN_NODE_HEADER 的说明）。两者都是**尽力而为**：拿不到就不发，
+ * 网关会退回它自己的口径，功能不受影响，只是挂接精度差一档。
+ */
+export async function callMcpTool(name, args = {}, ctx = {}) {
+  const f = pickFetch();
+  if (typeof f !== 'function') throw new Error('当前 Node 没有 fetch（需要 Node 18+）');
+  if (!conn.baseUrl || !conn.key) throw new Error('未配置网关地址或密钥，无法调用 MCP 工具');
+  const headers = { 'content-type': 'application/json', authorization: `Bearer ${conn.key}` };
+  const planNode = String(ctx?.planNode ?? '');
+  if (PLAN_NODE_RE.test(planNode)) headers[PLAN_NODE_HEADER] = planNode;
+  const baggage = sessionBaggage(ctx?.sessionId);
+  if (baggage) headers.baggage = baggage;
+  debug('POST ' + conn.baseUrl + '/v1/mcp/call ' + name
+    + (planNode ? ' @' + planNode : '')
+    + (baggage ? ' [' + baggage + ']' : ''));
+  const resp = await f(`${conn.baseUrl}/v1/mcp/call`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ name, arguments: args && typeof args === 'object' ? args : {} }),
+    signal: timeoutSignal(),
+  });
+  if (!resp.ok) {
+    let detail = `HTTP ${resp.status}`;
+    try {
+      const body = await resp.json();
+      if (body?.detail) detail = `${detail}: ${body.detail}`;
+    } catch {
+      /* 非 JSON 错误体：保留状态码就够了 */
+    }
+    throw new Error(detail);
+  }
+  const data = await resp.json();
+  const text = String(data?.text ?? '');
+  const failed = data?.is_error === true || data?.ok === false;
+  const firstLine = text.split('\n').find((l) => l.trim()) || '';
+  return {
+    ok: !failed,
+    summary: `${data?.server ? `${data.server} · ` : ''}${data?.tool || name} → ${firstLine.slice(0, 80) || (failed ? '失败' : '完成')}`,
+    content: text || (failed ? '（工具没有返回内容）' : '（空结果）'),
+  };
+}

package/lib/memory.js

@@ -0,0 +1,109 @@
+/**
+ * 项目记忆（AGENTS.md / CLAUDE.md）与工作目录初始化
+ *
+ * E 组指令的地基：`/instructions` 看这个工作目录注入给模型的是什么，`/init` 生成一份骨架。
+ *
+ * 为什么单独成文件：这些文件**既被 CLI 启动时读取**（注入 system prompt，见 cli-agent.js），
+ * **又被 Web 任务页的指令读写**（`/api/memory`、`/api/init`）。两处各写一遍文件名数组
+ * 和长度上限，迟早漂移成"CLI 认 CLAUDE.md、网页只认 AGENTS.md"这种鬼故事。
+ *
+ * 读的一半没有副作用；写的一半**必然绕过审批**（内容是服务端自己定的，不是模型提议的），
+ * 所以它只走 tools.js 里那套工作目录沙箱检查（`writeInsideRoot`），不做任何额外放行。
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { writeInsideRoot } from './tools.js';
+
+/** 约定：工作目录里这两个文件都算项目记忆，靠前的优先（与 cli-agent 的启动注入一致） */
+export const MEMORY_FILES = ['AGENTS.md', 'CLAUDE.md'];
+
+/** 注入上限：超过就截断。别把上下文全吃光 —— 4KB 足够写清"怎么跑测试"这类事 */
+export const MEMORY_MAX_CHARS = 4096;
+
+/**
+ * 读一个工作目录里的项目记忆。
+ * 不做任何路径解析魔法：文件名固定，位置固定在目录根部（这也是模型的约定）。
+ *
+ * @returns {{workDir:string, files:Array<object>, text:string, limit:number, hasAny:boolean}}
+ */
+export function readMemory(workDir) {
+  const files = [];
+  for (const name of MEMORY_FILES) {
+    const file = path.join(workDir, name);
+    if (!existsSync(file)) {
+      files.push({ name, path: file, exists: false });
+      continue;
+    }
+    try {
+      const raw = readFileSync(file, 'utf8');
+      files.push({
+        name,
+        path: file,
+        exists: true,
+        bytes: Buffer.byteLength(raw, 'utf8'),
+        chars: raw.length,
+        truncated: raw.length > MEMORY_MAX_CHARS,
+        content: raw.length > MEMORY_MAX_CHARS ? `${raw.slice(0, MEMORY_MAX_CHARS)}\n…（项目记忆过长已截断）` : raw,
+      });
+    } catch (e) {
+      // 读不到就当没有：记忆文件不该让整个接口失败（权限、编码问题都可能）
+      files.push({ name, path: file, exists: false, error: e.message });
+    }
+  }
+  const text = files
+    .filter((f) => f.content)
+    .map((f) => `# 项目记忆：${f.name}\n${f.content}`)
+    .join('\n\n');
+  return { workDir, files, text, limit: MEMORY_MAX_CHARS, hasAny: files.some((f) => f.exists) };
+}
+
+export const INIT_FILE = 'AGENTS.md';
+
+/**
+ * `/init` 的骨架内容。
+ * 刻意写得"像一张待填的表"而不是一段范文：让人（和模型）一眼看出哪些格子还空着。
+ */
+export const INIT_TEMPLATE = `# 项目约定（AGENTS.md）
+
+> 这个文件由 \`/init\` 生成，请把**这个项目自己的**规矩写在下面：
+> Agent 每次开工前都会先读它，写得越具体，越少来回问。
+
+## 这是什么
+（一句话：这个目录/仓库是做什么的）
+
+## 怎么跑
+- 安装：
+- 启动：
+- 测试：
+- 构建：
+
+## 约定
+- 动手前先读相关文件，不要凭猜测改
+- 改动尽量小、聚焦当前任务；不顺手重构无关代码
+- 提交信息一句话说清「改了什么、为什么」
+- 不要动：（生成物、密钥、别人的实验目录……）
+
+## 目录速览
+（用页面上的 \`/files\` 或 /files 看目录，把关键路径写在这里）
+`;
+
+/**
+ * 生成项目记忆文件（默认 AGENTS.md）。
+ * 已存在且没给 force 时**不覆盖**，只回报"已存在"—— 覆盖别人的约定是破坏性操作。
+ *
+ * @returns {{path:string, rel:string, bytes:number, written:boolean, existed:boolean}}
+ */
+export function initInstructions({ workDir, force = false, template = INIT_TEMPLATE, name = INIT_FILE } = {}) {
+  if (!MEMORY_FILES.includes(name)) {
+    throw Object.assign(new Error(`只允许初始化项目记忆文件：${MEMORY_FILES.join(' / ')}`), { status: 400 });
+  }
+  const target = path.join(workDir, name);
+  if (existsSync(target) && !force) {
+    return { path: target, rel: name, bytes: 0, written: false, existed: true };
+  }
+  const text = template.endsWith('\n') ? template : `${template}\n`;
+  const r = writeInsideRoot(workDir, name, text, { overwrite: true });
+  return { path: r.path, rel: r.rel, bytes: r.bytes, written: true, existed: r.overwrote };
+}