nx-kv 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# 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>` 按编号选，
+  命中多条时工具**拒绝执行**而不是猜一条。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 On-DevPlan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# nx-kv
+
+KV 清单（todo）管理中枢。一个 `npx` 命令起一个 Web 面板，同时提供同构 CLI——
+**面板上的每个按钮，底层都是同一条 CLI 命令**，输出 `--json` 即可被任何 agent 直接消费。
+
+对接 GoFrame KV 后端（默认 `http://47.110.80.47:8988`），
+数据落在**四把 key** 上：`todo:open` / `todo:done` / `todo:freeze` / `todo:topics`。
+
+## 快速开始
+
+```bash
+pnpm install
+
+# 开发模式（需要两个终端）
+pnpm run dev:serve    # 终端 1：后端 :7820
+pnpm run dev          # 终端 2：Vite :5181，/api 代理到 7820
+
+# 生产模式
+pnpm start            # 构建 + 起面板
+
+# 校验：lint + 构建 + 87 项端到端冒烟 + 31 项单元/一致性测试
+pnpm test
+```
+
+冒烟测试**对着假后端跑**（`tests/fake-backend.mjs`），不会碰生产服务器上的真实数据。
+
+## 登录
+
+```bash
+nx-kv auth login <email>          # 交互式隐藏输入密码
+nx-kv auth status                 # 看登录态（离线可读）
+```
+
+token 存 `~/.nx-kv/config.json`，**密码不落盘**。配置文件路径可用 `NX_KV_CONFIG`
+环境变量或 `--config` 覆盖。
+
+## 常用命令
+
+```bash
+# 取某个主题的全部待办（agent 首选）
+nx-kv todo list --status open --topic go --json
+nx-kv prompt get go --json                    # 顺带拿该主题的上下文提示词
+
+# 增删改查
+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 done 29 --result "已接入，commit abc123"
+nx-kv todo freeze 29        # 次级需求停放，id 保留
+nx-kv todo unfreeze 29      # 解冻回待办（id 撞车时自动换新 id）
+nx-kv todo archive          # 完成记录归档到冷 key（默认 30 天前）
+
+# 主题 / 工作空间
+nx-kv topic list
+nx-kv group list
+nx-kv group use shared      # 切换工作空间（只改本机配置）
+nx-kv group add 新空间 --description "..."   # 建
+nx-kv group update 507 --name 改个名          # 改
+nx-kv group remove 507                        # 解散（组内须无 KV）
+nx-kv group members 24                        # 成员
+```
+
+完整命令表由 action 声明自动生成：`nx-kv help`。
+命令与 HTTP 端点互相可查：`nx-kv routes`，反查用 `nx-kv routes --http "POST /api/todo"`。
+
+## ⚠️ id 不是唯一键
+
+id 分配只扫「待办 + 冻结」，所以任务完成、待办清空后 **id 会被复用**——
+`todo:done` 里因此会积累同 id 的多条（实测 68 条里有 7 条 id=29）。
+
+按 id 变更时工具**拒绝猜**，而是列出候选项让你选：
+
+```
+$ 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    # 或按主题收窄
+```
+
+## 架构：action 三端同源
+
+```
+┌──────────────┐   ┌──────────────┐   ┌──────────────┐
+│  Web 面板     │   │   agent CLI  │   │  HTTP API    │
+└───────┬──────┘   └───────┬──────┘   └───────┬──────┘
+        └──────────────────┼──────────────────┘
+                           ▼
+        ┌──────────────────────────────────────────┐
+        │  action 声明（每个功能域的 index.js）      │
+        │  { cli: [...], http: [...], run, render } │
+        └──────────────────┬───────────────────────┘
+                           ▼
+        ┌──────────────────────────────────────────┐
+        │  service 层（唯一业务真相源）              │
+        └──────────────────┬───────────────────────┘
+                           ▼
+        ┌──────────────────────────────────────────┐
+        │  core：KV 客户端 / 配置 / 错误 / 存储      │
+        └──────────────────────────────────────────┘
+```
+
+**一条 action 同时声明 CLI 命令路径与 HTTP 路由**，二者写在同一处，
+所以「Web 上能做的，CLI 都能做」是结构保证而非口头约定。
+
+```
+src/core/          零业务语义：kvapi(后端客户端) / config(本机配置) / errors / fstree
+src/modules/       功能域：system / auth / group / todo / bundled
+src/runtime/       装配层：registry / spec / cli / api / server
+src/web/frontend/  React 壳
+assets/nx-kv/      内置 skill（agent 操作手册）
+```
+
+分层由 `eslint.config.js` 的 `no-restricted-imports` 强制；
+`tests/unit/registry.test.mjs` 断言模块目录 ↔ 后端注册表 ↔ 前端视图注册表三方对齐。
+
+## 给 agent 用
+
+```bash
+nx-kv skill install      # 装到 ~/.claude/skills/nx-kv
+```
+
+装好后 agent 就能按 skill 里的 SOP 领任务、读主题上下文、完成后回填结果。
+
+## License
+
+MIT

