nx-kv 0.6.0 → 0.8.0

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

@@ -0,0 +1,149 @@
+# kv-waittask-workflow — 阻塞等待用户回填任务的完整 SOP
+
+> 归属 [[kv-waittask]]。当你要在一个对话里**不结束本轮**、靠一个阻塞工具
+> 调用等浏览器里继续回填任务时，按本 SOP 走。
+
+## 一、端到端时序
+
+```
+1. agent 正常干活（分析、读写文件、调用其它工具）。
+2. 当前任务做完、提交阶段结果，需要下一条输入时：
+     → 把「nx-kv localtask wait --summary "<当前现状总结>" --json」
+       作为本轮【最后一个动作】调用；工具调用超时设为 300000 ms。
+3. wait 的行为：
+     a. 若本目录主题队列已有待领取任务（含 kv-submit 委托排队的）→ 立即取走、
+        不开窗、不阻塞（queued:true）；
+     b. 否则在本机临时起一个 http 服务器（127.0.0.1，随机端口），
+        自动打开浏览器弹窗，然后阻塞。
+4. 用户在弹窗/面板看清现状，回填新任务 → 提交（Enter 或按钮）。
+5. wait 解除阻塞，stdout(--json) 返回 {status:"ok", task}，进程退出。
+6. agent 从工具结果读 task.text，继续干活、提交结果；做完回到第 2 步——循环。
+7. 若阻塞时限（默认 180 秒）内没有回填：wait 返回 {status:"timeout"}（exit 0），
+   agent 不再等待，收尾并结束本轮。
+```
+
+关键点：**第 2 步之后、工具结果回来之前，agent 不产生任何其它动作。** 用户的
+回填正是通过这个工具结果进入对话的，等于用工具调用替代了在原始输入框打字，
+agent 这一轮不会因为「等输入」而提前结束。
+
+## 二、现状总结怎么写
+
+wait 必带一句当前现状总结（≤2000 字，连续空白会折叠为单空格）：
+
+- 它**只是状态展示**：显示在弹窗/面板顶部，并作为「本轮完成总结」记录在被取走
+  的任务上（`task.roundSummary`），供用户和后续追溯。
+- **它不参与队列分桶**：领取顺序只由本目录队列的先后决定，与措辞无关——同一
+  目录的多次 wait（即便现状措辞不同）共用同一个任务队列。所以不必刻意保持
+  逐字一致，每次如实写当前现状即可。
+- 总结要让用户**不读整段对话也能快速了解现状**，建议包含三要素：
+  1. 已经做到哪一步 / 产出了什么；
+  2. 当前卡在哪、有哪些可选项；
+  3. 具体等用户决定或补充什么。
+- 一句话为宜。示例：
+  - `已完成登录，等待选择工作空间`
+  - `已生成 3 个方案（A/B/C），等待你选一个再细化`
+  - `面板已能提交，但删除还没接，等待确认是否现在补`
+
+## 三、队列语义（按目录划分、可提前排队）
+
+- **工作目录即主题**：wait 不传 `--cwd` 时按进程当前目录的**目录名**定位主题
+  （Windows 折叠大小写，同名目录共用队列）；`add` 可用 `--cwd` 给任意目录的
+  队列排任务。不同目录 → 不同主题 → 队列互不串。
+- 用户在弹窗、常驻面板「本地任务」页、或别人用 `localtask add`（kv-submit）
+  提交的回填，都会以 `pending` 进入对应目录的队列。
+- wait 总是取走该队列**最早的一条 pending**，标记为已领取（consumed）后返回：
+  - 队列非空 → wait 立刻返回（`queued:true`），连弹窗都不打开；
+  - 队列为空 → 才开窗阻塞（`delivered:true`）。
+- 已领取的任务保留为历史（状态「已领取」），不会被二次取走。
+
+这让「趁 agent 还在忙，先把后面几条排好」成为可能：agent 每次 wait 都能立刻
+拿到下一条，不打断节奏。
+
+## 四、返回形状与退出码
+
+成功（exit 0）：
+
+```json
+{
+  "status": "ok",
+  "cwd": "D:\\code\\a_js\\proj\\demo",
+  "summary": "已完成登录，等待选择工作空间",
+  "task": { "id": 3, "text": "选择工作空间 A", "status": "consumed",
+            "createdAt": "2026-10-11 10:00:00", "consumedAt": "2026-10-11 10:00:04",
+            "roundSummary": "已完成登录，等待选择工作空间" },
+  "delivered": true,
+  "queued": false
+}
+```
+
+- `delivered:true` = 实时回填；`queued:true` = 取到队列里排队的任务（二者互斥）。
+- **任务内容永远读 `task.text`**，多行换行原样保留。
+
+超时（exit 0，业务结果而非错误）：
+
+```json
+{ "status": "timeout", "cwd": "D:\\code\\a_js\\proj\\demo",
+  "summary": "已完成登录，等待选择工作空间", "timeoutMs": 180000 }
+```
+
+- 超时**不是失败**：退出码 0，按「用户没继续」收尾，不要按错误处理。
+- 阻塞时限：默认用页面配置（推荐 180 秒，最大 600 秒），可用 `--timeout <秒>`
+  覆盖（超上限自动截断）。
+- 参数非法（如缺 `--summary`、缺 `--id`）才是错误（exit 1，文本带「用法」），
+  按宿主失败流程处理。
+
+## 五、弹窗任务表怎么用（可转述给用户）
+
+- 顶部「当前现状」直接显示 agent 传入的现状总结，先看这句再决定回填什么。
+- 大输入框：回填下一条任务；**Enter 提交，Shift+Enter 换行**。
+- 状态栏倒计时显示还会等多久；归零未回填则本轮自动结束。
+- 下方是该主题的任务表，状态分「待领取 / 已领取」，可删除。
+- 提交后显示「已回填给 agent，正在返回」即说明 wait 已取走、窗口可关闭；agent
+  做完会再开下一个弹窗。
+
+## 六、多主题并存
+
+- 每个工作目录一个主题；常驻面板「本地任务」页把所有主题并排展示，每张卡显示
+  目录、当前现状、等待状态/倒计时、待领取数。
+- 用户在任意主题卡上都能**分别回填**，也可趁 agent 在忙给几个目录提前排队。
+- agent 在哪个目录跑 wait（或 `--cwd` 指哪个目录），就取哪个目录队列的任务，
+  互不串。
+
+## 七、删除主题与批量删除
+
+主题（工作目录）可整体删除，不必逐条删任务：
+
+- **单个删除**：
+  - 面板：主题卡片右下角「删除主题」；
+  - CLI：`nx-kv localtask topic remove --cwd "<工作目录>"`（或 `--key <key>`）。
+- **批量删除**：
+  - 面板：勾选卡片左上角（或总览标题处「全选」）→「批量删除 (N)」；
+  - CLI：`nx-kv localtask topic remove-many --keys "<key,key>"`，也可
+    `--cwds "<dir,dir>"`，或 `--all` 清空。
+- **安全保护**：等待中的主题默认不删（删了阻塞的 agent 只能等到超时）；界面会
+  二次确认，命令需加 `--force` 才连等待中一起删，agent 随后超时收尾。
+- **返回**：单个 `{status:"removed",topic}`；批量 `{count,removed,skipped}`，
+  skipped 列出被跳过的「等待中 / 不存在」主题。
+
+## 八、常见错误与避坑
+
+| 错误做法 | 后果 | 正确做法 |
+| --- | --- | --- |
+| wait 后又安排别的工具/推理 | wait 阻塞，后续动作被卡住、顺序全乱 | wait 严格放在最后一步，之后只处理返回 |
+| 工具超时没设 / 设成 120000 | CLI 默认阻塞 180 秒，宿主会在阻塞中途杀掉调用 | 工具超时设 `300000` ms；用更长的 `--timeout` 时同步放大 |
+| wait 不带 / 空着 --summary | 无法展示现状，命令报错退出 | 每次 wait 都写一句现状总结 |
+| 刻意维持现状措辞逐字一致 | 白费功夫——现状只是展示，不影响领取 | 每次如实写当前现状即可 |
+| 在错误的目录调 wait（没传 --cwd） | 取到别的目录队列的任务，或开出一个没人看的弹窗 | 确认进程 cwd 或显式 `--cwd "<目标目录>"` |
+| 把 timeout 当报错、反复重试 | 用户想停却被反复弹窗 | timeout 即收尾结束本轮 |
+| 读 `task.id` 当任务内容 | id 只是编号，内容在 `task.text` | 一律读 `task.text` |
+| 同时开多个 wait（同一目录主题） | 只有一个收到回填，另一个等到超时 | 同一目录同一时刻只调一个 wait |
+| 没用 --json | 输出人读文本，宿主难以可靠解析 | agent 调用一律加 `--json` |
+
+## 九、与常驻面板配合 / 排障
+
+- 已 `nx-kv serve` 打开面板时，直接在「本地任务」页点选主题回填；正在阻塞的
+  wait 通过轮询（约每 0.5 秒）取走，不依赖弹窗本身。
+- 弹窗没自动打开时：终端输出里有本次地址（`http://127.0.0.1:<端口>/`），手动
+  复制到浏览器打开；该窗口只在本次 wait 期间有效。
+- wait 结束（拿到任务或超时）后弹窗服务器随即关闭，窗口里再提交会失败——下一
+  条等 agent 下一次 wait 打开新窗口再给，或直接在常驻面板回填。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nx-kv",
-  "version": "0.6.0",
-  "description": "nx-kv — KV 清单管理中枢 + 对话内实时任务接力：serve 驱动 CLI 与 Web 面板，同源同构，附带可安装 skill 供 agent 领取任务与阻塞接收用户输入",
+  "version": "0.8.0",
+  "description": "nx-kv — KV 清单管理中枢（远程）+ 本机本地任务队列（localtask）：serve 驱动 CLI 与 Web 面板，同源同构，附带可安装 skill 供 agent 提交 / 领取 / 阻塞接收任务",
   "type": "module",
   "bin": {
     "nx-kv": "bin/cli.mjs"

package/src/index.js

@@ -4,7 +4,7 @@ export * as config from './core/config.js';
 export * as kvapi from './core/kvapi.js';
 export * as errors from './core/errors.js';
 export * as todo from './modules/todo/service.js';
-export * as sessiontask from './modules/sessiontask/service.js';
+export * as localtask from './modules/localtask/service.js';
 
 export { ACTIONS, MODULES } from './runtime/registry.js';
 export { startServer } from './runtime/server.js';

package/src/modules/{sessiontask → localtask}/index.js

@@ -1,14 +1,16 @@
-// 实时任务输入模块：在一个对话里通过工具调用向 agent 实时回填任务，替代原始输入框。
+// 本地任务（localtask）模块：本机按「工作目录（cwd）」划分的任务队列——提交（add）、
+// 领取（wait）、查看/编辑/删除/调序（list/get/update/remove/reorder）与主题管理。
+// 阻塞等待只是当前的一个子功能：agent 在一个对话里需要用户继续给任务时，不必结束
+// 本轮、等用户去原始输入框打字，而是把
+// `localtask wait --cwd "<工作目录>" --summary "<当前现状>"` 作为本轮**最后一步**调用：
+// 命令阻塞、自动打开浏览器弹窗，用户回填后解除阻塞、把新任务作为结果返回，agent 接着干。
 //
-// 声明了 `resource: 'sessiontask'`，故 CRUD 五操作齐备且两端可调用
-// （tests/unit/registry.test.mjs 据此断言）。核心动作是纯 CLI 的
-// `sessiontask wait --cwd "<工作目录>" --summary "<当前现状>"`——agent 把它放在本轮
-// **最后一步**调用：阻塞、自动打开浏览器弹窗，用户回填后解除阻塞，把新任务返回给
-// agent。工作目录即主题、主题拥有任务队列：同目录共用队列、不同目录互不串，任务可
-// 在主题队列里堆积。
+// 声明了 `resource: 'localtask'`，故 CRUD 五操作齐备且两端可调用
+// （tests/unit/registry.test.mjs 据此断言）。工作目录即主题、主题拥有任务队列：
+// 同目录共用队列、不同目录互不串，任务可在主题队列里堆积。
 //
-// 与 todo 的区别：todo 管 KV 后端上的清单（需登录）；sessiontask 是**本机**
-// 实时人机接力，数据存本地文件，不依赖后端登录态。
+// 与 todo 的区别：todo 管 KV 后端上的清单（需登录）；localtask 是**本机**
+// 任务队列，数据存本地文件，不依赖后端登录态。
 import * as service from './service.js';
 
 const CWD = { type: 'string', hint: '工作目录（作为主题；默认当前目录）' };
@@ -60,38 +62,53 @@ 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「实时任务」页）',
+  id: 'localtask',
+  title: '本地任务（= Web「本地任务」页）',
   order: 20,
   view: () => import('./view.jsx'),
 
   // CRUD 资源声明：主题任务的增删查改齐备，CLI 与面板都能调用
-  resource: 'sessiontask',
+  resource: 'localtask',
 
   actions: [
     // ─── CRUD 五操作 ───────────────────────────────────────────
     {
-      id: 'sessiontask.list',
-      cli: ['sessiontask', 'list'],
-      http: ['GET', '/api/sessiontasks'],
+      id: 'localtask.list',
+      cli: ['localtask', 'list'],
+      http: ['GET', '/api/localtasks'],
       summary: '总览全部主题（工作目录、现状、是否等待中、待领取数）',
       run: () => service.listTasks(),
       render: renderOverview,
     },
     {
-      id: 'sessiontask.get',
-      cli: ['sessiontask', 'get'],
-      http: ['GET', '/api/sessiontasks/item'],
+      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 }),
       render: renderTask,
     },
     {
-      id: 'sessiontask.add',
-      cli: ['sessiontask', 'add'],
-      http: ['POST', '/api/sessiontasks'],
+      id: 'localtask.add',
+      cli: ['localtask', 'add'],
+      http: ['POST', '/api/localtasks'],
       summary: '向某主题（工作目录）的队列回填一条任务（有 wait 在等则即时投递，否则排队）',
       args: ['text'],
       flags: { cwd: CWD, summary: { type: 'string', hint: '顺带刷新该主题的当前现状（可选）' } },
@@ -99,9 +116,9 @@ export default {
       render: renderAdd,
     },
     {
-      id: 'sessiontask.update',
-      cli: ['sessiontask', 'update'],
-      http: ['PATCH', '/api/sessiontasks/item'],
+      id: 'localtask.update',
+      cli: ['localtask', 'update'],
+      http: ['PATCH', '/api/localtasks/item'],
       summary: '编辑任务内容（按 --id，定位到 --cwd 主题）',
       flags: {
         id: { type: 'number', required: true, hint: '任务编号' },
@@ -112,19 +129,50 @@ export default {
       render: (d) => `已更新主题「${d.name}」#${d.task.id}: ${d.task.text}`,
     },
     {
-      id: 'sessiontask.remove',
-      cli: ['sessiontask', 'remove'],
-      http: ['DELETE', '/api/sessiontasks/item'],
+      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 }),
       render: (d) => `已删除主题「${d.name}」#${d.removed.id}: ${d.removed.text}`,
     },
 
+    // ─── 主题删除（单个 / 批量）──────────────────────────────
+    {
+      id: 'localtask.topic.remove',
+      cli: ['localtask', 'topic', 'remove'],
+      http: ['DELETE', '/api/localtasks/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: 'localtask.topic.removeMany',
+      cli: ['localtask', 'topic', 'remove-many'],
+      http: ['POST', '/api/localtasks/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'],
-      http: ['PATCH', '/api/sessiontasks/setting'],
+      id: 'localtask.config',
+      cli: ['localtask', 'config'],
+      http: ['PATCH', '/api/localtasks/setting'],
       summary: '配置等待超时（秒；推荐 180=3 分钟，最大 600=10 分钟，超上限自动截断）',
       flags: { timeout: { type: 'number', required: true, hint: '超时秒数（1-600）' } },
       run: (ctx) => service.updateSettings({ timeoutSec: ctx.timeout }),
@@ -132,9 +180,9 @@ export default {
     },
 
     {
-      id: 'sessiontask.prune',
-      cli: ['sessiontask', 'prune'],
-      http: ['POST', '/api/sessiontasks/prune'],
+      id: 'localtask.prune',
+      cli: ['localtask', 'prune'],
+      http: ['POST', '/api/localtasks/prune'],
       summary: '清理旧脏数据（旧模型无目录主题、空主题；等待中一律保留）',
       flags: {
         'all-finished': { type: 'boolean', hint: '连同已全部领取、无待领的主题一起清' },
@@ -149,9 +197,9 @@ export default {
     },
 
     {
-      id: 'sessiontask.reorder',
-      cli: ['sessiontask', 'reorder'],
-      http: ['PATCH', '/api/sessiontasks/reorder'],
+      id: 'localtask.reorder',
+      cli: ['localtask', 'reorder'],
+      http: ['PATCH', '/api/localtasks/reorder'],
       summary: '调整待领取任务优先级（--id <编号> 移到 --before-id <编号> 前或 --after-id <编号> 后）',
       flags: {
         id: { type: 'number', required: true, hint: '要移动的任务编号' },
@@ -169,8 +217,8 @@ export default {
 
     // ─── 阻塞等待（纯 CLI，agent 本轮最后一步）────────────────
     {
-      id: 'sessiontask.wait',
-      cli: ['sessiontask', 'wait'],
+      id: 'localtask.wait',
+      cli: ['localtask', 'wait'],
       http: null,
       summary: '针对某主题（按 cwd 目录名识别）阻塞等待用户回填（默认 3 分钟，最大 10 分钟）',
       flags: {

package/src/modules/{sessiontask → localtask}/popup.js

@@ -12,7 +12,7 @@ export function renderPopupPage({ key, cwd, summary, timeoutMs }) {
 <head>
 <meta charset="utf-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1" />
-<title>nx-kv · 实时任务</title>
+<title>nx-kv · 本地任务</title>
 <style>
   :root {
     --ink: #14161a;
@@ -109,7 +109,7 @@ export function renderPopupPage({ key, cwd, summary, timeoutMs }) {
 <body>
 <div class="wrap">
   <div class="top">
-    <div class="brand">nx-kv<span class="sub">实时任务输入</span></div>
+    <div class="brand">nx-kv<span class="sub">本地任务</span></div>
     <div class="meta"><span class="pill">回填后立即返回 agent</span></div>
   </div>
 
@@ -217,7 +217,7 @@ export function renderPopupPage({ key, cwd, summary, timeoutMs }) {
 
   function refresh() {
     if (delivered) return;
-    fetch('/api/sessiontasks', { cache: 'no-store' })
+    fetch('/api/localtasks', { cache: 'no-store' })
       .then(function (r) { return r.json(); })
       .then(function (j) {
         if (!j.ok) return;
@@ -234,7 +234,7 @@ export function renderPopupPage({ key, cwd, summary, timeoutMs }) {
     var input = el('input');
     var text = input.value.trim();
     if (!text) { input.focus(); return; }
-    fetch('/api/sessiontasks', {
+    fetch('/api/localtasks', {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({ text: text })
@@ -266,7 +266,7 @@ export function renderPopupPage({ key, cwd, summary, timeoutMs }) {
   el('list').addEventListener('click', function (e) {
     var b = e.target;
     if (b && b.dataset && b.dataset.id) {
-      fetch('/api/sessiontasks/item', {
+      fetch('/api/localtasks/item', {
         method: 'DELETE',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ id: Number(b.dataset.id) })

package/src/modules/{sessiontask → localtask}/service.js

@@ -1,8 +1,8 @@
-// 实时任务输入 service —— 按「工作目录（cwd）」划分的主题（topic）+ 主题任务队列 +
-// 阻塞等待 + 内嵌弹窗。
+// 本地任务（localtask）service —— 按「工作目录（cwd）」划分的主题（topic）+ 主题任务队列 +
+// 领取（含阻塞等待子功能）+ 内嵌弹窗。
 //
 // 解决的问题：agent 在一个对话里需要用户继续给任务时，不必结束本轮、等用户去
-// 原始输入框打字，而是把 `nx-kv sessiontask wait --cwd "<工作目录>" --summary "<当前现状>"`
+// 原始输入框打字，而是把 `nx-kv localtask wait --cwd "<工作目录>" --summary "<当前现状>"`
 // 当作 **本轮最后一个动作**调用——命令阻塞、自动打开浏览器弹窗；用户在弹窗/面板回填，
 // 命令解除阻塞、把新任务作为结果返回给 agent，agent 接着干。
 //
@@ -16,7 +16,7 @@
 //      http 服务器直出，未登录也能用。
 //   4. **排队语义。** 用户可提前回填：主题已有 pending 时 wait 立即取走、不开窗；
 //      没有 pending 才开窗阻塞。
-//   5. **超时是业务结果不是错误。** 默认阻塞 2 分钟；超时返回 {status:'timeout'}、
+//   5. **超时是业务结果不是错误。** 默认阻塞 3 分钟（页面可调，上限 10 分钟）；超时返回 {status:'timeout'}、
 //      exit 0，agent 据此安静收尾结束本轮，绝不抛异常。
 //
 // 跨进程：弹窗与 wait 同进程时靠内存 waiter 即时唤醒；任务由别的进程写入（如常驻
@@ -37,10 +37,21 @@ export const MAX_TIMEOUT_SEC = 600; // 阻塞时长上限（10 分钟）
 export const MAX_SUMMARY = 2000; // 现状（状态）长度上限（原 200，已放宽）
 export const MAX_TEXT = 20_000; // 单条任务内容长度上限
 
-// ─── 存储位置：可环境变量覆盖（测试隔离） ───────────────────────────
+// ─── 存储位置：可环境变量覆盖（测试隔离）；旧名/旧文件自动兼容 ──────────
 
 export function storePath() {
-  return process.env.NX_KV_SESSIONTASK_STORE || join(APP_DIR, 'sessiontasks.json');
+  return (
+    process.env.NX_KV_LOCALTASK_STORE ||
+    process.env.NX_KV_SESSIONTASK_STORE || // 改名前的环境变量，兼容既有脚本
+    join(APP_DIR, 'localtasks.json')
+  );
+}
+
+// 改名前的存储文件。显式覆盖（任一环境变量）时不迁移；新文件缺失时读它，
+// 首次保存即落到新文件（旧文件保留不删，数据零丢失）。
+function legacyStorePath() {
+  if (process.env.NX_KV_LOCALTASK_STORE || process.env.NX_KV_SESSIONTASK_STORE) return null;
+  return join(APP_DIR, 'sessiontasks.json');
 }
 
 // ─── 工作目录 → 主题 ───────────────────────────────────────────────
@@ -141,7 +152,15 @@ async function loadStore() {
   let topics = null;
   let settings = null;
   try {
-    const raw = await fsp.readFile(storePath(), 'utf8');
+    let raw;
+    try {
+      raw = await fsp.readFile(storePath(), 'utf8');
+    } catch (err) {
+      // 新文件不存在 → 尝试改名前的旧文件（一次性迁移读取；再缺失才落到空 store）
+      const legacy = err && err.code === 'ENOENT' ? legacyStorePath() : null;
+      if (!legacy) throw err;
+      raw = await fsp.readFile(legacy, 'utf8');
+    }
     const data = JSON.parse(raw);
     if (data && typeof data === 'object') {
       if (data.topics && typeof data.topics === 'object') {
@@ -274,6 +293,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 +461,76 @@ 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 之间换位；已领取（历史）任务固定、不可移动。
@@ -562,7 +663,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;
@@ -621,12 +722,12 @@ async function handlePopup(req, res, key, cwd, summary, timeoutMs) {
       return;
     }
 
-    if (url.pathname === '/api/sessiontasks' && method === 'GET') {
+    if (url.pathname === '/api/localtasks' && method === 'GET') {
       sendJson(res, 200, { ok: true, data: await listTasks() });
       return;
     }
 
-    if (url.pathname === '/api/sessiontasks' && method === 'POST') {
+    if (url.pathname === '/api/localtasks' && method === 'POST') {
       if (!originAllowed(req)) {
         sendJson(res, 403, { ok: false, error: '跨站请求被拒绝（弹窗仅接受本机来源）', code: 'BLOCKED' });
         return;
@@ -636,7 +737,7 @@ async function handlePopup(req, res, key, cwd, summary, timeoutMs) {
       return;
     }
 
-    if (url.pathname === '/api/sessiontasks/item' && method === 'DELETE') {
+    if (url.pathname === '/api/localtasks/item' && method === 'DELETE') {
       if (!originAllowed(req)) {
         sendJson(res, 403, { ok: false, error: '跨站请求被拒绝（弹窗仅接受本机来源）', code: 'BLOCKED' });
       } else {