nx-kv 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,48 +1,100 @@
-# Changelog
-
-本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
-
-## [0.1.0] - 2026-09-16
-
-首个版本。KV 清单（todo）的 CLI + Web 面板，对接 GoFrame KV 后端（默认 `47.110.80.47:8988`）。
-
-### Added
-
-- **清单 CRUD**：`todo list / get / add / update / remove`，覆盖四把 key
-  （`todo:open` / `todo:done` / `todo:freeze` / `todo:topics`）。
-- **状态流转**：`todo done / freeze / unfreeze`，以及 `todo archive` 把旧完成记录归档到冷 key。
-- **主题**：`topic list / add / remove`（带各状态任务数）。
-- **主题提示词**：`prompt set / get / remove` —— 存 `todo:prompt:<topic>`，
-  让 agent「拿任务即拿上下文」。
-- **工作空间完整 CRUD**：`group list / get / add / update / remove`（声明为集合资源，
-  五操作齐备且两端可达）+ `group current / use / members`。
-  切换只改本机配置；解散有前置条件（组内须无 KV），且**不能解散当前使用中的空间**。
-- **面板**：「已完成」列可一键**归档旧记录**（移到 `todo:done:cold:<日期>`）；
-  任一列超过 15 条自动折叠，避免历史记录把待办挤出视野。
-- **认证**：`auth login / logout / status / me`。token 存 `~/.nx-kv/config.json`，
-  密码交互式隐藏输入、**不落盘**。
-- **Web 面板**：`nx-kv serve`，三页（清单 / 工作空间 / 登录），无 emoji、单色、
-  响应式、状态持久化、路径与标识点击即复制。
-- **内置 skill**：`nx-kv skill install` 把 `assets/nx-kv/` 装到 `~/.claude/skills`，
-  供 agent 学会用这个 CLI 领任务。
-- **自省命令**：`routes`（命令 ↔ 路由对照 + `--http` 反查）、`bootstrap`（一次拿齐上下文）、
-  `health`。
-
-### 架构
-
-沿用 server-cli-web 标准骨架：**一条 action 声明同时驱动 CLI、HTTP、面板**，
-三端不可能分叉；分层由 eslint `no-restricted-imports` 强制；
-`tests/unit/registry.test.mjs` 断言模块目录 ↔ 后端注册表 ↔ 前端视图注册表三方对齐。
-
-### 安全
-
-- 后端信封是 `{code,message,data}` 且 **HTTP 恒为 200**，成败看 `code` —— 判断收在一处。
-- `remove` 等变更操作**按数组下标定位**，不按 id 批量过滤。
-- 跨站写请求被 Origin 校验拒绝；静态服务做 resolve 后前缀校验。
-
-### 已知问题
-
-- **`id` 不是唯一键**：分配只扫「待办 + 冻结」，任务完成、待办清空后 id 会被复用，
-  于是 `todo:done` 里会积累同 id 的多条（实测 68 条里有 7 条 id=29）。
-  因此按 id 变更**必须消歧**：`--topic` 收窄、或 `--pick <n>` 按编号选，
-  命中多条时工具**拒绝执行**而不是猜一条。
+# Changelog
+
+本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
+
+## [0.2.0] - 2026-09-26
+
+### Changed
+
+- **⚠️ 破坏性：单条任务操作改为按「内容」定位，不再接受 id。**
+  `todo get / update / remove / done / freeze / unfreeze` 一律改用 `--ref "<内容整串>"`。
+
+  原因是 id 根本不足以定位一条任务：
+  1. 分配只扫「待办 + 冻结」，任务完成后 **id 会被复用**（实测 done 有 68 条、其中 id=29 有 7 条）；
+  2. 同一主题下内容重复本来就是常态（「修复登录页」这类任务会反复投递）。
+
+  `id` 现在只是**给人看的元数据**：仍然分配、仍然出现在 `--json` 输出里
+  （`todo.add` 的返回也保留 `id`，兼容既有调用方），但**不再是任何命令的入参**。
+
+  ```bash
+  # 之前
+  nx-kv todo done 29 --result "已接入"
+  # 现在（内容含空格要加引号）
+  nx-kv todo done --ref "把 watchkv 的告警接进来" --result "已接入"
+  ```
+
+  消歧方式不变：`--pick <n>` 按编号选、`--topic <名字>` 按主题收窄；
+  命中多条时仍然**拒绝猜**。`update` 的消歧旗标是 `--match-topic`。
+
+- **HTTP 路由**：单条操作的路径从 `/api/todo/:id` 等改为固定的 `/api/todo/item`，
+  定位内容走 `ref` 参数（中文文本塞进路径段在编码与可读性上都不划算）。
+  受影响的端点：`GET/PATCH/DELETE /api/todo/item`、
+  `POST /api/todo/done|freeze|unfreeze`。
+
+- **面板**：任务的「同 id 有 N 条」提示改为「同内容×N」；所有按钮改传内容定位。
+  对已走 `/api/todo/:id` 的旧客户端不兼容。
+
+- **默认端口 7820 → 7877**。
+
+### Added
+
+- **`--ref` 为空时报 `INVALID_INPUT`**：挡住「忘了传 --ref 却恰好命中一条 `text` 为空
+  的坏数据」这种随机改数据的路径。
+- **装载期自检**：action 声明里若有 rest 型 flag（吃掉其后全部 token），
+  必须排在 `flags` 最后——否则后面的旗标会被静默吞掉。
+  *当前未启用 rest flag*（它无法与 `--pick` 组合，而消歧比少打引号重要），
+  自检与判定函数留着，供将来启用时不再踩坑。
+- **eslint 约束**：`src/modules/todo/**` 禁止用任务 id 拼定位路径。
+  只保留这一条语法上说得清的规则——`{ id: nextTaskId(...) }`（分配新 id）、
+  `{ task, id: task.id }`（回传）、`#{t.id}`（展示）都与定位无关，
+  会误伤的规则比没有规则更糟。
+
+### Fixed
+
+- `locateAll` 改为**整串精确比对**，不做前缀/模糊匹配——「看起来像」不该被当成「就是它」。
+- 错误文案不再把 id 当作任务标识（`task id=29 不存在` → `task「旧记录」不存在`），
+  改用它真正用来定位的那个键。
+
+## [0.1.0] - 2026-09-16
+
+首个版本。KV 清单（todo）的 CLI + Web 面板，对接 GoFrame KV 后端（默认 `47.110.80.47:8988`）。
+
+### Added
+
+- **清单 CRUD**：`todo list / get / add / update / remove`，覆盖四把 key
+  （`todo:open` / `todo:done` / `todo:freeze` / `todo:topics`）。
+- **状态流转**：`todo done / freeze / unfreeze`，以及 `todo archive` 把旧完成记录归档到冷 key。
+- **主题**：`topic list / add / remove`（带各状态任务数）。
+- **主题提示词**：`prompt set / get / remove` —— 存 `todo:prompt:<topic>`，
+  让 agent「拿任务即拿上下文」。
+- **工作空间完整 CRUD**：`group list / get / add / update / remove`（声明为集合资源，
+  五操作齐备且两端可达）+ `group current / use / members`。
+  切换只改本机配置；解散有前置条件（组内须无 KV），且**不能解散当前使用中的空间**。
+- **面板**：「已完成」列可一键**归档旧记录**（移到 `todo:done:cold:<日期>`）；
+  任一列超过 15 条自动折叠，避免历史记录把待办挤出视野。
+- **认证**：`auth login / logout / status / me`。token 存 `~/.nx-kv/config.json`，
+  密码交互式隐藏输入、**不落盘**。
+- **Web 面板**：`nx-kv serve`，三页（清单 / 工作空间 / 登录），无 emoji、单色、
+  响应式、状态持久化、路径与标识点击即复制。
+- **内置 skill**：`nx-kv skill install` 把 `assets/nx-kv/` 装到 `~/.claude/skills`，
+  供 agent 学会用这个 CLI 领任务。
+- **自省命令**：`routes`（命令 ↔ 路由对照 + `--http` 反查）、`bootstrap`（一次拿齐上下文）、
+  `health`。
+
+### 架构
+
+沿用 server-cli-web 标准骨架：**一条 action 声明同时驱动 CLI、HTTP、面板**，
+三端不可能分叉；分层由 eslint `no-restricted-imports` 强制；
+`tests/unit/registry.test.mjs` 断言模块目录 ↔ 后端注册表 ↔ 前端视图注册表三方对齐。
+
+### 安全
+
+- 后端信封是 `{code,message,data}` 且 **HTTP 恒为 200**，成败看 `code` —— 判断收在一处。
+- `remove` 等变更操作**按数组下标定位**，不按 id 批量过滤。
+- 跨站写请求被 Origin 校验拒绝；静态服务做 resolve 后前缀校验。
+
+### 已知问题
+
+- 历史版本（≤0.1.1）把 `id` 当定位键，而同 id 多条是常态。
+  单条操作现已改为按内容定位（见顶部 0.2.0），数据结构本身不变 ——
+  既有记录里的 id 照旧保留，只是不再参与定位。

