nx-kv 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.17.0] - 2026-11-04 参考仓库/看板改独立弹窗 + 弹窗组件收敛 + 本地任务附件落本机仓
+
+### Added
+
+- **本地任务附件改走本机附件仓（任务 #15 验收反馈）**：面板编辑器贴图/选文件、
+  `localtask attach --path` 一律落 `~/.nx-kv/attachments/local/`（不发网，与云端
+  图床零关联）——修掉「云端不可达时界面看着有图、agent 领取却 `count: 0`」的
+  断链。领取标注本机仓优先（命中即给绝对路径，全命中零网络），云端清单（todo）
+  的附件链路保持不变。`file upload --local` 是本机仓的直入口；`/api/file/content`
+  本机仓优先、未命中再透传云端（面板预览离线可用）。
+- **简介「补充文档」支持分类标签 tag**（任务 #27）：同一份简介下的多篇补充文档
+  可以按标签分组，列表里按标签成段，不再靠标题前缀辨认。
+
+### Changed
+
+- **参考仓库、看板管理从页面内联区块搬进独立弹窗**（筛选器右侧的两个入口，
+  虚线框 + ↗ 与筛选 chip 区分）。它们都是「隔一阵来维护一次」的元信息，平铺在
+  页面上会把开发仓库主表顶到两屏之外；主表因此重新回到首屏。
+- 参考仓库弹窗用宽版（1180px）：多列表格在 880px 里会将「绑定」列挤成一团；
+  表格自己当滚动容器，表头 sticky；名字列允许任意位置折断（带点的长标识原本
+  会冲出去盖住远程地址列）。
+- **弹窗栈**：弹窗里再开弹窗（参考仓库 → 绑定 / 克隆）时，Esc 只关最上层；
+  导入导出全屏面板（z-30）在捕获阶段接管 Esc 并阻断，不会连带关掉下面的弹窗。
+- 参考表格与看板行的字号提一档（td 13px、行高与留白同步），与新主表一致。
+- **弹窗组件收敛（重构，界面行为不变）**：全站模态卡、确认/输入框、浮层菜单
+  收编到 `components/popup/`（Modal / useDialog / PopMenu / RowMenu / useDismiss），
+  轻提示收编到 `components/toast/`；此前散在各处的 `.dlg` / 两套互斥的 `.modal`
+  定义 / `.mdw-sheet` / `.gmenu` 全部合并为 `.pp-*` 一套。Esc、点外关闭、busy 禁关
+  从此只有一个实现，浏览器原生 `alert/confirm/prompt` 清零。
+
+### Fixed
+
+- **md 编辑器**：点中块时不再跳行高；占位符获得焦点即隐；标题上下留白统一
+  （任务 #31）。
+
 ## [0.16.0] - 2026-11-04 占位成员可救可清 + 仓库页可读性 + 前后端分层解耦
 
 ### Added

package/package.json

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

package/src/core/localatt.js

