nx-kv 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.8.0] - 2026-10-11
+
+### Added
+
+- **新增内置 skill `kv-submit`（提交侧）**：把当前对话总结上下文、提炼出用户需求，
+  打包成自包含任务文本，通过 `nx-kv localtask add --cwd "<目标目录>"` 委托给在
+  别的目录工作的 agent；含任务文本模板、拆分/排序/跟踪与避坑清单
+  （`references/submit-workflow.md`）。
+- **新增内置 skill `kv-localget`（领取侧）**：agent 在自己目录里主动领取排给本目录
+  的任务（`localtask list` 查看待领取、`wait` 队列非空时立即取走），附单条
+  查看/编辑/删除/调序等队列管理。
+
+### Changed
+
+- **⚠️ 破坏性：功能域「实时任务输入」更名为「本地任务」（localtask），阻塞等待（wait）
+  只是其中的一个子功能。**
+  - CLI 子命令 `nx-kv sessiontask *` → `nx-kv localtask *`（add / list / get / update /
+    remove / reorder / config / prune / wait / topic remove / topic remove-many）；
+  - HTTP 路由 `/api/sessiontasks*` → `/api/localtasks*`；面板页「实时任务」→「本地任务」，
+    弹窗标题与面板内命令示例同步更新；
+  - 存储文件 `~/.nx-kv/sessiontasks.json` → `localtasks.json`：新文件缺失时自动读取
+    旧文件、首次保存落到新文件（旧文件保留不删），队列数据零丢失；存储路径环境变量
+    改名 `NX_KV_LOCALTASK_STORE`，旧名 `NX_KV_SESSIONTASK_STORE` 仍然兼容。
+- **内置 skill `kv-sessiontask` 重命名为 `kv-waittask`（等待侧）**：安装名、group 名
+  同步改为 `kv-waittask`（`nx-kv skill install kv-waittask`）；CLI 命令名随上一条改。
+  已装旧版的用户重新 `skill install kv-waittask` 即可，旧
+  `~/.claude/skills/kv-sessiontask/` 目录可手动删除。
+- **内置 skill `kv-local` 定名前改名为 `kv-localget`（领取侧）**：随本版首次发布，
+  无迁移成本。
+- **kv-waittask 文档对齐 v4 队列模型**：现状总结只是状态展示（并记录为被取走任务的
+  「本轮完成总结」），不再作为等待点 key；队列按工作目录划分、同目录多次 wait
+  共用同一队列，任务按先后领取。工具调用超时建议从 120000ms 修正为 300000ms
+  （CLI 默认阻塞 180 秒）。README 同步修正该节。
+
+## [0.7.0] - 2026-10-09
+
+### Added
+
+- **支持删除整个主题与批量删除**：
+  - 「实时任务」页主题卡片右下角新增「删除主题」，一次删除该主题及其全部任务；
+  - 卡片左上角可勾选（总览标题处支持「全选」），顶部「批量删除 (N)」一键删除多个主题。
+  - 新增 CLI/HTTP：
+    - `nx-kv sessiontask topic remove --cwd "<目录>"`（或 `--key`）/ `DELETE /api/sessiontasks/topic`；
+    - `nx-kv sessiontask topic remove-many --keys "<k,k>"`（也可 `--cwds` 或 `--all`）
+      / `POST /api/sessiontasks/topics/remove`。
+  - 安全保护：等待中的主题默认不删（避免阻塞的 agent 干等到超时），界面二次确认、
+    命令加 `--force` 才连等待中一起删；批量返回 `{count,removed,skipped}`，skipped
+    列出被跳过的「等待中 / 不存在」主题。
+- 新增删除/批量删除单测与冒烟断言。
+
 ## [0.6.0] - 2026-10-08
 
 ### Added

package/README.md

@@ -66,28 +66,34 @@ nx-kv group members 24                        # 成员
 完整命令表由 action 声明自动生成：`nx-kv help`。
 命令与 HTTP 端点互相可查：`nx-kv routes`，反查用 `nx-kv routes --http "POST /api/todo"`。
 
-## 实时任务输入（对话内连续提交）
+## 本地任务（localtask，不需登录）
 
