zipcalm 0.0.0-stage → 1.0.2

package/server/http/routes/metrics.js

@@ -0,0 +1,36 @@
+// 性能指标端点（docs/M0/API规范.md §4.6）
+//
+// - GET /metrics/snapshot        最新一帧（前端 2 秒轮询这一支）
+// - GET /metrics/history?window=300&step=5  最近窗口内的降采样样本
+//
+// 约束（docs/07 §四）：只暴露 6 张卡片对应的字段，不堆砌指标。
+// 兼容性：/proc 缺失时字段为 null（接口照常 200，前端显示"—"），绝不因为采集不到而 500。
+
+import { ERROR_CODES, apiError } from '../../lib/errors.js';
+
+/** 历史窗口上限（秒）：契约 §4.6 说明环形缓冲只保留最近 5 分钟 */
+const MAX_HISTORY_WINDOW_SECONDS = 300;
+/** 默认与最小步长（秒） */
+const DEFAULT_STEP_SECONDS = 5;
+const MIN_STEP_SECONDS = 1;
+
+/** 查询参数 → 正整数（非法值回退默认，不抛错） */
+function positiveInt(raw, fallback) {
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+export default async function metricsRoutes(app) {
+  app.get('/metrics/snapshot', { preHandler: [app.requireAuth] }, async (request, reply) => {
+    if (!app.metrics) throw apiError(ERROR_CODES.SERVICE_UNAVAILABLE, '指标采集尚未就绪');
+    reply.ok(app.metrics.snapshot());
+  });
+
+  app.get('/metrics/history', { preHandler: [app.requireAuth] }, async (request, reply) => {
+    if (!app.metrics) throw apiError(ERROR_CODES.SERVICE_UNAVAILABLE, '指标采集尚未就绪');
+    const query = request.query || {};
+    const windowSeconds = Math.min(MAX_HISTORY_WINDOW_SECONDS, positiveInt(query.window, MAX_HISTORY_WINDOW_SECONDS));
+    const stepSeconds = Math.max(MIN_STEP_SECONDS, positiveInt(query.step, DEFAULT_STEP_SECONDS));
+    reply.ok({ samples: app.metrics.history({ window: windowSeconds, step: stepSeconds }) });
+  });
+}

package/server/http/routes/tasks.js

@@ -0,0 +1,304 @@
+// 任务端点（M3）：SSE 事件流 + 列表/详情/取消/重试/确认删除
+//
+// 契约：docs/M0/API规范.md §五（SSE 端点）+ §4.3（任务端点）
+//
+// SSE 实现要点（逐条对齐契约）：
+// 1. 连接建立后**第一帧必是 snapshot**（INV-05：进度是状态不是消息，重连先拿快照）；
+// 2. 先订阅后发快照：快照期间产生的事件先缓冲，避免"快照与增量之间丢事件"的竞态；
+// 3. `since=<seq>` 续传：窗口内补发增量；窗口外（replaySince 返回 null）只靠快照兜底；
+// 4. 心跳每 15s（防中间设备断连）；
+// 5. 响应头带 `X-Accel-Buffering: no`（反代下不被缓冲）；
+// 6. 连接结束（close/error）必须退订，防订阅者泄漏；
+// 7. 连接登记进 `app.tasks.sseClients`：关停时统一 end()，否则优雅停止会超时（见 app.js preClose）。
+//
+// 结构：SSE 的每一步（接管响应 / 建帧写入器 / 缓冲订阅 / 首帧快照 / 续传补发 / 心跳）都是
+// 一个模块级小函数，主 handler 只做编排。
+
+import { ERROR_CODES, apiError } from '../../lib/errors.js';
+
+const DEFAULT_CHANNELS = ['tasks'];
+
+/** 解析 channels 查询参数（默认 tasks；空值也回落默认） */
+function parseChannels(raw) {
+  if (typeof raw !== 'string' || raw.length === 0) return DEFAULT_CHANNELS;
+  const channels = raw.split(',').map((item) => item.trim()).filter(Boolean);
+  return channels.length > 0 ? channels : DEFAULT_CHANNELS;
+}
+
+/** 单帧序列化（SSE 报文格式；id 用 seq，便于 Last-Event-ID 续传） */
+function frameToText(frame) {
+  return `id: ${frame.seq}\nevent: ${frame.event}\ndata: ${JSON.stringify(frame.data)}\n\n`;
+}
+
+// ===== SSE 分步实现 =====
+
+/** 接管原生响应并写响应头；返回 res（Fastify 的响应装饰不适用于流式响应） */
+function hijackForSse(reply, request) {
+  reply.hijack();
+  const res = reply.raw;
+  const socket = request.raw.socket;
+  if (socket && typeof socket.setTimeout === 'function') socket.setTimeout(0); // SSE 不能被空闲超时掐断
+  if (typeof res.setTimeout === 'function') res.setTimeout(0);
+
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream; charset=utf-8',
+    'Cache-Control': 'no-cache',
+    Connection: 'keep-alive',
+    'X-Accel-Buffering': 'no',
+  });
+  if (typeof res.flushHeaders === 'function') res.flushHeaders();
+  return res;
+}
+
+/** 帧写入器：连接已结束返回 false（事件总线据此自愈剔除订阅者） */
+function createFrameWriter(res) {
+  return (frame) => {
+    if (res.writableEnded || res.destroyed) return false;
+    try {
+      res.write(frameToText(frame));
+      return !res.writableEnded;
+    } catch {
+      return false;
+    }
+  };
+}
+
+/** 先订阅后发快照：快照完成前的事件先缓冲，activate() 后切换为直发 */
+function subscribeBuffered(events, channels, writeFrame) {
+  const buffered = [];
+  let ready = false;
+  const unsubscribe = events.subscribe({
+    channels,
+    send: (frame) => {
+      if (ready) return writeFrame(frame);
+      buffered.push(frame);
+      return true;
+    },
+  });
+  return {
+    buffered,
+    unsubscribe,
+    activate: () => {
+      ready = true;
+    },
+  };
+}
+
+/** 首帧快照；构造失败返回 null（调用方负责断开，绝不静默挂着连接） */
+function sendSnapshotFrame(app, manager, events, writeFrame) {
+  try {
+    const seq = events.currentSeq();
+    writeFrame({ seq, event: 'snapshot', data: { ...manager.snapshot(), seq } });
+    return seq;
+  } catch (error) {
+    app.log.error('SSE 首帧快照构造失败，已断开连接', { error: error.message });
+    return null;
+  }
+}
+
+/** since 续传 + 缓冲补发（跳过快照已覆盖的 seq，按 seq 升序去重） */
+function flushResumeFrames(events, since, snapshotSeq, buffered, writeFrame) {
+  const seen = new Set();
+  const replayed = Number.isInteger(since) ? events.replaySince(since) : null;
+  for (const frame of replayed || []) {
+    if (frame.seq <= snapshotSeq) continue; // 快照已覆盖的状态不再重发
+    seen.add(frame.seq);
+    writeFrame(frame);
+  }
+  const pending = [...buffered].filter((frame) => frame.seq > snapshotSeq).sort((a, b) => a.seq - b.seq);
+  for (const frame of pending) {
+    if (seen.has(frame.seq)) continue;
+    writeFrame(frame);
+  }
+  buffered.length = 0;
+}
+
+/** 心跳定时器（连接已结束则走清理）；返回 interval 句柄，由 cleanup 负责清掉 */
+function startHeartbeat(res, heartbeatMs, cleanup) {
+  const heartbeat = setInterval(() => {
+    if (res.writableEnded || res.destroyed) {
+      cleanup();
+      return;
+    }
+    try {
+      res.write(`event: heartbeat\ndata: ${JSON.stringify({ ts: Date.now() })}\n\n`);
+    } catch {
+      cleanup();
+    }
+  }, heartbeatMs);
+  if (typeof heartbeat.unref === 'function') heartbeat.unref();
+  return heartbeat;
+}
+
+// ===== 端点 handler =====
+
+/** GET /tasks/events —— SSE 事件流（首帧快照 + 增量 + 心跳 + seq/since 续传） */
+async function handleTaskEvents(app, request, reply) {
+  const { manager, events } = app.tasks;
+  const heartbeatMs = app.m2.config.limits.sseHeartbeatMs;
+  const channels = parseChannels(request.query.channels);
+
+  const res = hijackForSse(reply, request);
+  const writeFrame = createFrameWriter(res);
+  const subscription = subscribeBuffered(events, channels, writeFrame);
+
+  // ① 首帧：当前状态快照（契约铁律，无论是否带 since 都先发）
+  const snapshotSeq = sendSnapshotFrame(app, manager, events, writeFrame);
+  if (snapshotSeq === null) {
+    subscription.unsubscribe();
+    try {
+      res.end();
+    } catch {
+      /* 连接可能已被对端关闭：忽略即可，不影响订阅者清理 */
+    }
+    return;
+  }
+
+  // ② since 续传 + ③ 缓冲补发，随后切换为直发
+  const since = Number.parseInt(request.query.since, 10);
+  flushResumeFrames(events, since, snapshotSeq, subscription.buffered, writeFrame);
+  subscription.activate();
+
+  // ④ 心跳与断开清理（登记 res，关停时由 app.preClose 统一 end()）
+  let cleaned = false;
+  let heartbeat = null;
+  function cleanup() {
+    if (cleaned) return;
+    cleaned = true;
+    if (heartbeat) clearInterval(heartbeat);
+    subscription.unsubscribe();
+    app.tasks.sseClients.delete(res);
+    app.log.info('SSE 订阅断开', { remaining: events.subscriberCount() });
+  }
+  app.tasks.sseClients.add(res);
+  heartbeat = startHeartbeat(res, heartbeatMs, cleanup);
+
+  request.raw.on('close', cleanup);
+  request.raw.on('error', cleanup);
+  res.on('close', cleanup);
+  res.on('error', cleanup);
+
+  app.log.info('SSE 订阅建立', {
+    channels,
+    since: Number.isInteger(since) ? since : null,
+    subscribers: events.subscriberCount(),
+    snapshotSeq,
+  });
+}
+
+/** GET /tasks —— 任务列表（内存非终态 + 历史缓存；契约 §六.5） */
+async function handleTaskList(app, request, reply) {
+  const rawStatus = request.query.status;
+  const status = typeof rawStatus === 'string' && rawStatus.length > 0
+    ? rawStatus.split(',').map((item) => item.trim()).filter(Boolean)
+    : null;
+  const limit = Number.parseInt(request.query.limit, 10);
+  reply.ok(app.tasks.manager.list({ status, limit: Number.isInteger(limit) ? limit : 50 }));
+}
+
+/** GET /tasks/history —— 历史查询（最近 N 条；内存缓存 + 文件兜底） */
+async function handleTaskHistory(app, request, reply) {
+  const limit = Number.parseInt(request.query.limit, 10);
+  const rawStatus = request.query.status;
+  const status = typeof rawStatus === 'string' && rawStatus.length > 0
+    ? rawStatus.split(',').map((item) => item.trim()).filter(Boolean)
+    : null;
+  const items = app.tasks.store.listHistory({ limit: Number.isInteger(limit) ? limit : 50, status });
+  reply.ok({ items, total: items.length, max: app.tasks.store.historyMax });
+}
+
+/** GET /tasks/{id} —— 单任务详情（终态任务从历史缓存还原） */
+async function handleTaskGet(app, request, reply) {
+  const task = app.tasks.manager.get(request.params.id);
+  if (!task) throw apiError(ERROR_CODES.TASK_NOT_FOUND, '任务不存在', { taskId: request.params.id });
+  reply.ok({ task });
+}
+
+/** POST /tasks/{id}/cancel —— 取消（queued/running → cancelling → aborted） */
+async function handleTaskCancel(app, request, reply) {
+  reply.ok({ task: app.tasks.manager.cancel(request.params.id) });
+}
+
+/** POST /tasks/{id}/retry —— 重试 = **新任务**（新 UUID + retryOf 指向原任务） */
+async function handleTaskRetry(app, request, reply) {
+  const { manager } = app.tasks;
+  const orchestrator = app.m2.orchestrator;
+  const task = await manager.retry(request.params.id);
+  manager.enqueue(task.id, (record) => (task.kind === 'extract'
+    ? orchestrator.runExtract(record)
+    : orchestrator.runCompress(record)));
+  reply.ok({ task: manager.get(task.id) }, 201);
+}
+
+/** 取任务并确认它确实处于"待二次确认"状态（三个前置条件是同一类错误，集中判定） */
+function requireConfirmableTask(manager, id) {
+  const task = manager.get(id);
+  if (!task) throw apiError(ERROR_CODES.TASK_NOT_FOUND, '任务不存在', { taskId: id });
+  if (!task.delete) throw apiError(ERROR_CODES.INVALID_STATE, '该任务没有待删除目标', { taskId: id });
+  if (task.phase !== 'waiting_confirm') {
+    throw apiError(ERROR_CODES.INVALID_STATE, '当前不是待确认状态', { phase: task.phase });
+  }
+  return task;
+}
+
+/** 数量/字节比对（INV-03：弹窗数字与实际不一致就拒绝删除）；返回归一化后的期望值 */
+function parseExpectedCounts(body, task) {
+  const expectedFiles = Number.isInteger(body.expectedFiles) ? body.expectedFiles : null;
+  const expectedBytes = Number.isFinite(body.expectedBytes) ? body.expectedBytes : null;
+  const actualFiles = task.delete.targets.length;
+  const actualBytes = task.delete.targets.reduce((sum, target) => sum + (Number(target.sizeBytes) || 0), 0);
+
+  if (expectedFiles !== null && expectedFiles !== actualFiles) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, '待删除数量与弹窗不一致，已拒绝删除', { expectedFiles, actualFiles });
+  }
+  if (expectedBytes !== null && Math.abs(expectedBytes - actualBytes) > 1) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, '待删除字节数与弹窗不一致，已拒绝删除', { expectedBytes, actualBytes });
+  }
+  return { expectedFiles, expectedBytes };
+}
+
+/** POST /tasks/{id}/confirm-delete —— 二次确认删除（压缩删原文件 / 解压删压缩包共用） */
+async function handleTaskConfirmDelete(app, request, reply) {
+  const { manager } = app.tasks;
+  const id = request.params.id;
+  const task = requireConfirmableTask(manager, id);
+
+  const body = request.body || {};
+  if (body.confirm === false) {
+    manager.resolveConfirm(id, { confirmed: false });
+    reply.ok({ task: manager.get(id) });
+    return;
+  }
+
+  const { expectedFiles, expectedBytes } = parseExpectedCounts(body, task);
+  manager.resolveConfirm(id, { confirmed: true, expectedFiles, expectedBytes });
+  reply.ok({ task: manager.get(id) });
+}
+
+/** DELETE /tasks/{id} —— 删除**终态**任务的活动记录（只动 tasks.json，绝不动历史） */
+async function handleTaskDelete(app, request, reply) {
+  // 删除后由 manager 广播一次快照，其他客户端自行对齐
+  reply.ok(await app.tasks.manager.remove(request.params.id));
+}
+
+export default async function taskRoutes(app) {
+  const auth = { preHandler: [app.requireAuth] };
+  const bind = (handler) => (request, reply) => handler(app, request, reply);
+
+  // SSE 必须注册在 /tasks/:id 之前（否则 "events" 会被当成任务 id）
+  app.get('/tasks/events', auth, bind(handleTaskEvents));
+  app.get('/tasks/history', auth, bind(handleTaskHistory));
+
+  app.get('/tasks', auth, bind(handleTaskList));
+  app.get('/tasks/:id', auth, bind(handleTaskGet));
+  app.get('/compress/tasks/:id', auth, bind(handleTaskGet)); // 契约别名
+
+  app.delete('/tasks/:id', auth, bind(handleTaskDelete));
+
+  app.post('/tasks/:id/cancel', auth, bind(handleTaskCancel));
+  app.post('/compress/tasks/:id/cancel', auth, bind(handleTaskCancel));
+
+  app.post('/tasks/:id/retry', auth, bind(handleTaskRetry));
+  app.post('/tasks/:id/confirm-delete', auth, bind(handleTaskConfirmDelete));
+  app.post('/compress/tasks/:id/confirm-delete', auth, bind(handleTaskConfirmDelete));
+}

