@yangdcm/dsh-expert-team 1.1.0

package/lib/metrics/render.js

@@ -0,0 +1,100 @@
+// METRICS.md 的**纯渲染**（B 线 10b 的第一刀）。
+//
+// 为什么先切这一段：`aggregate()` 一个函数压了六件事（枚举 / 读取 / 解析 / 计算 / **渲染** / 写盘），
+// 其中**渲染**是 C 线一直在动的地方（未闭环、返工性质分解、撤销率都往这里加节）—— 而它只需要
+// 一个数据对象、零 IO ⇒ 切出去之后 METRICS 的格式可以**纯函数单测**，不用造 run 夹具。
+//
+// ⚠️ **提取的代价（必须由测试补偿）**：原来是闭包里的局部变量，写错名字会 `ReferenceError` 当场炸；
+// 现在改成 `stats` 对象的字段，**写错名字静默变 `undefined`**、直接印进用户看的报告里。
+// 所以配套的 `metrics-render.test.mjs` 有两道机器检查：
+//   ① 渲染结果里**不得出现 `undefined` / `NaN`**；
+//   ② 本模块解构出的每个字段名，调用点**必须**都传（源码级集合比对）。
+// 这两条是这次提取的安全网，不是可选项。
+
+/**
+ * 渲染 `team/METRICS.md` 全文。
+ * @param stats - 见下（字段名即契约；缺一个就会被上面的测试拦住）。
+ * @returns markdown 全文（不含尾换行，与旧实现一致）。
+ */
+export function renderMetrics(stats) {
+  const {
+    iso, runCount, skipped, completed, runsWithLogs, reworkRate, reworkRuns,
+    sourceLines, reworkNatureLines, phaseLines, firstRunnableLines, closingBudgetLines, roleLines, closureLines,
+    errLines, askLines, decLines, scanLines, maxReviewRound, maxTestRound, revertLine, tokenLines,
+  } = stats;
+  return [
+    '# 团队指标（METRICS）',
+    '',
+    `> 由 \`/team learn\` 自动聚合，最后更新：${iso}`,
+    '',
+    '## 总览',
+    '',
+    `- 总 run 数：${runCount}`,
+    `- 非 run 条目（文件 / 无 STATE.json·TASK.md·RUN.log.md 的目录，未计入）：${skipped} 个`,
+    `- 已完成：${completed}`,
+    `- 有日志的 run：${runsWithLogs}`,
+    `- 返工/失败率：${reworkRate}%（= ${reworkRuns}/${runsWithLogs}，分母是「有日志的 run」而非全部 run）`,
+    `- 返工判定口径（多源，可审计）：${sourceLines}`,
+    '  · 旧实现只统计 RUN.log 的 role:result 与 error 事件，而 LOGGING 约定从不写 role:result ⇒ 恒 0；',
+    '    现改由 TASKS.json 的 repair 任务 / round>1 / verdict / rounds 与日志共同判定。',
+    reworkNatureLines,
+    '',
+    '## 阶段覆盖',
+    '',
+    phaseLines,
+    '',
+    // E 线 E1（SKILL §7.32）：首产物必须**紧挨着阶段覆盖**渲染 —— 二者是同一个问题的两面
+    //（"阶段都覆盖了"不等于"用户早就拿到能跑的东西"）。文案由 `timing.js` 生成（纯函数可单测）。
+    '## 首产物（首个可运行产物耗时）',
+    '',
+    firstRunnableLines,
+    '',
+    // E 线 E2（SKILL §7.33）：收尾预算。与首产物同属"时间去哪了"这一族，放在阶段覆盖之后，
+    // 让读者连着读：阶段都覆盖了 → 多久拿到能跑的东西 → 实现与收尾各花了多久。
+    '## 收尾预算（实现期 = 首产物→冻结 · 收尾 = 冻结→交付）',
+    '',
+    closingBudgetLines,
+    '',
+    '## 角色结果（pass=交付 / rework=返工件 / fail=失败）',
+    '',
+    roleLines,
+    '',
+    '## 未闭环（不计入返工率，但必须可见）',
+    '',
+    closureLines,
+    '',
+    '## 高频卡点（error / 返工，去重）',
+    '',
+    errLines,
+    '',
+    '## 用户高频提问（ask，去重）',
+    '',
+    askLines,
+    '',
+    '## 决策记录（decision，去重）',
+    '',
+    decLines,
+    '',
+    // E 线 E3（SKILL §7.34）：单源化总扫。这条义务**没有代码能强制**（它要求 lead 在发现
+    // 第一个副本时当轮做全仓总扫），所以唯一的抓手是"让它可见"——没人登记本身就是一种可见状态。
+    '## 单源化总扫（见一个，扫全部）',
+    '',
+    scanLines,
+    '',
+    // P4（SPEC §1.5）：评审效率 —— 轮次到顶与"撤销幻觉"必须**可见**，否则噪声治理无从度量。
+    // 无撤销登记时**整行如实说明**（`- （暂无撤销登记：…）`），**不得静默省略** ——
+    // 沉默会被读成"没有撤销"，而事实可能只是"没人登记"。
+    '## 评审效率（轮次 / 撤销率）',
+    '',
+    `- 评审轮次：review ${maxReviewRound} 轮 · test ${maxTestRound} 轮`,
+    revertLine,
+    '',
+    // P5 线：token 成本与上下文峰值。放在**最后**是刻意的：它回答的是"这套流程总共花了多少资源"，
+    // 属于"总量"视角，前面各节回答的是"质量与进度"。空态**必须如实写"没测到"**，
+    // 否则会被读成"消耗很低"（本包在撤销率/首产物上反复吃过这个亏）。
+    '## token 成本与上下文峰值',
+    '',
+    tokenLines,
+    '',
+  ].join('\n');
+}

