nx-kv 0.12.0 → 0.15.0

package/CHANGELOG.md

@@ -2,10 +2,144 @@
 
 本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
-## [0.12.0] - 2026-10-30 仓库身份改用全局唯一 key + 导入导出重做
+## [0.15.0] - 2026-10-31 仓库详情页 + desc 升级成 md 列表
+
+### Added
+
+- **仓库详情页 `#/repo/<key>`**：一个仓库的信息（key / 远程 / 路径 / 备注 / 项目组）、
+  **md 描述文档**（按份渲染，可切 tab）、**相关任务**（本机队列按 cwd 匹配到它，
+  待领取 / 已领取分列，可一键跳工作台）。侧边栏点项目、列表点 md chip 都落这一页。
+- **`docs` 字段：仓库内 md 的相对路径列表**。desc 从此只是摘要，详细说明写 md：
+  `repo add/update --docs README.md,docs/arch.md`、`repo doc <id> --path …` 读正文。
+  只收仓库内相对路径（绝对路径 / `..` / 非 md 拒收），读正文有越界、不存在、
+  512KB 上限三类显式错误；导出布局不带 md 正文。
+- 仓库列表行的 desc 下面多一排 `md` chip（点一下直达详情页那一份）。
+
+### Changed
+
+- **侧边栏的项目行点击 = 进仓库详情页**。以前是「展开任务子行」，于是**没有队列的
+  仓库点了没反应**（它唯一去处是工作台，而空队列没有 topicKey）。现在行点击一律有去处，
+  展开任务子行改点左边的箭头（有队列才画箭头）；详情页里也能看到任务并跳工作台。
+- 侧边栏行的 tooltip 会列出该仓库的 md 文档。
+
+### 证据
+
+`tests/unit/repos-docs.test.mjs`（7 条：路径清洗、增改查口径、三类读错误、导出不带正文）。
+全量：lint 干净 / build 通过 / unit 303 / smoke 158。CLI 与面板都实测（无头 Chrome
+点侧边栏 → `#/repo/…`，md 渲染、任务列表、md chip 均正常）。
+
+## [0.14.0] - 2026-10-31 仓库身份只有两个来源：远程地址 / 自定义 key；都没有就冻结
+
+### Added
+
+- **编辑仓库弹窗可自定义 key**（原来只有 CLI 能设）。留空 = 跟随远程地址，填了 =
+  自定义身份。表单里实时说明当前这条的身份来自哪儿。
+- **冻结**：既没有远程地址、也没有自定义 key 的仓库被明确标成「无 key · 冻结」
+  （仓库表格徽标 + `repo list` / `repo add` 的 CLI 输出）。它照常能在本机用
+  （侧边栏、本地任务、绑定、进项目组），但**不参与导出导入**：导出时仓库本体被跳过，
+  项目组里的冻结成员也从导出的成员表里剔除，并如实告警——因为没有 key，
+  映射到「另一台机器上的同一个仓库」这件事本身就无意义。
+- CLI：`repo key refresh` 对没有远程地址的仓库不再建议 `local/<名称>` 兜底，
+  改为说明「无法派生 key：用 repo key set 自定义或补 remote，否则冻结」。
+
+### Changed
+
+- **`local/<名称>` 不再是身份**：它退化为纯内部锚点（本机关系要有落点），
+  不再冒充 key 参与导出、也不再参与导入匹配。
+- **改 key = 换身份，关系跟着搬**：项目组成员、组内描述、参考绑定会在 key 变化时
+  一起重映射。以前改 key（自定义或换 remote 派生）会把关系断在旧 key 上，
+  表现为「仓库莫名从项目组里掉了」。
+- 冻结的仓库不参与 key 唯一性检查：两份同名副本（如两个 `nx-kv` 目录）可以各自登记。
+- **仓库页去掉「扫描」按钮**（连同它的弹窗与结果卡片）：登记入口统一走「添加仓库」。
+  CLI 的 `nx-kv repo scan` 仍然保留（`--dry-run` 只发现不登记），需要时用命令跑。
+
+### 证据
+
+`tests/unit/repos-frozen-key.test.mjs`（11 条）钉住身份判定、冻结的导出行为、
+自定义 key 往返、改 key 搬关系、同名不冲突。全量：lint 干净 / build 通过 /
+unit 296 / smoke 158。
+
+## [0.13.0] - 2026-10-30 项目 / 项目组是资产，收纳组只是显示；remote 批量对齐
+
+### Changed
+
+- **侧边栏的层级错了，改正：项目组（看板）不是仓库的父目录。**
+  项目（仓库）与项目组（看板）是**并列的资产**——两者都能被编排、都能挂参考，
+  项目组内部装的是「开发仓库 + 参考仓库」（那是数据），但侧边栏不再把它画成
+  装仓库的文件夹：一条仓库属于某个项目组，仍然在顶层自己出现。
+  以前 board 行里嵌 repo 行，读起来就是「仓库属于它、移动就改归属」。
+- **左侧的「组」回到侧边栏，但只是显示层（收纳组）**：把项目/项目组摆在一起的
+  格子（类似压缩包），存在 `prefs.groups`（浏览器本地），不写 store、不进导出。
+  一条资产最多在一个盒子里；解散盒子只拆格子，资产一个都不少。
+  与项目组的分工写死在菜单措辞里：**「归入项目组 X」= 数据**（store 里的成员表，
+  会导出、跨机可见），**「放进收纳组 X」= 显示**（只影响我怎么看）。
+- **「对齐 remote」从一个仓库一个按钮改成一次扫全部**：判断该换哪条 remote 的依据
+  全在数据里（`git remote -v` + 登记采纳值 + key 派生），所以仓库页右上给一个
+  「对齐 remote」按钮：一屏列出 remote 现状（可替换 / 无 remote / 登记悬空 / 目录不可用），
+  带建议与「全部按建议对齐」。行内的 remote 按钮已去掉。
+  **清单只含开发仓库**：参考仓库的 remote 就是它 clone 的来源兼 key，没有「换一条」的
+  余地，列进来只是几十行噪音（它们的健康度看 `repo ref check`）。要看参考仓库得
+  显式 `--type ref`，两类一起是 `--type all`。
+- 侧边栏点项目组 = 去仓库页筛选到这一组（`#/repos?board=<id>`）——项目组没有独立
+  页面，它的成员、组级参考仓库、组内描述都长在仓库页上。
+
+### Fixed
+
+- **侧边栏拖拽在稀疏排序下「拖了没反应」**：`prefs.order` 只存用户动过的条目，
+  拖到一个从没排过序的目标上时 `order.indexOf(target)` 是 -1，旧实现直接放弃。
+  现在以「当前渲染序」为落点基准，结果写回完整序列，顺序完全确定。
+- 拖进收纳组会自动展开盒子（否则拖完像是东西消失了）。
 
 ### Added
 
