nx-kv 0.11.4 → 0.12.1

package/CHANGELOG.md

@@ -2,7 +2,160 @@
 
 本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
-## [Unreleased]
+## [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`
+    保留为本机行主键，但**不再参与任何关系引用**——id 换机即失效，key 才能精确映射。
+    一次性迁移：`nx-kv repo key migrate [--apply]`（幂等，死链自动清理）。
+  - **导入时保留占位**：对方分组里有、本地没有的仓库，**位置照抄进组里**
+    （组布局完整复制），组内描述按 key 一并保留；投影里 `present:false` 标出来。
+  - **clone 补齐**：`nx-kv repo clone <remote> --key <占位key>` 按 remote 克隆并用
+    **占位的 key** 登记 → 占位自动转正、位置不动。面板上「本地未拥有」的行有
+    「克隆到本地」按钮；仓库页的「成员管理」弹窗也能看到占位成员并补齐。
+  - **对齐 remote**（remote 才是协作的标准单位，key 只是本地身份）：
+    `repo remote list`（列 `git remote -v` 的全部候选、标出当前采纳的）、
+    `repo remote pick --url`（人工换一条，key 随之重算，自定义 key 不动）、
+    `repo remote check`（`git ls-remote` 检查远端是否存在，**存在 / 不存在 /
+    不可达**三种结论分清）。面板上每行有「remote」按钮，弹窗里下拉切换 + 存在性徽标。
+
+- **仓库获得全局唯一 key，导入导出改以 key 为身份（v3）+ 全屏导入导出面板**：
+  - **key**：归一化远程地址派生（`git@c:o/r.git`、`https://c/o/r`、
+    `ssh://git@ssh.github.com:443/o/r.git`、带端口、带 `.git` 都是同一个
+    `c/o/r`），无 remote 用 `local/<名称>` 兜底，也可 `repo key set` 自定义
+    （自定义不跟随 remote）。**跨 dev/ref 全局唯一**，`id / key / 路径` 都能定位。
+    顺带修掉 `ssh://host:port` 归一化错误（旧实现会得出 `git@ssh.github.com:443/...`）。
+  - **刷新**：`repo key refresh [id] | --all [--apply]` 扫 `git remote -v`
+    （**SSH 优先**，其次 https），提示可更新的 key/远程地址；`--apply` 才落盘。
+    存量 28 个仓库已迁移（10 个开发仓库从 `local/*` 纠正为真实 GitHub key）。
+  - **导入导出 v3**：导出物以 key 引用仓库与看板（`board/<名称>`），
+    **绝不含本地路径**；`repo export --zip` 打包 `layout.json` + `README.txt`
+    （自带最小 ZIP 写入器，无新依赖）；`--repos/--boards` 可选范围。
+  - **差异检查**：`repo import --diff <file>` 零副作用，逐条给出
+    新增 / 有差异（字段级）/ 一致 / 本地未拥有。
+  - **冲突方案**：`--strategy ours`（保留本地，默认）/ `overwrite`（覆盖字段，key 不变）/
+    `duplicate`（另存 `key-import-1/2/3`，两条并存）；`--select` 逐条挑、`--clone` 选克隆范围。
+  - **全屏面板**：仓库页「参考仓库」→「导入导出」→ 左右两栏覆盖层：
+    导出侧可选仓库/看板（全选/反选）+ JSON 预览与下载；导入侧粘贴/选文件 → 差异表
+    （状态徽标、字段级 diff、按状态筛选、全选/反选、逐条勾选）+ 冲突方案 + 克隆选项。
+  - 兼容 v2 导出文件（无 key 时用 remote/name 派生）。
+
+- **面板 v2：侧边栏目录工作台 + 本地 ⇄ 云端任务并列迁移**（设计稿与验收脚本见 `plan/`）：
+  - **侧边栏取代顶栏 + 平铺 tab**：目录（topic）提升为一级导航；分组可拖拽编排（上/下缘 = 排序，中段 = 移入分组，
+    目录行中段不作落点）；搜索按名称/路径/现状摘要过滤且命中自动展开；收起为 52px 图标 rail（悬停气泡 + 徽标仍在）；
+    底部入口：全部目录总览 / 云端总览 / 仓库管理 / 经典看板(v1) / 登录设置；
+  - **目录详情页默认全屏**（`#/dir/<key>`，进入即收起侧边栏）：顶栏含目录名、路径、现状摘要（点击即改）、任务源切换
+    （并列 / 仅本机 / 仅云端）；本机四列 = 待领取（正序 = 领取优先级，**列内可拖拽调序**）/ 进行中（等待回填 + 实时倒计时 +
+    回填闭环）/ 已领取（倒序，带回执）/ 归档（软删可恢复、可彻底删）；
+  - **本地 ⇄ 云端并列**：同一目录的两个任务来源并列成双栏（本机队列 ⇄ 云端清单，按 `topic` 过滤、按 groupId 共享）；
+    迁移有三条入口（拖卡片跨栏 / 卡片 ⋯ 菜单 / 列头批量），迁移前弹确认框写清「源 → 目标」映射并在目标端已有同内容时消歧
+    （可选择合并）；迁出留 tombstone 记录（可跳到目标、可移除），回执带撤销；
+  - **迁移原子性**：新增 `POST /api/task/move` 与同构 CLI `nx-kv task move --to cloud|local` / `--undo`
+    ——一次请求内「先写目标端、成功才改源端」，目标端不可达则源端原样不动、不产生迁出记录；撤销按 `targetId` 精确回退
+    （不按文本匹配，同内容 ×N 时不会误伤）；
+  - **全局任务池**（`__GLOBAL__`）成为独立全屏视图，可「投放到目录…」固定归属；「全部目录总览」承接 v1「本地任务」tab 的跨目录视角；
+  - 无障碍：焦点环可见、浮层焦点进出与归还、纯图标按钮带 `aria-label`、正文对比度达 WCAG AA。
+
+### Added
+- **参考仓库绑定模型升级：多对多 + 绑定描述 + 命名空间分层**（承接参考仓库功能的首轮反馈）：
+  - 面板双名单分离：主表只放开发仓库（行内新增「绑定的参考仓库」列 + 选项式「绑定」按钮）；
+    参考仓库有自己的**大面板表格**（状态徽标 / 远程地址 / 绑定 chips / 操作），不再与开发仓库混排；
+  - 绑定全部改**选项式勾选**（克隆弹窗、参考侧「绑定…」、dev 侧「绑定」三处都是 checkbox），不再手填 id 字符串；
+  - **绑定描述**（`repo ref note`）：「这个参考在该仓库/看板里参考什么」挂在绑定关系上，
+    同一条绑定在不同组里的意义可以不同；摘绑即清；导出导入随关系走；
+  - **分层查询**（`repo ref of [id|路径]`，缺省当前目录）：第一层 = 直接绑定的参考，
+    第二层 = 所在看板（命名空间）上的参考按组列出——agent 问「做这个仓库有什么参考」一条命令；
+  - 筛选到看板时显示该组（项目组）的**命名空间参考区**：组级绑定（可写命名空间描述）+ 成员仓库级参考（标明经由谁）。
+
+### Changed
+
+- 仓库页主表语义收窄为「开发仓库清单」（参考仓库移入自己的面板）；「全部」chip 改名「开发仓库」。
+- **绑定关系改为双向记录**：ref 侧记 `{repo|board, id, note?}`，dev 侧记反向的 `{ref, id, note?}`。
+  之前只有 ref 侧记，dev 仓库自己「不知道自己挂了哪些参考」——查上下文、列清单都得反向扫
+  ref 全表。现在 dev 仓库直接带着自己的参考列表（描述两侧各存一份同一内容），
+  删仓库/删看板双向清理，不留死链。存量数据已迁移（18 条反向引用）。
+
+- **仓库模块吸纳 mmx-research-gitclone：参考仓库（type=ref）成为登记的一等公民**。
+  远程 clone 下来学习/参考的仓库与开发仓库同住中心清单，`type` 区分双态
+  （dev = 本机开发，缺省；ref = 远程参考）；所有存储以**远程 git 地址为 key**
+  （`normalizeRemoteKey` 归一——SSH/HTTPS 写法不同也算同源，天然查重）：
+  - 新命令族 `repo ref`：`repo ref clone <url>`（clone + 登记 + 绑定一条龙，SSH 优先
+    失败自动回退 HTTPS；落到 `gitRepoRoot`——**未设置则显式拒绝**，
+    `nx-kv setting set --gitRepoRoot <非C盘目录>`）、`repo ref add`（登记已有 checkout）、
+    `repo ref sync [--all]`（`git pull --ff-only`，冲突不自动 merge）、
+    `repo ref check`（目录/.git/origin 一致性 + 绑定死链，零副作用）；
+  - **绑定关系**：`repo bind <ref> --repo <开发仓库> --board <看板id>`——参考仓库的
+    `linked` 记录「这个参考是给谁看的」，一个 ref 可绑多个目标、一个目标可被多个 ref 绑；
+    删开发仓库/删看板同步摘绑定。在开发仓库目录里跑 `repo ref clone` 默认自动绑定当前仓库；
+  - **布局导入导出 v2**：`repo export` / `repo import`——导出**远程地址 + 分组 +
+    参考关系**（不含任何本地路径，dev 无 remote 如实进 warnings）；导入两段式，
+    `--plan` 零副作用先出计划（登记什么/克隆什么/建什么组/连什么关系），确认后按
+    `--clone all|dev|ref|none` 与 `--only <remote…>` 选择性执行；
+  - `repo remote <id|path> [--url]`：登记远程地址存档（无 --url 从目录 origin 读）——
+    开发仓库也建议记，导出时导它；
+  - 新设置：`gitRepoRoot`（参考仓库存储根）、`gitDevRoot`（导入时开发仓库克隆根），
+    CLI `setting set` 与面板「仓库 → 参考仓库 → 存储根」同源读写；
+  - 面板「仓库」页新增**参考仓库子面板**：克隆/同步/检查/布局导入导出/存储根设置，
+    参考仓库行带检查状态徽标；筛选到看板时挂载「绑定在该看板或其成员上的参考仓库」小节；
+    中心清单 ref 行带「参考」标，筛选器加「参考」快捷档；
+  - 新 skill `kv-repo-mmx-gitrepo`（`nx-kv skill install kv-repo-mmx-gitrepo`）：
+    mmx 深搜 → `repo ref clone` 落地，替代裸 git clone + `.claude/www/git.remote`
+    文本清单的散装流程（旧 skill 不受影响，存量 `.claude/repo/` 可用 `repo ref add` 收编）。
+
+### Fixed
+
+- **`localtask wait` 不再重复创建浏览器标签页**。旧活性判据有两处盲区：
+  - 只数「本地任务」页的活动 SSE 连接——用户一切到别的页（SSE 单视图挂载，切页即断）
+    就被误判「没人在看」，于是 wait 重开标签；
+  - 只探默认端口 7877——`serve --port` 或端口被占自动顺延出来的面板完全看不见，
+    wait 会另起第二个 serve 实例、再开一个标签。
+  - 现在活性 = 活动 SSE 标签 **或** 面板最近 30s 内有请求（App 壳每 15s 打 `/api/ping`），
+    面板发现扫描 `panels.json` 全部登记端口并复用；App 壳在「本地任务」tab 上
+    增加等待中主题角标，用户停在任意页也能收到提醒。
+- bootstrap 补回 `projectRoot` 字段（serve 进程 cwd）——仓库页扫描弹窗的
+  「留空＝当前项目目录」之前读的是不存在的字段，缺省根恒为空。
+- 仓库页白屏（`Cannot access 'Z' before initialization`）——`shown` 的 useMemo 引用了
+  声明在它之后的 `devRepos`（生产构建压成单字母变量，报错信息因此看不出是哪个变量）。
+  已修，并新增 `scripts/check-tdz.mjs` 静态自查（接进 `npm run lint`）：
+  组件体内的「先引用后声明」和 useMemo 依赖晚于自身，都会在构建期被拦下。
 
 ## [0.11.4] - 2026-10-25
 