package/README.md

@@ -12,13 +12,13 @@ KV 清单（todo）管理中枢。一个 `npx` 命令起一个 Web 面板，同
 pnpm install
 
 # 开发模式（需要两个终端）
-pnpm run dev:serve    # 终端 1：后端 :7820
-pnpm run dev          # 终端 2：Vite :5181，/api 代理到 7820
+pnpm run dev:serve    # 终端 1：后端 :7877
+pnpm run dev          # 终端 2：Vite :5181，/api 代理到 7877
 
 # 生产模式
 pnpm start            # 构建 + 起面板
 
-# 校验：lint + 构建 + 87 项端到端冒烟 + 31 项单元/一致性测试
+# 校验：lint + 构建 + 94 项端到端冒烟 + 33 项单元/一致性测试
 pnpm test
 ```
 
@@ -41,16 +41,16 @@ token 存 `~/.nx-kv/config.json`，**密码不落盘**。配置文件路径可
 nx-kv todo list --status open --topic go --json
 nx-kv prompt get go --json                    # 顺带拿该主题的上下文提示词
 
-# 增删改查
+# 增删改查 —— 单条操作一律按**内容**定位（--ref），不用 id
 nx-kv todo add --topic go "把 watchkv 的告警接进来"
-nx-kv todo get 29 --topic go
-nx-kv todo update 29 --text "改过的内容"
-nx-kv todo remove 29 --topic go
+nx-kv todo get --ref "把 watchkv 的告警接进来"
+nx-kv todo update --ref "旧内容" --text "改过的内容"
+nx-kv todo remove --ref "要删的那条"
 
 # 状态流转
-nx-kv todo done 29 --result "已接入，commit abc123"
-nx-kv todo freeze 29        # 次级需求停放，id 保留
-nx-kv todo unfreeze 29      # 解冻回待办（id 撞车时自动换新 id）
+nx-kv todo done --ref "那条任务" --result "已接入，commit abc123"
+nx-kv todo freeze --ref "那条任务"        # 次级需求停放，id 保留
+nx-kv todo unfreeze --ref "那条任务"      # 解冻回待办（id 撞车时自动换新 id）
 nx-kv todo archive          # 完成记录归档到冷 key（默认 30 天前）
 
 # 主题 / 工作空间
@@ -66,24 +66,40 @@ nx-kv group members 24                        # 成员
 完整命令表由 action 声明自动生成：`nx-kv help`。
 命令与 HTTP 端点互相可查：`nx-kv routes`，反查用 `nx-kv routes --http "POST /api/todo"`。
 
-## ⚠️ id 不是唯一键
+## ⚠️ 定位一律按内容，不按 id
 
-id 分配只扫「待办 + 冻结」，所以任务完成、待办清空后 **id 会被复用**——
-`todo:done` 里因此会积累同 id 的多条（实测 68 条里有 7 条 id=29）。
+待办的 id **非常容易重复**，两条独立的原因：
 
-按 id 变更时工具**拒绝猜**，而是列出候选项让你选：
+1. 分配只扫「待办 + 冻结」，任务完成、待办清空后 **id 会被复用**——
+   `todo:done` 里因此会积累同 id 的多条（实测 68 条里有 7 条 id=29）。
+2. 同一个主题下，内容重复本来就是常态——「修复登录页」这类任务会被反复投递。
+
+所以 `id` 在本项目里**只是给人和外部系统看的元数据**：继续分配、继续出现在输出里，
+但**不再是任何命令的入参**。定位一律用任务内容：
+
+```bash
+nx-kv todo done --ref "把 watchkv 的告警接进来" --result "已接入"
+```
+
+内容命中多条时工具**拒绝猜**，而是列出候选项让你选：
 
 ```