package/assets/nx-kv/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: nx-kv
+description: KV 清单（todo）的收单与操作 —— 既用来**领取任务、确认意图、完成后回填**，也用来直接读写清单、维护主题提示词、在多个工作空间之间切换。触发词：领取任务、我的待办、看一下我的任务、某主题的任务（如「go 主题的任务」）、发布的任务、发布任务、收单、先确认再执行、把任务聚个类、任务队列、todo、清单、完成回填、给主题配上下文、切换工作空间/group。凡「提交方 → KV 清单 → agent 消费」这条任务流里 agent 一侧的收单动作，或任何要直接操作清单的命令，都走本 skill。
+---
+
+# nx-kv — 收单流程 + 命令手册
+
+KV 清单（todo）的操作入口。四把 key 上的任务管理，对接 GoFrame KV 后端。
+
+> 历史：本 skill 合并了原先独立的 `taskget`。以前它走 `kvcli`，现在统一走 `nx-kv`——
+> 后者是同一后端的 Node 实现，多了 Web 面板、覆盖全部四把 key（含 freeze / topics）、
+> 且随包自带本 skill（`nx-kv skill install` 一条命令装好）。
+
+## 先判断你要做哪件事
+
+| 你要做的事 | 读哪份 |
+| --- | --- |
+| **领任务 / 收单**：按主题拉待办 → 读上下文 → 与用户对齐意图 → 完成后回填 | [[agent-workflow]] |
+| **查命令**：要敲哪条、退出码、数据结构、避坑 | [[todo-commands]] |
+
+两份都是按需加载，不要一开始就全读进来。
+
+## 前置
+
+```bash
+nx-kv auth login <email>     # 交互式隐藏输入密码；同时记住后端地址
+nx-kv auth status            # 看登录态（离线可读本机配置）
+nx-kv group current          # 当前工作空间
+```
+
+**所有清单操作都需要登录**，否则报「未登录」并 exit 1。
+
+数据按 `groupId` 隔离。**先确认工作空间对不对**——在错的空间里会「什么都查不到」，
+而那不是「没有任务」，是「看错地方了」。
+
+## 最常用的四条
+
+```bash
+# 1. 取某主题的全部任务（三个桶一次拿全：待办 + 已完成 + 冻结）
+nx-kv todo list --topic <topic> --json
+# → { topic, status:'all', open:[...], done:[...], freeze:[...], topics:[...] }
+
+# 2. 只取待办（收单首选；只读一把 key，不带已完成历史，省上下文）
+nx-kv todo list --status open --topic <topic> --json
+# → open:[...] 非空，done/freeze 为 null
+
+# 3. 顺带读走该主题的上下文提示词（这是理解任务的背景，不是可选项）
+nx-kv prompt get <topic> --json
+
+# 4. 完成后回填结果（写进该任务的 note，供人和后续 agent 追溯）
+nx-kv todo done <id> --result "改了什么 / 关键决策 / 遗留问题"
+```
+
+**两条的区别**：`--topic` 不带 `--status` 是「全都要」（含历史），
+`--status open --topic` 是「只要待办」。收单用后者（省上下文），
+做统计/核对/回顾用前者。
+
+## ⚠️ id 不是唯一键（最容易删错数据的地方）
+
+id 分配只扫「待办 + 冻结」，所以任务完成、待办清空后 **id 会被复用**——
+`todo:done` 里因此会积累同 id 的多条（实测某账号 68 条里有 7 条 id=29）。
+
+因此按 id 变更时工具**拒绝猜**，而是列出候选项让你选：
+
+```
+$ 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    # 或按主题收窄
+```
+
+同一规则适用于 `get` / `update` / `remove` / `done` / `freeze` / `unfreeze`。
+`update` 用 `--match-topic` 消歧（`--topic` 在那里表示「改成这个主题」）。
+
+**只在 `todo:open` 和 `todo:freeze` 里 id 才是唯一的**，那里的操作一般不需要消歧。
+`todo:done` 是历史，按 id 操作它**必须**消歧。
+
+## 与 kvcli 的关系
+
+两者对接同一后端、同一份数据，可以混用（`kvcli auth login` 与 `nx-kv auth login` 各自存 token）。
+差异：
+
+- nx-kv 覆盖全部四把 key（`todo:freeze` / `todo:topics`），kvcli 只管 open / done
+- nx-kv 有 Web 面板：`nx-kv serve`
+- nx-kv 对「同 id 多条」有显式防护；kvcli 的 `done` 只在 open 里按 id 匹配
+- **本 skill 的命令一律写 nx-kv**。若环境里只有 kvcli，见 [[todo-commands]] 末尾的对应关系表
+
+## Ref 加载引导
+
+| ref | 何时读取 | 路径 |
+| --- | --- | --- |
+| [[agent-workflow]] | 要**领任务/收单**时——按主题拉待办、读上下文、与用户对齐意图、回填结果的完整 SOP | references/agent-workflow.md |
+| [[todo-commands]] | 要**敲具体命令**、查退出码/数据结构/避坑时 | references/todo-commands.md |
+
+**不要预先全读**：收单才读前者，查命令才读后者；平时它们不进上下文。

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

