pi-skill-evolve 0.1.5 → 0.1.6

package/extensions/skill-evolve/lib/web/render-skills.ts

@@ -73,7 +73,6 @@ export interface SkillsPageControls {
   csrf?: string;
   canWrite?: boolean;
   controls?: WebControls | null;
-  now?: number;
 }
 
 export function renderSkillsPage(view: SkillsView, state: WebState, options: SkillsPageControls = {}): string {

package/extensions/skill-evolve/lib/web/render-table.ts

@@ -0,0 +1,126 @@
+/**
+ * 列表的表格与分组：五列（状态 / 时间 / 技能 / 提案 / 操作）+ 同会话多条 run 的 `<details>` 分组。
+ *
+ * 为什么单独一个文件：行数据怎么取（render-rows.ts）与表怎么画是两件事，
+ * 表这部分自己就有三块（单行、分组、组标题摘要），挤在映射文件里会破 300 行。
+ * 这里只认 `ListRow`，不认识任何具体视图的数据结构。
+ */
+import { sessionHref, type SessionRef } from "./run-session.ts";
+import type { ListExtras } from "./list-query.ts";
+import { escapeHtml, formatClock, formatIso } from "./text.ts";
+import type { ListRow } from "./render-rows.ts";
+
+/** 表格骨架：五列固定，列宽由 CSS 管；操作列右对齐，扫行时视线不用来回跳 */
+const TABLE_HEAD = `<thead><tr><th class="status">状态</th><th class="time">时间</th><th class="skill">技能</th><th class="delta">提案</th><th class="ops">操作</th></tr></thead>`;
+
+/** 会话小字：单条会话的 run 不进组，所以会话只在这种行的状态格里出现一次 */
+function sessionLine(session: SessionRef): string {
+  // 老 run.json 可能没有 sessionId：写「会话 —」而不是凭空造一个空链接（点进去只会 404）
+  if (session.sessionId === null) return `<span class="sk-sess">会话 —</span>`;
+  const href = sessionHref(session);
+  const text = escapeHtml(`会话 ${session.sessionId.slice(0, 8)}`);
+  const link = href === null ? text : `<a class="sess" href="${escapeHtml(href)}" title="${escapeHtml(session.sessionId)}">${text}</a>`;
+  return `<span class="sk-sess">${link}</span>`;
+}
+
+function rowHtml(row: ListRow, standalone: boolean, now: number): string {
+  const time = row.at === null ? "—" : formatClock(row.at, now);
+  const skill = row.skill.length === 0 ? `<span class="off">—</span>` : `<code>${escapeHtml(row.skill)}</code>`;
+  const delta =
+    row.delta === null ? `<span class="off">—</span>` : `+${row.delta.added} / -${row.delta.removed}`;
+  const at = row.at === null ? "" : ` title="${escapeHtml(formatIso(row.at))}"`;
+  const badge = `<span class="badge ${row.badge.tone}" title="${escapeHtml(row.badge.title)}">${escapeHtml(row.badge.text)}</span>`;
+  return `<tr>
+<td class="status">${badge}${standalone ? sessionLine(row.session) : ""}</td>
+<td class="time"${at}>${time}</td>
+<td class="skill">${skill}</td>
+<td class="delta">${delta}</td>
+<td class="ops">${row.ops}</td>
+</tr>`;
+}
+
+/** 一张表：表头固定五列，列宽与省略号由 CSS 管 */
+function table(rows: readonly ListRow[], now: number, standalone: boolean): string {
+  return `<table class="rows">
+${TABLE_HEAD}
+<tbody>
+${rows.map((row) => rowHtml(row, standalone, now)).join("\n")}
+</tbody>
+</table>`;
+}
+
+/** 一个渲染块：连续的单条 run 合成一张表；同一会话的多条 run 各成一组 */
+export type RowBlock =
+  | { kind: "rows"; rows: ListRow[] }
+  | { kind: "group"; session: SessionRef; rows: ListRow[] };
+
+/**
+ * 按会话分组：**只有同一 sessionId 出现两次以上才进组**。
+ * 单条会话的 run 包进 `<details>` 只会多一次点击（组里就一行），所以直接平铺。
+ * 组出现在它第一条成员的位置，成员内部按时间倒序。
+ */
+export function groupRows(rows: readonly ListRow[]): RowBlock[] {
+  const counts = new Map<string, number>();
+  for (const row of rows) {
+    const id = row.session.sessionId;
+    if (id !== null) counts.set(id, (counts.get(id) ?? 0) + 1);
+  }
+  const emitted = new Set<string>();
+  const blocks: RowBlock[] = [];
+  for (const row of rows) {
+    const id = row.session.sessionId;
+    if (id !== null && (counts.get(id) ?? 0) > 1) {
+      if (emitted.has(id)) continue;
+      emitted.add(id);
+      const members = rows
+        .filter((item) => item.session.sessionId === id)
+        .sort((a, b) => (b.at ?? 0) - (a.at ?? 0));
+      blocks.push({ kind: "group", session: row.session, rows: members });
+      continue;
+    }
+    const last = blocks.at(-1);
+    if (last !== undefined && last.kind === "rows") last.rows.push(row);
+    else blocks.push({ kind: "rows", rows: [row] });
+  }
+  return blocks;
+}
+
+/**
+ * 组标题一行：`会话 01a1b90f · 9 条 · 最近 19:35 · 1 条需要处理`。
+ * 「最近」用组内最新那条的时间；「需要处理」为 0 时写「无待办」—— 组默认展开，标题就是这一组的摘要。
+ */
+function groupSummary(block: { session: SessionRef; rows: ListRow[] }, now: number): string {
+  const latest = block.rows.reduce<number | null>((acc, row) => {
+    if (row.at === null) return acc;
+    return acc === null ? row.at : Math.max(acc, row.at);
+  }, null);
+  const parts = [`${block.rows.length} 条`];
+  if (latest !== null) parts.push(`最近 ${formatClock(latest, now)}`);
+  const todo = block.rows.filter((row) => row.needsAction).length;
+  parts.push(todo > 0 ? `${todo} 条需要处理` : "无待办");
+  const id = block.session.sessionId ?? "—";
+  const href = sessionHref(block.session);
+  const label =
+    href === null
+      ? escapeHtml(`会话 ${id.slice(0, 8)}`)
+      : `<a class="sess" href="${escapeHtml(href)}" title="${escapeHtml(id)}">${escapeHtml(`会话 ${id.slice(0, 8)}`)}</a>`;
+  return `${label} · ${parts.join(" · ")}`;
+}
+
+/**
+ * 列表正文：块与块之间留空，组默认展开（`open`），由 URL 里的 `open=none` 决定要不要收起来。
+ * 收起状态只能靠 URL 记住 —— 面板零 JS，`<details>` 自己的状态刷新就没了。
+ */
+export function renderRows(rows: readonly ListRow[], extras: ListExtras, now: number): string {
+  const blocks = groupRows(rows);
+  const open = extras.open === "none" ? "" : " open";
+  return blocks
+    .map((block) => {
+      if (block.kind === "rows") return table(block.rows, now, true);
+      return `<details class="grp"${open}>
+<summary>${groupSummary(block, now)}</summary>
+${table(block.rows, now, false)}
+</details>`;
+    })
+    .join("\n");
+}

package/extensions/skill-evolve/lib/web/render.ts

@@ -1,31 +1,42 @@
 /**
  * Web 面板的服务端渲染：纯字符串拼 HTML，不引模板库、不发任何外部请求、不依赖 JS。
  *
- * 这一版只负责**列表页**：控制条 → 横幅 → 导航 → 筛选 → 列表 → 分页 → 最近操作 → 页脚。
+ * 这一版只负责**列表页**：粘性头部（摘要 + tabs + 控制条）→ 横幅 → 筛选 → 表格 → 分页 → 最近操作 → 页脚。
  * 页面骨架（`<head>` / 状态栏 / 六个 tab / 页脚）在 ./shell.ts；
- * 列表行在 ./render-rows.ts，控制条/筛选/分页/最近操作在 ./render-controls.ts，
- * 技能管理页在 ./render-skills.ts，run 详情页在 ./render-run.ts ——
- * 拆开是因为合在一起必然破 300 行，而拆开之后每段都能单独看。
+ * 列表行与分组在 ./render-rows.ts，控制条/筛选/分页/刷新提示/最近操作在 ./render-controls.ts，
+ * 技能管理页在 ./render-skills.ts，run 详情页在 ./render-run.ts —— 拆开是因为合在一起必然破 300 行。
  *
  * 渲染层不读盘：`controls`（开关与最后活动）与 `audit`（最近操作）都由服务端读好传进来。
  * 拿不到开关状态时**不渲染控制条**，而不是猜一个「已开」——顶部写错状态比不写更糟。
  *
- * 展开交互交给 `<details>`：零 JS，刷新即最新，坏处只是不能记住展开状态 —— 面板不需要。
+ * 刷新策略（用户 2026-11-08 报「待处理一直帮我收起，点开过一会又被收起」）：
+ * 默认**不**自动刷新，只给「更新于 …· 刷新」；`&live=1` 才是用户显式要的 5 秒重载，
+ * 且那时页头会写清「展开态会重置」。整页重载必然丢 `<details>` 展开态，这代价只该由要求它的人承担。
  */
 import type { AuditEntry } from "./audit-log.ts";
 import type { WebControls } from "./activity.ts";
 import type { WebState, WebView } from "./data.ts";
+import { NO_FILTER, buildViewPage, parseView, type ListFilter, type ViewPage } from "./filter.ts";
+import { DEFAULT_EXTRAS, listHref, type ListExtras } from "./list-query.ts";
 import {
-  NO_FILTER,
-  buildViewPage,
-  isDefaultFilter,
-  pageHref,
-  parseView,
-  type ListFilter,
-  type ViewPage,
-} from "./filter.ts";
-import { appliedRows, approvalRows, doneRows, pendingRows, reportRows, type RowContext } from "./render-rows.ts";
-import { renderAudit, renderControlBar, renderFilterForm, renderPagination } from "./render-controls.ts";
+  appliedRows,
+  approvalRows,
+  doneRows,
+  pendingRows,
+  reportRows,
+  type ListRow,
+  type RowContext,
+} from "./render-rows.ts";
+import { groupRows, renderRows } from "./render-table.ts";
+import {
+  activityText,
+  renderAudit,
+  renderControlBar,
+  renderFilterForm,
+  renderLiveNote,
+  renderPagination,
+  renderUpdatedAt,
+} from "./render-controls.ts";
 import { VIEW_LABEL, shellPage } from "./shell.ts";
 import { escapeHtml } from "./text.ts";
 