-$ nx-kv todo get 29
-错误: id=29 命中 7 条，无法确定是哪一条。用 --pick <n> 选择：
-  [0] done   qus   2026-08-15T15:09:00.097123  k8s的slb是什么
-  [1] done   qus   2026-08-22T10:40:12.469526  专业远控软件...
-  ...
-
-$ nx-kv todo get 29 --pick 2      # 按编号选
-$ nx-kv todo get 29 --topic fr    # 或按主题收窄
+$ nx-kv todo get --ref "旧记录"
+错误: task「旧记录」命中 3 条，无法确定是哪一条。用 --pick <n> 选择：
+  [0] done   qus   2026-08-15T15:09:00.097123
+  [1] done   qus   2026-08-22T10:40:12.469526
+  [2] done   fr    2026-08-30T10:36:25.731238
 ```
 
+```bash
+nx-kv todo get --ref "旧记录" --pick 1     # 按编号选
+nx-kv todo get --ref "旧记录" --topic fr   # 或按主题收窄
+```
+
+同一规则适用于 `get` / `update` / `remove` / `done` / `freeze` / `unfreeze`。
+`update` 用 `--match-topic` 消歧（`--topic` 在那里表示「改成这个主题」）。
+内容含空格时给 `--ref` 加引号。
+
 ## 架构：action 三端同源
 
 ```

