nx-kv 0.11.2 → 0.11.4

package/CHANGELOG.md

@@ -4,6 +4,27 @@
 
 ## [Unreleased]
 
+## [0.11.4] - 2026-10-25
+
+### Fixed
+
+- 本地任务页的仓库上下文只显示仓库名与用途，不再展示看板归属（列表 chip 与投递提示同步收敛）。
+
+## [0.11.3] - 2026-10-23 工作空间模块并入清单（子弹窗），不再单独占一个 tab
+
+### Changed
+
+- **工作空间（group）不再是独立模块，也不再单独占一个面板 tab**。它本质就是
+  **清单的设置**——它决定清单按哪一组隔离读写，单独把它抬成一个功能域反而割裂了。
+  - 独立的 `group` 模块目录删除；8 条命令的 **action id / CLI 命令 / HTTP 路由 /
+    参数一字未改**（`nx-kv group list|get|add|update|remove|current|use|members`、
+    `/api/groups*`、`/api/group`），只是住进了清单模块（`src/modules/todo/group.js`）。
+  - 面板顶栏少了一个「工作空间」tab（本地任务 / 清单 / 仓库 / 登录）。
+    清单页工具栏里那颗原本只读的工作空间药丸**变成可点的入口**，点开是**子弹窗**：
+    当前空间、切换、成员、改名、解散、新建，都在那一层里；「成员」再弹一层。
+  - 清单模块同时管理 `todo` 与 `group` 两个资源（`resources: ['todo','group']`），
+    registry 的 CRUD 完备性断言两边都仍然覆盖。
+
 ## [0.11.2] - 2026-10-23 仓库页改成中心清单（扁平，不分组）+ 看板只当标签
 
 ### Changed
@@ -843,7 +864,7 @@
 
 ## [0.1.0] - 2026-09-16
 
-首个版本。KV 清单（todo）的 CLI + Web 面板，对接 GoFrame KV 后端（默认 `47.110.80.47:8988`）。
+首个版本。KV 清单（todo）的 CLI + Web 面板，对接 GoFrame KV 后端（默认 `192.0.2.47:8988`）。
 
 ### Added
 

package/README.md

@@ -3,7 +3,7 @@
 KV 清单（todo）管理中枢。一个 `npx` 命令起一个 Web 面板，同时提供同构 CLI——
 **面板上的每个按钮，底层都是同一条 CLI 命令**，输出 `--json` 即可被任何 agent 直接消费。
 
-对接 GoFrame KV 后端（默认 `http://47.110.80.47:8988`），
+对接 GoFrame KV 后端（默认 `http://192.0.2.47:8988`），
 数据落在**四把 key** 上：`todo:open` / `todo:done` / `todo:freeze` / `todo:topics`。
 
 任务正文还能直接**嵌图片与文档**（标准 markdown：`![说明](fileId)` / `[文件名](fileId)`）——

package/assets/groups.json

@@ -21,6 +21,10 @@
     "kv-timegoal": {
       "skills": ["kv-timegoal"],
       "summary": "把「持续运行 N 小时」任务固化到 nx-kv：每轮回显原文提示词防偏移 + 时间到点自动停手"
+    },
+    "kv-repo": {
+      "skills": ["kv-repo"],
+      "summary": "仓库组识别与关系报告——/kv-repo <组名> 一步加载看板相关项目；board/repo 查询、读并维护领域描述（中心/终端、关键路径、搜索关键词）"
     }
   }
 }

