nx-kv 0.8.3 → 0.8.4

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 本文件记录对外可见的变更。格式参考 [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

package/package.json

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

package/src/modules/localtask/index.js

@@ -282,5 +282,20 @@ export default {
       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

@@ -991,3 +991,159 @@ async function ensureMainPanel() {
   }
   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 {
+    /* 客户端断开 / 瞬时读盘错误，静默结束 */
+  }
+}

package/src/modules/localtask/view.jsx

@@ -54,6 +54,11 @@ export default function SessionTaskView() {
   const [suffixEditing, setSuffixEditing] = useState(false);
   const [suffixDraft, setSuffixDraft] = useState('');
   const [suffixSaving, setSuffixSaving] = useState(false);
+  // 探活状态：'connecting' | 'ok' | 'reconnecting'（数据轮询 + 后续 SSE 接入）
+  const [liveStatus, setLiveStatus] = useState('connecting');
+  // 「只读弹窗」：点击现状/上一轮总结/任务文本时显示聚焦阅读的模态框
+  // modal = { title, body } | null
+  const [modal, setModal] = useState(null);
   const [editingId, setEditingId] = useState(null);
   const [editText, setEditText] = useState('');
   const [editSaving, setEditSaving] = useState(false);
@@ -69,11 +74,14 @@ export default function SessionTaskView() {
 
   const load = useCallback(async () => {
     try {
-      setOverview(await api('/api/localtasks'));
-    } catch (e) {
-      toast(e.message);
+      const data = await api('/api/localtasks');
+      setOverview(data);
+      setLiveStatus('ok');
+    } catch {
+      // 轮询失败 → 进入「重连中」态；指示灯变红，避免每 1.5s 弹错误 toast
+      setLiveStatus('reconnecting');
     }
-  }, [toast]);
+  }, []);
 
   useEffect(() => {
     load();
@@ -85,6 +93,16 @@ export default function SessionTaskView() {
     return () => clearInterval(t);
   }, [load]);
 
+  // 只读弹窗：按 Esc 关闭
+  useEffect(() => {
+    if (!modal) return;
+    const onKey = (e) => {
+      if (e.key === 'Escape') setModal(null);
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [modal]);
+
   const topics = overview ? overview.topics : [];
 
   // 同步页面上的超时配置（来源：后端 settings）
@@ -495,7 +513,35 @@ export default function SessionTaskView() {
           style={{ margin: 0 }}
         />
         <h3>主题总览（按工作目录）</h3>
-        <span className="muted">{overview ? `${topics.length} 个 · 等待中 ${overview.waiting}` : ''}</span>
+        <span
+          className="muted"
+          style={{
+            fontSize: 11,
+            display: 'inline-flex',
+            alignItems: 'center',
+            gap: 4,
+            color: liveStatus === 'ok' ? '#2a9d5c' : liveStatus === 'reconnecting' ? '#c0392b' : '#888',
+          }}
+          title={
+            liveStatus === 'ok'
+              ? '实时连接正常（数据轮询可达后端）'
+              : liveStatus === 'reconnecting'
+              ? '连接断开，正在重连…'
+              : '正在连接…'
+          }
+        >
+          <span
+            style={{
+              display: 'inline-block',
+              width: 8,
+              height: 8,
+              borderRadius: '50%',
+              background: liveStatus === 'ok' ? '#2a9d5c' : liveStatus === 'reconnecting' ? '#c0392b' : '#aaa',
+            }}
+          />
+          {liveStatus === 'ok' ? '实时连接正常' : liveStatus === 'reconnecting' ? '连接断开，正在重连…' : '正在连接…'}
+        </span>
+        <span className="muted">{overview ? ` · ${topics.length} 个 · 等待中 ${overview.waiting}` : ''}</span>
         <span style={{ marginLeft: 'auto', display: 'flex', gap: 8 }}>
           <button
             className="btn small ghost"
@@ -557,7 +603,12 @@ export default function SessionTaskView() {
                   </div>
                 </div>
                 {t.summary && (
-                  <div className="muted" style={{ fontSize: 11, whiteSpace: 'pre-wrap', marginBottom: 6 }}>
+                  <div
+                    className="muted"
+                    style={{ fontSize: 11, whiteSpace: 'pre-wrap', marginBottom: 6, cursor: 'zoom-in' }}
+                    title="点击查看完整现状"
+                    onClick={(e) => { e.stopPropagation(); setModal({ title: `主题「${t.name}」现状`, body: t.summary }); }}
+                  >
                     现状：{t.summary}
                   </div>
                 )}
@@ -712,12 +763,22 @@ export default function SessionTaskView() {
                           </>
                         ) : (
                           <>
-                            {t.text}
+                            <span
+                              style={{ cursor: t.text.length > 50 ? 'zoom-in' : 'default' }}
+                              onClick={(e) => {
+                                e.stopPropagation();
+                                if (t.text.length > 50) setModal({ title: `任务 #${t.id} 全文`, body: t.text });
+                              }}
+                              title={t.text.length > 50 ? '点击查看完整任务文本' : undefined}
+                            >
+                              {t.text}
+                            </span>
                             {t.roundSummary && (
                               <div
                                 className="muted"
-                                style={{ fontSize: 11, marginTop: 4, paddingTop: 4, borderTop: '1px dashed var(--line,#e6e8eb)', whiteSpace: 'pre-wrap' }}
-                                title="该任务所回应的 agent 上一轮完成总结"
+                                style={{ fontSize: 11, marginTop: 4, paddingTop: 4, borderTop: '1px dashed var(--line,#e6e8eb)', whiteSpace: 'pre-wrap', cursor: 'zoom-in' }}
+                                title="点击查看完整上一轮总结"
+                                onClick={(e) => { e.stopPropagation(); setModal({ title: '上一轮完成总结', body: t.roundSummary }); }}
                               >
                                 上一轮完成：{t.roundSummary}
                               </div>
@@ -777,6 +838,38 @@ export default function SessionTaskView() {
       )}
 
       <CliHints module="localtask" />
+
+      {modal && (
+        <div
+          onClick={() => setModal(null)}
+          style={{
+            position: 'fixed', inset: 0, background: 'rgba(0,0,0,0.4)',
+            display: 'flex', alignItems: 'center', justifyContent: 'center', zIndex: 1000,
+          }}
+        >
+          <div
+            onClick={(e) => e.stopPropagation()}
+            style={{
+              background: '#fff', borderRadius: 8, padding: 20, maxWidth: 'min(720px, 90vw)',
+              maxHeight: '80vh', overflow: 'auto', boxShadow: '0 12px 40px rgba(0,0,0,0.25)',
+            }}
+          >
+            <div style={{ display: 'flex', alignItems: 'center', marginBottom: 12 }}>
+              <strong style={{ fontSize: 14 }}>{modal.title}</strong>
+              <button
+                className="btn small ghost"
+                onClick={() => setModal(null)}
+                style={{ marginLeft: 'auto' }}
+              >
+                关闭
+              </button>
+            </div>
+            <div style={{ fontSize: 13, lineHeight: 1.6, whiteSpace: 'pre-wrap', wordBreak: 'break-word' }}>
+              {modal.body}
+            </div>
+          </div>
+        </div>
+      )}
     </>
   );
 }

package/src/runtime/api.js

@@ -92,6 +92,11 @@ export async function handleApi(req, res, url) {
       } else {
         Object.assign(raw, await readBody(req).catch(() => ({})));
       }
+      // stream 模式：把 req/res/url 透传给 run，让 action 自己接管响应（SSE 等）
+      if (action.stream) {
+        await action.run({ ...applySpec(action, raw), __raw: { req, res, url } }, { transport: 'http' });
+        return;
+      }
       const data = await action.run(applySpec(action, raw), { transport: 'http' });
       sendJson(res, 200, { ok: true, data });
     } catch (err) {

package/src/web/public/assets/{CliHints-DNK3TaU5.js → CliHints-D70_R4vQ.js}

@@ -1 +1 @@
-import{o as e,s as t,t as n}from"./index-Iz1qH6TC.js";var r=t();function i({module:t}){let{boot:i}=e(),a=(i?.commands||[]).filter(e=>e.module===t);return a.length?(0,r.jsxs)(`div`,{className:`cli-hint`,children:[(0,r.jsx)(`span`,{className:`cli-hint-label`,children:`CLI 等价（同构命令，加 --json 得机器可读输出）：`}),a.map(e=>(0,r.jsx)(n,{className:`cli-cmd`,text:e.command,title:`点击复制：${e.usage}`,children:e.command},e.id))]}):null}export{i as t};
+import{o as e,s as t,t as n}from"./index-2OK9SG2y.js";var r=t();function i({module:t}){let{boot:i}=e(),a=(i?.commands||[]).filter(e=>e.module===t);return a.length?(0,r.jsxs)(`div`,{className:`cli-hint`,children:[(0,r.jsx)(`span`,{className:`cli-hint-label`,children:`CLI 等价（同构命令，加 --json 得机器可读输出）：`}),a.map(e=>(0,r.jsx)(n,{className:`cli-cmd`,text:e.command,title:`点击复制：${e.usage}`,children:e.command},e.id))]}):null}export{i as t};