nx-kv 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -2,6 +2,87 @@
 
 本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.18.0] - 2026-11-04 描述绑定文档 + 描述弹窗
+
+### Changed
+
+- **描述全部改成绑定的文档，不再是字符串**。三层描述（仓库 / 看板 / 组内成员）以前
+  各存一份字符串字段（`repo.desc`、`board.desc`、`board.repoNotes[key]`），现在正文
+  一律在自有文档树里，字符串降级为「派生摘要」：
+
+  | 描述 | 文档位置 |
+  |---|---|
+  | 仓库（项目） | `repo/<key>/index.md`（主篇）+ `docLinks` 补充篇 |
+  | 看板（领域） | `board/<组>.md` |
+  | 组内成员 | `group/<组>/<key>.md` |
+
+- **写入入口全改为文档**：`repo add --desc` 变成「初始正文 → 写进主篇」；
+  `repo update --desc` / `board update --desc` 直接报错并指向 `docs set` / `docs bind`；
+  `board note --note` 写 `group/<组>/<key>.md` 再回写摘要。`desc` 字段只在保存文档时
+  由 `docs` 单向回写，不再是第三个真相源。
+- **仓库列表的描述列显示文档**：读主篇正文的首段（两行截断），点一下直接开文档页签；
+  没写过时显示「未写」，点了就地新建。补充篇的数量以 `+N` 挂在后面。
+- **编辑仓库弹窗**去掉「一句话描述」输入框，改成「项目描述（文档）」一行（显示主篇、
+  点击即开）。看板弹窗同理：编辑时只显示文档入口，新建时给的那段仍作为初始正文。
+- **「描述」按钮改为弹窗：左清单 + 右 md 编辑器**。以前点它直接跳文档页签——为了
+  改两个字把整页换掉，看板筛选与滚动位置一起丢。现在弹窗左栏列这个仓库的全部描述
+  文档（组内描述 / 项目主篇 / 补充篇，各带一行摘要与「未写」标记），右栏是 md 编辑器
+  （实时预览 / 源码 / 阅读三态，Ctrl+S 或按钮保存）。切换条目与关窗都先把未保存的
+  改动落盘；右上「↗ 页签」保留（读全文、点双链跳转）。
+- 存量数据用 `docs seed --apply` 一次性迁移（字符串 → 约定路径的 md，幂等；
+  实测本机 58 份：40 项目 + 17 组内 + 1 组介绍）。
+- **仓库页头部只留可操作的东西**：删掉标题下那段「开发仓库是你在写的 / 参考仓库是
+  clone 下来读的 / 看板只是分组」的说明段落，以及紧随其后的三条图例
+  （`开发仓库 · 本机路径，不碰 git` 一类）。这两块纯解释性文字占了首屏近 100px，
+  把它们去掉后表格从第 130px 开始、首屏多出两行仓库。参考仓库与看板弹窗头部的
+  说明文字同样删掉，弹窗第一行直接是操作按钮（克隆 / 同步 / 检查 / 导入导出 /
+  存储根），按钮从行首排起而不是被挤到右侧。想解释的留在按钮 `title` 里。
+
+### Added
+
+- `GET /api/repos` 每条记录多一个 `descDocs`：主篇（docId / 标题 / 摘要 / rel / 是否
+  已写）+ 补充篇列表，列表页不用再自己拼路径。
+
+### Fixed
+
+- **文档阅读态标题重复**：正文自带 `# 标题` 时不再额外渲染外层题头。此前同一行字
+  在阅读态会出现两次（标题 + 正文 h1），看着像渲染坏了。
+
+## [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.18.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/brief.js

