@leterhong/multichat 1.6.0

package/backend/lib/ssrf.ts

@@ -0,0 +1,120 @@
+// SSRF 防护：拦截指向私有/内网地址的导入与远程资产请求。
+// 注意：本地模型发现（/api/fetch-local-models）故意不在此拦截，因为它本就需要访问用户自己的 localhost 服务。
+const { promises: dns } = require('dns');
+const net = require('net');
+
+function ipv4ToInt(ip: string): number {
+  const parts = ip.split('.').map(Number);
+  return (((parts[0] << 24) >>> 0) + (parts[1] << 16) + (parts[2] << 8) + parts[3]) >>> 0;
+}
+
+function inCidr(ipInt: number, base: number, bits: number): boolean {
+  if (bits === 0) return ipInt === (base >>> 0);
+  const mask = (0xffffffff << (32 - bits)) >>> 0;
+  return (ipInt & mask) === (base & mask);
+}
+
+const PRIVATE_V4: Array<[number, number]> = [
+  [0, 8], // 0.0.0.0/8
+  [ipv4ToInt('10.0.0.0'), 8],
+  [ipv4ToInt('100.64.0.0'), 10], // CGNAT
+  [ipv4ToInt('127.0.0.0'), 8], // loopback
+  [ipv4ToInt('169.254.0.0'), 16], // link-local
+  [ipv4ToInt('172.16.0.0'), 12],
+  [ipv4ToInt('192.0.0.0'), 24],
+  [ipv4ToInt('192.168.0.0'), 16],
+  [ipv4ToInt('198.18.0.0'), 15],
+];
+
+function isPrivateV4(ip: string): boolean {
+  const n = ipv4ToInt(ip);
+  if (n === 0) return true;
+  return PRIVATE_V4.some(([base, bits]) => inCidr(n, base, bits));
+}
+
+function isPrivateV6(ip: string): boolean {
+  const a = ip.toLowerCase();
+  if (a === '::1' || a === '::') return true;
+  if (a.startsWith('fe80:')) return true; // link-local
+  if (a.startsWith('fc') || a.startsWith('fd')) return true; // unique local fc00::/7
+  const mapped = mappedV4(a);
+  if (mapped) return isPrivateV4(mapped);
+  return false;
+}
+
+function mappedV4(ip: string): string | null {
+  const dotted = ip.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+  if (dotted) return dotted[1];
+  const hex = ip.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i);
+  if (!hex) return null;
+  const high = Number.parseInt(hex[1], 16), low = Number.parseInt(hex[2], 16);
+  return `${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`;
+}
+
+function isMetadataAddress(ip: string): boolean {
+  const value = ip.toLowerCase();
+  const mapped = mappedV4(value);
+  const v4 = mapped || (net.isIP(value) === 4 ? value : null);
+  return Boolean(
+    v4 && (v4.startsWith('0.') || v4.startsWith('169.254.') || v4 === '100.100.100.200')
+  ) || value === '::' || value === 'fd00:ec2::254' || value.startsWith('fe80:');
+}
+
+async function assertSafeUrl(input: string, { allowPrivate = false }: { allowPrivate?: boolean } = {}): Promise<URL> {
+  let url: URL;
+  try {
+    url = new URL(input);
+  } catch {
+    throw new Error('非法 URL');
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error('仅支持 http/https 链接');
+  }
+  // Node keeps square brackets around IPv6 URL hostnames; net.isIP expects the
+  // bare address. Normalize before applying private/metadata checks.
+  const host = url.hostname.replace(/^\[|\]$/g, '');
+  if (net.isIP(host) === 4) {
+    if (isMetadataAddress(host)) throw new Error('SSRF: 目标为保留、元数据或链路本地地址 ' + host);
+    if (!allowPrivate && isPrivateV4(host)) throw new Error('SSRF: 目标为内网地址 ' + host);
+  } else if (net.isIP(host) === 6) {
+    if (isMetadataAddress(host)) throw new Error('SSRF: 目标为保留、元数据或链路本地地址 ' + host);
+    if (!allowPrivate && isPrivateV6(host)) throw new Error('SSRF: 目标为内网地址 ' + host);
+  } else {
+    const addrs = await dns.lookup(host, { all: true });
+    for (const { address } of addrs) {
+      const v = net.isIP(address);
+      if (isMetadataAddress(address)) throw new Error('SSRF: 解析到保留、元数据或链路本地地址 ' + address);
+      if (v === 4 && !allowPrivate && isPrivateV4(address)) throw new Error('SSRF: 解析到内网地址 ' + address);
+      if (v === 6 && !allowPrivate && isPrivateV6(address)) throw new Error('SSRF: 解析到内网地址 ' + address);
+    }
+  }
+  return url;
+}
+
+// 带 SSRF 校验的 fetch：手动处理重定向，每次跳转都重新校验目标地址。
+async function safeFetch(input: string, options: RequestInit = {}, allowPrivate = false, depth = 0): Promise<Response> {
+  const url = await assertSafeUrl(input, { allowPrivate });
+  const resp = await fetch(url, { ...options, redirect: 'manual' });
+  if ([301, 302, 307, 308].includes(resp.status) && depth < 3) {
+    const loc = resp.headers.get('location');
+    if (!loc) throw new Error('重定向缺少 Location');
+    const nextUrl = new URL(loc, url);
+    let nextOptions = options;
+    if (nextUrl.origin !== url.origin && options.headers) {
+      // Never forward credentials, cookies, MCP sessions or arbitrary custom
+      // headers to another origin. Only protocol/content negotiation headers
+      // are safe to retain across the redirect boundary.
+      const current = new Headers(options.headers);
+      const forwarded = new Headers();
+      for (const name of ['accept', 'accept-language', 'content-type', 'mcp-protocol-version']) {
+        const value = current.get(name);
+        if (value !== null) forwarded.set(name, value);
+      }
+      nextOptions = { ...options, headers: forwarded };
+    }
+    return safeFetch(nextUrl.toString(), nextOptions, allowPrivate, depth + 1);
+  }
+  return resp;
+}
+
+module.exports = { isPrivateV4, isPrivateV6, assertSafeUrl, safeFetch };