package/assets/groups.json

@@ -25,6 +25,10 @@
     "kv-repo": {
       "skills": ["kv-repo"],
       "summary": "仓库组识别与关系报告——/kv-repo <组名> 一步加载看板相关项目；board/repo 查询、读并维护领域描述（中心/终端、关键路径、搜索关键词）"
+    },
+    "kv-repo-mmx-gitrepo": {
+      "skills": ["kv-repo-mmx-gitrepo"],
+      "summary": "mmx 深度搜索并克隆参考仓库——repo ref clone 统一落 gitRepoRoot、remote 为 key 登记绑定，替代散装的 git clone + git.remote 清单流程"
     }
   }
 }

package/assets/kv-repo/SKILL.md

@@ -39,22 +39,30 @@ nx-kv board list --json
 
 ## 模型（30 秒版）
 
-- **仓库登记** = 本机事实（name / path / desc / notes），一张中心清单。
+- **仓库登记** = 本机事实（name / path / desc / notes / type / remote），一张中心清单。
+  `type` 区分开发仓库（dev，默认）与参考仓库（ref，远程 clone 下来的、统一放 gitRepoRoot）。
+  每条都有**全局唯一 key**（归一化远程地址派生，或自定义）——它是导出导入与跨机
+  映射的身份，本地路径只在本机有意义。
 - **看板** = 领域分组；一个仓库可同时归入多个组，分组只此一条路（没有标签）。
 - **看板的领域描述（desc）+ 成员的组内描述（note）是写给你（agent）读的上下文**：
   desc 讲这个领域的侧重与配合方式；note 讲单个仓库在组里的角色（谁是中心 / 终端、
   API 关联在哪、关键路径、搜什么关键词）。**接到任务先读它们，比翻代码快。**
