nx-kv 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [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
+
+- **待领取任务队列支持拖拽重排序优先级**：
+  - 「实时任务」页队列的待领取行可按住拖拽（行首 ⠿ 手柄），拖动时半透明、目标行
+    显示上/下落点指示线，松开即调整领取顺序；表格反转显示，落点已正确映射到数组真实顺序。
+  - 同时提供「提前 / 置后」按钮作为拖拽之外的兜底（窄屏/触屏友好），边界自动禁用。
+  - 新增 `nx-kv sessiontask reorder --id <编号> (--beforeId <编号> | --afterId <编号>) [--cwd]`
+    与 HTTP `PATCH /api/sessiontasks/reorder`；只在待领取任务之间换位，已领取（历史）任务
+    固定不可移动；非法输入（同时给/都不给/移到自己/移动已领取）一律显式报错。
+- 新增 reorder 逻辑单测；全套 51 项全绿。
+
 ## [0.5.0] - 2026-10-08
 
 ### Added

package/README.md

@@ -81,8 +81,9 @@ nx-kv sessiontask wait --summary "<当前现状总结>" --json
 新等待点。弹窗/面板顶部直接显示现状，用户不读对话也能快速了解、点选等待点
 **分别回填（分散答复）**，也可提前排队；等待点非空时 wait 立即取走、不开窗。
 纯本机协调、存本地文件，**不需登录后端**。其余命令：
-`sessiontask list / add / get / update / remove`（均按 `--summary` 定位），
-面板上对应「实时任务」页。
+`sessiontask list / add / get / update / remove`，以及主题级
+`sessiontask topic remove`（删整个主题）与 `sessiontask topic remove-many`
+（批量删除，`--keys/--cwds/--all`；等待中需 `--force`），面板上对应「实时任务」页。
 
 配套 skill：
 

package/assets/kv-sessiontask/SKILL.md

@@ -77,9 +77,15 @@ nx-kv sessiontask list                                   # 等待点总览
 nx-kv sessiontask add  "<回填内容>" --summary "<现状>"    # 针对现状排队/投递
 nx-kv sessiontask get   --id <n> --summary "<现状>"       # 查看单条
 nx-kv sessiontask update --id <n> --text "<新内容>" --summary "<现状>"
-nx-kv sessiontask remove --id <n> --summary "<现状>"      # 删除
+nx-kv sessiontask remove --id <n> --summary "<现状>"      # 删除单条任务
+nx-kv sessiontask topic remove --cwd "<工作目录>"          # 删除整个主题（等待中需 --force）
+nx-kv sessiontask topic remove-many --keys "<key,key>"     # 批量删除主题（或 --cwds "<dir,dir>"，或 --all）
 ```
 
+> 删除主题：面板「主题总览」每张卡有「删除主题」，顶部勾选后可「批量删除」。
+> 等待中的主题默认不删（避免让阻塞的 agent 干等），确认要删会二次提示并以
+> `--force` 强删、agent 随后超时收尾。
+
 常驻面板（`nx-kv serve`）的「实时任务」页就是等待点总览，可直接点选回填；
 wait 同样能取走（跨进程由轮询兜底）。
 

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

@@ -103,7 +103,23 @@ wait 必带一句当前现状总结，它被归一化（折叠首尾/连续空
   各现状下，而不是挤在一个队列。
 - agent 用对应现状调 wait 时只取该等待点的任务，互不串。
 
-## 七、常见错误与避坑
+## 七、删除主题与批量删除
+
+主题（工作目录）可整体删除，不必逐条删任务：
+
+- **单个删除**：
+  - 面板：主题卡片右下角「删除主题」；
+  - CLI：`nx-kv sessiontask topic remove --cwd "<工作目录>"`（或 `--key <key>`）。
+- **批量删除**：
+  - 面板：勾选卡片左上角（或总览标题处「全选」）→「批量删除 (N)」；
+  - CLI：`nx-kv sessiontask topic remove-many --keys "<key,key>"`，也可
+    `--cwds "<dir,dir>"`，或 `--all` 清空。
+- **安全保护**：等待中的主题默认不删（删了阻塞的 agent 只能等到超时）；界面会
+  二次确认，命令需加 `--force` 才连等待中一起删，agent 随后超时收尾。
+- **返回**：单个 `{status:"removed",topic}`；批量 `{count,removed,skipped}`，
+  skipped 列出被跳过的「等待中 / 不存在」主题。
+
+## 八、常见错误与避坑
 
 | 错误做法 | 后果 | 正确做法 |
 | --- | --- | --- |
@@ -117,7 +133,7 @@ wait 必带一句当前现状总结，它被归一化（折叠首尾/连续空
 | 同时开多个 wait（同一等待点） | 只有一个收到回填，另一个等到超时 | 同一等待点同一时刻只调一个 wait |
 | 没用 --json | 输出人读文本，宿主难以可靠解析 | agent 调用一律加 `--json` |
 
-## 八、与常驻面板配合 / 排障
+## 九、与常驻面板配合 / 排障
 
 - 已 `nx-kv serve` 打开面板时，直接在「等待点总览」点选现状回填；正在阻塞的
   wait 通过轮询（约每 0.5 秒）取走，不依赖弹窗本身。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nx-kv",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "nx-kv — KV 清单管理中枢 + 对话内实时任务接力：serve 驱动 CLI 与 Web 面板，同源同构，附带可安装 skill 供 agent 领取任务与阻塞接收用户输入",
   "type": "module",
   "bin": {

package/src/modules/sessiontask/index.js

@@ -60,6 +60,21 @@ function renderWait(r) {
   );
 }
 
+// 批量删除的人读输出：删除清单 + 跳过清单（等待中/不存在）
+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' ? '等待中' : '不存在';
+      lines.push(`  - [${why}] ${s.name || s.key}`);
+    }
+  }
+  if (!d.removed.length && !d.skipped.length) lines.push('（没有匹配的主题）');
+  return lines.join('\n');
+}
+
 export default {
   id: 'sessiontask',
   title: '实时任务（= Web「实时任务」页）',
@@ -121,6 +136,37 @@ export default {
       render: (d) => `已删除主题「${d.name}」#${d.removed.id}: ${d.removed.text}`,
     },
 