package/server/lib/atomic-json.js

@@ -0,0 +1,118 @@
+// 原子写 JSON（先写临时文件再 rename）
+//
+// 为什么必须原子：任务/令牌这类状态文件如果被"原地截断写"中途打断，
+// 重启后就是半个 JSON —— 直接导致服务起不来。先写 <file>.tmp 再 rename 可保证
+// 读到的永远是「旧完整版」或「新完整版」，不存在中间态（docs/12 lib/atomic-json.js）。
+//
+// 为什么还要重试：CIFS/SMB 的 rename 语义与 POSIX 不同 ——
+//   · 目标文件正被别的进程读打开时，rename 会返回 EACCES（瞬时冲突，读完就释放）
+//   · rename 过程中存在极短窗口目标不可见，此时读会拿到 ENOENT
+// 实测（150 次原子写 + 持续并发读，storage 在 CIFS 上）：写失败 28%、读失败 58%；
+// 同样的代码在本地盘上写失败 0%、读失败 2.4%。这两个错误都是**瞬时**的，
+// 几十毫秒后即消失，所以有界重试就能覆盖，不需要改动调用方。
+//
+// 重试不会掩盖真问题：
+//   · 真失败（磁盘满 / 权限真的不对 / 目录不存在）会连续重试全败，最终仍抛错
+//   · 内容损坏（JSON 解析失败）不重试 —— 那和文件可见性无关，重试也没用
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/** 瞬时错误码：网络盘上由并发读写引起的可见性/共享冲突，重试可恢复 */
+const TRANSIENT_CODES = new Set(['EACCES', 'ENOENT', 'EBUSY', 'EPERM']);
+
+const WRITE_RETRIES = 3;
+const WRITE_RETRY_DELAY_MS = 50;
+const READ_RETRIES = 2;
+const READ_RETRY_DELAY_MS = 50;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * 原子写入 JSON 文件。
+ *
+ * 瞬时冲突（网络盘的 rename 可见性窗口）会自动重试；真正失败（磁盘满、权限、
+ * 目录不存在）重试耗尽后照常抛出，调用方的错误处理逻辑不受影响。
+ *
+ * @param {string} filePath 目标文件（父目录不存在会自动创建）
+ * @param {unknown} data 可被 JSON.stringify 的数据
+ */
+export async function writeJsonAtomic(filePath, data) {
+  const dir = path.dirname(filePath);
+  await fs.mkdir(dir, { recursive: true });
+  const tmpPath = `${filePath}.tmp`;
+  const text = `${JSON.stringify(data, null, 2)}\n`;
+
+  let lastError = null;
+  for (let attempt = 0; attempt <= WRITE_RETRIES; attempt += 1) {
+    try {
+      await fs.writeFile(tmpPath, text, 'utf8');
+      await fs.rename(tmpPath, filePath);
+      return;
+    } catch (error) {
+      lastError = error;
+      // 非瞬时错误（如 ENOSPC）立刻放弃，不做无意义重试
+      if (!TRANSIENT_CODES.has(error && error.code)) break;
+      if (attempt < WRITE_RETRIES) {
+        // 先清掉可能残留的 .tmp，再等一下重试：.tmp 残留会让下次写覆盖同一临时文件，
+        // 而并发写的场景下留着它反而可能加剧冲突。
+        await fs.rm(tmpPath, { force: true }).catch(() => {});
+        await sleep(WRITE_RETRY_DELAY_MS * (attempt + 1));
+      }
+    }
+  }
+
+  // 重试耗尽仍失败：清理临时文件（避免 .tmp 残留被「无残留」类断言误判成产品泄漏），
+  // 目标文件（旧完整版）保持不动，然后把错误抛给调用方。
+  await fs.rm(tmpPath, { force: true }).catch(() => {});
+  throw lastError;
+}
+
+/**
+ * 读取 JSON；文件不存在或内容损坏时返回 fallback（不抛错，避免"一个坏文件拖垮启动"）。
+ *
+ * ENOENT 会短暂重试：网络盘的 rename 有可见性窗口，读到「文件暂时不存在」不代表真丢了。
+ * 重试仍读不到才按 not-found 返回 fallback；JSON 解析失败不重试（内容问题重试无意义）。
+ *
+ * @param {string} filePath
+ * @param {unknown} fallback
+ * @returns {Promise<{data: unknown, ok: boolean, reason?: string}>}
+ */
+export async function readJson(filePath, fallback = null) {
+  let lastReason = null;
+  for (let attempt = 0; attempt <= READ_RETRIES; attempt += 1) {
+    try {
+      const text = await fs.readFile(filePath, 'utf8');
+      return { data: JSON.parse(text), ok: true };
+    } catch (error) {
+      const code = error && error.code;
+      if (code === 'ENOENT') {
+        lastReason = 'not-found';
+        if (attempt < READ_RETRIES) {
+          await sleep(READ_RETRY_DELAY_MS * (attempt + 1));
+          continue;
+        }
+        break;
+      }
+      // 读到了但解析失败（内容损坏）、或权限类错误：重试无意义，直接返回原因
+      lastReason = `unreadable:${code}`;
+      break;
+    }
+  }
+  return { data: fallback, ok: false, reason: lastReason };
+}
+
+/** 确保目录存在（幂等） */
+export async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+/** 检查路径是否可读写（用于配置校验时给出明确原因） */
+export async function checkAccess(targetPath, mode) {
+  try {
+    await fs.access(targetPath, mode);
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, reason: error && error.code ? error.code : 'EUNKNOWN' };
+  }
+}