+- **参考仓库的 linked 是第三维上下文**：绑定是多对多（一个参考服务多个仓库/组，一个仓库
+  挂多个参考），`note` 写在**关系上**——同一条参考在不同组里的意义可以不同。接到任务时
+  `repo ref of <本仓库>` 一条命令拿全两层：自己的参考 + 所在组的命名空间参考。
 
 ## 完整命令（速查）
 
 ```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 repo list --json           # 扁平清单，每条带 key / boards[]（查单个仓库的归属）
+nx-kv repo ref of <id|key|路径> --json    # 这个仓库的参考：第一层直接绑定，第二层按看板命名空间
+nx-kv repo get <id|key|绝对路径> --json   # 单仓库详情 + 所在组（key 也是定位符）
 nx-kv board get <id> --json          # 单组详情（成员 + 组内描述）
 nx-kv board note <id|绝对路径> --board <看板id> --note "角色/配合关系/关键路径/关键词"
                                      # 写或清（--note 留空 = 清除）组内描述
+nx-kv repo ref check                 # 参考仓库完整性：目录/origin 一致性 + 绑定死链
 ```
 
 定位顺序：拿到任务/目录 → `repo list` 按**路径或目录名**找到仓库

package/assets/kv-repo-mmx-gitrepo/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: kv-repo-mmx-gitrepo
+description: 深度搜索（mmx）并克隆开源项目为 nx-kv 的「参考仓库」——替代 mmx-research-gitclone 的散装流程（裸 git clone + .claude/www/git.remote 文本清单），落地为登记表：remote 为 key、统一存放 gitRepoRoot（用户自设非 C 盘目录）、可绑定到当前开发仓库或看板、可同步更新与完整性检查。当用户想要搜索技术资料、调研开源项目、查找最佳实践并克隆参考时触发。例如："搜索Flutter liquid glass实现并clone"、"调研某个技术的开源方案"、"找几个参考项目"。保留 mmx 的既有纪律：3-5 路并行深搜、最多 clone 2 个最有价值的项目、SSH 优先失败双向回退、--depth 1 浅克隆。
+---
+
+# kv-repo-mmx-gitrepo — 搜索并克隆参考仓库（nx-kv 登记）
+
+与旧 mmx-research-gitclone 的区别只有**落地方式**：不再裸 `git clone` 到项目里的
+`.claude/repo/`、不再 append `.claude/www/git.remote` 文本清单。clone 改走
+`nx-kv repo ref clone`——落盘到统一的 gitRepoRoot、写进登记表（remote 为唯一 key）、
+顺手绑定到当前开发仓库或看板。换机/同步/查重/检查都由 nx-kv 接管。
+
+## 前置（首次必查一次）
+
+```bash
+nx-kv setting get
+# → 看 gitRepoRoot；未设置（提示文案里是「未设置」）则问用户要一个目录，然后：
+nx-kv setting set --gitRepoRoot <用户给的非C盘目录>
+```
+
+- **绝不默默落进默认目录**：gitRepoRoot 不设置，clone 会被显式拒绝——这是刻意的。
+- 用户已设置则直接用，不要每次都问。
+
+## SOP
+
+### 1. 深度搜索（mmx，3-5 路并行）
+
+```bash
+mmx search query --q "<技术方向> github implementation 2025" --output json --quiet
+mmx search query --q "<技术方向> fragment shader implementation code" --output json --quiet
+mmx search query --q "<技术方向> pub.dev package widget 2025" --output json --quiet
+mmx search query --q "<技术方向> best practice example tutorial" --output json --quiet
+```
+
+筛选标准：stars 高、最近更新、与需求最匹配、有真实代码实现。**最多 clone 2 个**。
+
+### 2. 核实仓库存在，不猜 URL
+
+```bash
+gh api repos/<owner>/<repo> --jq '.full_name'          # 已知 owner/repo：404 就换目标
+curl -s https://registry.npmjs.org/<pkg> | grep -o '"repository":{[^}]*}'   # npm 包反查源仓库
+```
+
+无 repository 字段 = 未开源，放弃。
+
+### 3. 克隆 + 登记 + 绑定（一条命令替代旧的三步）
+
+```bash
+# 在开发仓库目录里跑（推荐）——自动绑定当前目录的开发仓库
+nx-kv repo ref clone <url> --desc "一句话：它参考什么"
+# 显式控制：
+nx-kv repo ref clone <url> --desc "…" --board <看板id> --bind <开发仓库id|路径|名称> --depth 1
+# 只想登记、不自动绑当前仓库：
+nx-kv repo ref clone <url> --no-bind
+```
+
+- SSH 优先、失败自动回退 HTTPS（双向都试），登记的是实际成功的那条 URL；
+- 同一远程地址（SSH/HTTPS 写法不同也算同源）已登记 → 显式报错提醒，不会重复 clone；
+- gitRepoRoot 下同名目录已存在且同源 → 提示用 `repo ref add` 登记即可。
+
+### 4. 验证
+
+```bash
+nx-kv repo ref check              # 目录/.git/origin 一致性 + 绑定死链，零副作用
+nx-kv repo list --type ref --json # 刚 clone 的应该在列，带 remote 与 linked
+```
+
+check 全 ✓ 即完成；有 ✗ 按提示处理（目录缺失 → 重 clone；origin 不一致 → 核对后
+`repo remote <id> --url <真实地址>` 纠正）。
+
+### 5. 事后维护
+
+```bash
+nx-kv repo ref sync --all         # 参考仓库批量更新（git pull --ff-only，冲突不自动 merge）
+nx-kv repo bind <ref> --repo <开发仓库> --board <看板id>   # 补绑/多绑
+nx-kv repo bind <ref> --remove --repo <开发仓库>           # 摘某条绑定
+```
+
+## 输出格式
+
+```
+## 搜索结果总结
+
+已克隆为参考仓库（gitRepoRoot: <根目录>）：
+
+1. [项目名](github链接) - stars数
+   - 主要功能 / 技术栈
+   - nx-kv 登记: <id>，绑定: <开发仓库/看板>
+
+2. …（最多 2 个）
+
+检查: nx-kv repo ref check → N ✓ / 0 ✗
+```
+
+## 边界
+
+- 本 skill 只管**参考仓库**（type=ref）；开发仓库的 git 状态/diff/push 一律找 git 自己。
+- 旧 `.claude/repo/` 里的存量参考仓库不迁移不删除——要用时
+  `nx-kv repo ref add <path>` 登记进来（remote 缺省读目录 origin）。
+- 数据按本机 config 存储（~/.nx-kv/），跨机器搬运用 `repo export` / `repo import`
+  （导出的是远程地址 + 分组 + 参考关系，不含本地路径）。

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