package/assets/kv-repo/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: kv-repo
+description: 识别并汇报本机仓库的相关分组（仓库组）——快捷入口 `/kv-repo <组名>`：一步到位加载该看板的成员仓库、领域描述与配合关系，输出关系报告。用 nx-kv repo / board 命令回答「这台机器上有哪些仓库、按领域怎么分组、组内谁是中心谁是终端、关键路径与搜索关键词在哪」。看板的领域描述（desc）+ 成员仓库的组内描述（note：它在组里的角色）共同构成写给 agent 读的上下文——领域侧重、仓库间配合关系（如 fr 组内 API 关联、go-ah 为 OIDC 中心其余为终端）、入口路径、搜什么关键词。触发词：/kv-repo、kv-repo、仓库组、相关仓库、这个仓库属于哪个组、组里都有什么、它们什么关系、中心/终端、领域描述、关键路径、加载 fr 的看板、看板相关项目、board list、repo list。反例：登记/扫描/增删仓库与看板用 nx-kv 主 skill 的 repo-registry；git 状态与 diff 一律找 git 自己。
+---
+
+# kv-repo — 仓库组识别与关系报告
+
+回答两类问题：**「这组仓库是什么、怎么配合」**（给人看的关系报告）和
+**「我现在这个任务该去哪些仓库找上下文」**（给 agent 自己用的定位）。
+数据都在 nx-kv 的仓库模块里，两条命令足够。
+
+## 快捷 SOP：`/kv-repo <组名|仓库名|路径>`
+
+**带参数就是一步到位，不要反问、不要展开流程**：定位组 → 拉成员与领域描述 → 直接输出该组的关系报告。
+
+```bash
+nx-kv board list --json
+# → { boards:[{ id, name, desc, repos:[{ id, name, desc, path }] }], unassigned:[…] }
+```
+
+- 参数是**组名**（如 `/kv-repo fr`）→ 在 `boards[]` 里按 name 找到它（找不到再试包含匹配），取该组输出报告；
+- 参数是**仓库名或路径**（如 `/kv-repo go-ah`、`/kv-repo D:\code\a_go\proj\go-ah`）→ `nx-kv repo list --json` 定位仓库，报告它 `boards[]` 里的**每个**组（一个仓库可同时归入多个组）；
+- 本地任务的上下文若已带 repo/boards，直接用，不必重查。
+
+报告形状（desc 里的关键路径与关键词**原样带上**——它们是前人留下的搜索入口）：
+
+```
+【fr】Flutter 客户端组 —— 组内共享 API 契约
+  fr      D:\code\a_dart\prj\fr      （组内）API 契约方：lib/api/ 是唯一入口，搜 fr_ 前缀
+  …
+（领域描述）<组的 desc 全文>
+```
+
+每行优先读**组内描述（note）**——它讲这个仓库在本组里的角色；没写 note 再回退仓库自己的 desc。
+组领域描述（desc）与各仓库的关键路径 / 关键词**原样带上**——它们是前人留下的搜索入口。
+
+**无参数**（`/kv-repo`）：输出全部组速览——每行「组名 · 成员数 · desc 首行」+ 未分组计数，
+然后问用户要深入哪一组（只问这一次，别连环追问）。
+
+## 模型（30 秒版）
+
+- **仓库登记** = 本机事实（name / path / desc / notes），一张中心清单。
+- **看板** = 领域分组；一个仓库可同时归入多个组，分组只此一条路（没有标签）。
+- **看板的领域描述（desc）+ 成员的组内描述（note）是写给你（agent）读的上下文**：
+  desc 讲这个领域的侧重与配合方式；note 讲单个仓库在组里的角色（谁是中心 / 终端、
+  API 关联在哪、关键路径、搜什么关键词）。**接到任务先读它们，比翻代码快。**
+
+## 完整命令（速查）
+
+```bash
+nx-kv board list --json          # 首选：全部组 + 成员（含组内描述 note）+ 各组领域描述
+# → { boards:[{ id, name, desc, repos:[{ id, name, desc, path, note }] }], unassigned:[…] }
+nx-kv repo list --json           # 扁平清单，每条带 boards[]（查单个仓库的归属）
+nx-kv repo get <id|绝对路径> --json   # 单仓库详情 + 所在组
+nx-kv board get <id> --json          # 单组详情（成员 + 组内描述）
+nx-kv board note <id|绝对路径> --board <看板id> --note "角色/配合关系/关键路径/关键词"
+                                     # 写或清（--note 留空 = 清除）组内描述
+```
+
+定位顺序：拿到任务/目录 → `repo list` 按**路径或目录名**找到仓库
+→ 它的 `boards[]` 给出所属组 → 回 `board list` 读该组的 `desc` 与**兄弟仓库**。
+
+## 维护：发现过期就修（这是本 skill 的另一半职责）
+
+读到的 desc 与代码现实不符（路径变了、关系变了、压根没写）时，顺手补上：
+
+```bash
+nx-kv board update <id> --desc "侧重…；谁配合谁（谁是中心/终端、API 关联在哪）；关键路径…；搜索关键词…"
+nx-kv board note <仓库id|路径> --board <看板id> --note "这个仓库在组里的角色…；关键路径…；搜什么"
+```
+
+写领域描述的约定（一个看板一个领域，侧重各不相同）：
+
+1. **一句话侧重**：这组仓库共同在做什么；
+2. **配合关系**：谁是中心、谁是终端、谁调谁的 API（如 fr 组内 API 关联、go-ah 与其接入方）——组级关系写看板 desc，单个仓库的角色写 board note；
+3. **关键路径**：契约文件 / 配置 / 入口代码的位置（如 `lib/api/`、`issuer 192.0.2.47:8082`）；
+4. **搜索关键词**：下次 agent 该搜什么（如 `fr_` 前缀、模块名）。
+
+## 边界
+
+- 本 skill **只读分组与描述**；登记/扫描/增删仓库看板走 nx-kv 主 skill（repo-registry）。
+- 不碰 git：状态 / diff / pull / push 一律直接用 git 自己。
+- 数据按 groupId 隔离，查询前先确认工作空间对不对（`nx-kv group current`）。

