nx-kv 0.8.4 → 0.8.5

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.8.5] - 2026-10-13
+
+### Added
+
+- **本地任务新增「全局任务池」（跨目录共享队列 + 工作窃取）**，参考 Go 调度器的
+  local runq + global runq 两层模型：
+  - `wait` 的领取顺序变为：本目录队列 → **全局任务池** → 阻塞。本地取不到时自动
+    去全局领，全局也没有才阻塞；**显式传 `--cwd` 不会关闭全局兜底**（防止调用方
+    习惯性传 cwd 导致池子无人领取）。返回新增 `source: "local" | "global"` 标明
+    任务来源，旧字段全部保留。
+  - 发布进池子：`localtask add --global "<任务文本>"`（CLI/HTTP 同名 flag；
+    `--global` 时 `--cwd` 被忽略）。不限定接收方、谁闲谁领的任务走这里。
+  - 多个 agent 同时阻塞时，全局任务按阻塞先后（FIFO）实时投递给最早等待的；
+    跨进程由既有 0.5s 轮询兜底，同样本地优先、全局其次。
+  - 全局主题在 `localtask list` 与面板「本地任务」页永远置顶（名称「全局任务」，
+    key 固定 `__GLOBAL__`，卡片带「全局」徽章）；面板回填表单新增「全局」勾选，
+    选中全局主题卡片时只能推全局。
+  - 全局主题默认受保护：`topic remove --key __GLOBAL__` 需 `--force`、
+    `topic remove-many` 将其计入 `skipped`（reason `protected`）、`prune` 永不清理；
+    它不是等待源——`cancel` 返回 `global_not_waitable`、永不计入等待数。
+  - 任务级 `get/update/remove/reorder` 新增 `--key` 寻址（与 `--cwd` 二选一），
+    全局主题没有 cwd、只能按 key 管理。
+
+### Fixed
+
+- **落盘并发安全**：`saveStore` 进程内串行化（链式队列）——此前同进程两个写操作
+  重叠时共用同一个 `.tmp` 中转文件，先完成的 rename 会把 tmp 消耗掉、后一个
+  rename 直接 ENOENT 崩溃（全局唤醒与等待复位并发时必现）；rename 另加 Windows
+  EPERM/EACCES 小退避重试（目标文件被并发读者/杀软短暂锁住的瞬态失败）。
+
 ## [0.8.4] - 2026-10-12
 
 ### Added

package/assets/kv-submit/SKILL.md

@@ -26,13 +26,18 @@ nx-kv localtask add "<任务文本>" --cwd "<目标工作目录>" --json
 
 # 可选：顺带刷新该目录主题的现状展示（面板/弹窗顶部那句话）
 nx-kv localtask add "<任务文本>" --cwd "<目标目录>" --summary "<该目录当前现状>" --json
+
+# 不限定接收方、谁闲谁领 → 推到全局任务池（--cwd 被忽略）：
+# 任何目录的 agent 在本地队列空时都会自动领取（返回 source:"global"）
+nx-kv localtask add --global "<任务文本>" --json
 ```
 
 返回 `{status:"ok", task:{id,text,...}, queued|delivered}`：
 
 - `queued:true`（跨进程提交的常态）→ 已入队；目标目录里正在 wait 的 agent
-  会在约 0.5 秒内取走，没人等就排在队列里等它下次领取。
-- 记下 `task.id`，向用户报告「已提交到哪个目录、第几号任务」。
+  会在约 0.5 秒内取走，没人等就排在队列里等它下次领取。`--global` 提交则排在
+  全局任务池，任何目录空闲的 agent 自动领取。
+- 记下 `task.id`，向用户报告「已提交到哪个目录（或全局池）、第几号任务」。
 
 ## 任务文本怎么写（一句话版）
 
@@ -48,12 +53,14 @@ nx-kv localtask add "<任务文本>" --cwd "<目标目录>" --summary "<该目
 ## 硬规则
 
 1. **`--cwd` 必须填接收方 agent 实际所在的目录**（目录名即主题；同名目录共用
-   队列）。填错了任务就排到了没人看的队列——不确定就先问用户。
+   队列）。填错了任务就排到了没人看的队列——不确定就先问用户。**不限定接收方**
+   的通用任务才走 `--global`（无需 cwd）。
 2. **任务文本自包含**：不写「如上所述」「刚才那个」，不引用本对话；路径写全。
 3. **提交前把提炼结果给用户过目**（尤其需求是提炼出来的而非用户原话时），
    确认后再 `add`。
 4. **大需求拆成多条按序提交**，每条一个可独立完成的单元；顺序重要时提交后用
-   `localtask reorder` 校正优先级。
+   `localtask reorder` 校正优先级。**全局池不保顺序**——「先做 A 再做 B」这类
+   有依赖的步骤必须 `--cwd` 指名提交到同一目录队列，不要进池子。
 
 ## 什么时候不用
 
@@ -63,6 +70,7 @@ nx-kv localtask add "<任务文本>" --cwd "<目标目录>" --summary "<该目
 | 主动领取排给**本目录**的任务 | kv-localget |
 | 操作远程 KV 后端的 todo 清单（需登录） | nx-kv |
 | 给**正在等待**的 agent 补一条任务 | 本 skill（add 到它的目录） |
+| 不限定接收方、让任何空闲 agent 自取 | 本 skill（`add --global` 推全局任务池） |
 
 ## 与其它 skill 的分工
 

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

@@ -64,11 +64,18 @@
 ## 三、提交命令与返回
 
 ```bash
