nx-kv 0.8.5 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,82 @@
 
 本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.9.0] - 2026-10-16
+
+### Added
+
+- **任务附件：正文里用标准 markdown 嵌图片与文档，并可同步到本地给 agent 直接读。**
+
+  - **嵌入语法就是标准 markdown**，不发明新方言（解析实现只有一处：
+    `src/modules/todo/attach.js`，Node 与浏览器共用）：
+    `![说明](fileId)` 图片（面板内联预览）、`[文件名](fileId)` 其他文件（docx/pdf…）。
+    `fileId` 是后端图床的不透明 id（32 位 hex，原文件名带后缀时结尾接 `.<ext>`）。
+    **判定刻意收窄**：URL（含 `://`）、站点路径（`/…`）、相对路径（`./…`）一律按
+    普通 markdown 原样保留 —— 否则任务里写条普通链接就会被当成附件，
+    然后预览 404、同步白跑一趟网络。
+  - **新模块 `file`**：`file upload / list / get / remove / content / sync`。
+    上传走后端 multipart（`POST /api/v1/files`，字段名 `file`）；`file content` 在
+    HTTP 侧把后端出图内容原样透传（面板 `<img src="/api/file/content/<id>">` 用），
+    CLI 侧只打印地址与本地路径。
+  - **`file sync`：把附件同步到本机** —— 存在的唯一理由是让 agent **读本地文件而不是读网**。
+    默认落到 `~/.nx-kv/attachments/<groupId|default>/`（`NX_KV_ATTACHMENTS` 可改根目录），
+    同目录 `manifest.json` 记「fileId → 本地文件名 + 大小」，所以二次同步跳过未变更的。
+    本地文件名优先取正文里的说明文字（`![设计稿.png](id)` → `设计稿.png`），否则退回
+    fileId 并按 Content-Type 补扩展名（没有扩展名，Windows 上双击打不开）。
+    `--ids` 只同步指定附件；`--prune` 清理本地已不在后端的（**仅在全量同步时生效**——
+    带 `--ids` 再 prune 会把没列出来的附件一起删掉）；`--dryRun` 只列不落盘。
+  - **`todo attach` / `todo attachments`**：把附件**追加**到任务正文；列出某条任务
+    引用了哪些附件、本地是否已有。`todo attach` 会拒绝不像 fileId 的值（比如 URL）。
+    ⚠️ 追加会改写正文，而定位按正文内容（`--ref`）—— 连续操作要用**新的** text。
+  - **新模块 `setting` + 面板开关：「读任务时自动下载附件」。**
+    `nx-kv setting get` / `nx-kv setting set --autoSyncAttachments[=false]`
+    （面板在「清单」页工具栏）。开启后 `todo list` / `todo get` 会同步正文引用的附件，
+    给每个任务附加 `attachments[]`（`id / kind / name / localPath / synced`，
+    **localPath 是本地绝对路径**），并用 `attachmentsSync` 汇报这一轮
+    `downloaded / skipped / failures`。**下载失败不阻断读取** —— 附件拿不到与
+    清单读不到是两件事，失败如实进 `failures`，本地已有旧版本时继续用它。
+    默认**关**：开启意味着每次 list/get 都触网，对「只想看一眼清单」是纯负担。
+  - **`attachments` 标注与开关无关**：关掉开关后不再同步，但「这条任务挂了附件」
+    仍会出现在 `attachments[]` 里（`localPath` 反映本地已有则给路径）。
+  - 前端：`todo` 的编辑从单行 dialog 换成完整编辑器弹窗（`editor.jsx`）——
+    **粘贴（Ctrl+V）/ 拖入 / 选择文件** 三条路都能上传，自动插到光标处、实时预览；
+    列表里图片以缩略图内联、其他文件显示为可点附件（`markdown.jsx`）。
+    - **Ctrl+V 直接粘截图**是主路径：截图工具不给文件名，`upload.js` 会替它起
+      `粘贴图片-<时间戳>.png`（这个名字会一路用下去：正文说明文字 + 落盘文件名，
+      退化成 `image.png` 就再也认不出是哪张）。一次粘多张带序号，不重名。
+    - 拖拽挂在 **window** 上而不是编辑区上：往弹窗里丢文件、落点差一点也该接住，
+      而不是让浏览器把文件打开；只在拖**文件**时介入（拖选中的文字不弹提示）。
+    - 批量上传**先收齐再一次性插入** —— 边传边插会跟光标位置打架
+      （插入后 DOM 里光标还没更新，第二个附件会算错落点、变成倒序）。
+    - 纯文本粘贴不拦截，交给浏览器默认行为插到光标处。
+    - 快捷键 <kbd>Ctrl</kbd>+<kbd>Enter</kbd> 保存；字符计数与插入语法提示常驻。
+  - 「快速新增」那一栏也能 Ctrl+V 贴图：贴张截图再回车，任务与附件一次成型。
+  - 「附件自动下载」做成胶囊开关（面板「清单」页），悬停显示附件会落到哪个目录。
+  - `core/fileapi.js`（后端文件客户端，与 kvapi 共用同一套信封判定）、
+    `core/attachstore.js`（本地镜像与台账）、`core/config.resolveGroupId`
+    （模块间共享的 group 回落规则 —— todo 读 KV 与 file 选分组/本地目录必须同一条，
+    否则会出现「任务读 A 组、附件同步 B 组」这种不报错的错位）。
+  - 本机服务的请求体上限 4MB → 24MB：面板上传走 base64 JSON（膨胀 ~33%），
+    10MB 的图会变成 ~13MB 的请求体。
+
+### Changed
+
+- `core/kvapi.js` 的 `call` 改为导出，供 `core/fileapi.js` 复用（两处各写一遍
+  信封判定迟早分叉）。
+- `todo list` / `todo get` 的每个任务可能多出 `attachments[]`；开启自动下载时
+  顶层多出 `attachmentsSync`。未开启时**没有** `attachmentsSync`，其余字段与旧版一致。
+
+### Tests
+
+- `tests/fake-backend.mjs` 增加文件端点，并**手写 multipart 解析** ——
+  用 JSON 假装上传就测不出「boundary 丢了」「字段名写错」。
+  假后端刻意**不返回 originalName**，与真实后端一致：本地文件名只能自己解决。
+- `tests/smoke.mjs` 新增 25 项：上传（图片/docx）、list/get/remove、content 直出字节、
+  嵌入追加、`file sync` 落盘与二次跳过、开关打开后读任务自动下载并回传全路径、
+  关掉后不再同步但标注仍在、非法 fileId 被拒。
+- `tests/unit/attach.test.mjs` 新增 9 项：嵌入解析的边界（普通链接不许被误判、
+  去重保序、说明文字取首次出现、往返一致）。
+
 ## [0.8.5] - 2026-10-13
 
 ### Added