@@ -7,13 +7,14 @@
 - 用户问「这台机器上有哪些仓库 / 某个仓库在哪」
 - 需要把某个目录登记为受管仓库，或扫描某目录批量发现仓库
 - 需要维护仓库的元信息：名称、描述、备注，或改登记路径
-- **需要 git 状态、差异、拉取、推送时不要进这里**——本工具不提供 git 操作（见下）
+- **需要 git 状态、差异、拉取、推送时不要进这里**——开发仓库不做 git 操作（见下）
+- **要搜索并克隆参考项目时用 [[kv-repo-mmx-gitrepo]]**——那是参考仓库的克隆 SOP
 - **只查分组与关系（不改动）时用 [[kv-repo]]**——那是仓库组的查询/报告侧
 
-## 边界：本工具不管 git
+## 边界：git 操作只给参考仓库
 
-仓库模块只维护一份**目录清单**。状态、diff、pull、push、冲突落地全部不做，
-原因见 README「为什么不管 git」：git 客户端是无底洞，面板做不出比 IDE 更好的体验，
+仓库模块只维护一份**目录清单**。开发仓库（type=dev）的 git 状态、diff、pull、push、
+冲突落地全部不做：git 客户端是无底洞，面板做不出比 IDE 更好的体验，
 而半吊子的状态显示比没有更危险（用户会拿它当决策依据）。
 
 要用 git 时直接用它自己：