package/assets/nx-kv/SKILL.md

@@ -47,37 +47,39 @@ nx-kv todo list --status open --topic <topic> --json
 # 3. 顺带读走该主题的上下文提示词（这是理解任务的背景，不是可选项）
 nx-kv prompt get <topic> --json
 
-# 4. 完成后回填结果（写进该任务的 note，供人和后续 agent 追溯）
-nx-kv todo done <id> --result "改了什么 / 关键决策 / 遗留问题"
+# 4. 完成后回填结果（--ref 是任务**内容**；结果写进该任务的 note，供人和后续 agent 追溯）
+nx-kv todo done --ref "<任务内容>" --result "改了什么 / 关键决策 / 遗留问题"
 ```
 
 **两条的区别**：`--topic` 不带 `--status` 是「全都要」（含历史），
 `--status open --topic` 是「只要待办」。收单用后者（省上下文），
 做统计/核对/回顾用前者。
 
-## ⚠️ id 不是唯一键（最容易删错数据的地方）
+## ⚠️ 定位一律按内容，不按 id（最容易改错数据的地方）
 
-id 分配只扫「待办 + 冻结」，所以任务完成、待办清空后 **id 会被复用**——
-`todo:done` 里因此会积累同 id 的多条（实测某账号 68 条里有 7 条 id=29）。
+待办的 id **非常容易重复**，两条独立的原因：
 
-因此按 id 变更时工具**拒绝猜**，而是列出候选项让你选：
+1. 分配只扫「待办 + 冻结」，所以任务完成、待办清空后 **id 会被复用**——
+   `todo:done` 里因此会积累同 id 的多条（实测某账号 68 条里有 7 条 id=29）。
+2. 同一个主题下，内容重复本来就是常态——「修复登录页」这类任务会被反复投递。
+
+所以 `id` 只是**给人看的元数据**（继续分配、继续出现在输出里），
+**不是任何命令的入参**。单条操作一律用 `--ref <内容>`：
 
 ```