package/backend/lib/store.ts

@@ -0,0 +1,79 @@
+const fs = require('fs');
+const path = require('path');
+import type { JsonStore } from '../types';
+
+function createJsonStore(rootDir: string): JsonStore {
+  // per-file 串行化队列：防止多个并发请求对同一 JSON 做 read-modify-write 时互相覆盖
+  const chains = new Map<string, Promise<unknown>>();
+
+  function resolve(name: string) {
+    if (typeof name !== 'string' || !name || path.basename(name) !== name) {
+      throw new Error('invalid data file name');
+    }
+    return path.join(rootDir, name);
+  }
+
+  function read<T>(name: string, fallback: T): T {
+    const file = resolve(name);
+    if (!fs.existsSync(file)) return fallback;
+    try {
+      return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {
+      // A partially written/corrupted JSON file should not silently erase the
+      // user's view of their data. Every successful write keeps one local
+      // recovery copy, so prefer that before falling back to an empty value.
+      const backup = `${file}.bak`;
+      try {
+        if (fs.existsSync(backup)) return JSON.parse(fs.readFileSync(backup, 'utf8'));
+      } catch {}
+      return fallback;
+    }
+  }
+
+  function write(name: string, value: unknown) {
+    const file = resolve(name);
+    fs.mkdirSync(rootDir, { recursive: true });
+    const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temp, JSON.stringify(value, null, 2), 'utf8');
+    // Keep one known-good recovery point. On Windows rename-over-existing can
+    // fail with EPERM, so use a guarded replacement fallback while retaining
+    // the backup. The temporary file is always cleaned up.
+    try {
+      if (fs.existsSync(file)) fs.copyFileSync(file, `${file}.bak`);
+      try {
+        fs.renameSync(temp, file);
+      } catch (error) {
+        if (!['EEXIST', 'EPERM'].includes(error?.code)) throw error;
+        fs.rmSync(file, { force: true });
+        fs.renameSync(temp, file);
+      }
+    } finally {
+      if (fs.existsSync(temp)) fs.rmSync(temp, { force: true });
+    }
+  }
+
+  function remove(name: string) {
+    const file = resolve(name);
+    if (fs.existsSync(file)) fs.unlinkSync(file);
+  }
+
+  // 串行化 read-modify-write：fn(currentValue) => newValue（或 undefined 表示不写回）。
+  // 同一 name 的多次 mutate 会严格按调用顺序排队执行，杜绝并发覆盖。
+  function mutate<T>(name: string, fn: (current: T) => T | undefined | Promise<T | undefined>, fallback: T) {
+    const prev = chains.get(name) || Promise.resolve();
+    const run = prev
+      .then(() => fn(read(name, fallback)))
+      .then((result) => {
+        if (result === undefined) return result;
+        write(name, result);
+        return result;
+      });
+    // 存入"已处理 rejection"的链，避免后续排队因前序失败而中断，也避免 unhandled rejection
+    chains.set(name, run.then(() => {}, () => {}));
+    return run;
+  }
+
+  return { kind: 'json', read, write, remove, resolve, mutate };
+}
+
+module.exports = { createJsonStore };

