@xiaobuyu/nodesign 0.0.1

package/server/engine/browse/screencast.js

@@ -0,0 +1,170 @@
+/**
+ * server/engine/browse/screencast.js — 把 agent 的浏览器画面推给用户（2026-08-18）
+ *
+ * 用户要的形态：「**用通用显示器来播放 agent 当前浏览器操作画面，必要时人类可以
+ * 协助 agent**」。这个模块是那条像素通路加上行输入。
+ *
+ * ## 为什么是 CDP screencast（而不是轮询截图）
+ *
+ * ⭐ **screencast 是 damage-driven**（实测）：页面静止时 30 秒只发 1 帧、0.1% 单核；
+ * 一次 DOM 改动 = 一帧。所以代价全在「页面在动 + 有人看」，静止时近乎免费。
+ * 周期性 `page.screenshot()` 轮询正好丢掉这个免费午餐 —— 页面动不动都要编码一张，
+ * 在 1 vCPU 上更差。
+ *
+ * ## 1 vCPU 上的账（⚠️ 实测纠正过一次归因）
+ *
+ * ⚠️ **这一节我写错过一次，纠正如下。**
+ *
+ * 第一版量的是「动画页 + 没人订阅 85.6% / 有人订阅 86.6%」，据此写了「贵的是页面
+ * 自己在动，画面流几乎免费」。两处都错：
+ *   - 基线**本来就吃满核了**（只剩 ~14pp 余量），推流的成本被天花板挡住
+ *   - 用的是 `ps` 的 `pcpu`，那是进程**生命周期平均值**，量不出增量
+ *
+ * 改用 `/proc` 的 utime+stime 差分 + 稳态等待，在**有余量**的页面上量两次：
+ *
+ *   小元素每 100ms 变一次：基线 1.3% → 订阅中 7.6% → 退订 1.8%（漂移 0.5pp）
+ *       → 净成本 **+6.0pp @ 2.0 fps**
+ *   小元素 rAF 每帧变：    基线 4.0% → 订阅中 43.5% → 退订 4.1%（漂移 0.2pp）
+ *       → 净成本 **+39.4pp @ 12.2 fps**
+ *
+ * 两点独立，每 fps 约 **3.1pp 单核**。所以：**满帧推流要吃掉约 40% 单核**，
+ * `MAX_ACTIVE = 1` 恰恰是唯一能把这个核还回来的刹车 —— 不是"便宜无害的装饰"。
+ * （待考虑没做：没人看时用 `Emulation.setVirtualTimePolicy` 把页面本身冻住，
+ *  能再省下页面动画那部分，但有些页面 resume 会坏，要真跑一批站才敢上。）
+ *
+ * 三道刹车：
+ * 1. **帧率硬压**：`everyNthFrame=5`（60fps 动画 → ~12fps）、`quality=45`、`maxWidth=1024`
+ * 2. ⭐ **ack 门控背压**：CDP 的 screencast 是 ack 驱动的 —— 只在 socket 没堵
+ *    （`bufferedAmount` 低于阈值）时才 `screencastFrameAck`。socket 堵住就不 ack，
+ *    chromium 自然停发下一帧。**把"没人接得住"直接变成"不生产"**，不丢帧也不排队膨胀。
+ * 3. **没人看就停**：最后一个订阅者断开 → 立刻 `stopScreencast`，不等浏览器空闲回收。
+ *    同时活跃画面流全局 ≤1（**这条是 CPU 定的，不是内存**）。
+ */
+
+/** 帧参数：1 vCPU 下的取舍，别调高（改这里前先拿 `top` 量一遍） */
+const CAST = { format: 'jpeg', quality: 45, maxWidth: 1024, maxHeight: 700, everyNthFrame: 5 };
+/** socket 里积压超过这个就不再 ack（= 让 chromium 停发） */
+const BACKPRESSURE_BYTES = 256 * 1024;
+/** 全局同时只允许一路活跃画面流。**这是 CPU 的主要保护**：满帧推流约 40% 单核
+ * （见文件头的实测），这台机器只有一个核。 */
+const MAX_ACTIVE = 1;
+
+/** projectId → { page, cdp, subs:Set<ws>, meta } */
+const casts = new Map();
+
+function activeCount() {
+  let n = 0;
+  for (const c of casts.values()) if (c.subs.size) n += 1;
+  return n;
+}
+
+/**
+ * 让某个 socket 订阅某项目的画面。
+ * @returns {Promise<{ok:true}|{ok:false, reason:string}>}
+ */
+let subscribing = false;   // 绕过二的锁，见下
+
+export async function subscribe(projectId, ws, page) {
+  let cast = casts.get(projectId);
+  // ⛔ **上限检查要在"这一路要不要开始编码"上判，不是在"有没有这个条目"上判**
+  // （审查攻出来的两个绕过）：
+  //   ① 退订只清 subs、**不删 casts 里的条目**，于是"再订一次"会走进 `cast` 已存在
+  //      那一支，整个跳过上限检查 —— 两路同时推流。
+  //   ② 检查之后紧跟着 await（建 CDP 会话），两个并发 subscribe 都能过。
+  const willStartCasting = !cast || !cast.casting;
+  if (willStartCasting) {
+    if (subscribing) {
+      return { ok: false, reason: '另一路画面正在建立，稍等一下再打开这扇窗。' };
+    }
+    if (activeCount() >= MAX_ACTIVE) {
+      // ⚠️ 这个上限是**全机器**的（CPU 是全机器的），所以占着它的那一路很可能
+      // 属于**别的项目、甚至别的用户**。原来的话术是"先关掉另一扇浏览器窗"，
+      // 那扇窗他既看不见也关不掉 —— 一句让人白忙的假指令。说实话就行。
+      const mine = casts.get(projectId)?.subs?.size ? '（就是这个项目自己的那扇）' : '（在别的会话里，你看不到也关不掉）';
+      return { ok: false, reason: `这台机器同时只能推一路浏览器画面，现在有一路在跑${mine}。`
+        + '满帧推流约吃 40% 个核（实测），而这里只有 1 个核。等那边看完再打开，'
+        + '或者让 agent 用截图代替实时画面。' };
+    }
+    subscribing = true;
+  }
+  try {
+  if (!cast) {
+    const cdp = await page.context().newCDPSession(page);
+    cast = { projectId, page, cdp, subs: new Set(), meta: null, casting: false };
+    casts.set(projectId, cast);
+
+    cdp.on('Page.screencastFrame', (ev) => {
+      cast.meta = ev.metadata;   // 里面有 deviceWidth/deviceHeight —— 接手时坐标换算要用
+      const buf = Buffer.from(ev.data, 'base64');
+      let anyoneKeepingUp = false;
+      for (const sock of cast.subs) {
+        if (sock.readyState !== 1) continue;
+        // ⭐ 堵住的 socket 直接跳过这一帧（画面会掉帧，但不会积压）
+        if (sock.bufferedAmount > BACKPRESSURE_BYTES) continue;
+        anyoneKeepingUp = true;
+        try { sock.send(buf, { binary: true, compress: false }); } catch { /* 下一帧再说 */ }
+      }
+      // ack 决定 chromium 发不发下一帧：没人接得住就不 ack = 不生产
+      if (anyoneKeepingUp) {
+        cdp.send('Page.screencastFrameAck', { sessionId: ev.sessionId }).catch(() => {});
+      } else {
+        // 留一条慢速心跳，免得所有人都堵住之后再也不恢复
+        setTimeout(() => {
+          cdp.send('Page.screencastFrameAck', { sessionId: ev.sessionId }).catch(() => {});
+        }, 500).unref?.();
+      }
+    });
+  }
+
+  cast.subs.add(ws);
+  if (!cast.casting) {
+    await cast.cdp.send('Page.startScreencast', CAST);
+    cast.casting = true;
+    // ⭐ 立刻补一帧。screencast 是 damage-driven —— 静止页面订阅之后可能**一帧都不发**，
+    // 用户看到的是一扇全白的窗，而它其实是"连上了但页面没动"。
+    // 这条是审查锐化出来的：接手功能在静止页面上由构造决定会失败（窗白着没法点）。
+    try {
+      const shot = await cast.cdp.send('Page.captureScreenshot', { format: 'jpeg', quality: CAST.quality });
+      const buf = Buffer.from(shot.data, 'base64');
+      for (const sock of cast.subs) {
+        if (sock.readyState === 1) sock.send(buf, { binary: true, compress: false });
+      }
+    } catch { /* 补不上就等页面自己动 */ }
+  }
+  return { ok: true };
+  } finally {
+    if (willStartCasting) subscribing = false;
+  }
+}
+
+/** 退订。最后一个人走了就停止编码。 */
+export async function unsubscribe(projectId, ws) {
+  const cast = casts.get(projectId);
+  if (!cast) return;
+  cast.subs.delete(ws);
+  if (cast.subs.size) return;
+  if (cast.casting) {
+    await cast.cdp.send('Page.stopScreencast').catch(() => {});
+    cast.casting = false;
+  }
+  // 条目留着也没用（下次订阅要重新 startScreencast），而留着正好造出上面那个
+  // "跳过上限检查"的绕过。删掉 —— `activeCount()` 数的是"有订阅者的路"，
+  // 但少一个空壳条目也少一处可以钻的缝。
+  casts.delete(projectId);
+}
+
+/** 浏览器被关掉时（空闲回收 / LRU 淘汰）把这一路彻底忘掉 */
+export function forget(projectId) {
+  const cast = casts.get(projectId);
+  if (!cast) return;
+  casts.delete(projectId);
+  for (const sock of cast.subs) {
+    try { sock.send(JSON.stringify({ type: 'closed', reason: 'browser was shut down' })); } catch { /* */ }
+  }
+}
+
+/** 当前帧的设备像素尺寸 —— 接手时前端坐标要按它换算 */
+export function frameMeta(projectId) {
+  return casts.get(projectId)?.meta ?? null;
+}
+