-$ nx-kv todo get 29
-错误: id=29 命中 7 条，无法确定是哪一条。用 --pick <n> 选择：
-  [0] done   qus   2026-08-15T15:09:00.097123  k8s的slb是什么
-  [1] done   qus   2026-08-22T10:40:12.469526  专业远控软件...
-  ...
-
-$ nx-kv todo get 29 --pick 2      # 按编号选
-$ nx-kv todo get 29 --topic fr    # 或按主题收窄
+$ nx-kv todo get --ref "旧记录"
+错误: task「旧记录」命中 3 条，无法确定是哪一条。用 --pick <n> 选择：
+  [0] done   qus   2026-08-15T15:09:00.097123
+  [1] done   qus   2026-08-22T10:40:12.469526
+  [2] done   fr    2026-08-30T10:36:25.731238
+
+$ nx-kv todo get --ref "旧记录" --pick 2      # 按编号选
+$ nx-kv todo get --ref "旧记录" --topic fr    # 或按主题收窄
 ```
 
 同一规则适用于 `get` / `update` / `remove` / `done` / `freeze` / `unfreeze`。
 `update` 用 `--match-topic` 消歧（`--topic` 在那里表示「改成这个主题」）。
-
-**只在 `todo:open` 和 `todo:freeze` 里 id 才是唯一的**，那里的操作一般不需要消歧。
-`todo:done` 是历史，按 id 操作它**必须**消歧。
+**内容含空格时要加引号**（`--ref "修复登录页 500"`）——`--ref` 是普通 flag，值不会自动吃掉后面的 token。
 
 ## 与 kvcli 的关系
 
@@ -86,7 +88,8 @@ $ nx-kv todo get 29 --topic fr    # 或按主题收窄
 
 - nx-kv 覆盖全部四把 key（`todo:freeze` / `todo:topics`），kvcli 只管 open / done
 - nx-kv 有 Web 面板：`nx-kv serve`
-- nx-kv 对「同 id 多条」有显式防护；kvcli 的 `done` 只在 open 里按 id 匹配
+- nx-kv 单条操作按**内容**定位（`--ref`），kvcli 的 `done` 只在 open 里按 **id** 匹配
+  —— 而 id 会被复用，所以 kvcli 那套在 done 上定位不安全
 - **本 skill 的命令一律写 nx-kv**。若环境里只有 kvcli，见 [[todo-commands]] 末尾的对应关系表
 
 ## Ref 加载引导

package/assets/nx-kv/references/agent-workflow.md

@@ -83,7 +83,7 @@ nx-kv todo list --status open --topic <topic> --json
 ```
 
 **不要「拉全量再自己过滤」**：`--topic` 已经做了，而全量里还混着别的主题和已完成历史
-（done 里有重复 id 和长 note，会白占大量上下文）。
+（done 里带长 note 和大量历史，会白占上下文）。
 
 > ⚠️ **禁止** `nx-kv todo list --json | ...按 topic 过滤...` 这套自己过滤的做法。
 
@@ -133,15 +133,17 @@ nx-kv todo list --status open --topic <topic> --json
 漏掉会让任务一直挂在 open 队列：
 
 ```bash
-nx-kv todo done <id> --result "改了什么 / 怎么验证 / 遗留问题"
+nx-kv todo done --ref "<任务内容整串>" --result "改了什么 / 怎么验证 / 遗留问题"
 ```
 
-- 领取时（Step 2）**记下每条任务的 `<id>`**，回填时用同一个
+- `--ref` 用 Step 2 拿到的 `.text` **原样**传（**不是 `.id`** —— id 会被复用，
+  同一主题下内容重复也是常态，用它定位迟早回填到别的任务上）
+- 内容含空格要加引号：`--ref "修复登录页 500"`
 - `--result` 写清楚，供下次查阅、也供提交方确认
 - 同主题多条任务**逐条解决、逐条回填**，不要攒到最后一次填
 