+- `repo remote scan [--type dev|ref]`（HTTP `GET /api/repos/remote/scan`）：
+  批量扫描全部仓库的 remote 现状并给建议。**只读本地 git 配置、不发网络请求**，
+  所以够快；远端存在性仍是按需的 `repo remote check`。
+- `repo remote align`（HTTP `POST /api/repos/remote/align`，body `items`）：
+  整批落盘（自定义 key 只改 remote，不覆盖 key）。
+- 测试：`tests/unit/sidebar-model.test.mjs`（15 条，钉住「资产 vs 收纳组」与拖拽落点）、
+  `tests/unit/repos-remote-scan.test.mjs`（10 条，钉住 scan 的判定与批量对齐）。
+  全量：lint 干净、build 通过、unit 285、smoke 158。
+
+## [0.12.1] - 2026-10-30 key 归一化修复 + remote 对齐反馈
+
+### Fixed
+
+- **keyFromRemote 在 Linux 上多一个前导斜杠**：同一地址在「派生」（keyFromRemote）与
+  「归一」（normalizeKey）两条路上算出的 key 必须一致。Linux 的 `file:///tmp/x` 剥协议后
+  带前导斜杠，于是「派生」得 `/tmp/x`、「归一」得 `tmp/x` —— 同一份数据算出两个 key，
+  导入时参考关系直接连不上（「参考仓库不存在」）。Windows 上是盘符所以走不到这个分支，
+  只有 CI 红。keyFromRemote 的结果现在就规范化（它是「key 的来源」，不该产出非规范形态）。
+- **remote 对齐弹窗的「检查」点了像没反应**：git ls-remote 要几秒，期间界面毫无变化；
+  出错又被 toast 吞掉（一闪而过）。改成点击即显示「检查中…」，错误原因直接写进弹窗
+  （错误信息不该只活 3 秒）。
+
+### Changed
+
+- 并入三个工作树的成果：md-desc（关系改 key + 导入占位 + remote 对齐）、
+  sidebar-repo-boards（侧边栏改用仓库登记 + 看板）、fix-checkbox-width
+  （勾选框被 width:100% 撑满 → 选项列表看着一片空白）。
+
+## [0.12.0] - 2026-10-30 仓库身份改用全局唯一 key + 导入导出重做
+
+### Changed
+
+- **侧边栏不再自建一套「目录 + 分组」，改为直接用仓库登记与看板**。
+  以前侧边栏的「目录」是本地任务队列按 cwd 自动生成的主题，「分组」存在浏览器
+  localStorage 里（`prefs.groups` / `prefs.dirGroups`）——后者与仓库页的看板是
+  **两套互不相干的数据**：换浏览器分组就没了，改看板侧边栏也不知道。
+  现在：
+  - 目录行 = **仓库登记**里的开发仓库（带全局唯一 key、描述、路径）；
+  - 分组行 = **看板**（展开看成员），归属关系就是看板的成员表；
+  - 侧边栏只保留纯 UI 偏好：排序、隐藏、展开态、收起态（`prefs` 里的
+    `groups` / `dirGroups` 已废弃并在读取时从 localStorage 抹掉）；
+  - 行菜单改操作真实数据：「归入/移出看板」走 `board assign`，
+    「＋」菜单变成「登记仓库 / 新建看板」（原来建的是任务队列主题，不是仓库登记）；
+  - 拖拽只改顺序（显示态），归属一律走行菜单——拖拽不再写本地分组。
+- 仓库模块：看板成员从随机 id（`repoIds`）迁到 **key**（`repoKeys`），读时自动
+  迁移并落盘；绑定目标同样记 key；`keyFromRemote` 剥 `file://` URL 的盘符冒号
+  （否则 `normalizeKey` 会把 `:` 压成 `-`，导致「登记的是 A、成员表里是 B」）。
+
 - **内部关系全面改用 key（不再是随机 id）+ 导入分组的「本地未拥有」占位**：
   - **关系一律用 key**：看板成员存 `repoKeys`（不是 `repoIds`）、组内描述按 key、
     绑定关系（linked，ref 侧与 dev 侧双向记录）也按 key。`repo.id` / `board.id`
