@xiaobuyu/nodesign 0.0.1

package/server/lib/publish-store.js

@@ -0,0 +1,115 @@
+/**
+ * server/lib/publish-store.js — 站点发布记录（2026-08-02 Cloudflare 一键上线）
+ *
+ * 一行 = 一个已发布站点（project+task 唯一）。cf_project 是 Cloudflare Pages
+ * 项目名，全局唯一 —— URL 就是 https://<cf_project>.pages.dev，重发布不换名
+ * 所以 URL 稳定。行删掉 = 已下线（Pages 项目同步删）。
+ *
+ * 配额口径按 user_id 数行：默认每个正式号 2 个（env NODESIGN_USER_PUBLISH_LIMIT），
+ * admin 不限；重发布同一个任务不占新额度。
+ */
+
+import crypto from 'node:crypto';
+import db from '../engine/runs/store.js';
+
+db.exec(`
+  CREATE TABLE IF NOT EXISTS published_sites (
+    id TEXT PRIMARY KEY,
+    project_id TEXT NOT NULL,
+    task TEXT NOT NULL,
+    user_id TEXT,
+    cf_project TEXT NOT NULL UNIQUE,
+    url TEXT NOT NULL,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    last_published_at TEXT,
+    UNIQUE(project_id, task)
+  );
+`);
+
+// custom domain（08-02 当天追加）：<slug>.share.xiaobuyu.trade 这一层。
+// 发布时挂上就记着，重发布沿用 —— URL 稳定性的真相源在这一列
+const pubCols = new Set(db.prepare('PRAGMA table_info(published_sites)').all().map(c => c.name));
+if (!pubCols.has('custom_domain')) {
+  db.exec('ALTER TABLE published_sites ADD COLUMN custom_domain TEXT');
+  console.log('[publish-store] published_sites.custom_domain column added');
+}
+
+function rowToSite(row) {
+  if (!row) return null;
+  return {
+    id: row.id,
+    projectId: row.project_id,
+    task: row.task,
+    userId: row.user_id,
+    cfProject: row.cf_project,
+    url: row.url,
+    customDomain: row.custom_domain || null,
+    createdAt: row.created_at,
+    lastPublishedAt: row.last_published_at,
+  };
+}
+
+export function getPublished(projectId, task) {
+  return rowToSite(db.prepare(
+    'SELECT * FROM published_sites WHERE project_id = ? AND task = ?',
+  ).get(projectId, task));
+}
+
+export function countPublishedByUser(userId) {
+  return db.prepare('SELECT COUNT(*) AS n FROM published_sites WHERE user_id = ?').get(userId).n;
+}
+
+export function listPublished() {
+  return db.prepare('SELECT * FROM published_sites ORDER BY last_published_at DESC').all().map(rowToSite);
+}
+
+/** 浏览工具撞上死掉的 share 域名时，用它查"本项目现在真正的线上地址" */
+export function listPublishedByProject(projectId) {
+  return db.prepare(
+    'SELECT * FROM published_sites WHERE project_id = ? ORDER BY last_published_at DESC',
+  ).all(projectId).map(rowToSite);
+}
+
+export function getByCustomDomain(host) {
+  return rowToSite(db.prepare('SELECT * FROM published_sites WHERE custom_domain = ?').get(host));
+}
+
+/** 发布成功后落记录（存在则刷时间戳 + 补 domain/url —— 重发布 URL 不变） */
+export function upsertPublished({ projectId, task, userId, cfProject, url, customDomain = null }) {
+  const existing = getPublished(projectId, task);
+  if (existing) {
+    db.prepare(
+      "UPDATE published_sites SET last_published_at = datetime('now'), url = ?, custom_domain = ? WHERE id = ?",
+    ).run(url, customDomain, existing.id);
+    return getPublished(projectId, task);
+  }
+  const id = `pub_${Date.now().toString(36)}_${crypto.randomBytes(3).toString('hex')}`;
+  db.prepare(`
+    INSERT INTO published_sites (id, project_id, task, user_id, cf_project, url, custom_domain, last_published_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now'))
+  `).run(id, projectId, task, userId, cfProject, url, customDomain);
+  return getPublished(projectId, task);
+}
+
+export function removePublished(projectId, task) {
+  return db.prepare('DELETE FROM published_sites WHERE project_id = ? AND task = ?')
+    .run(projectId, task).changes > 0;
+}
+
+/**
+ * Pages 项目名：nd-<任务名slug>-<hash6>。任务名多半是中文，slug 化后常剩空串，
+ * hash（pid+task 派生，稳定）才是唯一性的真来源；slug 只为了人在 CF 面板里认得出。
+ * Pages 命名规则：小写字母数字连字符，不能头尾连字符。
+ */
+export function slugify(name, max = 32) {
+  return String(name ?? '').toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '')
+    .slice(0, max);
+}
+
+export function cfProjectNameFor(projectId, task) {
+  // 24 而不是 32：Pages 项目名整体还要塞得下 `nd-` 前缀和 6 位 hash
+  const slug = slugify(task, 24);
+  const hash = crypto.createHash('sha1').update(`${projectId}/${task}`).digest('hex').slice(0, 6);
+  return `nd-${slug ? `${slug}-` : ''}${hash}`;
+}

