nx-kv 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 本文件记录对外可见的变更。格式参考 [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

package/package.json

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

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/repos/boards.js

@@ -123,18 +123,21 @@ export async function getBoard(idOrKey) {
 export async function createBoard({ name, desc } = {}) {
   const nm = cleanText(name);
   if (!nm) throw badInput('看板名称不能为空');
-  return mutateStore((s) => {
-    if (s.boards.some((b) => b.name === nm)) throw conflict('同名看板已存在: ' + nm);
-    const b = {
+  const b = await mutateStore((s) => {
+    if (s.boards.some((x) => x.name === nm)) throw conflict('同名看板已存在: ' + nm);
+    const board = {
       id: newId('b'),
       name: nm,
       desc: cleanText(desc),
       createdAt: new Date().toISOString(),
       repoKeys: [], // 成员按 key 存（不再用随机 id）
     };
-    s.boards.push(b);
-    return { id: b.id, name: b.name, desc: b.desc, key: boardKeyOf(nm), repos: [] };
+    s.boards.push(board);
+    return { id: board.id, name: board.name, desc: board.desc, key: boardKeyOf(nm), repos: [] };
   });
+  // 描述是文档：初始描述写成组介绍的主篇（已有就不动），摘要由回写刷新
+  if (cleanText(desc)) await writeBoardDocContent({ name: nm }, desc);
+  return b;
 }
 
 export async function updateBoard(idOrKey, { name, desc } = {}) {
@@ -147,7 +150,13 @@ export async function updateBoard(idOrKey, { name, desc } = {}) {
       throw conflict('同名看板已存在: ' + nm);
     }
     if (nm !== undefined) b.name = nm;
-    if (desc !== undefined) b.desc = cleanText(desc);
+    // 领域描述同样是文档：写正文用 docs set，换绑主篇用 docs bind --board
+    if (desc !== undefined) {
+      throw badInput(
+        '描述已改为文档（不再是字符串）：改正文用 `docs set board/<组>.md`，' +
+        '换绑主篇用 `docs bind --board <看板> --rel <路径>`'
+      );
+    }
     return { id: b.id, name: b.name, desc: b.desc, key: boardKeyOf(b.name) };
   });
 }
@@ -408,6 +417,35 @@ export async function prunePlaceholders({ board, all = false, apply = false } =
   return { apply, total: items.length, items };
 }
 
+/**
+ * 看板的领域描述写进 board/<组>.md（文档是权威）。已有文档就不动——
+ * 重复 createBoard（导入/补建）不该把写过的组介绍冲掉。
+ */
+async function writeBoardDocContent(board, text) {
+  const { boardDocRel } = await import('../docs/paths.js');
+  const store = await import('../docs/store.js');
+  const { writeBackSummary } = await import('../docs/seed.js');
+  const rel = boardDocRel(board.name);
+  if (await store.ownDocExists(rel)) return rel;
+  const body = `# ${board.name}\n\n${String(text || '').trim()}\n`;
+  await store.writeOwnDoc(rel, body);
+  await writeBackSummary(rel, body);
+  return rel;
+}
+
+/** 组内描述写进 group/<组>/<key>.md（覆盖正文；空文本 = 只留标题，摘要自然为空）。 */
+async function writeGroupNoteDoc(info, text) {
+  const { groupNoteRel } = await import('../docs/paths.js');
+  const store = await import('../docs/store.js');
+  const { writeBackSummary } = await import('../docs/seed.js');
+  const rel = groupNoteRel(info.boardName, info.key);
+  const head = `# ${info.boardName} · ${info.name}`;
+  const body = text ? `${head}\n\n${text}\n` : `${head}\n`;
+  await store.writeOwnDoc(rel, body);
+  await writeBackSummary(rel, body); // 摘要回填 repoNotes（列表读的那份影子）
+  return rel;
+}
+
 /**
  * 设置组内描述：key = 仓库（id / key / 路径 / 名称 均可），board = 看板。
  * 只对**已在板内**的成员有意义——不是成员就显式报错，别静默挂到没人读的地方。
@@ -417,28 +455,25 @@ export async function setBoardRepoNote({ id, key, board, note } = {}) {
   const locator = key || id;
   if (!locator) throw badInput('缺少仓库 id 或 key');
   if (!board) throw badInput('缺少看板 id');
-  return mutateStore((s) => {
-    // 占位成员（本地未拥有）也允许写描述——描述挂在 key 上，clone 补齐后自动生效
-    const rkey = repoKeyIn(s, locator) || normalizeKey(locator);
-    const b = findBoardIn(s, board);
-    if (!b) throw notFound('看板不存在: ' + board);
-    if (!boardRepoKeys(b, s).includes(rkey)) {
-      throw conflict(`仓库「${rkey}」不在看板「${b.name}」里——组内描述只对成员有意义`);
-    }
-    const text = String(note || '').trim();
-    if (!b.repoNotes) b.repoNotes = {};
-    if (text) b.repoNotes[rkey] = text;
-    else delete b.repoNotes[rkey];
-    const r = s.repos.find((x) => deriveKey(x) === rkey);
-    return {
-      key: rkey,
-      name: r ? r.name : rkey,
-      board: b.id,
-      boardKey: boardKeyOf(b.name),
-      boardName: b.name,
-      note: text,
-    };
-  });
+  const s = await loadStore();
+  // 占位成员（本地未拥有）也允许写描述——描述挂在 key 上，clone 补齐后自动生效
+  const rkey = repoKeyIn(s, locator) || normalizeKey(locator);
+  const b = findBoardIn(s, board);
+  if (!b) throw notFound('看板不存在: ' + board);
+  if (!boardRepoKeys(b, s).includes(rkey)) {
+    throw conflict(`仓库「${rkey}」不在看板「${b.name}」里——组内描述只对成员有意义`);
+  }
+  const text = String(note || '').trim();
+  const info = {
+    key: rkey,
+    name: (s.repos.find((x) => deriveKey(x) === rkey) || {}).name || rkey,
+    board: b.id,
+    boardKey: boardKeyOf(b.name),
+    boardName: b.name,
+  };
+  // 描述 = 文档：写 group/<组>/<key>.md；repoNotes 只是摘要影子（由回写维护）
+  await writeGroupNoteDoc(info, text);
+  return { ...info, note: text };
 }
 
 // 导入：一段 JSON = 一批主题。{boards:[{name, desc?, repos:[{key|name, desc?}]}]}

package/src/modules/repos/index.js

@@ -212,7 +212,7 @@ export default {
       flags: {
         name: { type: 'string' },
         icon: { type: 'string', hint: '项目图标（emoji 或单字符，≤8 字；留空 = 用默认图标）' },
-        desc: { type: 'string' },
+        desc: { type: 'string', hint: '初始描述（写成项目主篇文档；之后描述以文档为准）' },
         notes: { type: 'string' },
         type: { type: 'string', enum: ['dev', 'ref'], hint: 'dev=开发仓库（默认），ref=参考仓库' },
         remote: { type: 'string', hint: '远程 git 地址（key 的来源；导出时导它）' },
@@ -231,13 +231,13 @@ export default {
       cli: ['repo', 'update'],
       http: ['PATCH', '/api/repos/:id'],
       summary:
-        '修改仓库路径 / 名称 / 描述 / 备注 / 类型 / 远程地址 / key；--get-loop* 配置项目级「持续 get」（waitgoal：该项目 get 无任务时阻塞等人回填 + 交付文本带继续 get 模板）',
+        '修改仓库路径 / 名称 / 备注 / 类型 / 远程地址 / key；--get-loop* 配置项目级「持续 get」（waitgoal：该项目 get 无任务时阻塞等人回填 + 交付文本带继续 get 模板）。描述已改为文档，不再经这里改',
       args: ['id'],
       flags: {
         path: { type: 'string' },
         name: { type: 'string' },
         icon: { type: 'string', hint: '项目图标（emoji 或单字符，≤8 字；留空 = 用默认图标）' },
-        desc: { type: 'string' },
+        desc: { type: 'string', hint: '（已废弃）描述是文档：改正文用 docs set，换绑用 docs bind —— 传了会报错' },
         notes: { type: 'string' },
         type: { type: 'string', enum: ['dev', 'ref'], hint: 'dev=开发仓库，ref=参考仓库' },
         remote: { type: 'string', hint: '远程 git 地址' },

package/src/modules/repos/service.js

@@ -369,7 +369,7 @@ export function migrateStoreKeys(store) {
 export async function listRepos() {
   const s = await loadStore();
   // docs/paths 反过来依赖本文件的 normalizeKey（动态引入避免静态环）
-  const { repoDocRel } = await import('../docs/paths.js');
+  const { repoDocRel, groupNoteRel } = await import('../docs/paths.js');
   const boardsOf = new Map(); // repoKey -> [看板投影]
   for (const b of s.boards) {
     for (const rk of boardRepoKeys(b, s)) {
@@ -380,11 +380,14 @@ export async function listRepos() {
         desc: b.desc || '',
         key: boardKeyOf(b.name),
         note: (b.repoNotes || {})[rk] || '',
+        // 组内描述也是文档：前端点「描述」直接开这篇（绑定优先，缺省约定路径）
+        noteDocRel: (b.repoDocs || {})[rk]?.rel || groupNoteRel(b.name, rk),
+        noteDocPath: (b.repoDocs || {})[rk]?.path || '',
       });
     }
   }
-  return s.repos
-    .map(({ tags: _dropped, ...r }) => {
+  const { docSetOf } = await import('../docs/brief.js');
+  const rows = s.repos.map(({ tags: _dropped, ...r }) => {
       const rk = deriveKey(r);
       return {
         ...r,
@@ -397,8 +400,10 @@ export async function listRepos() {
         docRel: r.doc?.rel || repoDocRel(rk),
         boards: boardsOf.get(rk) || [],
       };
-    })
-    .sort((a, b) => String(a.name).localeCompare(String(b.name)));
+    });
+  // 描述 = 绑定的文档集（主篇标题 + 补充篇），不再是 desc 字符串
+  for (const row of rows) row.descDocs = await docSetOf(row, 'repo');
+  return rows.sort((a, b) => String(a.name).localeCompare(String(b.name)));
 }
 
 export async function addRepo(input) {
@@ -414,9 +419,40 @@ export async function addRepo(input) {
     if (dup) throw conflict(`该 key 已登记为「${dup.name}」（${dup.id}）: ${repo.key}`);
     s.repos.push(repo);
   });
+  await seedRepoDoc(repo);
   return repo;
 }
 
+/**
+ * 描述是文档：add 时给的 desc 只是**初始正文**，落到主篇 md（repo/<key>/index.md 的旧单文件位），
+ * 再按 md 回写摘要。文档已在就不动——老仓库重登记不该把写过的介绍冲掉。
+ * 动态 import 同 listRepos：docs 是叶子，repos 反向依赖它（静态引会成环）。
+ */
+async function seedRepoDoc(repo) {
+  const desc = String((repo && repo.desc) || '').trim();
+  if (!desc) return null;
+  const { repoDocRel } = await import('../docs/paths.js');
+  const store = await import('../docs/store.js');
+  const rel = repoDocRel(repo.key);
+  if (await store.ownDocExists(rel)) return null;
+  return writeRepoDocContent(repo, desc);
+}
+
+/**
+ * 把一段文本写成仓库的主篇文档（覆盖正文，标题取仓库名）。
+ * 导入覆盖（transfer 的 overwrite 策略）走这里——描述不能再经 updateRepo 的 desc 字段。
+ */
+export async function writeRepoDocContent(repo, text) {
+  const { repoDocRel } = await import('../docs/paths.js');
+  const store = await import('../docs/store.js');
+  const { writeBackSummary } = await import('../docs/seed.js');
+  const rel = repoDocRel(repo.key);
+  const body = `# ${repo.name || repo.key}\n\n${String(text || '').trim()}\n`;
+  await store.writeOwnDoc(rel, body);
+  await writeBackSummary(rel, body);
+  return rel;
+}
+
 export async function updateRepo(id, patch) {
   return mutateStore((s) => {
     // 定位：id → key → 绝对路径 → 名称（与 getRepo 同一口径——
@@ -430,7 +466,12 @@ export async function updateRepo(id, patch) {
     if (!r) throw notFound('repo 不存在: ' + id);
     if (patch.name !== undefined) r.name = String(patch.name).trim();
     if (patch.icon !== undefined) r.icon = sanitizeIcon(patch.icon);
-    if (patch.desc !== undefined) r.desc = String(patch.desc).trim();
+    if (patch.desc !== undefined) {
+      throw badInput(
+        '描述已改为文档（不再是字符串）：改正文用 `docs set <rel>`，换绑主篇用 ' +
+        '`docs bind --repo <仓库> --rel <路径>`，加补充篇用 `docs link --board <看板> --doc <路径>`'
+      );
+    }
     if (patch.notes !== undefined) r.notes = String(patch.notes);
     if (patch.type !== undefined) {
       const t = patch.type === 'ref' ? 'ref' : patch.type === 'dev' ? 'dev' : null;

package/src/modules/repos/transfer.js

@@ -519,12 +519,18 @@ export async function repoImport({
         }
         if (strategy === 'overwrite') {
           const patch = {};
+          let descIn = null;
           for (const f of item.fields) {
+            // 描述是文档（不再是字符串字段）：攒下来单独写主篇，不进 updateRepo 的 patch
+            if (f.field === 'desc') { descIn = inc.desc; continue; }
             if (f.field === 'type') patch.type = inc.type;
             else if (f.field === 'remote') patch.remote = inc.remote || '';
             else patch[f.field] = inc[f.field];
           }
           await service.updateRepo(item.local.id, patch);
+          if (descIn !== null) {
+            await service.writeRepoDocContent({ key: item.key, name: inc.name || item.key }, descIn);
+          }
           updated.push({ key: item.key, fields: item.fields.map((f) => f.field) });
           continue;
         }
@@ -627,8 +633,17 @@ export async function repoImport({
             .catch(() => {});
         }
         if (m.note) {
-          // 组内描述挂在 key 上：占位成员也保留描述，等仓库补齐后自动生效
-          await boards.setBoardRepoNote({ key: m.key, board: b.id, note: m.note }).catch(() => {});
+          // 组内描述挂在 key 上：占位成员也保留描述，等仓库补齐后自动生效。
+          // **直接写摘要字段**，不走 setBoardRepoNote —— 后者会把这句话写进
+          // group 文档，覆盖刚从 zip 还原的正文（描述以文档为准，文字只是影子）。
+          await service
+            .mutateStore((s) => {
+              const bb = s.boards.find((x) => x.id === b.id);
+              if (!bb) return;
+              if (!bb.repoNotes) bb.repoNotes = {};
+              bb.repoNotes[m.key] = m.note;
+            })
+            .catch(() => {});
         }
         if (!known) {
           unmatched.push({

package/src/web/frontend/components/md/md-panes.jsx

@@ -36,6 +36,16 @@ import {
 // 格式快捷键 → 编辑操作（预览态划选后直接套用）
 const FMT_KEYS = { b: 'bold', i: 'italic', e: 'code', k: 'link' };
 
+/** 正文里已经自带 `# 标题` 了吗（跳过 frontmatter）——阅读态据此决定要不要再画题头 */
+function bodyHasH1(body) {
+  let t = String(body || '').replace(/^\uFEFF/, '').trimStart();
+  if (t.startsWith('---')) {
+    const end = t.indexOf('\n---', 3);
+    if (end > 0) t = t.slice(end + 4).trimStart();
+  }
+  return /^#[ \t]+\S/.test(t);
+}
+
 function autoSize(el) {
   if (!el) return;
   el.style.height = '0px';
@@ -1254,8 +1264,12 @@ export const MdPanes = forwardRef(function MdPanes(
       {mode === 'preview' && (
         <div className="mdw-pane mdw-preview">
           <div className="mdw-reader">
-            {/* 阅读态此前不渲染标题，与 live/源码两态断裂；题头与正文同轴同宽 */}
-            {title ? <h1 className="mdw-reader-title">{title}</h1> : null}
+            {/* 阅读态此前不渲染标题，与 live/源码两态断裂；题头与正文同轴同宽。
+                正文自带 `# 标题` 时不再画外部题头——文档的 body 本来就含首行标题，
+                两个都画就是同一行字出现两次（阅读态看起来像渲染 bug）。 */}
+            {title && !bodyHasH1(body) ? (
+              <h1 className="mdw-reader-title">{title}</h1>
+            ) : null}
             <article ref={articleRef} dangerouslySetInnerHTML={{ __html: previewHtml }} />
           </div>
         </div>