@@ -33,13 +44,31 @@ import { escapeHtml } from "./text.ts";
 export { escapeHtml, formatStamp, shortRunId } from "./text.ts";
 export { parseView } from "./filter.ts";
 
-/** 每个列表页的空态文案：写清「为什么空」与「空在这里意味着什么」，不是一句「暂无数据」 */
-export const EMPTY: Record<WebView, string> = {
-  pending: "暂无待处理：所有复盘都已完成，也没有待人批的改动。",
-  approvals: "没有待批：auto 级不需要人批，approval 级的会出现在这里。",
-  applied: "还没有已采纳的提案：采纳过的会连 diff 一起留在这里。",
-  done: "暂无已处理记录：还没有回滚、失败或被否决的提案。",
-  reports: "暂无复盘报告：还没有 run 写过 01-findings.json。",
+/**
+ * 每个列表页的空态：一句话说「为什么空」+ 一句下一步。
+ * 只写「暂无数据」等于把「接下来该敲什么」留给人自己猜，而这里每个空态都对应一个具体动作。
+ */
+export const EMPTY: Record<WebView, { text: string; next: string }> = {
+  pending: {
+    text: "暂无待处理：所有复盘都已完成，也没有待人批的改动。",
+    next: "下一批提案来自真实会话：确认 <code>/skill-evolve telemetry on</code> 与 <code>/skill-evolve dispatch on</code>。",
+  },
+  approvals: {
+    text: "没有待批：auto 级不需要人批，approval 级的会出现在这里。",
+    next: "想让提案先来这儿：<code>/skill-evolve level approval</code>。",
+  },
+  applied: {
+    text: "还没有已采纳的提案：采纳过的会连 diff 一起留在这里。",
+    next: "先 <code>/skill-evolve dispatch on</code>，让真实会话自动出提案。",
+  },
+  done: {
+    text: "暂无已处理记录：还没有回滚、失败或被否决的提案。",
+    next: "只有走完终态的 run 才进这里；在跑的 run 看「待处理」。",
+  },
+  reports: {
+    text: "暂无复盘报告：还没有 run 写过 01-findings.json。",
+    next: "先 <code>/skill-evolve run</code> 手动跑一次复盘。",
+  },
 };
 
 /** 页脚按视图分：只有待审批页能点，其它页要把「去哪批」写清楚 */
@@ -51,31 +80,58 @@ function footer(view: WebView, canWrite: boolean): string {
     }
     return `点「批准」= 在 TUI 敲 <code>/skill-evolve approve &lt;runId&gt;</code>，走同一套五道闸；「拒绝」只改队列状态，不动任何技能文件。${api}`;
   }