+# 指名提交：投进目标目录的队列（常态；务必加 --json）
 nx-kv localtask add "<任务文本>" --cwd "<目标工作目录>" --json
+
+# 全局投递：不限定接收方，谁闲谁领（--cwd 被忽略）
+nx-kv localtask add --global "<任务文本>" --json
 ```
 
 - `--cwd`：接收方 agent 的**工作目录**（主题按目录名识别，Windows 折叠大小写；
   同名目录共用队列）。
+- `--global`：推到**全局任务池**——任何目录的 agent 在本地队列空时自动领取
+  （返回 `key` 为 `__GLOBAL__`）。适合不依赖顺序、不挑执行者的通用任务；有依赖
+  顺序或只能某人做的任务必须 `--cwd` 指名提交。
 - `--summary "<现状>"`：可选，顺带刷新该主题在面板/弹窗顶部展示的现状。
 - 文本含空格必须加引号；跨执行边界传长文本时优先保持**单行**（多行参数可能
   被平台切掉后半截），用 ①②③ 编号替代换行。
@@ -78,7 +85,7 @@ nx-kv localtask add "<任务文本>" --cwd "<目标工作目录>" --json
 | 字段 | 含义 |
 | --- | --- |
 | `task.id` | 任务编号（该队列内自增），向用户报告用它 |
-| `queued:true` | 已入队（跨进程提交的常态）；那边正在 wait 的 agent 约 0.5 秒内取走 |
+| `queued:true` | 已入队（跨进程提交的常态）；那边正在 wait 的 agent 约 0.5 秒内取走（全局投递则由任何空闲 agent 领取） |
 | `delivered:true` | 提交进程内正好有 wait 在等、当场送达（罕见） |
 
 文本非法（空、超 20000 字）或目录非法 → 报错 exit 1，按错误处理并修正后重试。
@@ -100,7 +107,7 @@ nx-kv localtask add "<任务文本>" --cwd "<目标工作目录>" --json
 
 | 错误做法 | 后果 | 正确做法 |
 | --- | --- | --- |
-| `--cwd` 随手填或省略 | 任务排进错误/没人看的队列；省略时提交进**你自己的**目录 | 填接收方 agent 实际工作的目录；不确定先问 |
+| `--cwd` 随手填或省略（且没用 --global） | 任务排进错误/没人看的队列；省略时提交进**你自己的**目录 | 填接收方 agent 实际工作的目录；不确定先问 |
 | 任务文本引用本对话（「如上所述」） | 接收方无从执行 | 自包含：目标/背景/注意写全，路径写全 |
 | 把没和用户对齐的猜测提交出去 | 那边的 agent 按错误需求白干一轮 | 先确认再提交；提交前给用户过目 |
 | 多行长文本直接塞 argv | 跨执行边界可能被切掉后半截（静默丢内容） | 单行 + ①②③ 编号；确要换行用引号包裹并提交后 `get` 核对 |

package/assets/kv-waittask/SKILL.md

@@ -43,6 +43,27 @@ agent 接着干；做完再 wait——如此循环。别人通过 kv-submit /
 待领取任务**。队列里有任务时 wait 立即返回（不开窗、不阻塞）；队列为空才开窗
 阻塞。不同目录 → 不同主题 → 互不串。
 
+**本地空了一定去全局池领（内建兜底，没有开关）。** 即便显式传了 `--cwd`，本地
+队列取不到任务时，wait 也会自动去「全局任务池」（跨目录共享队列）领一条；全局
+也没有才阻塞。不要假设「传了 cwd 就只看本地」——习惯性传 cwd 不影响全局任务被
+领取；同样，别往全局池放"只能某人做"的任务，池子对一切空闲 agent 开放。
+
+## 全局任务池（工作窃取）
+
+除按目录划分的本地队列外，还有一个**跨目录共享**的全局主题：任何目录的 agent
+在本地队列空时自动领取池里的任务——类似 Go 调度器的 global runq：本地空就去
+全局拿，全局也空才 park 阻塞。
+
+- **发布**：`nx-kv localtask add --global "<任务文本>" --json`——不限定接收方、
+  谁闲谁领的任务走这里（`--global` 时 `--cwd` 被忽略）。
+- **领取**：无需任何 flag，wait 内建兜底；返回用 `source: "local" | "global"`
+  区分任务来自本目录队列还是全局池。agent 不必区分，照常执行 `task.text`。
+- **顺序**：本地优先、全局兜底——本目录有排队任务时不会去抢全局的。
+- **公平**：多个 agent 同时阻塞时，全局任务按阻塞先后（先到先得）投递。
+- **查看/管理**：`nx-kv localtask list` 中全局主题永远置顶（名称「全局任务」，
+  key 固定 `__GLOBAL__`）；默认受保护，`topic remove --key __GLOBAL__` 需 `--force`
+  才能清空。
+
 ## 核心命令
 
 ```bash