+    // ─── 主题删除（单个 / 批量）──────────────────────────────
+    {
+      id: 'sessiontask.topic.remove',
+      cli: ['sessiontask', 'topic', 'remove'],
+      http: ['DELETE', '/api/sessiontasks/topic'],
+      summary: '删除整个主题（含全部任务；按 --cwd 或 --key，等待中需 --force）',
+      flags: {
+        cwd: { type: 'string', hint: '工作目录（与 --key 二选一）' },
+        key: { type: 'string', hint: '主题 key（与 --cwd 二选一）' },
+        force: { type: 'boolean', hint: '连等待中的主题也删（agent 将超时收尾）' },
+      },
+      run: (ctx) => service.removeTopic({ cwd: ctx.cwd, key: ctx.key, force: ctx.force }),
+      render: (d) =>
+        `已删除主题「${d.name}」（待领取/共 ${d.topic.pending}/${d.topic.total} 条任务一并删除）`,
+    },
+    {
+      id: 'sessiontask.topic.removeMany',
+      cli: ['sessiontask', 'topic', 'remove-many'],
+      http: ['POST', '/api/sessiontasks/topics/remove'],
+      summary: '批量删除主题（--keys/--cwds 逗号分隔，或 --all；等待中默认跳过，--force 连等待中删）',
+      flags: {
+        keys: { type: 'array', hint: '主题 key，逗号分隔' },
+        cwds: { type: 'array', hint: '工作目录，逗号分隔' },
+        all: { type: 'boolean', hint: '清空全部主题（等待中仍跳过，除非 --force）' },
+        force: { type: 'boolean', hint: '连等待中的主题一起删' },
+      },
+      run: (ctx) =>
+        service.removeTopics({ keys: ctx.keys, cwds: ctx.cwds, all: ctx.all, force: ctx.force }),
+      render: renderRemoveMany,
+    },
+
     {
       id: 'sessiontask.config',
       cli: ['sessiontask', 'config'],
@@ -148,6 +194,25 @@ export default {
       },
     },
 