package/server/engine/browse/state.js

@@ -0,0 +1,121 @@
+/**
+ * server/engine/browse/state.js — 浏览器在桌面上留下的那点持久痕迹（2026-08-18）
+ *
+ * ## 为什么需要它
+ *
+ * 浏览器实例本身是**进程内的、易失的**（`registry.js` 的 Map，空闲 5 分钟就回收，
+ * pm2 重启就没了）。这是对的 —— 浏览器真的没了。
+ *
+ * 但用户要的是「**桌面上有一张浏览器卡片，随时能进去看和用**」（2026-08-18 拍板，
+ * 推翻了当初 BrowserWindow 里那句「你不会想在桌面上永久摆着一张某次浏览的卡片」）。
+ * 卡片要活得比实例长：agent 昨天逛过的站，今天打开项目还应该看得见那张卡，双击
+ * 就回到那一页。所以要有一点**落盘**的状态。
+ *
+ * ## 落哪儿
+ *
+ * `<pid>/.browser/`，跟 chromium 的 profile 同级、在 `shared/` **外面**。
+ * 理由跟 profile 一样（registry.js 里核过）：`shared/` 是 agent 的 cwd 也是
+ * artifact-file 的服务根，放进去等于让 agent 能 Read 自己的浏览历史、
+ * 还会被当文件服出去、还进 per-project git。删项目时 `<pid>/` 整个删掉，
+ * 这里跟着走，不用另写清理。
+ *
+ * ## 两份东西，两种性质
+ *
+ * - `state.json` —— 上次在哪一页（`{url, title, at}`）。导航/点击后写，**必须极便宜
+ *   且永不抛**：它长在导航路径上，为了一张卡片让 agent 的导航失败是划不来的。
+ * - `last.webp` —— 上次看到的样子（卡片上那块预览）。
+ *   ⭐ 只在**本来就截了图**的时候顺手存（`browser_screenshot` 的视口档），
+ *   或者用户正在看画布、preview 端点现截一张。**不为了刷新卡片主动截图** ——
+ *   实测视口截图在 stripe/小红书这种站上要 1.7~4.2 秒，而这台机器只有 1 个核。
+ *
+ * 卡上的预览因此是「**上次看到的样子**」，跟 word 卡是同一路数（那也是一张静态页图）。
+ * 活的画面流只在窗打开时给：实测每 fps 约 3.1pp 单核，满帧 40%。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { getProjectWorkspace } from '../../projects/workspace.js';
+
+const dirOf = (projectId) => path.join(getProjectWorkspace(projectId), '.browser');
+const STATE_FILE = 'state.json';
+const FRAME_FILE = 'last.webp';
+
+/** 卡片预览的绝对路径（存在与否由调用方 stat） */
+export function framePath(projectId) {
+  return path.join(dirOf(projectId), FRAME_FILE);
+}
+
+/**
+ * 记一笔「现在在这一页」。**永不抛** —— 它挂在导航路径上。
+ * @param {string} projectId
+ * @param {import('playwright').Page} page
+ */
+export async function recordVisit(projectId, page) {
+  try {
+    const url = page.url();
+    if (!/^https?:/.test(url)) return;      // about:blank / chrome-error 不值得记
+    const title = await page.title().catch(() => '');
+    const dir = dirOf(projectId);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, STATE_FILE), `${JSON.stringify({
+      url, title: title || null, at: new Date().toISOString(),
+    }, null, 2)}\n`, 'utf8');
+  } catch { /* 记不下来就算了，不能因此让导航失败 */ }
+}
+
+/**
+ * 上次在哪一页。没逛过 → null（桌面上就没有这张卡）。
+ * @returns {Promise<{url: string, title: string|null, at: string}|null>}
+ */
+export async function readVisit(projectId) {
+  try {
+    const raw = await fs.readFile(path.join(dirOf(projectId), STATE_FILE), 'utf8');
+    const v = JSON.parse(raw);
+    return (v && typeof v.url === 'string' && /^https?:/.test(v.url)) ? v : null;
+  } catch { return null; }
+}
+
+/**
+ * 存一帧当卡片预览。传的是原始截图 buffer，这里缩成卡片尺寸再落盘。
+ *
+ * 卡片预览区 640×400（`ARTIFACT_PREVIEW_H.browse`），主角档 ×1.5 = 960 宽，
+ * 所以存 1024 宽足够，再大是白占盘和白花编码时间。**永不抛。**
+ */
+export async function saveFrame(projectId, buf) {
+  try {
+    const { default: sharp } = await import('sharp');
+    const out = await sharp(buf).resize({ width: 1024, withoutEnlargement: true })
+      .webp({ quality: 72 }).toBuffer();
+    const dir = dirOf(projectId);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, FRAME_FILE), out);
+    return out.length;
+  } catch { return 0; }
+}
+
+/**
+ * 忘掉这个项目的浏览痕迹 —— 桌面上那张卡随之消失。
+ *
+ * 为什么需要：卡片的存在判据是 `state.json` 在不在，而它一旦写下就永远在 ——
+ * 一个月前逛过一次的项目，桌面上会一直摆着那张卡赶不走。这是"卡活得比实例长"
+ * 的代价，得给个出口。
+ *
+ * ⚠️ **profile 不删**（`.browser/default/`）：登录态是资产，用户点的是"这张卡
+ * 我不看了"，不是"把我在那个站的登录清掉"。
+ */
+export async function forgetVisit(projectId) {
+  const dir = dirOf(projectId);
+  await Promise.all([
+    fs.unlink(path.join(dir, STATE_FILE)).catch(() => {}),
+    fs.unlink(path.join(dir, FRAME_FILE)).catch(() => {}),
+  ]);
+}
+
+/** 上次那张预览的字节 + mtime；没有 → null */
+export async function readFrame(projectId) {
+  const file = framePath(projectId);
+  try {
+    const [buf, st] = await Promise.all([fs.readFile(file), fs.stat(file)]);
+    return { buf, mtime: st.mtime };
+  } catch { return null; }
+}

