pi-skill-evolve 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,156 @@
+/**
+ * 页面骨架里的四块「管理性质」的东西：顶部控制条、列表筛选、分页、最近操作。
+ *
+ * 都不依赖列表行，所以与 render-rows.ts 分开。
+ *
+ * 两条设计取舍：
+ * 1. **控制条只在服务端传了数据时才渲染**：渲染层不自己去读盘（否则 renderPage 会变成「读盘 + 渲染」两件事），
+ *    也不在拿不到开关状态时猜一个出来 —— 顶部写「复盘：开」而实际是关的，比不写更糟；
+ * 2. **筛选用 `<form method="get">` + hidden view**：零 JS，所以筛选结果能被拷成链接、
+ *    能退回上一页、能在刷新后保持；翻页链接由 pageHref 带上全部筛选参数，不保留就等于点下一页即清空筛选。
+ */
+import type { AuditEntry } from "./audit-log.ts";
+import type { ConfigFlag } from "../config.ts";
+import { FLAG_EFFECT, FLAG_LABEL, TELEMETRY_OFF_WARNING, telemetryOffWhileEnabled } from "../flags.ts";
+import type { WebView } from "./data.ts";
+import { RANGE_KEYS, RANGE_LABEL, STATUS_OPTIONS, pageHref, type ListFilter, type ViewPage } from "./filter.ts";
+import { escapeHtml, formatStamp } from "./text.ts";
+import type { WebControls } from "./activity.ts";
+
+export interface ControlBarOptions {
+  /** 动作用户在哪一页点的，就回哪一页：技能管理页也要能开关采集（曝光数据就是它采的） */
+  view: WebView | "skills";
+  /** 现时（单测注入固定时钟）：决定「最后活动」写成几分钟前 */
+  now: number;
+  csrf?: string;
+  canWrite?: boolean;
+}
+
+const MINUTE_MS = 60_000;
+
+/**
+ * 「最后活动」的人话：只给粗粒度，不给秒 —— 精确到秒反而看不出差别，
+ * 而「几分钟前 / 几小时前 / 几天前」正好是「这个插件还在动吗」需要的精度。
+ */
+export function activityText(at: number | null, now: number): string {
+  if (at === null) return "最后活动：还没有任何记录";
+  const minutes = Math.floor(Math.max(0, now - at) / MINUTE_MS);
+  if (minutes < 1) return "最后活动：刚刚";
+  if (minutes < 60) return `最后活动：${minutes} 分钟前`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `最后活动：${hours} 小时前`;
+  return `最后活动：${Math.floor(hours / 24)} 天前`;
+}
+
+/** 控制条上的「立即复盘」按钮；只读面板不渲染任何表单 */
+function runForm(ctx: ControlBarOptions): string {
+  return `<form method="post" action="/action">
+<input type="hidden" name="csrf" value="${escapeHtml(ctx.csrf ?? "")}">
+<input type="hidden" name="name" value="run">
+<input type="hidden" name="view" value="${ctx.view}">
+<button type="submit">立即复盘</button>
+</form>`;
+}
+
+/**
+ * 一个独立开关：状态 + 后果说明 + 「点下去会发生什么」的按钮。
+ *
+ * 两个开关各自 post 到 `/toggle?field=`（带上隐藏的 view，动作完回同一页），
+ * 按钮文案写动作不写状态 —— 状态已经在左边那一段里，按钮再写一遍会让人把「当前值」看成「点了会变的值」。
+ */
+function flagSwitch(field: ConfigFlag, on: boolean, ctx: ControlBarOptions): string {
+  const state = `<span class="state ${on ? "on" : "off"}">${FLAG_LABEL[field]}：${on ? "开" : "关"}</span>`;
+  const effect = `<span class="hint">${FLAG_EFFECT[field]}</span>`;
+  const writable = ctx.canWrite === true && (ctx.csrf ?? "").length > 0;
+  const form = writable
+    ? `<form method="post" action="/toggle?field=${field}">
+<input type="hidden" name="csrf" value="${escapeHtml(ctx.csrf ?? "")}">
+<input type="hidden" name="view" value="${ctx.view}">
+<button type="submit">${on ? "关闭" : "开启"}${FLAG_LABEL[field]}</button>
+</form>`
+    : "";
+  return `<span class="sw">${state}${effect}${form}</span>`;
+}
+
+/**
+ * 顶部控制条：两个独立开关（采集 / 复盘）+ 立即复盘 + 最后活动。
+ *
+ * 两个开关不许合成一个「开启采集与派生」：采集只写本地文件，复盘才花 token，
+ * 想采集样本但不想花钱是常见的中间状态，捆在一起就无路可走。
+ * 只开复盘不采集时另给一行警告（见 flags.ts 的 TELEMETRY_OFF_WARNING），不许静默。
+ */
+export function renderControlBar(controls: WebControls, ctx: ControlBarOptions): string {
+  const writable = ctx.canWrite === true && (ctx.csrf ?? "").length > 0;
+  const run = writable ? runForm(ctx) : "";
+  const warn = telemetryOffWhileEnabled(controls.enabled, controls.telemetry)
+    ? `<p class="warn">⚠ ${TELEMETRY_OFF_WARNING}</p>\n`
+    : "";
+  return `<div class="ctl">
+${flagSwitch("telemetry", controls.telemetry, ctx)}
+${flagSwitch("enabled", controls.enabled, ctx)}
+${run}<span class="act">${escapeHtml(activityText(controls.lastActivityAt, ctx.now))}</span>
+</div>
+${warn}`;
+}
+
+/** 状态下拉：先「全部」，再固定七个状态（顺序与 STATUS_OPTIONS 一致，别在渲染层重排） */
+function statusSelect(current: string): string {
+  const options = [`<option value="">全部状态</option>`];
+  for (const status of STATUS_OPTIONS) {
+    options.push(`<option value="${status}"${status === current ? " selected" : ""}>${status}</option>`);
+  }
+  return options.join("");
+}
+
+function rangeSelect(current: string): string {
+  return RANGE_KEYS.map(
+    (key) => `<option value="${key}"${key === current ? " selected" : ""}>${RANGE_LABEL[key]}</option>`,
+  ).join("");
+}
+
+/** 筛选表单：hidden view 保证 GET 提交后还在同一页；「重置」链回不带筛选的本页 */
+export function renderFilterForm(view: WebView, filter: ListFilter): string {
+  return `<form class="filter" method="get">
+<input type="hidden" name="view" value="${view}">
+<label>技能 <input type="text" name="skill" value="${escapeHtml(filter.skill)}" placeholder="全部技能" size="16"></label>
+<label>状态 <select name="status">${statusSelect(filter.status)}</select></label>
+<label>时间 <select name="range">${rangeSelect(filter.range)}</select></label>
+<button type="submit">筛选</button>
+<a class="btn" href="/?view=${view}">重置</a>
+</form>`;
+}
+
+/**
+ * 分页条：`第 X / Y 页，共 N 条` 永远显示（空列表也显示「第 1 / 1 页，共 0 条」——
+ * 页脚消失了人只会以为筛选坏了），只有到底时才把箭头换成灰字。
+ */
+export function renderPagination(view: WebView, page: ViewPage, filter: ListFilter): string {
+  const prev =
+    page.page > 1
+      ? `<a href="${escapeHtml(pageHref(view, filter, page.page - 1))}">← 上一页</a>`
+      : `<span class="off">← 上一页</span>`;
+  const next =
+    page.page < page.pages
+      ? `<a href="${escapeHtml(pageHref(view, filter, page.page + 1))}">下一页 →</a>`
+      : `<span class="off">下一页 →</span>`;
+  return `<p class="page">${prev} <span class="count">第 ${page.page} / ${page.pages} 页，共 ${page.total} 条</span> ${next}</p>`;
+}
+
+/** 「最近操作」：时间 + 动作 + runId + 结果；结果里的 error 前缀单独染色，扫一眼就知道有没有出事 */
+function auditRow(entry: AuditEntry): string {
+  const failed = entry.result.startsWith("error");
+  const cls = failed ? "fail" : entry.result === "partial" ? "partial" : "ok";
+  const runId = entry.runId ? ` · <code>${escapeHtml(entry.runId)}</code>` : "";
+  return `<li><span class="when">${formatStamp(entry.at)}</span> · <b>${entry.action}</b>${runId} · <span class="${cls}">${escapeHtml(entry.result)}</span></li>`;
+}
+
+export function renderAudit(entries: readonly AuditEntry[]): string {
+  const body =
+    entries.length === 0
+      ? `<p class="empty">还没有网页操作记录。</p>`
+      : `<ul>\n${entries.map(auditRow).join("\n")}\n</ul>`;
+  return `<section class="audit">
+<h2>最近操作</h2>
+${body}
+</section>`;
+}

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