@@ -24,12 +25,15 @@ git -C <path> diff
 git -C <path> pull --no-edit
 ```
 
+唯一的例外是**参考仓库**（type=ref，见下节）：clone / sync / check 三件事由本工具做——
+它的价值就是「把远程仓库抓到本机参考并保持新鲜」，不做这个它就没存在意义。
+
 本工具的价值在另一方面：把这些路径**记住并描述清楚**（叫什么、干什么用、归在哪类），
 让 agent 下次不必重新问一遍「这个是哪个项目」。
 
 ## 数据模型
 
-`~/.nx-rh/store.json` 的 `repos[]`，一条记录形如：
+`~/.nx-kv/repos.json` 的 `repos[]`，一条记录形如：
 
 ```json
 {
@@ -38,17 +42,90 @@ git -C <path> pull --no-edit
   "path": "D:\\a_js\\js_proj\\br_controller\\ext",
   "desc": "对外扩展模块",
   "notes": "",
+  "type": "dev",
+  "remote": "git@github.com:me/ext.git",
+  "linked": [],
   "addedAt": "…",
   "updatedAt": "…"
 }
 ```
 
-- **id 或绝对路径**都能定位仓库（agent 直接给路径更省事）
+- **id / key / 绝对路径**都能定位仓库（agent 直接给路径或 key 更省事）
 - 路径不必是 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` 才落盘
