nx-kv 0.16.0 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/CHANGELOG.md +81 -0
  2. package/package.json +1 -1
  3. package/src/core/localatt.js +137 -0
  4. package/src/modules/docs/brief.js +84 -0
  5. package/src/modules/docs/docref.js +17 -0
  6. package/src/modules/docs/index.js +5 -2
  7. package/src/modules/docs/knowledge.js +8 -7
  8. package/src/modules/docs/refs.js +18 -5
  9. package/src/modules/file/index.js +9 -5
  10. package/src/modules/file/service.js +75 -9
  11. package/src/modules/localtask/index.js +5 -7
  12. package/src/modules/repos/boards.js +63 -28
  13. package/src/modules/repos/index.js +8 -7
  14. package/src/modules/repos/service.js +50 -11
  15. package/src/modules/repos/transfer.js +22 -7
  16. package/src/modules/tasktool/attach.js +55 -46
  17. package/src/modules/tasktool/groupctx.js +1 -1
  18. package/src/web/frontend/App.jsx +14 -6
  19. package/src/web/frontend/components/Introduction/index.jsx +44 -13
  20. package/src/web/frontend/components/Introduction/style.css +11 -0
  21. package/src/web/frontend/components/Introduction/use-intro.js +66 -16
  22. package/src/web/frontend/components/board/member-picker.jsx +16 -21
  23. package/src/web/frontend/components/cloud/editor.jsx +1 -1
  24. package/src/web/frontend/components/cloud/group-popup.jsx +3 -1
  25. package/src/web/frontend/components/cloud/upload.js +6 -5
  26. package/src/web/frontend/components/md/attachments.js +12 -10
  27. package/src/web/frontend/components/md/md-panes.jsx +20 -3
  28. package/src/web/frontend/components/md/shortcut-sheet.jsx +19 -50
  29. package/src/web/frontend/components/migrate/dialog.jsx +51 -55
  30. package/src/web/frontend/components/popup/dismiss.js +32 -0
  31. package/src/web/frontend/components/popup/index.jsx +270 -0
  32. package/src/web/frontend/components/popup/style.css +64 -0
  33. package/src/web/frontend/components/repos/desc-modal.jsx +250 -0
  34. package/src/web/frontend/components/repos/transfer-panel.jsx +14 -7
  35. package/src/web/frontend/components/sidebar/index.jsx +4 -3
  36. package/src/web/frontend/components/sidebar/row-menu.jsx +11 -5
  37. package/src/web/frontend/components/sidebar/task-children.jsx +1 -1
  38. package/src/web/frontend/components/toast/index.jsx +40 -0
  39. package/src/web/frontend/components/toast/style.css +24 -0
  40. package/src/web/frontend/components/ui.jsx +11 -113
  41. package/src/web/frontend/main.jsx +1 -1
  42. package/src/web/frontend/modules/md/style.css +54 -33
  43. package/src/web/frontend/page/cloud/index.jsx +5 -3
  44. package/src/web/frontend/page/dir/index.jsx +10 -4
  45. package/src/web/frontend/page/dir/task.jsx +13 -3
  46. package/src/web/frontend/page/doc/index.jsx +2 -1
  47. package/src/web/frontend/page/group/index.jsx +1 -1
  48. package/src/web/frontend/page/overview/index.jsx +11 -2
  49. package/src/web/frontend/page/progress/index.jsx +14 -3
  50. package/src/web/frontend/page/repos/index.jsx +156 -124
  51. package/src/web/frontend/page/settings/index.jsx +9 -3
  52. package/src/web/frontend/page/templates/index.jsx +11 -3
  53. package/src/web/frontend/style-v2.css +7 -42
  54. package/src/web/frontend/style.css +182 -136
  55. package/src/web/public/assets/Introduction-B4k08SH9.css +1 -0
  56. package/src/web/public/assets/Introduction-CLTMLBZ5.js +1 -0
  57. package/src/web/public/assets/cloud-B9_h1Ym7.js +3 -0
  58. package/src/web/public/assets/dir-BLUQranN.js +3 -0
  59. package/src/web/public/assets/group-DIeOm80x.js +1 -0
  60. package/src/web/public/assets/index-DA98QEzx.css +1 -0
  61. package/src/web/public/assets/index-t7PgSf_t.js +50 -0
  62. package/src/web/public/assets/md-history-CDVA0KIl.js +5 -0
  63. package/src/web/public/assets/member-picker-9MAmKm9d.js +1 -0
  64. package/src/web/public/assets/overview-DNLRHNzP.js +1 -0
  65. package/src/web/public/assets/progress-C0MiaOW0.js +3 -0
  66. package/src/web/public/assets/repos--i4W5fzj.js +10 -0
  67. package/src/web/public/assets/settings-DSx2Wsto.js +1 -0
  68. package/src/web/public/assets/task-D2-CWZXv.js +2 -0
  69. package/src/web/public/assets/templates-DD6m8DT4.js +2 -0
  70. package/src/web/public/assets/{upload-DLBQnUn4.js → upload-BupH8dMK.js} +1 -1
  71. package/src/web/public/index.html +2 -3
  72. package/src/web/frontend/components/cloud/row-menu.jsx +0 -52
  73. package/src/web/frontend/components/overlay.jsx +0 -74
  74. package/src/web/public/assets/Introduction-DdUm5Il3.js +0 -1
  75. package/src/web/public/assets/Introduction-Q36q9sjA.css +0 -1
  76. package/src/web/public/assets/cloud-CRC00qO-.js +0 -3
  77. package/src/web/public/assets/dir-CrUiP4aQ.js +0 -3
  78. package/src/web/public/assets/group-CYVEZpI9.js +0 -1
  79. package/src/web/public/assets/index-Did6XKz0.js +0 -50
  80. package/src/web/public/assets/index-pgxfM8xe.css +0 -1
  81. package/src/web/public/assets/jsx-runtime-D3jfb0Ew.js +0 -1
  82. package/src/web/public/assets/md-history-rfsLK89W.js +0 -4
  83. package/src/web/public/assets/member-picker-BGUlAVgA.js +0 -1
  84. package/src/web/public/assets/overview-BFoqWgXk.js +0 -1
  85. package/src/web/public/assets/progress-Df-DZ6uP.js +0 -3
  86. package/src/web/public/assets/repos-Bvg8dLSB.js +0 -11
  87. package/src/web/public/assets/settings-DtmMN_KG.js +0 -1
  88. package/src/web/public/assets/task-D5YReySK.js +0 -2
  89. package/src/web/public/assets/templates-BLGE6arn.js +0 -2