package/assets/nx-kv/SKILL.md

@@ -34,6 +34,11 @@ nx-kv group current          # 当前工作空间
 数据按 `groupId` 隔离。**先确认工作空间对不对**——在错的空间里会「什么都查不到」，
 而那不是「没有任务」，是「看错地方了」。
 
+> 工作空间是**清单的设置**（不是独立功能域）：面板上没有单独的「工作空间」页，
+> 入口在**清单页**工具栏里那颗可点的工作空间药丸 —— 点开是子弹窗，
+> 切换 / 成员 / 改名 / 解散 / 新建都在那儿。命令与路由一字未改
+> （`nx-kv group ...`、`/api/groups*`）。
+
 ## 最常用的四条
 
 ```bash

package/assets/nx-kv/references/repo-registry.md

@@ -6,8 +6,9 @@
 
 - 用户问「这台机器上有哪些仓库 / 某个仓库在哪」
 - 需要把某个目录登记为受管仓库，或扫描某目录批量发现仓库
-- 需要维护仓库的元信息：名称、描述、标签、备注，或改登记路径
+- 需要维护仓库的元信息：名称、描述、备注，或改登记路径
 - **需要 git 状态、差异、拉取、推送时不要进这里**——本工具不提供 git 操作（见下）
+- **只查分组与关系（不改动）时用 [[kv-repo]]**——那是仓库组的查询/报告侧
 
 ## 边界：本工具不管 git
 
@@ -35,7 +36,6 @@ git -C <path> pull --no-edit
   "id": "r_xxx",
   "name": "ext",
   "path": "D:\\a_js\\js_proj\\br_controller\\ext",
-  "tags": ["eco-import"],
   "desc": "对外扩展模块",
   "notes": "",
   "addedAt": "…",
@@ -44,8 +44,10 @@ git -C <path> pull --no-edit
 ```
 
 - **id 或绝对路径**都能定位仓库（agent 直接给路径更省事）
-- tags 是自由标签数组，用于分组
 - 路径不必是 git 仓库：登记不校验目录内容，也不要求目录存在
+- **没有标签**：分组只走看板一条路（2026-10-24 废除仓库 tags，两套平行分组只会打架）
+- **看板的 desc 是领域描述**：写该组仓库的侧重、配合关系（谁是中心/终端）、
+  关键路径与搜索关键词——它是给人和 agent 读的上下文，写法约定见 [[kv-repo]]
 
 ## SOP
 
@@ -59,7 +61,7 @@ nx-kv repo list --json          # 程序消费
 ### 2. 登记
 
 ```bash
-nx-kv repo add <path> [--name N] [--desc D] [--tags a,b] [--notes T]
+nx-kv repo add <path> [--name N] [--desc D] [--notes T]
 ```
 
 - `name` 缺省取目录名
@@ -80,7 +82,7 @@ nx-kv repo scan [root] [--depth 3] [--dry-run]   # 不带 --dry-run 会真的全
 
 ```bash
 nx-kv repo get <id|path> [--json]
-nx-kv repo update <id> [--name N] [--desc D] [--tags a,b] [--notes T] [--path P]
+nx-kv repo update <id> [--name N] [--desc D] [--notes T] [--path P]
 ```
 
 - `update --path` 用来纠正登记错位的目录；改到**已被别的记录占用**的路径会显式报错

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