+- **所有内部关系用 key，不用随机 id**（2026-10-28）：看板成员存 `repoKeys`、
+  组内描述按 key、绑定关系（linked）按 key。id 只是本机行主键，不再参与任何关系引用
+  ——id 换机即失效，key 才能精确映射
+- **remote 是协作的标准单位**：key 是本地身份，remote 是别人 clone 用的地址。
+  两者要对齐但方向由人定（SSH 优先只是默认值）：
+  `repo remote list`（列候选）、`repo remote pick --url`（人工换一条）、
+  `repo remote check`（存在 / 不存在 / 不可达，三种结论分清）
 - **没有标签**：分组只走看板一条路（2026-10-24 废除仓库 tags，两套平行分组只会打架）
+- **type 双态**：`dev` = 开发仓库（默认），`ref` = 参考仓库（见下节）
+- **remote 是稳定 key**：参考仓库必有；开发仓库也建议记（`repo remote <id|path>` 一条命令
+  从目录 origin 读来存档）——导出布局时导远程地址而非本地路径，换机导入才 clone 得回来
 - **看板的 desc 是领域描述**：写该组仓库的侧重、配合关系（谁是中心/终端）、
   关键路径与搜索关键词——它是给人和 agent 读的上下文，写法约定见 [[kv-repo]]
 