package/README.md

@@ -6,6 +6,10 @@ KV 清单（todo）管理中枢。一个 `npx` 命令起一个 Web 面板，同
 对接 GoFrame KV 后端（默认 `http://47.110.80.47:8988`），
 数据落在**四把 key** 上：`todo:open` / `todo:done` / `todo:freeze` / `todo:topics`。
 
+任务正文还能直接**嵌图片与文档**（标准 markdown：`![说明](fileId)` / `[文件名](fileId)`）——
+附件存在后端图床的同一用户空间里，既能同步到本地给 agent 直接读（`nx-kv file sync`），
+也能在读任务时自动下载并把本地绝对路径一并交出去。
+
 ## 快速开始
 
 ```bash
@@ -66,6 +70,47 @@ nx-kv group members 24                        # 成员
 完整命令表由 action 声明自动生成：`nx-kv help`。
 命令与 HTTP 端点互相可查：`nx-kv routes`，反查用 `nx-kv routes --http "POST /api/todo"`。
 
+## 附件（图片 / 文档）
+
+任务正文直接用**标准 markdown** 引用附件，附件本体存在后端图床的同一用户空间里：
+
+```
+修一下首页 logo  ![设计稿](3f2a1b…9c)      # 图片：面板内联预览
+补充材料见 [需求说明.docx](b71e…04.docx)    # 其他文件：点开即下载/预览
+```
+
+括号里是后端返回的 `fileId`（32 位 hex，原文件名带后缀时会接 `.<ext>`）。
+URL 与相对路径不算附件，按普通 markdown 原样保留（不会误判）。
+
+```bash
+nx-kv file upload --path "D:\设计\首页.png"   # 上传到当前用户空间
+nx-kv todo attach --ref "修一下首页 logo" --path "D:\设计\首页.png"  # 上传并嵌进正文
+nx-kv todo attachments --ref "修一下首页 logo"   # 这条任务引用了哪些附件
+
+nx-kv file sync            # 把附件同步到 ~/.nx-kv/attachments/<工作空间>/
+nx-kv file sync --ids a,b  # 只同步指定附件
+nx-kv file sync --prune    # 顺带清掉本地已不在后端的（仅全量同步时生效）
+```
+
+面板里编辑任务时，**Ctrl+V 直接粘截图**、把文件拖进来、或点「选择文件」——
+都会自动上传并插到光标处，右侧实时预览；列表里图片显示为缩略图、其他文件是可点附件。
+「快速新增」那一栏也支持粘贴图片。
+
+**给 agent 的关键开关**：开启「读任务时自动下载」后，`todo list` / `todo get`
+的每个任务会多出 `attachments[]`，里面是**本地绝对路径**，另有 `attachmentsSync`
+汇报下载/跳过/失败。读本地文件因此不再受网络与跨域影响：
+
+```bash
+nx-kv setting set --autoSyncAttachments        # 开
+nx-kv setting set --autoSyncAttachments=false  # 关（默认）
+```
+
+面板里对应「清单」页工具栏的「附件自动下载」勾选。本地文件名优先取正文里的说明文字
+（`![设计稿.png](id)` → `设计稿.png`），否则退回 fileId 并补上扩展名；
+同目录 `manifest.json` 记「fileId → 文件名 + 大小」，所以二次同步会跳过未变更的。
+
+单独的命令参考见 `nx-kv help file` 与 skill 的 `todo-commands`。
+
 ## 本地任务（localtask，不需登录）
 
 本机任务队列，按**工作目录**划分（目录名即主题）：提交（`add`）、领取（`wait`）、
@@ -156,8 +201,8 @@ nx-kv todo get --ref "旧记录" --topic fr   # 或按主题收窄
 所以「Web 上能做的，CLI 都能做」是结构保证而非口头约定。
 
 ```