-> ⚠️ 回填前确认 id 没歧义。done 里会积累同 id 的多条，报「命中 N 条」时用 `--topic` 或 `--pick` 选准
-> —— 详见主文档的「id 不是唯一键」一节。
+> ⚠️ 报「命中 N 条」时说明这个内容有多条，用 `--topic` 或 `--pick` 选准
+> —— 详见主文档的「定位一律按内容」一节。
 
 ## 稳定契约（可依赖）
 
@@ -160,7 +162,7 @@ nx-kv todo done <id> --result "改了什么 / 怎么验证 / 遗留问题"
 ## 安全边界
 
 - **不要**往别的 topic 写任务来「提醒自己」——那是污染别人的队列
-- **不要**在没有消歧的情况下对 `done` 里的 id 做删除
+- **不要**在没有消歧的情况下按相同内容删除 `done` 里的条目
 - 切换工作空间前先确认，别在别人的空间里写数据
 - `--password` 写在命令行里会进 shell 历史；交互式输入更安全
 
@@ -172,7 +174,7 @@ nx-kv todo done <id> --result "改了什么 / 怎么验证 / 遗留问题"
 | `todo list --json` 再自己过滤 topic | 多写一坨过滤逻辑、易错，还把 done 的历史噪音拉进来 | `todo list --status open --topic <t>` 一步到位 |
 | 拿待办时用了不带 `--status open` 的 `list` | done 数组带出重复 id 历史 + 长 note，上下文被大量占用 | 领取待办一律 `--status open --topic <t>`；要看完成历史才用全量 |
 | 解决完不回填 `done` | 任务一直挂 open，队列失真、提交方不知完成 | 解决一条立即回填，`--result` 写明结果 |
-| 回填用错 id | 报了别的任务的完成 | 用 Step 2 拿到的 open 里的那个 id；有歧义时加 `--topic`/`--pick` |
+| 回填定位错 | 报了别的任务的完成 | 用 Step 2 拿到的 `.text` 原样作 `--ref`；有歧义时加 `--topic`/`--pick` |
 | 未登录就调 todo | 报「未登录」exit 1 | 先 `nx-kv auth login <email>` |
 | 沉默清理上下文（丢弃/改写/合并任务文本、prompt、用户背景而不告知） | 信息丢失、用户不知情、难以回滚 | 删除或改写前先问：丢弃 / 改写 / 补充？ |
 | 需要外部资源就直接问（或凭「常识」猜默认值） | 下游全错、用户反复回答、推进变慢 | 先在当前目录穷尽调查，超出能力再问，且必须带「我已查过哪里、缺什么」 |

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

@@ -15,7 +15,7 @@
 
 | 命令 | 说明 |
 | --- | --- |
-| `nx-kv serve [--port 7820] [--no-open]` | 起 Web 面板（`--no-open` 给自动化） |
+| `nx-kv serve [--port 7877] [--no-open]` | 起 Web 面板（`--no-open` 给自动化） |
 | `nx-kv help [模块]` | 命令表（由动作声明生成）；`help todo` / `help group` 均可 |
 | `nx-kv routes [--module M] [--http "METHOD /api/x"]` | 命令 ↔ 路由对照与反查 |
 | `nx-kv bootstrap --json` | 一次拿齐：版本 / 登录态 / 工作空间 / 命令表 |
@@ -37,18 +37,22 @@ nx-kv auth me              # 向后端确认 token 仍有效
 
 ```bash
 nx-kv todo list [--topic T] [--status open|done|freeze|all] [--group N] [--json]
-nx-kv todo get <id> [--topic T] [--pick N] [--group N]
+nx-kv todo get --ref "<内容>" [--topic T] [--pick N] [--group N]
 nx-kv todo add <text> --topic T [--group N]
-nx-kv todo update <id> [--topic T] [--text T] [--note N] [--match-topic T] [--pick N]
-nx-kv todo remove <id> [--topic T] [--pick N]
-nx-kv todo done <id> [--result "完成结果"] [--topic T] [--pick N]
-nx-kv todo freeze <id> [--topic T] [--pick N]
-nx-kv todo unfreeze <id> [--topic T] [--pick N]
+nx-kv todo update --ref "<内容>" [--topic T] [--text T] [--note N] [--match-topic T] [--pick N]
+nx-kv todo remove --ref "<内容>" [--topic T] [--pick N]
+nx-kv todo done --ref "<内容>" [--result "完成结果"] [--topic T] [--pick N]
+nx-kv todo freeze --ref "<内容>" [--topic T] [--pick N]
+nx-kv todo unfreeze --ref "<内容>" [--topic T] [--pick N]
 nx-kv todo archive [--before 2026-08-01] [--group N]
 ```
 
