nx-kv 0.8.2 → 0.8.4

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.8.4] - 2026-10-12
+
+### Added
+
+- **主题总览加「实时连接」探活指示灯**：1.5s 数据轮询 + EventSource 双心跳，
+  主题总览标题旁显示「实时连接正常 / 连接断开，正在重连… / 正在连接…」三态
+  （断线用红色语义提示）；轮询失败不再每 1.5s 弹错误 toast，统一由指示灯提示。
+- **主题现状 / 上一轮完成总结 / 长任务文本支持点击弹窗阅读**：在原位完整展示基础上，
+  叠加点击在居中模态框中专注阅读（长任务文本长度 >50 时才显示可点击指针）；
+  支持点遮罩、按 Esc 或「关闭」按钮退出。纯前端交互、无新接口。
+- **wait 生命周期事件流（后端 SSE）**：
+  - HTTP 为 **SSE** `GET /api/localtasks/events`（可带 `cwd`/`key` 过滤，缺省订阅全部主题，
+    首帧 `: connected`、每 15s 心跳、断线自动重连）；CLI 等价为
+    `localtask events [--cwd|--key]`，逐行 NDJSON。
+  - 事件三类：`waiting`（开始等待，连接时已在等待补发 `replay` 快照）、
+    `reminder`（剩余 **30s / 10s** 各提醒一次）、`resolved`（`delivered` 被回填 /
+    `timeout` 超时；对等待标志残留的僵死状态补发 `stale:true` 的 timeout）。
+  - 后端生成器 `watchEvents` 与传输 `streamEventsSSE` 解耦，单测可独立驱动生成器。
+  - `api.js` 增 `action.stream === true` 机制：透传 req/res 给 action.run，
+    由 action 自己接管响应（SSE 等长连接用得到）。
+
+## [0.8.3] - 2026-10-12
+
+### Changed
+
+- **wait 统一到常驻主面板（固定端口 7877），彻底移除随机端口临时弹窗**：
+  - wait 阻塞时不再在 wait 进程内临时起 http 服务器/弹窗，而是复用 `nx-kv serve` 的
+    「本地任务」页：已在运行则直接打开并深链到当前主题
+    （`#/localtask?key=<主题>&cwd=<目录>`，前端按 key/cwd 自动选中）；
+  - 主面板未运行时，wait 在后台 **detached 自动拉起** `nx-kv serve --no-open
+    --auto-exit`（独立常驻进程，健康检查通过后再开浏览器；拉起失败只降级为纯阻塞、
+    绝不报错中断）；
+  - **主面板页面常驻、提交后不关闭、可连续排队**；wait 拿到任务或超时退出后 serve 依然存活，
+    回填统一由约每 0.5 秒的跨进程文件轮询取走（独立进程写入返回 `delivered:false`）；
+  - `--no-open` 语义保持：不开浏览器、也不自动拉起 serve，仅阻塞等待（冒烟/CI 依赖）。
+
+### Removed
+
+- 删除随 wait 生命周期起停的随机端口临时弹窗服务器及其内嵌页面
+  （`src/modules/localtask/popup.js`），以及与之重复的弹窗专用 HTTP 路由；
+  实时任务统一在固定端口常驻主面板完成。
+  **行为变更**：不再有「wait 结束即关闭」的临时窗口，也不再输出随机端口地址——
+  请改用常驻面板 `http://127.0.0.1:7877/`（wait 会自动打开/拉起）。
+
 ## [0.8.2] - 2026-10-12
 
 ### Added

package/package.json

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

package/src/modules/localtask/index.js

@@ -271,5 +271,31 @@ export default {
       run: (ctx) => service.cancelWait({ cwd: ctx.cwd, key: ctx.key }),
       render: renderCancel,
     },