package/server/lib/errors.js

@@ -0,0 +1,145 @@
+// 错误对象与错误码统一入口（M1）
+//
+// 铁律（docs/M0/API规范.md §八 + INV-12）：**错误码全部来自 shared/error-codes.js，不允许自造**。
+// 这里只做三件事：
+//   1. 提供 ApiError（携带契约错误码 + 可选 details）；
+//   2. 把 Node 的系统错误（ENOENT/EACCES/ENOSPC…）翻译成契约错误码；
+//   3. 输出契约要求的 error 载荷 {code, message, details}。
+
+import { ERROR_CODES, isErrorCode, errorCodeMeta } from '../../shared/error-codes.js';
+
+/** 系统错误码 → 契约错误码（只映射已知的，其余落到 INTERNAL_ERROR） */
+const SYSTEM_ERROR_MAP = {
+  ENOENT: ERROR_CODES.PATH_NOT_FOUND,
+  EACCES: ERROR_CODES.PERMISSION_DENIED,
+  EPERM: ERROR_CODES.PERMISSION_DENIED,
+  ENOTDIR: ERROR_CODES.NOT_A_DIRECTORY,
+  EISDIR: ERROR_CODES.NOT_A_DIRECTORY,
+  ENOSPC: ERROR_CODES.DISK_FULL,
+  EDQUOT: ERROR_CODES.QUOTA_EXCEEDED,
+  EMFILE: ERROR_CODES.SERVICE_UNAVAILABLE,
+  ENFILE: ERROR_CODES.SERVICE_UNAVAILABLE,
+  ELOOP: ERROR_CODES.PATH_OUT_OF_ROOT,
+  // 路径类错误：全部归 INVALID_PATH(400)，**不允许落到 500**
+  // （契约 §八 把「超长」明确列在 INVALID_PATH 的触发场景里：这是客户端可修正的请求，
+  //   不是服务端故障。真实案例：GET /fs/list?path=/aaaa…(300) 曾返回 500 INTERNAL_ERROR，
+  //   根因就是 ENAMETOOLONG 没有映射，落到兜底 INTERNAL_ERROR。）
+  ENAMETOOLONG: ERROR_CODES.INVALID_PATH,
+  EINVAL: ERROR_CODES.INVALID_PATH,
+  EBADF: ERROR_CODES.INVALID_PATH,
+  EFAULT: ERROR_CODES.INVALID_PATH,
+};
+
+/**
+ * 与路径操作相关的系统调用名。
+ * 用途：**兜底**——即便某个底层错误码没在上面显式映射，只要它出自路径类 syscall，
+ * 也一律翻译成 INVALID_PATH(400)，避免"路径太长/非法"再次变成 500。
+ */
+const PATH_SYSCALLS = new Set([
+  'realpath',
+  'stat',
+  'lstat',
+  'fstat',
+  'readdir',
+  'scandir',
+  'opendir',
+  'open',
+  'access',
+  'readlink',
+  'mkdir',
+  'rename',
+]);
+
+export class ApiError extends Error {
+  /**
+   * @param {string} code shared/error-codes.js 里的错误码
+   * @param {string} [message] 给人看的说明（不给则用契约里的中文文案）
+   * @param {object|null} [details] 机器可读的附加信息
+   */
+  constructor(code, message = '', details = null) {
+    const safeCode = isErrorCode(code) ? code : ERROR_CODES.INTERNAL_ERROR;
+    super(message || errorCodeMeta(safeCode).label);
+    this.name = 'ApiError';
+    this.code = safeCode;
+    this.details = details;
+    // 标记为非预期错误（用于日志级别判断）
+    this.expected = true;
+  }
+}
+
+/** 语法糖：throw apiError('PATH_NOT_FOUND', '...', {path}) */
+export function apiError(code, message, details = null) {
+  return new ApiError(code, message, details);
+}
+
+/**
+ * 任意异常 → ApiError。
+ * 已经是 ApiError 的原样返回；系统错误按表翻译；其余归 INTERNAL_ERROR（保留 cause 便于排查）。
+ *
+ * 安全：对外可见的 message **绝不携带本机绝对路径与内部细节**——
+ * Node 系统错误的原始 message 里通常带 `realpath '<绝对路径>'`，直接透出等于把存储根布局
+ * 告诉任何已登录客户端。因此这里只保留 syscall（如 realpath）作为排障线索，路径不进 message。
+ */
+/** 标 expected=true 的错误：属于调用方造成的可预期失败，不写内部堆栈 */
+function expectedError(code, details) {
+  const mapped = new ApiError(code, undefined, details);
+  mapped.expected = true;
+  return mapped;
+}
+
+/**
+ * 系统错误码 → 契约错误（不为认知的错误返回 null，由调用方继续兜底）。
+ * @returns {ApiError|null}
+ */
+function mapSystemError(error) {
+  const systemCode = error && error.code;
+  if (typeof systemCode !== 'string') return null;
+  if (SYSTEM_ERROR_MAP[systemCode]) {
+    return expectedError(SYSTEM_ERROR_MAP[systemCode], { syscall: error.syscall || null });
+  }
+  // 未映射的路径类 syscall：按"路径非法"处理（4xx），不要变成 500
+  if (PATH_SYSCALLS.has(error && error.syscall)) {
+    return expectedError(ERROR_CODES.INVALID_PATH, { syscall: error.syscall, sys: systemCode });
+  }
+  return null;
+}
+
+export function toApiError(error) {
+  if (error instanceof ApiError) return error;
+
+  const mappedSystem = mapSystemError(error);
+  if (mappedSystem) return mappedSystem;
+
+  // Fastify 自带校验错误（如 body 结构不对）
+  if (error && error.validation) {
+    return new ApiError(ERROR_CODES.VALIDATION_FAILED, error.message, { validation: error.validation });
+  }
+  if (error && typeof error.statusCode === 'number' && error.statusCode === 400) {
+    return new ApiError(ERROR_CODES.BAD_REQUEST, '请求格式不正确');
+  }
+
+  // 兜底：内部错误对外只给通用文案（真实原因写日志，靠 traceId 关联）
+  const internal = new ApiError(ERROR_CODES.INTERNAL_ERROR, undefined, null);
+  internal.expected = false;
+  internal.cause = error;
+  return internal;
+}
+
+/** 契约的 error 载荷 */
+export function errorPayload(error) {
+  const apiErr = toApiError(error);
+  const payload = {
+    code: apiErr.code,
+    message: apiErr.message || errorCodeMeta(apiErr.code).label,
+  };
+  if (apiErr.details) payload.details = apiErr.details;
+  return payload;
+}
+
+/** HTTP 状态：优先契约里的映射，缺省 500 */
+export function httpStatusOfError(error) {
+  const meta = errorCodeMeta(toApiError(error).code);
+  return meta.http || 500;
+}
+
+export { ERROR_CODES };

package/server/lib/fs-probe.js

@@ -0,0 +1,25 @@
+/*
+ * 文件系统探测小工具（**一律异步**）
+ *
+ * 为什么单独收成一模块：服务端的这些探测几乎都发生在**请求路径**或**任务执行路径**上，
+ * `existsSync` / `statSync` 会把事件循环钉住（一次系统调用不慢，但它们在循环与并发请求里会被放大）；
+ * 而且它们被多个模块各写一份（预检、产物命名、创建守卫、落盘计划）—— 收成一处才不会"改一处忘一处"。
+ */
+
+import fsp from 'node:fs/promises';
+
+/**
+ * 路径是否存在。
+ * 语义与 `existsSync` 对齐：任何访问失败（ENOENT / EACCES / ENOTDIR …）都算"不存在"，
+ * 不区分失败原因（需要区分原因的调用方请直接用 fsp.stat/access 并自行处理错误）。
+ * @param {string} target
+ * @returns {Promise<boolean>}
+ */
+export async function pathExists(target) {
+  try {
+    await fsp.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}