+    {
+      id: 'sessiontask.reorder',
+      cli: ['sessiontask', 'reorder'],
+      http: ['PATCH', '/api/sessiontasks/reorder'],
+      summary: '调整待领取任务优先级（--id <编号> 移到 --before-id <编号> 前或 --after-id <编号> 后）',
+      flags: {
+        id: { type: 'number', required: true, hint: '要移动的任务编号' },
+        beforeId: { type: 'number', hint: '插到该编号之前（与 afterId 二选一）' },
+        afterId: { type: 'number', hint: '插到该编号之后（与 beforeId 二选一）' },
+        cwd: CWD,
+      },
+      run: (ctx) =>
+        service.reorderTasks({ id: ctx.id, beforeId: ctx.beforeId, afterId: ctx.afterId, cwd: ctx.cwd }),
+      render: (d) => {
+        const order = d.topic.tasks.filter((x) => x.status !== 'consumed').map((x) => `#${x.id}`);
+        return `主题「${d.name}」待领取顺序：${order.join(' -> ') || '（无待领取）'}`;
+      },
+    },
+
     // ─── 阻塞等待（纯 CLI，agent 本轮最后一步）────────────────
     {
       id: 'sessiontask.wait',

package/src/modules/sessiontask/service.js

@@ -274,6 +274,18 @@ async function setWaiting(key, cwd, summary, waiting, deadline) {
   await saveStore(store);
 }
 
+// wait 结束复位：**仅当主题仍存在**时清等待态，绝不重建——主题可能已被 force 删除，
+// 重建会让「删除主题」失效（曾在超时清理路径上把删掉的主题又建回来）。
+async function clearWaiting(key) {
+  const store = await loadStore();
+  const t = store.topics[key];
+  if (!t) return;
+  t.waiting = false;
+  t.waitingUntil = '';
+  t.updatedAt = stampNow();
+  await saveStore(store);
+}
+
 // ─── CRUD ───────────────────────────────────────────────────────────
 
 function settingsView(s) {
@@ -430,6 +442,125 @@ export async function removeTask({ cwd: rawCwd, id } = {}) {
   return { status: 'ok', key, cwd, name: t.name, removed: normalizeTask(removed) };
 }
 
+// ─── 主题删除（单个 / 批量） ───────────────────────────────────────
+
+// 定位主题 key：显式 --key 优先，否则按工作目录（目录名）推导
+function resolveTopicKey({ key: rawKey, cwd: rawCwd }) {
+  if (rawKey && String(rawKey).trim()) return String(rawKey).trim();
+  return normalizeCwd(rawCwd).key;
+}
+
+// 删除整个主题（连同其全部任务）。默认拒绝删除「等待中」主题——那会让正阻塞的
+// agent 只能等到超时；force=true 才强删（agent 随后超时收尾）。
+export async function removeTopic({ cwd: rawCwd, key: rawKey, force = false } = {}) {
+  if (!rawKey && !rawCwd) {
+    throw badInput('需要 --cwd "<工作目录>" 或 --key "<主题key>"');
+  }
+  const key = resolveTopicKey({ key: rawKey, cwd: rawCwd });
+  const store = await loadStore();
+  const t = store.topics[key];
+  if (!t) {
+    const { notFound } = await import('../../core/errors.js');
+    throw notFound(`主题不存在（key ${key}）`);
+  }
+  if (t.waiting && !force) {
+    throw badInput('主题正在等待中，不能删除（确认要删请加 --force，agent 将超时收尾）');
+  }
+  const view = topicView(t);
+  delete store.topics[key];
+  await saveStore(store);
+  return { status: 'removed', key, name: t.name, cwd: t.cwd, topic: view };
+}
+
+// 批量删除主题：keys / cwds（数组，可并用），或 all=true 清空全部。
+// 默认把「等待中」「不存在」计入 skipped 而不删；force=true 连等待中一起删。
+export async function removeTopics({ keys, cwds, all = false, force = false } = {}) {
+  const hasList = (a) => Array.isArray(a) && a.some((x) => String(x).trim());
+  if (!all && !hasList(keys) && !hasList(cwds)) {
+    throw badInput('需要 --keys "<key,key>" 或 --cwds "<目录,目录>"，或 --all');
+  }
+
+  const store = await loadStore();
+  let targets;
+  if (all) {
+    targets = Object.keys(store.topics);
+  } else {
+    const list = [];
+    if (Array.isArray(keys)) list.push(...keys.map((x) => String(x).trim()).filter(Boolean));
+    if (Array.isArray(cwds)) {
+      for (const c of cwds) if (String(c).trim()) list.push(normalizeCwd(c).key);
+    }
+    targets = [...new Set(list)];
+  }
+
+  const removed = [];
+  const skipped = [];
+  for (const key of targets) {
+    const t = store.topics[key];
+    if (!t) {
+      skipped.push({ key, reason: 'not_found' });
+      continue;
+    }
+    if (t.waiting && !force) {
+      skipped.push({ key, name: t.name, cwd: t.cwd, reason: 'waiting' });
+      continue;
+    }
+    removed.push({ key, name: t.name, cwd: t.cwd });
+    delete store.topics[key];
+  }
+  if (removed.length) await saveStore(store);
+  return { status: 'ok', all: !!all, count: removed.length, removed, skipped };
+}
+
+// 调整**待领取**任务的优先级：把 #id 移动到 #beforeId 之前或 #afterId 之后。
+// 领取顺序 = tasks 数组里 pending 子序列的先后（consumeFirstPending 取第一条 pending），
+// 故只在 pending 之间换位；已领取（历史）任务固定、不可移动。
+export async function reorderTasks({ cwd: rawCwd, id, beforeId, afterId } = {}) {
+  const { key, cwd } = normalizeCwd(rawCwd);
+  const dragId = Number(id);
+  const hasBefore = beforeId !== undefined && beforeId !== null;
+  const hasAfter = afterId !== undefined && afterId !== null;
+
+  if (!Number.isFinite(dragId) || dragId <= 0) {
+    throw badInput('reorder 缺少 --id <要移动的任务编号>');
+  }
+  if (hasBefore === hasAfter) {
+    throw badInput('reorder 需且仅需 --before <编号> 或 --after <编号> 之一');
+  }
+  const targetId = Number(hasBefore ? beforeId : afterId);
+  if (!Number.isFinite(targetId) || targetId <= 0) {
+    throw badInput('reorder 的目标任务编号非法');
+  }
+  if (targetId === dragId) throw badInput('不能把任务移动到它自己旁边');
+
+  const store = await loadStore();
+  const t = store.topics[key];
+  if (!t) {
+    const { notFound } = await import('../../core/errors.js');
+    throw notFound(`主题「${cwd}」不存在`);
+  }
+  const drag = t.tasks.find((x) => Number(x.id) === dragId);
+  const target = t.tasks.find((x) => Number(x.id) === targetId);
+  if (!drag || !target) {
+    const { notFound } = await import('../../core/errors.js');
+    throw notFound(
+      `主题「${t.name}」里找不到任务 #${drag ? targetId : dragId}`
+    );
+  }
+  if (drag.status === 'consumed' || target.status === 'consumed') {
+    throw badInput('只有「待领取」任务可以调整优先级（已领取任务是固定历史）');
+  }
+
+  const from = t.tasks.indexOf(drag);
+  t.tasks.splice(from, 1);
+  const ti = t.tasks.indexOf(target); // 删除 drag 后目标下标自动修正
+  t.tasks.splice(hasBefore ? ti : ti + 1, 0, drag);
+  t.updatedAt = stampNow();
+
+  await saveStore(store);
+  return { status: 'ok', key, cwd, name: t.name, topic: topicView(t) };
+}
+
 // ─── 阻塞等待：核心入口 ─────────────────────────────────────────────
 
 /**
@@ -513,7 +644,7 @@ export async function waitForTask({
     clearInterval(poll);
     clearTimeout(timer);
     waiters.delete(key);
-    await setWaiting(key, cwd, '', false);
+    await clearWaiting(key);
     await stopServer(server);
   }
   return result;