@@ -1,8 +1,9 @@
1
- // 附件模块:用户空间里的图片 / 文档等二进制原件。
2
- //
3
- // 后端是 dev_ctr_hello 的图床(/api/v1/files*,上传 multipart,出图 /files/:fileId)。
4
- // 本模块只做「业务编排 + 人读渲染」,网络细节全在 core/fileapi.js,
5
- // 本地镜像细节全在 core/attachstore.js。
1
+ // 附件模块:用户空间里的图片 / 文档等二进制原件,**双后端**:
2
+ // - 云端图床(dev_ctr_hello /api/v1/files*,上传 multipart,出图 /files/:fileId)
3
+ // —— 云端清单(todo)的附件走这边,本地镜像细节在 core/attachstore.js;
4
+ // - 本地附件仓(core/localatt.js)—— 本地任务(localtask)的贴图走这边,
5
+ // 不碰网:上传落本机盘、预览读本机文件、agent 直接拿本地路径。
6
+ // 本模块只做「业务编排 + 人读渲染」,网络细节全在 core/fileapi.js。
6
7
  //
7
8
  // 与 todo 的分工:附件**内容**归这里;附件**怎么被任务引用**归 todo
8
9
  // (任务正文里的 ![说明](fileId),见 modules/todo/attach.js)。
@@ -16,6 +17,7 @@ import {
16
17
  accessUrlOf, contentTypeOf, deleteFile, fileInfo, fileUpload, isImageName, listFiles, openFileStream,
17
18
  } from '../../core/fileapi.js';
18
19
  import { localDirFor, localIndex, resolveLocal, syncAttachments } from '../../core/attachstore.js';
20
+ import { localDir, localReadStream, localResolve, localUpload } from '../../core/localatt.js';
19
21
 