+## 参考仓库（type=ref）：搜索并克隆外部项目
+
+mmx-research-gitclone 的整体吸纳（2026-10-27）：远程 clone 下来学习/参考的仓库与
+开发仓库同住中心清单，但统一存放在 `gitRepoRoot`（`nx-kv setting set --gitRepoRoot <非C盘目录>`，
+**不设置则 clone 显式拒绝**——绝不默默堆进用户目录）。完整搜索→克隆 SOP 见
+[[kv-repo-mmx-gitrepo]]；这里登记命令面的速查：
+
+```bash
+nx-kv repo ref clone <url> [--name N] [--desc D] [--board <看板id>] [--bind <开发仓库>] [--depth 1] [--no-bind]
+#   clone + 登记 + 绑定一条龙；在开发仓库目录里跑默认自动绑定当前仓库（--no-bind 关掉）
+nx-kv repo ref add <path> [--remote <url>]    # 登记一个已存在的 checkout（不 clone；remote 缺省读 origin）
+nx-kv repo ref sync [--all] [id|名称|url]     # 同步更新（git pull --ff-only；冲突不自动 merge）
+nx-kv repo ref check                          # 完整性检查：目录/.git/origin 一致性 + 绑定死链（零副作用）
+nx-kv repo bind <ref> --repo <开发仓库> --board <看板id>    # 绑定（多对多；目标可多个，逗号分隔）
+nx-kv repo bind <ref> --remove [--repo x | --board y]       # 摘绑定（都不带 = 清空）
+nx-kv repo ref note <ref> --repo <开发仓库> --note "在这参考什么"   # 写/清绑定描述（board 同理；留空=清）
+nx-kv repo ref of [id|路径]                                 # 分层查询：第一层直接绑定，第二层按看板命名空间
+nx-kv repo remote <id|path> [--url <地址>]    # 登记远程地址（无 --url = 从目录 origin 读）
+```
+
+- **remote 是参考仓库的唯一 key**：同一远程地址（SSH/HTTPS 写法不同也算同源）只允许一条登记
+- **linked 挂绑定关系（多对多）**：`[{kind:'repo'|'board', id, note?}]`——一个 ref 可服务
+  多个仓库/组，一个仓库/组可挂多个 ref；`note` 是**绑定描述**（这个参考在该仓库/看板里
+  参考什么，挂在关系上、摘绑即清，与看板组内描述 board.note 同一哲学）；
+  删开发仓库/删看板会同步摘指向它们的绑定，`ref check` 也能查出死链
+- **分层查询**：`repo ref of [id|路径]`（缺省当前目录）——第一层 = 直接绑定到该仓库的 ref，
+  第二层 = 它所在看板（命名空间）上的 ref 按组列出；agent 问「做这个仓库的事有什么参考」
+  用这一条命令就够
+- **布局导入导出 v3**（换机/分享整套环境）：
+
+```bash
+nx-kv repo export                                   # 全局 key + 分组 + 参考关系（不含本地路径）
+nx-kv repo export --zip /path/layout.zip            # 打包成 zip（layout.json + README）
+nx-kv repo export --repos <key1,key2> --boards <board/k1>   # 只导出一部分
+
+nx-kv repo import --diff <file>                     # 差异检查（零副作用）：新增/有差异/一致/本地未拥有
+nx-kv repo import <file> --strategy ours            # 保留本地（默认）
+nx-kv repo import <file> --strategy overwrite       # 用导入文件覆盖（key 不变）
+nx-kv repo import <file> --strategy duplicate       # 另存 key-import-1/2/3，两条并存
+nx-kv repo import <file> --select <key1,key2> --clone ref   # 只处理选中的，并克隆参考仓库
+```
+
+**「本地未拥有」保留占位**：导入时对方分组里有、本地没有的仓库，**位置照抄进组里**
+（组布局完整复制），组内描述也按 key 保留。补齐有两条路：
+
+```bash
+nx-kv repo clone <remote> --key <占位的key>    # 按 remote 克隆并用占位的 key 登记 → 占位自动转正
+nx-kv repo key set <id> <key>                   # 纯自定义 key 的占位：自己建仓库后再指定同一个 key
+```
+
+面板：仓库页 →「参考仓库」面板 →「导入导出」→ 全屏面板（左右两栏，逐条勾选 +
+冲突方案 + 克隆选项）。「本地未拥有」的条目会显示 key 与 remote，有远程地址的可一键
+「克隆到本地」；仓库页的「成员管理」弹窗里也能看到占位成员并补齐。
+
+
 ## SOP
 
 ### 1. 看清单

package/package.json