@@ -22,6 +156,25 @@
     `repo remote check`（`git ls-remote` 检查远端是否存在，**存在 / 不存在 /
     不可达**三种结论分清）。面板上每行有「remote」按钮，弹窗里下拉切换 + 存在性徽标。
 
+- **MD 工作台编辑器专业对齐（10 轮 UI/UX 循环，纪要见 `plan/LOOP-MD-EDITOR.md`）**：
+  - **标题不再截断**：live 与源码两态的标题改为自动增高 textarea，长标题按宽度软换行；
+    Enter 不产生换行、直接把焦点交给正文（live 进首块 / 源码回正文 0 位）
+  - **工具栏分层**：模式 | 格式 | 插入三簇 hairline 分组，格式组去灰底容器（hover 才显底），
+    次级动作去描边转文本态，视觉重量留给主按钮
+  - **自适应改容器查询**：`.mdw-main` 声明 container，工具栏/纸面按「编辑列」实际宽度三级折叠
+    （1280 收转变组 / 960 收进溢出菜单 / 640 纸面紧凑）——修掉右侧进程 rail 一开就静默裁按钮的缺陷
+  - **溢出菜单 portal 到 body**：修 `···`/`更多` 菜单被工具栏 `overflow:hidden` 整条裁掉的缺陷
+  - **阅读态补题头**：三态标题呈现统一，题头与正文同轴同宽
+  - **空文档幽灵引导**：空文档渲染 Notion 式引导条，点击直接聚焦首块
+  - **撤销/重做**：新增文档级历史栈——受控 textarea 的程序化改写会冲掉浏览器原生 undo 栈，
+    原先「Ctrl+B 加粗 → Ctrl+Z」毫无反应；现在格式操作、输入段均可撤销/重做，
+    且撤销后光标回到改动处（源码精确，live 跨块自动跳转并接管焦点）
+  - **Ctrl/⌘S 保存 + 页签未保存圆点**：改动即在页签挂一颗点，保存/提交后摘除
+  - **快捷键速查面板**：Ctrl/⌘ / 或工具栏问号唤起，15 条键位分三组
+  - **实时预览块级查找**：Ctrl/⌘F 在预览态可用，n/m 计数 + 命中块高亮 + 滚动定位
+  - **无障碍**：编辑区 aria-label 补齐、状态栏小字对比度提到 WCAG AA
+
+
 - **仓库获得全局唯一 key，导入导出改以 key 为身份（v3）+ 全屏导入导出面板**：
   - **key**：归一化远程地址派生（`git@c:o/r.git`、`https://c/o/r`、
     `ssh://git@ssh.github.com:443/o/r.git`、带端口、带 `.git` 都是同一个

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