package/backend/lib/usage.ts

@@ -0,0 +1,212 @@
+const crypto = require('crypto');
+import type { JsonRecord, JsonStore } from '../types';
+
+const USAGE_FILE = 'usage.json';
+const SCHEMA_VERSION = 1;
+const MAX_RECORDS = 20_000;
+const RETENTION_MS = 400 * 24 * 60 * 60 * 1000;
+
+function finite(value: unknown): number {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? Math.round(number) : 0;
+}
+
+function tokenFields(raw: JsonRecord = {}) {
+  const input = finite(raw.prompt_tokens ?? raw.input_tokens);
+  const output = finite(raw.completion_tokens ?? raw.output_tokens);
+  const total = finite(raw.total_tokens) || input + output;
+  const cached = finite(raw.cached_tokens ?? raw.prompt_tokens_details?.cached_tokens ?? raw.input_tokens_details?.cache_read_tokens);
+  const reasoning = finite(raw.reasoning_tokens ?? raw.completion_tokens_details?.reasoning_tokens);
+  return { input, output, total, cached, reasoning };
+}
+
+function estimateText(value: unknown): number {
+  if (value == null) return 0;
+  const text = typeof value === 'string' ? value : JSON.stringify(value);
+  // A deterministic local estimate for providers that do not report usage.
+  // It is intentionally labelled as estimated in every API/UI surface.
+  return Math.max(0, Math.ceil(text.length / 4));
+}
+
+function mergeUsage(base: JsonRecord = {}, next: JsonRecord = {}) {
+  const left = tokenFields(base);
+  const right = tokenFields(next);
+  return {
+    prompt_tokens: Math.max(left.input, right.input),
+    completion_tokens: Math.max(left.output, right.output),
+    total_tokens: Math.max(left.total, right.total, Math.max(left.input, right.input) + Math.max(left.output, right.output)),
+    cached_tokens: Math.max(left.cached, right.cached),
+    reasoning_tokens: Math.max(left.reasoning, right.reasoning),
+  };
+}
+
+function normalizeUsage(raw: JsonRecord | null | undefined, messages: JsonRecord[] = [], output = '') {
+  const exact = tokenFields(raw || {});
+  if (exact.total > 0) return { ...exact, source: 'reported' };
+  const input = messages.reduce((sum, message) => sum + estimateText(message.content) + 4, 0);
+  const outputTokens = estimateText(output);
+  return { input, output: outputTokens, total: input + outputTokens, cached: 0, reasoning: 0, source: 'estimated' };
+}
+
+interface UsageLedger { version: number; records: JsonRecord[]; }
+
+function ledger(store: JsonStore): UsageLedger {
+  const value = store.read<JsonRecord | JsonRecord[]>(USAGE_FILE, { version: SCHEMA_VERSION, records: [] });
+  if (Array.isArray(value)) return { version: SCHEMA_VERSION, records: value };
+  return { version: SCHEMA_VERSION, records: Array.isArray(value.records) ? value.records : [] };
+}
+
+async function recordUsage(store: JsonStore, input: JsonRecord) {
+  const now = new Date().toISOString();
+  const normalized = input.usage || normalizeUsage(input.rawUsage, input.messages, input.output);
+  const record = {
+    id: `use_${Date.now().toString(36)}_${crypto.randomBytes(3).toString('hex')}`,
+    timestamp: input.timestamp || now,
+    finishedAt: input.finishedAt || now,
+    providerId: String(input.providerId || 'unknown'),
+    providerName: String(input.providerName || input.providerId || 'Unknown'),
+    model: String(input.model || 'unknown'),
+    mode: input.mode === 'agent' ? 'agent' : 'chat',
+    status: input.status === 'error' || input.status === 'cancelled' ? input.status : 'success',
+    errorCode: input.errorCode ? String(input.errorCode).slice(0, 80) : null,
+    workspaceId: input.workspaceId || null,
+    projectId: input.projectId || null,
+    conversationId: input.conversationId || null,
+    runId: input.runId || null,
+    interactionId: input.interactionId || input.runId || input.conversationId || null,
+    step: finite(input.step),
+    durationMs: finite(input.durationMs),
+    inputTokens: finite(normalized.input),
+    outputTokens: finite(normalized.output),
+    totalTokens: finite(normalized.total) || finite(normalized.input) + finite(normalized.output),
+    cachedTokens: finite(normalized.cached),
+    reasoningTokens: finite(normalized.reasoning),
+    source: normalized.source === 'reported' ? 'reported' : 'estimated',
+  };
+  await store.mutate<UsageLedger | JsonRecord[]>(USAGE_FILE, current => {
+    const state = Array.isArray(current) ? { version: SCHEMA_VERSION, records: current } : current;
+    const cutoff = Date.now() - RETENTION_MS;
+    state.version = SCHEMA_VERSION;
+    state.records = [record, ...(state.records || [])]
+      .filter(item => Date.parse(item.timestamp || '') >= cutoff)
+      .slice(0, MAX_RECORDS);
+    return state;
+  }, { version: SCHEMA_VERSION, records: [] });
+  return record;
+}
+
+function localParts(timestamp: string, offsetMinutes: number) {
+  const parsed = Date.parse(timestamp);
+  if (!Number.isFinite(parsed)) return { date: '0000-00-00', hour: 0 };
+  const local = new Date(parsed - offsetMinutes * 60_000);
+  return {
+    date: local.toISOString().slice(0, 10),
+    hour: local.getUTCHours(),
+  };
+}
+
+function dateRange(days: number, offsetMinutes: number) {
+  const end = new Date(Date.now() - offsetMinutes * 60_000);
+  end.setUTCHours(0, 0, 0, 0);
+  const out = [];
+  for (let index = days - 1; index >= 0; index -= 1) {
+    out.push(new Date(end.getTime() - index * 86_400_000).toISOString().slice(0, 10));
+  }
+  return out;
+}
+
+function summarizeRows(rows: JsonRecord[], days: number, offsetMinutes: number) {
+  const dailyMap = new Map<string, JsonRecord>();
+  const modelMap = new Map<string, JsonRecord>();
+  const providerMap = new Map<string, JsonRecord>();
+  const hours = Array.from({ length: 24 }, () => 0);
+  const interactionIds = new Set<string>();
+  let inputTokens = 0, outputTokens = 0, totalTokens = 0, cachedTokens = 0, reasoningTokens = 0;
+  let reportedTokens = 0, estimatedTokens = 0, errors = 0, durationMs = 0, durationCount = 0;
+  for (const row of rows) {
+    const { date, hour } = localParts(row.timestamp, offsetMinutes);
+    const daily = dailyMap.get(date) || { date, inputTokens: 0, outputTokens: 0, totalTokens: 0, requests: 0, errors: 0, models: {} };
+    daily.inputTokens += finite(row.inputTokens);
+    daily.outputTokens += finite(row.outputTokens);
+    daily.totalTokens += finite(row.totalTokens);
+    daily.requests += 1;
+    if (row.status !== 'success') daily.errors += 1;
+    daily.models[row.model] = finite(daily.models[row.model]) + finite(row.totalTokens);
+    dailyMap.set(date, daily);
+
+    const modelKey = String(row.model || 'unknown');
+    const model = modelMap.get(modelKey) || { name: modelKey, totalTokens: 0, inputTokens: 0, outputTokens: 0, requests: 0 };
+    model.totalTokens += finite(row.totalTokens); model.inputTokens += finite(row.inputTokens); model.outputTokens += finite(row.outputTokens); model.requests += 1;
+    modelMap.set(modelKey, model);
+
+    const providerKey = String(row.providerId || 'unknown');
+    const provider = providerMap.get(providerKey) || { id: providerKey, name: row.providerName || providerKey, totalTokens: 0, requests: 0, errors: 0 };
+    provider.totalTokens += finite(row.totalTokens); provider.requests += 1; if (row.status !== 'success') provider.errors += 1;
+    providerMap.set(providerKey, provider);
+
+    inputTokens += finite(row.inputTokens); outputTokens += finite(row.outputTokens); totalTokens += finite(row.totalTokens);
+    cachedTokens += finite(row.cachedTokens); reasoningTokens += finite(row.reasoningTokens);
+    if (row.source === 'reported') reportedTokens += finite(row.totalTokens); else estimatedTokens += finite(row.totalTokens);
+    if (row.status !== 'success') errors += 1;
+    if (row.durationMs) { durationMs += finite(row.durationMs); durationCount += 1; }
+    hours[hour] += finite(row.totalTokens) || 1;
+    interactionIds.add(String(row.interactionId || row.runId || row.conversationId || row.id));
+  }
+
+  const dailyDates = dateRange(days, offsetMinutes);
+  const daily = dailyDates.map(date => dailyMap.get(date) || { date, inputTokens: 0, outputTokens: 0, totalTokens: 0, requests: 0, errors: 0, models: {} });
+  const models = [...modelMap.values()].filter(item => item.totalTokens > 0).sort((a, b) => b.totalTokens - a.totalTokens).map(item => ({ ...item, share: totalTokens ? item.totalTokens / totalTokens : 0 }));
+  const providers = [...providerMap.values()].sort((a, b) => b.totalTokens - a.totalTokens).map(item => ({ ...item, share: totalTokens ? item.totalTokens / totalTokens : 0 }));
+  const activeDates = new Set(rows.map(row => localParts(row.timestamp, offsetMinutes).date));
+  const today = dateRange(1, offsetMinutes)[0];
+  let currentStreak = 0;
+  for (let cursor = new Date(`${today}T00:00:00.000Z`); activeDates.has(cursor.toISOString().slice(0, 10)); cursor = new Date(cursor.getTime() - 86_400_000)) currentStreak += 1;
+  let longestStreak = 0, running = 0, previous = '';
+  for (const date of [...activeDates].sort()) {
+    const adjacent = previous && Date.parse(`${date}T00:00:00Z`) - Date.parse(`${previous}T00:00:00Z`) === 86_400_000;
+    running = adjacent ? running + 1 : 1; longestStreak = Math.max(longestStreak, running); previous = date;
+  }
+  const peakHour = hours.reduce((best, value, index) => value > hours[best] ? index : best, 0);
+  return {
+    totals: {
+      inputTokens, outputTokens, totalTokens, cachedTokens, reasoningTokens,
+      requests: rows.length, messages: interactionIds.size, sessions: interactionIds.size,
+      activeDays: activeDates.size, errors, successRate: rows.length ? (rows.length - errors) / rows.length : 1,
+      averagePerActiveDay: activeDates.size ? Math.round(totalTokens / activeDates.size) : 0,
+      averageDurationMs: durationCount ? Math.round(durationMs / durationCount) : 0,
+      reportedTokens, estimatedTokens, reportedShare: totalTokens ? reportedTokens / totalTokens : 0,
+      currentStreak, longestStreak, peakHour,
+    },
+    daily, models, providers,
+  };
+}
+
+function usageSummary(store: JsonStore, options: JsonRecord = {}) {
+  const all = ledger(store).records;
+  const offsetMinutes = Math.max(-840, Math.min(840, Number(options.offsetMinutes) || 0));
+  const requestedRange = String(options.range || '30');
+  const days = requestedRange === 'all'
+    ? Math.max(1, Math.min(400, all.length ? Math.ceil((Date.now() - Date.parse(all[all.length - 1].timestamp)) / 86_400_000) + 1 : 30))
+    : Math.max(1, Math.min(365, Number.parseInt(requestedRange, 10) || 30));
+  const startDate = dateRange(days, offsetMinutes)[0];
+  const rows = all.filter(row => localParts(row.timestamp, offsetMinutes).date >= startDate)
+    .filter(row => !options.projectId || row.projectId === options.projectId);
+  const summary = summarizeRows(rows, days, offsetMinutes);
+  const heatmapStart = dateRange(182, offsetMinutes)[0];
+  const heatmapRows = all
+    .filter(row => localParts(row.timestamp, offsetMinutes).date >= heatmapStart)
+    .filter(row => !options.projectId || row.projectId === options.projectId);
+  const heatmap = summarizeRows(heatmapRows, 182, offsetMinutes).daily.map(day => ({ date: day.date, totalTokens: day.totalTokens, requests: day.requests }));
+  return {
+    version: SCHEMA_VERSION,
+    range: requestedRange,
+    days,
+    timezoneOffset: offsetMinutes,
+    generatedAt: new Date().toISOString(),
+    ...summary,
+    heatmap,
+    recent: rows.slice(0, 30),
+  };
+}
+
+module.exports = { USAGE_FILE, mergeUsage, normalizeUsage, recordUsage, usageSummary };