package/server/lib/quick-summary.js

@@ -0,0 +1,52 @@
+/**
+ * quick-summary —— 画布铅笔精灵那行手写短句的整形（纯本地，零成本零延迟）
+ *
+ * ## 这里以前还挂着一发 haiku（2026-08-14 加，2026-08-19 拆）
+ *
+ * 原设计是两条腿：assistant 文本一到先用下面的 clampFirstClause 起个"底稿"
+ * 写上画布，同时起一发一次性 SDK 会话让 haiku 精修一行，到货覆盖底稿
+ * （前端管这叫"显影"）。拆掉不是因为它写得不好，是因为它**写死走订阅**：
+ *
+ *   - 模型名是常量 `claude-haiku-4-5`，**不跟随会话的主 agent 模型**。会话
+ *     跑在本地 Qwen / 中转 API 上时，这一发照旧打进 Claude 订阅额度 ——
+ *     用户明明选了别的模型，装饰性短句却还在替他烧订阅；而且是每条
+ *     assistant 消息一发、每轮收场再一发。
+ *   - 它是**独立 SDK 会话**（自己 spawn 一个 CLI 进程），不经 model-ingress，
+ *     所以既不受路由表管，也不进 run_model_usage 记账 —— 花掉的钱看不见。
+ *
+ * 一行装饰性旁白不值这个价。现在只剩底稿这条腿：纯字符串整形，不发任何请求，
+ * 精灵照常有话说，只是不再有"过几秒被精修覆盖"那一下。
+ *
+ * 同批退役的还有收场 recap（原 summarizeRecap → `run.recap` 事件）：它没有
+ * 本地底稿可垫，唯一的产出方式就是那发 haiku，所以随通道一起走。闲时精灵
+ * 改回写问候语 —— 那本来就是 recap 缺席时的既有分支（SpriteSketchLayer 的
+ * pickGreeting），不是新造的降级路。
+ */
+
+/** 一行整形：合并空白、去首尾引号、硬截。再啰嗦的原文也只放一行上画布。 */
+export function sanitizeLine(s, max = 48) {
+  const line = String(s || '')
+    .replace(/\s+/g, ' ')
+    .replace(/^["'「『""]+|["'」』""]+$/g, '')
+    .trim();
+  return line.length > max ? `${line.slice(0, max - 1)}…` : line;
+}
+
+/**
+ * 回复 → 精灵手写行：取第一小句。中文回复的第一小句通常本来就像一句旁白
+ * （"好的，我来把配色调暖一点"）。
+ *
+ * 开头的应答词单独剥掉（"好的，"/"明白，"/"没问题，"）：那半句是说给用户听的
+ * 客套，占着 26 字的额度还不带信息，剥了剩下的正好是"我在干什么"。
+ */
+const OPENER_RE = /^(好的?|行|明白了?|收到|没问题|你说得对|说得对|确实|是的|对|OK|ok|Sure|当然)[，,。！!、～~ ]+/;
+
+export function clampFirstClause(text, max = 26) {
+  const t = String(text || '').replace(/\s+/g, ' ').trim();
+  if (!t) return '';
+  const parts = t.split(/(?<=[。！？!?；;\n])/).filter(s => s.trim());
+  // 整句都是应答词（"没问题！"）就往后挪一句 —— 这行要的是"在干什么"那句
+  const hit = parts.find(s => s.replace(OPENER_RE, '').replace(/[。！？!?；;，,、～~ ]/g, ''));
+  const cut = hit || parts[0] || t;
+  return sanitizeLine(cut.replace(OPENER_RE, '').trim() || cut, max);
+}

package/server/lib/quota.js

@@ -0,0 +1,270 @@
+/**
+ * server/lib/quota.js — 每用户日用量限额（2026-07-30 内测；07-31 口径改成金额）
+ *
+ * # 为什么闸门数的是钱不是 token
+ *
+ * 原口径是 sum(input_tokens + output_tokens)，缓存不计。实测这个口径量错了主项：
+ * 07-31 当天全站 input+output 是 317k，cache_read 是 83M，差 260 倍。也就是说
+ * 配额条显示"才用了 4%"的人，实际推给账号的负载可能已经是一整天的大头。
+ *
+ * 更要命的是**缓存过期**。同一轮对话，缓存全命中和全过期的 token 计数几乎一样，
+ * 但过期后那批 token 从 $0.30/M 的 cache_read 变成 $3/M 的 input，还要再花
+ * $6.00/M 重写一次缓存，金额能差十倍。token 口径对这件事完全瞎。
+ *
+ * SDK 的 `ModelUsage.costUSD` 是原生字段，CLI 内部按分模型价目表算好给出来的。
+ * 逆推验证精确到小数点后 7 位：
+ *   9703×$3/M + 39032×$15/M + 6032461×$0.30/M + 414101×$6.00/M = $4.9089333
+ *   （SDK 报 4.908933300000001；haiku 行 532×$1/M + 17×$5/M 也精确命中）
+ * 缓存过期的代价自动体现在里面 —— 失效后 API 逐请求如实上报 input/cache_read
+ * 的实际拆分，costUSD 照单算，不需要我们建模 TTL 或命中率。
+ *
+ * # 数据源必须是 run_model_usage.cost_usd，不能是 runs.total_cost_usd
+ *
+ * runs 那列有历史污染：07-31 计量重做之前，写进去的是 SDK 的**会话累计**
+ * total_cost_usd（同一会话每轮都存一次当时的累计值），admin 的存量行因此虚高
+ * 三倍（$165 vs 实际 $53.6）。run_model_usage 是重做后新建的表，只由差分路径
+ * 写入，两个真人用户的行都跟公式精确对齐。
+ *
+ * # 口径覆盖范围
+ *
+ * 包含：该会话所有模型的 input / output / cache_read / cache_create，含子代理
+ * sidechain（Miel 从没手选过 haiku，她的 haiku 行是子代理自己用的，照样进账）。
+ * 不含：生图（codex 骑订阅）、web_search（Tavily/百度/Exa/智谱各自的账单）、
+ * 机器本身。所以这个数字的准确定义是「该用户对 Anthropic 账号造成的负载」，
+ * 恰好就是我们要配给的东西。
+ *
+ * 限额来源：users.daily_cost_limit_usd 优先，NULL 走 env NODESIGN_USER_DAILY_USD
+ * （默认 $5）。admin 不限。按 Asia/Shanghai 日界滚动现算，没有定时任务。
+ */
+
+import { readFileSync } from 'node:fs';
+import db, { getRun } from '../engine/runs/store.js';
+import { countRunningTurns, listRunningTurnRunIds } from '../engine/runs/active-runs.js';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const TZ_OFFSET_MS = 8 * 60 * 60 * 1000;   // Asia/Shanghai，内测口径写死
+
+/** 当天（+08:00 日界）的 UTC 起点，格式对齐 SQLite datetime('now') */
+export function dayStartUtcSql(now = Date.now()) {
+  const startLocal = Math.floor((now + TZ_OFFSET_MS) / DAY_MS) * DAY_MS - TZ_OFFSET_MS;
+  return new Date(startLocal).toISOString().slice(0, 19).replace('T', ' ');
+}
+
+/** 当天已花的美元（闸门真口径）。数据源见文件头：run_model_usage.cost_usd */
+export function usedCostToday(userId, now = Date.now()) {
+  const row = db.prepare(
+    `SELECT COALESCE(SUM(m.cost_usd), 0) AS used
+     FROM run_model_usage m JOIN runs r ON r.id = m.run_id
+     WHERE r.user_id = ? AND r.created_at >= ?`,
+  ).get(userId, dayStartUtcSql(now));
+  return row.used;
+}
+
+/** 全史花费（终身额度口径）。同一数据源同一公式，只是不设日界 */
+export function usedCostTotal(userId) {
+  const row = db.prepare(
+    `SELECT COALESCE(SUM(m.cost_usd), 0) AS used
+     FROM run_model_usage m JOIN runs r ON r.id = m.run_id
+     WHERE r.user_id = ?`,
+  ).get(userId);
+  return row.used;
+}
+
+/**
+ * 当天 input+output token 数。**不再是闸门口径**，只留给 admin 视图和
+ * 前端的参考行 —— 用户看得懂 token，看不懂 $0.87 意味着多少对话。
+ */
+export function usedTokensToday(userId, now = Date.now()) {
+  const row = db.prepare(
+    `SELECT COALESCE(SUM(COALESCE(input_tokens,0) + COALESCE(output_tokens,0)), 0) AS used
+     FROM runs WHERE user_id = ? AND created_at >= ?`,
+  ).get(userId, dayStartUtcSql(now));
+  return row.used;
+}
+
+/**
+ * 默认日额度（美元）。
+ *
+ * $15 的依据是 07-31 晚上第一个真用户的实际曲线：Miel 一小时零四分跑了 32 轮，
+ * 烧掉 $6.60，约 $6/小时（速率随会话变长而涨 —— 上下文越长每轮读的缓存越多）。
+ * 一晚上三小时的热情使用就是 $18 量级。
+ *
+ * 先按 $5 配过，实测下来那个数会在她玩到一半时把人挡在外面 —— 而她正是唯一
+ * 越过冷启动的人。日限额的职责是拦住失控，不是给正常使用配给；卡到最活跃的
+ * 那个人身上，说明数字定错了，不是人用多了。
+ *
+ * 参照：admin 重度开发日 $1.03/轮 × 52 轮 = $53.6（自己不限额）。
+ */
+export function defaultDailyLimit() {
+  const v = Number(process.env.NODESIGN_USER_DAILY_USD);
+  return Number.isFinite(v) && v > 0 ? v : 15;
+}
+
+/** 生图按张计价（08-21 深夜，basic 开放生图）：每张记 $0.20 进本回合账，跟模型花费同一本、同一把日限尺。env NODESIGN_IMAGE_PRICE_USD */
+export function imageChargeUsd(env = process.env) {
+  const v = Number(env.NODESIGN_IMAGE_PRICE_USD);
+  return Number.isFinite(v) && v >= 0 ? v : 0.2;
+}
+
+/** @returns {number|null} 美元；null = 不限（admin） */
+export function limitFor(user) {
+  if (!user || user.role === 'admin') return null;
+  return user.dailyCostLimitUsd ?? defaultDailyLimit();
+}
+
+/** 金额展示：$1.36。小额也留两位小数，别把 $0.06 显示成 $0 让人以为没扣 */
+export function fmtUsd(n) {
+  return `$${(Number(n) || 0).toFixed(2)}`;
+}
+
+/**
+ * 额度检查。两种口径（08-02 起）：
+ *   daily    — 默认。+08:00 日界滚动，隔天刷新（内测熟人号）。
+ *   lifetime — users.lifetime_cost_limit_usd 非空即生效：全史花费封顶，
+ *              永不刷新。给简历上的通用邀请码用（注册时从
+ *              invites.grant_lifetime_usd 复制到用户身上，与码解耦）。
+ *              终身口径**取代**日限不叠加 —— HR 试用要的是当晚完整体验，
+ *              细水长流反而是坏体验；单号封顶 $15 本身就是敞口上限。
+ *
+ * `used` 是与 limit 同口径的比较数（终身号 = 全史）；`usedToday` 恒为当日数，
+ * 展示层要"今天花了多少"时不用管口径。
+ *
+ * @returns {{ ok, kind: 'unlimited'|'daily'|'lifetime', used, limit, usedToday }} 单位美元
+ */
+export function checkQuota(user, now = Date.now()) {
+  const usedToday = usedCostToday(user?.id, now);
+  if (!user || user.role === 'admin') {
+    return { ok: true, kind: 'unlimited', used: usedToday, limit: null, usedToday };
+  }
+  if (user.lifetimeCostLimitUsd != null) {
+    const used = usedCostTotal(user.id);
+    return { ok: used < user.lifetimeCostLimitUsd, kind: 'lifetime', used, limit: user.lifetimeCostLimitUsd, usedToday };
+  }
+  const limit = user.dailyCostLimitUsd ?? defaultDailyLimit();
+  return { ok: usedToday < limit, kind: 'daily', used: usedToday, limit, usedToday };
+}
+
+/**
+ * 免费模型的闸（08-21）：金额对 $0 的模型没有意义，免费档按**当日轮次**封顶 + 并发闸
+ * （checkConcurrency 不变）。数据源 runs.created_at（同 usedCostToday 的日界）。
+ * 口径：数的是该账号今天**所有**轮次，不按模型分 —— 公开注册号只能跑免费模型，
+ * 邀请码号跑免费模型时也照这个数（订阅额度是另一把尺，互不抵扣）。
+ * 上限 .env NODESIGN_FREE_DAILY_TURNS，默认 300；admin 不限。
+ */
+export function freeDailyTurnLimit() {
+  const v = Number(process.env.NODESIGN_FREE_DAILY_TURNS);
+  return Number.isFinite(v) && v > 0 ? v : 300;
+}
+export function usedTurnsToday(userId, now = Date.now()) {
+  const row = db.prepare('SELECT COUNT(*) AS n FROM runs WHERE user_id = ? AND created_at >= ?').get(userId, dayStartUtcSql(now));
+  return row.n;
+}
+export function checkFreeQuota(user, now = Date.now()) {
+  const used = usedTurnsToday(user?.id, now);
+  if (!user || user.role === 'admin') return { ok: true, kind: 'unlimited', used, limit: null };
+  const limit = freeDailyTurnLimit();
+  return { ok: used < limit, kind: 'free-turns', used, limit };
+}
+
+// ── 分模型明细（2026-07-31）──
+//
+// **只用于展示，不再是独立闸门。** 改成金额口径之后，分模型限额失去了理由：
+// 原来配 sonnet 300k / opus 100k 是为了让 opus 更难挥霍，而金额天然做到这件事
+// —— 同样一轮对话 opus 就是烧掉五倍预算，不需要第二个数字去表达同一个意图。
+// 代价是没了"这个模型满了可以换那个继续"的退路，撞线就是撞线；换来的是用户
+// 只需要理解一个数字，以及不会出现"opus 额度还剩很多但钱其实早花光了"的错位。
+//
+// 家族归并按模型串关键字：表里存的是 SDK 上报的原始模型名（'claude-sonnet-5'），
+// 用户视角只有 Sonnet / Opus 两个选项，版本号是实现细节。
+// 注意：如果哪天重开 kimi gateway，SDK 上报的是 spoof 后的 opus 名，
+// 这里会把 kimi 记成 opus —— 见 model-context.js APP_TO_SDK_MODEL。
+
+export function modelFamily(model) {
+  const s = String(model || '').toLowerCase();
+  if (s.includes('sonnet')) return 'sonnet';
+  if (s.includes('opus')) return 'opus';
+  if (s.includes('haiku')) return 'haiku';
+  return 'other';
+}
+
+/** 家族显示名（429 文案 / 前端徽标共用） */
+export function familyLabel(family) {
+  return { sonnet: 'Sonnet', opus: 'Opus', haiku: 'Haiku' }[family] || family;
+}
+
+/**
+ * 当天该用户按家族聚合的花费与 token，如
+ * `{ sonnet: { costUsd: 1.36, tokens: 18831 }, haiku: { costUsd: 0, tokens: 549 } }`
+ * 只有真出现过的家族才有键（没用过 opus 就没有 opus 键）。
+ */
+export function usedTodayByFamily(userId, now = Date.now()) {
+  const rows = db.prepare(
+    `SELECT m.model AS model,
+            SUM(m.cost_usd) AS cost,
+            SUM(m.input_tokens + m.output_tokens) AS tokens
+     FROM run_model_usage m JOIN runs r ON r.id = m.run_id
+     WHERE r.user_id = ? AND r.created_at >= ?
+     GROUP BY m.model`,
+  ).all(userId, dayStartUtcSql(now));
+  const byFamily = {};
+  for (const row of rows) {
+    const f = modelFamily(row.model);
+    const acc = byFamily[f] || (byFamily[f] = { costUsd: 0, tokens: 0 });
+    acc.costUsd += row.cost || 0;
+    acc.tokens += row.tokens || 0;
+  }
+  return byFamily;
+}
+
+// ── 并发闸门 ──
+// 语义是"拒绝返 429"而不是"排队 await"：turn.js 是 202 fire-and-forget，
+// 闸门必须在 202 之前同步判。同 session 追加消息走既有排队语义不经这里。
+//
+// 08-21 经营态转向后分两档：
+// - 订阅行（花站主的订阅）：全局固定数 NODESIGN_MAX_CONCURRENT_RUNS（默认 3）
+// - 免费行（Ox 这类零价模型）：不受全局固定数限制。它的约束只剩机器本身 ——
+//   每个 claude CLI 进程 350MB~1GB、机器 1 vCPU/8G 无 swap，所以改成**内存闸**：
+//   MemAvailable 低于 NODESIGN_MIN_FREE_MEM_MB（默认 700）就拒，外加一个防失控的
+//   上限 NODESIGN_FREE_MAX_CONCURRENT_RUNS（默认 12）。内存闸对两档都生效（订阅行
+//   的固定数 3 本来就是按内存拍的，内存先见底时固定数也救不了）
+// - 每用户同时 1 个（admin 免）两档都一样：这是公平性不是资源
+
+export function memAvailableMb() {
+  try {
+    const m = /MemAvailable:\s+(\d+) kB/.exec(readFileSync('/proc/meminfo', 'utf8'));
+    return m ? Math.floor(Number(m[1]) / 1024) : null;
+  } catch { return null; }   // 非 Linux / 读不到 → 不以内存拒
+}
+
+/** 纯决策：输入全是数，方便测 */
+export function decideConcurrency({ running, mine, isAdmin, free, memMb, env = process.env }) {
+  const minMem = Number(env.NODESIGN_MIN_FREE_MEM_MB) || 700;
+  if (memMb != null && memMb < minMem) {
+    return { ok: false, code: 'BUSY', message: `机器内存快满了（${running} 个任务在跑），稍等一会儿再发` };
+  }
+  const globalMax = free
+    ? (Number(env.NODESIGN_FREE_MAX_CONCURRENT_RUNS) || 12)
+    : (Number(env.NODESIGN_MAX_CONCURRENT_RUNS) || 3);
+  if (running >= globalMax) {
+    return { ok: false, code: 'BUSY', message: `现在有点挤（${running} 个任务在跑），稍等一会儿再发` };
+  }
+  if (!isAdmin) {
+    const perUser = Number(env.NODESIGN_USER_CONCURRENT_RUNS) || 1;
+    if (mine >= perUser) {
+      return { ok: false, code: 'BUSY', message: '你有任务正在跑，等它完成再开下一个（同一对话里追加消息不受限）' };
+    }
+  }
+  return { ok: true };
+}
+
+export function checkConcurrency(user, { free = false } = {}) {
+  // running turn → user 归属：runId 查 runs.user_id（不给 session 注册表加
+  // userId 字段 —— 正在跑的 turn 就几个，查表成本可忽略）
+  let mine = 0;
+  if (user?.role !== 'admin') {
+    for (const rid of listRunningTurnRunIds()) {
+      if (getRun(rid)?.userId === user?.id) mine += 1;
+    }
+  }
+  return decideConcurrency({ running: countRunningTurns(), mine, isAdmin: user?.role === 'admin', free, memMb: memAvailableMb() });
+}

package/server/lib/rate-window.js

@@ -0,0 +1,29 @@
+/**
+ * rate-window.js —— 内存滑动窗口限流。
+ *
+ * 给演出端点用的频率闸门：金额日限（quota.js）拦不住单日尖峰——iframe 同源
+ * 带 cookie，agent 写的页面里一个 setInterval 就是烧钱机，必须有按分钟的闸。
+ * 内存实现就够：限流是保护性关卡不是记账，重启清零无所谓。
+ */
+
+export function makeRateWindow({ limit, windowMs }) {
+  const hits = new Map();   // key → 命中时间戳数组（只留窗口内的）
+  return {
+    /** 窗口内已命中几次（只看不扣；注册这类"先判再做、做成了才扣"的场景用） */
+    count(key, now = Date.now()) {
+      return (hits.get(key) || []).filter(t => now - t < windowMs).length;
+    },
+    /** @returns {{ok: true} | {ok: false, retryAfterMs: number}} */
+    take(key, now = Date.now()) {
+      const arr = (hits.get(key) || []).filter(t => now - t < windowMs);
+      if (arr.length >= limit) {
+        hits.set(key, arr);
+        // limit=0（闸门关死）时窗口里没有命中记录，arr[0] 是 undefined → NaN；按整窗算
+        return { ok: false, retryAfterMs: arr.length ? windowMs - (now - arr[0]) : windowMs };
+      }
+      arr.push(now);
+      hits.set(key, arr);
+      return { ok: true };
+    },
+  };
+}

package/server/lib/reference-assets.js

@@ -0,0 +1,92 @@
+/**
+ * server/lib/reference-assets.js — 参考素材清单（2026-08-18）
+ *
+ * `assets/references/**` 里的东西：web-search 下载的参考图、`browser_capture` 从
+ * 参照站带回来的截图与调色板/字体/结构 json。
+ *
+ * ## 它们此前完全看不见，原因不是"kinds 不认图片"
+ *
+ * 图片有自己的 file-kind（`kinds/file-kinds.js`，IMAGE_EXTS 六种齐全）。真正的断点
+ * 是**扫描根**：`api/assets.js` 的 `/assets` 端点只 readdir 顶层文件，而产物清单那遍
+ * `scanDir` 用的是默认 `depth = 0`（`depth <= 0` 就不进子目录）——
+ * `assets/generated` 和 `assets/notes` 能上墙只因为它们被**单独列了一行**，
+ * `assets/references/` 没被列。所以修法是加一个扫描口，不是改形态注册表。
+ *
+ * ## 走抽屉不走画布（用户 2026-08-18 拍板）
+ *
+ * 每逛一站甩十几张卡到画布上是噪音，而 web-search 下载的参考图还会成倍冒出来
+ * （它按 `count*2` 下载但只上报 `count` 张，磁盘上本来就有 agent 不知道的孤儿）。
+ * 收进「参考素材」抽屉杂波小得多。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+/**
+ * 最多下探几层：`references/`(0) → `web/`(1) → `<站名>/`(2) → 文件。
+ *
+ * ⭐ 2026-08-18 下午 +1：`browser_capture` 改成**一站一文件夹**（按站点产物那条
+ * 范式：目录 = 单位）。深度不够的话整棵采集树在清单里凭空消失 —— 而"扫描根/深度
+ * 不够"正是当初参考素材完全看不见的真因（见文件头），同一个坑别踩第二次。
+ */
+const MAX_DEPTH = 3;
+
+/** 这份素材属于哪个参照站（`assets/references/web/<站名>/…` 的那一段） */
+function siteOf(rel) {
+  const m = /^assets\/references\/web\/([^/]+)\//.exec(rel);
+  return m ? m[1] : null;
+}
+
+/**
+ * @param {string} assetsDir  `<工作区>/assets` 的绝对路径
+ * @returns {Promise<Array<{rel,name,size,mtime,source?,lookingFor?,capturedAt?}>>}
+ *   按 mtime 倒序。读不到就返回空数组 —— 素材列不出来不该让整份 /assets 响应失败。
+ */
+export async function listReferences(assetsDir) {
+  const out = [];
+
+  const walk = async (dir, relPrefix, depth) => {
+    let ents;
+    try { ents = await fs.readdir(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (e.name === '.meta') continue;                     // sidecar 目录本身不列
+      if (e.isDirectory()) {
+        if (depth > 0) await walk(path.join(dir, e.name), `${relPrefix}/${e.name}`, depth - 1);
+        continue;
+      }
+      if (!e.isFile() || e.name.startsWith('.')) continue;
+      let st;
+      try { st = await fs.stat(path.join(dir, e.name)); } catch { continue; }
+
+      // 出处：照 generate-image 的 `.meta/<主干>.json` 约定读（不另发明一套）。
+      // 没有出处很正常 —— web-search 下载的那些本来就没写 sidecar。
+      let meta = null;
+      try {
+        const stem = e.name.replace(/\.[^.]+$/, '');
+        meta = JSON.parse(await fs.readFile(path.join(dir, '.meta', `${stem}.json`), 'utf8'));
+      } catch { /* 无出处 */ }
+
+      const rel = `${relPrefix}/${e.name}`;
+      out.push({
+        rel,
+        name: e.name,
+        site: siteOf(rel),
+        // 类别写在文件名里（`.screenshot.webp` / `.palette.json` / `.css` …），
+        // sidecar 里也记着一份 —— 文件名优先，它是用户和 agent 直接看到的那个
+        category: /\.(screenshot)\.\w+$/.test(e.name) ? 'screenshot'
+          : (/\.(palette|fonts|skeleton)\.json$/.exec(e.name)?.[1] || (e.name.endsWith('.css') ? 'css' : null)),
+        size: st.size,
+        mtime: st.mtime.toISOString(),
+        ...(meta ? {
+          source: meta.sourceUrl || null,
+          lookingFor: meta.lookingFor || null,
+          capturedAt: meta.capturedAt || null,
+        } : {}),
+      });
+    }
+  };
+
+  await walk(path.join(assetsDir, 'references'), 'assets/references', MAX_DEPTH);
+  out.sort((a, b) => (a.mtime < b.mtime ? 1 : -1));
+  return out;
+}