+**单条操作一律用 `--ref` 传任务内容整串，不要用 id**（见下节）。
+内容含空格时加引号：`--ref "修复登录页 500"`。
+
 **CRUD 五操作齐备**（`list` / `get` / `add` / `update` / `remove`），
 且每条都能从 CLI 与 HTTP 两端调用——`tests/unit/registry.test.mjs` 有断言。
+单条操作的 HTTP 路径是 `/api/todo/item`，定位内容走 `ref` 参数（不放路径里）。
 
 **两种取法的区别**：
 
@@ -88,14 +92,14 @@ nx-kv group current
 nx-kv group use <id|name|default>     # 别名：group switch
 ```
 
-## 数据结构
+## ⚠️ 定位按内容（--ref），不按 id
 
 ```jsonc
 // todo:open / todo:done / todo:freeze 里的一条
 {
-  "id": 23,
+  "id": 23,                                     // ★ 仅供展示/互操作，不要用来定位
   "topic": "go",
-  "text": "watchkv",
+  "text": "watchkv",                            // ★ 定位就用这个（整串）
   "createdAt": "2026-08-14T19:04:56.028788",   // Dart 风格：本地时间、无时区
   "doneAt": "",                                 // 完成时写 RFC3339 带偏移
   "note": "",                                   // done --result 写这里
@@ -103,6 +107,20 @@ nx-kv group use <id|name|default>     # 别名：group switch
 }
 ```
 
+id 会重复（分配只扫 open + freeze，完成过的 id 会被复用），
+同一主题下内容重复也是常态。所以：
+
+| 想要 | 写法 |
+| --- | --- |
+| 精确一条 | `--ref "<完整内容>"` |
+| 内容有多条 → 按编号选 | `--ref "<内容>" --pick <n>`（n 从报错里的候选列表取） |
+| 内容有多条 → 按主题收窄 | `--ref "<内容>" --topic <主题>` |
+| `update` 时消歧 | 用 `--match-topic`（`--topic` 表示「改成这个主题」） |
+
+内容命中多条时**报错并列出候选**（exit 1 / code `CONFLICT`），**绝不替你猜**。这是保护，不是 bug。
+
+`--ref` 传空串会报 `INVALID_INPUT`——挡住「忘了传 --ref 却恰好命中一条 text 为空的坏数据」。
+
 | key | 内容 |
 | --- | --- |
 | `todo:open` | Task[] 待办 |
@@ -122,7 +140,7 @@ nx-kv group use <id|name|default>     # 别名：group switch
 | 参数缺失/非法 | 1 | `INVALID_INPUT` |
 | 未登录 / token 失效 | 1 | `INVALID_INPUT`（文本含「未登录」） |
 | 目标不存在 | 1 | `NOT_FOUND` |
-| **同 id 多条需消歧** | 1 | `CONFLICT` |
+| **同内容多条需消歧** | 1 | `CONFLICT` |
 | 状态已是目标（已完成/已冻结） | 1 | `CONFLICT` |
 | 后端不可达 / 返回业务错误 | 1 | `EXTERNAL` |
 
@@ -140,8 +158,8 @@ nx-kv todo add --topic bug "修复登录页 500"
 nx-kv todo list --status open --topic bug --json
 # → [{...},{...}] 纯待办数组
 
-# 记下 id，做完回填
-nx-kv todo done 42 --result "已修复根因: token 过期未刷新；补了 3 个单测"
+# 用返回里的 .text 原样回填（不要用 .id）
+nx-kv todo done --ref "修复登录页 500" --result "已修复根因: token 过期未刷新；补了 3 个单测"
 ```
 
 **主题提示词（让 agent 拿任务即拿上下文）**：