@@ -1,59 +1,58 @@
-{
-  "name": "nx-kv",
-  "version": "0.11.4",
-  "description": "nx-kv — KV 清单管理中枢（远程）+ 本机本地任务队列（localtask）：serve 驱动 CLI 与 Web 面板，同源同构，附带可安装 skill 供 agent 提交 / 领取 / 阻塞接收任务",
-  "type": "module",
-  "bin": {
-    "nx-kv": "bin/cli.mjs"
-  },
-  "main": "src/index.js",
-  "exports": {
-    ".": "./src/index.js"
-  },
-  "scripts": {
-    "build": "vite build && node scripts/link-local.mjs --auto",
-    "dev": "vite",
-    "dev:serve": "node bin/cli.mjs serve --no-open",
-    "start": "pnpm run build && node bin/cli.mjs serve",
-    "link:local": "node scripts/link-local.mjs",
-    "unlink:local": "node scripts/link-local.mjs --unlink",
-    "lint": "eslint .",
-    "test": "pnpm run lint && pnpm run build && pnpm run test:smoke && pnpm run test:unit",
-    "test:smoke": "node tests/smoke.mjs",
-    "test:unit": "node --test tests/unit/*.test.mjs"
-  },
-  "packageManager": "pnpm@10.33.0",
-  "engines": {
-    "node": ">=18.17"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "assets/",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "keywords": [
-    "cli",
-    "web-panel",
-    "kv",
-    "todo",
-    "agent-tools",
-    "skills",
-    "npx"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/On-DevPlan/nx-kv.git"
-  },
-  "license": "MIT",
-  "devDependencies": {
-    "@vitejs/plugin-react": "^6.1.1",
-    "eslint": "^10.10.0",
-    "vite": "^8.3.0"
-  },
-  "dependencies": {
-    "react": "^19.3.0",
-    "react-dom": "^19.3.0"
-  }
-}
+{
+  "name": "nx-kv",
+  "version": "0.12.1",
+  "description": "nx-kv — KV 清单管理中枢（远程）+ 本机本地任务队列（localtask）：serve 驱动 CLI 与 Web 面板，同源同构，附带可安装 skill 供 agent 提交 / 领取 / 阻塞接收任务",
+  "type": "module",
+  "bin": {
+    "nx-kv": "bin/cli.mjs"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "build": "vite build && node scripts/link-local.mjs --auto",
+    "dev": "vite",
+    "dev:serve": "node bin/cli.mjs serve --no-open",
+    "start": "pnpm run build && node bin/cli.mjs serve",
+    "link:local": "node scripts/link-local.mjs",
+    "unlink:local": "node scripts/link-local.mjs --unlink",
+    "lint": "eslint . && node scripts/check-tdz.mjs --all",
+    "test": "pnpm run lint && pnpm run build && pnpm run test:smoke && pnpm run test:unit",
+    "test:smoke": "node tests/smoke.mjs",
+    "test:unit": "node --test tests/unit/*.test.mjs"
+  },
+  "packageManager": "pnpm@10.33.0",
+  "engines": {
+    "node": ">=18.17"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "assets/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "cli",
+    "web-panel",
+    "kv",
+    "todo",
+    "agent-tools",
+    "skills"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/On-DevPlan/nx-kv.git"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@vitejs/plugin-react": "^6.1.1",
+    "eslint": "^10.10.0",
+    "vite": "^8.3.0"
+  },
+  "dependencies": {
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  }
+}

package/src/core/config.js

@@ -29,6 +29,11 @@ const EMPTY = () => ({
   autoSyncAttachments: false,
   // 附件本地目录覆盖；空 = 用默认 ~/.nx-kv/attachments/<groupId>/
   attachmentsDir: '',
+  // 参考仓库（type=ref）的存储根目录。**空 = clone 拒绝执行**：用户必须显式指一个
+  // 非 C 盘的目录（参考仓库动辄几十 MB～GB 级，不能默默堆进 homedir）。
+  gitRepoRoot: '',
+  // 导入布局时开发仓库（type=dev）的默认克隆根；空 = 导入时 dev 只登记不克隆。
+  gitDevRoot: '',
 });
 
 let cache = null;
@@ -45,6 +50,8 @@ function normalize(data) {
     groupId: Number(data.groupId) || 0,
     autoSyncAttachments: data.autoSyncAttachments === true,
     attachmentsDir: String(data.attachmentsDir || ''),
+    gitRepoRoot: String(data.gitRepoRoot || ''),
+    gitDevRoot: String(data.gitDevRoot || ''),
   };
 }