package/server/engine/chatai/chat-log.js

@@ -0,0 +1,79 @@
+/**
+ * chat-log.js —— 演出的对话记录与摘要落盘。
+ *
+ * 对话记录（默认 `对话.jsonl`，可在 编排.yaml 的 历史.文件 改）：
+ *   一行一条 { seq, role: 'user'|'assistant', text, at }。
+ *   ⭐ 只存双方真实发言，永远只追加、永远不删——摘要折叠掉的轮次仍然留在
+ *   文件里（编译时靠 摘要.json 的 `至` 跳过），全量记录随时可重放、可导出。
+ *
+ * 摘要（固定名 `摘要.json`，派生态不给改名旋钮）：
+ *   { 至, 内容, 时, 模型, 用量, 花费 } —— `至` 是被折叠的最后一条记录的 seq，
+ *   滚动覆盖写（旧摘要在生成新摘要时被并入，不单独存档）。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+export const SUMMARY_FILE = '摘要.json';
+
+function logPath(dir, config) {
+  const rel = config?.历史?.文件 || '对话.jsonl';
+  const abs = path.resolve(dir, rel);
+  if (abs !== path.resolve(dir) && !abs.startsWith(path.resolve(dir) + path.sep)) {
+    throw Object.assign(new Error(`历史.文件「${rel}」跑出了演出文件夹`), { code: 'ORCH_INVALID' });
+  }
+  return abs;
+}
+
+/** 读全量记录。文件不存在 = 空场；坏行跳过不炸（记录是追加型文件，尾行可能残缺）。 */
+export async function readLog(dir, config) {
+  let raw;
+  try { raw = await fs.readFile(logPath(dir, config), 'utf8'); } catch { return []; }
+  const out = [];
+  for (const line of raw.split('\n')) {
+    const s = line.trim();
+    if (!s) continue;
+    try {
+      const r = JSON.parse(s);
+      if (Number.isInteger(r.seq) && (r.role === 'user' || r.role === 'assistant') && typeof r.text === 'string') {
+        out.push(r);
+      }
+    } catch { /* 残行跳过 */ }
+  }
+  return out;
+}
+
+/**
+ * 追加一轮（user + assistant 成对写入，调用成功之后才落盘——失败的调用
+ * 不留半条记录，重试不会双写）。
+ */
+export async function appendTurn(dir, config, userText, assistantText) {
+  const records = await readLog(dir, config);
+  const last = records.length ? records[records.length - 1].seq : 0;
+  const at = new Date().toISOString();
+  const lines = [
+    { seq: last + 1, role: 'user', text: String(userText), at },
+    { seq: last + 2, role: 'assistant', text: String(assistantText), at },
+  ];
+  await fs.appendFile(
+    logPath(dir, config),
+    lines.map(r => JSON.stringify(r)).join('\n') + '\n',
+    'utf8',
+  );
+  return lines;
+}
+
+export async function readSummary(dir) {
+  try {
+    const s = JSON.parse(await fs.readFile(path.join(dir, SUMMARY_FILE), 'utf8'));
+    return (s && Number.isInteger(s.至) && typeof s.内容 === 'string') ? s : null;
+  } catch { return null; }
+}
+
+/** 原子写（tmp + rename）：摘要生成要花一次真调用，别让并发读读到半个文件。 */
+export async function writeSummary(dir, summary) {
+  const target = path.join(dir, SUMMARY_FILE);
+  const tmp = `${target}.tmp`;
+  await fs.writeFile(tmp, JSON.stringify(summary, null, 2), 'utf8');
+  await fs.rename(tmp, target);
+}

