nx-kv 0.7.0 → 0.8.0

package/assets/{kv-sessiontask/references/sessiontask-workflow.md → kv-waittask/references/kv-waittask-workflow.md}

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nx-kv",
-  "version": "0.7.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: '工作目录（作为主题；默认当前目录）' };
@@ -76,37 +78,37 @@ function renderRemoveMany(d) {
 }
 
 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: '顺带刷新该主题的当前现状（可选）' } },
@@ -114,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: '任务编号' },
@@ -127,9 +129,9 @@ 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 }),
@@ -138,9 +140,9 @@ export default {
 
     // ─── 主题删除（单个 / 批量）──────────────────────────────
     {
-      id: 'sessiontask.topic.remove',
-      cli: ['sessiontask', 'topic', 'remove'],
-      http: ['DELETE', '/api/sessiontasks/topic'],
+      id: 'localtask.topic.remove',
+      cli: ['localtask', 'topic', 'remove'],
+      http: ['DELETE', '/api/localtasks/topic'],
       summary: '删除整个主题（含全部任务；按 --cwd 或 --key，等待中需 --force）',
       flags: {
         cwd: { type: 'string', hint: '工作目录（与 --key 二选一）' },
@@ -152,9 +154,9 @@ export default {
         `已删除主题「${d.name}」（待领取/共 ${d.topic.pending}/${d.topic.total} 条任务一并删除）`,
     },
     {
-      id: 'sessiontask.topic.removeMany',
-      cli: ['sessiontask', 'topic', 'remove-many'],
-      http: ['POST', '/api/sessiontasks/topics/remove'],
+      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，逗号分隔' },
@@ -168,9 +170,9 @@ export default {
     },
 
     {
-      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 }),
@@ -178,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: '连同已全部领取、无待领的主题一起清' },
@@ -195,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: '要移动的任务编号' },
@@ -215,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') {
@@ -703,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;
@@ -718,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 {

package/src/modules/{sessiontask → localtask}/view.jsx

@@ -1,4 +1,4 @@
-// 实时任务页：主题（按工作目录划分）总览 + 选中某个主题回填 + 该主题的任务队列。
+// 本地任务（localtask）页：主题（按工作目录划分）总览 + 选中某个主题回填 + 该主题的任务队列。
 // 本质是「agent 提交结果 → 阻塞 → 用户在 web 针对主题回填 → agent 接收」。
 import { useCallback, useEffect, useState } from 'react';
 import { api } from '../../web/frontend/api/client.js';
@@ -47,7 +47,7 @@ export default function SessionTaskView() {
 
   const load = useCallback(async () => {
     try {
-      setOverview(await api('/api/sessiontasks'));
+      setOverview(await api('/api/localtasks'));
     } catch (e) {
       toast(e.message);
     }
@@ -75,7 +75,7 @@ export default function SessionTaskView() {
       setTimeoutSec(Number(sec));
       setCfgSaving(true);
       try {
-        const s = await api('/api/sessiontasks/setting', {
+        const s = await api('/api/localtasks/setting', {
           method: 'PATCH',
           body: { timeout: Number(sec) },
         });
@@ -91,7 +91,7 @@ export default function SessionTaskView() {
     guard(async () => {
       setPruning(true);
       try {
-        const r = await api('/api/sessiontasks/prune', { method: 'POST', body: {} });
+        const r = await api('/api/localtasks/prune', { method: 'POST', body: {} });
         toast(r.count ? `已清理 ${r.count} 个旧主题` : '没有需要清理的旧数据');
         await load();
       } finally {
@@ -144,7 +144,7 @@ export default function SessionTaskView() {
       }
       setSaving(true);
       try {
-        const r = await api('/api/sessiontasks', {
+        const r = await api('/api/localtasks', {
           method: 'POST',
           body: { cwd: active.cwd, text: body },
         });
@@ -158,7 +158,7 @@ export default function SessionTaskView() {
 
   const remove = (id) =>
     guard(async () => {
-      await api('/api/sessiontasks/item', {
+      await api('/api/localtasks/item', {
         method: 'DELETE',
         body: { cwd: active.cwd, id },
       });
@@ -175,7 +175,7 @@ export default function SessionTaskView() {
       if (!window.confirm(msg)) return;
       setDeleting(true);
       try {
-        await api('/api/sessiontasks/topic', {
+        await api('/api/localtasks/topic', {
           method: 'DELETE',
           body: t.waiting ? { key: t.key, force: true } : { key: t.key },
         });
@@ -202,7 +202,7 @@ export default function SessionTaskView() {
       if (!window.confirm(msg)) return;
       setDeleting(true);
       try {
-        const r = await api('/api/sessiontasks/topics/remove', {
+        const r = await api('/api/localtasks/topics/remove', {
           method: 'POST',
           body: { keys: [...selected], force: waitingCount > 0 },
         });
@@ -233,7 +233,7 @@ export default function SessionTaskView() {
       }
       setEditSaving(true);
       try {
-        await api('/api/sessiontasks/item', {
+        await api('/api/localtasks/item', {
           method: 'PATCH',
           body: { cwd: active.cwd, id: editingId, text: body },
         });
@@ -255,7 +255,7 @@ export default function SessionTaskView() {
     guard(async () => {
       setReordering(true);
       try {
-        await api('/api/sessiontasks/reorder', {
+        await api('/api/localtasks/reorder', {
           method: 'PATCH',
           body: { cwd: active.cwd, id, beforeId, afterId },
         });
@@ -301,7 +301,7 @@ export default function SessionTaskView() {
       <div className="card" style={{ padding: '10px 14px' }}>
         <div className="muted" style={{ fontSize: 12 }}>
           agent 用法：完成当前任务后，把
-          <code> nx-kv sessiontask wait --cwd "&lt;工作目录&gt;" --summary "&lt;当前现状&gt;" --json </code>
+          <code> nx-kv localtask wait --cwd "&lt;工作目录&gt;" --summary "&lt;当前现状&gt;" --json </code>
           作为本轮<strong>最后一个动作</strong>调用——工作目录即<strong>主题</strong>、主题拥有任务队列，
           同目录共用队列、不同目录互不串，任务可在队列里堆积；命令阻塞并自动打开浏览器弹窗，
           用户回填后解除阻塞、返回新任务；超时未回填则返回 <code>status:"timeout"</code>，agent 收尾结束本轮。
@@ -432,7 +432,7 @@ export default function SessionTaskView() {
           })
         ) : (
           <div className="card muted" style={{ padding: '20px 16px', width: '100%', textAlign: 'center' }}>
-            （暂无主题；agent 调用 sessiontask wait 后会出现在这里）
+            （暂无主题；agent 调用 localtask wait 后会出现在这里）
           </div>
         )}
       </div>
@@ -610,7 +610,7 @@ export default function SessionTaskView() {
         </>
       )}
 
-      <CliHints module="sessiontask" />
+      <CliHints module="localtask" />
     </>
   );
 }