-src/core/          零业务语义：kvapi(后端客户端) / config(本机配置) / errors / fstree
-src/modules/       功能域：system / auth / group / localtask / todo / bundled
+src/core/          零业务语义：kvapi / fileapi（后端客户端） / attachstore（附件本地镜像） / config / errors / fstree
+src/modules/       功能域：system / setting / auth / group / localtask / todo / file / bundled
 src/runtime/       装配层：registry / spec / cli / api / server
 src/web/frontend/  React 壳
 assets/nx-kv/            内置 skill：KV 清单操作手册（远程）

package/assets/nx-kv/SKILL.md

@@ -17,6 +17,7 @@ KV 清单（todo）的操作入口。四把 key 上的任务管理，对接 GoFr
 | --- | --- |
 | **领任务 / 收单**：按主题拉待办 → 读上下文 → 与用户对齐意图 → 完成后回填 | [[agent-workflow]] |
 | **查命令**：要敲哪条、退出码、数据结构、避坑 | [[todo-commands]] |
+| **任务带附件**：正文里的图片 / docx 怎么读、怎么落到本地 | 本页「附件」一节 + [[todo-commands]] |
 
 两份都是按需加载，不要一开始就全读进来。
 
@@ -55,6 +56,53 @@ nx-kv todo done --ref "<任务内容>" --result "改了什么 / 关键决策 /
 `--status open --topic` 是「只要待办」。收单用后者（省上下文），
 做统计/核对/回顾用前者。
 