20
22
  const fmtBytes = (n) => {
21
23
  const v = Number(n) || 0;
@@ -65,8 +67,7 @@ export async function listFilesAction({ group, limit = 100, offset = 0 } = {}) {
65
67
  }
66
68
 
67
69
  export async function uploadFileAction(patch = {}) {
68
- const { path: localPath, content, name, contentType, group, accessLevel = 'public' } = patch;
69
- const gid = await resolveGroupId(group);
70
+ const { path: localPath, content, name, contentType, group, accessLevel = 'public', local: toLocal } = patch;
70
71
  let buffer;
71
72
  let fileName;
72
73
 
@@ -86,6 +87,26 @@ export async function uploadFileAction(patch = {}) {
86
87
  throw badInput('上传需要 --path <本机文件>,或 --content <base64> --name <文件名>');
87
88
  }
88
89
 
90
+ // 本地任务贴图 → 本地附件仓:不碰网、不解析工作空间(group 是云端图床的归属维度),
91
+ // 上传即已在本地,agent 直接读 localPath——这条链路与云端零关联。
92
+ if (toLocal) {
93
+ const rec = await localUpload({ name: fileName, buffer, contentType: contentType || contentTypeOf(fileName) });
94
+ return {
95
+ fileId: rec.fileId,
96
+ name: rec.name,
97
+ size: rec.size,
98
+ contentType: rec.contentType,
99
+ url: `/api/file/content/${rec.fileId}`,
100
+ isImage: isImageName(rec.name, rec.contentType),
101
+ localPath: rec.path,
102
+ localDir: localDir(),
103
+ storage: 'local',
104
+ markdown: snippetOf(rec.name, rec.fileId),
105
+ };
106
+ }
107
+
108
+ const cfg = await loadConfig();
109
+ const gid = await resolveGroupId(group);
89
110
  const meta = await fileUpload({
90
111
  name: fileName,
91
112
  buffer,
@@ -93,18 +114,33 @@ export async function uploadFileAction(patch = {}) {
93
114
  groupId: gid,
94
115
  accessLevel,
95
116
  });
96
- const cfg = await loadConfig();
97
117
  return {
98
118
  ...meta,
99
119
  url: accessUrlOf(cfg.baseUrl, meta.fileId),
100
120
  isImage: isImageName(fileName, meta.contentType),
101
121
  localDir: localDirFor(gid, cfg.attachmentsDir),
122
+ storage: 'cloud',
102
123
  markdown: snippetOf(fileName, meta.fileId),
103
124
  };
104
125
  }
105
126
 
106
127
  export async function getFileAction(fileId, { group } = {}) {
107
128
  if (!fileId) throw badInput('缺少 fileId');
129
+ // 本地仓命中就不问云端:本地任务贴图的查询零网络、离线可用。
130
+ // 两套 id 同构(32 位 hex),先本地后云端的顺序天然消歧。
131
+ const hit = await localResolve(fileId);
132
+ if (hit) {
133
+ return {
134
+ fileId: hit.fileId,
135
+ name: hit.name,
136
+ size: hit.size,
137
+ contentType: hit.contentType,
138
+ url: `/api/file/content/${hit.fileId}`,
139
+ isImage: isImageName(hit.name, hit.contentType),
140
+ localPath: hit.path,
141
+ storage: 'local',
142
+ };
143
+ }
108
144
  const cfg = await loadConfig();
109
145
  const gid = await resolveGroupId(group);
110
146
  const meta = await fileInfo(fileId, gid);
@@ -115,6 +151,7 @@ export async function getFileAction(fileId, { group } = {}) {
115
151
  isImage: isImageName(meta.fileId, meta.contentType),
116
152
  localPath: local?.path || '',
117
153
  localName: local?.name || '',
154
+ storage: 'cloud',
118
155
  };
119
156
  }
120
157
 
@@ -138,10 +175,24 @@ export async function syncFilesAction({ group, ids, dir, prune, dryRun } = {}) {
138
175
  return { ...result, usedDir: localDirFor(gid, dir || cfg.attachmentsDir) };
139
176
  }
140
177
 
141
- /** HTTP 原始流:把后端的出图内容原样透给浏览器(面板里 <img src> 直接用)。 */
178
+ /** HTTP 原始流:附件本体直接透给浏览器(面板里 <img src> 直接用)。
179
+ * 本地仓命中 → 读本机文件(离线可预览,本地任务贴图不依赖云端);
180
+ * 未命中 → 云端出图原样透传(云端清单附件的老路径,行为不变)。 */
142
181
  export async function serveContent(ctx) {
143
182
  const { res } = ctx.__raw || {};
144
183
  if (!res) throw badInput('内部错误:缺少响应对象');
184
+ const hit = await localResolve(ctx.fileId);
185
+ if (hit) {
186
+ res.writeHead(200, { 'content-type': hit.contentType || 'application/octet-stream', 'cache-control': 'no-store' });
187
+ await new Promise((done, fail) => {
188
+ const rs = localReadStream(hit.path);
189
+ rs.once('error', fail);
190
+ res.once('close', done);
191
+ res.once('finish', done);
192
+ rs.pipe(res);
193
+ });
194
+ return;
195
+ }
145
196
  const up = await openFileStream(ctx.fileId);
146
197
  const ct = up.headers.get('content-type') || 'application/octet-stream';
147
198
  res.writeHead(200, { 'content-type': ct, 'cache-control': 'no-store' });
@@ -167,6 +218,14 @@ export function renderFileList(d) {
167
218
  }
168
219
 
169
220
  export function renderUpload(d) {
221
+ if (d.storage === 'local') {
222
+ return [
223
+ `已上传 ${d.fileId}(${fmtBytes(d.size)} · ${d.contentType})→ 本机附件仓`,
224
+ `本地: ${d.localPath}`,
225
+ `贴进任务正文(编辑时也可直接选图上传):`,
226
+ ` ${d.isImage ? d.markdown.image : d.markdown.file}`,
227
+ ].join('\n');
228
+ }
170
229
  return [
171
230
  `已上传 ${d.fileId}(${fmtBytes(d.size)} · ${d.contentType})`,
172
231
  `地址: ${d.url}`,
@@ -177,6 +236,13 @@ export function renderUpload(d) {
177
236
  }
178
237
 
179
238
  export function renderFileInfo(d) {
239
+ if (d.storage === 'local') {
240
+ return [
241
+ `${d.fileId} · ${d.isImage ? '图片' : '文件'} · ${fmtBytes(d.size)} · ${d.contentType}`,
242
+ `地址: ${d.url}`,
243
+ `本地: ${d.localPath}(本机附件仓,不依赖云端)`,
244
+ ].join('\n');
245
+ }
180
246
  return [
181
247
  `${d.fileId} · ${d.isImage ? '图片' : '文件'} · ${fmtBytes(d.size)} · ${d.contentType}`,
182
248
  `地址: ${d.url}`,
@@ -355,21 +355,20 @@ export default {
355
355
  : ''),
356
356
  },
357
357
  {
358
- // 附件追加(与云端 todo attach 同构):上传/复用 fileId → markdown 嵌入正文末尾。
359
- // 面板编辑器贴的是同一条语法(components/md/attachments.js),两端渲染一致。
358
+ // 附件追加(与云端 todo attach 同构):--path 落**本机附件仓**(零云端)→ 嵌入正文末尾;
359
+ // --fileId 引用已有附件(本机仓 / 云端 id)。面板编辑器贴同一条语法(components/md/attachments.js)。
360
360
  id: 'localtask.attach',
361
361
  cli: ['localtask', 'attach'],
362
362
  http: ['POST', '/api/localtasks/attach'],
363
- summary: '给任务追加附件:--path 上传本机文件,或 --fileId 追加已上传附件,以 markdown 嵌入正文末尾(不替换正文)',
363
+ summary: '给任务追加附件:--path 存本机附件仓(不碰云端),或 --fileId 引用已有附件,以 markdown 嵌入正文末尾(不替换正文)',
364
364
  flags: {
365
365
  id: { type: 'number', required: true, hint: '任务编号' },
366
366
  cwd: CWD,
367
367
  key: KEY,
368
- path: { type: 'string', hint: '本机文件路径(先上传再嵌入)' },
369
- fileId: { type: 'string', hint: '已上传附件的 id(32 位 hex,可带扩展名)' },
368
+ path: { type: 'string', hint: '本机文件路径(落 ~/.nx-kv/attachments/local/ 再嵌入)' },
369
+ fileId: { type: 'string', hint: '已有附件的 id(32 位 hex,可带扩展名;本机仓或云端)' },
370
370
  name: { type: 'string', hint: '嵌入文字与本地文件名(默认取原文件名)' },
371
371
  kind: { type: 'string', hint: 'image | file(不给按文件名/扩展名判)' },
372
- accessLevel: { type: 'string', hint: 'public | private | protected(默认 public;仅 --path 上传时生效)' },
373
372
  },
374
373
  run: async (ctx) => {
375
374
  const { attachToTask } = await import('../tasktool/attach.js');
@@ -381,7 +380,6 @@ export default {
381
380
  fileId: ctx.fileId,
382
381
  name: ctx.name,
383
382
  kind: ctx.kind,
384
- accessLevel: ctx.accessLevel,
385
383
  });
386
384
  },
387
385
  render: (d) =>
@@ -123,18 +123,21 @@ export async function getBoard(idOrKey) {
123
123
  export async function createBoard({ name, desc } = {}) {
124
124
  const nm = cleanText(name);
125
125
  if (!nm) throw badInput('看板名称不能为空');
126
- return mutateStore((s) => {
127
- if (s.boards.some((b) => b.name === nm)) throw conflict('同名看板已存在: ' + nm);
128
- const b = {
126
+ const b = await mutateStore((s) => {
127
+ if (s.boards.some((x) => x.name === nm)) throw conflict('同名看板已存在: ' + nm);
128
+ const board = {
129
129
  id: newId('b'),
130
130
  name: nm,
131
131
  desc: cleanText(desc),
132
132
  createdAt: new Date().toISOString(),
133
133
  repoKeys: [], // 成员按 key 存(不再用随机 id)
134
134
  };
135
- s.boards.push(b);
136
- return { id: b.id, name: b.name, desc: b.desc, key: boardKeyOf(nm), repos: [] };
135
+ s.boards.push(board);
136
+ return { id: board.id, name: board.name, desc: board.desc, key: boardKeyOf(nm), repos: [] };
137
137
  });
138
+ // 描述是文档:初始描述写成组介绍的主篇(已有就不动),摘要由回写刷新
139
+ if (cleanText(desc)) await writeBoardDocContent({ name: nm }, desc);
140
+ return b;
138
141
  }
139
142
 
140
143
  export async function updateBoard(idOrKey, { name, desc } = {}) {
@@ -147,7 +150,13 @@ export async function updateBoard(idOrKey, { name, desc } = {}) {
147
150
  throw conflict('同名看板已存在: ' + nm);
148
151
  }
149
152
  if (nm !== undefined) b.name = nm;
150
- if (desc !== undefined) b.desc = cleanText(desc);
153
+ // 领域描述同样是文档:写正文用 docs set,换绑主篇用 docs bind --board
154
+ if (desc !== undefined) {
155
+ throw badInput(
156
+ '描述已改为文档(不再是字符串):改正文用 `docs set board/<组>.md`,' +
157
+ '换绑主篇用 `docs bind --board <看板> --rel <路径>`'
158
+ );
159
+ }
151
160
  return { id: b.id, name: b.name, desc: b.desc, key: boardKeyOf(b.name) };
152
161
  });
153
162
  }
@@ -408,6 +417,35 @@ export async function prunePlaceholders({ board, all = false, apply = false } =
408
417
  return { apply, total: items.length, items };
409
418
  }
410
419
 
420
+ /**
421
+ * 看板的领域描述写进 board/<组>.md(文档是权威)。已有文档就不动——
422
+ * 重复 createBoard(导入/补建)不该把写过的组介绍冲掉。
423
+ */
424
+ async function writeBoardDocContent(board, text) {
425
+ const { boardDocRel } = await import('../docs/paths.js');
426
+ const store = await import('../docs/store.js');
427
+ const { writeBackSummary } = await import('../docs/seed.js');
428
+ const rel = boardDocRel(board.name);
429
+ if (await store.ownDocExists(rel)) return rel;
430
+ const body = `# ${board.name}\n\n${String(text || '').trim()}\n`;
431
+ await store.writeOwnDoc(rel, body);
432
+ await writeBackSummary(rel, body);
433
+ return rel;
434
+ }
435
+
436
+ /** 组内描述写进 group/<组>/<key>.md(覆盖正文;空文本 = 只留标题,摘要自然为空)。 */
437
+ async function writeGroupNoteDoc(info, text) {
438
+ const { groupNoteRel } = await import('../docs/paths.js');
439
+ const store = await import('../docs/store.js');
440
+ const { writeBackSummary } = await import('../docs/seed.js');
441
+ const rel = groupNoteRel(info.boardName, info.key);
442
+ const head = `# ${info.boardName} · ${info.name}`;
443
+ const body = text ? `${head}\n\n${text}\n` : `${head}\n`;
444
+ await store.writeOwnDoc(rel, body);
445
+ await writeBackSummary(rel, body); // 摘要回填 repoNotes(列表读的那份影子)
446
+ return rel;
447
+ }
448
+
411
449
  /**
412
450
  * 设置组内描述:key = 仓库(id / key / 路径 / 名称 均可),board = 看板。
413
451
  * 只对**已在板内**的成员有意义——不是成员就显式报错,别静默挂到没人读的地方。
@@ -417,28 +455,25 @@ export async function setBoardRepoNote({ id, key, board, note } = {}) {
417
455
  const locator = key || id;
418
456
  if (!locator) throw badInput('缺少仓库 id 或 key');
419
457
  if (!board) throw badInput('缺少看板 id');
420
- return mutateStore((s) => {
421
- // 占位成员(本地未拥有)也允许写描述——描述挂在 key 上,clone 补齐后自动生效
422
- const rkey = repoKeyIn(s, locator) || normalizeKey(locator);
423
- const b = findBoardIn(s, board);
424
- if (!b) throw notFound('看板不存在: ' + board);
425
- if (!boardRepoKeys(b, s).includes(rkey)) {
426
- throw conflict(`仓库「${rkey}」不在看板「${b.name}」里——组内描述只对成员有意义`);
427
- }
428
- const text = String(note || '').trim();
429
- if (!b.repoNotes) b.repoNotes = {};
430
- if (text) b.repoNotes[rkey] = text;
431
- else delete b.repoNotes[rkey];
432
- const r = s.repos.find((x) => deriveKey(x) === rkey);
433
- return {
434
- key: rkey,
435
- name: r ? r.name : rkey,
436
- board: b.id,
437
- boardKey: boardKeyOf(b.name),
438
- boardName: b.name,
439
- note: text,
440
- };
441
- });
458
+ const s = await loadStore();
459
+ // 占位成员(本地未拥有)也允许写描述——描述挂在 key 上,clone 补齐后自动生效
460
+ const rkey = repoKeyIn(s, locator) || normalizeKey(locator);
461
+ const b = findBoardIn(s, board);
462
+ if (!b) throw notFound('看板不存在: ' + board);
463
+ if (!boardRepoKeys(b, s).includes(rkey)) {
464
+ throw conflict(`仓库「${rkey}」不在看板「${b.name}」里——组内描述只对成员有意义`);
465
+ }
466
+ const text = String(note || '').trim();
467
+ const info = {
468
+ key: rkey,
469
+ name: (s.repos.find((x) => deriveKey(x) === rkey) || {}).name || rkey,
470
+ board: b.id,
471
+ boardKey: boardKeyOf(b.name),
472
+ boardName: b.name,
473
+ };
474
+ // 描述 = 文档:写 group/<组>/<key>.md;repoNotes 只是摘要影子(由回写维护)
475
+ await writeGroupNoteDoc(info, text);
476
+ return { ...info, note: text };
442
477
  }
443
478
 
444
479
  // 导入:一段 JSON = 一批主题。{boards:[{name, desc?, repos:[{key|name, desc?}]}]}
@@ -212,7 +212,7 @@ export default {
212
212
  flags: {
213
213
  name: { type: 'string' },
214
214
  icon: { type: 'string', hint: '项目图标(emoji 或单字符,≤8 字;留空 = 用默认图标)' },
215
- desc: { type: 'string' },
215
+ desc: { type: 'string', hint: '初始描述(写成项目主篇文档;之后描述以文档为准)' },
216
216
  notes: { type: 'string' },
217
217
  type: { type: 'string', enum: ['dev', 'ref'], hint: 'dev=开发仓库(默认),ref=参考仓库' },
218
218
  remote: { type: 'string', hint: '远程 git 地址(key 的来源;导出时导它)' },
@@ -231,13 +231,13 @@ export default {
231
231
  cli: ['repo', 'update'],
232
232
  http: ['PATCH', '/api/repos/:id'],
233
233
  summary:
234
- '修改仓库路径 / 名称 / 描述 / 备注 / 类型 / 远程地址 / key;--get-loop* 配置项目级「持续 get」(waitgoal:该项目 get 无任务时阻塞等人回填 + 交付文本带继续 get 模板)',
234
+ '修改仓库路径 / 名称 / 备注 / 类型 / 远程地址 / key;--get-loop* 配置项目级「持续 get」(waitgoal:该项目 get 无任务时阻塞等人回填 + 交付文本带继续 get 模板)。描述已改为文档,不再经这里改',
235
235
  args: ['id'],
236
236
  flags: {
237
237
  path: { type: 'string' },
238
238
  name: { type: 'string' },
239
239
  icon: { type: 'string', hint: '项目图标(emoji 或单字符,≤8 字;留空 = 用默认图标)' },
240
- desc: { type: 'string' },
240
+ desc: { type: 'string', hint: '(已废弃)描述是文档:改正文用 docs set,换绑用 docs bind —— 传了会报错' },
241
241
  notes: { type: 'string' },
242
242
  type: { type: 'string', enum: ['dev', 'ref'], hint: 'dev=开发仓库,ref=参考仓库' },
243
243
  remote: { type: 'string', hint: '远程 git 地址' },
@@ -272,7 +272,7 @@ export default {
272
272
  args: ['id'],
273
273
  run: (ctx) => listRepoDocs(ctx.id),
274
274
  render: (d) => {
275
- const one = (x, i) => ` ${i}. ${x.rel ? '自有 ' + x.rel : x.ref ? 'ref ' + x.ref + '/' + x.rel : '外部 ' + x.path}${x.note ? ' #' + x.note : ''}`;
275
+ 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}` : ''}`;
276
276
  const lines = [`【${d.repo.name}】介绍文档 ${d.count} 篇`];
277
277
  if (d.main) lines.push(one(d.main, 1));
278
278
  d.links.forEach((x, i) => lines.push(one(x, i + 2)));
@@ -283,7 +283,7 @@ export default {
283
283
  id: 'repo.doc.add',
284
284
  cli: ['repo', 'doc', 'add'],
285
285
  http: ['POST', '/api/repos/docs'],
286
- summary: '给项目加一篇介绍文档:--rel 自有树路径 / --path 外部绝对路径 / --ref <参考仓库key> --file <仓库内相对路径>',
286
+ summary: '给项目加一篇介绍文档:--rel 自有树路径 / --path 外部绝对路径 / --ref <参考仓库key> --file <仓库内相对路径>(同 rel/path 重复添加 = 更新)',
287
287
  args: ['id'],
288
288
  flags: {
289
289
  rel: { type: 'string', hint: '自有树内相对路径(如 repo/github.com/me/x.md)' },
@@ -291,8 +291,9 @@ export default {
291
291
  ref: { type: 'string', hint: '参考仓库 key(type=ref 的本机仓库)' },
292
292
  file: { type: 'string', hint: '参考仓库内的相对路径(配合 --ref)' },
293
293
  note: { type: 'string', hint: '这篇的说明' },
294
+ tag: { type: 'string', hint: '分类标签(如 qa;简介行渲染成小 chip;空串 = 清掉)' },
294
295
  },
295
- run: (ctx) => addRepoDoc(ctx.id, { rel: ctx.rel, path: ctx.path, ref: ctx.ref, file: ctx.file, note: ctx.note }),
296
+ run: (ctx) => addRepoDoc(ctx.id, { rel: ctx.rel, path: ctx.path, ref: ctx.ref, file: ctx.file, note: ctx.note, tag: ctx.tag }),
296
297
  render: (d) => `已加一篇介绍文档(共 ${d.count} 篇)`,
297
298
  },
298
299
  {
@@ -612,7 +613,7 @@ export default {
612
613
  lines.push(` ◇ 组「${b.name}」`);
613
614
  if (b.intro && !b.intro.missing) lines.push(` 组介绍: ${b.intro.docId}`);
614
615
  if (b.note && !b.note.missing) lines.push(` 组内描述: ${b.note.docId}`);
615
- for (const l of b.docLinks) lines.push(` 绑定: ${l.docId}${l.note ? ` · ${l.note}` : ''}${l.missing ? '(缺失)' : ''}`);
616
+ for (const l of b.docLinks) lines.push(` 绑定: ${l.docId}${l.tag ? ` [${l.tag}]` : ''}${l.note ? ` · ${l.note}` : ''}${l.missing ? '(缺失)' : ''}`);
616
617
  for (const x of b.externalDirs) lines.push(` 外部目录: ${x.path}(${x.files.length} 个文档,按需读盘)`);
617
618
  }
618
619
  if (d.refs.length) {
@@ -14,7 +14,7 @@ import fsp from 'node:fs/promises';
14
14
  import { APP_DIR } from '../../core/paths.js';
15
15
  import { openPath } from '../../core/open.js';
16
16
  import { badInput, notFound, conflict } from '../../core/errors.js';
17
- import { sanitizeDocRef } from '../docs/docref.js';
17
+ import { sanitizeDocRef, withLinkMeta } from '../docs/docref.js';
18
18
  import { sanitizeGetLoop } from '../tasktool/getloop.js';
19
19
 
20
20
  // ─── 存储(NX_KV_REPOS_STORE 可覆盖;测试隔离)──────────────────────────
@@ -94,8 +94,7 @@ function normalizeDocRefs(store) {
94
94
  .map((l) => {
95
95
  const d = sanitizeDocRef(l);
96
96
  if (!d) return null;
97
- const note = l && typeof l.note === 'string' ? l.note.trim() : '';
98
- return note ? { ...d, note } : d;
97
+ return withLinkMeta(d, l);
99
98
  })
100
99
  .filter(Boolean);
101
100
  if (links.length) r.docLinks = links;
@@ -109,8 +108,7 @@ function normalizeDocRefs(store) {
109
108
  .map((l) => {
110
109
  const d = sanitizeDocRef(l);
111
110
  if (!d) return null;
112
- const note = l && typeof l.note === 'string' ? l.note.trim() : '';
113
- return note ? { ...d, note } : d;
111
+ return withLinkMeta(d, l);
114
112
  })
115
113
  .filter(Boolean);
116
114
  if (links.length) b.docLinks = links;
@@ -371,7 +369,7 @@ export function migrateStoreKeys(store) {
371
369
  export async function listRepos() {
372
370
  const s = await loadStore();
373
371
  // docs/paths 反过来依赖本文件的 normalizeKey(动态引入避免静态环)
374
- const { repoDocRel } = await import('../docs/paths.js');
372
+ const { repoDocRel, groupNoteRel } = await import('../docs/paths.js');
375
373
  const boardsOf = new Map(); // repoKey -> [看板投影]
376
374
  for (const b of s.boards) {
377
375
  for (const rk of boardRepoKeys(b, s)) {
@@ -382,11 +380,14 @@ export async function listRepos() {
382
380
  desc: b.desc || '',
383
381
  key: boardKeyOf(b.name),
384
382
  note: (b.repoNotes || {})[rk] || '',
383
+ // 组内描述也是文档:前端点「描述」直接开这篇(绑定优先,缺省约定路径)
384
+ noteDocRel: (b.repoDocs || {})[rk]?.rel || groupNoteRel(b.name, rk),
385
+ noteDocPath: (b.repoDocs || {})[rk]?.path || '',
385
386
  });
386
387
  }
387
388
  }
388
- return s.repos
389
- .map(({ tags: _dropped, ...r }) => {
389
+ const { docSetOf } = await import('../docs/brief.js');
390
+ const rows = s.repos.map(({ tags: _dropped, ...r }) => {
390
391
  const rk = deriveKey(r);
391
392
  return {
392
393
  ...r,
@@ -399,8 +400,10 @@ export async function listRepos() {
399
400
  docRel: r.doc?.rel || repoDocRel(rk),
400
401
  boards: boardsOf.get(rk) || [],
401
402
  };
402
- })
403
- .sort((a, b) => String(a.name).localeCompare(String(b.name)));
403
+ });
404
+ // 描述 = 绑定的文档集(主篇标题 + 补充篇),不再是 desc 字符串
405
+ for (const row of rows) row.descDocs = await docSetOf(row, 'repo');
406
+ return rows.sort((a, b) => String(a.name).localeCompare(String(b.name)));
404
407
  }
405
408
 
406
409
  export async function addRepo(input) {
@@ -416,9 +419,40 @@ export async function addRepo(input) {
416
419
  if (dup) throw conflict(`该 key 已登记为「${dup.name}」(${dup.id}): ${repo.key}`);
417
420
  s.repos.push(repo);
418
421
  });
422
+ await seedRepoDoc(repo);
419
423
  return repo;
420
424
  }
421
425
 
426
+ /**
427
+ * 描述是文档:add 时给的 desc 只是**初始正文**,落到主篇 md(repo/<key>/index.md 的旧单文件位),
428
+ * 再按 md 回写摘要。文档已在就不动——老仓库重登记不该把写过的介绍冲掉。
429
+ * 动态 import 同 listRepos:docs 是叶子,repos 反向依赖它(静态引会成环)。
430
+ */
431
+ async function seedRepoDoc(repo) {
432
+ const desc = String((repo && repo.desc) || '').trim();
433
+ if (!desc) return null;
434
+ const { repoDocRel } = await import('../docs/paths.js');
435
+ const store = await import('../docs/store.js');
436
+ const rel = repoDocRel(repo.key);
437
+ if (await store.ownDocExists(rel)) return null;
438
+ return writeRepoDocContent(repo, desc);
439
+ }
440
+
441
+ /**
442
+ * 把一段文本写成仓库的主篇文档(覆盖正文,标题取仓库名)。
443
+ * 导入覆盖(transfer 的 overwrite 策略)走这里——描述不能再经 updateRepo 的 desc 字段。
444
+ */
445
+ export async function writeRepoDocContent(repo, text) {
446
+ const { repoDocRel } = await import('../docs/paths.js');
447
+ const store = await import('../docs/store.js');
448
+ const { writeBackSummary } = await import('../docs/seed.js');
449
+ const rel = repoDocRel(repo.key);
450
+ const body = `# ${repo.name || repo.key}\n\n${String(text || '').trim()}\n`;
451
+ await store.writeOwnDoc(rel, body);
452
+ await writeBackSummary(rel, body);
453
+ return rel;
454
+ }
455
+
422
456
  export async function updateRepo(id, patch) {
423
457
  return mutateStore((s) => {
424
458
  // 定位:id → key → 绝对路径 → 名称(与 getRepo 同一口径——
@@ -432,7 +466,12 @@ export async function updateRepo(id, patch) {
432
466
  if (!r) throw notFound('repo 不存在: ' + id);
433
467
  if (patch.name !== undefined) r.name = String(patch.name).trim();
434
468
  if (patch.icon !== undefined) r.icon = sanitizeIcon(patch.icon);
435
- if (patch.desc !== undefined) r.desc = String(patch.desc).trim();
469
+ if (patch.desc !== undefined) {
470
+ throw badInput(
471
+ '描述已改为文档(不再是字符串):改正文用 `docs set <rel>`,换绑主篇用 ' +
472
+ '`docs bind --repo <仓库> --rel <路径>`,加补充篇用 `docs link --board <看板> --doc <路径>`'
473
+ );
474
+ }
436
475
  if (patch.notes !== undefined) r.notes = String(patch.notes);
437
476
  if (patch.type !== undefined) {
438
477
  const t = patch.type === 'ref' ? 'ref' : patch.type === 'dev' ? 'dev' : null;
@@ -15,7 +15,7 @@ import { loadConfig } from '../../core/config.js';
15
15
  import { badInput } from '../../core/errors.js';
16
16
  import { makeZip } from '../../core/zip.js';
17
17
  import { md5Of } from '../../core/fstree.js';
18
- import { sanitizeDocRef } from '../docs/docref.js';
18
+ import { sanitizeDocRef, withLinkMeta } from '../docs/docref.js';
19
19
  import { listOwnDocs, writeOwnDoc, externalClosure } from '../docs/store.js';
20
20
  import * as service from './service.js';
21
21
  import * as boards from './boards.js';
@@ -105,11 +105,12 @@ export async function repoExport({ repoKeys, boardKeys, includeUnassigned = true
105
105
  // 文档绑定(v4):组介绍覆盖 / 组级附加列表 / 组内描述覆盖
106
106
  const bdoc = sanitizeDocRef(b.doc);
107
107
  if (bdoc) entry.doc = bdoc;
108
+ // docLinks 条目 = DocRef + 注解(note/tag),注解跟条目一起走(withLinkMeta 统一口径)
108
109
  const links = (Array.isArray(b.docLinks) ? b.docLinks : [])
109
110
  .map((l) => {
110
111
  const d = sanitizeDocRef(l);
111
112
  if (!d) return null;
112
- return l.note ? { ...d, note: String(l.note).trim() } : d;
113
+ return withLinkMeta(d, l);
113
114
  })
114
115
  .filter(Boolean);
115
116
  if (links.length) entry.docLinks = links;
@@ -223,12 +224,11 @@ function parseLayout(json) {
223
224
  }
224
225
 
225
226
  // v2 → v3:没有 key 的条目用 remote/name 现算,让老导出文件也能导入。
226
- // v3 → v4:文档绑定字段做形状归一(非法形状丢弃;带 note 的保留 note)。
227
+ // v3 → v4:文档绑定字段做形状归一(非法形状丢弃;note/tag 注解原样保留)。
227
228
  const refOf = (raw) => {
228
229
  const d = sanitizeDocRef(raw);
229
230
  if (!d) return null;
230
- const note = raw && typeof raw.note === 'string' ? raw.note.trim() : '';
231
- return note ? { ...d, note } : d;
231
+ return withLinkMeta(d, raw);
232
232
  };
233
233
 
234
234
  function normalizeLayout(data) {
@@ -519,12 +519,18 @@ export async function repoImport({
519
519
  }
520
520
  if (strategy === 'overwrite') {
521
521
  const patch = {};
522
+ let descIn = null;
522
523
  for (const f of item.fields) {
524
+ // 描述是文档(不再是字符串字段):攒下来单独写主篇,不进 updateRepo 的 patch
525
+ if (f.field === 'desc') { descIn = inc.desc; continue; }
523
526
  if (f.field === 'type') patch.type = inc.type;
524
527
  else if (f.field === 'remote') patch.remote = inc.remote || '';
525
528
  else patch[f.field] = inc[f.field];
526
529
  }
527
530
  await service.updateRepo(item.local.id, patch);
531
+ if (descIn !== null) {
532
+ await service.writeRepoDocContent({ key: item.key, name: inc.name || item.key }, descIn);
533
+ }
528
534
  updated.push({ key: item.key, fields: item.fields.map((f) => f.field) });
529
535
  continue;
530
536
  }
@@ -627,8 +633,17 @@ export async function repoImport({
627
633
  .catch(() => {});
628
634
  }
629
635
  if (m.note) {
630
- // 组内描述挂在 key 上:占位成员也保留描述,等仓库补齐后自动生效
631
- await boards.setBoardRepoNote({ key: m.key, board: b.id, note: m.note }).catch(() => {});
636
+ // 组内描述挂在 key 上:占位成员也保留描述,等仓库补齐后自动生效。
637
+ // **直接写摘要字段**,不走 setBoardRepoNote —— 后者会把这句话写进
638
+ // group 文档,覆盖刚从 zip 还原的正文(描述以文档为准,文字只是影子)。
639
+ await service
640
+ .mutateStore((s) => {
641
+ const bb = s.boards.find((x) => x.id === b.id);
642
+ if (!bb) return;
643
+ if (!bb.repoNotes) bb.repoNotes = {};
644
+ bb.repoNotes[m.key] = m.note;
645
+ })
646
+ .catch(() => {});
632
647
  }
633
648
  if (!known) {
634
649
  unmatched.push({