nx-kv 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -2,6 +2,75 @@
 
 本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.8.1] - 2026-10-12
+
+### Added
+
+- **常驻面板空闲自释放（serve --auto-exit）**：面板（web）全关且无等待中的主题时，
+  serve 进程优雅退出，释放端口——避免后台留一个永远没人看的常驻进程。
+  - `nx-kv serve` 新增 `--auto-exit`（配 `--idle <秒>` 调宽限期，默认 120s）。开启后，
+    **面板页全部关闭、且没有任何等待中的主题**并持续超过宽限期时，进程优雅退出、释放端口；
+    下一次 `localtask wait` 需要时会自动重新拉起（冷启动 <1s）。**用户手动 `nx-kv serve`
+    默认不带该标志，面板不会自己跑掉**。
+  - 判定「面板是否还开着」用的是任意面板请求的最近时间（SSE 连接数会随切页归 0，
+    不能用），为此新增 `GET /api/ping`（纯本机快返回）并在面板壳层每 15s 打一次心跳，
+    任意页面停留都算「面板开着」。
+  - 两条硬性否决：**有等待中的主题**（agent 正阻塞等人，面板是唯一提醒源）与
+    **有活动 SSE 标签**时不释放；`waiting` 标志若已过 `waitingUntil` 截止时刻（wait
+    进程被强杀后的残留）不计入，避免残留标志让进程永不释放。
+  - 从未有面板客户端连过（无 GUI / 开页失败）时用更长的兜底上限（默认 600s），
+    避免与 wait 的「无标签就重开页」互相拉扯出 spawn 抖动。
+  - 新增 `src/modules/localtask/panel-guard.js`（纯判定 `shouldAutoExit` + 可注入
+    时钟/定时器的看门狗 `startPanelIdleGuard`）与 `countWaitingTopics()`。
+
+- **主题卡「等待中」勋章显示等了多久，并可一键「关闭」这个等待**：
+  - 勋章文案由「等待中 m:ss（剩余）」升级为 **`等待中 已等 m:ss · 剩 m:ss`**：
+    新增 `waitingSince`（等待起点）落盘——只靠 `waitingUntil`（截止时刻）反推不出起点，
+    因为超时上限本身可被改写；旧记录缺该字段时自动退化为只显示剩余。
+  - 勋章内新增 **「关闭」按钮**：点确认后**只关等待**——阻塞中的 `wait` 立即收尾并返回
+    `{status:"timeout", cancelled:true}`（走与超时同一条出口，agent 侧不必认识新状态，
+    照常结束本轮），**不删主题、不删任务、不动队列**。
+  - 新增 action `localtask cancel`（CLI `nx-kv localtask cancel --cwd/--key`，
+    HTTP `POST /api/localtasks/cancel`）；对「不在等待中」的主题是无操作
+    （`{cancelled:false, reason:"not_waiting"}`），不报错。
+  - 关闭标记（`cancelRequested`）**只生效一次**：`setWaiting` 在每次等待开始时清掉残留，
+    避免「用户点关闭」与「上一轮 wait 收尾」撞车后误杀下一轮等待；wait 端每 0.5s 轮询取走，
+    另在等待登记完成后立即复查一次，不让用户白等半秒。
+
+## [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

package/README.md