@@ -54,7 +75,8 @@ nx-kv localtask wait --summary "<当前现状总结>" --json
 
 | 返回 | 含义 | agent 怎么做 |
 | --- | --- | --- |
-| `{status:"ok", queued:true, task}` | 队列里已有**排队任务**（含 kv-submit 委托的） | 直接执行 task |
+| `{status:"ok", queued:true, source:"local", task}` | 本目录队列已有**排队任务**（含 kv-submit 委托的） | 直接执行 task |
+| `{status:"ok", queued:true, source:"global", task}` | 本地空，从**全局任务池**领到任务 | 直接执行 task |
 | `{status:"ok", delivered:true, task}` | 用户在弹窗/面板**实时回填** | 执行 task |
 | `{status:"timeout", cwd, summary, timeoutMs}` | 阻塞时限内未收到回填 | 收尾、结束本轮 |
 

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

@@ -79,11 +79,14 @@ wait 必带一句当前现状总结（≤2000 字，连续空白会折叠为单
             "createdAt": "2026-10-11 10:00:00", "consumedAt": "2026-10-11 10:00:04",
             "roundSummary": "已完成登录，等待选择工作空间" },
   "delivered": true,
-  "queued": false
+  "queued": false,
+  "source": "local"
 }
 ```
 
 - `delivered:true` = 实时回填；`queued:true` = 取到队列里排队的任务（二者互斥）。
+- `source` = 任务来自哪个队列：`"local"`（本目录队列，含实时回填）或 `"global"`
+  （全局任务池）；agent 不必区分，照常执行 `task.text`。
 - **任务内容永远读 `task.text`**，多行换行原样保留。
 
 超时（exit 0，业务结果而非错误）：
@@ -116,7 +119,26 @@ wait 必带一句当前现状总结（≤2000 字，连续空白会折叠为单
 - agent 在哪个目录跑 wait（或 `--cwd` 指哪个目录），就取哪个目录队列的任务，
   互不串。
 
-## 七、删除主题与批量删除
+## 七、全局任务池（跨目录共享，工作窃取）
+
+除本地队列外还有一个**跨所有目录共享**的「全局任务池」：任何目录的 agent 在
+本地队列空时自动领取池里的任务，全局也空才阻塞——类似 Go 调度器的 global runq
+（本地空 → 全局拿 → 都空才 park）。
+
+- **领取是无条件兜底**：显式传 `--cwd` 也不例外——本地取不到就一定去全局扫一眼。
+  不要假设「传了 cwd 就只看本地」。
+- **本地优先**：本目录有排队任务时 wait 先取本地的，不会去抢全局的。
+- **发布**：`nx-kv localtask add --global "<任务文本>" --json`（`--global` 时
+  `--cwd` 被忽略）。适合放不限定接收方、谁闲谁领的通用任务；「只能某人做」的
+  任务不要放池子，用 `--cwd` 指名提交。
+- **公平**：多个 agent 同时阻塞时，全局任务按阻塞先后（先到先得）投递。
+- **返回标记**：`source: "local" | "global"` 标明任务来自本目录队列还是全局池；
+  agent 不必区分，照常执行 `task.text`。
+- **管理**：`nx-kv localtask list` 中全局主题永远置顶（名称「全局任务」，key 固定
+  `__GLOBAL__`）；受保护——`topic remove --key __GLOBAL__` 默认拒绝，`--force`
+  才能清空；`topic remove-many --all` 默认跳过它。
+
+## 八、删除主题与批量删除
 
 主题（工作目录）可整体删除，不必逐条删任务：
 
@@ -132,7 +154,7 @@ wait 必带一句当前现状总结（≤2000 字，连续空白会折叠为单
 - **返回**：单个 `{status:"removed",topic}`；批量 `{count,removed,skipped}`，
   skipped 列出被跳过的「等待中 / 不存在」主题。
 
-## 八、常见错误与避坑
+## 九、常见错误与避坑
 
 | 错误做法 | 后果 | 正确做法 |
 | --- | --- | --- |
@@ -147,7 +169,7 @@ wait 必带一句当前现状总结（≤2000 字，连续空白会折叠为单
 | 同时开多个 wait（同一目录主题） | 只有一个收到回填，另一个等到超时 | 同一目录同一时刻只调一个 wait |
 | 没用 --json | 输出人读文本，宿主难以可靠解析 | agent 调用一律加 `--json` |
 
-## 九、与常驻面板配合 / 排障
+## 十、与常驻面板配合 / 排障
 
 - 已 `nx-kv serve` 打开面板时，直接在「本地任务」页点选主题回填；正在阻塞的
   wait 通过轮询（约每 0.5 秒）取走，不依赖弹窗本身。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nx-kv",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "description": "nx-kv — KV 清单管理中枢（远程）+ 本机本地任务队列（localtask）：serve 驱动 CLI 与 Web 面板，同源同构，附带可安装 skill 供 agent 提交 / 领取 / 阻塞接收任务",
   "type": "module",
   "bin": {

package/src/modules/localtask/index.js

@@ -15,6 +15,8 @@ import * as service from './service.js';
 
 const CWD = { type: 'string', hint: '工作目录（作为主题；默认当前目录）' };
 const SUMMARY = { type: 'string', required: true, hint: '当前现状（agent 当前状态，展示给用户）' };
+// 任务级寻址的 key flag：全局主题没有 cwd，只能按 key 定位（__GLOBAL__）
+const KEY = { type: 'string', hint: '主题 key（与 --cwd 二选一；全局任务池固定 __GLOBAL__）' };
 
 const STATUS_TAG = { pending: '待领取', consumed: '已领取' };
 
@@ -26,7 +28,7 @@ function renderOverview(d) {
     return lines.join('\n');
   }
   for (const t of d.topics) {
-    const tag = t.waiting ? '[等待中]' : '[已结束]';
+    const tag = t.isGlobal ? '[全局池]' : t.waiting ? '[等待中]' : '[已结束]';
     const head = t.cwd ? `${t.name}  ${t.cwd}` : t.name;
     lines.push(`  ${tag} ${head}  · 待领取 ${t.pending}/${t.total}`);
     if (t.summary) lines.push(`        现状: ${t.summary}`);
@@ -44,40 +46,43 @@ const renderTask = (t) =>
     .join('\n');
 
 function renderAdd(d) {
+  const where = d.isGlobal ? '全局任务（共享池）' : `主题「${d.name}」`;
   const head = `#${d.task.id} [${d.task.status}] ${d.task.text}`;
   return d.delivered