-在一个对话里，agent 完成当前任务、提交结果、需要下一条输入时，可调用**阻塞式**
-命令等用户在浏览器回填，替代在原始输入框打字：
+本机任务队列，按**工作目录**划分（目录名即主题）：提交（`add`）、领取（`wait`）、
+队列管理（`list / get / update / remove / reorder`）与主题管理（`topic remove /
+remove-many`）。阻塞等待弹窗只是 `wait` 当前的一个子功能。三个 skill 角色共用
+同一条队列、一套存储：
 
 ```bash
-# 本轮【最后一步】：阻塞并自动打开浏览器弹窗（工具调用超时需设为 120000ms）
-nx-kv sessiontask wait --summary "<当前现状总结>" --json
-# 成功 → {status:"ok", task:{text,...}}；120 秒未回填 → {status:"timeout"}（exit 0）
+# 等待侧：agent 本轮【最后一步】阻塞等浏览器回填（工具调用超时设 300000ms）
+nx-kv localtask wait --summary "<当前现状总结>" --json
+# 队列非空 → 立即取走（queued:true）；空 → 开窗阻塞，默认 180 秒未回填 → {status:"timeout"}（exit 0）
+
+# 提交侧：把提炼好的任务投进目标目录的队列，委托在那边工作的 agent
+nx-kv localtask add "<任务文本>" --cwd "<目标工作目录>" --json
 ```
 
-**现状总结即等待点 key**：同现状用同一句总结复用同一等待点，新现状换新句分散为
-新等待点。弹窗/面板顶部直接显示现状，用户不读对话也能快速了解、点选等待点
-**分别回填（分散答复）**，也可提前排队；等待点非空时 wait 立即取走、不开窗。
-纯本机协调、存本地文件，**不需登录后端**。其余命令：
-`sessiontask list / add / get / update / remove`（均按 `--summary` 定位），
-面板上对应「实时任务」页。
+现状总结只作展示（弹窗/面板顶部），不参与队列分桶；任务按各目录队列的先后
+领取。其余命令：`localtask list / get / update / remove / reorder`，以及主题级
+`localtask topic remove`（删整个主题）与 `localtask topic remove-many`
+（批量删除，`--keys/--cwds/--all`；等待中需 `--force`），面板上对应「本地任务」页。
+纯本机协调、存本地文件（`~/.nx-kv/localtasks.json`），**不需登录后端**。
 
-配套 skill：
+配套 skill（三件套各管一角；远程清单仍归 nx-kv 主 skill）：
 
 ```bash
-nx-kv skill install kv-sessiontask     # 教 agent 在最后一步阻塞等用户喂任务
+nx-kv skill install kv-waittask   # 等待侧：agent 最后一步阻塞等用户喂任务
+nx-kv skill install kv-submit     # 提交侧：总结上下文、提炼需求，委托别的 agent
+nx-kv skill install kv-localget   # 领取侧：主动领取排给本目录的任务
 ```
 
 ## ⚠️ 定位一律按内容，不按 id
@@ -151,11 +157,13 @@ nx-kv todo get --ref "旧记录" --topic fr   # 或按主题收窄
 
 ```
 src/core/          零业务语义：kvapi(后端客户端) / config(本机配置) / errors / fstree
-src/modules/       功能域：system / auth / group / sessiontask / todo / bundled
+src/modules/       功能域：system / auth / group / localtask / todo / bundled
 src/runtime/       装配层：registry / spec / cli / api / server
 src/web/frontend/  React 壳
-assets/nx-kv/            内置 skill：KV 清单操作手册
-assets/kv-sessiontask/   内置 skill：对话内实时任务接力
+assets/nx-kv/            内置 skill：KV 清单操作手册（远程）
+assets/kv-waittask/         内置 skill：对话内本地任务接力（等待侧）
+assets/kv-submit/        内置 skill：需求提炼与委托提交（提交侧）
+assets/kv-localget/         内置 skill：领取本目录本地任务（领取侧）
 ```
 
 分层由 `eslint.config.js` 的 `no-restricted-imports` 强制；