@@ -66,29 +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）
+# 等待侧：每完成一步、提交结果后【必须】调 wait 领新任务（循环只有 timeout 才终止）
+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`，以及主题级
-`sessiontask topic remove`（删整个主题）与 `sessiontask topic remove-many`
-（批量删除，`--keys/--cwds/--all`；等待中需 `--force`），面板上对应「实时任务」页。
+现状总结只作展示（弹窗/面板顶部），不参与队列分桶；任务按各目录队列的先后
+领取。其余命令：`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
@@ -152,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` 强制；
@@ -165,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> 二选一）
@@ -174,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,81 @@
+---
+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. **总结上下文**：当前对话聊了什么、做了哪些决策、涉及哪些文件/路径/约定。
+   只挑与需求相关的，不搬流水账。会话很长、或要把会话保存下来交给其他
+   agent 时，先按 [[context-layering]] 分层组织（旧对话结构化摘要 + 最近
+   对话逐字保留），再挑。
+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/context-layering.md

@@ -0,0 +1,121 @@
+# context-layering — 长会话的分层上下文组织 SOP
+
+> 归属 [[kv-submit]]。会话已经拉得很长（几十上百轮、关键信息散落各处），
+> 要把会话保存下来交给其他 agent、或从中提炼需求时，先按本 SOP 组织上下文，
+> 再走 [[submit-workflow]] 提交。
+
+## 一、交接 = 换一个没有本会话记忆的读者
+
+kv-submit 的本质是**会话交接**：接收方看不到本对话，任务文本必须把上下文
+重新组织成它能独立使用的形态。这和 agent 延续自己的会话是同一个问题，
+答案也一样：**分层组织，不要单层平铺**。
+
+单层的两种翻车：
+
+- 全搬流水账 → 接收方抓不住重点，对话里独有的信息被淹没；
+- 只搬最近几轮 → 早期定下的决策/约束丢失，接收方做出早被否决的方案。
+
+分层的解法：
+
+```
+[旧对话 E1…E8][最近对话 E9 E10]  →  [结构化摘要层 S1] + [最近原文层 E9 E10]
+```
+
+- **摘要层**（旧对话）：按固定模板组织成结构化事实，保证记忆槽位不缺；
+- **原文层**（最近对话）：最近一两轮**逐字保留**——用户需求的原始措辞是
+  第一手证据，不经转述。
+
+两层各管一件事：摘要层保结构齐全，原文层保措辞保真。
+
+## 二、摘要层：七个固定槽位
+
+摘要不是自由发挥的笔记，是**固定槽位的结构化事实**——每个槽位回答一个
+交接必备的问题，缺一个槽位就缺一类记忆：
+
+| 槽位 | 回答的问题 |
+| --- | --- |
+| 目标 | 用户到底想完成什么（一两句） |
+| 需求与约束 | 用户明说过的约束、偏好、范围边界 |
+| 已定决策 | 定下来了什么、为什么 |
+| 工作状态 | 做到哪了：已完成 / 进行中 / 被阻塞 |
+| 下一步 | 接下来按什么顺序做什么 |
+| 相关文件 | 接手要打开哪些路径，写全路径 + 为什么相关（最多 15 条，最重要的在前） |
+| 关键上下文 | 什么事实缺了就干不了、对方又无法自行恢复 |
+
+组织规则：
+
+| 规则 | 做法 |
+| --- | --- |
+| 单行短句要点 | 不写段落、不嵌套列表 |
+| 引用代替复述 | 对方能从代码/文件恢复的信息不搬，列路径即可 |
+| 精确保留原文 | 路径、符号名、命令、报错字符串、URL、标识符一字不改 |
+| 只带未解决的 | 用户问题：已被解决的删掉；未解决的保留原话措辞 |
+| 带上工作流状态 | 未提交/已提交/已推送/在 review/已合并——决定对方从哪接手 |
+| 环境信息不搬 | 仓库通用约定、CLAUDE.md/AGENTS.md 内容对方自己有；**对话独有的决策与偏好必须搬** |
+| 输出只搬关键行 | 日志/命令输出摘关键结论，不整段贴 |
+| 已否决 ≠ 已决策 | 被推翻的旧方案标注「已否决」或丢弃，不得混进「已定决策」 |
+| 文本自包含 | 不出现「如前所述」「上文提到」——交接文本里没有「上文」 |
+
+## 三、原文层：最近对话逐字保留
+
+- 最近 1-2 轮对话（用户消息 + 助手回复）原样保留，不进摘要层；
+- 用户最后几条消息的**原话**最重要——需求的第一手证据。进一次摘要是一次
+  转述，组装进任务文本又是一次转述，两层转述就跑偏了；
+- 拿不准某句是决策还是闲聊，回对话原文核对，不靠记忆复述。
+
+## 四、交接层：两层组装成任务文本
+
+任务文本是交给接收方的**交接层**，从上面两层逐段组装（①目标②背景③注意，单行）：
+
+| 来源 | 去向 |
+| --- | --- |
+| 摘要层·目标 + 下一步 | ①目标 |
+| 摘要层·需求与约束 + 已定决策 + 相关文件 + 关键上下文 | ②背景 |
+| 摘要层·工作状态·已完成 | ②背景里写「已完成，不要重做」，或无必要则省略 |
+| 摘要层·工作状态·被阻塞 + 已否决方案 | ③注意 |
+| 原文层·未回答的用户问题（原话） | ③注意，标注「用户尚未回答」 |
+
+逐段组装，不跳段——跳一段就是丢一块记忆。
+
+## 五、交接文本的提示词构建
+
+把两层组装成任务文本时，按四条要领构建——它们决定接收方拿到文本后
+能不能正确「接」：
+
+1. **开篇重定义任务**：第一句就让接收方明白这是**接手**，不是新开工。
+   ①目标开头交代已有进度（「继续/接手…，已完成 X」），防止它从零重做。
+2. **固定槽位 = 输出契约**：七槽位就是契约，缺一个槽位就是缺一类记忆。
+   组装完对照第七节清单逐段核对，缺了就补，不带侥幸提交。
+3. **消费侧说明**：明写接收方该怎么用这份交接——「已完成 X，不要重做」；
+   未答问题标「用户尚未回答」；带原文引用的地方是第一手证据，可放心依据。
+4. **禁区前置**：③注意先写「不要做什么」，再写坑——禁令比描述更防跑偏。
+
+## 六、会话继续增长后再组织
+
+交接不是一次性的：给同一个目标分多轮补任务、或会话又聊了一段需要重新
+组织时，按同一套架构迭代：
+
+- **新事实永远优先于旧摘要**：旧信息保留，除非新对话明确推翻、取代或解决了它；
+- 重新对工作状态：完成的从「进行中」移出；已解决的阻塞、已回答的问题删掉；未解决的继续保留；
+- 已不再服务于「接着干」的信息可以删——组织为续做服务，不为存档服务。
+
+## 七、交接前校验清单
+
+- [ ] 路径全部是全路径且真实存在
+- [ ] 报错/命令/符号名与对话原文逐字一致
+- [ ] 「已定决策」里没有混入被否决方案
+- [ ] 用户未回答的问题原话保留并标注
+- [ ] 工作流状态（提交/推送与否）写清了
+- [ ] 「如上所述」「刚才那个」零出现
+- [ ] 给用户过目后再 `localtask add`
+
+## 八、常见错误
+
+| 错误 | 后果 | 正确做法 |
+| --- | --- | --- |
+| 会话很长还直接提炼，不分层 | 早期决策/约束静默丢失 | 先分两层（摘要 + 原文），再组装任务文本 |
+| 摘要层写成流水账 | 任务文本超长，接收方抓不住重点 | 七个固定槽位 + 单行要点，无关支线不搬 |
+| 报错/路径凭记忆转述 | 对方按错误信息排查半天 | 精确保留原文，拿不准回对话核对 |
+| 用户原话被两轮转述 | 需求失真，做出来的不是要的 | 最近对话逐字保留，未答问题带原话 |
+| 已否决方案混进背景 | 对方做出被否决的方案 | 已否决的进 ③注意 或丢弃 |
+| AGENTS.md/通用约定大段搬进任务 | 文本膨胀，独有信息被稀释 | 只搬对话独有的决策、偏好、事实 |

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

@@ -0,0 +1,109 @@
+# submit-workflow — 需求提炼与委托提交的完整 SOP
+
+> 归属 [[kv-submit]]。当你要把当前对话里的需求委托给别的 agent 时，按本 SOP 走。
+
+## 一、什么时候提交 / 委托
+
+| 信号 | 动作 |
+| --- | --- |
+| 用户明说「交给 xxx 那边的 agent」「让另一个项目去做」 | 提交到那个项目的目录 |
+| 用户给的需求属于另一个项目/目录的职责范围，且那边有 agent 在工作 | 先向用户确认目标目录，再提交 |
+| 用户想给一个**正在等待**的 agent 追加/更正任务 | add 到它的目录（正在 wait 的约 0.5 秒内取走） |
+| 目标目录暂时没人，但用户想先把任务存上 | 照常提交——任务排队，等那边的 agent 下次领取 |
+
+不要在目标不明时猜目录：`--cwd` 错了任务就沉进没人看的队列。**不确定就问。**
+
+## 二、三步提炼法
+
+### 1. 总结上下文（挑相关的）
+
+从当前对话里摘出与需求直接相关的：
+
+- 已做的决策（「用方案 B」「不改现有 API」）；
+- 涉及的文件/目录/服务的**完整路径**；
+- 相关约定（分支名、命名规则、兼容性要求）。
+
+流水账、被否决的方案、与本需求无关的支线——都不要带。
+
+会话已经很长（几十上百轮）、或要把会话保存下来交给其他 agent 时，直接挑
+容易丢早期决策——先按 [[context-layering]] 分层组织（旧对话结构化摘要 +
+最近对话逐字保留），再提炼。
+
+### 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 |