+
+    {
+      // 探测常驻面板上当前正打开的「实时任务」标签数（活动 SSE 连接数）。
+      // wait 开页前先经此端点：有活标签就复用、不再 openBrowser 新开页（避免 Edge 重复开标签）；
+      // 没有活标签时才开页深链。探测失败 / 旧版无此端点时 service 保守返回 0，不阻塞 wait。
+      id: 'localtask.presence',
+      cli: ['localtask', 'presence'],
+      http: ['GET', '/api/localtasks/presence'],
+      summary: '探测主面板上当前打开的「实时任务」标签数（活动 SSE 连接数；用于 wait 不重复开页）',
+      run: () => service.panelPresence(),
+    },
+
+    {
+      // 等待生命周期事件流：SSE 端点（带 cwd/key 过滤），由 watchEvents 派生 waiting/reminder/resolved。
+      // action 标 stream:true → api.js 透传 req/res，run 自己接管响应不走 sendJson。
+      id: 'localtask.events',
+      cli: ['localtask', 'events'],
+      http: ['GET', '/api/localtasks/events'],
+      summary: '等待事件流：waiting 开始 / reminder 30s·10s / resolved delivered|timeout（SSE 长连接）',
+      flags: {
+        cwd: { type: 'string', hint: '工作目录过滤（与 --key 二选一）' },
+        key: { type: 'string', hint: '主题 key 过滤（与 --cwd 二选一）' },
+      },
+      stream: true,
+      run: (ctx) => service.streamEventsSSE(ctx.__raw.req, ctx.__raw.res, { cwd: ctx.cwd, key: ctx.key }),
+    },
   ],
 };

package/src/modules/localtask/service.js

@@ -24,11 +24,12 @@
 import http from 'node:http';
 import crypto from 'node:crypto';
 import fsp from 'node:fs/promises';
+import { spawn } from 'node:child_process';
 import { basename, dirname, join, resolve } from 'node:path';
-import { APP_DIR } from '../../core/paths.js';
+import { fileURLToPath } from 'node:url';
+import { APP_DIR, DEFAULT_PORT } from '../../core/paths.js';
 import { badInput } from '../../core/errors.js';
 import { openBrowser } from '../../core/open.js';
-import { renderPopupPage } from './popup.js';
 
 export const DEFAULT_TIMEOUT_MS = 180_000; // 阻塞默认 3 分钟（推荐值）
 const POLL_MS = 500; // 跨进程兜底轮询间隔