+## 附件：正文里的图片与文档（读本地，不读网）
+
+任务**正文本身**就能带附件——用标准 markdown 写，不发明新语法：
+
+```
+修一下首页 logo  ![设计稿](3f2a1b…9c)       ← 图片，面板里内联预览
+补充材料见 [需求说明.docx](b71e…04.docx)     ← 其他文件，点开即下载/预览
+```
+
+`( )` 里是**后端图床的 fileId**（32 位 hex，原文件名带后缀时结尾会接 `.<ext>`）。
+除此之外的 markdown 链接（`http(s)://`、`./x.md`）一律按普通链接处理，不会被当成附件。
+
+```bash
+nx-kv todo attachments --ref "<任务内容>" --json   # 这条任务引用了哪些附件（含本地路径）
+nx-kv todo attach --ref "<任务内容>" --path <本机文件>       # 上传并追加到正文
+nx-kv todo attach --ref "<任务内容>" --fileId <fileId>       # 追加一个已上传的附件
+```
+
+**给要读附件的 agent：先把附件落到本地，再读本地文件。**
+
+```bash
+nx-kv file sync --json      # 同步当前工作空间的附件 → ~/.nx-kv/attachments/<工作空间>/
+```
+
+**更省事的做法是打开「读任务时自动下载」**（面板「清单」页的开关，或 CLI 一条命令）：
+
+```bash
+nx-kv setting set --autoSyncAttachments        # 开
+nx-kv setting set --autoSyncAttachments=false  # 关（默认）
+```
+
+开启后，`todo list` / `todo get` 的每个任务会多出 `attachments[]`，
+里面直接给出**本地绝对路径**（`localPath`），另有 `attachmentsSync` 汇报这一轮
+下载了什么、跳过什么、失败什么：
+
+```json
+{ "id": "3f2a…9c", "kind": "image", "name": "设计稿.png",
+  "localPath": "C:\\Users\\me\\.nx-kv\\attachments\\24\\设计稿.png", "synced": true }
+```
+
+于是 agent 只要 `Read` 那个路径就行——不必拼出图 URL、不受网络和跨域影响。
+下载失败**不会**让清单读不出来：附件拿不到与任务读不到是两件事，
+失败项如实出现在 `attachmentsSync.failures` 里。
+
+> ⚠️ 追加附件会**改写正文**，而定位是按正文内容（`--ref`）——
+> 同一条任务连续操作时，要用**新的** text 去 `--ref`。
+
 ## ⚠️ 定位一律按内容，不按 id（最容易改错数据的地方）
 
 待办的 id **非常容易重复**，两条独立的原因：

package/assets/nx-kv/references/todo-commands.md