@@ -0,0 +1,252 @@
+/**
+ * 列表行的渲染：五种视图（待处理 / 待审批 / 已采纳 / 已处理 / 复盘报告）各一段，加上每行针对那条 run 的操作按钮。
+ *
+ * 为什么单独一个文件：行渲染是面板里最长的一段（抬头 + 详情 + 行内表单），
+ * 和页面骨架（状态栏 / 导航 / 页脚）混在一起必然破 300 行。
+ *
+ * 行的操作只有三个（重跑 / 清理 / 看日志），且**只在待处理与复盘报告页**出现：
+ * 待审批页逐行就是批准/拒绝，已采纳与已处理页是档案（只给看 diff / 看日志），都不挂「重跑」——
+ * 一个已采纳的 run 旁边放「重跑」按钮，只会让人以为它能重放整个采纳流程。
+ *
+ * 按钮只在 `writable` 且拿到 csrf 时渲染，绝不自己造一个「能点但写不动」的按钮；
+ * 「看日志」是只读 GET，只读面板也照常给（它不写任何东西）。
+ */
+import type { AppliedItem, ApprovalItem, DoneItem, PendingItem, RunReport, WebView } from "./data.ts";
+import { escapeHtml, formatStamp, shortRunId, withId } from "./text.ts";
+
+/** 行内操作需要的上下文：csrf 与 canWrite 决定按钮渲不渲染，view 决定动作做完回哪一页 */
+export interface RowContext {
+  csrf: string;
+  writable: boolean;
+  view: WebView;
+}
+
+/**
+ * 抬头里的 runId 做成链接（点进去看 run 详情页：diff / 评审 / 五闸）。
+ *
+ * 实现上**先整段转义、再把 shortRunId 那一段换成锚点**：抬头文本来自磁盘，
+ * 绝不能先拼 HTML 再转义（会出现两次转义与注入两种毛病）。
+ */
+function linkRunId(text: string, runId: string): string {
+  const short = escapeHtml(shortRunId(runId));
+  const index = text.indexOf(short);
+  if (index < 0) return text;
+  const href = escapeHtml(`/?view=run&runId=${encodeURIComponent(runId)}`);
+  const anchor = `<a class="run" href="${href}">${short}</a>`;
+  return `${text.slice(0, index)}${anchor}${text.slice(index + short.length)}`;
+}
+
+/** 一行；detail 为空就不给 `<details>`（空折叠框比没有更烦）；给了 runId 就把抬头里的 runId 变链接 */
+function row(head: string, detail: string, acts = "", runId?: string): string {
+  const text = escapeHtml(head);
+  const rendered = runId === undefined ? text : linkRunId(text, runId);
+  const inner =
+    detail.length === 0
+      ? `<span class="head">${rendered}</span>`
+      : `<details><summary class="head">${rendered}</summary><pre>${escapeHtml(detail)}</pre></details>`;
+  return acts.length === 0 ? `<li class="row">${inner}</li>` : `<li class="row">${inner}\n${acts}</li>`;
+}
+
+/** 一个 `/action` 表单：csrf / name / runId / view 全走 hidden，按钮就是提交键 */
+function runForm(name: "rerun" | "cleanup", runId: string, ctx: RowContext): string {
+  const label = name === "rerun" ? "重跑" : "清理记录";
+  const cls = name === "rerun" ? "" : ' class="danger"';
+  const title = name === "rerun" ? "" : ' title="移到 runs/.trash/，不会删数据"';
+  return `<form method="post" action="/action">
+<input type="hidden" name="csrf" value="${escapeHtml(ctx.csrf)}">
+<input type="hidden" name="name" value="${name}">
+<input type="hidden" name="runId" value="${escapeHtml(runId)}">
+<input type="hidden" name="view" value="${ctx.view}">
+<button type="submit"${cls}${title}>${label}</button>
+</form>`;
+}
+
+/**
+ * 行内操作条。`stale` 才给「清理记录」：清理是把目录移走，非卡死的 run 还在写盘，
+ * 移走等于把活进程的 cwd 抽掉（Linux 上不报错，但之后的写入全进孤儿 inode）。
+ */
+function rowActs(runId: string, ctx: RowContext, stale: boolean): string {
+  const parts: string[] = [];
+  if (ctx.writable) {
+    parts.push(runForm("rerun", runId, ctx));
+    if (stale) parts.push(runForm("cleanup", runId, ctx));
+  }
+  parts.push(`<a class="btn" href="/log?runId=${encodeURIComponent(runId)}">看日志</a>`);
+  return `<div class="acts">\n${parts.join("\n")}\n</div>`;
+}
+
+/** 档案类行的操作：只有两个只读链接（看 diff / 看日志），不挂重跑 */
+function archiveActs(runId: string): string {
+  const id = encodeURIComponent(runId);
+  return `<div class="acts">\n<a class="btn" href="${escapeHtml(`/?view=run&runId=${id}`)}">看 diff</a>\n<a class="btn" href="${escapeHtml(`/log?runId=${id}`)}">看日志</a>\n</div>`;
+}
+
+export function pendingRows(items: readonly PendingItem[], ctx: RowContext): string {
+  const badge: Record<PendingItem["kind"], string> = { running: "进行中", approval: "待批", stale: "卡死", reviewed: "待入队" };
+  return items
+    .map((item) => {
+      const skill = item.skill.length > 0 ? ` · ${item.skill}` : "";
+      return row(
+        `[${badge[item.kind]}] ${shortRunId(item.runId)}${skill} · ${formatStamp(item.at)}`,
+        withId(item.runId, item.detail),
+        rowActs(item.runId, ctx, item.kind === "stale"),
+      );
+    })
+    .join("\n");
+}
+
+export function doneRows(items: readonly DoneItem[]): string {
+  return items
+    .map((item) => {
+      const skill = item.skill.length > 0 ? ` · ${item.skill}` : "";
+      const level = item.level === "-" ? "" : ` · ${item.level}`;
+      return row(
+        `[${item.status}] ${shortRunId(item.runId)}${skill}${level} · ${formatStamp(item.at)}`,
+        withId(item.runId, item.detail),
+        archiveActs(item.runId),
+        item.runId,
+      );
+    })
+    .join("\n");
+}
+
+/** 五闸一句话：没记录时写「无记录」而不是「失败」（判不了 ≠ 没过） */
+function gateText(item: AppliedItem): string {
+  if (item.gatesOk === null) return "五闸：无记录";
+  const failed = item.gates.filter((gate) => !gate.ok).length;
+  return failed === 0 ? "五闸：全 ok" : `五闸：${failed} 项失败`;
+}
+
+function appliedDetail(item: AppliedItem): string {
+  const gates =
+    item.gates.length === 0
+      ? ["五闸：没有 06-verify.json（无法判定）"]
+      : item.gates.map((gate) => `  ${gate.gate} ${gate.name} ${gate.ok ? "✓" : "✗"}`);
+  return [
+    `层级：${item.level}`,
+    `采纳：${formatStamp(item.appliedAt)}`,
+    `提案：${item.type} +${item.added}/-${item.removed} 行`,
+    ...gates,
+    item.gatesOk === false ? "注意：有闸没过却仍被采纳，先看 06-verify.json" : "",
+    "完整 diff：点上方 runId 进详情页",
+  ]
+    .filter((line) => line.length > 0)
+    .join("\n");
+}
+
+/** 已采纳：技能 · 提案类型 · +N/-M · 采纳时间 · 五闸结论（用户要的就是这五个字段） */
+export function appliedRows(items: readonly AppliedItem[]): string {
+  return items
+    .map((item) => {
+      const skill = item.skill.length > 0 ? ` · ${item.skill}` : "";
+      const delta = ` · ${item.type} +${item.added}/-${item.removed}`;
+      return row(
+        `[applied] ${shortRunId(item.runId)}${skill}${delta} · ${formatStamp(item.appliedAt)} · ${gateText(item)}`,
+        appliedDetail(item),
+        archiveActs(item.runId),
+        item.runId,
+      );
+    })
+    .join("\n");
+}
+
+/** 待批条目的抬头：一眼看到「谁、改多少、评审怎么判」，详情留给 targets 与完整 runId */
+function approvalHead(item: ApprovalItem): string {
+  const proposal = item.proposal ? ` · ${item.proposal.type} +${item.proposal.added}/-${item.proposal.removed}` : " · 无提案";
+  const verdict = item.review ? ` · ${item.review.verdict ?? "无 verdict"}/blocking ${item.review.blocking}` : "";
+  return `[${item.level}] ${shortRunId(item.runId)} · ${item.skill}${proposal}${verdict} · ${formatStamp(item.createdAt)}`;
+}
+
+function approvalDetail(item: ApprovalItem): string {
+  return [
+    `层级：${item.level}（必须人批；auto 级不在这里）`,
+    `目标：${item.targets.join("、") || "（未写 targets）"}`,
+    `入队：${formatStamp(item.createdAt)}`,
+    item.proposal
+      ? `提案：${item.proposal.type} +${item.proposal.added}/-${item.proposal.removed} 行`
+      : "提案：读不到 02-proposal.json",
+    item.review ? `评审：verdict=${item.review.verdict ?? "（未写）"} · blocking ${item.review.blocking} 条` : "评审：读不到 03-review.json",
+    item.detail ? `备注：${item.detail}` : "",
+  ]
+    .filter((line) => line.length > 0)
+    .join("\n");
+}
+
+/** 一个审批动作表单：csrf 与 runId 都走 hidden，按钮就是提交键 */
+function actionForm(action: "approve" | "reject", item: ApprovalItem, csrf: string): string {
+  const label = action === "approve" ? "批准" : "拒绝";
+  const cls = action === "approve" ? "" : ' class="reject"';
+  return `<form method="post" action="/${action}">
+<input type="hidden" name="csrf" value="${escapeHtml(csrf)}">
+<input type="hidden" name="runId" value="${escapeHtml(item.runId)}">
+<button type="submit"${cls}>${label}</button>
+</form>`;
+}
+
+export function approvalRows(items: readonly ApprovalItem[], ctx: RowContext): string {
+  return items
+    .map((item) => {
+      const detail = `<details><summary class="head">${escapeHtml(approvalHead(item))}</summary><pre>${escapeHtml(
+        withId(item.runId, approvalDetail(item)),
+      )}</pre></details>`;
+      if (!ctx.writable) return `<li class="row">${detail}</li>`;
+      const acts = `<div class="acts">\n${actionForm("approve", item, ctx.csrf)}\n${actionForm("reject", item, ctx.csrf)}\n</div>`;
+      return `<li class="row">${detail}\n${acts}</li>`;
+    })
+    .join("\n");
+}
+
+function gateLine(report: RunReport): string {
+  if (!report.verify) return "验证：还没跑过五闸（未采纳）";
+  const marks = report.verify.gates.map((gate) => `${gate.gate}${gate.ok ? "✓" : "✗"}`).join(" ");
+  return `验证：${report.verify.status} · ${formatStamp(report.verify.at)} · ${marks || "（未记录闸门）"}`;
+}
+
+/** 报告的展开内容：按「结论 → 依据 → 执行」的顺序排，最后才是数字，方便先看结论 */
+function reportDetail(report: RunReport): string {
+  const lines = [`状态：${report.status} · 触发：${report.trigger} · 开始：${formatStamp(report.startedAt)}`];
+  // 失败留档先给原因与日志末行：先知道“为什么没有 findings”，再看其它字段
+  if (report.failure) lines.push(report.failure);
+  const rows = report.findings.rows.map((item) => `  · ${item.skill} · ${item.kind} · ${item.reason}`);
+  lines.push(`findings：${report.findings.total} 条`);
+  lines.push(...rows);
+  if (report.findings.total > report.findings.rows.length) {
+    lines.push(`  …另有 ${report.findings.total - report.findings.rows.length} 条（见 01-findings.json）`);
+  }
+  lines.push(
+    report.proposal
+      ? `提案：${report.proposal.type} ${report.proposal.skill} +${report.proposal.added}/-${report.proposal.removed}`
+      : "提案：无",
+  );
+  lines.push(
+    report.review
+      ? `评审：${report.review.status}${report.review.verdict ? ` verdict=${report.review.verdict}` : ""} · blocking ${report.review.blocking} 条`
+      : "评审：无",
+  );
+  lines.push(
+    report.decision
+      ? `决策：${report.decision.status} · ${report.decision.approver} · ${formatStamp(report.decision.at)}${report.decision.detail ? ` · ${report.decision.detail}` : ""}`
+      : "决策：未采纳（没有 04-decision.json）",
+  );
+  lines.push(gateLine(report));
+  return lines.join("\n");
+}
+
+export function reportRows(reports: readonly RunReport[], ctx: RowContext): string {
+  return reports
+    .map((report) => {
+      // 行上就要能看出「有没有东西」：全部折叠成一行状态+时间，等于用户得逐个点开才知道
+      const findings = report.findings.total > 0 ? ` · ${report.findings.total} 条发现` : " · 无发现";
+      const proposal = report.proposal ? ` · ${report.proposal.type} ${report.proposal.skill}` : "";
+      const verdict = report.review?.verdict ? ` · ${report.review.verdict}` : "";
+      // 卡死的 run 与其它状态同样重要，但中文标签才有用：行首就是用户扫的关键词
+      const label = report.status === "stale" ? "卡死" : report.status;
+      return row(
+        `[${label}] ${shortRunId(report.runId)}${findings}${proposal}${verdict} · ${formatStamp(report.startedAt)}`,
+        withId(report.runId, reportDetail(report)),
+        rowActs(report.runId, ctx, report.status === "stale"),
+        report.runId,
+      );
+    })
+    .join("\n");
+}

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