-    ? `已实时回填给等待中的 agent（主题 ${d.name}）: ${head}`
-    : `已排入主题「${d.name}」队列（agent 下一次 wait 取走）: ${head}`;
+    ? `已实时投递给等待中的 agent（${where}）: ${head}`
+    : `已排入${where}队列（agent 下一次 wait 取走）: ${head}`;
 }
 
-// wait 的人读输出：成功给任务，超时明确提示「本轮结束」
+// wait 的人读输出：成功给任务（注明来自本地队列还是全局共享池），超时明确提示「本轮结束」
 function renderWait(r) {
   if (r.status === 'timeout') {
     const tail = r.cancelled ? '（用户在面板点了「关闭」）' : '';
     return `等待超时（${Math.round(r.timeoutMs / 1000)} 秒未回填）${tail}：主题「${r.cwd}」现状「${r.summary}」结束本轮。`;
   }
-  const origin = r.queued ? '排队任务' : '实时回填';
+  const origin =
+    (r.source === 'global' ? '全局任务池' : '本目录队列') + (r.queued ? '排队任务' : ' · 实时回填');
   return (
     `已取得下一条任务（${origin} · 主题「${r.cwd}」现状「${r.summary}」）: #${r.task.id}\n` +
     `  ${r.task.text.replace(/\n/g, '\n  ')}`
   );
 }
 