@@ -172,22 +190,28 @@ nx-kv todo list --status open --topic bug    # bug 消费者
 | --- | --- |
 | `nx-kv todo list --status open --topic t` | `kvcli todo --open --topic t` |
 | `nx-kv todo list --topic t` | `kvcli todo list --topic t` |
-| `nx-kv todo get <id>` | `kvcli todo first --topic t`（部分场景） |
-| `nx-kv todo add --topic t "文本"` | `kvcli todo add --topic t "文本"` |
-| `nx-kv todo done <id> --result "..."` | `kvcli todo done <id> --result "..."` |
+| `nx-kv todo get --ref "<内容>"` | `kvcli todo first --topic t`（部分场景） |
+| `nx-kv todo add --topic t "<文本>"` | `kvcli todo add --topic t "<文本>"` |
+| `nx-kv todo done --ref "<内容>" --result "..."` | `kvcli todo done <id> --result "..."`（只能按 id） |
 | `nx-kv prompt get/set/remove --topic t` | `kvcli todo prompt get/set/del --topic t` |
 | （无对应） | —— |
 
+> ⚠️ 换算到 kvcli 的 `done <id>` 时要知道风险：kvcli 按 **id** 在 open 里匹配，
+> 而 id 会被复用。当日志/清单里出现同 id 多条时，它可能完成掉另一条。
+> 能用 nx-kv 就别换算。
+
 **kvcli 没有的能力**：`todo:freeze`、`todo:topics`、`todo archive`、Web 面板、
-以及「同 id 多条」的消歧防护。要用这些就得用 nx-kv。
+以及**按内容定位与「同内容多条」的消歧防护**。要用这些就得用 nx-kv。
 
 ## 避坑
 
 | 坑 | 后果 | 注意 |
 | --- | --- | --- |
-| 按 id 直接改 `done` 里的条目 | 报「命中 N 条」——这是保护，不是 bug | 用 `--topic` 或 `--pick` |
-| `done <id>` 传非数字 | exit 1 | 从 `--json` 输出里取 `.id` |
+| **拿 id 去定位**（`--ref 29` / `todo done 29`） | 报「不存在」，或命中一条完全不相干的记录 | id 不是定位键。`--ref` 要传**内容整串** |
+| 「同内容」有多条 | 报「命中 N 条」——这是保护，不是 bug | 用 `--topic` 收窄，或 `--pick <n>` 按编号选 |
+| `--ref` 忘了加引号 | 内容被空格切碎，报「多余的参数」 | `--ref "修复登录页 500"` |
+| 漏传 `--ref` / 传空串 | exit 1，`INVALID_INPUT` | 空串会被挡下，不会误命中 text 为空的坏条目 |
 | `add` 漏 `--topic` | exit 1，`--topic 必填` | 必带 |
 | 未登录就调 todo | exit 1「未登录」 | 先 `auth login` |
 | 以为切换 group 会改服务端 | 只改本机配置 | 数据一直在服务端，切换只是换个 groupId |
-| 领取待办时用了全量 `list` | done 的重复 id + 长 note 白占上下文 | 一律 `--status open --topic <t>` |
+| 领取待办时用了全量 `list` | done 的历史 + 长 note 白占上下文 | 一律 `--status open --topic <t>` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nx-kv",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "nx-kv — KV 清单管理中枢：serve 驱动 CLI 与 Web 面板，同源同构，附带可安装 skill 供 agent 领取主题任务",
   "type": "module",
   "bin": {

package/src/core/paths.js

@@ -6,7 +6,7 @@ import { badInput } from './errors.js';
 export const APP_NAME = 'nx-kv';
 export const APP_DIR = join(homedir(), '.nx-kv');
 export const STORE_PATH = join(APP_DIR, 'store.json');
-export const DEFAULT_PORT = 7820;
+export const DEFAULT_PORT = 7877;
 
 // 允许测试与多实例覆盖存储位置：NX_KV_STORE 环境变量优先
 export function storePathFromEnv() {