@@ -164,8 +172,10 @@ assets/kv-sessiontask/   内置 skill：对话内实时任务接力
 ## 给 agent 用
 
 ```bash
-nx-kv skill install      # 装到 ~/.claude/skills/nx-kv（KV 清单操作手册）
-nx-kv skill install kv-sessiontask   # 实时任务接力：最后一步阻塞等用户喂任务
+nx-kv skill install      # 装到 ~/.claude/skills/nx-kv（KV 清单操作手册，远程）
+nx-kv skill install kv-waittask      # 本地任务接力：最后一步阻塞等用户喂任务
+nx-kv skill install kv-submit     # 提交侧：总结上下文、提炼需求，委托别的 agent
+nx-kv skill install kv-localget      # 领取侧：主动领取排给本目录的任务
 nx-kv skill list         # 列出可装 skill、默认安装项与可装 group
 nx-kv skill groups       # 列出 group → 包含哪些 skill
 nx-kv skill install --group=<key>    # 一键装整组（与 <name> 二选一）
@@ -173,7 +183,8 @@ nx-kv skill get [name] [ref]         # 输出 skill 全文，外部 agent 一键
 ```
 
 装好后 agent 就能按 skill 里的 SOP 领任务、读主题上下文、完成后回填结果；
-或在一个对话里靠 `sessiontask wait` 阻塞弹窗、连续接收用户任务。
+或在一个对话里靠 `localtask wait` 阻塞弹窗、连续接收用户任务，
+把需求提炼成任务 `add` 到别的目录委托其它 agent，或主动领取排给本目录的任务。
 
 ## License
 

package/assets/groups.json

@@ -4,11 +4,19 @@
   "groups": {
     "nx-kv": {
       "skills": ["nx-kv"],
-      "summary": "KV 清单管理中枢主 skill（默认 install 装的就是这个）：todo / group / 工作空间"
+      "summary": "KV 清单管理中枢主 skill（默认 install 装的就是这个）：todo / group / 工作空间（远程，需登录）"
     },
-    "kv-sessiontask": {
-      "skills": ["kv-sessiontask"],
-      "summary": "本机实时人机接力（sessiontask）——agent 阻塞 wait，用户在网页回填"
+    "kv-waittask": {
+      "skills": ["kv-waittask"],
+      "summary": "对话内实时人机接力（等待侧）——agent 阻塞 wait，用户在网页回填"
+    },
+    "kv-submit": {
+      "skills": ["kv-submit"],
+      "summary": "总结上下文、提炼用户需求，提交到别的目录队列委托其它 agent（提交侧）"
+    },
+    "kv-localget": {
+      "skills": ["kv-localget"],
+      "summary": "领取排给本目录的本地任务 + 队列管理（领取侧）"
     }
   }
 }

package/assets/kv-localget/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: kv-localget
+description: 领取排给本工作目录的本地任务——别人通过 kv-submit 委托的、用户在面板/弹窗排队的，都落在「目录名即主题」的队列里；agent 在自己目录里用 nx-kv localtask list 查看待领取，用 wait（队列非空时立即返回、不阻塞）按序取走执行，附单条查看/编辑/删除/调序等队列管理。触发词：领取本地任务、看看有没有排给我的任务、本地队列、领取委托任务、拿任务、本目录的任务、排队任务、localtask list、kv-localget。凡「主动获取排给本目录的任务」的场景都走本 skill。反例：干完活等用户在浏览器回填下一条用 kv-waittask；把需求提交/委托给别的目录用 kv-submit；操作远程 KV 清单（todo）用 nx-kv。
+---
+# kv-localget — 领取本目录的本地任务（领取侧）
+
+任务队列按**工作目录**划分（目录名即主题）：kv-submit 委托的、用户在面板/弹窗
+排队的，都进各自目录的队列。你在哪个目录工作，就领哪个目录的队列——不传
+`--cwd` 时命令自动按进程当前目录定位。数据在本机文件（`~/.nx-kv/localtasks.json`），
+**不需登录**。
+
+## 领取流程
+
+```bash
+# 1. 看总览：找到自己目录的主题，看待领取数（pending）与现状
+nx-kv localtask list --json
+# → {topics:[{key,cwd,name,summary,waiting,pending,total,tasks:[...]}], waiting, settings}
+
+# 2. 有待领取 → 取走最早的一条（队列非空时 wait 立即返回，不开窗不阻塞）
+nx-kv localtask wait --summary "<本轮现状，如：空闲，领取新任务>" --timeout 30 --json
+# → {status:"ok", queued:true, task:{id,text,...}}
+
+# 3. 执行 task.text（内容永远读 task.text，id 只是编号），产出落在本目录
+```
+
+- `queued:true` = 从队列取到任务，直接执行。
+- `{status:"timeout"}`（exit 0，不是错误）= 时限内没有新任务：想继续等就再
+  wait（挂起等待，期间别人提交的会立刻送达），不想等就收工。
+- `--timeout <秒>`：阻塞上限（缺省用页面配置 180 秒，最大 600）；「查完就走」
+  用短超时，「挂着等活」用长超时。
+
+## 队列管理（需要时）
+
+```bash
+nx-kv localtask get    --id <n>                        # 查看单条
+nx-kv localtask update --id <n> --text "<新内容>"       # 改写任务内容
+nx-kv localtask remove --id <n>                        # 删除单条
+nx-kv localtask reorder --id <n> --before-id <m>       # 调整领取顺序（或 --after-id）
+nx-kv localtask topic remove --cwd "<目录>"             # 删除整个主题（等待中需 --force）
+```
+
+以上都不传 `--cwd` 时同样按进程当前目录定位。
+
+## 硬规则
+
+1. **内容读 `task.text`**，`task.id` 只是编号；领取顺序 = 队列里待领取任务的
+   先后（可用 reorder 校正）。
+2. **同一目录同一时刻只挂一个 wait**——两个 wait 抢同一队列，只有一个拿得到。
+3. **timeout 是业务结果**（exit 0）：按「暂时没活」处理，不要当错误重试。
+4. **确认目录对不对**：`list` 里自己主题的 `cwd` 与你工作的目录一致才领取；
+   跨目录代领需显式 `--cwd "<目标目录>"`（目录名相同即同一队列）。
+
+## 什么时候不用
+
+| 场景                                                     | 用哪个      |
+| -------------------------------------------------------- | ----------- |
+| 你干完活、**等用户在浏览器回填**下一条（人机接力） | kv-waittask |
+| 把这个对话的需求**提交/委托**给别的目录的 agent    | kv-submit   |
+| 操作远程 KV 后端的 todo 清单（需登录、按 groupId 隔离）  | nx-kv       |
+
+wait / kv-localget 共用同一个队列与同一条取数命令（`wait`）：区别只在意图——
+kv-waittask 把 wait 当「本轮最后一步等人接力」，kv-localget 把 wait 当「领活」。
+
+## 安装
+
+```bash
+nx-kv skill install kv-localget          # 装到 ~/.claude/skills/kv-localget
+nx-kv skill list                       # 列出 nx-kv / kv-waittask / kv-submit / kv-localget
+```