-// cancel 的人读输出：等待中→已关闭（主题与任务保留）；非等待中→无操作
+// cancel 的人读输出：等待中→已关闭（主题与任务保留）；非等待中→无操作；全局→不可关闭
 function renderCancel(d) {
   if (d.cancelled) return `已关闭主题「${d.name}」的等待：阻塞中的 wait 立即收尾，主题与任务保留。`;
+  if (d.reason === 'global_not_waitable') return '全局主题是共享任务池（不是等待源），无从关闭。';
   if (d.reason === 'not_waiting') return `主题「${d.name || d.key}」不在等待中，无需关闭。`;
   return '已关闭。';
 }
 
-// 批量删除的人读输出：删除清单 + 跳过清单（等待中/不存在）
+// 批量删除的人读输出：删除清单 + 跳过清单（等待中/受保护/不存在）
 function renderRemoveMany(d) {
   const lines = [d.all ? `清空：删除 ${d.count} 个主题` : `已删除 ${d.count} 个主题`];
   for (const r of d.removed) lines.push(`  - ${r.name}${r.cwd ? `  ${r.cwd}` : ''}`);
   if (d.skipped.length) {
     lines.push(`跳过 ${d.skipped.length} 个：`);
     for (const s of d.skipped) {
-      const why = s.reason === 'waiting' ? '等待中' : '不存在';
+      const why = s.reason === 'waiting' ? '等待中' : s.reason === 'protected' ? '全局共享池' : '不存在';
       lines.push(`  - [${why}] ${s.name || s.key}`);
     }
   }
@@ -108,41 +113,51 @@ export default {
       id: 'localtask.get',
       cli: ['localtask', 'get'],
       http: ['GET', '/api/localtasks/item'],
-      summary: '查看单条任务（按 --id，定位到 --cwd 主题）',
-      flags: { id: { type: 'number', required: true, hint: '任务编号' }, cwd: CWD },
-      run: (ctx) => service.getTask({ id: ctx.id, cwd: ctx.cwd }),
+      summary: '查看单条任务（按 --id，定位到 --cwd 主题或 --key）',
+      flags: { id: { type: 'number', required: true, hint: '任务编号' }, cwd: CWD, key: KEY },
+      run: (ctx) => service.getTask({ id: ctx.id, cwd: ctx.cwd, key: ctx.key }),
       render: renderTask,
     },
     {
       id: 'localtask.add',
       cli: ['localtask', 'add'],
       http: ['POST', '/api/localtasks'],
-      summary: '向某主题（工作目录）的队列回填一条任务（有 wait 在等则即时投递，否则排队）',
+      summary:
+        '向某主题（工作目录）的队列回填一条任务（有 wait 在等则即时投递，否则排队）；--global 推到全局共享池',
       args: ['text'],
-      flags: { cwd: CWD, summary: { type: 'string', hint: '顺带刷新该主题的当前现状（可选）' } },
-      run: (ctx) => service.addTask({ text: ctx.text, cwd: ctx.cwd, summary: ctx.summary }),
+      flags: {
+        cwd: CWD,
+        summary: { type: 'string', hint: '顺带刷新该主题的当前现状（可选）' },
+        global: {
+          type: 'boolean',
+          hint: '推到全局主题（共享池）：任何目录的 wait 在本地空时自动领取；--cwd 被忽略',
+        },
+      },
+      run: (ctx) =>
+        service.addTask({ text: ctx.text, cwd: ctx.cwd, summary: ctx.summary, global: ctx.global }),
       render: renderAdd,
     },
     {
       id: 'localtask.update',
       cli: ['localtask', 'update'],
       http: ['PATCH', '/api/localtasks/item'],
-      summary: '编辑任务内容（按 --id，定位到 --cwd 主题）',
+      summary: '编辑任务内容（按 --id，定位到 --cwd 主题或 --key）',
       flags: {
         id: { type: 'number', required: true, hint: '任务编号' },
         text: { type: 'string', required: true, hint: '改成这个内容' },
         cwd: CWD,
+        key: KEY,
       },
-      run: (ctx) => service.updateTask({ id: ctx.id, text: ctx.text, cwd: ctx.cwd }),
+      run: (ctx) => service.updateTask({ id: ctx.id, text: ctx.text, cwd: ctx.cwd, key: ctx.key }),
       render: (d) => `已更新主题「${d.name}」#${d.task.id}: ${d.task.text}`,
     },
     {
       id: 'localtask.remove',
       cli: ['localtask', 'remove'],
       http: ['DELETE', '/api/localtasks/item'],
-      summary: '删除一条任务（按 --id，定位到 --cwd 主题）',
-      flags: { id: { type: 'number', required: true, hint: '任务编号' }, cwd: CWD },
-      run: (ctx) => service.removeTask({ id: ctx.id, cwd: ctx.cwd }),
+      summary: '删除一条任务（按 --id，定位到 --cwd 主题或 --key）',
+      flags: { id: { type: 'number', required: true, hint: '任务编号' }, cwd: CWD, key: KEY },
+      run: (ctx) => service.removeTask({ id: ctx.id, cwd: ctx.cwd, key: ctx.key }),
       render: (d) => `已删除主题「${d.name}」#${d.removed.id}: ${d.removed.text}`,
     },
 
@@ -228,9 +243,16 @@ export default {
         beforeId: { type: 'number', hint: '插到该编号之前（与 afterId 二选一）' },
         afterId: { type: 'number', hint: '插到该编号之后（与 beforeId 二选一）' },
         cwd: CWD,
+        key: KEY,
       },
       run: (ctx) =>
-        service.reorderTasks({ id: ctx.id, beforeId: ctx.beforeId, afterId: ctx.afterId, cwd: ctx.cwd }),
+        service.reorderTasks({
+          id: ctx.id,
+          beforeId: ctx.beforeId,
+          afterId: ctx.afterId,
+          cwd: ctx.cwd,
+          key: ctx.key,
+        }),
       render: (d) => {
         const order = d.topic.tasks.filter((x) => x.status !== 'consumed').map((x) => `#${x.id}`);
         return `主题「${d.name}」待领取顺序：${order.join(' -> ') || '（无待领取）'}`;
@@ -242,7 +264,8 @@ export default {
       id: 'localtask.wait',
       cli: ['localtask', 'wait'],
       http: null,
-      summary: '针对某主题（按 cwd 目录名识别）阻塞等待用户回填（默认 3 分钟，最大 10 分钟）',
+      summary:
+        '针对某主题（按 cwd 目录名识别）阻塞等待用户回填（默认 3 分钟，最大 10 分钟）；本地空时自动领取全局共享池的任务',
       flags: {
         cwd: CWD,
         summary: SUMMARY,