@@ -54,9 +54,25 @@ git -C <path> pull --no-edit
 - 路径不必是 git 仓库：登记不校验目录内容，也不要求目录存在
 - **key 是身份，全局唯一**（2026-10-28）：来自归一化远程地址（`git@c:o/r.git`、
   `https://c/o/r`、`ssh://git@ssh.github.com:443/o/r.git` 归一到同一个
-  `c/o/r`），或无 remote 时 `local/<名称>` 兜底，也可 `repo key set` 自定义。
-  自定义 key 不跟随 remote 变化；`repo key refresh --all` 扫描 `git remote -v`
-  （**SSH 优先**）提示可更新的 key/远程地址，`--apply` 才落盘
+  `c/o/r`）。自定义 key 不跟随 remote 变化；`repo key refresh --all` 扫描
+  `git remote -v`（**SSH 优先**）提示可更新的 key/远程地址，`--apply` 才落盘
+- **身份只有两个来源：远程地址，或人显式自定义**（2026-10-31）。两者都没有的仓库
+  **冻结**：它照常能在本机用（侧边栏、本地任务、绑定、进项目组），但
+  - **不导出**（导出靠 key 映射到「另一台机器上的同一个仓库」，`local/<名称>` 在
+    别人那里映射不到任何东西），项目组里的冻结成员也会被从导出的成员表里剔除；
+  - 不参与导入匹配（不会被别人的布局「命中」）。
+
+  这里**不再有 `local/<名称>` 兜底身份**——那个兜底只是本机关系的内部锚点，
+  绝不外发。要给一个没有远程地址的仓库身份，就显式指定 key：
+
+  ```bash
+  nx-kv repo key set <id|路径> 团队/nx-rh     # 自定义身份（也可 repo update <id> --key …）
+  nx-kv repo update <id> --key ""            # 清空 = 回到跟随远程地址；没有远程地址就回到冻结
+  ```
+
+  面板上就是「编辑仓库」弹窗里那个 **key** 字段：留空 = 跟随远程地址，填了 = 自定义。
+  **改 key 等于换身份**，服务层会把项目组成员、组内描述、绑定一起搬过去
+  （不搬的话关系会断在旧 key 上，表现为「仓库莫名从组里掉了」）。
 - **所有内部关系用 key，不用随机 id**（2026-10-28）：看板成员存 `repoKeys`、
   组内描述按 key、绑定关系（linked）按 key。id 只是本机行主键，不再参与任何关系引用
   ——id 换机即失效，key 才能精确映射
@@ -64,6 +80,21 @@ git -C <path> pull --no-edit
   两者要对齐但方向由人定（SSH 优先只是默认值）：
   `repo remote list`（列候选）、`repo remote pick --url`（人工换一条）、
   `repo remote check`（存在 / 不存在 / 不可达，三种结论分清）
+- **批量对齐走 scan**：判断「该换哪条 remote」的依据全在数据里（`git remote -v`
+  + 登记采纳值 + key 派生），所以有一条批量命令，别一个仓库一个仓库点：
+
+  ```bash
+  nx-kv repo remote scan                 # 缺省只扫开发仓库：ok / 可替换 / 空 / 登记悬空 / 目录不可用 + 建议
+  nx-kv repo remote scan --type ref|all  # 要看参考仓库才显式指定
+  # 面板上就是「仓库」页右上那个「对齐 remote」按钮（不是每行一个 remote 按钮）
+  ```
+
+  **范围默认是开发仓库**：参考仓库的 remote 就是它 clone 的来源兼 key，没有「换一条」
+  的余地，列进来只是几十行噪音；它们的健康度看 `repo ref check`。
+
+  `scan` **只读本地 git 配置、不发网络请求**，所以够快；远端存在性（`git ls-remote`）
+  是按需的 `remote check`。整批落盘用 `repo.remote.align`（HTTP：`POST
+  /api/repos/remote/align`，body `items = [{ id|key, url }]`）。
 - **没有标签**：分组只走看板一条路（2026-10-24 废除仓库 tags，两套平行分组只会打架）
 - **type 双态**：`dev` = 开发仓库（默认），`ref` = 参考仓库（见下节）
 - **remote 是稳定 key**：参考仓库必有；开发仓库也建议记（`repo remote <id|path>` 一条命令