package/assets/kv-submit/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: kv-submit
+description: 把当前对话里的需求打包成任务，通过 nx-kv localtask add 提交到另一个工作目录的队列，委托在那里的 agent 完成——先总结上下文（聊了什么、定了什么、涉及哪些文件）、再提炼出用户的真实需求（目标、约束、验收标准），写成不依赖本对话就能执行的自包含任务文本再提交；可给正在等待的 agent 实时补任务，也可给不在等待的目录排队。触发词：提交任务、委托、派任务、丢给另一个 agent、交给那边做、转发需求、整理成任务提交、总结上下文提交、提炼需求、localtask add、kv-submit。凡「把这个对话里的东西变成任务交给别的 agent」的场景都走本 skill。反例：你自己在等用户回填用 kv-waittask；主动领取排给本目录的任务用 kv-localget；操作远程 KV 清单（todo）用 nx-kv。
+---
+
+# kv-submit — 提炼需求，委托其它 agent（提交侧）
+
+把「这个对话里的上下文 + 用户需求」变成一条**自包含**的任务，投进目标工作目录
+的任务队列。在那边工作的 agent（正在 wait 的立刻收到；不在等的下次领取）接手
+执行。**你发的是任务，不是对话记录**——接收方看不到你的对话，任务文本必须
+自己站得住。
+
+## 三步走（核心流程）
+
+1. **总结上下文**：当前对话聊了什么、做了哪些决策、涉及哪些文件/路径/约定。
+   只挑与需求相关的，不搬流水账。
+2. **提炼用户需求**：把用户散落的表述收敛成一句明确的目标 + 验收标准；
+   有歧义的先向用户确认，不要把猜测提交出去。
+3. **打包提交**：写成自包含任务文本（模板见 [[submit-workflow]]），投给目标目录：
+
+```bash
+# 提交到目标目录的队列（务必加 --json；--cwd 是接收方 agent 的工作目录）
+nx-kv localtask add "<任务文本>" --cwd "<目标工作目录>" --json
+
+# 可选：顺带刷新该目录主题的现状展示（面板/弹窗顶部那句话）
+nx-kv localtask add "<任务文本>" --cwd "<目标目录>" --summary "<该目录当前现状>" --json
+```
+
+返回 `{status:"ok", task:{id,text,...}, queued|delivered}`：
+
+- `queued:true`（跨进程提交的常态）→ 已入队；目标目录里正在 wait 的 agent
+  会在约 0.5 秒内取走，没人等就排在队列里等它下次领取。
+- 记下 `task.id`，向用户报告「已提交到哪个目录、第几号任务」。
+
+## 任务文本怎么写（一句话版）
+
+接收方没有你的上下文，任务文本按这个顺序组织成一段（单行，用 ①②③ 编号，
+总长 ≤20000 字）：
+
+> 目标：做什么、做到什么程度算完成。
+> 背景：相关文件/目录路径、已确定的技术决策、必须遵守的约束。
+> 注意：不要做什么、有哪些坑（如果有的话）。
+
+细节模板、多任务拆分、提交后的跟踪，读 [[submit-workflow]]。
+
+## 硬规则
+
+1. **`--cwd` 必须填接收方 agent 实际所在的目录**（目录名即主题；同名目录共用
+   队列）。填错了任务就排到了没人看的队列——不确定就先问用户。
+2. **任务文本自包含**：不写「如上所述」「刚才那个」，不引用本对话；路径写全。
+3. **提交前把提炼结果给用户过目**（尤其需求是提炼出来的而非用户原话时），
+   确认后再 `add`。
+4. **大需求拆成多条按序提交**，每条一个可独立完成的单元；顺序重要时提交后用
+   `localtask reorder` 校正优先级。
+
+## 什么时候不用
+
+| 场景 | 用哪个 |
+| --- | --- |
+| 你自己干完活、等用户在浏览器回填下一条 | kv-waittask（wait） |
+| 主动领取排给**本目录**的任务 | kv-localget |
+| 操作远程 KV 后端的 todo 清单（需登录） | nx-kv |
+| 给**正在等待**的 agent 补一条任务 | 本 skill（add 到它的目录） |
+
+## 与其它 skill 的分工
+
+三者共享同一份本机任务存储与按目录划分的队列（`~/.nx-kv/localtasks.json`）：
+
+- **kv-submit（本 skill）**：提交侧——总结上下文、提炼需求、投递到别的目录。
+- **kv-waittask**：等待侧——目标目录的 agent 用 wait 阻塞接任务（人机接力）。
+- **kv-localget**：领取侧——目标目录的 agent 主动领队列里的任务。
+- **nx-kv**：远程 KV 后端的 todo 清单（需登录、按 groupId 隔离），与本机队列无关。
+
+## 安装
+
+```bash
+nx-kv skill install kv-submit         # 装到 ~/.claude/skills/kv-submit
+nx-kv skill list                       # 列出 nx-kv / kv-waittask / kv-submit / kv-localget
+```

