nx-kv 0.8.4 → 0.9.0

package/src/core/attachstore.js

@@ -0,0 +1,269 @@
+// 附件的「本地镜像」：把某个用户空间（group）里的附件落到本机，
+// 好让 agent **直接读本地文件**，不再依赖网络与出图地址。
+//
+// 目录（刻意落在 nx-kv 的用户目录下）：
+//   ~/.nx-kv/attachments/<groupId|default>/        ← NX_KV_ATTACHMENTS 可改根目录
+// 台账：
+//   同目录 manifest.json → { groupId, dir, updatedAt, files: { <fileId>: {name, size, contentType, syncedAt} } }
+//
+// 为什么需要台账：后端 FileInfoRes **不回传原始文件名**，本地落点只能自己定；
+// 台账把「fileId → 本地文件名 + 大小」固定下来，于是反复同步能跳过未变更的，
+// 也不会每 sync 一次就换一个名字（那样等于每次重新下载）。
+import fsp from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, extname, join, parse as parsePath, resolve } from 'node:path';
+import { attachmentsRootFromEnv } from './paths.js';
+import { normalizeGroupId } from './config.js';
+import { downloadFile, listAllFiles } from './fileapi.js';
+
+export const MANIFEST_NAME = 'manifest.json';
+
+const nowIso = () => new Date().toISOString();
+
+/** 该 group 的本地目录。override 优先（来自设置里的 attachmentsDir）。 */
+export function localDirFor(groupId, override = '') {
+  if (override) return resolve(String(override));
+  const n = normalizeGroupId(groupId);
+  return join(attachmentsRootFromEnv(), n === undefined ? 'default' : String(n));
+}
+
+export function manifestPath(dir) {
+  return join(dir, MANIFEST_NAME);
+}
+
+export async function readManifest(dir) {
+  try {
+    const raw = JSON.parse(await fsp.readFile(manifestPath(dir), 'utf8'));
+    return {
+      groupId: Number(raw.groupId) || 0,
+      dir: String(raw.dir || dir),
+      updatedAt: String(raw.updatedAt || ''),
+      files: raw.files && typeof raw.files === 'object' ? raw.files : {},
+    };
+  } catch {
+    // 台账不存在或损坏：当成空台账。它只是缓存，不是真相源 —— 真相源是后端。
+    return { groupId: 0, dir, updatedAt: '', files: {} };
+  }
+}
+
+export async function writeManifest(dir, data) {
+  await fsp.mkdir(dir, { recursive: true });
+  const tmp = manifestPath(dir) + '.tmp';
+  await fsp.writeFile(tmp, JSON.stringify(data, null, 2), 'utf8');
+  await fsp.rename(tmp, manifestPath(dir));
+  return data;
+}
+
+// Windows 保留设备名做文件名会让文件无法访问
+const RESERVED = new Set([
+  'con', 'prn', 'aux', 'nul',
+  ...Array.from({ length: 9 }, (_, i) => `com${i + 1}`),
+  ...Array.from({ length: 9 }, (_, i) => `lpt${i + 1}`),
+]);
+
+/** 收成跨平台可用的单段文件名（保留中文）。 */
+export function safeFileName(name) {
+  let s = String(name ?? '')
+    .replace(/[<>:"/\\|?*\x00-\x1f]/g, '_')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/^\.+/, '');
+  if (!s) s = 'file';
+  if (RESERVED.has(parsePath(s).name.toLowerCase())) s = '_' + s;
+  return s.slice(0, 120);
+}
+
+const EXT_BY_TYPE = {
+  'image/png': '.png',
+  'image/jpeg': '.jpg',
+  'image/webp': '.webp',
+  'image/gif': '.gif',
+  'image/svg+xml': '.svg',
+  'application/pdf': '.pdf',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': '.docx',
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': '.xlsx',
+  'application/vnd.openxmlformats-officedocument.presentationml.presentation': '.pptx',
+  'text/plain; charset=utf-8': '.txt',
+  'text/markdown; charset=utf-8': '.md',
+};
+
+/**
+ * 本地落点文件名。优先用调用方给的「人读名字」（任务里 markdown 的说明/链接文字），
+ * 否则退回 fileId；两者都没有扩展名时，再按 fileId 自带后缀 / Content-Type 补一个。
+ * 补后缀是刚需：没有扩展名，Windows 上双击打不开、内联预览也认不出类型。
+ */
+export function localNameFor(fileId, preferred, contentType = '') {
+  let base = safeFileName(preferred || fileId);
+  if (!extname(base)) {
+    const fromId = extname(String(fileId));
+    const guess = fromId || EXT_BY_TYPE[String(contentType).toLowerCase()] || '';
+    if (guess) base += guess;
+  }
+  return base;
+}
+
+/** 同目录内不重名的落点（`名字 (2).ext`）。files 是 id → 台账记录。 */
+function uniqueName(files, name, selfId) {
+  const taken = new Set(
+    Object.entries(files)
+      .filter(([id]) => id !== selfId)
+      .map(([, rec]) => String(rec?.name || ''))
+  );
+  if (!taken.has(name)) return name;
+  const { name: stem, ext } = parsePath(name);
+  let n = 1;
+  let candidate = name;
+  while (taken.has(candidate)) {
+    n += 1;
+    candidate = `${stem} (${n})${ext}`;
+  }
+  return candidate;
+}
+
+/**
+ * 读台账 + 落盘文件，判断某个附件是否**已经在本地且内容未变**。
+ * 返回绝对路径；没同步过（或本地文件被删了）返回 null。
+ */
+export async function resolveLocal(groupId, fileId, overrideDir = '') {
+  const dir = localDirFor(groupId, overrideDir);
+  const man = await readManifest(dir);
+  const rec = man.files[fileId];
+  if (!rec || !rec.name) return null;
+  const abs = join(dir, String(rec.name));
+  return existsSync(abs) ? { path: abs, name: String(rec.name), size: Number(rec.size) || 0 } : null;
+}
+
+/** 该目录下已同步的全部条目（id → {path,name,size}），供 `todo attachments` 批量标注用。 */
+export async function localIndex(groupId, overrideDir = '') {
+  const dir = localDirFor(groupId, overrideDir);
+  const man = await readManifest(dir);
+  const out = new Map();
+  for (const [id, rec] of Object.entries(man.files)) {
+    const abs = join(dir, String(rec?.name || ''));
+    if (rec?.name && existsSync(abs)) {
+      out.set(id, { path: abs, name: String(rec.name), size: Number(rec.size) || 0 });
+    }
+  }
+  return { dir, index: out };
+}
+
+/**
+ * 同步附件到本地。
+ *
+ * - `ids` 为空 → 同步该 group 的**全部**附件（`file sync` 的默认语义）
+ * - `ids` 非空 → 只同步这些 id（读任务时按引用同步走这条）
+ * - `names` → fileId 的人读文件名（来自任务里 markdown 的说明文字）
+ * - `prune` → 删掉本地已不在后端的文件（**仅在 sync-all 时生效**：
+ *   带了 ids 过滤还 prune，会把没列出来的附件一起删掉）
+ *
+ * 单个文件下载失败**不中断整体**：如实记进 failures 让调用方知道哪些没拿到。
+ */
+export async function syncAttachments({
+  groupId,
+  ids = null,
+  names = {},
+  dir: overrideDir = '',
+  prune = false,
+  dryRun = false,
+} = {}) {
+  const dir = localDirFor(groupId, overrideDir);
+  const man = await readManifest(dir);
+  const files = { ...man.files };
+
+  const remote = await listAllFiles({ groupId });
+  const wanted = Array.isArray(ids) && ids.length ? new Set(ids.map(String)) : null;
+  const remoteIds = new Set(remote.items.map((f) => f.fileId));
+
+  const failures = [];
+  const missing = [];
+  if (wanted) for (const id of wanted) if (!remoteIds.has(id)) missing.push(id);
+
+  const entries = [];
+  let downloaded = 0;
+  let skipped = 0;
+
+  for (const meta of remote.items) {
+    const id = meta.fileId;
+    if (wanted && !wanted.has(id)) continue;
+
+    const desired = localNameFor(id, names[id], meta.contentType);
+    const prev = files[id];
+    const prevAbs = prev?.name ? join(dir, String(prev.name)) : '';
+    const sizeKnown = Number(prev?.size) > 0;
+    const unchanged = prevAbs && existsSync(prevAbs) && sizeKnown && Number(prev.size) === Number(meta.size);
+
+    if (unchanged) {
+      skipped++;
+      entries.push({ id, name: String(prev.name), path: prevAbs, size: Number(prev.size), contentType: meta.contentType, synced: true });
+      continue;
+    }
+    if (dryRun) {
+      entries.push({ id, name: desired, path: join(dir, desired), size: meta.size, contentType: meta.contentType, synced: false });
+      continue;
+    }
+
+    let buf;
+    try {
+      buf = await downloadFile(id);
+    } catch (e) {
+      failures.push({ id, error: String((e && e.message) || e) });
+      // 本地已有旧版本就继续用它，避免「网络抖一下附件就消失」
+      if (prevAbs && existsSync(prevAbs)) {
+        entries.push({ id, name: String(prev.name), path: prevAbs, size: Number(prev.size), contentType: meta.contentType, synced: true, stale: true });
+      }
+      continue;
+    }
+
+    const name = uniqueName(files, desired, id);
+    const abs = join(dir, name);
+    try {
+      await fsp.mkdir(dirname(abs), { recursive: true });
+      await fsp.writeFile(abs, buf);
+    } catch (e) {
+      failures.push({ id, error: String((e && e.message) || e) });
+      continue;
+    }
+    files[id] = { name, size: buf.length, contentType: meta.contentType, syncedAt: nowIso() };
+    downloaded++;
+    entries.push({ id, name, path: abs, size: buf.length, contentType: meta.contentType, synced: true });
+  }
+
+  // prune：只在同步全部时生效（理由见函数头）
+  const removed = [];
+  if (prune && !wanted && !dryRun) {
+    for (const id of Object.keys(files)) {
+      if (remoteIds.has(id)) continue;
+      const abs = join(dir, String(files[id]?.name || ''));
+      try {
+        if (existsSync(abs)) await fsp.unlink(abs);
+      } catch {
+        // 删不掉就留着（可能被占用）；台账条目仍移除，下次同步不会误认它是最新的
+      }
+      removed.push(files[id]?.name || id);
+      delete files[id];
+    }
+  }
+
+  if (!dryRun) {
+    await writeManifest(dir, {
+      groupId: normalizeGroupId(groupId) || 0,
+      dir,
+      updatedAt: nowIso(),
+      files,
+    });
+  }
+
+  return {
+    dir,
+    groupId: normalizeGroupId(groupId) || 0,
+    dryRun: !!dryRun,
+    totalRemote: remote.items.length,
+    target: wanted ? wanted.size : remote.items.length,
+    downloaded,
+    skipped,
+    removed,
+    missing,
+    failures,
+    files: entries,
+  };
+}

package/src/core/config.js

@@ -23,6 +23,12 @@ const EMPTY = () => ({
   userId: 0,
   // 当前工作空间：0 = 不传 groupId（后端回落默认组）
   groupId: 0,
+  // 读任务时是否自动把附件拉到本机。默认 **关**：开启意味着每次 list/get 都会
+  // 触网下载，对「只想看一眼清单」的场景是纯负担；开关在面板「清单」页或
+  // `nx-kv setting set --autoSyncAttachments`。
+  autoSyncAttachments: false,
+  // 附件本地目录覆盖；空 = 用默认 ~/.nx-kv/attachments/<groupId>/
+  attachmentsDir: '',
 });
 
 let cache = null;
@@ -37,6 +43,8 @@ function normalize(data) {
     email: String(data.email || ''),
     userId: Number(data.userId) || 0,
     groupId: Number(data.groupId) || 0,
+    autoSyncAttachments: data.autoSyncAttachments === true,
+    attachmentsDir: String(data.attachmentsDir || ''),
   };
 }
 
@@ -92,3 +100,17 @@ export function normalizeGroupId(v) {
   const n = Number(v);
   return Number.isFinite(n) && n > 0 ? n : undefined;
 }
+
+/**
+ * 解析「这次操作作用于哪个工作空间」：显式传入的 --group 优先，否则回落到本机配置
+ * 里的当前工作空间。
+ *
+ * 放进 core 是因为**不止一个模块要用同一条规则**：todo 拿它读写 KV，
+ * file 拿它选后端分组与本地附件目录。两处各写一遍的话，一旦有人只改了一处，
+ * 就会出现「从 A 组读任务、往 B 组同步附件」—— 这类错不报错，只是静默地对不上。
+ */
+export async function resolveGroupId(groupId) {
+  if (groupId !== undefined && groupId !== null && groupId !== '') return normalizeGroupId(groupId);
+  const cfg = await loadConfig();
+  return normalizeGroupId(cfg.groupId);
+}

package/src/core/fileapi.js

@@ -0,0 +1,243 @@
+// 后端文件（图床）客户端 —— 对接 dev_ctr_hello 的 /api/v1/files* 与 /files/:fileId。
+//
+// 与 kvapi.js 共用同一套信封判定：**HTTP 恒为 200，成败看 body 里的 `code`**（0 = 成功），
+// 所以这里复用 kvapi 导出的 call()，不另写一份解析。
+//
+// 上传走 multipart（后端 r.GetUploadFile("file")），其余走 JSON。
+//
+// fileId 是后端生成的不透明串：16 字节随机 → 32 位 hex；原文件名带扩展名时
+// 后端会在 id 后再接 `.<ext>`（service/file/file.go 的 newFileId + "." + newExt），
+// 所以 id 偶尔带后缀。判定「像不像 fileId」一律走 attach.js 的 looksLikeFileId。
+import { badInput, external, notFound } from './errors.js';
+import { loadConfig, normalizeGroupId } from './config.js';
+import { call } from './kvapi.js';
+
+const TIMEOUT_MS = 60000;
+
+// 扩展名 → Content-Type。上传时按文件名猜：一律 octet-stream 会让浏览器
+// 拿到 application/octet-stream 而不内联渲染，图片就「预览不出来」了。
+const MIME = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+  '.bmp': 'image/bmp',
+  '.avif': 'image/avif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.pdf': 'application/pdf',
+  '.doc': 'application/msword',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.xls': 'application/vnd.ms-excel',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  '.ppt': 'application/vnd.ms-powerpoint',
+  '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  '.txt': 'text/plain; charset=utf-8',
+  '.md': 'text/markdown; charset=utf-8',
+  '.csv': 'text/csv; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.zip': 'application/zip',
+};
+
+const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp', '.avif', '.svg', '.ico']);
+
+const extOf = (name) => {
+  const m = /(\.[A-Za-z0-9]{1,8})$/.exec(String(name || ''));
+  return m ? m[1].toLowerCase() : '';
+};
+
+export function contentTypeOf(name, fallback = 'application/octet-stream') {
+  return MIME[extOf(name)] || fallback;
+}
+
+export function isImageName(name, contentType = '') {
+  const e = extOf(name);
+  if (e) return IMAGE_EXT.has(e);
+  return /^image\//i.test(String(contentType));
+}
+
+export function normalizeFileMeta(d = {}) {
+  return {
+    fileId: String(d.fileId ?? ''),
+    url: String(d.url ?? ''),
+    accessLevel: String(d.accessLevel ?? ''),
+    size: Number(d.size) || 0,
+    contentType: String(d.contentType ?? ''),
+    groupId: Number(d.groupId) || 0,
+    groupName: String(d.groupName ?? ''),
+    sha256: String(d.sha256 ?? ''),
+    md5: String(d.md5 ?? ''),
+    tags: Array.isArray(d.tags) ? d.tags.map(String) : [],
+    createdAt: String(d.createdAt ?? ''),
+    expireAt: String(d.expireAt ?? ''),
+  };
+}
+
+const gidQuery = (groupId) => {
+  const n = normalizeGroupId(groupId);
+  return n === undefined ? '' : `?groupId=${n}`;
+};
+
+/** 出图地址：一律**自己拼**，不用后端回的 url。
+ *  后端 url 按请求 Host 推断（可能被反代写成内网地址），自己拼才跟 baseUrl 一致，
+ *  也才在假后端 / 换域名时都可预期。 */
+export function accessUrlOf(baseUrl, fileId) {
+  return String(baseUrl || '').replace(/\/$/, '') + '/files/' + encodeURIComponent(fileId);
+}
+
+export async function fileAccessUrl(fileId) {
+  const cfg = await loadConfig();
+  // fileId 可能带扩展名（xxx.docx）；encodeURIComponent 不会编码 `.`，安全
+  return accessUrlOf(cfg.baseUrl, fileId);
+}
+
+// ---- 上传（multipart）----
+
+async function parseEnvelope(res, ctxLabel) {
+  let envelope;
+  try {
+    envelope = JSON.parse(await res.text());
+  } catch {
+    throw external(`后端返回了非 JSON（HTTP ${res.status}）: ${ctxLabel}`);
+  }
+  const code = envelope.code ?? res.status;
+  if (code !== 0) {
+    if (code === 401) throw badInput('未登录或登录已过期（执行 nx-kv auth login <email>）');
+    throw external(`后端 code=${code}: ${envelope.message || '(无消息)'}`, { code, path: ctxLabel });
+  }
+  return envelope.data ?? null;
+}
+
+/**
+ * 上传一个文件到当前用户空间（group）。
+ * buffer 是完整字节：CLI 从本机文件读、面板从 base64 解 —— 两条路共用这一处。
+ */
+export async function fileUpload({
+  name,
+  buffer,
+  contentType,
+  groupId,
+  accessLevel = 'public',
+  tags = [],
+  key = '',
+  expireSeconds = 0,
+} = {}) {
+  if (!name) throw badInput('上传必须带文件名');
+  if (!buffer || !buffer.length) throw badInput('上传内容为空');
+
+  const cfg = await loadConfig();
+  const url = cfg.baseUrl.replace(/\/$/, '') + '/api/v1/files';
+  const ct = contentType || contentTypeOf(name);
+
+  const form = new FormData();
+  form.append('file', new Blob([buffer], { type: ct }), String(name));
+  form.append('accessLevel', String(accessLevel));
+  const gid = normalizeGroupId(groupId);
+  if (gid !== undefined) form.append('groupId', String(gid));
+  if (expireSeconds) form.append('expireSeconds', String(expireSeconds));
+  if (key) form.append('key', String(key));
+  for (const t of tags) form.append('tags', String(t));
+
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+  let res;
+  try {
+    // ⚠️ 不能自己设 content-type：multipart 的 boundary 由 FormData 生成，
+    // 手写一个会丢掉 boundary，后端解析直接失败。
+    res = await fetch(url, {
+      method: 'POST',
+      headers: cfg.token ? { authorization: `Bearer ${cfg.token}` } : {},
+      body: form,
+      signal: ctrl.signal,
+    });
+  } catch (e) {
+    if (e && e.name === 'AbortError') throw external(`上传超时（${TIMEOUT_MS}ms）: ${name}`);
+    throw external(`无法连接后端 ${cfg.baseUrl}: ${e.message}`);
+  } finally {
+    clearTimeout(timer);
+  }
+
+  const data = await parseEnvelope(res, 'POST /api/v1/files');
+  if (!data || !data.fileId) throw external('上传成功但后端未返回 fileId');
+  return normalizeFileMeta(data);
+}
+
+// ---- 列表 / 元数据 / 删除（JSON）----
+
+export async function listFiles({ groupId, limit = 100, offset = 0 } = {}) {
+  const n = normalizeGroupId(groupId);
+  const q = `?limit=${Number(limit) || 100}&offset=${Number(offset) || 0}` + (n === undefined ? '' : `&groupId=${n}`);
+  const data = await call({ method: 'GET', path: '/api/v1/files' + q });
+  return {
+    total: Number(data?.total) || 0,
+    hasMore: data?.hasMore === true,
+    items: (data?.items ?? []).map(normalizeFileMeta),
+  };
+}
+
+/** 一次拉全（分页直到 total 或页数上限），供同步用。
+ *  上限存在的意义：列表接口异常返回 hasMore=true 时不会把 CLI 卡死。 */
+export async function listAllFiles({ groupId, pageSize = 200, maxPages = 50 } = {}) {
+  const out = [];
+  let total = 0;
+  for (let page = 0; page < maxPages; page++) {
+    const r = await listFiles({ groupId, limit: pageSize, offset: page * pageSize });
+    out.push(...r.items);
+    total = r.total;
+    if (!r.items.length || out.length >= total) break;
+  }
+  return { total, items: out };
+}
+
+export async function fileInfo(fileId, groupId) {
+  if (!fileId) throw badInput('缺少 fileId');
+  const data = await call({
+    method: 'GET',
+    path: `/api/v1/files/${encodeURIComponent(fileId)}/info` + gidQuery(groupId),
+    allowMissing: true,
+  });
+  if (!data) throw notFound(`附件不存在: ${fileId}（可能已被删除或不在当前工作空间）`);
+  return normalizeFileMeta(data);
+}
+
+export async function deleteFile(fileId, groupId) {
+  if (!fileId) throw badInput('缺少 fileId');
+  await call({
+    method: 'DELETE',
+    path: `/api/v1/files/${encodeURIComponent(fileId)}` + gidQuery(groupId),
+  });
+  return { fileId, deleted: true };
+}
+
+/**
+ * 取文件本体：返回未解析的 fetch Response（调用方 pipe / arrayBuffer）。
+ * 走的是**无鉴权的出图路由** /files/:fileId —— 与 <img src> 同一条路，
+ * 所以「浏览器能预览」与「CLI 能下载」在权限上永远一致。
+ */
+export async function openFileStream(fileId) {
+  if (!fileId) throw badInput('缺少 fileId');
+  const cfg = await loadConfig();
+  const url = await fileAccessUrl(fileId);
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+  let res;
+  try {
+    res = await fetch(url, {
+      headers: cfg.token ? { authorization: `Bearer ${cfg.token}` } : {},
+      signal: ctrl.signal,
+    });
+  } catch (e) {
+    if (e && e.name === 'AbortError') throw external(`下载超时（${TIMEOUT_MS}ms）: ${fileId}`);
+    throw external(`无法连接后端 ${cfg.baseUrl}: ${e.message}`);
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!res.ok) throw notFound(`附件下载失败（HTTP ${res.status}）: ${fileId}`);
+  return res;
+}
+
+export async function downloadFile(fileId) {
+  const res = await openFileStream(fileId);
+  return Buffer.from(await res.arrayBuffer());
+}