package/server/engine/chatai/index.js

@@ -0,0 +1,193 @@
+/**
+ * chatai —— 第二条模型通路（跟 agent 会话完全无关）
+ *
+ * agent 走 Claude Agent SDK、有工具、会改文件；**chatai 只是一次补全调用**：
+ * 传进去 system + messages，回来一段文本和用量。它没有工具、没有会话、
+ * 改不了任何东西。
+ *
+ * 存在的理由不是省钱，是**别让高频生成挤掉设计会话**：订阅通路是全站共享的一个
+ * OAuth 额度加并发上限，而生成类动作频次高，一跑起来能把正经设计会话挤没。
+ *
+ * 通路配置走 env（`CHATAI_BASE_URL` / `CHATAI_API_KEY` / `CHATAI_MODEL`），
+ * 密钥不进代码不进 git。
+ *
+ * 计价：上游中转站的计量口径不透明，所以金额一律按**我们自己的单价表**算，
+ * 谁要拿它进配额闸门就用这个数。
+ */
+
+import { callOpenAICompat } from './openai-compat.js';
+
+/**
+ * 模型表 —— 单价、思考档位、中转站实名，一张表说完（2026-08-15 加思考档）。
+ *
+ * 单价 USD / 1M token。gemini-3.7-flash 是促销价，2027-01-01 起翻倍到 1.5 / 7.5。
+ * 思考 token 按输出计价（Gemini 的口径；Claude 的思考量直接混在 completion_tokens 里）。
+ *
+ * ⭐ **思考等级在中转站是模型名的一部分，不是请求参数**（2026-08-15 实测它家 100 个
+ * 模型：gemini 系是 -low/-medium/-high 三个独立模型名，claude 系是 base 与 -thinking
+ * 两个）。所以「档」不发 reasoning_effort，而是换实名。用户那边只看见标准名 + 一个
+ * 档位旋钮，换渠道时改这张表就行。
+ *
+ * 思耗 = 粗估的「思考 token ÷ 正文 token」倍数，只给设置页算预演帐目用，不进计费。
+ * 实测（演出类提示，2026-08-15）：gemini flash 正文 234 / 思考 785 ≈ 3.4 倍，且
+ * 低/中/高 三档的思考量差异淹在噪声里（785/587/601），别把它当精确旋钮；
+ * claude 开思考后正文 363→408、输入 115→144（中转站往提示里塞了东西）。
+ */
+export const MODEL_SPECS = Object.freeze({
+  'gemini-3.7-flash': {
+    价: { in: 0.75, out: 3.75 }, 思耗: 3.4,
+    注: '$0.75 / $3.75 每百万 · 促销价，思考计入输出',
+    默认档: '低',
+    档: {
+      低: { 名: '反重力-流式抗截断/gemini-3.7-flash-low', 注: '最省，中转站的常规档' },
+      中: { 名: '反重力-流式抗截断/gemini-3.7-flash-medium', 注: '中档' },
+      高: { 名: '反重力-流式抗截断/gemini-3.7-flash-high', 注: '让它多想一会儿（实测三档差异有限，别指望它是精确旋钮）' },
+    },
+  },
+  'gemini-3.6-flash': {
+    价: { in: 0.75, out: 3.75 }, 思耗: 3.4,
+    注: '$0.75 / $3.75 每百万 · 上一版，行文更收敛',
+    默认档: '低',
+    档: {
+      低: { 名: '反重力-流式抗截断/gemini-3.6-flash-low', 注: '最省，中转站的常规档' },
+      中: { 名: '反重力-流式抗截断/gemini-3.6-flash-medium', 注: '中档' },
+      高: { 名: '反重力-流式抗截断/gemini-3.6-flash-high', 注: '让它多想一会儿' },
+    },
+  },
+  'gemini-3-flash': {
+    价: { in: 0.50, out: 2.50 }, 思耗: 3.0,
+    注: '$0.50 / $2.50 每百万 · 更便宜，思考档不可调',
+    实名: '反重力-流式抗截断/gemini-3-flash',
+    档: null,
+  },
+  'claude-sonnet-4-6': {
+    价: { in: 3.00, out: 15.00 }, 思耗: 1,
+    注: '$3 / $15 每百万 · 文笔更稳，一轮贵一个量级',
+    默认档: '关',
+    档: {
+      关: { 名: '反重力-流式抗截断/claude-sonnet-4-6', 思耗: 1, 注: '不开扩展思考' },
+      高: { 名: '反重力-流式抗截断/claude-sonnet-4-6-thinking', 思耗: 1.3, 注: '开扩展思考：思考走单独通道不进台词，但按输出计价' },
+    },
+  },
+  'claude-opus-4-6': {
+    价: { in: 15.00, out: 75.00 }, 思耗: 1,
+    注: '$15 / $75 每百万 · 只在真的在乎的场合；中转站常报没容量',
+    默认档: '关',
+    档: {
+      关: { 名: '反重力-claude-opus-4-6', 思耗: 1, 注: '不开扩展思考' },
+      高: { 名: '反重力-claude-opus-4-6-thinking', 思耗: 1.3, 注: '开扩展思考：思考不进台词，但按输出计价' },
+    },
+  },
+});
+
+/** 档位词表 —— 编排.yaml 只认这四个词，设置页只画模型支持的那几档 */
+export const LEVELS = Object.freeze(['关', '低', '中', '高']);
+
+/** 单价表（USD / 1M token），从模型表派生 —— 价格只有一处定义 */
+export const PRICES = Object.freeze({
+  ...Object.fromEntries(Object.entries(MODEL_SPECS).map(([k, v]) => [k, v.价])),
+  _default: { in: 1.00, out: 5.00 },
+});
+
+/** 从中转站的花式模型名里认出计价用的底模（`反重力-流式抗截断/gemini-3.7-flash-low`） */
+export function priceKeyOf(model) {
+  const s = String(model || '').toLowerCase();
+  for (const k of Object.keys(PRICES)) {
+    if (k !== '_default' && s.includes(k)) return k;
+  }
+  return '_default';
+}
+
+/** 按单价表估这次调用多少钱。缓存读按输入价一折（隐式缓存的通行口径） */
+export function costOf(model, usage) {
+  const p = PRICES[priceKeyOf(model)];
+  const inTok = Math.max(0, (usage.inputTokens || 0) - (usage.cacheReadTokens || 0));
+  const cached = usage.cacheReadTokens || 0;
+  const outTok = (usage.outputTokens || 0) + (usage.reasoningTokens || 0);
+  return (inTok * p.in + cached * p.in * 0.1 + outTok * p.out) / 1e6;
+}
+
+export function chataiConfig() {
+  const base = (process.env.CHATAI_BASE_URL || '').replace(/\/+$/, '');
+  const key = process.env.CHATAI_API_KEY || '';
+  const model = process.env.CHATAI_MODEL || '';
+  return { base, key, model, ok: !!(base && key && model) };
+}
+
+/** 简写 → 标准名（历史遗留的手写值，别再往里加） */
+const SHORTHAND = Object.freeze({ 'claude-sonnet': 'claude-sonnet-4-6' });
+
+/**
+ * 标准模型名 + 思考档 → 中转站实名（2026-08-15 时停之城 503 案 + 思考档）。
+ *
+ * 中转站的 100 个模型**没有一个裸标准名**，全是「反重力-流式抗截断/xxx」这类
+ * 前缀变体，思考等级也编在名字里。而 编排.yaml / 设置页 / skill 教的都是标准名
+ * （用户不该学中转站的命名黑话，换渠道也不用改配置）。这层在发请求前换成实名。
+ *
+ * 档给空或者这个模型不支持这档 → 落到模型的默认档（每个模型的默认档都是最便宜
+ * 那档），并把降级理由报回去：设置页只画支持的档，但 编排.yaml 是 agent 和人手写的，
+ * 写岔了不该拒开演出，只该说清楚跑的是哪档。
+ * 表里没有的模型名原样放行（直接写实名也合法）。env `CHATAI_MODEL_ALIASES`（JSON）
+ * 覆盖标准名→实名，写了就绕开档位（中转站哪天改名，改 env 不用动代码）。
+ *
+ * @returns {{ 名: string, 档: string|null, 降级: string|null, 思耗: number }}
+ */
+export function resolveModelVariant(model, 档) {
+  const empty = { 名: model, 档: null, 降级: null, 思耗: 1 };
+  if (!model) return empty;
+  let extra = {};
+  try { extra = JSON.parse(process.env.CHATAI_MODEL_ALIASES || '{}'); } catch { /* 坏 JSON 当没配 */ }
+  if (extra[model]) return { ...empty, 名: extra[model] };
+
+  const canonical = SHORTHAND[model] || model;
+  const spec = MODEL_SPECS[canonical];
+  if (!spec) return empty;
+  if (!spec.档) {
+    return {
+      名: spec.实名, 档: null, 思耗: spec.思耗,
+      降级: 档 ? `${canonical} 的思考档不可调，「${档}」没生效` : null,
+    };
+  }
+  const 生效 = spec.档[档] ? 档 : spec.默认档;
+  const v = spec.档[生效];
+  return {
+    名: v.名, 档: 生效, 思耗: v.思耗 ?? spec.思耗,
+    降级: 档 && 生效 !== 档 ? `${canonical} 没有「${档}」档，按默认档「${生效}」跑` : null,
+  };
+}
+
+/** 只要实名的老口径（默认档） */
+export function resolveModelAlias(model) {
+  return resolveModelVariant(model).名;
+}
+
+/** 给设置页的模型目录：单价、档位、注释都从这一张表来，前端不再各存一份 */
+export function modelCatalog() {
+  return Object.entries(MODEL_SPECS).map(([id, s]) => ({
+    id, 入: s.价.in, 出: s.价.out, 注: s.注, 思耗: s.思耗,
+    档: s.档 ? Object.entries(s.档).map(([名, v]) => ({ 名, 思耗: v.思耗 ?? s.思耗, 注: v.注 ?? null })) : [],
+    默认档: s.默认档 ?? null,
+  }));
+}
+
+/**
+ * 跑一次 chatai。
+ * @param {object} opts  system / messages / model / 思考 / maxTokens / signal / onDelta
+ */
+export async function runChatai({
+  system = '', messages = [], model, 思考 = null, maxTokens = 2000, signal, onDelta,
+} = {}) {
+  const cfg = chataiConfig();
+  if (!cfg.ok) {
+    throw Object.assign(
+      new Error('chatai 通路没配置（CHATAI_BASE_URL / CHATAI_API_KEY / CHATAI_MODEL）'),
+      { code: 'CHATAI_UNCONFIGURED' },
+    );
+  }
+  const v = resolveModelVariant(model || cfg.model, 思考);
+  const out = await callOpenAICompat({
+    base: cfg.base, key: cfg.key, model: v.名,
+    system, messages, maxTokens, signal, onDelta,
+  });
+  return { ...out, model: v.名, 档: v.档, 降级: v.降级, costUsd: costOf(v.名, out.usage) };
+}