package/assets/kv-submit/references/submit-workflow.md

@@ -0,0 +1,105 @@
+# submit-workflow — 需求提炼与委托提交的完整 SOP
+
+> 归属 [[kv-submit]]。当你要把当前对话里的需求委托给别的 agent 时，按本 SOP 走。
+
+## 一、什么时候提交 / 委托
+
+| 信号 | 动作 |
+| --- | --- |
+| 用户明说「交给 xxx 那边的 agent」「让另一个项目去做」 | 提交到那个项目的目录 |
+| 用户给的需求属于另一个项目/目录的职责范围，且那边有 agent 在工作 | 先向用户确认目标目录，再提交 |
+| 用户想给一个**正在等待**的 agent 追加/更正任务 | add 到它的目录（正在 wait 的约 0.5 秒内取走） |
+| 目标目录暂时没人，但用户想先把任务存上 | 照常提交——任务排队，等那边的 agent 下次领取 |
+
+不要在目标不明时猜目录：`--cwd` 错了任务就沉进没人看的队列。**不确定就问。**
+
+## 二、三步提炼法
+
+### 1. 总结上下文（挑相关的）
+
+从当前对话里摘出与需求直接相关的：
+
+- 已做的决策（「用方案 B」「不改现有 API」）；
+- 涉及的文件/目录/服务的**完整路径**；
+- 相关约定（分支名、命名规则、兼容性要求）。
+
+流水账、被否决的方案、与本需求无关的支线——都不要带。
+
+### 2. 提炼用户需求（收敛成一句目标）
+
+把用户分散的、口语化的表述收敛成：
+
+- **一句目标**：「做什么、为什么」；
+- **验收标准**：做到什么程度算完成（可观察、可检查）；
+- **显式边界**：不要做什么。
+
+有歧义（比如「优化一下」没说优化什么指标）→ 先向用户确认，**不要把猜测提交
+出去**。提交前把提炼结果给用户过目。
+
+### 3. 打包成自包含任务文本
+
+模板（单行，①②③ 编号；总长 ≤20000 字）：
+
+```
+①目标：<做什么，做到什么程度算完成> ②背景：<相关路径（写全）、已定决策、约束>
+③注意：<不要做什么、已知坑（没有就省略）>
+```
+
+示例：
+
+```
+①目标：把 src/api/auth.js 的登录超时从 30s 改为 120s，并补对应单测，跑通全量测试
+②背景：仓库在 D:\code\a_js\proj\demo；超时逻辑集中在 auth.js 的 TIMEOUT 常量；
+测试用 pnpm test；不要动 token 刷新逻辑（上周刚重构过）
+③注意：Windows 换行，改完别动文件结尾的 BOM
+```
+
+**为什么必须自包含**：接收方看不到你的对话。「如上所述」「刚才说的那个文件」
+到它那里都是空引用。
+
+## 三、提交命令与返回
+
+```bash
+nx-kv localtask add "<任务文本>" --cwd "<目标工作目录>" --json
+```
+
+- `--cwd`：接收方 agent 的**工作目录**（主题按目录名识别，Windows 折叠大小写；
+  同名目录共用队列）。
+- `--summary "<现状>"`：可选，顺带刷新该主题在面板/弹窗顶部展示的现状。
+- 文本含空格必须加引号；跨执行边界传长文本时优先保持**单行**（多行参数可能
+  被平台切掉后半截），用 ①②③ 编号替代换行。
+
+成功返回 `{status:"ok", key, cwd, name, summary, task:{id,text,status:"pending",createdAt}, delivered, queued}`：
+
+| 字段 | 含义 |
+| --- | --- |
+| `task.id` | 任务编号（该队列内自增），向用户报告用它 |
+| `queued:true` | 已入队（跨进程提交的常态）；那边正在 wait 的 agent 约 0.5 秒内取走 |
+| `delivered:true` | 提交进程内正好有 wait 在等、当场送达（罕见） |
+
+文本非法（空、超 20000 字）或目录非法 → 报错 exit 1，按错误处理并修正后重试。
+
+## 四、提交后：拆分、排序、跟踪
+
+- **大需求拆多条**：每条一个可独立完成的单元，按执行顺序逐条提交（同一队列
+  按提交先后领取）；发现顺序不对用
+  `nx-kv localtask reorder --id <n> --before-id <m> --cwd "<目录>"` 校正。
+- **查状态**：`nx-kv localtask list`（全部主题总览）或
+  `nx-kv localtask get --id <n> --cwd "<目录>"`（单条；`status` 从 pending →
+  consumed 即已被领取）。
+- **改/撤**：`update --id <n> --text "<新内容>"` 改写；`remove --id <n>` 撤回。
+- **完成怎么知道**：本机队列是单向投递，不回传执行结果——接收方完成后的产出
+  在它的目录/对话里，由用户或那边的 agent 汇报。不要轮询本队列等「完成」状态，
+  它没有这个状态。
+
+## 五、常见错误与避坑
+
+| 错误做法 | 后果 | 正确做法 |
+| --- | --- | --- |
+| `--cwd` 随手填或省略 | 任务排进错误/没人看的队列；省略时提交进**你自己的**目录 | 填接收方 agent 实际工作的目录；不确定先问 |
+| 任务文本引用本对话（「如上所述」） | 接收方无从执行 | 自包含：目标/背景/注意写全，路径写全 |
+| 把没和用户对齐的猜测提交出去 | 那边的 agent 按错误需求白干一轮 | 先确认再提交；提交前给用户过目 |
+| 多行长文本直接塞 argv | 跨执行边界可能被切掉后半截（静默丢内容） | 单行 + ①②③ 编号；确要换行用引号包裹并提交后 `get` 核对 |
+| 一条任务塞一整个项目 | 接收方要么做偏要么摆烂 | 拆成多条可独立完成的单元 |
+| 提交后反复轮询队列等「完成」 | 队列没有完成状态，永远等不到 | 产出由用户/接收方汇报；本侧只管投递与查领取状态 |
+| 没加 --json | 人读文本难解析 | agent 调用一律加 --json |