package/src/core/kvapi.js

@@ -16,7 +16,9 @@ import { loadConfig, normalizeGroupId } from './config.js';
 
 const TIMEOUT_MS = 20000;
 
-async function call({ method, path, body, token, baseUrl, allowMissing = false }) {
+// 信封感知的通用调用器。**导出**是为了让 fileapi.js 复用同一套
+// 「HTTP 恒 200、成败看 code」的判定——两处各写一遍迟早分叉。
+export async function call({ method, path, body, token, baseUrl, allowMissing = false }) {
   const cfg = baseUrl ? { baseUrl, token } : await loadConfig();
   const url = cfg.baseUrl.replace(/\/$/, '') + path;
 

package/src/core/paths.js

@@ -8,11 +8,20 @@ export const APP_DIR = join(homedir(), '.nx-kv');
 export const STORE_PATH = join(APP_DIR, 'store.json');
 export const DEFAULT_PORT = 7877;
 
+// 附件的本地镜像根目录。**刻意放在 nx-kv 的用户目录下**（~/.nx-kv/attachments/）：
+// agent 读附件只认本地路径，放在项目目录里会随 cwd 漂移，还会被 git 捡走。
+export const ATTACHMENTS_DIR = join(APP_DIR, 'attachments');
+
 // 允许测试与多实例覆盖存储位置：NX_KV_STORE 环境变量优先
 export function storePathFromEnv() {
   return process.env.NX_KV_STORE || STORE_PATH;
 }
 
+// 允许测试与多实例覆盖附件目录：NX_KV_ATTACHMENTS 环境变量优先
+export function attachmentsRootFromEnv() {
+  return process.env.NX_KV_ATTACHMENTS || ATTACHMENTS_DIR;
+}
+
 // 名称安全校验：拒绝路径穿越（保留中文等合法命名，与 fileops.go 语义一致）。
 //
 // 用于「这个字符串会被用作**目录名**」的场景：skill 名、内置包名、适配器 id。

package/src/modules/file/index.js

@@ -0,0 +1,100 @@
+// 附件模块（= 后端图床的用户空间视图）。
+//
+// 不声明 `resource`：这里的「集合」是后端图床的投影，`upload/sync` 是它的动作，
+// 硬凑 get/update/remove 五动词只会得到语义别扭的命令。
+// 命令与路由仍然一一对应，所以「面板上能做的，CLI 都能做」依旧成立。
+import * as service from './service.js';
+
+// 所有动作都接受 --group 覆盖当前工作空间；默认取本机配置里的当前值
+const GROUP = { type: 'number', hint: '工作空间 id（默认取当前）' };
+
+export default {
+  id: 'file',
+  title: '附件',
+  order: 40,
+  // 没有独立面板：附件在「清单」页里被引用与预览，单独开一个 tab
+  // 会得到第二个「附件列表」，反而不知道以哪个为准。
+  view: null,
+
+  actions: [
+    {
+      id: 'file.list',
+      cli: ['file', 'list'],
+      http: ['GET', '/api/file'],
+      summary: '列出当前用户空间的附件（含本地已同步路径）',
+      flags: {
+        group: GROUP,
+        limit: { type: 'number', default: 100 },
+        offset: { type: 'number', default: 0 },
+      },
+      run: (ctx) => service.listFilesAction(ctx),
+      render: (d) => service.renderFileList(d),
+    },
+    {
+      id: 'file.upload',
+      cli: ['file', 'upload'],
+      http: ['POST', '/api/file'],
+      summary: '上传附件到当前用户空间（--path 本机文件；面板走 --content base64 --name 文件名）',
+      flags: {
+        path: { type: 'string', hint: '本机文件路径' },
+        content: { type: 'string', hint: 'base64 内容（面板上传用，可为 data URL）' },
+        name: { type: 'string', hint: '文件名（content 上传时必填）' },
+        contentType: { type: 'string', hint: '覆盖 Content-Type（默认按扩展名猜）' },
+        accessLevel: { type: 'string', enum: ['public', 'private', 'protected'], default: 'public', hint: '出图权限；public 才能被 <img> 直接预览' },
+        group: GROUP,
+      },
+      run: (ctx) => service.uploadFileAction(ctx),
+      render: (d) => service.renderUpload(d),
+    },
+    {
+      id: 'file.get',
+      cli: ['file', 'get'],
+      http: ['GET', '/api/file/item'],
+      summary: '查单个附件的元数据与本地路径',
+      args: ['fileId'],
+      flags: { group: GROUP },
+      run: (ctx) => service.getFileAction(ctx.fileId, { group: ctx.group }),
+      render: (d) => service.renderFileInfo(d),
+    },
+    {
+      id: 'file.remove',
+      cli: ['file', 'remove'],
+      http: ['DELETE', '/api/file/item'],
+      summary: '删除附件（后端软删；本地副本要清用 file sync --prune）',
+      args: ['fileId'],
+      flags: { group: GROUP },
+      run: (ctx) => service.removeFileAction(ctx.fileId, { group: ctx.group }),
+      render: (d) => service.renderRemove(d),
+    },
+    {
+      id: 'file.content',
+      // HTTP 侧直接透传文件本体（面板里 <img src="/api/file/content/<id>"> 预览）；
+      // CLI 侧只打印地址与本地路径 —— 终端吐二进制没有意义。
+      cli: ['file', 'content'],
+      http: ['GET', '/api/file/content/:fileId'],
+      stream: true,
+      summary: '取附件本体：面板内联预览；CLI 打印出图地址与本地路径',
+      args: ['fileId'],
+      flags: { group: GROUP },
+      run: (ctx) => (ctx.__raw
+        ? service.serveContent(ctx)
+        : service.getFileAction(ctx.fileId, { group: ctx.group })),
+      render: (d) => service.renderContent(d),
+    },
+    {
+      id: 'file.sync',
+      cli: ['file', 'sync'],
+      http: ['POST', '/api/file/sync'],
+      summary: '把附件同步到本机（默认全部；--ids 只同步指定附件）——为了不再依赖网络读附件',
+      flags: {
+        ids: { type: 'array', hint: '只同步这些 fileId（逗号分隔）' },
+        dir: { type: 'string', hint: '本地目录（默认 ~/.nx-kv/attachments/<工作空间>/）' },
+        prune: { type: 'boolean', hint: '删掉本地已不在后端的文件（仅全量同步时生效）' },
+        dryRun: { type: 'boolean', hint: '只列出将下载什么，不落盘' },
+        group: GROUP,
+      },
+      run: (ctx) => service.syncFilesAction(ctx),
+      render: (d) => service.renderSync(d),
+    },
+  ],
+};