package/backend/lib/util.ts

@@ -0,0 +1,31 @@
+// ── 跨路由共享的纯函数工具 ──────────────────────────────────────────────
+// 从资产对象中剔除 content 字段，仅保留元数据（避免列表接口返回大正文）
+function assetMeta<T extends { content?: unknown }>(asset: T | null | undefined) {
+  if (!asset) return asset;
+  const { content: _content, ...meta } = asset;
+  return meta;
+}
+
+async function readResponseText(response: Response, maxBytes = 2_000_000): Promise<string> {
+  const declared = Number(response.headers.get('content-length') || 0);
+  if (declared > maxBytes) throw new Error(`response exceeds ${maxBytes} bytes`);
+  if (!response.body) return '';
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let bytes = 0, output = '';
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    bytes += value.byteLength;
+    if (bytes > maxBytes) { await reader.cancel(); throw new Error(`response exceeds ${maxBytes} bytes`); }
+    output += decoder.decode(value, { stream: true });
+  }
+  return output + decoder.decode();
+}
+
+async function readResponseJson(response: Response, maxBytes = 2_000_000) {
+  const text = await readResponseText(response, maxBytes);
+  return JSON.parse(text);
+}
+
+module.exports = { assetMeta, readResponseText, readResponseJson };

package/backend/lib/workspace-store.ts