-  return `只读面板：只绑 127.0.0.1、无鉴权、不能在这里点批准 ——
-采纳请回 TUI 跑 <code>/skill-evolve approve &lt;runId&gt;</code>，或去<a href="/?view=approvals">待审批页</a>直接批。${api}`;
+  return `本机面板 · 只绑 127.0.0.1 · 无鉴权 · 机器可读副本见 <a href="/api/state">/api/state</a>。`;
+}
+
+/** 五个视图各自的「条目 → 行」映射；字段差异都在各自函数里消化，渲染层只认 ListRow */
+function rowsOf(page: ViewPage, ctx: RowContext): ListRow[] {
+  switch (page.view) {
+    case "pending":
+      return pendingRows(page.rows, ctx);
+    case "approvals":
+      return approvalRows(page.rows, ctx);
+    case "applied":
+      return appliedRows(page.rows);
+    case "done":
+      return doneRows(page.rows);
+    default:
+      return reportRows(page.rows, ctx);
+  }
 }
 
 /**
- * 列表区：筛选表单 + 列表 + 分页。待审批页不给筛选也不分页 ——
+ * 分组开关：只在真的出现了组（同会话 ≥2 条）时给链接 —— 没有组的页面给「收起分组」等于给一个点了没反应的开关。
+ * 两个显式链接（`open=all` / `open=none`）优先于默认值，靠 URL 记住，不用 JS。
+ */
+function groupToggle(view: WebView, filter: ListFilter, extras: ListExtras, hasGroup: boolean): string {
+  if (!hasGroup) return "";
+  const collapsed = extras.open === "none";
+  const target = { ...extras, open: collapsed ? ("all" as const) : ("none" as const) };
+  const text = collapsed ? "展开全部分组" : "收起全部分组";
+  return `<p class="hint"><a href="${escapeHtml(listHref(view, filter, 1, target))}">${text}</a></p>\n`;
+}
+
+/**
+ * 列表区：筛选表单 + 表格（或空态）+ 分页。待审批页不给筛选也不分页 ——
  * 它必须在一屏里看全（每个都等着人点），筛掉一部分只会制造「怎么还有没批的」。
  */