@@ -720,9 +721,16 @@ export async function waitForTask({
     return { status: 'ok', key, cwd, name, summary, task: withTaskSuffix(queued, suffix), queued: true };
   }
 
-  // 2. 没有 pending → 起内嵌弹窗服务器
-  const server = await startPopupServer(key, cwd, summary, tmo);
-  const addr = `http://127.0.0.1:${server.address().port}/`;
+  // 2. 没有 pending → 复用常驻主面板（不再起随机端口临时弹窗）：
+  //    a) 确保主面板在跑（不存在就 detached 拉起 serve --no-open --auto-exit）；
+  //    b) 探测活动 SSE 连接：有活标签就不开新页（避免 Edge 重复开标签）；
+  //                没活标签就 openBrowser 深链到当前主题。
+  //    失败只降级为纯阻塞——绝不抛错中断 wait。
+  //    --no-open 模式（冒烟/CI）不发起任何面板相关动作：不开浏览器、不拉起 serve、不开 SSE。
+  //    这样可避免在测试里 spawn 出一堆孤儿进程占着 7877 端口。
+  const panelInfo = open ? await ensureMainPanel() : { running: false, started: false, url: '' };
+  const presence = panelInfo.running ? await probePresence() : 0;
+  const deepLink = deepLinkUrl(key, cwd);
 
   // 3. 结果承诺：两个生产者（同进程 waiter / 跨进程轮询）+ 超时
   let resolveOutcome;
@@ -755,7 +763,7 @@ export async function waitForTask({
       .catch(() => {});
   }, POLL_MS);
 
-  // 登记「等待中」（含截止时刻与现状），面板/弹窗据此显示倒计时
+  // 登记「等待中」（含截止时刻与现状），面板据此显示倒计时
   await setWaiting(key, cwd, summary, true, new Date(Date.now() + tmo));
 
   // 登记之后再查一次关闭标记：setWaiting 刚清掉上一轮残留的标记，因此这里若有值
@@ -767,13 +775,32 @@ export async function waitForTask({
   // waiter/轮询就位后再回调，保证 onReady 里立刻回填也能被接住
   if (typeof onReady === 'function') {
     try {
-      await onReady({ addr, key, cwd, name, summary });
+      await onReady({ addr: deepLink, key, cwd, name, summary });
     } catch {
       /* 钩子异常不得影响 wait */
     }
   }
 
-  if (open) openBrowser(addr);
+  // 没活标签且主面板在跑 → 开浏览器深链（让用户能在面板里选中主题并响应等待事件）。
+  // 已有活标签 / --no-open / 主面板未启动 → 都不开（避免重复标签 + 冒烟/CI 兼容）。
+  const openPage = open && presence === 0 && panelInfo.running;
+  if (openPage) openBrowser(deepLink);
+
+  // 周期复查：等待期间每 5s 查一次活动标签；万一开始时判错（页面被关），20s 冷却内重开。
+  // 不到点不开新页（节流，避免「标签被关 → 立刻开 → 立刻关」抖动）。
+  const REVIEW_MS = 5_000;
+  const REOPEN_COOLDOWN_MS = 20_000;
+  let lastReopenAt = 0;
+  const review = setInterval(async () => {
+    if (!panelInfo.running || !open) return;
+    const n = await probePresence().catch(() => 0);
+    if (n > 0) return; // 有活标签，不动
+    const now = Date.now();
+    if (now - lastReopenAt < REOPEN_COOLDOWN_MS) return; // 冷却中
+    lastReopenAt = now;
+    openBrowser(deepLink);
+  }, REVIEW_MS);
+  review.unref?.();
 
   let result;
   try {
@@ -787,123 +814,14 @@ export async function waitForTask({
   } finally {
     clearInterval(poll);
     clearInterval(cancelPoll);
+    clearInterval(review);
     clearTimeout(timer);
     waiters.delete(key);
     await clearWaiting(key);
-    await stopServer(server);
   }
   return result;
 }
 
-// ─── 内嵌弹窗服务器 ─────────────────────────────────────────────────
-
-function sendJson(res, status, obj) {
-  res.writeHead(status, {
-    'content-type': 'application/json; charset=utf-8',
-    'cache-control': 'no-store',
-  });
-  res.end(JSON.stringify(obj));
-}
-
-function sendHtml(res, html) {
-  res.writeHead(200, {
-    'content-type': 'text/html; charset=utf-8',
-    'cache-control': 'no-store',
-  });
-  res.end(html);
-}
-
-async function readBody(req) {
-  const chunks = [];
-  let size = 0;
-  for await (const c of req) {
-    size += c.length;
-    if (size > 1024 * 1024) throw new Error('请求体过大');
-    chunks.push(c);
-  }
-  if (!chunks.length) return {};
-  return JSON.parse(Buffer.concat(chunks).toString('utf8'));
-}
-
-// 与主 api.js 同一套跨站防护：弹窗服务器虽只绑 127.0.0.1，浏览器里任意页面都能
-// 向它发请求，非本机来源一律挡。
-function originAllowed(req) {
-  const origin = req.headers.origin;
-  if (!origin) return true;
-  try {
-    const h = new URL(origin).hostname;
-    return h === '127.0.0.1' || h === 'localhost' || h === '::1';
-  } catch {
-    return false;
-  }
-}
-
-async function handlePopup(req, res, key, cwd, summary, timeoutMs) {
-  const url = new URL(req.url, 'http://127.0.0.1/');
-  const method = (req.method || 'GET').toUpperCase();
-
-  try {
-    if ((method === 'GET' || method === 'HEAD') && (url.pathname === '/' || url.pathname === '/index.html')) {
-      sendHtml(res, renderPopupPage({ key, cwd, summary, timeoutMs }));
-      return;
-    }
-
-    if (url.pathname === '/api/localtasks' && method === 'GET') {
-      sendJson(res, 200, { ok: true, data: await listTasks() });
-      return;
-    }
-
-    if (url.pathname === '/api/localtasks' && method === 'POST') {
-      if (!originAllowed(req)) {
-        sendJson(res, 403, { ok: false, error: '跨站请求被拒绝（弹窗仅接受本机来源）', code: 'BLOCKED' });
-        return;
-      }
-      const body = await readBody(req);
-      sendJson(res, 200, { ok: true, data: await addTask({ cwd, text: body.text }) });
-      return;
-    }
-
-    if (url.pathname === '/api/localtasks/item' && method === 'DELETE') {
-      if (!originAllowed(req)) {
-        sendJson(res, 403, { ok: false, error: '跨站请求被拒绝（弹窗仅接受本机来源）', code: 'BLOCKED' });
-      } else {
-        const body = await readBody(req);
-        sendJson(res, 200, { ok: true, data: await removeTask({ cwd, id: body.id }) });
-      }
-      return;
-    }
-
-    sendJson(res, 404, { ok: false, error: '不存在: ' + method + ' ' + url.pathname });
-  } catch (err) {
-    const code = err && err.code === 'INVALID_INPUT' ? 400 : err && err.code === 'NOT_FOUND' ? 404 : 500;
-    sendJson(res, code, { ok: false, error: String((err && err.message) || err), code: err.code || 'INTERNAL' });
-  }
-}
-
-function startPopupServer(key, cwd, summary, timeoutMs) {
-  const server = http.createServer((req, res) => handlePopup(req, res, key, cwd, summary, timeoutMs));
-  return new Promise((resolve_, reject) => {
-    server.once('error', reject);
-    server.listen(0, '127.0.0.1', () => resolve_(server));
-  });
-}
-
-function stopServer(server) {
-  return new Promise((resolve_) => {
-    const force = setTimeout(() => {
-      try {
-        server.closeAllConnections();
-      } catch {
-        /* Node 版本不支持则忽略，close 仍会兜底 */
-      }
-    }, 800);
-    server.close(() => {
-      clearTimeout(force);
-      resolve_();
-    });
-  });
-}
-
 // ─── 面板空闲自释放所需的观测接口（panel-guard.js 调用）────────────
 
 // 当前有多少主题「真的在等待」——常驻面板的空闲自释放据此否决退出：
@@ -974,3 +892,258 @@ export function addEventStreamConn(req, res) {
   res.on('close', cleanup);
   return conn;
 }
+
+// ─── 常驻主面板（固定端口）统一入口 ───────────────────────────────────
+
+// 「主面板就绪」=端口上有可响应的服务。
+// 这与 /api/ping 不同：ping 是面板壳层每 15s 主动上报「有页面开着」，
+// 这里只问「端口上有没有人接 HTTP」——用于决定是否要拉起 serve。
+async function probePanelReady(timeoutMs = 900) {
+  const url = `${panelBaseUrl()}/api/ping`;
+  return new Promise((resolve_) => {
+    const req = http.get(url, { timeout: timeoutMs }, (res) => {
+      res.resume();
+      resolve_(true);
+    });
+    req.on('timeout', () => {
+      req.destroy();
+      resolve_(false);
+    });
+    req.on('error', () => resolve_(false));
+  });
+}
+
+// 「活动 SSE 连接数」= 主面板上当前正打开的「实时任务」标签数。
+// 用于 wait 决策：已有活标签就不重开页面，让那个标签响铃/打角标/弹通知；
+// 没有活标签时再 openBrowser 新开深链标签。
+//
+// 任何失败/旧版无此端点都按 0 处理（保守地开一次页），绝不因探测失败而阻塞 wait。
+async function probePresence(timeoutMs = 900) {
+  const url = `${panelBaseUrl()}/api/localtasks/presence`;
+  return new Promise((resolve_) => {
+    const req = http.get(url, { timeout: timeoutMs }, (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (c) => {
+        body += c;
+      });
+      res.on('end', () => {
+        try {
+          const j = JSON.parse(body);
+          const d = j && typeof j === 'object' && j.data ? j.data : j;
+          resolve_(Math.max(0, Number(d && d.clients) || 0));
+        } catch {
+          resolve_(0);
+        }
+      });
+    });
+    req.on('timeout', () => {
+      req.destroy();
+      resolve_(0);
+    });
+    req.on('error', () => resolve_(0));
+  });
+}
+
+function panelBaseUrl() {
+  return `http://127.0.0.1:${DEFAULT_PORT}`;
+}
+
+// 深链到主面板「实时任务」页并选中当前主题（key 优先，cwd 兜底）。
+function deepLinkUrl(key, cwd) {
+  return `${panelBaseUrl()}/#/localtask?key=${encodeURIComponent(key)}&cwd=${encodeURIComponent(cwd)}`;
+}
+
+// 本仓库/已安装包的 CLI 入口（src/modules/localtask/ 上三级到包根）。
+function binCliPath() {
+  return fileURLToPath(new URL('../../../bin/cli.mjs', import.meta.url));
+}
+
+// 确保常驻主面板可用：已在运行直接复用；否则后台 detached 拉起一个独立
+// `nx-kv serve --no-open --auto-exit`（unref，不随 wait 退出而关闭），再轮询健康端点。
+// 失败只返回 running:false，绝不抛错——wait 仍可阻塞等待 CLI/轮询回填。
+//
+// --auto-exit：这个实例是**为等用户回填而临时拉起**的，用完就该让位——面板页全部关闭、
+// 又没有等待中的主题时自行退出（宽限期见 panel-guard.js）。下一次 wait 需要时会再拉起
+// （冷启动 <1s）。用户手动 `nx-kv serve` 的实例不带此标志，不会自己跑掉。
+async function ensureMainPanel() {
+  const url = panelBaseUrl() + '/';
+  if (await probePanelReady()) return { running: true, started: false, url };
+
+  try {
+    const child = spawn(process.execPath, [binCliPath(), 'serve', '--no-open', '--auto-exit'], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    child.on('error', () => {
+      /* 见轮询兜底 */
+    });
+    child.unref();
+  } catch {
+    return { running: false, started: false, url };
+  }
+
+  const deadline = Date.now() + 15_000;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 200));
+    if (await probePanelReady(700)) return { running: true, started: true, url };
+  }
+  return { running: false, started: true, url };
+}
+
+// ─── 等待生命周期事件流（主面板及时通知，避免用户漏过超时）────────────
+//
+// wait 与常驻主面板通常是两个进程，内存 EventEmitter 跨不过进程，所以事件流
+// 不依赖进程内回调，而是轮询 store，从 waiting/waitingUntil 与「已领取数」的变化里
+// 派生事件：waiting / reminder（剩余 30s、10s）/ resolved（delivered 或 timeout）。
+// HTTP(SSE) 与 CLI(NDJSON) 共用本生成器。
+
+const EVENT_POLL_MS = 500;
+const REMINDER_SEC = [30, 10]; // 剩余 ≤30s、≤10s 各提醒一次
+
+// 纯函数：给定剩余秒数与已提醒过的阈值，返回本次应触发的阈值（秒）。便于单测。
+export function remindersDue(remainSec, firedSet) {
+  const out = [];
+  for (const sec of REMINDER_SEC) {
+    if (remainSec <= sec && remainSec > 0 && !firedSet.has(sec)) out.push(sec);
+  }
+  return out;
+}
+
+function consumedCount(t) {
+  return (Array.isArray(t.tasks) ? t.tasks : []).filter((x) => x.status === 'consumed').length;
+}
+
+/**
+ * 订阅等待生命周期事件（异步生成器）。
+ * @param {{cwd?:string,key?:string,pollMs?:number,signal?:AbortSignal}} opts
+ *   不传 cwd/key 则订阅全部主题（主面板总览需要）。
+ */
+export async function* watchEvents({ cwd: rawCwd, key: rawKey, pollMs = EVENT_POLL_MS, signal } = {}) {
+  let onlyKey = null;
+  if (rawKey && String(rawKey).trim()) onlyKey = String(rawKey).trim();
+  else if (rawCwd && String(rawCwd).trim()) onlyKey = normalizeCwd(rawCwd).key;
+
+  const sleep = (ms) =>
+    new Promise((res) => {
+      const to = setTimeout(res, ms);
+      if (signal) {
+        signal.addEventListener(
+          'abort',
+          () => {
+            clearTimeout(to);
+            res();
+          },
+          { once: true }
+        );
+      }
+    });
+
+  const state = new Map();
+  let first = true;
+  while (!(signal && signal.aborted)) {
+    let topics = [];
+    try {
+      const store = await loadStore();
+      topics = Object.values(store.topics).filter(
+        (t) => Array.isArray(t.tasks) && (!onlyKey || t.key === onlyKey)
+      );
+    } catch {
+      topics = [];
+    }
+
+    const now = Date.now();
+    for (const t of topics) {
+      const deadline = parseStampMs(t.waitingUntil);
+      const isWaiting = !!t.waiting && Number.isFinite(deadline) && deadline > now;
+      let st = state.get(t.key);
+
+      if (isWaiting) {
+        if (!st || st.phase !== 'waiting' || st.waitingUntil !== t.waitingUntil) {
+          st = {
+            phase: 'waiting',
+            waitingUntil: t.waitingUntil,
+            deadline,
+            consumed0: consumedCount(t),
+            reminders: new Set(),
+          };
+          state.set(t.key, st);
+          yield {
+            type: 'waiting',
+            key: t.key,
+            cwd: t.cwd || '',
+            name: t.name || '',
+            summary: t.summary || '',
+            waitingUntil: t.waitingUntil,
+            remainMs: Math.max(0, deadline - now),
+            replay: first,
+          };
+        }
+        const remainSec = Math.floor((st.deadline - now) / 1000);
+        for (const sec of remindersDue(remainSec, st.reminders)) {
+          st.reminders.add(sec);
+          yield {
+            type: 'reminder',
+            key: t.key,
+            cwd: t.cwd || '',
+            name: t.name || '',
+            summary: t.summary || '',
+            waitingUntil: t.waitingUntil,
+            remainSec: sec,
+            remainMs: Math.max(0, st.deadline - now),
+            label: `${sec}s`,
+          };
+        }
+      } else if (st && st.phase === 'waiting') {
+        const outcome = consumedCount(t) > st.consumed0 ? 'delivered' : 'timeout';
+        state.set(t.key, { phase: 'ended' });
+        yield { type: 'resolved', key: t.key, cwd: t.cwd || '', name: t.name || '', outcome };
+      } else if (!st) {
+        state.set(t.key, { phase: 'idle' });
+      }
+
+      // 兜底：waiting 标志还在但截止已过（wait 进程异常退出），也派生一次 timeout
+      if (t.waiting && (!Number.isFinite(deadline) || deadline <= now)) {
+        const cur = state.get(t.key);
+        if (!cur || cur.phase === 'waiting') {
+          state.set(t.key, { phase: 'ended' });
+          yield {
+            type: 'resolved',
+            key: t.key,
+            cwd: t.cwd || '',
+            name: t.name || '',
+            outcome: 'timeout',
+            stale: true,
+          };
+        }
+      }
+    }
+
+    first = false;
+    await sleep(pollMs);
+  }
+}
+
+// HTTP 传输：SSE。注册到 sseConns 让 panelPresence 计入（wait 据此判活标签）。
+// 客户端断开即中止生成器。SSE 心跳由 addEventStreamConn 统一管。
+export async function streamEventsSSE(req, res, { cwd, key } = {}) {
+  res.writeHead(200, {
+    'content-type': 'text/event-stream; charset=utf-8',
+    'cache-control': 'no-store',
+    connection: 'keep-alive',
+  });
+  res.write(': connected\n\n');
+  // addEventStreamConn 内部已把 conn 加入 sseConns（panelPresence 据此统计活标签），
+  // 我们不再直接引用——心跳 / 失败剔除 / 断开清理都由它托管。
+  addEventStreamConn(req, res);
+  const ac = new AbortController();
+  req.on('close', () => ac.abort());
+  try {
+    for await (const ev of watchEvents({ cwd, key, signal: ac.signal })) {
+      res.write(`event: ${ev.type}\ndata: ${JSON.stringify(ev)}\n\n`);
+    }
+  } catch {
+    /* 客户端断开 / 瞬时读盘错误，静默结束 */
+  }
+}