@@ -0,0 +1,137 @@
+// 本地附件仓：**本地任务**（localtask 队列）的贴图/文件原件，落在本机磁盘上。
+//
+// 口径（任务 #15 验收反馈 2026-11-04）：本地任务的贴图走本地存储，与云端图床
+// **零关联**——上传不碰网、预览不透传、agent 领取直接读本地路径。云端清单
+// （todo）的附件仍走云端图床（core/fileapi.js + core/attachstore.js 镜像），
+// 两条链路互不依赖；只有「正文引用的附件 id」是同一套语法（modules/todo/attach.js）。
+//
+// 目录：~/.nx-kv/attachments/local/（NX_KV_ATTACHMENTS 可改根目录；与各
+// 工作空间的数字目录天然不撞）。台账 manifest.json 形状与 attachstore 一致
+// （files: fileId → {name,size,contentType,…}），复用同一套读写函数。
+//
+// 正文引用语法不变：`![名](fileId)`，fileId 同样是 32 位 hex——面板/解析端
+// 不需要知道 id 背后是本地仓还是云端；读取时先查本地仓、未命中再走云端。
+import { randomBytes } from 'node:crypto';
+import fsp from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { createReadStream } from 'node:fs';
+import { dirname, join, parse as parsePath } from 'node:path';
+import { attachmentsRootFromEnv } from './paths.js';
+import { contentTypeOf } from './fileapi.js';
+import {
+  localNameFor,
+  readManifest as readMirrorManifest,
+  safeFileName,
+  writeManifest as writeMirrorManifest,
+} from './attachstore.js';
+
+export const LOCAL_STORE_DIRNAME = 'local';
+
+// 台账读写直接复用镜像那套（同形状：files 是 fileId → 记录）。groupId 字段
+// 对本地仓没有意义（readManifest 缺省补 0），写入时不带即可。
+const readManifest = (dir) => readMirrorManifest(dir);
+const writeManifest = (dir, data) => writeMirrorManifest(dir, data);
+
+/** 本地附件仓根目录（每个实例独立：NX_KV_ATTACHMENTS 覆盖根时测试天然隔离）。 */
+export function localDir() {
+  return join(attachmentsRootFromEnv(), LOCAL_STORE_DIRNAME);
+}
+
+const nowIso = () => new Date().toISOString();
+
+/**
+ * 新条目的 id：32 位 hex（16 字节随机）。与云端 fileId 同构——
+ * looksLikeFileId（modules/todo/attach.js）照常认，正文语法零分叉。
+ * 撞车概率 2^-128，先查本地仓再查云端的读取顺序天然消歧。
+ */
+function newFileId() {
+  return randomBytes(16).toString('hex');
+}
+
+// 同目录不重名的落点（`名字 (2).ext`）——台账是唯一真相源，文件名只是给人看的。
+function uniqueName(taken, 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;
+}
+
+/**
+ * 上传一个附件到本地仓：落盘 + 记台账，返回元数据。
+ * 不碰网络——本机 serve 进程内一次落盘即完成。
+ *
+ * @param {{name: string, buffer: Buffer, contentType?: string}} p
+ * @returns {Promise<{fileId: string, name: string, size: number, contentType: string, path: string, storage: 'local'}>}
+ */
+export async function localUpload({ name, buffer, contentType = '' } = {}) {
+  if (!Buffer.isBuffer(buffer) || !buffer.length) throw new Error('上传内容为空');
+  const base = safeFileName(name);
+  if (!base || base === 'file') throw new Error('上传需要文件名');
+  const dir = localDir();
+  const man = await readManifest(dir);
+  const id = newFileId();
+  // 落盘文件名人读优先（嵌入的说明文字一路跟过来），缺扩展名按 contentType 补
+  const fileName = uniqueName(
+    new Set(Object.values(man.files).map((r) => String(r?.name || ''))),
+    localNameFor(id, base, contentType || contentTypeOf(base))
+  );
+  const abs = join(dir, fileName);
+  await fsp.mkdir(dirname(abs), { recursive: true });
+  await fsp.writeFile(abs, buffer);
+  const ct = contentType || contentTypeOf(fileName);
+  man.files[id] = { name: fileName, size: buffer.length, contentType: ct, createdAt: nowIso() };
+  man.updatedAt = nowIso();
+  await writeManifest(dir, { ...man, dir });
+  return { fileId: id, name: fileName, size: buffer.length, contentType: ct, path: abs, storage: 'local' };
+}
+
+/** 台账 + 落盘文件都在 → 返回本地元数据；没传过或文件被手删 → null。 */
+export async function localResolve(fileId) {
+  const id = String(fileId ?? '').trim();
+  if (!id) return null;
+  const dir = localDir();
+  const man = await readManifest(dir);
+  const rec = man.files[id];
+  if (!rec || !rec.name) return null;
+  const abs = join(dir, String(rec.name));
+  if (!existsSync(abs)) return null;
+  return {
+    fileId: id,
+    path: abs,
+    name: String(rec.name),
+    size: Number(rec.size) || 0,
+    contentType: String(rec.contentType || ''),
+    storage: 'local',
+  };
+}
+
+/** 本地仓全部在盘条目（id → 元数据），供领取侧批量标注。 */
+export async function localIndex() {
+  const dir = localDir();
+  const man = await readManifest(dir);
+  const index = new Map();
+  for (const [id, rec] of Object.entries(man.files)) {
+    const abs = join(dir, String(rec?.name || ''));
+    if (rec?.name && existsSync(abs)) {
+      index.set(id, {
+        fileId: id,
+        path: abs,
+        name: String(rec.name),
+        size: Number(rec.size) || 0,
+        contentType: String(rec.contentType || ''),
+        storage: 'local',
+      });
+    }
+  }
+  return { dir, index };
+}
+
+/** 本地文件读流（HTTP 透传给面板 <img> 用）；调用方先 localResolve 确认在盘。 */
+export function localReadStream(absPath) {
+  return createReadStream(absPath);
+}