@@ -7,7 +7,7 @@
 
 1. **命令就绪**：`nx-kv` 在可执行路径上（`npx nx-kv` 亦可）
 2. **登录态**：`nx-kv auth login <email>`，token 存 `~/.nx-kv/config.json`
-3. **后端可达**：默认 `http://47.110.80.47:8988`；用 `--baseUrl` 临时覆盖，或写进配置
+3. **后端可达**：默认 `http://192.0.2.47:8988`；用 `--baseUrl` 临时覆盖，或写进配置
 
 所有清单操作都需要登录，否则报「未登录」并 exit 1。
 

package/package.json

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

package/src/core/config.js

@@ -14,7 +14,7 @@ export function configPathFromEnv() {
   return process.env.NX_KV_CONFIG || CONFIG_PATH;
 }
 
-export const DEFAULT_BASE_URL = 'http://47.110.80.47:8988';
+export const DEFAULT_BASE_URL = 'http://192.0.2.47:8988';
 
 const EMPTY = () => ({
   baseUrl: process.env.NX_KV_BASE_URL || DEFAULT_BASE_URL,

package/src/modules/localtask/view.jsx

@@ -850,21 +850,14 @@ export default function SessionTaskView() {
                       <strong>{row.name}</strong>
                       {row.isGlobal && <span className="tag badge">全局池</span>}
                       {t?.manual && <span className="tag">已登记</span>}
-                      {/* 仓库上下文（= 周围联系）：这个目录属于哪个已登记仓库、
-                          它又关联着哪些看板。一枚 chip，不占额外一行。 */}
+                      {/* 仓库上下文：这个目录属于哪个已登记仓库。一枚 chip 一行不占。
+                          看板归属不在本地任务页显示（太吵）——要看去「仓库」页。 */}
                       {t?.repo && (
                         <span
                           className="tag repo-boards"
-                          title={
-                            `仓库「${t.repo.name}」${t.repo.desc ? '：' + t.repo.desc : ''}` +
-                            (t.repo.boards?.length
-                              ? `\n所属看板：${t.repo.boards.map((b) => b.name).join('、')}`
-                              : '\n（未归入任何看板）')
-                          }
+                          title={`仓库「${t.repo.name}」${t.repo.desc ? '：' + t.repo.desc : ''}`}
                         >
-                          {t.repo.boards?.length
-                            ? t.repo.boards.map((b) => b.name).join(' · ')
-                            : t.repo.name}
+                          {t.repo.name}
                         </span>
                       )}
                       {row.cwd && cwdTail.length > 0 && (
@@ -1098,17 +1091,12 @@ export default function SessionTaskView() {
 
       {active && showQueue && (
         <>
-          {/* 仓库上下文提示：投递到这个目录时，先告诉用户「这是哪个仓库、
-              周围关联哪些看板」——写任务时不用再切到「仓库」页去查。 */}
+          {/* 仓库上下文提示：投递到这个目录时，先告诉用户「这是哪个仓库、干什么用」——
+              写任务时不用再切到「仓库」页去查。看板归属不在这里显示。 */}
           {active.repo && (
             <div className="compose-context">
               <span className="repo-name">仓库 {active.repo.name}</span>
               {active.repo.desc ? <span className="repo-desc">{active.repo.desc}</span> : null}
-              {active.repo.boards?.length ? (
-                <span className="repo-boards-list">
-                  看板：{active.repo.boards.map((b) => b.name).join('、')}
-                </span>
-              ) : null}
             </div>
           )}
           <div className="toolbar compose-toolbar">

package/src/modules/repos/boards.js

@@ -3,21 +3,31 @@
 // 与 repo 登记的关系：看板只存 id 引用，登记数据（name/desc/path…）的唯一真相在 s.repos——
 // 删看板不动登记，删登记要同步摘引用（见 service.js 的 removeRepo）。
 // 本文件不含传输层概念（不认识 argv 与 HTTP）。
+import { resolve } from 'node:path';
 import { loadStore, mutateStore, newId } from './service.js';
 import { badInput, notFound, conflict } from '../../core/errors.js';
 
 // 卡片投影：面板方格与 CLI 速览共用的最小字段
-const card = (r) => ({ id: r.id, name: r.name, desc: r.desc, path: r.path, tags: r.tags || [] });
+const card = (r) => ({ id: r.id, name: r.name, desc: r.desc, path: r.path });
 
 const cleanText = (v) => String(v || '').trim();
 
+// 组内描述：同一个仓库在不同看板里的角色可以各不相同（「fr 组里它是 API 契约方」，
+// 「nx 组里它只是同族工具」），所以描述挂在**看板的成员关系**上（repoNotes），
+// 而不是仓库登记上。登记里的 desc 回答「这个仓库是干什么的」，
+// 组内描述回答「它在这个组里占什么位置、怎么配合」。
+const noteOf = (b, rid) => (b.repoNotes || {})[rid] || '';
+
 export async function listBoards() {
   const s = await loadStore();
   const inBoard = new Set(s.boards.flatMap((b) => b.repoIds || []));
-  const reposOf = (ids) =>
-    ids.map((id) => s.repos.find((r) => r.id === id)).filter(Boolean).map(card);
+  const reposOf = (b) =>
+    (b.repoIds || [])
+      .map((id) => s.repos.find((r) => r.id === id))
+      .filter(Boolean)
+      .map((r) => ({ ...card(r), note: noteOf(b, r.id) }));
   return {
-    boards: s.boards.map((b) => ({ id: b.id, name: b.name, desc: b.desc, repos: reposOf(b.repoIds || []) })),
+    boards: s.boards.map((b) => ({ id: b.id, name: b.name, desc: b.desc, repos: reposOf(b) })),
     unassigned: s.repos.filter((r) => !inBoard.has(r.id)).map(card),
   };
 }
@@ -26,7 +36,10 @@ export async function getBoard(id) {
   const s = await loadStore();
   const b = s.boards.find((x) => x.id === id);
   if (!b) throw notFound('看板不存在: ' + id);
-  const repos = (b.repoIds || []).map((rid) => s.repos.find((r) => r.id === rid)).filter(Boolean).map(card);
+  const repos = (b.repoIds || [])
+    .map((rid) => s.repos.find((r) => r.id === rid))
+    .filter(Boolean)
+    .map((r) => ({ ...card(r), note: noteOf(b, r.id) }));
   return { id: b.id, name: b.name, desc: b.desc, repos };
 }
 
@@ -87,12 +100,15 @@ export async function assignRepo({ id, board, before, remove } = {}) {
           target.repoIds.splice(at, 1);
           n = 1;
         }
+        // 摘出成员时组内描述一起带走（它只对这个成员关系有意义）
+        if (target.repoNotes && n) delete target.repoNotes[id];
       } else {
         for (const b of s.boards) {
           const at = (b.repoIds || []).indexOf(id);
           if (at >= 0) {
             b.repoIds.splice(at, 1);
             n += 1;
+            if (b.repoNotes) delete b.repoNotes[id];
           }
         }
       }
@@ -115,6 +131,32 @@ export async function assignRepo({ id, board, before, remove } = {}) {
   });
 }
 
+// 设置组内描述：id = 仓库（id 或绝对路径均可），board = 看板 id。
+// 只对**已在板内**的成员有意义——不是成员就显式报错，别静默挂到没人读的地方。
+// note 为空 = 清除。
+export async function setBoardRepoNote({ id, board, note } = {}) {
+  if (!id) throw badInput('缺少仓库 id 或路径');
+  if (!board) throw badInput('缺少看板 id（--board）');
+  return mutateStore((s) => {
+    let repo = s.repos.find((r) => r.id === id);
+    if (!repo) {
+      const p = resolve(String(id));
+      repo = s.repos.find((r) => r.path.toLowerCase() === p.toLowerCase());
+    }
+    if (!repo) throw notFound('repo 不存在: ' + id);
+    const b = s.boards.find((x) => x.id === board);
+    if (!b) throw notFound('看板不存在: ' + board);
+    if (!(b.repoIds || []).includes(repo.id)) {
+      throw conflict(`仓库「${repo.name}」不在看板「${b.name}」里——组内描述只对成员有意义`);
+    }
+    const text = String(note || '').trim();
+    if (!b.repoNotes) b.repoNotes = {};
+    if (text) b.repoNotes[repo.id] = text;
+    else delete b.repoNotes[repo.id];
+    return { id: repo.id, name: repo.name, board: b.id, boardName: b.name, note: text };
+  });
+}
+
 // 导入：一段 JSON = 一批主题。{boards:[{name, desc?, repos:[{path|name, desc?}]}]}
 // 条目按 path（大小写不敏感）或名称匹配**已登记**仓库——导入不硬造登记，
 // 匹配不上的如实报告（数量与清单）。同名看板 = 合并（追加匹配到的仓库）。
@@ -162,13 +204,18 @@ export async function importBoards({ json } = {}) {
           b.repoIds.push(id);
           matched += 1;
         }
+        const note = cleanText(e.note);
+        if (note) {
+          if (!b.repoNotes) b.repoNotes = {};
+          b.repoNotes[id] = note;
+        }
       }
     }
     return { created, merged, matched, unmatched };
   });
 }
 