@@ -0,0 +1,84 @@
+// 「描述即文档」：把一个所有者（repo / board）的绑定文档集整理成短视图。
+//
+// 为什么单开一个文件：列表接口（repos list / board 投影）要给前端「这个项目的描述
+// 是哪几篇 md」——主篇标题 + 补充篇数量。这活儿既要读盘（取标题）、又要按约定路径
+// 推导（没绑过 doc 的项目也要能显示默认主篇），但**不能**把整棵树读一遍：
+// 列表里只有主篇需要标题，补充篇给 rel 名就够（点开才读正文）。
+//
+// 依赖方向：docs 是叶子，repos/service 反向依赖它（它已经 import 了 docs/paths）。
+// 这里要 deriveKey 所以走 reposBridge 动态拿，静态 import 会成环。
+import * as paths from './paths.js';
+import * as store from './store.js';
+import { summaryFromMd } from './seed.js';
+
+const TITLE_RE = /^#\s+(.+)$/m;
+
+const baseNameOf = (p) => String(p || '').replace(/\\/g, '/').split('/').pop().replace(/\.md$/i, '');
+
+/** DocRef → docId（与前端 openByDocId 同一口径：rel: / path: 前缀） */
+export function refToDocId(ref) {
+  if (!ref) return '';
+  if (ref.rel) return 'rel:' + ref.rel;
+  if (ref.path) return 'path:' + ref.path;
+  return '';
+}
+
+/** 约定主篇路径（没显式绑 doc 时的默认位置） */
+export function defaultMainRel(owner, kind) {
+  if (kind === 'board') return paths.boardDocRel(owner.name);
+  const key = owner.key || owner.repoKey || '';
+  return key ? paths.repoDocRel(key) : '';
+}
+
+/**
+ * 主篇的展示元信息：标题 + 摘要（正文首个非标题行，与 seed 同一口径）。
+ * 文件还没写过时标题退回**仓库/看板名**（key 末段往往是 remote 的仓库名，
+ * 跟用户认知里的项目名对不上），摘要空着，由前端显示「未写」。
+ */
+async function mainMeta(ref, fallbackRel, ownerName) {
+  // 没显式绑 doc 的项目只有约定路径——那种情况**也要读**，
+  // 否则迁过来的主篇永远显示不出摘要（doc 字段为空 ≠ 文档不存在）。
+  const rel = (ref && ref.rel) || fallbackRel;
+  if (rel) {
+    try {
+      const body = await store.readOwnDoc(rel);
+      const t = TITLE_RE.exec(body);
+      return {
+        title: (t && t[1].trim()) || ownerName || baseNameOf(rel),
+        summary: summaryFromMd(body),
+      };
+    } catch { /* 还没落盘 */ }
+    return { title: ownerName || baseNameOf(rel), summary: '' };
+  }
+  if (ref && ref.path) return { title: baseNameOf(ref.path), summary: '' };
+  return { title: ownerName || '', summary: '' };
+}
+
+/**
+ * 文档集短视图。
+ * @param {object} owner repo 或 board 记录
+ * @param {'repo'|'board'} kind
+ * @returns {Promise<{main:{docId,title,rel,path,exists},links:Array<{docId,title,note,tag}>,count:number}>}
+ */
+export async function docSetOf(owner, kind) {
+  if (!owner) return { main: null, links: [], count: 0 };
+  const mainRef = owner.doc && (owner.doc.rel || owner.doc.path) ? owner.doc : null;
+  const rel = (mainRef && mainRef.rel) || defaultMainRel(owner, kind);
+  const exists = !!(rel && (await store.ownDocExists(rel))) || !!(mainRef && mainRef.path);
+  const meta = await mainMeta(mainRef, rel, owner.name || '');
+  const main = {
+    docId: mainRef ? refToDocId(mainRef) : rel ? 'rel:' + rel : '',
+    title: meta.title,
+    summary: meta.summary,
+    rel: (mainRef && mainRef.rel) || rel,
+    path: (mainRef && mainRef.path) || '',
+    exists,
+  };
+  const links = (Array.isArray(owner.docLinks) ? owner.docLinks : []).map((l) => ({
+    docId: refToDocId(l),
+    title: baseNameOf(l.rel || l.path),
+    note: l.note || '',
+    tag: l.tag || '',
+  }));
+  return { main, links, count: (main.title ? 1 : 0) + links.length };
+}

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),