@@ -0,0 +1,178 @@
+# 场景：领任务 · 确认意图 · 再解决
+
+> 归属主文档 [[nx-kv]]。当你是**任务队列的消费端**——提交方把任务投到某个 `topic`，
+> 你负责领任务、对齐意图、做完回填——读本文件。
+
+关键在中间那几步「确认」：**不确认不动手**。任务往往模糊、多条、或覆盖多个主题，
+先对齐能避免大段返工。
+
+## 何时进入
+
+- 用户让你「领取 / 看一下 / 处理」某个主题的任务
+- 用户提到「发布的任务」「任务队列」「todo 清单」「待办」
+- 你被分配了清单上的任务，需要消费
+- 用户要求「先确认意图再执行」「把任务聚类成文档」
+
+不确定是否该进入时，**倾向进入**——这比跳过确认直接开干安全得多。
+
+## 两条行为准则（必读，覆盖全流程）
+
+> 遇到相应场景**主动先问用户**再行动，不要沉默地自行处理。
+
+### 1. 清理 / 覆盖上下文时，先问用户
+
+删除、改写、合并、丢弃任何上下文信息（任务文本、topic 提示词、之前的状态、用户给的背景）
+之前，主动向用户确认：**是要丢弃、改写还是补充？**
+
+沉默的清理 = 信息丢失 + 用户不知情。
+
+### 2. 先自己查到底，摸不到底再问
+
+拿到需求 → **先别问、自己去摸** → 摸不到底再问。
+
+**第一步：在当前目录穷尽调查。** 翻代码、读文档、读配置、查 git 历史、看相关任务、
+跑命令验证、读测试、用 grep/find 搜。
+
+- 当前目录**能回答的，不许问用户**
+- 不许「凭常识猜默认值」「还没查就先问」「查到一半就问」、把能查到的推给用户
+
+**第二步：确实超出当前目录能力，才问用户。** 确认无法解决后，告诉用户
+「**我已经查过 X、Y、Z，缺的是 W，请提供**」——把已查证据一起摆出来。
+
+真的需要外部资源的：配置项 / 凭据 / 外部 prompt / 别的项目文件 / 用户主观偏好 / 业务决策。
+
+> 反例：任务说「线上如何访问」，直接问「线上地址是？」。正确做法是先看 `deploy.yml` /
+> `docker-compose` / `README` / `docs`，能推断就推断，推断不出再问并摆已查证据。
+
+## 前置依赖
+
+- **动手前必须调用** `superpowers:writing-plans`
+- 时机：**Step 7 确认主题意图之后、Step 8 开始解决之前**
+- 把已确认的意图作为 spec 交给它，产出实现计划（存 `docs/superpowers/plans/YYYY-MM-DD-<feature>-indent.md`），**按计划**再解决
+- 任务拆分、写法、执行交接都以 `superpowers:writing-plans` 为准，本文件不重复
+
+## 核心流程（8 步）
+
+```mermaid
+flowchart LR
+  A[1 确认登录与工作空间] --> B[2 取该 topic 全部待办]
+  B --> C[3 读上下文提示词 + 润色]
+  C --> D[4 不立即执行 → 摆给用户确认/补充]
+  D --> E{多条任务?}
+  E -- 是 --> F[5 按主题聚类]
+  F --> G[6 生成意图文档]
+  G --> H[7 确认主题意图 + writing-plans]
+  E -- 否 --> H
+  H --> I[8 解决 + done 回填]
+```
+
+### Step 1 — 先确认登录与工作空间
+
+```bash
+nx-kv auth status --json     # loggedIn / groupId
+nx-kv group current          # 当前在哪个空间
+```
+
+**先确认空间对不对**：数据按 `groupId` 隔离，在错的空间里会「什么都查不到」——
+而那不是「没有任务」，是「看错地方了」。这一步不花什么时间，却能避免整轮白干。
+
+### Step 2 — 一次拿全该 topic 的待办
+
+```bash
+nx-kv todo list --status open --topic <topic> --json
+```
+
+**不要「拉全量再自己过滤」**：`--topic` 已经做了，而全量里还混着别的主题和已完成历史
+（done 里有重复 id 和长 note，会白占大量上下文）。
+
+> ⚠️ **禁止** `nx-kv todo list --json | ...按 topic 过滤...` 这套自己过滤的做法。
+
+### Step 3 — 读上下文提示词 + 润色
+
+**探索整个项目时派一个 subagent 收集上下文**，比你自己逐个文件翻更省上下文：
+
+- 读该 topic 的提示词：`nx-kv prompt get <topic> --json`（`{topic, prompt, hasPrompt}`）
+  —— 它是 topic 级的共享背景（项目约定、技术栈、注意事项），**不是可选项**：缺了它，任务往往只是「半句话需求」
+- 读任务文本，把含糊措辞、缺的信息、明显的错误标出来
+- 把每条任务**改写成清晰的表述**（可执行、有边界、可验收），但**不改原意**
+- 可选：让 subagent 一并返回相关的、可作为依据的 skill 条目
+
+### Step 4 — 不要立即执行，先摆给用户确认
+
+拿到任务**先停下来**。直接开干是这里最常见的错误。
+
+把润色后的任务清单摆给用户：
+
+- 每条确认「你理解得对不对」
+- 让用户补充缺失的背景、约束、优先级
+- 合并 / 删除过时任务在这里一并敲定
+
+### Step 5 — 按主题聚类
+
+若有多条任务，按**主题**聚类（如「CLI 重构」「测试补全」「文档」各成一簇）。
+一条任务只属一簇，簇名即主题意图。
+
+### Step 6 — 生成意图文档
+
+把聚类结果写成结构化文档（如 `.claude/repo/_self/<主题>-意图.md` 或
+`docs/superpowers/specs/` 下的设计文档）：
+
+- 每个主题：任务列表、目标、上下文/提示词摘要、边界、验收标准
+- 文档既是 Step 7 确认的载体，也是后续执行的依据
+
+### Step 7 — 确认主题意图 → 交给 writing-plans
+
+把文档 / 聚类结果交给用户确认每个主题的意图与优先级。**用户拍板后才算对齐。**
+
+对齐后**立即调用 `superpowers:writing-plans`**，把已确认的意图作为 spec 产出实现计划。
+计划落地后才进 Step 8。
+
+### Step 8 — 按计划解决 → **完成即回填 `todo done`**
+
+按主题逐簇解决。**每解决完一条，立即回填**——这是收单闭环的最后一步，
+漏掉会让任务一直挂在 open 队列：
+
+```bash
+nx-kv todo done <id> --result "改了什么 / 怎么验证 / 遗留问题"
+```
+
+- 领取时（Step 2）**记下每条任务的 `<id>`**，回填时用同一个
+- `--result` 写清楚，供下次查阅、也供提交方确认
+- 同主题多条任务**逐条解决、逐条回填**，不要攒到最后一次填
+
+> ⚠️ 回填前确认 id 没歧义。done 里会积累同 id 的多条，报「命中 N 条」时用 `--topic` 或 `--pick` 选准
+> —— 详见主文档的「id 不是唯一键」一节。
+
+## 稳定契约（可依赖）
+
+| 契约 | 内容 |
+| --- | --- |
+| `--json` | 单个 JSON 值到 stdout；无多余文本 |
+| 退出码 | `0` 成功；`1` 失败（含需消歧的情况） |
+| 错误码 | `code` 可取 `INVALID_INPUT` / `NOT_FOUND` / `CONFLICT` / `EXTERNAL`，优先用它分支 |
+| 错误文本 | 含「未登录」「不存在」「用法:」等稳定锚点，可作兜底判断 |
+| 幂等 | 重复 `topic add`、删除不存在的主题都不报错 |
+| 状态冲突 | 已完成再 `done`、已冻结再 `freeze` → `CONFLICT` + exit 1；语义是「已经是你要的」，跳过即可 |
+
+**一次拿齐上下文**：`nx-kv bootstrap --json` 返回版本、登录态、当前工作空间、
+工作空间列表与完整命令表，省去多次往返。
+
+## 安全边界
+
+- **不要**往别的 topic 写任务来「提醒自己」——那是污染别人的队列
+- **不要**在没有消歧的情况下对 `done` 里的 id 做删除
+- 切换工作空间前先确认，别在别人的空间里写数据
+- `--password` 写在命令行里会进 shell 历史；交互式输入更安全
+
+## 避坑
+
+| 坑 | 后果 | 正确做法 |
+| --- | --- | --- |
+| 直接动手不先确认意图 | 任务文本常是半句话，盲目执行必返工 | 走 Step 4：润色 → 摆给用户 → 用户补充 |
+| `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` |
+| 未登录就调 todo | 报「未登录」exit 1 | 先 `nx-kv auth login <email>` |
+| 沉默清理上下文（丢弃/改写/合并任务文本、prompt、用户背景而不告知） | 信息丢失、用户不知情、难以回滚 | 删除或改写前先问：丢弃 / 改写 / 补充？ |
+| 需要外部资源就直接问（或凭「常识」猜默认值） | 下游全错、用户反复回答、推进变慢 | 先在当前目录穷尽调查，超出能力再问，且必须带「我已查过哪里、缺什么」 |

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

