@gavinc-cn/touchstone-dsh 0.2.0 → 0.3.0

package/backend/lib/sse.js

@@ -0,0 +1,207 @@
+/**
+ * SSE 消费（`dshdriver._stream_events` 的 Node 对应物）：会话事件流与全局状态流共用。
+ *
+ * 为什么要单独一层：两版后端都要订阅 dsh 插件的事件流（`/events?scope=session|state`），
+ * 而这一层的**坑全在收尾与超时**上（Python 侧踩过）：SocketIO 读超时会永久毒化连接、
+ * `read(n)` 对 chunked 响应会攒够 n 字节才返回（长连 SSE 下等于永不返回）。Node 侧对应的是
+ * `fetch` + `ReadableStream` 读取 + 空闲计时器 + AbortController 主动断开。
+ *
+ * 契约（与 Python `_stream_events` 逐条对齐）：
+ *   - 帧 = `data:` 行里的 JSON（`dshdriver.parse_stream_line`）；注释/空行/其他字段忽略；
+ *   - 非 200 ⇒ 抛 `SseError(status, '事件流被拒: …')`（正文取前 200 字，便于排障）；
+ *   - **空闲超时**：`idleTimeoutMs` 内没有任何字节（含 keepalive 注释）⇒ `SseError(-2, '事件流空闲超时…')`
+ *     —— 任一 chunk（哪怕只是注释）都会重置计时；
+ *   - **对端关闭**：流 EOF 且未请求停止 ⇒ `SseError(-2, '事件流被对端关闭')`；
+ *   - **主动断开不算异常**：`stop()` 返回真（或 `signal` 被 abort）⇒ 正常返回，`stopped=true`；
+ *   - 返回 `{frames, lastSeq, stopped}`，`lastSeq` 是见过的最大 `seq`（重连时传回去续传）。
+ */
+/** 驱动侧链路错误（与 Python `DshDriverError` 同形：`code` + 中文消息） */
+export class SseError extends Error {
+  /**
+   * @param {number} code 0=HTTP 状态异常；-1=未配置；-2=链路问题（超时/被关）
+   * @param {string} message
+   */
+  constructor(code, message) {
+    super(message);
+    this.name = 'SseError';
+    this.code = code;
+  }
+}
+
+/** 停止轮询间隔（对齐 Python `dshdriver.STOP_WATCH_INTERVAL=0.25s`） */
+export const STOP_WATCH_INTERVAL_MS = 250;
+
+/**
+ * 把一行 SSE 文本解析成帧；注释/空行/非 data 行返回 null（对齐 `parse_stream_line`）。
+ * @param {string} line
+ * @returns {object|null}
+ */
+export function parseStreamLine(line) {
+  if (typeof line !== 'string' || !line.startsWith('data:')) return null;
+  try {
+    const value = JSON.parse(line.slice('data:'.length).trim());
+    return value !== null && typeof value === 'object' ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 解析一个 `\n\n` 分隔的 SSE 块 → 帧数组（Python 是逐行解析，故一个块可能出多帧）。
+ * @param {string} block
+ * @returns {object[]}
+ */
+export function parseSseBlock(block) {
+  const frames = [];
+  for (const line of String(block).split('\n')) {
+    const frame = parseStreamLine(line.trim());
+    if (frame !== null) frames.push(frame);
+  }
+  return frames;
+}
+
+/**
+ * 订阅一个 SSE 流直到：`stop()` 为真 / `signal` 被 abort / 对端关闭 / 空闲超时。
+ *
+ * @param {string} url 完整 URL（含 query，调用方负责拼 `since`/`scope`）
+ * @param {object} [opts]
+ * @param {object} [opts.headers] 附加请求头（驱动 token 等）
+ * @param {number} [opts.since] 起始 seq（只用于统计；补发由服务端按 query 处理）
+ * @param {(frame: object) => void} [opts.onFrame] 每帧回调
+ * @param {() => boolean} [opts.stop] 主动停止探测（每 250ms 查一次）
+ * @param {AbortSignal} [opts.signal] 外部取消信号（与 stop 等价）
+ * @param {number} [opts.idleTimeoutMs] 空闲超时（缺省 90s，对齐 `STREAM_IDLE_TIMEOUT`）
+ * @param {typeof fetch} [opts.fetchImpl] 注入用（测试）
+ * @returns {Promise<{frames:number,lastSeq:number,stopped:boolean}>}
+ */
+export async function streamEvents(url, {
+  headers = {},
+  since = 0,
+  onFrame,
+  stop,
+  signal,
+  idleTimeoutMs = 90000,
+  fetchImpl = fetch,
+} = {}) {
+  const controller = new AbortController();
+  let lastSeq = Number.isInteger(since) ? since : 0;
+  let frames = 0;
+  let stopped = false;
+  let idleTimer = null;
+  // `stop()` 按**真值**判定（对齐 Python `if stop is not None and stop():`）：只认 `=== true`
+  // 会把 `() => 1` 这类真值回调误判成「未停止」，长寿命订阅下永不收尾。
+  const stopWanted = () => (typeof stop === 'function' && Boolean(stop()))
+    || (signal !== undefined && signal.aborted === true);
+  const armIdle = () => {
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => controller.abort(new SseError(-2,
+      `事件流空闲超时（>${Math.round(idleTimeoutMs / 1000)}s 无数据）`)), idleTimeoutMs);
+    if (idleTimer.unref) idleTimer.unref();
+  };
+  // 主动停止探测：fetch 的 body reader 阻塞时不响应外部状态，只能旁路轮询 + abort
+  const watcher = setInterval(() => {
+    if (stopWanted()) {
+      stopped = true;
+      controller.abort(new SseError(0, 'stopped'));
+    }
+  }, STOP_WATCH_INTERVAL_MS);
+  if (watcher.unref) watcher.unref();
+  // 外部取消信号：监听器必须成对摘除（`signal` 往往是长寿命对象——平台侧复用它做整体收尾，
+  // 每轮重连都挂一个监听器会在它上面线性堆积 ⇒ 内存与误触发风险）
+  const onAbort = () => {
+    stopped = true;
+    controller.abort(new SseError(0, 'aborted'));
+  };
+  if (signal) signal.addEventListener('abort', onAbort, { once: true });
+
+  let response;
+  let reader = null;
+  try {
+    armIdle();
+    try {
+      response = await fetchImpl(url, {
+        method: 'GET',
+        headers: { accept: 'text/event-stream', ...headers },
+        signal: controller.signal,
+      });
+    } catch (error) {
+      // 连接/响应头阶段被 abort 时 fetch 抛的是 AbortError。**先判主动停止**（那不是异常），
+      // 再把「我们自己塞进去的 SseError」还原出来（如空闲超时），最后才当链路失败。
+      if (stopped || stopWanted()) return { frames, lastSeq, stopped: true };
+      const reason = controller.signal.reason;
+      if (reason instanceof SseError) throw reason;
+      throw new SseError(-2, `事件流连接失败: ${(error && error.message) || error}`);
+    }
+    if (response.status !== 200) {
+      const detail = await response.text().catch(() => '');
+      throw new SseError(response.status, `事件流被拒: ${detail.slice(0, 200)}`);
+    }
+    reader = response.body.getReader();
+    const decoder = new TextDecoder('utf-8');
+    let buffer = '';
+    for (;;) {
+      armIdle();
+      let chunk;
+      try {
+        chunk = await reader.read();
+      } catch (error) {
+        // abort 唤醒的读会以 AbortError 形式回来：主动断开不算链路异常
+        if (stopped || stopWanted()) { stopped = true; break; }
+        const reason = controller.signal.reason;
+        if (reason instanceof SseError) throw reason;
+        throw new SseError(-2, `事件流读取失败: ${(error && error.message) || error}`);
+      }
+      if (chunk.done) {
+        if (stopped || stopWanted()) { stopped = true; break; }
+        throw new SseError(-2, '事件流被对端关闭');
+      }
+      buffer += decoder.decode(chunk.value, { stream: true });
+      while (buffer.includes('\n\n')) {
+        const idx = buffer.indexOf('\n\n');
+        const block = buffer.slice(0, idx);
+        buffer = buffer.slice(idx + 2);
+        for (const frame of parseSseBlock(block)) {
+          frames += 1;
+          if (Number.isInteger(frame.seq) && frame.seq > lastSeq) lastSeq = frame.seq;
+          if (typeof onFrame === 'function') {
+            try {
+              onFrame(frame);
+            } catch {
+              // 回调抛异常不影响订阅循环（对齐 Python feed_into 的 on_frame 容错）
+            }
+          }
+        }
+      }
+    }
+  } finally {
+    if (idleTimer) clearTimeout(idleTimer);
+    clearInterval(watcher);
+    if (signal) signal.removeEventListener('abort', onAbort);
+    // 收尾顺序与实测口径（评审 2026-10-11 复核）：
+    //   ① `reader.cancel()` 让读取端立即放弃（不 cancel 也不会长期泄漏——实测 5 轮「连上→stop」
+    //      后服务端打开 socket 数都是 0，真正兜底的是 ② 的 abort；但显式 cancel 能让
+    //      HTTP 层尽早复用/关闭连接，且避免 reader 挂着 pending read）；
+    //   ② `controller.abort()` 才是**保证**连接释放的那一步（fetch 的 socket 归它管）。
+    //      ⚠ 不要写成「不 cancel 会挂到 GC 才释放」——那是过度声称，实测不成立。
+    if (reader) {
+      try {
+        await reader.cancel();
+      } catch { /* 已关闭/已取消：忽略 */ }
+    }
+    try {
+      controller.abort();
+    } catch { /* 已 abort：忽略 */ }
+  }
+  return { frames, lastSeq, stopped };
+}
+
+/** 小工具：把 base + path + query 拼成 URL（对齐 Python 的 `f"{base}/events?{query}"`） */
+export function sseUrl(base, pathName, query = {}) {
+  const usp = new URLSearchParams();
+  for (const [k, v] of Object.entries(query)) {
+    if (v === undefined || v === null || v === '') continue;
+    usp.append(k, String(v));
+  }
+  const qs = usp.toString();
+  return `${String(base).replace(/\/$/, '')}${pathName}${qs ? `?${qs}` : ''}`;
+}

package/backend/lib/static.js

@@ -0,0 +1,84 @@
+/**
+ * 静态托管 + SPA 全路由回退（Node 后端的 `server.py:_serve_static()` / `_send_file()`）。
+ *
+ * 为什么逐条对齐 Python：前端 `webui/dist-plugin` 两版共用同一份产物，它是契约测试本身
+ * （方案 §3.5）——静态语义差一点，SPA 的深链、资源 404 与 MIME 就会在 Node 版下变异。
+ * 语义（照抄 Python）：
+ *   ① 空相对路径 ⇒ index.html；
+ *   ② normpath 后逃出 WEB_DIR ⇒ 403 `forbidden`（text/plain）；
+ *   ③ 目录**或文件不存在** ⇒ 回退 index.html（这就是 SPA 回退，`/app`、`/haha.js` 都走它）；
+ *   ④ 扩展名 → MIME 表（未知 = application/octet-stream）；⑤ 读不到文件 ⇒ 404 `not found`。
+ * 路径不做百分号解码：Python 侧 `self.path` 也不解码，`%2e%2e` 在两个实现里同样不构成越界。
+ */
+import { statSync } from 'node:fs';
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+import { respond } from './http.js';
+
+/** 扩展名 → MIME。表抄自 `server.py:_serve_static()`。 */
+export function mimeFor(ext) {
+  const table = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'application/javascript; charset=utf-8',
+    '.mjs': 'application/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.json': 'application/json; charset=utf-8',
+    '.map': 'application/json; charset=utf-8',
+  };
+  return table[String(ext).toLowerCase()] || 'application/octet-stream';
+}
+
+/**
+ * 静态路径解析（`_serve_static` 的解析段，不含 IO）。
+ * 返回 `{ forbidden: true }` 或 `{ file, contentType }`。
+ * 用同步 stat 是有意的：解析段要在路由分派里同步决定「转发给静态还是回退」，
+ * 一次本地 stat 的代价远小于把它拆成异步状态机。
+ */
+export function resolveStaticPath(webDir, urlPath) {
+  const base = path.resolve(webDir);
+  const rel = String(urlPath || '').replace(/^\/+/, '') || 'index.html';
+  const full = path.normalize(path.join(base, rel));
+  if (full !== base && !full.startsWith(base + path.sep)) return { forbidden: true };
+  const index = path.join(base, 'index.html');
+  let target = full;
+  try {
+    if (!statSync(full).isFile()) target = index;
+  } catch {
+    target = index;
+  }
+  return { file: target, contentType: mimeFor(path.extname(target)) };
+}
+
+/**
+ * 服务一个静态请求：越界 → 403，命中 → 200 + MIME，解析到的目标读不到 → 404。
+ * （`_send_file` 的 OSError 分支＝文件在解析与读取之间消失，Node 侧同样兜住。）
+ */
+export async function serveStatic(res, webDir, urlPath) {
+  const resolved = resolveStaticPath(webDir, urlPath);
+  if (resolved.forbidden) {
+    respond(res, 403, 'forbidden', 'text/plain; charset=utf-8');
+    return;
+  }
+  try {
+    const data = await readFile(resolved.file);
+    respond(res, 200, data, resolved.contentType);
+  } catch {
+    respond(res, 404, 'not found', 'text/plain; charset=utf-8');
+  }
+}
+
+/** WEB_DIR 是否就绪（index.html 在不在）：启动期校验，别把错误留到首个请求 */
+export async function webDirReady(webDir) {
+  try {
+    return (await stat(path.join(webDir, 'index.html'))).isFile();
+  } catch {
+    return false;
+  }
+}