package/lib/metrics/session-usage.js

@@ -0,0 +1,319 @@
+// token 记账的 **IO 层**：从 DSH 会话遥测里读真实用量，按 run 的时间窗归属。
+//
+// 为什么放在单独文件：`lib/metrics/tokens.js` 是纯计算（可纯单测），这里全是"读盘 + 解压"，
+// 而**读盘是要失败的**（会话目录可能是别的机器、可能被清理、可能没有 zstd）——
+// 失败必须能被如实报告（"读不到" ≠ "消耗低"），不能让渲染层去猜。
+//
+// 格式（2026-09 实测，`~/.dsh/sessions/--Users-…--/<sid>/session.v3.jsonl.zstd`）：
+//   首行 `{"type":"session", "createdAt":<ms>, "delegationDepth":0|1, "cwd":…, "agentPreset":…}`
+//   其后每行一个事件；`{"type":"assistant/message","data":{"usage":{inputTokens,cacheReadTokens,outputTokens,reasoningTokens,totalTokens}}}`
+//   注意：**usage 挂在 `data` 下**，不是顶层 —— 读错这一层会让所有数静默变成 0（本模块首轮就踩过）。
+//
+// 两条性能纪律（都来自实测体量：单个大会话解压后 ~10MB，一个工作区有几十个会话）：
+//   ① **头与用量分两趟读**：列会话只读首行（起 `zstd -dc`，拿到第一行即杀进程）；
+//      只有**落在某 run 时间窗内**的会话才做全量解压。
+//   ② 两趟都按 `(路径, mtime, size)` 缓存 —— `/team learn` 会被反复调用。
+//
+// 压缩：优先 `zstd -dc`（本机已有），不可用时退回 Node 内置 `zlib.zstdDecompressSync`
+//（Node ≥ 23.8 / 22.15）。两者都没有 ⇒ 如实报 `unsupported`，不猜。
+
+import { readdir, stat, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+
+/** DSH 会话根目录（`<DSH_HOME>/sessions`）。 */
+export function sessionsRoot(dshHome) {
+  const home = dshHome || process.env.DSH_HOME || join(process.env.HOME || '', '.dsh');
+  return join(home, 'sessions');
+}
+
+/**
+ * 工作区路径 → DSH 会话目录名（slug）。
+ *
+ * 实测编码规则（来自既有会话目录）：
+ *   `/home/dev/code/my-app` → `--home-dev-code-my-app--`
+ *   `/home/dev/code/packages/api` → `--home-dev-code-packages-api--`
+ *   `/home/dev/code/我的项目` → `/home-dev-code-~6211~7684~9879~76EE--`
+ * 即：分隔符与 `_` → `-`；非 ASCII 码点 → `~` + 大写十六进制；外层再包 `--` … `--`。
+ *
+ * ⚠️ 这是**逆向出来**的规则，不是从宿主源码读到的 ⇒ 找不到目录时调用方必须**列出候选目录并报告**，
+ * 不能默默返回空（"读不到"与"没消耗"必须可区分）。
+ */
+export function workspaceSlug(cwd) {
+  const s = String(cwd ?? '');
+  // 前导分隔符**原样留着**（它自己就是 slug 开头那两个短横线里的一个），其余分隔符与 `_` → `-`，
+  // 最后补 `--` 收口。首轮实现把前导 `/` 也换成了 `-` 再补 `--` ⇒ 得到 `---Users-…`（多一个横杠，
+  // 于是**永远找不到会话目录**，而且失败是静默的 —— 正是本模块注释里警告的那类"读不到"）。
+  const head = /^[/\\]/.test(s) ? s[0] : '';
+  let body = '';
+  for (const ch of s.slice(head ? 1 : 0)) {
+    const cp = ch.codePointAt(0);
+    if (cp > 127) body += `~${cp.toString(16).toUpperCase().padStart(4, '0')}`;
+    else if (ch === '/' || ch === '\\' || ch === '_') body += '-';
+    else body += ch;
+  }
+  return `${head}${body}--`;
+}
+
+let _zstd = null;
+/** `zstd -dc` 是否可用（只探测一次，结果缓存）。 */
+export async function hasZstd() {
+  if (_zstd !== null) return _zstd;
+  _zstd = await new Promise((resolve) => {
+    try {
+      const p = spawn('zstd', ['--version'], { stdio: 'ignore' });
+      p.on('error', () => resolve(false));
+      p.on('close', (code) => resolve(code === 0));
+    } catch { resolve(false); }
+  });
+  return _zstd;
+}
+
+/** 只读首行（`type: session` 的头）：拿到第一行即杀掉解压进程，不做全量解压。 */
+async function readSessionHeader(file) {
+  if (!(await hasZstd())) {
+    try {
+      const { zstdDecompressSync } = await import('node:zlib');
+      const text = zstdDecompressSync(await readFile(file)).toString('utf8');
+      const nl = text.indexOf('\n');
+      return JSON.parse(nl < 0 ? text : text.slice(0, nl));
+    } catch { return null; }
+  }
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (v) => {
+      if (done) return;
+      done = true;
+      try { p.kill('SIGKILL'); } catch { /* 已退出 */ }
+      resolve(v);
+    };
+    const p = spawn('zstd', ['-dc', file], { stdio: ['ignore', 'pipe', 'ignore'] });
+    let buf = '';
+    p.stdout.on('data', (c) => {
+      buf += c.toString('utf8');
+      const nl = buf.indexOf('\n');
+      if (nl >= 0) { try { finish(JSON.parse(buf.slice(0, nl))); } catch { finish(null); } }
+    });
+    p.on('error', () => finish(null));
+    p.on('close', () => finish(null));
+  });
+}
+
+/** 全量解压 → 事件数组（坏行跳过：半写状态是常态）。 */
+async function readSessionEvents(file) {
+  let text;
+  if (!(await hasZstd())) {
+    const { zstdDecompressSync } = await import('node:zlib');
+    text = zstdDecompressSync(await readFile(file)).toString('utf8');
+  } else {
+    text = await new Promise((resolve, reject) => {
+      const p = spawn('zstd', ['-dc', file], { stdio: ['ignore', 'pipe', 'ignore'] });
+      const chunks = [];
+      p.stdout.on('data', (c) => chunks.push(c));
+      p.on('error', reject);
+      p.on('close', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    });
+  }
+  // ⚠️ 不要用 `readline` 去"流式"切行：文本本来就已经整份在内存里，而
+  // `createInterface({ input: Readable.from([text]) })` 把整份文本当成**一个 chunk**，
+  // 遍历时会抛 `readline was closed` —— 而外层 `catch { return null }` 会把它变成
+  // 「读不到」，也就是**所有会话的用量静默变成 0**（本模块实测踩过这个坑：
+  // 表现是 46 个会话角色认不出 + 大量数据缺失，而没有任何报错）。
+  const out = [];
+  for (const line of text.split('\n')) {
+    if (!line) continue;
+    try { out.push(JSON.parse(line)); } catch { /* 坏行跳过 */ }
+  }
+  return out;
+}
+
+/** 取一条消息的文本。
+ *
+ * ⚠️ **两种形状都存在**（实测，同一份日志里）：
+ *   · `system/message` / `assistant/message`：`data.message.content[]`
+ *   · `user/message`：**`data.content[]`**（没有 `message` 包装层）
+ * 首轮只认前者 ⇒ 用户提示词一条都读不到，于是"角色标签"与"runId 标记"双双失效
+ * （表现正是 28 个会话角色认不出、45 个会话无归属）。所以两种都收。
+ */
+function messageText(data) {
+  if (!data || typeof data !== 'object') return '';
+  const content = (data.message && data.message.content) || data.content || [];
+  let s = '';
+  for (const x of content) if (x && x.type === 'text') s += String(x.text || '');
+  return s;
+}
+
+/** 单会话的用量汇总（与会话文件一一对应）。 */
+function summarizeEvents(events) {
+  let inTok = 0; let cacheTok = 0; let outTok = 0; let reasonTok = 0; let steps = 0;
+  let peak = 0; let first = 0; let sysChars = 0; let userChars = 0;
+  // 前几条 user 消息的文本：**角色标签**（`【测试工程师】…`）与 **runId 标记**都在里面。
+  // 为什么要采它：会话头**没有** role，也没有 runId —— 归属只能从提示词里读；
+  // 而 `STATE.members` 只记部分成员（实测一个 run 的 14 个会话里只有 4 个在 members 里）。
+  // 取**前 4 条**而不是第 1 条：真实子会话的第 1 条用户消息可能是"运行环境说明"，
+  // 角色标签在后面那条任务提示词里（实测就是这么排的）。
+  const promptSample = [];
+  for (const o of events) {
+    if (!o || typeof o !== 'object') continue;
+    if (o.type === 'system/message') {
+      sysChars += messageText(o.data).length;
+    } else if (o.type === 'user/message') {
+      const txt = messageText(o.data);
+      userChars += txt.length;
+      if (promptSample.length < 4 && txt) promptSample.push(txt.slice(0, 4000));
+    } else if (o.type === 'assistant/message' && o.data && o.data.usage) {
+      const u = o.data.usage;
+      const prompt = (Number(u.inputTokens) || 0) + (Number(u.cacheReadTokens) || 0);
+      steps += 1;
+      inTok += Number(u.inputTokens) || 0;
+      cacheTok += Number(u.cacheReadTokens) || 0;
+      outTok += Number(u.outputTokens) || 0;
+      reasonTok += Number(u.reasoningTokens) || 0;
+      if (prompt > peak) peak = prompt;
+      if (!first) first = prompt;   // 「首个带 usage 的 assistant 消息」= 每会话固定开销
+    }
+  }
+  return { in: inTok, cache: cacheTok, out: outTok, reasoning: reasonTok, steps, peak, first, sysChars, userChars, promptSample };
+}
+
+const HEADER_CACHE = new Map();    // file -> {mtimeMs, size, entry}
+const USAGE_CACHE = new Map();     // file -> {mtimeMs, size, summary}
+const DIR_CACHE = new Map();       // cwd -> {dir, reason}
+let _lastListError = '';
+
+/** 会话文件名（两种都在用：新会话 `session.v3.jsonl.zstd`，更早的 `session.jsonl.zstd`）。 */
+const SESSION_FILES = ['session.v3.jsonl.zstd', 'session.jsonl.zstd'];
+
+/** 找到目录里第一个会话文件（两种命名都认）。 */
+function firstSessionFile(sessionDir) {
+  for (const f of SESSION_FILES) {
+    const p = join(sessionDir, f);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * 解析一个工作区的会话目录。
+ *
+ * **不再靠猜 path→slug 的编码**：首轮按逆向出的规则拼 slug，两次都拼错（前导分隔符与
+ * 非 ASCII 的处理都与我猜的不同），而拼错的后果是**静默找不到目录** —— 正是本模块注释里
+ * 反复警告的那类失败。改成**内容验证**：候选目录里读一个会话头，比对头里的 `cwd`
+ * （会话头自带 `cwd`，这是**权威**，不是推出来的）。slug 只作为**快路径提示**，命中不了就扫。
+ *
+ * 代价：冷启动最多扫一遍 sessions 根（本机 9 个目录 × 1 次头部读取 ≈ 几十毫秒），结果按 cwd 缓存。
+ *
+ * @returns `{ok, dir, reason, candidates}`
+ */
+export async function resolveWorkspaceDir(cwd, opts = {}) {
+  const root = sessionsRoot(opts.dshHome);
+  const key = String(cwd ?? '');
+  const cached = DIR_CACHE.get(key);
+  if (cached && (cached.ok ? existsSync(cached.dir) : true)) return cached;
+
+  let candidates = [];
+  try { candidates = (await readdir(root)).filter((d) => d.startsWith('--')); } catch {
+    const r = { ok: false, dir: '', reason: 'sessions-root-unreadable', candidates: [] };
+    _lastListError = `会话根目录读不了：${root}`;
+    return r;
+  }
+
+  // 快路径：slug 猜中且头里的 cwd 一致才认（**必须验证**，否则会把别人的 run 算进来）。
+  const guess = join(root, workspaceSlug(cwd));
+  const order = [guess, ...candidates.map((d) => join(root, d)).filter((d) => d !== guess)];
+  for (const dir of order) {
+    if (!existsSync(dir)) continue;
+    let names = [];
+    try { names = await readdir(dir); } catch { continue; }
+    for (const name of names) {
+      const file = firstSessionFile(join(dir, name));
+      if (!file) continue;
+      const header = await readSessionHeader(file);
+      if (!header || header.type !== 'session') continue;
+      if (String(header.cwd || '') === String(cwd)) {
+        const r = { ok: true, dir, reason: '', candidates };
+        DIR_CACHE.set(key, r);
+        return r;
+      }
+      break;   // 该目录的第一个会话头已经能判定归属，不必再读同目录其它会话
+    }
+  }
+  const r = { ok: false, dir: '', reason: 'no-session-for-workspace', candidates };
+  DIR_CACHE.set(key, r);
+  _lastListError = `sessions 根下没有属于本工作区（${cwd}）的会话目录；已扫 ${candidates.length} 个候选目录`;
+  return r;
+}
+
+/**
+ * 列出一个工作区下的会话（**只读头**，不解压正文）。
+ *
+ * @param cwd - 工作区绝对路径。
+ * @param opts - `{dshHome}`。
+ * @returns `{ok, slug, dir, sessions:[{id, file, createdAt, depth, preset, mtimeMs, size}], candidates, reason}`
+ *   `ok:false` 时 `candidates` 是 sessions 根下**实际存在的 slug**（供报告指出"找不到哪个目录"）。
+ */
+export async function listWorkspaceSessions(cwd, opts = {}) {
+  const slug = workspaceSlug(cwd);
+  const resolved = await resolveWorkspaceDir(cwd, opts);
+  if (!resolved.ok) {
+    return { ok: false, slug, dir: resolved.dir, sessions: [], candidates: resolved.candidates, reason: resolved.reason };
+  }
+  const dir = resolved.dir;
+  let names = [];
+  try { names = await readdir(dir); } catch {
+    _lastListError = `会话目录读不了：${dir}`;
+    return { ok: false, slug, dir, sessions: [], candidates: resolved.candidates, reason: 'unreadable' };
+  }
+  const sessions = [];
+  for (const name of names) {
+    const file = firstSessionFile(join(dir, name));
+    if (!file) continue;
+    let st;
+    try { st = await stat(file); } catch { continue; }
+    const cached = HEADER_CACHE.get(file);
+    if (cached && cached.mtimeMs === st.mtimeMs && cached.size === st.size) {
+      sessions.push(cached.entry);
+      continue;
+    }
+    const header = await readSessionHeader(file);
+    if (!header || header.type !== 'session') continue;
+    const entry = {
+      id: String(header.id || name),
+      file,
+      createdAt: Number(header.createdAt) || 0,
+      depth: Number(header.delegationDepth) || 0,
+      preset: String(header.agentPreset || ''),
+      cwd: String(header.cwd || ''),
+      mtimeMs: st.mtimeMs,
+      size: st.size,
+    };
+    HEADER_CACHE.set(file, { mtimeMs: st.mtimeMs, size: st.size, entry });
+    sessions.push(entry);
+  }
+  sessions.sort((a, b) => a.createdAt - b.createdAt);
+  _lastListError = '';
+  return { ok: true, slug, dir, sessions, candidates: [], reason: '' };
+}
+
+/** 上一次 `listWorkspaceSessions` 的失败原因（供报告引用；成功时为空串）。 */
+export function lastListError() { return _lastListError; }
+
+/**
+ * 读一个会话的**用量汇总**（会全量解压；结果按 mtime/size 缓存）。
+ * @returns 用量对象，或 `null`（解压/读取失败 —— 调用方按"读不到"处理，**不得**当成 0）。
+ */
+export async function readSessionUsage(file) {
+  try {
+    const st = await stat(file);
+    const cached = USAGE_CACHE.get(file);
+    if (cached && cached.mtimeMs === st.mtimeMs && cached.size === st.size) return cached.summary;
+    const events = await readSessionEvents(file);
+    const summary = summarizeEvents(events);
+    USAGE_CACHE.set(file, { mtimeMs: st.mtimeMs, size: st.size, summary });
+    return summary;
+  } catch { return null; }
+}
+
+/** 清缓存（测试用；也便于命令侧强制重读）。 */
+export function clearSessionCache() { HEADER_CACHE.clear(); USAGE_CACHE.clear(); DIR_CACHE.clear(); _lastListError = ''; }

package/lib/metrics/timing.js

@@ -0,0 +1,188 @@
+// 阶段计时（E 线 **E1/E2 共用的唯一一份时钟算术**）。
+//
+// 为什么单独成模块：E1（首个可运行产物耗时）与 E2（阶段时长分解 / 收尾定额）都要把
+// `RUN.log.md` 行首的 `[HH:MM:SS]` 相减 —— 而**真实 run 是跨午夜的**（实测样本
+// 22:21:03 起、次日 08:15:30 收尾，全程 9h54m）。裸减会得到 **负数**：`00:32:30 - 22:21:03`
+// = -78273 秒。跨午夜回绕是这类算术最容易写错、也最容易被复制到第二处的地方，而本仓的
+// **头号返工源正是「一个事实多份拷贝」**（一次真实 run 里出现 6 例，占返工 14/29）。
+// 所以：**只此一份**，另一处一律 import；两份实现在这里等于故意埋返工。
+//
+// 本模块**零 IO、零依赖**、全部纯函数 ⇒ 可以纯单测（不需要造 run 夹具）。
+
+/** 一天的秒数（跨午夜回绕用）。 */
+const SECONDS_PER_DAY = 86400;
+
+/**
+ * `HH:MM:SS` → 当日秒数（0..86399）。不可解析（含 `[now]` 这类历史写法、空值、越界值）返回 `null`。
+ * @param hhmmss - 形如 `22:21:03` 的字符串。
+ */
+export function clockSeconds(hhmmss) {
+  const m = String(hhmmss ?? '').match(/^(\d{1,2}):(\d{2}):(\d{2})$/);
+  if (!m) return null;
+  const h = Number(m[1]);
+  const mi = Number(m[2]);
+  const s = Number(m[3]);
+  if (h > 23 || mi > 59 || s > 59) return null;
+  return h * 3600 + mi * 60 + s;
+}
+
+/**
+ * 从 `from` 到 `to` 的分钟数（四舍五入到整数分钟）。
+ * **负值按跨午夜处理（+24h）** —— 真实 run 跨午夜是常态，不处理会把 2h11m 算成 −22h。
+ * 任一时刻不可解析（如历史 run 的 `[now]`）返回 `null` —— 调用方必须把 `null` 当
+ * 「算不出」而不是 0（把算不出当 0 会系统性美化指标）。
+ */
+export function clockDeltaMinutes(from, to) {
+  const a = clockSeconds(from);
+  const b = clockSeconds(to);
+  if (a === null || b === null) return null;
+  let d = b - a;
+  if (d < 0) d += SECONDS_PER_DAY;
+  return Math.round(d / 60);
+}
+
+/**
+ * 中位数：偶数个时取**偏小**的那个（整数分钟，不做平均 —— 平均出来的 23.5 分钟既不是
+ * 任何一次真实观测，又会被读成精确值）。
+ * @param nums - 数字数组（调用方保证非空）。
+ */
+export function medianLower(nums) {
+  const s = [...nums].sort((a, b) => a - b);
+  return s[Math.floor((s.length - 1) / 2)];
+}
+
+/**
+ * E1「首个可运行产物」小节的正文（纯函数 ⇒ 版面与"两种零"的区分可单测）。
+ *
+ * ⚠️ **必须区分的两种零**（本仓在撤销率上吃过这个亏）：`0 个 run 登记` 与
+ * `登记了但算不出` 是两件事，都不能被读成「首产物很快」。所以三种形态各有各的文案。
+ *
+ * @param args.samples - `[{ run, minutes }]`，只含**算得出**的那些 run。
+ * @param args.runsWithLogs - 有日志的 run 总数（分母）。
+ * @param args.unparsable - 写了 `first-runnable` 但**算不出**耗时（缺 `run:started` / 时间戳非 `HH:MM:SS`）的 run 数。
+ * @param args.thresholdMinutes - 阈值（默认 10 分钟）。
+ * @returns 小节正文（不含小节标题）。
+ */
+export function summarizeFirstRunnable({ samples, runsWithLogs, unparsable = 0, thresholdMinutes = 10 }) {
+  const bad = unparsable > 0
+    ? [`  · ⚠️ ${unparsable} 个 run 写了 \`first-runnable\` 但**算不出耗时**（缺 \`run:started\`，或时间戳不是 \`HH:MM:SS\`）⇒ 按**未登记**处理，不计入上面的分位数`]
+    : [];
+  const missing = runsWithLogs - samples.length - unparsable;
+  const missNote = (n) => `  · 「未登记」${n} 个 run = 该 run 没有可运行产物 **或** lead 没写 \`first-runnable\` 事件 —— 日志**无法区分**这两种情况`;
+
+  if (!samples.length) {
+    return [
+      `- （暂无 first-runnable 登记：有日志的 run 共 ${runsWithLogs} 个，但没有一个算得出「首个可运行产物耗时」—— **这不等于"首产物很快"**）`,
+      ...bad,
+      ...(missing > 0 ? [missNote(missing)] : []),
+    ].join('\n');
+  }
+
+  const mins = samples.map((s) => s.minutes);
+  const over = samples.filter((s) => s.minutes > thresholdMinutes).sort((a, b) => b.minutes - a.minutes);
+  return [
+    `- 首个可运行产物耗时：有登记 ${samples.length} / 有日志 ${runsWithLogs} 个 run · 中位 ${medianLower(mins)} 分钟 · 最快 ${Math.min(...mins)} 分钟 · 最慢 ${Math.max(...mins)} 分钟（阈值 ${thresholdMinutes} 分钟）`,
+    ...bad,
+    ...(over.length
+      ? [`  · 超阈值（> ${thresholdMinutes} 分钟）：${over.map((s) => `${s.run}（${s.minutes} 分钟）`).join('、')}`]
+      : [`  · 全部 ≤ ${thresholdMinutes} 分钟`]),
+    ...(missing > 0 ? [missNote(missing)] : []),
+  ].join('\n');
+}
+
+// ── E 线 E2：收尾预算（冻结后追加的阶段 ≤ 实现期 × 50%）─────────────────────────
+//
+// 实测依据（同一个真实 run，见 `docs/专家团-开发计划.md`）：实现期 3h23m，**代码冻结之后的
+// 收尾 3h35m** —— 收尾比实现还长（1.06 倍），而它的成因不是"活多"，是「P3 不阻塞交付」这条
+// 规则当时**只写在 SKILL 里、没有定额**，于是没人知道该在第几小时停手。
+//
+// ⚠️ 更糟的一点：那个 run 的 `RUN.log.md` 里**一条 `phase:review` / `phase:test` 事件都没有**
+// ⇒ 光靠日志，聚合器连"收尾有多长"都算不出来。所以本节的**头号产出不是那个比率，而是
+// 「缺记账」这件事必须可见** —— 隐形比超标更难修。
+
+/**
+ * 从**按日志顺序**的阶段事件里算出「开工 / 实现 / 收尾」三段时长。
+ *
+ * 口径（**近似，必须显式说明**）：把**首个 `review` 或 `test` 阶段事件**当作"代码冻结"的
+ * 观测点 —— 冻结本身没有独立事件，而 review/test 按流水线必然发生在 freeze 之后。
+ * 缺 review/test 时**不猜**：`implementMinutes` / `closingMinutes` 一律返回 `null`。
+ *
+ * @param args.started - `run:started` 的时间戳（可 `null`）。
+ * @param args.phases - `[{ phase, time }]`，按日志出现顺序；同一阶段可重复出现。
+ * @returns `{ preCodeMinutes, implementMinutes, closingMinutes, firstImplement, firstClosing, deliver }`
+ *   —— 任一环节算不出就是 `null`（**不是 0**：把算不出当 0 会让缺失看起来像"很快"）。
+ */
+export function runTimeline({ started, phases, firstRunnable = null }) {
+  const first = {};
+  for (const p of (Array.isArray(phases) ? phases : [])) {
+    // 只认**时间戳可解析**的那一条：`[now]` 这类历史写法不能参与算术，否则整条链变 null。
+    if (first[p.phase] === undefined && clockSeconds(p.time) !== null) first[p.phase] = p.time;
+  }
+  // 实现期**起点**：`first-runnable` **优先**，回退 `phase:implement`。
+  //
+  // 2026-09-13 真实数据修正：原先只认 `phase:implement`，而 SKILL §7.33 ⓿ 与 METRICS 标题写的口径是
+  // 「实现期 = **首产物** → 冻结」。实测那个跑完的 run **有 `phase:review`/`phase:test` 却从没写
+  // `phase:implement`** ⇒ 口径与代码不一致，整段收尾预算算不出来，还被误报成「一条阶段事件都没写」。
+  // 现在以首产物为准；老 run 没有 `first-runnable` 时仍回落 `phase:implement`（向后兼容，且**来源可见**）。
+  const implement = firstRunnable ?? first.implement ?? null;
+  const implementSource = firstRunnable ? 'first-runnable' : (first.implement ? 'phase:implement' : null);
+  // 冻结观测点：review 优先，其次 test（两者都没有 ⇒ null，绝不退化成 deliver）。
+  const closingStart = first.review ?? first.test ?? null;
+  const deliver = first.deliver ?? null;
+  return {
+    firstImplement: implement,
+    implementSource,
+    firstClosing: closingStart,
+    deliver,
+    preCodeMinutes: clockDeltaMinutes(started, implement),
+    implementMinutes: clockDeltaMinutes(implement, closingStart),
+    closingMinutes: clockDeltaMinutes(closingStart, deliver),
+  };
+}
+
+/**
+ * E2「收尾预算」小节的正文（纯函数 ⇒ 版面与三种缺失形态可单测）。
+ *
+ * @param args.rows - `[{ run, implementMinutes, closingMinutes }]`，只含**两段都算得出**的 run。
+ * @param args.missingClosing - 有 `implement` 但**没有** `review`/`test` 阶段事件的 run 数。
+ * @param args.noPhases - 有日志但**连 `implement` 都没有**的 run 数（阶段记账整体缺失）。
+ * @param args.runsWithLogs - 有日志的 run 总数（分母）。
+ * @param args.ratio - 预算比例（默认 0.5，即收尾 ≤ 实现期的一半）。
+ * @returns 小节正文（不含小节标题）。
+ */
+export function summarizeClosingBudget({ rows, missingClosing = 0, missingStart = 0, noPhases = 0, runsWithLogs, ratio = 0.5 }) {
+  const pct = Math.round(ratio * 100);
+  const notes = [];
+  if (missingClosing > 0) {
+    notes.push(`  · ⚠️ ${missingClosing} 个 run **有起点（首产物 / \`phase:implement\`）却没有 \`review\`/\`test\` 阶段事件** ⇒ 实现期与收尾期**分不开**（本仓实测：某真实 run 的 3h35m 收尾就是这样在指标上完全隐形的。聚合器**不猜**，宁可显示"分不开"）`);
+  }
+  if (missingStart > 0) {
+    notes.push(`  · ⚠️ ${missingStart} 个 run **既无 \`first-runnable\` 也无 \`phase:implement\`** ⇒ **实现期起点缺失**（这跟"没有收尾"是两回事；SKILL §7.33 ⓿ 要求开工时就登记首产物）`);
+  }
+  if (noPhases > 0) {
+    notes.push(`  · 「未登记」${noPhases} 个 run = 一条阶段事件都没写 —— **不等于"收尾很短"**`);
+  }
+
+  if (!rows.length) {
+    return [
+      `- （暂无收尾预算可算：有日志的 run 共 ${runsWithLogs} 个，但没有一个同时算得出「实现期」与「收尾期」—— 缺的是 \`phase:review\`/\`phase:test\` 记账，不是"没有收尾"）`,
+      ...notes,
+    ].join('\n');
+  }
+
+  const withRatio = rows.map((r) => ({ ...r, p: r.implementMinutes > 0 ? r.closingMinutes / r.implementMinutes : null }));
+  const over = withRatio
+    .filter((r) => r.implementMinutes > 0 && r.closingMinutes > r.implementMinutes * ratio)
+    .sort((a, b) => b.p - a.p);
+  return [
+    // 口径写在这里、也写在 render 的小节标题里：**实现期 = 首产物 → 首个 review/test**，
+    // **收尾 = 首个 review/test → 交付**。澄清/调研/设计那一段（`preCodeMinutes`）**不进实现期** ——
+    // 2026-09-13 真实 run 实测：把 pre-code 算进去会把 51% 读成 48%，**跨过 50% 红线、结论翻转**。
+    `- 收尾预算（实现期 = 首产物→冻结，收尾 = 冻结→交付；收尾 ≤ 实现期 × ${pct}%）：可算 ${rows.length} / 有日志 ${runsWithLogs} 个 run · 超预算 ${over.length} 个`,
+    ...notes,
+    ...(over.length
+      ? [`  · 超预算：${over.map((r) => `${r.run}（实现 ${r.implementMinutes} 分钟 / 收尾 ${r.closingMinutes} 分钟 = ${Math.round(r.p * 100)}%）`).join('、')}`]
+      : [`  · 全部 ≤ ${pct}%（或实现期为 0，无法成比例，不计入超预算）`]),
+    '  · 「冻结」的观测点是**首个 `review`/`test` 阶段事件**（冻结本身没有独立事件，这是近似口径）。',
+  ].join('\n');
+}