-function listSection(view: WebView, page: ViewPage, filter: ListFilter, ctx: RowContext): string {
+function listSection(
+  view: WebView,
+  page: ViewPage,
+  filter: ListFilter,
+  extras: ListExtras,
+  ctx: RowContext,
+): string {
+  const rows = rowsOf(page, ctx);
   const body =
-    page.view === "pending"
-      ? pendingRows(page.rows, ctx)
-      : page.view === "approvals"
-        ? approvalRows(page.rows, ctx)
-        : page.view === "applied"
-          ? appliedRows(page.rows)
-          : page.view === "done"
-            ? doneRows(page.rows)
-            : reportRows(page.rows, ctx);
-  const list = body.length === 0 ? `<p class="empty">${EMPTY[view]}</p>` : `<ul>\n${body}\n</ul>`;
-  if (view === "approvals") return `<main>\n${list}\n</main>`;
+    rows.length === 0
+      ? `<p class="empty">${EMPTY[view].text}</p>\n<p class="next">${EMPTY[view].next}</p>`
+      : `${groupToggle(view, filter, extras, groupRows(rows).some((block) => block.kind === "group"))}${renderRows(rows, extras, ctx.now)}`;
+  if (view === "approvals") return `<main>\n${body}\n</main>`;
   return `<main>
-${renderFilterForm(view, filter)}
-${list}
-${renderPagination(view, page, filter)}
+${renderFilterForm(view, filter, extras)}
+${body}
+${renderPagination(view, page, filter, extras)}
 </main>`;
 }
 
@@ -92,6 +148,8 @@ export interface RenderOptions {
   audit?: readonly AuditEntry[] | null;
   /** 列表筛选；不传按默认（全部技能 / 全部状态 / 最近 7 天 / 第 1 页） */
   filter?: ListFilter;
+  /** 三个显式开关（自动刷新 / 分组展开）；不传就是默认（不刷新、展开） */
+  extras?: ListExtras;
   /** 现时（单测注入固定时钟） */
   now?: number;
 }
@@ -102,23 +160,24 @@ export function renderPage(state: WebState, view: WebView, options: RenderOption
   const now = options.now ?? Date.now();
   // 渲染层不自带筛选：不传就是「全部、第 1 页」；产品默认的 7 天由 HTTP 层（parseListQuery）给
   const filter = options.filter ?? NO_FILTER;
+  const extras = options.extras ?? DEFAULT_EXTRAS;
+  // `live` 只在待处理页有意义：别的页数据不会自己变，给了也忽略（与 parseListExtras 同一口径）
+  const live = extras.live && view === "pending";
   const page = buildViewPage(state, view, filter, now);
-  const ctx: RowContext = { csrf, writable, view };
-  // 只给「待处理」加 5 秒自刷新：等待时人会停留，看档案 / 历史时刷新只会把页面跳回去；
-  // 待审批页有按钮，刷新会打断正在点的动作，同样不加。
-  // 带筛选时刷新必须带上同样的筛选参数，否则挑完技能看着看着就被弹回全部 —— 没筛时保持最短 URL。
-  // 渲染层不传 filter（= 全量、第 1 页）与默认筛选（7d、第 1 页且没挑技能/状态）都用最短 URL
-  const plainRefresh = options.filter === undefined || isDefaultFilter(filter);
-  const refresh =
-    view === "pending"
-      ? `<meta http-equiv="refresh" content="5; url=${plainRefresh ? "?view=pending" : escapeHtml(pageHref(view, filter, page.page))}">\n`
-      : "";
+  const ctx: RowContext = { csrf, writable, view, now };
+  const here = listHref(view, filter, page.page, extras);
+  // 只有 `&live=1` 的待处理页才 5 秒重载：别的页数据不会自己变，重载只会丢展开态与滚动位置
+  const refresh = live ? `<meta http-equiv="refresh" content="5; url=${escapeHtml(here)}">\n` : "";
+  const liveNote = live
+    ? renderLiveNote(listHref(view, filter, page.page, { ...extras, live: false }))
+    : "";
   const notice = options.notice
-    ? `<p class="notice${options.notice.kind === "err" ? " err" : ""}">${escapeHtml(options.notice.text)}</p>\n`
+    ? `<p class="notice${options.notice.kind === "err" ? " err" : ""}">${escapeHtml(options.notice.text)}</p>`
     : "";
   const top = [
-    options.controls ? renderControlBar(options.controls, { view, now, csrf, canWrite: writable }) : "",
-    notice.trimEnd(),
+    options.controls ? renderControlBar(options.controls, { view, csrf, canWrite: writable }) : "",
+    liveNote,
+    notice,
   ]
     .filter((part) => part.length > 0)
     .map((part) => `${part}\n`)
@@ -129,8 +188,11 @@ export function renderPage(state: WebState, view: WebView, options: RenderOption
     title: VIEW_LABEL[view],
     active: view,
     head: refresh,
+    meta: options.controls
+      ? `${renderUpdatedAt(now, here)} · ${escapeHtml(activityText(options.controls.lastActivityAt, now))}`
+      : renderUpdatedAt(now, here),
     top,
-    body: listSection(view, page, filter, ctx),
+    body: listSection(view, page, filter, extras, ctx),
     foot: `${audit}${footer(view, writable)}`,
   });
 }