package/backend/lib/taskjson.js

@@ -0,0 +1,302 @@
+/**
+ * 任务族派生逻辑（`server.py:_task_json` / `_session_title` + `runner.py:read_dialogue` /
+ * `read_log_tail` 的 Node 对应物，M3 读路径）。
+ *
+ * 为什么单独一层：`_task_json` 有 29 个字段，其中三个是**派生**的 —— `new_cases` 要走案例库
+ * 扫描（StateCache）、`model` 走 `effectiveModel`、`session_title` 走 dsh 会话存储；日志端点
+ * 还要把轮次日志解析成对话条目。这些都不属于「鉴权/取数/回响应」的路由职责，单独放一层才能
+ * 脱离 HTTP 单测（`backend/test/tasks-route.test.mjs` 直接喂行对象/日志文件）。
+ *
+ * 归属说明：`read_dialogue` / `read_log_tail` 在 Python 里住在 `runner.py`；Node 侧 B 族的
+ * `lib/runner.js` 目前只有队列读函数（M3 只搬了看板/队列需要的那些）。任务族不能因此停摆，
+ * 故这两个函数落在这里，**并在文件头显式记录**：若 B 族把 runner 的两个日志读函数收编过去，
+ * 本文件应改为复用，避免两份实现。
+ *
+ * 逐点对齐的细节（都是「看着一样其实不一样」的坑）：
+ *   - 日志行切分是 Python **文本模式 universal newlines**（`readlines()` 把 `\r`/`\r\n` 也算换行）
+ *     ⇒ 复用 `lib.js:readText()`（已做归一），不是 `split('\n')` 硬切；
+ *   - `read_log_tail(path, limit)` 的 `limit` 走 Python 切片语义 `[-limit:]`：`0` = 全文、
+ *     负数 = 丢掉开头 |limit| 行（实测探针确认）；
+ *   - `### PROMPT ` 后面的内容按 JSON 解析，解析失败**保留原文**（不是跳过该行）；
+ *   - 工具结果按 6000 **码点**截断（Python `len`/切片按码点；JS 的 UTF-16 长度会把 emoji 算两个，
+ *     截断还可能劈开代理对 ⇒ 用 `Array.from` 按码点切）；
+ *   - `x or default` 用 Python 真值集合（`[]`/`{}` 是假值，JS 里是真值）⇒ 见 `pyOr`。
+ *
+ * 已知有意放宽（只影响**坏日志/坏行**，正常库不出现；比 Python 更稳）：
+ *   Python 在 `obj["tool_calls"][i]["function"]` 不是 dict 时抛 AttributeError，会把整个
+ *   `/dialogue` 打成 500（连接被关）。Node 侧按「缺字段取默认」降级继续 —— 一行坏日志不该让
+ *   整个对话流不可读。这类差异在正常 fixture 上不可见。
+ */
+import { agentFamily } from './agents.js';
+import { getProject } from './db.js';
+import { isFile, readText } from './lib.js';
+import { dsh_title as dshTitle } from './sessparse.js';
+import { effectiveModel, sessFamily } from './servercaps.js';
+
+/** 工具结果/助手摘要单条可返回的最大码点数（对齐 `runner.DIALOGUE_TEXT_LIMIT`） */
+export const DIALOGUE_TEXT_LIMIT = 6000;
+/**
+ * 单条对话条目中 JSON 内容「按长度直接截断」时保留的码点数（对齐 `runner.DIALOGUE_RAW_LIMIT`）。
+ * M3 的六个读端点用不到它；它属于 `runner.summary_entry_text()`（前端折叠摘要）——那一处随
+ * 会话/看板族移植时用这个常量，别在调用点写死 1200。
+ */
+export const DIALOGUE_RAW_LIMIT = 1200;
+
+/**
+ * Python `d.get(key, fallback)`：键**存在**就取键值（哪怕值是 null），否则取默认。
+ * 不能用 `obj[key] ?? fallback`（那会把显式 null 也折成默认）。
+ * @param {object} obj
+ * @param {string} key
+ * @param {any} fallback
+ * @returns {any}
+ */
+function pyGet(obj, key, fallback) {
+  return Object.prototype.hasOwnProperty.call(obj, key) ? obj[key] : fallback;
+}
+
+/**
+ * Python `value or fallback` 的真值口径：`None/False/0/''/[]/{}` 都是假值。
+ * JS 里 `[]` 与 `{}` 是真值，直接写 `||` 会在「空数组内容」上分叉。
+ * @param {any} value
+ * @param {any} fallback
+ * @returns {any}
+ */
+function pyOr(value, fallback) {
+  if (value === null || value === undefined || value === false || value === '' || value === 0) {
+    return fallback;
+  }
+  if (Array.isArray(value) && value.length === 0) return fallback;
+  if (typeof value === 'object' && Object.keys(value).length === 0) return fallback;
+  return value;
+}
+
+/**
+ * Python `len(s)` / `s[:limit]` 的**码点**口径（JS 按 UTF-16 码元会把代理对算成 2 个）。
+ * @param {any} value 字符串或数组（Python 的 str/list 都可切片）
+ * @param {number} limit
+ * @returns {{length: number, sliced: any}}
+ */
+function pySlice(value, limit) {
+  if (Array.isArray(value)) return { length: value.length, sliced: value.slice(0, limit) };
+  const chars = Array.from(String(value));
+  return { length: chars.length, sliced: chars.slice(0, limit).join('') };
+}
+
+/**
+ * Python `f.readlines()` 的等价：按 `\n` 切分，**每行带结尾换行**，且结尾换行不产生额外空行。
+ *
+ * 为什么不能用 `text.split('\n')`：文件以换行结尾时它会多出一个 `''` 元素，
+ * `[-limit:]` 的窗口就整体错一位（实测：`tail=5` 少回一行 —— 对拍里是正文哈希差异）。
+ * @param {string} text 已归一换行的文本（见 `lib.js:readText`）
+ * @returns {string[]}
+ */
+function pyReadLines(text) {
+  const lines = [];
+  let start = 0;
+  for (;;) {
+    const idx = text.indexOf('\n', start);
+    if (idx < 0) break;
+    lines.push(text.slice(start, idx + 1));      // 行尾换行跟着行走（同 Python readlines）
+    start = idx + 1;
+  }
+  if (start < text.length) lines.push(text.slice(start));   // 末行无换行
+  return lines;
+}
+
+/**
+ * `runner.read_dialogue(rounds)`：把多轮日志解析成结构化对话条目。
+ *
+ * 识别内容（与 Python 逐条对应）：
+ *   - `### PROMPT <json>` → `{kind:'user'}`（JSON 解析失败则原样当文本）
+ *   - `{"role":"assistant"}` → `{kind:'assistant', text, tool_calls:[{name,args}]}`
+ *   - `{"role":"tool"}` → `{kind:'tool_result', tool_call_id, text(截断), truncated, tool_calls:[]}`
+ *   - `{"role":"meta","type":"session.resume_hint"}` → `{kind:'meta', text: session_id}`
+ *
+ * @param {object[]} rounds `db.list_rounds()` 的行（按 round_no 升序；本函数再按 round_no 排一次，
+ *   与 Python 的 `sorted(rounds, key=...)` 同形 —— JS 的 `sort` 默认按字符串比，必须给数值比较器）
+ * @returns {object[]} 条目数组，按日志出现顺序
+ */
+export function readDialogue(rounds) {
+  const entries = [];
+  const ordered = [...rounds].sort((a, b) => (
+    a.round_no < b.round_no ? -1 : a.round_no > b.round_no ? 1 : 0));
+  for (const round of ordered) {
+    const logPath = round.log_path;
+    if (!logPath || !isFile(logPath)) continue;
+    const text = readText(logPath);       // OSError → ''（Python 的 except OSError → continue 同效）
+    for (const rawLine of pyReadLines(text)) {
+      const line = rawLine.replace(/\n+$/, '');         // 对齐 raw.rstrip("\n")
+      if (line.startsWith('### PROMPT ')) {
+        let prompt = line.slice('### PROMPT '.length);
+        try {
+          prompt = JSON.parse(prompt);
+        } catch {
+          // Python：json.loads 抛 ValueError 就保留原文（不是跳过这一行）
+        }
+        entries.push({ kind: 'user', round: round.round_no, text: prompt });
+        continue;
+      }
+      if (!line.startsWith('{"role"')) continue;
+      let obj;
+      try {
+        obj = JSON.parse(line);
+      } catch {
+        continue;                                       // Python：ValueError → continue
+      }
+      const role = pyGet(obj, 'role', null);
+      if (role === 'meta') {
+        if (pyGet(obj, 'type', null) === 'session.resume_hint') {
+          entries.push({
+            kind: 'meta', round: round.round_no, text: pyGet(obj, 'session_id', ''),
+          });
+        }
+        continue;
+      }
+      if (role === 'assistant') {
+        const toolCalls = [];
+        const rawCalls = pyOr(pyGet(obj, 'tool_calls', null), []);
+        if (Array.isArray(rawCalls)) {                  // 非数组是坏行：Python 会 AttributeError，这里降级
+          for (const tc of rawCalls) {
+            const fn = pyOr(pyGet(tc === null || typeof tc !== 'object' ? {} : tc, 'function', {}), {});
+            toolCalls.push({
+              name: pyGet(fn, 'name', ''),
+              args: pyGet(fn, 'arguments', ''),
+            });
+          }
+        }
+        entries.push({
+          kind: 'assistant',
+          round: round.round_no,
+          text: pyOr(pyGet(obj, 'content', ''), ''),
+          tool_calls: toolCalls,
+        });
+        continue;
+      }
+      if (role === 'tool') {
+        const content = pyOr(pyGet(obj, 'content', ''), '');
+        const { length, sliced } = pySlice(content, DIALOGUE_TEXT_LIMIT);
+        entries.push({
+          kind: 'tool_result',
+          round: round.round_no,
+          tool_call_id: pyGet(obj, 'tool_call_id', ''),
+          text: sliced,
+          truncated: length > DIALOGUE_TEXT_LIMIT,
+          tool_calls: [],
+        });
+      }
+    }
+  }
+  return entries;
+}
+
+/**
+ * `runner.read_log_tail(path, limit)`：读日志末尾 `limit` 行文本（编码容错）。
+ *
+ * 注意这是「读全文再取末尾 N 行」（Python 就是 `f.readlines()[-limit:]`），不是 seek 式 tail。
+ * `limit` 的切片语义见文件头（0 = 全文、负数 = 丢开头）。
+ * @param {string} filePath
+ * @param {number} [limit]
+ * @returns {string}
+ */
+export function readLogTail(filePath, limit = 200) {
+  if (!filePath || !isFile(filePath)) return '';
+  const text = readText(filePath);                      // OSError → ''（Python 同）
+  // readlines() 口径见 pyReadLines；`slice(-limit)` 与 Python `[-limit:]` 同语义
+  // （limit=0 ⇒ 全文；limit<0 ⇒ 丢掉开头 |limit| 行），两者都已用探针实测确认
+  return pyReadLines(text).slice(-limit).join('');
+}
+
+/**
+ * `_task_json` 的 `new_cases`：库内用例总数 − 创建时的基数（负数归零）。
+ *
+ * 依赖注入 `stateCache`（= `server.py:state_cache`，C 族的 `lib/casescan.js:StateCache`）：
+ * 传进来的实例负责 1s TTL 与全量扫描。任何异常（含未注入/项目读不到）都折成 0 ——
+ * 与 Python `_task_json` 里那圈 `try/except Exception: new_cases = 0` 逐点同形。
+ * @param {object} row 任务行
+ * @param {{db?: object, stateCache?: object}} [deps]
+ * @returns {number}
+ */
+function newCases(row, { db, stateCache } = {}) {
+  try {
+    const project = getProject(pyGet(row, 'project_id', null), { db });
+    if (!project) return 0;
+    const state = stateCache.get(project.id, project.cases_root, project.bug_dir, project.work_dir);
+    const total = state && state.library && state.library.stats ? state.library.stats.total : 0;
+    // Python `int(row["cases_base"] or 0)`：非数字会抛 ValueError ⇒ 走 except（new_cases=0）；
+    // `total` 不是数字时 `total - int(base)` 抛 TypeError ⇒ 同样归 0。JS 不抛，故显式判。
+    const base = Number(pyOr(pyGet(row, 'cases_base', 0), 0));
+    if (!Number.isFinite(base) || typeof total !== 'number' || !Number.isFinite(total)) return 0;
+    return Math.max(0, Math.trunc(total) - Math.trunc(base));
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * `_session_title(row)`：任务会话标题（dsh 会话读宿主标题事件；无会话/非 dsh 族/读失败 → ''）。
+ * @param {object} row 任务行
+ * @param {{db?: object}} [deps]
+ * @returns {string}
+ */
+export function sessionTitle(row, { db } = {}) {
+  try {
+    const sid = pyOr(pyGet(row, 'session_id', ''), '');
+    if (!sid) return '';
+    const project = getProject(pyGet(row, 'project_id', null), { db });
+    if (!project) return '';
+    const family = agentFamily(project.agent_path);
+    if (sessFamily(family) === 'dsh') return dshTitle(sid);
+  } catch {
+    return '';                                          // Python：except Exception → ''
+  }
+  return '';
+}
+
+/**
+ * `_task_json(row)`：任务 JSON（**字段与顺序逐字对齐 server.py:2533**，因为响应体走
+ * `pyJsonDumps`，顺序不同就是字节差异；对拍里 `kind:'text'` 用例会直接抓出来）。
+ *
+ * 三个派生字段：`new_cases`（案例库扫描）、`model`（effectiveModel：显式 > 首轮日志 -m > dsh 默认）、
+ * `session_title`（dsh 会话标题）。
+ *
+ * 缺列老行：Python 对「行里没这一列」会 IndexError（请求 500），但 `migrate()` 保证迁移后列必在
+ * —— 这里对 `or "" / or 0` 那几列按空值降级、其余按 null 输出，属**有意的更稳行为**（单测覆盖）。
+ * @param {object} row 任务行（`db.get_task` / `db.list_tasks`）
+ * @param {{db?: object, stateCache?: object}} [deps]
+ * @returns {object}
+ */
+export function taskJson(row, { db, stateCache } = {}) {
+  const raw = (key) => (row[key] === undefined ? null : row[key]);
+  const str0 = (key) => pyOr(row[key] === undefined ? null : row[key], '');
+  return {
+    id: raw('id'),
+    project_id: raw('project_id'),
+    name: raw('name'),
+    auto_fix: Boolean(row.auto_fix),
+    retest: raw('retest'),
+    stop_type: raw('stop_type'),
+    stop_value: raw('stop_value'),
+    task_type: raw('task_type'),
+    payload: raw('payload'),
+    start_stage: str0('start_stage'),
+    end_stage: str0('end_stage'),
+    date_from: str0('date_from'),
+    date_to: str0('date_to'),
+    extra: raw('extra'),
+    model: effectiveModel(row.id, row.model, { db }),
+    permission: raw('permission'),
+    auto_commit: Boolean(row.auto_commit),
+    auto_deploy: Boolean(row.auto_deploy),
+    auto_retest: Boolean(row.auto_retest),
+    new_cases: newCases(row, { db, stateCache }),
+    status: raw('status'),
+    session_id: raw('session_id'),
+    session_title: sessionTitle(row, { db }),
+    current_round: raw('current_round'),
+    new_bugs: raw('new_bugs'),
+    created_at: raw('created_at'),
+    started_at: raw('started_at'),
+    ended_at: raw('ended_at'),
+    error: raw('error'),
+  };
+}