-// 导出：看板 + 仓库的 path/name/desc（可回灌给 import 的同一结构）
+// 导出：看板 + 仓库的 path/name/desc + 组内描述 note（可回灌给 import 的同一结构）
 export async function exportBoards() {
   const s = await loadStore();
   return {
@@ -177,9 +224,13 @@ export async function exportBoards() {
       name: b.name,
       desc: b.desc,
       repos: (b.repoIds || [])
-        .map((id) => s.repos.find((r) => r.id === id))
-        .filter(Boolean)
-        .map((r) => ({ path: r.path, name: r.name, desc: r.desc })),
+        .map((id) => {
+          const r = s.repos.find((x) => x.id === id);
+          if (!r) return null;
+          const note = noteOf(b, id);
+          return note ? { path: r.path, name: r.name, desc: r.desc, note } : { path: r.path, name: r.name, desc: r.desc };
+        })
+        .filter(Boolean),
     })),
   };
 }

package/src/modules/repos/index.js

@@ -42,7 +42,7 @@ function renderRepoList(list) {
   if (!list.length) return '（暂无仓库，用 repo add <path> 登记）';
   const lines = [`共 ${list.length} 个仓库`];
   for (const r of list) {
-    lines.push(`${r.name.padEnd(18)} ${r.path}  ${r.tags.length ? '[' + r.tags.join(',') + ']' : ''}`);
+    lines.push(`${r.name.padEnd(18)} ${r.path}`);
   }
   return lines.join('\n');
 }