@@ -71,6 +102,28 @@ git -C <path> pull --no-edit
 - **看板的 desc 是领域描述**：写该组仓库的侧重、配合关系（谁是中心/终端）、
   关键路径与搜索关键词——它是给人和 agent 读的上下文，写法约定见 [[kv-repo]]
 
+## 仓库的描述：desc 是摘要，docs 才是正文
+
+`desc` 一句话不够用（用户的原话：desc 不该是一句话，而是 **md 列表**）。所以一个仓库带：
+
+- `desc` —— 一句话摘要。列表行、搜索、导出都读它，必须短。
+- `docs` —— **仓库内 md 的相对路径数组**（最多 24 条）。详细说明、设计、约定写在这些
+  md 里，谁写谁维护；面板的仓库详情页把它们渲染出来。
+
+```bash
+nx-kv repo add <path> --docs README.md,docs/arch.md     # 登记时一起挂
+nx-kv repo update <id> --docs README.md,docs/arch.md    # 改（传空数组 = 清空）
+nx-kv repo doc <id> --path docs/arch.md                 # 读正文（面板也走这条）
+```
+
+只认**仓库内**的相对路径：绝对路径、`..` 越界、非 `.md` 一律拒收（`sanitizeDocs`）。
+读正文时不存在 / 越界 / 超过 512KB 都是显式错误，不静默返回空。导出布局**不带 md 正文**
+（本机文件不入布局，只带登记）。
+
+面板：`#/repo/<key>` 是仓库详情页（信息 + md 描述 + 项目组 + 相关任务）；侧边栏点项目
+就落这儿——**空任务的仓库也点得开**（以前它只能去工作台，没队列就没去处）。
+列表行里 desc 下面那排 `md` chip 就是 docs，点一下直达详情页对应的那一份。
+
 ## 参考仓库（type=ref）：搜索并克隆外部项目
 
 mmx-research-gitclone 的整体吸纳（2026-10-27）：远程 clone 下来学习/参考的仓库与

package/package.json

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

package/src/modules/auth/index.js