package/assets/kv-waittask/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: kv-waittask
+description: 在一个对话里通过工具调用实时接收任务（本机人机接力），替代在原始输入框打字——agent 完成当前任务、提交结果后，把 nx-kv localtask wait --summary "<当前现状总结>" 作为本轮最后一步强制调用；命令阻塞并自动打开浏览器弹窗，用户在面板看清现状、针对该现状回填后解除阻塞、把新任务作为工具结果返回，agent 继续；队列按工作目录划分，同目录的任务（含别人委托排队的）按序领取；超时未回填则收尾结束本轮。触发词：本地任务、下一条任务、继续给任务、连续提交任务、补充任务、回填任务、现状总结、在网页/弹窗里给任务、阻塞等待、挂起等用户、人机接力、等用户喂任务、localtask wait、localtask（旧称 sessiontask）、kv-waittask。凡是「agent 不结束本轮、靠一个阻塞工具调用等浏览器里继续喂任务」的场景，都走本 skill。反例：要「主动领取排给本目录的委托任务」用 kv-localget；要「把需求打包提交给别的 agent」用 kv-submit；要操作远程 KV 清单（todo）用 nx-kv。
+---
+
+# kv-waittask — 对话内本地任务接力（等待侧）
+
+本质是一个循环：**agent 提交结果 → CLI 阻塞 → 用户在 web 看清现状、回填新任务 →
+agent 接收并继续**。在一个对话里连续接收任务，不靠原始输入框。
+
+agent 完成当前任务、需要下一条输入时，调用一个**阻塞式**工具
+`nx-kv localtask wait`，并带上一句**当前现状总结**；它自动打开浏览器弹窗。
+用户在面板/弹窗一眼看到现状，针对该现状回填，阻塞解除、新任务作为工具结果返回，
+agent 接着干。如此循环。别人通过 kv-submit / 面板 / CLI 排进**本目录队列**的任务，
+wait 也会按序取走。
+
+> 纯本机协调：弹窗由 wait 进程临时起的 http 服务器直出，数据存本机文件
+> （`~/.nx-kv/localtasks.json`），**不需要登录 KV 后端**。
+
+## 四条硬规则（最重要）
+
+1. **wait 必须是本轮最后一个动作。** 把它安排在所有分析与工具调用之后（阶段
+   结果已经通过正常输出提交）；调用之后不要再安排任何别的工具、输出或推理——
+   它会阻塞，直到拿到新任务或超时。
+2. **这次工具调用的超时设为 `300000` ms（5 分钟）。** CLI 默认阻塞 180 秒、
+   上限 600 秒；5 分钟覆盖默认值并留余量。若显式传了更长的 `--timeout`，
+   工具超时要同步放大到比它更大。
+3. **wait 必须带 `--summary "<当前现状总结>"`。** 总结写**当前做到哪、卡在哪、
+   等用户决定什么**，让用户不读对话也能在面板快速了解现状；它展示在弹窗/面板
+   顶部，并作为「本轮完成总结」记录在被取走的任务上。它**只是状态展示**——
+   措辞不影响领取顺序，不必刻意保持逐字一致。
+4. **返回 `status:"timeout"` 时直接收尾。** 用户在阻塞时限内没回填，就不要再
+   追问、不要再次调用 wait，把当前结论交代清楚、结束本轮即可。
+
+## 队列模型（一句话版）
+
+**工作目录即主题，主题拥有一个任务队列。** wait 不传 `--cwd` 时以进程当前目录
+（目录名）定位主题；同一目录的所有任务共用一个队列，wait 总是取走其中**最早的
+待领取任务**。队列里有任务时 wait 立即返回（不开窗、不阻塞）；队列为空才开窗
+阻塞。不同目录 → 不同主题 → 互不串。
+
+## 核心命令
+
+```bash
+# 阻塞等待本目录的下一条任务（agent 本轮最后一步；务必加 --json）
+nx-kv localtask wait --summary "<当前现状总结>" --json
+```
+
+返回形状：
+
+| 返回 | 含义 | agent 怎么做 |
+| --- | --- | --- |
+| `{status:"ok", queued:true, task}` | 队列里已有**排队任务**（含 kv-submit 委托的） | 直接执行 task |
+| `{status:"ok", delivered:true, task}` | 用户在弹窗/面板**实时回填** | 执行 task |
+| `{status:"timeout", cwd, summary, timeoutMs}` | 阻塞时限内未收到回填 | 收尾、结束本轮 |
+
+成功结果里带 `cwd` 与 `summary`；`task` 形如
+`{id, text, status, createdAt, consumedAt, roundSummary}`，**任务内容在 `task.text`**。
+
+## 一次循环长什么样
+
+```
+agent：干活 → 提交阶段结果
+       → 最后一步：nx-kv localtask wait --summary "已完成登录，等待选择工作空间" --json
+         （队列空 → 阻塞，弹窗/面板顶部显示这句现状）
+用户：看清现状 → 回填「选择工作空间 A」→ 提交
+agent：工具结果拿到 task.text → 继续干活、提交结果
+       → 需要下一条再 wait……（循环）
+若阻塞时限内没回填：wait 返回 timeout → agent 结束本轮
+```
+
+## 弹窗与常驻面板
+
+- 弹窗顶部「当前现状」显示 wait 传入的现状总结；大输入框 **Enter 提交、
+  Shift+Enter 换行**；状态栏倒计时归零即本轮结束；下方是该主题的任务表
+  （待领取 / 已领取，可删除）。
+- 常驻面板（`nx-kv serve`）的「本地任务」页按主题展示所有目录的队列与现状，
+  可直接点选回填；正在阻塞的 wait 通过轮询（约每 0.5 秒）取走，不依赖弹窗本身。
+- 弹窗没自动打开时，终端输出里有本次地址（`http://127.0.0.1:<端口>/`），手动
+  打开即可；该窗口只在本次 wait 期间有效，wait 结束即关闭。
+
+## 配套命令（队列管理，agent 一般不直接用）
+
+```bash
+nx-kv localtask list                                   # 主题总览（各目录、现状、待领取数）
+nx-kv localtask add  "<回填内容>" --cwd "<目录>"        # 给某目录的队列排任务
+nx-kv localtask get   --id <n> [--cwd "<目录>"]         # 查看单条
+nx-kv localtask update --id <n> --text "<新内容>"       # 编辑任务内容
+nx-kv localtask remove --id <n> [--cwd "<目录>"]        # 删除单条任务
+nx-kv localtask reorder --id <n> --before-id <m>        # 调整待领取优先级（或 --after-id）
+nx-kv localtask topic remove --cwd "<工作目录>"          # 删除整个主题（等待中需 --force）
+nx-kv localtask topic remove-many --keys "<key,key>"    # 批量删除主题（或 --cwds / --all）
+```
+
+> 删除主题：面板「本地任务」页每张主题卡有「删除主题」，勾选后可「批量删除」。
+> 等待中的主题默认不删（避免让阻塞的 agent 干等），确认要删会二次提示并以
+> `--force` 强删、agent 随后超时收尾。
+
+## 先判断你要做哪件事
+
+| 你要做的事 | 用哪个 |
+| --- | --- |
+| 干完活，**等用户在浏览器里继续喂下一条** | 本 skill（wait） |
+| 主动**领取排给本目录的委托任务**（他人 / 其它 agent 提交的） | kv-localget |
+| 把当前对话的需求**打包提交给别的 agent** | kv-submit |
+| 操作远程 KV 后端上的清单（todo，需登录） | nx-kv |
+
+要完整时序、返回字段、排队语义与避坑清单，读 [[kv-waittask-workflow]]（按需加载，
+只是查命令不必读）。
+
+## 与其它 skill 的分工
+
+- **kv-waittask（本 skill）**：等待侧——阻塞等浏览器回填，人机接力的「等」。
+- **kv-localget**：领取侧——主动把排给本目录的任务领走执行，附队列管理。
+- **kv-submit**：提交侧——总结上下文、提炼用户需求，委托给别的目录的 agent。
+- **nx-kv**：远程 KV 后端的 todo 清单（需登录、按 groupId 隔离）。
+
+三者共享同一份本机任务存储与按目录划分的队列：kv-submit 提交的、面板回填的、
+CLI add 排队的，wait / kv-localget 都能取走。可与 nx-kv 同时安装，各管一段。
+
+## 安装
+
+```bash
+nx-kv skill install kv-waittask           # 装到 ~/.claude/skills/kv-waittask
+nx-kv skill list                        # 列出 nx-kv / kv-waittask / kv-submit / kv-localget
+```