@@ -0,0 +1,193 @@
+# nx-kv 命令参考
+
+> 归属主文档 [[nx-kv]]。**当且仅当**要执行具体命令、或校验退出码/输出结构时加载本文件。
+> 覆盖：前置条件、命令清单、退出码、数据结构、典型用法、与 kvcli 的对应关系、避坑。
+
+## 前置条件
+
+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` 临时覆盖，或写进配置
+
+所有清单操作都需要登录，否则报「未登录」并 exit 1。
+
+## 全局
+
+| 命令 | 说明 |
+| --- | --- |
+| `nx-kv serve [--port 7820] [--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` | 一次拿齐：版本 / 登录态 / 工作空间 / 命令表 |
+| `nx-kv health` | 本机配置 + 后端可达性 |
+| `--config <path>` | 本次运行覆盖配置文件（默认 `~/.nx-kv/config.json`） |
+
+## 认证
+
+```bash
+nx-kv auth login <email> [--password P] [--baseUrl URL]
+nx-kv auth logout
+nx-kv auth status          # 离线可读，不请求后端
+nx-kv auth me              # 向后端确认 token 仍有效
+```
+
+`--password` 省略时进入**隐藏式交互输入**。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 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 archive [--before 2026-08-01] [--group N]
+```
+
+**CRUD 五操作齐备**（`list` / `get` / `add` / `update` / `remove`），
+且每条都能从 CLI 与 HTTP 两端调用——`tests/unit/registry.test.mjs` 有断言。
+
+**两种取法的区别**：
+
+| 想要 | 命令 | 拿到 |
+| --- | --- | --- |
+| **某主题的全部任务** | `nx-kv todo list --topic T` | 三个桶：待办 + 已完成 + 冻结 |
+| 只要待办（收单首选） | `nx-kv todo list --status open --topic T` | 只读一把 key，无历史噪音 |
+| 只要完成历史 | `nx-kv todo list --status done --topic T` | 含完成结果 note |
+| 只要冻结区 | `nx-kv todo list --status freeze --topic T` | 次级需求停放区 |
+
+不带 `--topic` 时就是全量（所有主题）。
+
+## 主题与提示词
+
+```bash
+nx-kv topic list                      # 含各状态任务数
+nx-kv topic add <name>
+nx-kv topic remove <name>             # 移出候选；仍有任务在用时会提示条数
+
+nx-kv prompt set <topic> "<上下文>"
+nx-kv prompt get <topic> [--json]     # --json → {topic,prompt,hasPrompt}
+nx-kv prompt remove <topic>
+```
+
+`todo:prompt:<topic>` 是**纯文本**（不是 JSON），存该主题的共享上下文。
+
+## 工作空间
+
+```bash
+nx-kv group list
+nx-kv group get <id|name>
+nx-kv group add <name> [--description D]
+nx-kv group update <id> [--name N] [--description D]
+nx-kv group remove <id>               # 解散；不能删当前使用中的，且后端要求组内无 KV
+nx-kv group members <id>
+nx-kv group current
+nx-kv group use <id|name|default>     # 别名：group switch
+```
+
+## 数据结构
+
+```jsonc
+// todo:open / todo:done / todo:freeze 里的一条
+{
+  "id": 23,
+  "topic": "go",
+  "text": "watchkv",
+  "createdAt": "2026-08-14T19:04:56.028788",   // Dart 风格：本地时间、无时区
+  "doneAt": "",                                 // 完成时写 RFC3339 带偏移
+  "note": "",                                   // done --result 写这里
+  "frozenAt": ""                                // 冻结时写 Dart 风格
+}
+```
+
+| key | 内容 |
+| --- | --- |
+| `todo:open` | Task[] 待办 |
+| `todo:done` | Task[] 已完成（含完成结果 note） |
+| `todo:freeze` | Task[] 冻结（次级需求停放区，id 保留） |
+| `todo:topics` | String[] 快捷主题列表 |
+| `todo:prompt:<topic>` | 纯文本：该主题的上下文提示词 |
+| `todo:done:cold:<日期>` | Task[] 冷归档（app 只写不查） |
+
+两种时间格式在同一份数据里并存是**既成事实**，nx-kv 按字段各自的约定写，不做统一。
+
+## 退出码与错误码
+
+| 情形 | exit | code |
+| --- | --- | --- |
+| 成功 | 0 | — |
+| 参数缺失/非法 | 1 | `INVALID_INPUT` |
+| 未登录 / token 失效 | 1 | `INVALID_INPUT`（文本含「未登录」） |
+| 目标不存在 | 1 | `NOT_FOUND` |
+| **同 id 多条需消歧** | 1 | `CONFLICT` |
+| 状态已是目标（已完成/已冻结） | 1 | `CONFLICT` |
+| 后端不可达 / 返回业务错误 | 1 | `EXTERNAL` |
+
+**脚本里只看退出码判定成败**，不要 parse 人类文案（需要分支时用 `code`）。
+
+## 典型用法
+
+**收单一条龙**（提交 → 拉取 → 回填）：
+
+```bash
+# 提交方
+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 个单测"
+```
+
+**主题提示词（让 agent 拿任务即拿上下文）**：
+
+```bash
+nx-kv prompt set go "Go 1.25; 多模块 go.work; 优先标准库; 错误用 fmt.Errorf+%w"
+nx-kv prompt get go --json     # → {"topic":"go","prompt":"...","hasPrompt":true}
+```
+
+**多消费者各拉各的**：
+
+```bash
+nx-kv todo add --topic docs "更新 API 文档"
+nx-kv todo add --topic bug  "登录页 500"
+
+nx-kv todo list --status open --topic docs   # docs 消费者
+nx-kv todo list --status open --topic bug    # bug 消费者
+```
+
+**空 open 的处理**：列表为空时输出「待办: （空）」（JSON 模式给空数组），exit 0。
+脚本据此判定无任务可做。
+
+## 与 kvcli 的对应关系
+
+两者对接同一后端、同一份数据。环境里只有 `kvcli` 时按下表换算：
+
+| 本 skill 写法 | 等价的 kvcli 写法 |
+| --- | --- |
+| `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 prompt get/set/remove --topic t` | `kvcli todo prompt get/set/del --topic t` |
+| （无对应） | —— |
+
+**kvcli 没有的能力**：`todo:freeze`、`todo:topics`、`todo archive`、Web 面板、
+以及「同 id 多条」的消歧防护。要用这些就得用 nx-kv。
+
+## 避坑
+
+| 坑 | 后果 | 注意 |
+| --- | --- | --- |
+| 按 id 直接改 `done` 里的条目 | 报「命中 N 条」——这是保护，不是 bug | 用 `--topic` 或 `--pick` |
+| `done <id>` 传非数字 | exit 1 | 从 `--json` 输出里取 `.id` |
+| `add` 漏 `--topic` | exit 1，`--topic 必填` | 必带 |
+| 未登录就调 todo | exit 1「未登录」 | 先 `auth login` |
+| 以为切换 group 会改服务端 | 只改本机配置 | 数据一直在服务端，切换只是换个 groupId |
+| 领取待办时用了全量 `list` | done 的重复 id + 长 note 白占上下文 | 一律 `--status open --topic <t>` |