package/src/modules/docs/docref.js

@@ -50,6 +50,23 @@ export function sanitizeDocRef(raw) {
   }
 }
 
+/**
+ * DocRef + 链接级注解（note/tag）合成列表条目。
+ *
+ * 为什么收在 DocRef 模块：docLinks 条目 = DocRef + 注解，而注解要过三道关
+ * （写入口合并 / 读归一化回贴 / 导出保留），三处口径必须一致——
+ * 实现只此一份，docs/refs 与 repos/service、transfer 都从这里拿。
+ * 空串/缺省 = 不落字段（对已有条目即「清掉」）。
+ */
+export function withLinkMeta(ref, raw = {}) {
+  const note = typeof raw.note === 'string' ? raw.note.trim() : '';
+  const tag = typeof raw.tag === 'string' ? raw.tag.trim() : '';
+  const entry = { ...ref };
+  if (note) entry.note = note;
+  if (tag) entry.tag = tag;
+  return entry;
+}
+
 // ─── docId（前后端统一寻址）────────────────────────────────────────────
 //
 // 自有：rel:<相对路径>（裸相对路径视为自有——人类可以直接给路径）

package/src/modules/docs/index.js

@@ -207,7 +207,9 @@ const renderNoteRef = (d) =>
 const renderLink = (d) => {
   if (d.removed !== undefined) return `已移除组绑定: ${d.removed}（剩 ${d.count} 条）`;
   const lines = [`「${d.boardName}」的组绑定（${d.count} 条）:`];
-  for (const l of d.links) lines.push(`  ${l.rel ? 'rel:' + l.rel : 'path:' + l.path}${l.note ? `  · ${l.note}` : ''}`);
+  for (const l of d.links) {
+    lines.push(`  ${l.rel ? 'rel:' + l.rel : 'path:' + l.path}${l.tag ? `  [${l.tag}]` : ''}${l.note ? `  · ${l.note}` : ''}`);
+  }
   return lines.join('\n');
 };
 