@@ -52,10 +52,12 @@ function renderRepo(r) {
     `${r.name}${r.desc ? '  ' + r.desc : ''}`,
     `  id:    ${r.id}`,
     `  路径:  ${r.path}`,
-    `  标签:  ${r.tags.length ? r.tags.join(', ') : '-'}`,
     `  登记:  ${(r.addedAt || '').slice(0, 10)}`,
     `  更新:  ${(r.updatedAt || '').slice(0, 10)}`,
   ];
+  if (r.boards?.length) {
+    lines.push(`  看板:  ${r.boards.map((b) => b.name).join('、')}`);
+  }
   if (r.notes) lines.push('  备注:  ' + r.notes);
   return lines.join('\n');
 }
@@ -100,7 +102,6 @@ export default {
       flags: {
         name: { type: 'string' },
         desc: { type: 'string' },
-        tags: { type: 'array' },
         notes: { type: 'string' },
       },
       run: (ctx) => service.addRepo(ctx),
@@ -110,13 +111,12 @@ export default {
       id: 'repo.update',
       cli: ['repo', 'update'],
       http: ['PATCH', '/api/repos/:id'],
-      summary: '修改仓库路径 / 名称 / 描述 / 标签 / 备注',
+      summary: '修改仓库路径 / 名称 / 描述 / 备注',
       args: ['id'],
       flags: {
         path: { type: 'string' },
         name: { type: 'string' },
         desc: { type: 'string' },
-        tags: { type: 'array' },
         notes: { type: 'string' },
       },
       run: (ctx) => service.updateRepo(ctx.id, ctx),
@@ -235,6 +235,23 @@ export default {
         ? `已移出: ${d.name}（${d.count} 个看板）`
         : `${d.added ? '已聚合' : '已在（位次已调）'}: ${d.name} → ${d.board}`),
     },
+    {
+      // 组内描述：同一个仓库在不同看板里的角色各不相同，描述挂在成员关系上而非登记上。
+      // 登记的 desc = 「这个仓库是干什么的」；组内描述 = 「它在这个组里占什么位置、怎么配合」。
+      id: 'board.note',
+      cli: ['board', 'note'],
+      http: ['POST', '/api/boards/note'],
+      summary: '写/清组内描述：仓库在看板里的角色与配合关系（--note 留空 = 清除；仓库给 id 或绝对路径）',
+      args: ['id'],
+      flags: {
+        board: { type: 'string', required: true, hint: '看板 id' },
+        note: { type: 'string', hint: '组内描述（多行可含关键路径/关键词；留空 = 清除）' },
+      },
+      run: (ctx) => boards.setBoardRepoNote({ id: ctx.id, board: ctx.board, note: ctx.note }),
+      render: (d) => (d.note
+        ? `已写组内描述: ${d.name} @ 「${d.boardName}」`
+        : `已清除组内描述: ${d.name} @ 「${d.boardName}」`),
+    },
     {
       id: 'board.import',
       cli: ['board', 'import'],

package/src/modules/repos/service.js

@@ -80,19 +80,14 @@ export function newId(prefix) {
   return prefix + '_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 7);
 }
 
-function parseTags(tags) {
-  if (Array.isArray(tags)) return tags.map((t) => String(t).trim()).filter(Boolean);
-  if (typeof tags === 'string') return tags.split(',').map((t) => t.trim()).filter(Boolean);
-  return [];
-}
-
-function normalizeRepoInput({ path, name, tags, notes, desc }) {
+// 标签已废除（2026-10-24）：分组只走看板一条路，两套平行的分组机制只会互相打架。
+// 旧数据里残留的 tags 字段留在盘上不动，但不再写入、不再外发。
+function normalizeRepoInput({ path, name, notes, desc }) {
   const abs = resolve(String(path || ''));
   return {
     id: newId('r'),
     name: (name || basename(abs) || 'repo').trim(),
     path: abs,
-    tags: parseTags(tags),
     desc: (desc || '').trim(),
     notes: (notes || '').trim(),
     addedAt: new Date().toISOString(),
@@ -119,11 +114,11 @@ export async function listRepos() {
   for (const b of s.boards) {
     for (const rid of b.repoIds || []) {
       if (!boardsOf.has(rid)) boardsOf.set(rid, []);
-      boardsOf.get(rid).push({ id: b.id, name: b.name, desc: b.desc || '' });
+      boardsOf.get(rid).push({ id: b.id, name: b.name, desc: b.desc || '', note: (b.repoNotes || {})[rid] || '' });
     }
   }
   return s.repos
-    .map((r) => ({ ...r, boards: boardsOf.get(r.id) || [] }))
+    .map(({ tags: _dropped, ...r }) => ({ ...r, boards: boardsOf.get(r.id) || [] }))
     .sort((a, b) => String(a.name).localeCompare(String(b.name)));
 }
 
@@ -144,7 +139,6 @@ export async function updateRepo(id, patch) {
     const r = s.repos.find((x) => x.id === id);
     if (!r) throw notFound('repo 不存在: ' + id);
     if (patch.name !== undefined) r.name = String(patch.name).trim();
-    if (patch.tags !== undefined) r.tags = parseTags(patch.tags);
     if (patch.desc !== undefined) r.desc = String(patch.desc).trim();
     if (patch.notes !== undefined) r.notes = String(patch.notes);
     if (patch.path !== undefined) {
@@ -183,7 +177,8 @@ export async function getRepo(idOrPath) {
   const boards = s.boards
     .filter((b) => (b.repoIds || []).includes(r.id))
     .map((b) => ({ id: b.id, name: b.name, desc: b.desc || '' }));
-  return { ...r, boards };
+  const { tags: _dropped, ...base } = r;
+  return { ...base, boards };
 }
 
 const SKIP_DIRS = new Set([
@@ -320,7 +315,7 @@ export async function contextMap() {
   for (const b of s.boards) {
     for (const rid of b.repoIds || []) {
       if (!boardsOf.has(rid)) boardsOf.set(rid, []);
-      boardsOf.get(rid).push({ id: b.id, name: b.name, desc: b.desc || '' });
+      boardsOf.get(rid).push({ id: b.id, name: b.name, desc: b.desc || '', note: (b.repoNotes || {})[rid] || '' });
     }
   }
   const map = new Map();
@@ -329,7 +324,6 @@ export async function contextMap() {
       id: r.id,
       name: r.name,
       path: r.path,
-      tags: r.tags || [],
       desc: r.desc || '',
       notes: r.notes || '',
       boards: boardsOf.get(r.id) || [],