@@ -0,0 +1,188 @@
+/**
+ * run 详情页（`?view=run&runId=...`）的渲染：概要 + 提案 diff + 改后全文 + 评审 + 五闸 + 发现。
+ *
+ * 为什么 diff 放最前：用户点进这一页 90% 是为了「看看它到底改了什么」。
+ * 结论（评审 / 五闸）排在 diff 之后，因为先看结论再看改动的人，一定会回头再看改动。
+ *
+ * 六块各自的空态都要写明「缺的是哪个文件」—— 一句「暂无数据」会让人以为页面坏了。
+ */
+import type { WebState } from "./data.ts";
+import { DIFF_PREVIEW_LINES, renderDiffLines, parseDiffLines } from "./diff-lines.ts";
+import type { RunBlocking, RunDetail } from "./run-detail.ts";
+import { shellPage } from "./shell.ts";
+import { escapeHtml, formatStamp } from "./text.ts";
+
+/** 概要的一行：标签 + 值（值已转义） */
+function kv(label: string, value: string): string {
+  return `<div class="kv-row"><span class="k">${label}</span><span class="v">${value}</span></div>`;
+}
+
+function overview(detail: RunDetail): string {
+  const log = detail.hasChildLog
+    ? `<a href="/log?runId=${encodeURIComponent(detail.runId)}">child.log</a>`
+    : `<span class="off">没有 child.log</span>`;
+  return `<section>
+<h2>概要</h2>
+<div class="kv">
+${kv("runId", `<code>${escapeHtml(detail.runId)}</code>`)}
+${kv("状态", escapeHtml(detail.status))}
+${kv("技能", escapeHtml(detail.skill.length > 0 ? detail.skill : "—"))}
+${kv("触发", escapeHtml(detail.trigger))}
+${kv("开始", escapeHtml(formatStamp(detail.startedAt)))}
+${kv("结束", escapeHtml(formatStamp(detail.endedAt)) + (detail.endedAt === null ? "" : ' <span class="hint">（取最后一个产出时刻）</span>'))}
+${kv("pid", detail.pid === null ? "—" : String(detail.pid))}
+${kv("日志", log)}
+</div>
+</section>`;
+}
+
+/** 提案 diff：逐行统一 diff；超 400 行只渲染前 400 行并给完整下载链接 */
+function diffSection(detail: RunDetail): string {
+  if (detail.diff === null) {
+    return `<section>
+<h2>提案 diff</h2>
+<p class="empty">这个 run 没有 02-proposal.diff：提案阶段没写出改动（或已被清理）。</p>
+</section>`;
+  }
+  const lines = parseDiffLines(detail.diff);
+  const shown = lines.slice(0, DIFF_PREVIEW_LINES);
+  const truncated = lines.length > shown.length;
+  const note = truncated
+    ? `<p class="hint">diff 共 ${lines.length} 行，页面只渲染前 ${DIFF_PREVIEW_LINES} 行：
+<a class="btn" href="/diff?runId=${encodeURIComponent(detail.runId)}">完整 diff</a></p>`
+    : `<p class="hint">diff 共 ${lines.length} 行。</p>`;
+  return `<section>
+<h2>提案 diff</h2>
+${note}
+${renderDiffLines(shown)}
+</section>`;
+}
+
+/** 改后全文：`<details>` 折叠，默认收起（全文可能很长） */
+function candidateSection(detail: RunDetail): string {
+  if (detail.candidateText === null) {
+    return `<section>
+<h2>改后全文</h2>
+<p class="empty">没有 candidate/${escapeHtml(detail.skill || "<技能名>")}/SKILL.md：这个 run 没留候选文件。</p>
+</section>`;
+  }
+  const lines = detail.candidateText.split(/\r?\n/).length;
+  return `<section>
+<h2>改后全文</h2>
+<details><summary>candidate/${escapeHtml(detail.candidateSkill ?? "")}/SKILL.md（${lines} 行）</summary>
+<pre class="candidate">${escapeHtml(detail.candidateText)}</pre>
+</details>
+</section>`;
+}
+
+function blockingRows(blocking: readonly RunBlocking[]): string {
+  if (blocking.length === 0) return `<p class="hint">blocking：0 条。</p>`;
+  const rows = blocking.map((item) => {
+    const where = item.file.length > 0 ? `${item.file}${item.line === null ? "" : `:${item.line}`}` : "（未写位置）";
+    return `<tr><td>${escapeHtml(item.issue)}</td><td><code>${escapeHtml(where)}</code></td><td>${escapeHtml(item.quote)}</td></tr>`;
+  });
+  return `<table class="tbl">
+<thead><tr><th>问题</th><th>证据位置</th><th>原文引用</th></tr></thead>
+<tbody>
+${rows.join("\n")}
+</tbody>
+</table>`;
+}
+
+function reviewSection(detail: RunDetail): string {
+  if (detail.review === null) {
+    return `<section>
+<h2>评审结论</h2>
+<p class="empty">没有 03-review.json：这一轮还没评审完，或被跳过。</p>
+</section>`;
+  }
+  const review = detail.review;
+  return `<section>
+<h2>评审结论</h2>
+<p class="kv-line">
+verdict <b class="${review.verdict === "pass" ? "ok" : "fail"}">${escapeHtml(review.verdict)}</b> ·
+action <b>${escapeHtml(review.action)}</b> ·
+状态 ${escapeHtml(review.status)} ·
+评审模型 <code>${escapeHtml(review.reviewerModel)}</code>
+</p>
+${blockingRows(detail.blocking)}
+</section>`;
+}
+
+function gateSection(detail: RunDetail): string {
+  if (detail.gates.length === 0) {
+    return `<section>
+<h2>五闸</h2>
+<p class="empty">没有 06-verify.json：五闸未执行（这个 run 没被采纳）。</p>
+</section>`;
+  }
+  const rows = detail.gates.map(
+    (gate) =>
+      `<tr><td><code>${escapeHtml(gate.gate)}</code></td><td>${escapeHtml(gate.name)}</td><td class="${gate.ok ? "ok" : "fail"}">${gate.ok ? "ok" : "fail"}</td><td>${escapeHtml(gate.detail)}</td></tr>`,
+  );
+  return `<section>
+<h2>五闸</h2>
+<p class="hint">验证状态：${escapeHtml(detail.verifyStatus ?? "—")}</p>
+<table class="tbl">
+<thead><tr><th>闸</th><th>名称</th><th>结果</th><th>说明</th></tr></thead>
+<tbody>
+${rows.join("\n")}
+</tbody>
+</table>
+</section>`;
+}
+
+function findingsSection(detail: RunDetail): string {
+  if (detail.findingsTotal === 0) {
+    return `<section>
+<h2>发现</h2>
+<p class="empty">01-findings.json 里没有条目（这一轮没发现值得改的地方）。</p>
+</section>`;
+  }
+  const rows = detail.findings.map((item) => {
+    const lines = item.lines.length > 0 ? item.lines.join("、") : "—";
+    return `<tr><td>${escapeHtml(item.skill)}</td><td>${escapeHtml(item.reason)}</td><td>${escapeHtml(item.confidence)}</td><td>${escapeHtml(lines)}</td></tr>`;
+  });
+  const more =
+    detail.findingsTotal > detail.findings.length
+      ? `<p class="hint">只列前 ${detail.findings.length} 条，共 ${detail.findingsTotal} 条（完整内容见 01-findings.json）。</p>`
+      : "";
+  return `<section>
+<h2>发现</h2>
+<p class="hint">共 ${detail.findingsTotal} 条${detail.notes.length > 0 ? `：${escapeHtml(detail.notes)}` : ""}</p>
+<table class="tbl">
+<thead><tr><th>技能</th><th>归因</th><th>置信度</th><th>证据行</th></tr></thead>
+<tbody>
+${rows.join("\n")}
+</tbody>
+</table>
+${more}
+</section>`;
+}
+
+export interface RenderRunOptions {
+  /** 状态栏要的数字（shell.ts 的 statusBar 唯一依赖） */
+  state: WebState;
+  /** 返回列表页的链接文案来源：从哪一页点进来的（缺省回待处理） */
+  back?: { view: string; label: string };
+}
+
+export function renderRunPage(detail: RunDetail, options: RenderRunOptions): string {
+  const back = options.back ?? { view: "pending", label: "待处理" };
+  const body = `<main class="run">
+<p class="hint"><a href="/?view=${escapeHtml(back.view)}">← 回${escapeHtml(back.label)}</a></p>
+${overview(detail)}
+${diffSection(detail)}
+${candidateSection(detail)}
+${reviewSection(detail)}
+${gateSection(detail)}
+${findingsSection(detail)}
+</main>`;
+  return shellPage({
+    state: options.state,
+    title: `run ${detail.runId}`,
+    active: null,
+    body,
+    foot: `本页只读：diff 与全文来自 <code>runs/${escapeHtml(detail.runId)}</code>，页面不写任何文件。`,
+  });
+}