@@ -331,11 +333,12 @@ export default {
       id: 'docs.link',
       cli: ['docs', 'link'],
       http: ['POST', '/api/docs/link'],
-      summary: '维护组的附加文档列表（--doc <自有路径|绝对路径> + --note；--remove <序号> 移除；--before <序号> 插位）',
+      summary: '维护组的附加文档列表（--doc <自有路径|绝对路径> + --note/--tag；--remove <序号> 移除；--before <序号> 插位；同 doc 重复添加 = 更新）',
       args: ['board'],
       flags: {
         doc: { type: 'string', hint: '自有树路径 = 自有文档；盘符/绝对路径 = 外部只读引用' },
         note: { type: 'string', hint: '条目说明' },
+        tag: { type: 'string', hint: '分类标签（如 qa；简介行渲染成小 chip；空串 = 清掉）' },
         remove: { type: 'number', hint: '移除第 N 条（1 起）' },
         before: { type: 'number', hint: '插到第 N 条之前（缺省追加到末尾）' },
       },

package/src/modules/docs/knowledge.js

@@ -125,8 +125,9 @@ export async function repoKnowledge(locator, { md = false } = {}) {
     const docLinks = [];
     const externalDirs = [];
     for (const l of Array.isArray(b.docLinks) ? b.docLinks : []) {
+      const meta = l.tag ? { tag: l.tag } : {};
       if (l.rel) {
-        docLinks.push({ note: l.note || '', ...(await readOwn(l.rel, { warnings, label: `组绑定·${l.rel}` })) });
+        docLinks.push({ note: l.note || '', ...meta, ...(await readOwn(l.rel, { warnings, label: `组绑定·${l.rel}` })) });
         continue;
       }
       const abs = l.path && store.resolveExternal(l.path, closure);
@@ -136,11 +137,11 @@ export async function repoKnowledge(locator, { md = false } = {}) {
       }
       const st = await import('node:fs/promises').then((m) => m.stat(abs).catch(() => null));
       if (!st) {
-        docLinks.push({ note: l.note || '', missing: true, docId: paths.extDocId(abs) });
+        docLinks.push({ note: l.note || '', ...meta, missing: true, docId: paths.extDocId(abs) });
       } else if (st.isDirectory()) {
-        externalDirs.push({ path: abs, note: l.note || '', files: await listDirMd(abs) });
+        externalDirs.push({ path: abs, note: l.note || '', ...meta, files: await listDirMd(abs) });
       } else {
-        docLinks.push({ note: l.note || '', ...(await readExternalDoc(abs, { warnings, label: `组绑定·${l.path}` })) });
+        docLinks.push({ note: l.note || '', ...meta, ...(await readExternalDoc(abs, { warnings, label: `组绑定·${l.path}` })) });
       }
     }
     boards.push({ name: b.name, key: bkey, intro: bIntro, note, docLinks, externalDirs });
@@ -250,16 +251,16 @@ export async function groupContextFor(cwd) {
       );
       peers.push({ name: mname, note: peerNote.body || (b.repoNotes || {})[mkey] || '' });
     }
-    // 组绑定参考文件（给可读路径——agent 直接读盘）
+    // 组绑定参考文件（给可读路径——agent 直接读盘）；tag 随条目走（有才带）
     const docLinks = [];
     for (const l of Array.isArray(b.docLinks) ? b.docLinks : []) {
       if (l.rel) {
-        docLinks.push({ rel: l.rel, abs: join(paths.docsRoot(), l.rel), note: l.note || '' });
+        docLinks.push({ rel: l.rel, abs: join(paths.docsRoot(), l.rel), note: l.note || '', ...(l.tag ? { tag: l.tag } : {}) });
         continue;
       }
       const abs = l.path && store.resolveExternal(l.path, closure);
       if (!abs) continue;
-      docLinks.push({ path: abs, abs, note: l.note || '' });
+      docLinks.push({ path: abs, abs, note: l.note || '', ...(l.tag ? { tag: l.tag } : {}) });
     }
     groups.push({
       name: b.name,

package/src/modules/docs/refs.js

@@ -10,6 +10,7 @@ import * as paths from './paths.js';
 import { normalizeKey } from '../../core/keys.js';
 import { reposBridge } from './repos-bridge.js';
 import { badInput, notFound, conflict } from '../../core/errors.js';
+import { withLinkMeta } from './docref.js';
 
 // 看板定位（id / key / 名称）：boardKeyOf 由 bridge 注入（key 口径必须与 repos 完全一致）
 function findBoardIn(s, idOrKey, { normalizeKey: nk, boardKeyOf }) {
@@ -95,10 +96,13 @@ export async function setNoteDocRef({ board, repo, rel, path, reset } = {}) {
  * 维护组的 docLinks。
  *   doc    --doc <rel|绝对路径>（盘符/绝对 → 外部，否则自有）
  *   note   条目说明
+ *   tag    分类标签（如 qa——简介行的补充链接会渲染成小 chip；传空串=清掉）
  *   remove --remove <序号>（1 起）
  *   before --before <序号>（插到该条之前；缺省追加）
+ *
+ * 同 rel/path 重复添加 = 更新该条（note/tag 以本次为准）——改标签就是重加一遍。
  */
-export async function setDocLink({ board, doc, note, remove, before } = {}) {
+export async function setDocLink({ board, doc, note, tag, remove, before } = {}) {
   if (!board) throw badInput('缺少看板（id / key / 名称）');
   const { mutateStore, boardKeyOf } = await reposBridge();
   return mutateStore((s) => {
@@ -124,7 +128,8 @@ export async function setDocLink({ board, doc, note, remove, before } = {}) {
         ? { path: String(doc).trim() }
         : { rel: String(doc || '') }
     );
-    const entry = note ? { ...ref, note: String(note).trim() } : ref;
+    // 条目 = DocRef + 注解（note/tag）；合成逻辑收在 docref.withLinkMeta
+    const entry = withLinkMeta(ref, { note, tag });
     const at = b.docLinks.findIndex((x) => (x.rel || '') === (entry.rel || '') && (x.path || '') === (entry.path || ''));
     if (at >= 0) b.docLinks.splice(at, 1);
     const want = before !== undefined ? idxOf(before) : -1;
@@ -162,18 +167,26 @@ export async function listRepoDocs(locator) {
   };
 }
 
-/** 往项目的介绍文档集里加一篇（rel / path / ref+rel 三选一） */
+/** 往项目的介绍文档集里加一篇（rel / path / ref+rel 三选一；note/tag 可选注解）。
+ *
+ * 同 rel/path 重复添加 = 更新该条（与组级 setDocLink 同一语义）——
+ * 此前是盲目 push：改个说明就得先 remove 再 add，还顺手丢掉 note
+ * （assertDocRef 只认 rel/path，注解要在这里显式贴回去）。
+ */
 export async function addRepoDoc(locator, raw) {
   const { getRepo, deriveKey, mutateStore } = await reposBridge();
   const repo = await getRepo(locator);
   const docRef = paths.assertDocRef(raw);
+  const entry = withLinkMeta(docRef, { note: raw && raw.note, tag: raw && raw.tag });
   return mutateStore((s) => {
     const r = s.repos.find((x) => deriveKey(x) === deriveKey(repo));
     if (!r) throw notFound('repo 不存在: ' + locator);
     if (!Array.isArray(r.docLinks)) r.docLinks = [];
-    r.docLinks.push(docRef);
+    const at = r.docLinks.findIndex((x) => (x.rel || '') === (entry.rel || '') && (x.path || '') === (entry.path || ''));
+    if (at >= 0) r.docLinks.splice(at, 1);
+    r.docLinks.push(entry);
     r.updatedAt = new Date().toISOString();
-    return { key: deriveKey(r), name: r.name, added: docRef, count: r.docLinks.length };
+    return { key: deriveKey(r), name: r.name, added: entry, count: r.docLinks.length };
   });
 }
 

package/src/modules/file/index.js

@@ -1,8 +1,11 @@
-// 附件模块（= 后端图床的用户空间视图）。
+// 附件模块（双后端：云端图床的用户空间视图 + 本机附件仓）。
 //
-// 不声明 `resource`：这里的「集合」是后端图床的投影，`upload/sync` 是它的动作，
-// 硬凑 get/update/remove 五动词只会得到语义别扭的命令。
+// 不声明 `resource`：这里的「集合」是附件存储的投影（云端图床 / 本机仓），
+// `upload/sync` 是它的动作，硬凑 get/update/remove 五动词只会得到语义别扭的命令。
 // 命令与路由仍然一一对应，所以「面板上能做的，CLI 都能做」依旧成立。
+//
+// 两条链路的分工（任务 #15 口径）：云端清单（todo）附件走图床；
+// 本地任务（localtask）贴图走 --local 本机仓——不碰网、零云端依赖。
 import * as service from './service.js';
 
 // 所有动作都接受 --group 覆盖当前工作空间；默认取本机配置里的当前值
@@ -33,13 +36,14 @@ export default {
       id: 'file.upload',
       cli: ['file', 'upload'],
       http: ['POST', '/api/file'],
-      summary: '上传附件到当前用户空间（--path 本机文件；面板走 --content base64 --name 文件名）',
+      summary: '上传附件（--local 存本机附件仓，本地任务贴图用；默认传当前用户空间的云端图床）',
       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> 直接预览' },
+        local: { type: 'boolean', hint: '存本机附件仓（~/.nx-kv/attachments/local/），不碰云端' },
+        accessLevel: { type: 'string', enum: ['public', 'private', 'protected'], default: 'public', hint: '出图权限；public 才能被 <img> 直接预览（--local 时无意义）' },
         group: GROUP,
       },
       run: (ctx) => service.uploadFileAction(ctx),

package/src/modules/file/service.js

@@ -1,8 +1,9 @@
-// 附件模块：用户空间里的图片 / 文档等二进制原件。
-//
-// 后端是 dev_ctr_hello 的图床（/api/v1/files*，上传 multipart，出图 /files/:fileId）。
-// 本模块只做「业务编排 + 人读渲染」，网络细节全在 core/fileapi.js，
-// 本地镜像细节全在 core/attachstore.js。
+// 附件模块：用户空间里的图片 / 文档等二进制原件，**双后端**：
+//   - 云端图床（dev_ctr_hello /api/v1/files*，上传 multipart，出图 /files/:fileId）
+//     —— 云端清单（todo）的附件走这边，本地镜像细节在 core/attachstore.js；
+//   - 本地附件仓（core/localatt.js）—— 本地任务（localtask）的贴图走这边，
+//     不碰网：上传落本机盘、预览读本机文件、agent 直接拿本地路径。
+// 本模块只做「业务编排 + 人读渲染」，网络细节全在 core/fileapi.js。
 //
 // 与 todo 的分工：附件**内容**归这里；附件**怎么被任务引用**归 todo
 // （任务正文里的 ![说明](fileId)，见 modules/todo/attach.js）。
@@ -16,6 +17,7 @@ import {
   accessUrlOf, contentTypeOf, deleteFile, fileInfo, fileUpload, isImageName, listFiles, openFileStream,
 } from '../../core/fileapi.js';
 import { localDirFor, localIndex, resolveLocal, syncAttachments } from '../../core/attachstore.js';
+import { localDir, localReadStream, localResolve, localUpload } from '../../core/localatt.js';
 
 const fmtBytes = (n) => {
   const v = Number(n) || 0;
@@ -65,8 +67,7 @@ export async function listFilesAction({ group, limit = 100, offset = 0 } = {}) {
 }
 
 export async function uploadFileAction(patch = {}) {
-  const { path: localPath, content, name, contentType, group, accessLevel = 'public' } = patch;
-  const gid = await resolveGroupId(group);
+  const { path: localPath, content, name, contentType, group, accessLevel = 'public', local: toLocal } = patch;
   let buffer;
   let fileName;
 
@@ -86,6 +87,26 @@ export async function uploadFileAction(patch = {}) {
     throw badInput('上传需要 --path <本机文件>，或 --content <base64> --name <文件名>');
   }
 
+  // 本地任务贴图 → 本地附件仓：不碰网、不解析工作空间（group 是云端图床的归属维度），
+  // 上传即已在本地，agent 直接读 localPath——这条链路与云端零关联。
+  if (toLocal) {
+    const rec = await localUpload({ name: fileName, buffer, contentType: contentType || contentTypeOf(fileName) });
+    return {
+      fileId: rec.fileId,
+      name: rec.name,
+      size: rec.size,
+      contentType: rec.contentType,
+      url: `/api/file/content/${rec.fileId}`,
+      isImage: isImageName(rec.name, rec.contentType),
+      localPath: rec.path,
+      localDir: localDir(),
+      storage: 'local',
+      markdown: snippetOf(rec.name, rec.fileId),
+    };
+  }
+
+  const cfg = await loadConfig();
+  const gid = await resolveGroupId(group);
   const meta = await fileUpload({
     name: fileName,
     buffer,
@@ -93,18 +114,33 @@ export async function uploadFileAction(patch = {}) {
     groupId: gid,
     accessLevel,
   });
-  const cfg = await loadConfig();
   return {
     ...meta,
     url: accessUrlOf(cfg.baseUrl, meta.fileId),
     isImage: isImageName(fileName, meta.contentType),
     localDir: localDirFor(gid, cfg.attachmentsDir),
+    storage: 'cloud',
     markdown: snippetOf(fileName, meta.fileId),
   };
 }
 
 export async function getFileAction(fileId, { group } = {}) {
   if (!fileId) throw badInput('缺少 fileId');
+  // 本地仓命中就不问云端：本地任务贴图的查询零网络、离线可用。
+  // 两套 id 同构（32 位 hex），先本地后云端的顺序天然消歧。
+  const hit = await localResolve(fileId);
+  if (hit) {
+    return {
+      fileId: hit.fileId,
+      name: hit.name,
+      size: hit.size,
+      contentType: hit.contentType,
+      url: `/api/file/content/${hit.fileId}`,
+      isImage: isImageName(hit.name, hit.contentType),
+      localPath: hit.path,
+      storage: 'local',
+    };
+  }
   const cfg = await loadConfig();
   const gid = await resolveGroupId(group);
   const meta = await fileInfo(fileId, gid);
@@ -115,6 +151,7 @@ export async function getFileAction(fileId, { group } = {}) {
     isImage: isImageName(meta.fileId, meta.contentType),
     localPath: local?.path || '',
     localName: local?.name || '',
+    storage: 'cloud',
   };
 }
 
@@ -138,10 +175,24 @@ export async function syncFilesAction({ group, ids, dir, prune, dryRun } = {}) {
   return { ...result, usedDir: localDirFor(gid, dir || cfg.attachmentsDir) };
 }
 
-/** HTTP 原始流：把后端的出图内容原样透给浏览器（面板里 <img src> 直接用）。 */
+/** HTTP 原始流：附件本体直接透给浏览器（面板里 <img src> 直接用）。
+ *  本地仓命中 → 读本机文件（离线可预览，本地任务贴图不依赖云端）；
+ *  未命中 → 云端出图原样透传（云端清单附件的老路径，行为不变）。 */
 export async function serveContent(ctx) {
   const { res } = ctx.__raw || {};
   if (!res) throw badInput('内部错误：缺少响应对象');
+  const hit = await localResolve(ctx.fileId);
+  if (hit) {
+    res.writeHead(200, { 'content-type': hit.contentType || 'application/octet-stream', 'cache-control': 'no-store' });
+    await new Promise((done, fail) => {
+      const rs = localReadStream(hit.path);
+      rs.once('error', fail);
+      res.once('close', done);
+      res.once('finish', done);
+      rs.pipe(res);
+    });
+    return;
+  }
   const up = await openFileStream(ctx.fileId);
   const ct = up.headers.get('content-type') || 'application/octet-stream';
   res.writeHead(200, { 'content-type': ct, 'cache-control': 'no-store' });
@@ -167,6 +218,14 @@ export function renderFileList(d) {
 }
 
 export function renderUpload(d) {
+  if (d.storage === 'local') {
+    return [
+      `已上传 ${d.fileId}（${fmtBytes(d.size)} · ${d.contentType}）→ 本机附件仓`,
+      `本地:   ${d.localPath}`,
+      `贴进任务正文（编辑时也可直接选图上传）:`,
+      `  ${d.isImage ? d.markdown.image : d.markdown.file}`,
+    ].join('\n');
+  }
   return [
     `已上传 ${d.fileId}（${fmtBytes(d.size)} · ${d.contentType}）`,
     `地址:   ${d.url}`,
@@ -177,6 +236,13 @@ export function renderUpload(d) {
 }
 
 export function renderFileInfo(d) {
+  if (d.storage === 'local') {
+    return [
+      `${d.fileId} · ${d.isImage ? '图片' : '文件'} · ${fmtBytes(d.size)} · ${d.contentType}`,
+      `地址:   ${d.url}`,
+      `本地:   ${d.localPath}（本机附件仓，不依赖云端）`,
+    ].join('\n');
+  }
   return [
     `${d.fileId} · ${d.isImage ? '图片' : '文件'} · ${fmtBytes(d.size)} · ${d.contentType}`,
     `地址:   ${d.url}`,

package/src/modules/localtask/index.js

@@ -355,21 +355,20 @@ export default {
             : ''),
     },
     {
-      // 附件追加（与云端 todo attach 同构）：上传/复用 fileId → markdown 嵌入正文末尾。
-      // 面板编辑器贴的是同一条语法（components/md/attachments.js），两端渲染一致。
+      // 附件追加（与云端 todo attach 同构）：--path 落**本机附件仓**（零云端）→ 嵌入正文末尾；
+      // --fileId 引用已有附件（本机仓 / 云端 id）。面板编辑器贴同一条语法（components/md/attachments.js）。
       id: 'localtask.attach',
       cli: ['localtask', 'attach'],
       http: ['POST', '/api/localtasks/attach'],
-      summary: '给任务追加附件：--path 上传本机文件，或 --fileId 追加已上传附件，以 markdown 嵌入正文末尾（不替换正文）',
+      summary: '给任务追加附件：--path 存本机附件仓（不碰云端），或 --fileId 引用已有附件，以 markdown 嵌入正文末尾（不替换正文）',
       flags: {
         id: { type: 'number', required: true, hint: '任务编号' },
         cwd: CWD,
         key: KEY,
-        path: { type: 'string', hint: '本机文件路径（先上传再嵌入）' },
-        fileId: { type: 'string', hint: '已上传附件的 id（32 位 hex，可带扩展名）' },
+        path: { type: 'string', hint: '本机文件路径（落 ~/.nx-kv/attachments/local/ 再嵌入）' },
+        fileId: { type: 'string', hint: '已有附件的 id（32 位 hex，可带扩展名；本机仓或云端）' },
         name: { type: 'string', hint: '嵌入文字与本地文件名（默认取原文件名）' },
         kind: { type: 'string', hint: 'image | file（不给按文件名/扩展名判）' },
-        accessLevel: { type: 'string', hint: 'public | private | protected（默认 public；仅 --path 上传时生效）' },
       },
       run: async (ctx) => {
         const { attachToTask } = await import('../tasktool/attach.js');
@@ -381,7 +380,6 @@ export default {
           fileId: ctx.fileId,
           name: ctx.name,
           kind: ctx.kind,
-          accessLevel: ctx.accessLevel,
         });
       },
       render: (d) =>

package/src/modules/repos/index.js

@@ -272,7 +272,7 @@ export default {
       args: ['id'],
       run: (ctx) => listRepoDocs(ctx.id),
       render: (d) => {
-        const one = (x, i) => `  ${i}. ${x.rel ? '自有 ' + x.rel : x.ref ? 'ref  ' + x.ref + '/' + x.rel : '外部 ' + x.path}${x.note ? '  #' + x.note : ''}`;
+        const one = (x, i) => `  ${i}. ${x.rel ? '自有 ' + x.rel : x.ref ? 'ref  ' + x.ref + '/' + x.rel : '外部 ' + x.path}${x.tag ? `  [${x.tag}]` : ''}${x.note ? `  # ${x.note}` : ''}`;
         const lines = [`【${d.repo.name}】介绍文档 ${d.count} 篇`];
         if (d.main) lines.push(one(d.main, 1));
         d.links.forEach((x, i) => lines.push(one(x, i + 2)));
@@ -283,7 +283,7 @@ export default {
       id: 'repo.doc.add',
       cli: ['repo', 'doc', 'add'],
       http: ['POST', '/api/repos/docs'],
-      summary: '给项目加一篇介绍文档：--rel 自有树路径 / --path 外部绝对路径 / --ref <参考仓库key> --file <仓库内相对路径>',
+      summary: '给项目加一篇介绍文档：--rel 自有树路径 / --path 外部绝对路径 / --ref <参考仓库key> --file <仓库内相对路径>（同 rel/path 重复添加 = 更新）',
       args: ['id'],
       flags: {
         rel: { type: 'string', hint: '自有树内相对路径（如 repo/github.com/me/x.md）' },
@@ -291,8 +291,9 @@ export default {
         ref: { type: 'string', hint: '参考仓库 key（type=ref 的本机仓库）' },
         file: { type: 'string', hint: '参考仓库内的相对路径（配合 --ref）' },
         note: { type: 'string', hint: '这篇的说明' },
+        tag: { type: 'string', hint: '分类标签（如 qa；简介行渲染成小 chip；空串 = 清掉）' },
       },
-      run: (ctx) => addRepoDoc(ctx.id, { rel: ctx.rel, path: ctx.path, ref: ctx.ref, file: ctx.file, note: ctx.note }),
+      run: (ctx) => addRepoDoc(ctx.id, { rel: ctx.rel, path: ctx.path, ref: ctx.ref, file: ctx.file, note: ctx.note, tag: ctx.tag }),
       render: (d) => `已加一篇介绍文档（共 ${d.count} 篇）`,
     },
     {
@@ -612,7 +613,7 @@ export default {
           lines.push(`  ◇ 组「${b.name}」`);
           if (b.intro && !b.intro.missing) lines.push(`    组介绍: ${b.intro.docId}`);
           if (b.note && !b.note.missing) lines.push(`    组内描述: ${b.note.docId}`);
-          for (const l of b.docLinks) lines.push(`    绑定: ${l.docId}${l.note ? `  · ${l.note}` : ''}${l.missing ? '（缺失）' : ''}`);
+          for (const l of b.docLinks) lines.push(`    绑定: ${l.docId}${l.tag ? `  [${l.tag}]` : ''}${l.note ? `  · ${l.note}` : ''}${l.missing ? '（缺失）' : ''}`);
           for (const x of b.externalDirs) lines.push(`    外部目录: ${x.path}（${x.files.length} 个文档，按需读盘）`);
         }
         if (d.refs.length) {

package/src/modules/repos/service.js

@@ -14,7 +14,7 @@ import fsp from 'node:fs/promises';
 import { APP_DIR } from '../../core/paths.js';
 import { openPath } from '../../core/open.js';
 import { badInput, notFound, conflict } from '../../core/errors.js';
-import { sanitizeDocRef } from '../docs/docref.js';
+import { sanitizeDocRef, withLinkMeta } from '../docs/docref.js';
 import { sanitizeGetLoop } from '../tasktool/getloop.js';
 
 // ─── 存储（NX_KV_REPOS_STORE 可覆盖；测试隔离）──────────────────────────
@@ -94,8 +94,7 @@ function normalizeDocRefs(store) {
       .map((l) => {
         const d = sanitizeDocRef(l);
         if (!d) return null;
-        const note = l && typeof l.note === 'string' ? l.note.trim() : '';
-        return note ? { ...d, note } : d;
+        return withLinkMeta(d, l);
       })
       .filter(Boolean);
     if (links.length) r.docLinks = links;
@@ -109,8 +108,7 @@ function normalizeDocRefs(store) {
       .map((l) => {
         const d = sanitizeDocRef(l);
         if (!d) return null;
-        const note = l && typeof l.note === 'string' ? l.note.trim() : '';
-        return note ? { ...d, note } : d;
+        return withLinkMeta(d, l);
       })
       .filter(Boolean);
     if (links.length) b.docLinks = links;