package/extensions/skill-evolve/lib/web/server.ts

@@ -22,6 +22,7 @@ import { collectControls } from "./activity.ts";
 import { readAudit } from "./audit-log.ts";
 import { collectWebState } from "./data.ts";
 import { parseListQuery, parsePanelView } from "./filter.ts";
+import { parseListExtras } from "./list-query.ts";
 import { HTML_TYPE, MAX_BODY_BYTES, TEXT_TYPE, sendText } from "./http.ts";
 import { clearWebPid, isAlive, readWebPid, writeWebPid } from "./panel-pid.ts";
 import { renderPage } from "./render.ts";
@@ -98,7 +99,12 @@ function renderGet(ctx: RouteContext, url: URL): GetResult {
       sessionId,
       ...(url.searchParams.get("file") !== null ? { file: url.searchParams.get("file") } : {}),
     });
-    return { status: 200, body: renderSessionPage(source, { state }), type: HTML_TYPE };
+    // `only=user` 在服务端过滤（面板零 JS）：列表只渲染用户消息与助手纯文本，工具调用压成一行
+    return {
+      status: 200,
+      body: renderSessionPage(source, { state, onlyUser: url.searchParams.get("only") === "user" }),
+      type: HTML_TYPE,
+    };
   }
   if (view === "run") {
     const runId = url.searchParams.get("runId") ?? "";
@@ -138,6 +144,8 @@ function renderGet(ctx: RouteContext, url: URL): GetResult {
       controls,
       audit: readAudit(ctx.evolutionDir, RECENT_ACTIONS),
       filter: parseListQuery(url.searchParams),
+      // 三个显式开关（自动刷新 / 分组展开 / 只看对话的前两个）：`live` 按页面白名单放行，仅待处理页生效
+      extras: parseListExtras(url.searchParams, view),
     }),
     type: HTML_TYPE,
   };