@@ -32,7 +32,8 @@ export default {
   id: 'auth',
   title: '认证（登录态）',
   order: 10,
-  view: () => import('./view.jsx'),
+  // 登录 UI 已合并进云端页（frontend todo view），此处只保留 CLI/HTTP action；
+  // 独立面板视图已下线（2026-10-30）。
 
   actions: [
     {

package/src/modules/repos/boards.js

@@ -16,7 +16,7 @@
 //
 // 本文件不含传输层概念（不认识 argv 与 HTTP）。
 import { resolve } from 'node:path';
-import { loadStore, mutateStore, newId, boardKeyOf, boardRepoKeys, deriveKey, normalizeKey } from './service.js';
+import { loadStore, mutateStore, newId, boardKeyOf, boardRepoKeys, deriveKey, normalizeKey, isFrozen } from './service.js';
 import { badInput, notFound, conflict } from '../../core/errors.js';
 
 const cleanText = (v) => String(v || '').trim();
@@ -198,6 +198,8 @@ export async function assignRepo({ id, key, board, before, remove } = {}) {
     }
 
     if (!target) throw badInput('请给 --board <看板id>');
+    // 冻结（无身份）的仓库**允许**进项目组：本机的编排不该被「有没有远程地址」卡住。
+    // 代价由导出承担——它的 local/<名称> 不是身份，导出时会被剔除并告警（transfer.js）。
     if (!Array.isArray(target.repoKeys)) target.repoKeys = [];
     const at = target.repoKeys.indexOf(rkey);
     // 已在板内：摘出后按 before 回插（纯调位次）；不在：追加。
@@ -257,9 +259,12 @@ export async function importBoards({ json } = {}) {
   const incoming = Array.isArray(data?.boards) ? data.boards : null;
   if (!incoming || !incoming.length) throw badInput('JSON 里没有 boards 数组');
   return mutateStore((s) => {
-    const byName = new Map(s.repos.map((r) => [String(r.name).trim(), deriveKey(r)]));
+    // 冻结仓库不参与匹配：它的 key 是 local/<名称>，别人导出的文件里不会有这个 key，
+    // 拿它去对齐只会把成员错配到本机凑巧同名的目录上。
+    const ident = s.repos.filter((r) => !isFrozen(r));
+    const byName = new Map(ident.map((r) => [String(r.name).trim(), deriveKey(r)]));
     // path 匹配（大小写不敏感、分隔符归一）——老格式的导入文件按 path 引用
-    const byPath = new Map(s.repos.map((r) => [String(r.path).toLowerCase().replace(/\\/g, '/'), deriveKey(r)]));
+    const byPath = new Map(ident.map((r) => [String(r.path).toLowerCase().replace(/\\/g, '/'), deriveKey(r)]));
     let created = 0;
     let merged = 0;
     let matched = 0;

package/src/modules/repos/detail.jsx

@@ -0,0 +1,289 @@
+// 仓库详情页（#/repo/<key>）：**一个仓库的信息 + 它的 md 描述 + 它的任务**。
+//
+// 为什么要这一页（用户的原始诉求）：
+//   1. 侧边栏「所有资源都应该支持点击」——没有任务队列的仓库以前点了没反应，
+//      因为它唯一的去处是工作台（#/dir/<topicKey>），而空队列没有 topicKey；
+//   2. 点开要能看到**仓库信息**，并且 desc 不是一句话而是 **md 列表**
+//      （[]md 是 string desc 的上位替代，链到仓库里的本地 md 文件）；
+//   3. 顺带能看到这个仓库**相关的任务**（本机队列按 cwd 匹配到它）。
+//
+// 数据边界：仓库登记来自 /api/repos/:id，md 正文来自 /api/repos/doc，
+// 任务来自 App 已经轮询着的 localtasks（rows），这一页不自己再拉一遍队列。
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { api } from '../../web/frontend/api/client.js';
+import { useGuard, useToast, Copyable } from '../../web/frontend/components/ui.jsx';
+import { Icon } from '../../web/frontend/components/icons.jsx';
+import { renderMarkdownHtml } from '../../web/frontend/modules/md-workspace/md-parse.js';
+
+/** 任务正文里抽一行标题（与侧边栏同一口径：`# 标题` 优先，否则首行） */
+function taskTitle(t) {
+  const text = String(t?.text || '');
+  const m = text.match(/^#\s+(.+)$/m);
+  if (m) return m[1].trim();
+  const line = text.split('\n').find((l) => l.trim());
+  return (line || `#${t.id}`).trim().slice(0, 80);
+}
+
+const isDeleted = (t) => !!t.deletedAt;
+const isPending = (t) => t.status !== 'consumed' && !t.deletedAt;
+
+export default function RepoDetail({ dirKey, rows, onNavigate }) {
+  const guard = useGuard();
+  const toast = useToast();
+
+  const [repo, setRepo] = useState(null);   // 仓库登记
+  const [err, setErr] = useState('');
+  const [active, setActive] = useState(''); // 当前 md（相对路径）
+  const [doc, setDoc] = useState(null);     // { path, text, size }
+  const [docErr, setDocErr] = useState('');
+  const [adding, setAdding] = useState(''); // 「挂一个 md」输入框
+
+  const load = useCallback(async () => {
+    if (!dirKey) return;
+    setErr('');
+    try {
+      const d = await api('/api/repos/' + encodeURIComponent(dirKey));
+      setRepo(d);
+      // 选中哪份 md：?doc=<相对路径> 优先（列表里点具体某份直达），否则第一份
+      const want = (() => {
+        const m = /[?&]doc=([^&]+)/.exec(typeof location !== 'undefined' ? location.hash || '' : '');
+        return m ? decodeURIComponent(m[1]) : '';
+      })();
+      setActive((cur) => {
+        if (want && (d.docs || []).includes(want)) return want;
+        if (cur && (d.docs || []).includes(cur)) return cur;
+        return (d.docs || [])[0] || '';
+      });
+    } catch (e) {
+      setErr(String((e && e.message) || e));
+    }
+  }, [dirKey]);
+  useEffect(() => { load(); }, [load]);
+
+  // md 正文按需拉（一次一份，切换时再拉：md 可能很大，没必要全预取）
+  useEffect(() => {
+    if (!repo || !active) { setDoc(null); return; }
+    let alive = true;
+    setDocErr('');
+    api('/api/repos/doc?id=' + encodeURIComponent(repo.key) + '&path=' + encodeURIComponent(active))
+      .then((d) => { if (alive) setDoc(d); })
+      .catch((e) => { if (alive) { setDoc(null); setDocErr(String((e && e.message) || e)); } });
+    return () => { alive = false; };
+  }, [repo, active]);
+
+  // 这个仓库的本机队列：服务端按 cwd 匹配登记，topic.repo.id 就是它
+  const topic = useMemo(() => {
+    if (!repo) return null;
+    return (rows || []).find((t) => t.repo && t.repo.id === repo.id) || null;
+  }, [rows, repo]);
+
+  const tasks = useMemo(() => {
+    const list = (topic && topic.tasks) || [];
+    return {
+      pending: list.filter(isPending),
+      done: list.filter((t) => t.status === 'consumed' && !isDeleted(t)).slice().reverse(),
+    };
+  }, [topic]);
+
+  const addDoc = () => guard(async () => {
+    const p = adding.trim();
+    if (!p) return;
+    setAdding('');
+    if ((repo.docs || []).includes(p)) return;
+    await api('/api/repos/' + encodeURIComponent(repo.id), {
+      method: 'PATCH',
+      body: { docs: [...(repo.docs || []), p] },
+    });
+    await load();
+    setActive(p); // 挂上就直接看它（挂错了下一步就是「摘掉」）
+    toast('已挂上 ' + p);
+  });
+
+  const removeDoc = (p) => guard(async () => {
+    await api('/api/repos/' + encodeURIComponent(repo.id), {
+      method: 'PATCH',
+      body: { docs: (repo.docs || []).filter((x) => x !== p) },
+    });
+    if (active === p) setActive('');
+    await load();
+  });
+
+  const openFolder = () => guard(async () => {
+    await api('/api/repos/open', { method: 'POST', body: { id: repo.id } });
+  });
+
+  if (err) {
+    return (
+      <div className="rpd">
+        <div className="rpd-err">
+          仓库读取失败：{err}
+          <button className="btn small ghost" onClick={load}>重试</button>
+          <button className="btn small ghost" onClick={() => onNavigate('#/repos')}>回仓库管理</button>
+        </div>
+      </div>
+    );
+  }
+  if (!repo) return <div className="rpd"><div className="muted" style={{ padding: 24 }}>读取中…</div></div>;
+
+  return (
+    <div className="rpd" data-testid="repo-detail">
+      <div className="rpd-head">
+        <div className="rpd-title">
+          <h2>{repo.name}</h2>
+          <span className="rpd-badge">{repo.type === 'ref' ? '参考仓库' : '开发仓库'}</span>
+          {repo.frozen ? (
+            <span className="rpd-badge warn" title="没有 key：既没有远程地址，也没有自定义 key。导出导入不包含它">无 key · 冻结</span>
+          ) : (
+            <span className="rpd-badge key" title="key 是身份，导出导入按它映射">
+              {repo.keyCustom ? '自定义 key' : 'key 跟随远程地址'}
+            </span>
+          )}
+        </div>
+        {repo.desc ? <div className="rpd-desc">{repo.desc}</div> : null}
+        <div className="rpd-acts">
+          {topic ? (
+            <button className="btn small" onClick={() => onNavigate('#/dir/' + encodeURIComponent(topic.key))}>
+              打开工作台{topic.pending ? `（${topic.pending} 待领）` : ''}
+            </button>
+          ) : null}
+          <button className="btn small ghost" onClick={openFolder}>打开目录</button>
+          <button className="btn small ghost" onClick={() => onNavigate('#/repos')}>仓库管理</button>
+        </div>
+      </div>
+
+      <div className="rpd-cols">
+        {/* 左：md 描述列表（desc 的上位替代） */}
+        <section className="rpd-docs">
+          <div className="rpd-colhead">
+            <h3>描述文档</h3>
+            <span className="muted">仓库内的 md（相对路径），谁写谁维护</span>
+          </div>
+          <div className="rpd-tabs">
+            {(repo.docs || []).map((p) => (
+              <span key={p} className={'rpd-tab' + (active === p ? ' on' : '')}>
+                <button className="rpd-tab-name" onClick={() => setActive(p)} title={p}>{p}</button>
+                <button className="rpd-tab-x" title="从描述里摘掉（不删文件）" onClick={() => removeDoc(p)}>
+                  <Icon name="x" size={10} />
+                </button>
+              </span>
+            ))}
+            <span className="rpd-add">
+              <input
+                value={adding}
+                placeholder="挂一个 md，如 README.md"
+                spellCheck="false"
+                onChange={(e) => setAdding(e.target.value)}
+                onKeyDown={(e) => { if (e.key === 'Enter') addDoc(); }}
+              />
+              <button className="btn small ghost" onClick={addDoc} disabled={!adding.trim()}>挂上</button>
+            </span>
+          </div>
+          {active ? (
+            docErr ? (
+              <div className="rpd-docerr">
+                {docErr}
+                <button className="btn small ghost" onClick={() => setActive('')}>关闭</button>
+              </div>
+            ) : doc ? (
+              <article
+                className="rpd-md"
+                // md 渲染用工作台同一份解析器：预览与真实内容不会各说各话
+                dangerouslySetInnerHTML={{ __html: renderMarkdownHtml(doc.text) }}
+              />
+            ) : (
+              <div className="muted" style={{ padding: 12 }}>读取中…</div>
+            )
+          ) : (
+            <div className="rpd-empty">
+              还没有描述文档。{repo.desc ? '现在只有一句描述：' : ''}
+              {repo.desc ? <b>{repo.desc}</b> : null}
+              <div className="muted">
+                在上面的输入框里填一个**仓库内**的 md 相对路径（<code>README.md</code>、
+                <code>docs/arch.md</code>），挂上就能在这里读。
+              </div>
+            </div>
+          )}
+        </section>
+
+        {/* 右：身份 + 项目组 + 相关任务 */}
+        <aside className="rpd-side">
+          <div className="rpd-card">
+            <div className="rpd-colhead"><h3>登记信息</h3></div>
+            <dl className="rpd-fields">
+              <dt>key</dt>
+              <dd><Copyable text={repo.key || '（无）'} title="点击复制">{repo.frozen ? '（无 · 冻结）' : repo.key}</Copyable></dd>
+              <dt>远程</dt>
+              <dd>{repo.remote ? <Copyable text={repo.remote} title="点击复制">{repo.remote}</Copyable> : <span className="muted">（无）</span>}</dd>
+              <dt>路径</dt>
+              <dd><Copyable text={repo.path} title="点击复制">{repo.path}</Copyable></dd>
+              {repo.notes ? (<><dt>备注</dt><dd>{repo.notes}</dd></>) : null}
+            </dl>
+          </div>
+
+          <div className="rpd-card">
+            <div className="rpd-colhead">
+              <h3>项目组</h3>
+              <span className="muted">{(repo.boards || []).length ? `${repo.boards.length} 个` : ''}</span>
+            </div>
+            {(repo.boards || []).length ? (
+              <div className="rpd-chips">
+                {repo.boards.map((b) => (
+                  <button key={b.id} className="rpd-chip" title={b.desc || ''}
+                    onClick={() => onNavigate('#/repos?board=' + encodeURIComponent(b.id))}>
+                    {b.name}
+                  </button>
+                ))}
+              </div>
+            ) : <div className="muted rpd-none">还没进任何项目组</div>}
+          </div>
+
+          <div className="rpd-card">
+            <div className="rpd-colhead">
+              <h3>相关任务</h3>
+              <span className="muted">
+                {topic ? `${tasks.pending.length} 待领 · ${tasks.done.length} 已领` : '本机队列未建立'}
+              </span>
+            </div>
+            {!topic ? (
+              <div className="rpd-empty small">
+                这个目录还没有任务队列。往它投一条任务（在本目录下）：
+                <code>nx-kv localtask add "要做的事" --cwd {repo.path}</code>
+              </div>
+            ) : (
+              <>
+                {tasks.pending.length || tasks.done.length ? (
+                  <ul className="rpd-tasks">
+                    {tasks.pending.map((t) => (
+                      <li key={t.id} className="pending">
+                        <span className="rpd-dot" />
+                        <span className="rpd-task-title" title={t.text || ''}>{taskTitle(t)}</span>
+                        <button className="rpd-task-go" title="在工作台打开"
+                          onClick={() => onNavigate('#/dir/' + encodeURIComponent(topic.key) + '?task=' + encodeURIComponent(t.id))}>
+                          <Icon name="jump" size={11} />
+                        </button>
+                      </li>
+                    ))}
+                    {tasks.done.map((t) => (
+                      <li key={t.id} className="done">
+                        <span className="rpd-dot" />
+                        <span className="rpd-task-title" title={t.text || ''}>{taskTitle(t)}</span>
+                      </li>
+                    ))}
+                  </ul>
+                ) : (
+                  <div className="rpd-empty small">
+                    队列是空的——没有待领取的任务。
+                    <code>nx-kv localtask add "要做的事"</code>
+                  </div>
+                )}
+                <button className="btn small ghost rpd-open-dir" onClick={() => onNavigate('#/dir/' + encodeURIComponent(topic.key))}>
+                  去工作台
+                </button>
+              </>
+            )}
+          </div>
+        </aside>
+      </div>
+    </div>
+  );
+}