@@ -92,6 +92,55 @@ nx-kv group current
 nx-kv group use <id|name|default>     # 别名：group switch
 ```
 
+## 附件（图片 / 文档）
+
+| 操作 | 命令 | 路由 |
+| --- | --- | --- |
+| 传附件 | `nx-kv file upload --path <本机文件>` | `POST /api/file` |
+| 列附件 | `nx-kv file list [--limit N]` | `GET /api/file` |
+| 查单个 | `nx-kv file get <fileId>` | `GET /api/file/item` |
+| 出图/下载 | `nx-kv file content <fileId>` | `GET /api/file/content/:fileId`（HTTP 直出字节） |
+| 删附件 | `nx-kv file remove <fileId>` | `DELETE /api/file/item` |
+| **同步到本地** | `nx-kv file sync [--ids a,b] [--dir D] [--prune] [--dryRun]` | `POST /api/file/sync` |
+| 给任务挂附件 | `nx-kv todo attach --ref <内容> --path <本机文件>` | `POST /api/todo/attach` |
+| 看任务挂了什么 | `nx-kv todo attachments --ref <内容>` | `GET /api/todo/attachments` |
+| 读/改设置 | `nx-kv setting get` / `nx-kv setting set --autoSyncAttachments` | `GET|POST /api/setting` |
+
+**正文里的嵌入语法**（标准 markdown，不发明方言）：
+
+```
+![说明](fileId)      图片：面板里内联预览
+[文件名](fileId)      其他文件（docx/pdf/…）：点开即下载/预览
+```
+
+`fileId` 是后端图床的不透明 id：32 位 hex，原文件名带扩展名时结尾接 `.<ext>`
+（如 `3f2a…9c.docx`）。URL（含 `://`）与相对路径（`./x.md`、`/files/x`）**不算附件**，
+一律按普通 markdown 原样保留。
+
+**本地镜像**：默认落到 `~/.nx-kv/attachments/<groupId|default>/`，同目录的
+`manifest.json` 记「fileId → 本地文件名 + 大小」，所以二次同步会跳过未变更的
+（不会每次重下）。文件名优先用正文里的**说明文字**（`![设计稿.png](id)` → `设计稿.png`），
+没有说明文字时退回 fileId 并补上扩展名。
+
+```bash
+# 读任务时自动下载：开启后 todo list / get 会带回本地绝对路径
+nx-kv setting set --autoSyncAttachments
+nx-kv todo get --ref "<任务内容>" --json
+# → 任务对象多出 attachments[]（id / kind / name / localPath / synced）
+#   + attachmentsSync（dir / downloaded / skipped / failures）
+
+# 手动同步（不依赖开关）
+nx-kv file sync --json            # 全部附件
+nx-kv file sync --ids <id1>,<id2> # 只同步指定附件（读任务时按引用同步走的就是这条）
+nx-kv file sync --prune           # 额外删掉本地已不在后端的文件（仅全量同步时生效）
+```
+
+`file sync --prune` 在带 `--ids` 时**刻意不生效**：过滤出几个 id 再 prune，
+会把没列出来的附件一起删掉。
+
+删除附件的语义：`file remove` 只删后端记录（软删），本地已同步的副本会留着；
+要连本地一起清，用 `file sync --prune`。
+
 ## ⚠️ 定位按内容（--ref），不按 id
 
 ```jsonc
@@ -215,3 +264,6 @@ nx-kv todo list --status open --topic bug    # bug 消费者
 | 未登录就调 todo | exit 1「未登录」 | 先 `auth login` |
 | 以为切换 group 会改服务端 | 只改本机配置 | 数据一直在服务端，切换只是换个 groupId |
 | 领取待办时用了全量 `list` | done 的历史 + 长 note 白占上下文 | 一律 `--status open --topic <t>` |
+| `todo attach` 之后还用**旧的** `--ref` | 报「不存在」——正文已被追加改写 | 用返回的 `task.text`（新正文）继续操作 |
+| 把附件当成「读了就行」的东西 | agent 拿 `<img>` URL 去请求，受网络/跨域影响 | 先 `file sync`（或开 `--autoSyncAttachments`），读 `localPath` |
+| 拿图片地址手拼 / 存进正文 | 换后端地址就全失效 | 正文只写 `fileId`（`![说明](fileId)`），地址由客户端拼 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nx-kv",
-  "version": "0.8.5",
+  "version": "0.9.0",
   "description": "nx-kv — KV 清单管理中枢（远程）+ 本机本地任务队列（localtask）：serve 驱动 CLI 与 Web 面板，同源同构，附带可安装 skill 供 agent 提交 / 领取 / 阻塞接收任务",
   "type": "module",
   "bin": {

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);
+}