package/extensions/skill-evolve/lib/web/session-render.ts

@@ -0,0 +1,189 @@
+/**
+ * 会话正文与目录的**渲染**：把 session-view.ts 解析出来的块拼成 HTML 与目录条目。
+ *
+ * 与解析拆开是因为两件事的行数各自都不小：解析要处理 pi 的 JSONL 细节，
+ * 渲染要处理 Markdown、折叠、目录锚点与总输出上限 —— 合在一个文件里必然破 300 行。
+ *
+ * 三条口径：
+ * 1. **正文走 Markdown-lite**：pi 的对话里满是 `**加粗**`、`` `代码` ``、列表，
+ *    原样输出等于让人读一堆星号（用户 2026-11-08：「Markdown 原样输出」）；
+ * 2. **工具块默认收起**，抬头给「次数 + 首个参数摘要」——`bash ×9` 看不出调了什么；
+ * 3. **正文与目录一次遍历产出**：锚点 id 与目录 href 因此不会对不上。
+ */
+import { renderMarkdownLite } from "./markdown-lite.ts";
+import {
+  MAX_MESSAGES,
+  MAX_OUTPUT,
+  MAX_TEXT,
+  MAX_USER_TEXT,
+  type SessionEntry,
+  type SessionToolCall,
+  type SessionTranscript,
+} from "./session-view.ts";
+import { escapeHtml, formatTime, formatTimeSeconds } from "./text.ts";
+
+/** 折叠抬头里的首个参数摘要上限 */
+export const TOOL_PREVIEW = 60;
+/** 目录条目里的用户消息摘要上限 */
+export const TOC_TEXT = 40;
+
+/** 截断并加省略号：中文一行话也可能超长，所以在字符数上截，不在行上截 */
+function clip(text: string, max: number): string {
+  const trimmed = text.trim();
+  return trimmed.length > max ? `${trimmed.slice(0, max)}…` : trimmed;
+}
+
+/** 工具调用的抬头：`read ×3、bash ×2`（同名的合成一个计数，别写三遍 read） */
+function toolSummary(calls: readonly SessionToolCall[]): string {
+  const counts = new Map<string, number>();
+  for (const call of calls) counts.set(call.name, (counts.get(call.name) ?? 0) + 1);
+  return [...counts.entries()].map(([name, count]) => `${name} ×${count}`).join("、");
+}
+
+/** 一个工具调用块：名字 + 参数摘要 + 结果前 200 字（全转义，original 里可能带尖括号） */
+function toolBlock(call: SessionToolCall): string {
+  return `<div class="tool">
+<p class="tool-name">${escapeHtml(call.name)}</p>
+<pre class="tool-args">${escapeHtml(call.args.length > 0 ? call.args : "（无参数）")}</pre>
+<pre class="tool-result">${escapeHtml(call.result)}</pre>
+</div>`;
+}
+
+/**
+ * 一组工具调用：`<details>` **默认收起**（不加 `open`）——
+ * 一段会话动辄几百次调用，默认展开等于把对话正文顶到十屏之外。
+ * 抬头里给「首个参数摘要」：`bash ×9` 看不出调了什么，`rg -n "x" lib` 一眼就知道。
+ */
+function toolGroup(calls: readonly SessionToolCall[]): string {
+  const first = calls[0];
+  // 摘要按工具取（bash 取 command 第一行、read 取文件名…），取不到就只留 `▸ bash ×9`
+  const preview = first === undefined ? "" : clip(first.summary, TOOL_PREVIEW);
+  const tail = preview.length === 0 ? "" : ` · <span class="muted">${escapeHtml(preview)}</span>`;
+  return `<details class="tools"><summary>▸ ${escapeHtml(toolSummary(calls))}${tail}</summary>
+${calls.map(toolBlock).join("\n")}
+</details>`;
+}
+
+/** `only=user` 时工具调用的替身：一行说清省略了多少次，并给「看全部」的链接 */
+function omittedLine(calls: readonly SessionToolCall[], expandHref: string | null): string {
+  const more = expandHref === null ? "" : `（<a href="${escapeHtml(expandHref)}">看全部</a>）`;
+  return `<p class="hint">… 本轮省略 ${calls.length} 次工具调用${more}</p>`;
+}
+
+/** 目录条目：`19:35 · 前 40 字`（换行压成空格，否则目录会被一段代码撑成几行） */
+export interface TocEntry {
+  id: string;
+  at: number | null;
+  text: string;
+}
+
+export interface TranscriptView {
+  /** 消息流 HTML */
+  body: string;
+  /** 目录条目（只收 user 消息，顺序与正文一致） */
+  toc: TocEntry[];
+  /** 实际渲染的块数 */
+  shown: number;
+  /** 是否撞到总输出上限 */
+  truncated: boolean;
+}
+
+export interface RenderSessionOptions {
+  /** 因「只渲染最后 200 条」丢掉的条数（>0 时在顶部说明一句） */
+  dropped?: number;
+  /** 只看对话：工具调用压成一行 */
+  onlyUser?: boolean;
+  /** 「看全部」链接（去掉 only=user 的同一会话地址） */
+  expandHref?: string | null;
+}
+
+/** 一条对话消息：徽章 + 时刻 + Markdown-lite 正文（用户底色更亮，扫读时能一眼分段） */
+function messageBlock(
+  entry: Extract<SessionEntry, { kind: "user" | "assistant" }>,
+  id: string,
+  label: { text: string; tone: string },
+): { html: string; text: string } {
+  const max = entry.kind === "user" ? MAX_USER_TEXT : MAX_TEXT;
+  const body = clip(entry.text, max);
+  if (body.length === 0) return { html: "", text: "" };
+  const at = entry.at === null ? "" : `<span class="at">${formatTimeSeconds(entry.at)}</span>`;
+  const html = `<div class="msg ${entry.kind} m" id="${id}">
+<div class="mhead"><span class="badge ${label.tone}">${label.text}</span>${at}</div>
+<div class="msg-body">${renderMarkdownLite(body)}</div>
+</div>`;
+  return { html, text: body.replace(/\s+/g, " ").trim() };
+}
+
+/**
+ * 会话正文 + 目录：**一次遍历同时产出两者**，锚点 id 与目录 href 因此不会对不上
+ * （分两处各自编号迟早出现「点了目录跳错块」）。
+ */
+export function renderTranscript(
+  transcript: SessionTranscript,
+  options: RenderSessionOptions = {},
+): TranscriptView {
+  const parts: string[] = [];
+  const toc: TocEntry[] = [];
+  let size = 0;
+  let shown = 0;
+  let truncated = false;
+  if (options.dropped !== undefined && options.dropped > 0) {
+    parts.push(
+      `<p class="hint">只渲染最后 ${MAX_MESSAGES} 条消息，前面还有 ${options.dropped} 条未显示（看全文请用 rg/read 打开原文件）。</p>`,
+    );
+  }
+  for (const entry of transcript.entries) {
+    const id = `m-${shown + 1}`;
+    const rendered =
+      entry.kind === "tools"
+        ? {
+            html:
+              options.onlyUser === true ? omittedLine(entry.calls, options.expandHref ?? null) : toolGroup(entry.calls),
+            text: "",
+          }
+        : messageBlock(
+            entry,
+            id,
+            entry.kind === "user" ? { text: "用户", tone: "blue" } : { text: "助手", tone: "green" },
+          );
+    if (rendered.html.length === 0) continue;
+    if (size + rendered.html.length > MAX_OUTPUT) {
+      truncated = true;
+      break;
+    }
+    shown += 1;
+    parts.push(rendered.html);
+    size += rendered.html.length;
+    if (entry.kind === "user") {
+      toc.push({ id, at: entry.at, text: clip(rendered.text, TOC_TEXT) });
+    }
+  }
+  if (shown === 0) {
+    return {
+      body: '<p class="empty">这段会话里没有可渲染的对话（可能全是工具调用与系统提示）。</p>',
+      toc,
+      shown,
+      truncated,
+    };
+  }
+  if (truncated) {
+    parts.push(
+      `<p class="hint">已达页面输出上限（${Math.round(MAX_OUTPUT / 1024)}KB），后面还有内容未渲染：继续看请用 rg/read 打开原文件。</p>`,
+    );
+  }
+  return { body: parts.join("\n"), toc, shown, truncated };
+}
+
+/**
+ * 目录内容（左侧粘性栏与窄屏折叠目录共用同一份）：
+ * 只列 user 消息 —— 一段会话里用户消息就是天然的「章节」。
+ */
+export function renderToc(toc: readonly TocEntry[]): string {
+  if (toc.length === 0) return `<p class="hint">这段会话里没有用户消息。</p>`;
+  return toc
+    .map((item) => {
+      const when = item.at === null ? "—" : formatTime(item.at);
+      return `<a href="#${item.id}">${escapeHtml(when)} · ${escapeHtml(item.text)}</a>`;
+    })
+    .join("\n");
+}