@@ -0,0 +1,150 @@
+const { safeId } = require('./catalog');
+import type { AssetRecord, JsonRecord, JsonStore, ProjectRecord, WorkspaceRecord } from '../types';
+
+const WORKSPACE_FILE = 'workspaces.json';
+const PROJECT_FILE = 'projects.json';
+const ASSET_FILE = 'assets.json';
+
+function now() { return new Date().toISOString(); }
+
+function createWorkspaceStore(store: JsonStore) {
+  function workspaces(): WorkspaceRecord[] { return store.read(WORKSPACE_FILE, [] as WorkspaceRecord[]); }
+  function projects(): ProjectRecord[] { return store.read(PROJECT_FILE, [] as ProjectRecord[]); }
+  function assets(): AssetRecord[] { return store.read(ASSET_FILE, [] as AssetRecord[]); }
+
+  function ensureSeed() {
+    let rows = workspaces();
+    if (!rows.length) {
+      const timestamp = now();
+      rows = [{ id: 'ws_default', name: '默认工作区', description: 'MultiChat 本地 Agent 工作区', createdAt: timestamp, updatedAt: timestamp, defaultProjectId: 'pr_inbox' }];
+      store.write(WORKSPACE_FILE, rows);
+    }
+    let projectRows = projects();
+    if (!projectRows.length) {
+      const timestamp = now();
+      projectRows = [{ id: 'pr_inbox', workspaceId: rows[0].id, name: '收件箱', description: '未分类的对话和文件', createdAt: timestamp, updatedAt: timestamp }];
+      store.write(PROJECT_FILE, projectRows);
+    }
+    if (!store.read(ASSET_FILE, null)) store.write(ASSET_FILE, []);
+  }
+
+  function getWorkspace(id: string) { return workspaces().find(x => x.id === id) || null; }
+  function getProject(id: string) { return projects().find(x => x.id === id) || null; }
+  function getAsset(id: string) { return assets().find(x => x.id === id) || null; }
+  function requireWorkspace(id: string) {
+    const value = getWorkspace(id);
+    if (!value) throw new Error('workspace not found');
+    return value;
+  }
+  function requireProject(id: string) {
+    const value = getProject(id);
+    if (!value) throw new Error('project not found');
+    return value;
+  }
+
+  function createWorkspace(input: JsonRecord = {}) {
+    const timestamp = now();
+    const workspaceId = 'ws_' + Date.now().toString(36);
+    const projectId = 'pr_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 5);
+    const row = { id: workspaceId, name: String(input.name || '新工作区').trim(), description: String(input.description || '').trim(), createdAt: timestamp, updatedAt: timestamp, defaultProjectId: projectId };
+    if (!row.name) throw new Error('workspace name is required');
+    const project = { id: projectId, workspaceId, name: '收件箱', description: '未分类的对话和文件', createdAt: timestamp, updatedAt: timestamp };
+    const rows = workspaces();
+    rows.unshift(row);
+    store.write(WORKSPACE_FILE, rows);
+    const projectRows = projects();
+    projectRows.unshift(project);
+    store.write(PROJECT_FILE, projectRows);
+    return row;
+  }
+
+  function updateWorkspace(id: string, input: JsonRecord = {}) {
+    const rows = workspaces();
+    const index = rows.findIndex(x => x.id === id);
+    if (index < 0) throw new Error('workspace not found');
+    const current = rows[index];
+    rows[index] = { ...current, ...(input.name !== undefined ? { name: String(input.name).trim() } : {}), ...(input.description !== undefined ? { description: String(input.description).trim() } : {}), updatedAt: now(), id: current.id };
+    if (!rows[index].name) throw new Error('workspace name is required');
+    store.write(WORKSPACE_FILE, rows);
+    return rows[index];
+  }
+
+  function removeWorkspace(id: string) {
+    const rows = workspaces();
+    if (rows.length <= 1) throw new Error('at least one workspace is required');
+    const workspace = requireWorkspace(id);
+    const remaining = rows.filter(x => x.id !== id);
+    const projectRows = projects().filter(x => x.workspaceId !== id);
+    const projectIds = new Set(projects().filter(x => x.workspaceId === id).map(x => x.id));
+    const assetRows = assets().filter(x => x.workspaceId !== id && !projectIds.has(x.projectId));
+    store.write(WORKSPACE_FILE, remaining);
+    store.write(PROJECT_FILE, projectRows);
+    store.write(ASSET_FILE, assetRows);
+    return workspace;
+  }
+
+  function createProject(input: JsonRecord = {}) {
+    const workspaceId = safeId(input.workspaceId || '', 'workspace id');
+    requireWorkspace(workspaceId);
+    const timestamp = now();
+    const row = { id: 'pr_' + Date.now().toString(36), workspaceId, name: String(input.name || '新项目').trim(), description: String(input.description || '').trim(), createdAt: timestamp, updatedAt: timestamp };
+    if (!row.name) throw new Error('project name is required');
+    const rows = projects();
+    rows.unshift(row);
+    store.write(PROJECT_FILE, rows);
+    return row;
+  }
+
+  function updateProject(id: string, input: JsonRecord = {}) {
+    const rows = projects();
+    const index = rows.findIndex(x => x.id === id);
+    if (index < 0) throw new Error('project not found');
+    const current = rows[index];
+    const nullableId = (value, label) => value == null || value === '' ? null : safeId(value, label);
+    rows[index] = {
+      ...current,
+      ...(input.name !== undefined ? { name: String(input.name).trim() } : {}),
+      ...(input.description !== undefined ? { description: String(input.description).trim() } : {}),
+      ...(input.defaultAgentId !== undefined ? { defaultAgentId: nullableId(input.defaultAgentId, 'agent id') } : {}),
+      ...(input.defaultProviderId !== undefined ? { defaultProviderId: nullableId(input.defaultProviderId, 'provider id') } : {}),
+      ...(input.defaultModel !== undefined ? { defaultModel: input.defaultModel == null || input.defaultModel === '' ? null : String(input.defaultModel).trim().slice(0, 200) } : {}),
+      updatedAt: now(), id: current.id, workspaceId: current.workspaceId,
+    };
+    if (!rows[index].name) throw new Error('project name is required');
+    store.write(PROJECT_FILE, rows);
+    return rows[index];
+  }
+
+  function removeProject(id: string) {
+    const project = requireProject(id);
+    if (projects().filter(x => x.workspaceId === project.workspaceId).length <= 1) throw new Error('a workspace must keep one project');
+    store.write(PROJECT_FILE, projects().filter(x => x.id !== id));
+    store.write(ASSET_FILE, assets().filter(x => x.projectId !== id));
+    return project;
+  }
+
+  function createAsset(input: JsonRecord = {}) {
+    const project = requireProject(safeId(input.projectId || '', 'project id'));
+    const content = String(input.content || '');
+    if (!content) throw new Error('asset content is required');
+    if (Buffer.byteLength(content, 'utf8') > 2_000_000) throw new Error('asset content exceeds 2 MB');
+    const timestamp = now();
+    const row: AssetRecord = { id: 'asset_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6), workspaceId: project.workspaceId, projectId: project.id, name: String(input.name || '未命名文件').trim(), mimeType: String(input.mimeType || 'text/plain'), size: Buffer.byteLength(content, 'utf8'), source: input.source === 'url' ? 'url' : 'local', url: input.url ? String(input.url) : null, content, createdAt: timestamp, updatedAt: timestamp };
+    if (!row.name) throw new Error('asset name is required');
+    const rows = assets();
+    rows.unshift(row);
+    store.write(ASSET_FILE, rows);
+    return row;
+  }
+
+  function removeAsset(id: string) {
+    const asset = getAsset(id);
+    if (!asset) throw new Error('asset not found');
+    store.write(ASSET_FILE, assets().filter(x => x.id !== id));
+    return asset;
+  }
+
+  return { ensureSeed, workspaces, projects, assets, getWorkspace, getProject, getAsset, requireWorkspace, requireProject, createWorkspace, updateWorkspace, removeWorkspace, createProject, updateProject, removeProject, createAsset, removeAsset };
+}
+
+module.exports = { createWorkspaceStore, WORKSPACE_FILE, PROJECT_FILE, ASSET_FILE };