pi-skill-evolve 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,234 @@
+/**
+ * run 详情页（`?view=run&runId=...`）的数据：一次读全这一轮复盘留下的证据。
+ *
+ * 一个 run 目录里能看的东西固定为六类，正好对应页面上六块：
+ * run.json（概要）· 02-proposal.diff（改了什么）· candidate/<技能>/SKILL.md（改后全文）
+ * · 03-review.json（评审结论与 blocking）· 06-verify.json（五闸）· 01-findings.json（发现了什么）。
+ *
+ * 纪律：
+ * 1. **只读**；2. **坏文件当空**（六块各自独立退化，缺一块不影响其它块）；
+ * 3. **runId 必须过白名单**：走 resolveRunDir()（已有闸：解析后的父目录必须是 runs/），
+ *    否则 `?view=run&runId=../../..` 就能把仓库外的文件读出来。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ServerResponse } from "node:http";
+import { readVerify } from "../apply.ts";
+import { readProposalSummary } from "../proposal.ts";
+import type { RunRecord } from "../runs.ts";
+import { asNumber, asRecord, asText, readJson, reasonLabel } from "./json-read.ts";
+import { sendText, TEXT_TYPE } from "./http.ts";
+import { resolveRunDir } from "./run-path.ts";
+
+/** findings 最多展示 20 条：一轮复盘可能列出几十个技能，页面只用来快速定位问题 */
+export const FINDING_LIMIT = 20;
+
+/** 技能名白名单：candidate 目录名来自 run.json 里的提案，绝不能让 `../` 参与拼路径 */
+const SAFE_SKILL = /^[A-Za-z0-9._-]+$/;
+
+export interface RunBlocking {
+  issue: string;
+  file: string;
+  line: number | null;
+  quote: string;
+}
+
+export interface RunGate {
+  gate: string;
+  name: string;
+  ok: boolean;
+  detail: string;
+}
+
+export interface RunFinding {
+  skill: string;
+  /** 已加载 / 未加载的原因（G 没触发 之类），搬 reports.ts 的同一套口径 */
+  reason: string;
+  confidence: string;
+  /** evidence 里的行号（01-findings.json 只写 line，没有 file） */
+  lines: number[];
+}
+
+export interface RunDetail {
+  runId: string;
+  status: string;
+  trigger: string;
+  /** 提案目标技能；没有提案时为空串 */
+  skill: string;
+  startedAt: number | null;
+  /** 结束时间：run.json 不写 finishedAt，取 03/04/06 里最后一个时刻（没有就是 null） */
+  endedAt: number | null;
+  pid: number | null;
+  /** 有没有 child.log（决定要不要给日志链接） */
+  hasChildLog: boolean;
+  /** 02-proposal.diff 原文；没有这个文件为 null */
+  diff: string | null;
+  /** candidate 目录里的技能名（与 skill 一致才读全文） */
+  candidateSkill: string | null;
+  candidateText: string | null;
+  review: { status: string; verdict: string; action: string; reviewerModel: string } | null;
+  blocking: RunBlocking[];
+  gates: RunGate[];
+  verifyStatus: string | null;
+  findings: RunFinding[];
+  findingsTotal: number;
+  notes: string;
+}
+
+function readTextFile(file: string): string | null {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function exists(file: string): boolean {
+  try {
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** 03-review.json → verdict / action / reviewerModel + blocking（每条带 file:line 与原文引用） */
+function readReview(runDir: string): Pick<RunDetail, "review" | "blocking"> {
+  const raw = asRecord(readJson<unknown>(path.join(runDir, "03-review.json")));
+  if (!raw) return { review: null, blocking: [] };
+  const blocking: RunBlocking[] = [];
+  for (const item of Array.isArray(raw.blocking) ? raw.blocking : []) {
+    const record = asRecord(item);
+    if (!record) continue;
+    const evidence = asRecord(record.evidence);
+    blocking.push({
+      issue: asText(record.issue, "（未写问题描述）"),
+      file: asText(evidence?.file),
+      line: asNumber(evidence?.line),
+      quote: asText(evidence?.quote),
+    });
+  }
+  return {
+    review: {
+      status: asText(raw.status, "（未写状态）"),
+      verdict: asText(raw.verdict, "（未写 verdict）"),
+      action: asText(raw.action, "（未写 action）"),
+      reviewerModel: asText(raw.reviewerModel, "（未写模型）"),
+    },
+    blocking,
+  };
+}
+
+/** 五闸：06-verify.json 的 gates（apply.ts 写的唯一一处闸门记录） */
+function readGates(runDir: string): Pick<RunDetail, "gates" | "verifyStatus"> {
+  const verify = readVerify(runDir);
+  if (!verify) return { gates: [], verifyStatus: null };
+  const gates = (Array.isArray(verify.gates) ? verify.gates : []).map((gate) => ({
+    gate: asText(gate.gate),
+    name: asText(gate.name),
+    ok: gate.ok === true,
+    detail: asText(gate.detail),
+  }));
+  return { gates, verifyStatus: asText(verify.status, "（未写状态）") };
+}
+
+/** 01-findings.json：每条技能的归因 + evidence 行号，最多 20 条 */
+function readFindings(runDir: string): Pick<RunDetail, "findings" | "findingsTotal" | "notes"> {
+  const raw = asRecord(readJson<unknown>(path.join(runDir, "01-findings.json")));
+  if (!raw) return { findings: [], findingsTotal: 0, notes: "" };
+  const skills = Array.isArray(raw.skills) ? raw.skills : [];
+  const rows: RunFinding[] = [];
+  for (const item of skills.slice(0, FINDING_LIMIT)) {
+    const record = asRecord(item);
+    if (!record) continue;
+    const loaded = record.loaded === true;
+    const code = asText(record.whyNotLoaded);
+    const lines: number[] = [];
+    for (const evidence of Array.isArray(record.evidence) ? record.evidence : []) {
+      const line = asNumber(asRecord(evidence)?.line);
+      if (line !== null) lines.push(line);
+    }
+    rows.push({
+      skill: asText(record.name, "（未写技能名）"),
+      reason: loaded ? "已加载" : code.length > 0 ? reasonLabel(code) : "未写归因",
+      confidence: asText(record.confidence, "—"),
+      lines,
+    });
+  }
+  return { findings: rows, findingsTotal: skills.length, notes: asText(raw.notes) };
+}
+
+/** 改后全文：candidate/<技能>/SKILL.md，技能名过白名单 + 解析后父目录必须是 candidate/ */
+function readCandidate(runDir: string, skill: string): Pick<RunDetail, "candidateSkill" | "candidateText"> {
+  if (!SAFE_SKILL.test(skill)) return { candidateSkill: null, candidateText: null };
+  const candidateRoot = path.join(runDir, "candidate");
+  const dir = path.join(candidateRoot, skill);
+  if (path.dirname(path.resolve(dir)) !== path.resolve(candidateRoot)) {
+    return { candidateSkill: null, candidateText: null };
+  }
+  const text = readTextFile(path.join(dir, "SKILL.md"));
+  return text === null ? { candidateSkill: null, candidateText: null } : { candidateSkill: skill, candidateText: text };
+}
+
+/** 判目录是否存在：resolveRunDir 只管「不越界」，不保证目录真存在（由调用方按 404 处理） */
+function isDir(dir: string): boolean {
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 读一个 run 的详情。runId 不合法（含 `../`、绕对路径）**或目录不存在**一律返回 null ——
+ * 调用方据此回 404：不读盘越界，也不返回一个全是空值的假页。
+ */
+export function readRunDetail(evolutionDir: string, runId: string): RunDetail | null {
+  const runDir = resolveRunDir(evolutionDir, runId);
+  if (!runDir || !isDir(runDir)) return null;
+  const record = readJson<RunRecord>(path.join(runDir, "run.json"));
+  const review = readReview(runDir);
+  const gates = readGates(runDir);
+  const findings = readFindings(runDir);
+  // 子进程常常只写 02-proposal.json 而没回写 run.json（真实 run 就是这样），两处都要看
+  const skill = asText(record?.proposal?.skill ?? readProposalSummary(runDir)?.skill);
+  const candidate = readCandidate(runDir, skill);
+  const decision = asNumber(asRecord(readJson<unknown>(path.join(runDir, "04-decision.json")))?.at);
+  const verifyAt = asNumber(asRecord(readJson<unknown>(path.join(runDir, "06-verify.json")))?.at);
+  const reviewAt = asNumber(asRecord(readJson<unknown>(path.join(runDir, "03-review.json")))?.reviewedAt);
+  const stamps = [decision, verifyAt, reviewAt].filter((value): value is number => value !== null);
+  const hasChildLog = exists(path.join(runDir, "child.log"));
+  return {
+    runId,
+    status: asText(record?.status, "（无 run.json）"),
+    trigger: asText(record?.trigger, "—"),
+    skill,
+    startedAt: asNumber(record?.dispatchedAt),
+    endedAt: stamps.length === 0 ? null : Math.max(...stamps),
+    pid: asNumber(record?.pid),
+    hasChildLog,
+    diff: readTextFile(path.join(runDir, "02-proposal.diff")),
+    ...candidate,
+    ...review,
+    ...gates,
+    ...findings,
+  };
+}
+
+/**
+ * `GET /diff?runId=...`：返回 02-proposal.diff 原文（text/plain），给「完整 diff」链接用。
+ * 不合法 / 不存在一律 404，文案与 /log 同一套口径（说清缺什么，别只说 not found）。
+ */
+export function handleDiff(evolutionDir: string, response: ServerResponse, url: URL): void {
+  const runId = url.searchParams.get("runId") ?? "";
+  const runDir = resolveRunDir(evolutionDir, runId);
+  if (!runDir) {
+    sendText(response, 404, `404：没有这个 run 的 diff（runId=${runId}）`, TEXT_TYPE);
+    return;
+  }
+  const text = readTextFile(path.join(runDir, "02-proposal.diff"));
+  if (text === null) {
+    sendText(response, 404, `404：这个 run 没写 02-proposal.diff（runId=${runId}）`, TEXT_TYPE);
+    return;
+  }
+  sendText(response, 200, text, TEXT_TYPE);
+}

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

@@ -0,0 +1,21 @@
+/**
+ * runId → run 目录的唯一解析口。
+ *
+ * 为什么要有这一层：runId 来自 URL query（`/log?runId=`）与表单（`name=rerun`），是**用户可控输入**。
+ * `path.join(runs, "../../etc/passwd")` 是完全合法的 join，所以「拼路径」之前必须先做两道：
+ * 字符白名单 + 解析后必须仍在 `runs/` 下。少一道就有目录穿越 —— 面板能读的日志盘上任何文件都能读。
+ */
+import * as path from "node:path";
+
+/** 白名单：`/`、`\`、`..`（单独作为一段）都会被这道挡掉，`.` 与 `-` 是 runId 里真会出现的 */
+export const SAFE_RUN_ID = /^[A-Za-z0-9._-]+$/;
+
+/** 合法且不越界返回绝对路径，否则 null（调用方一律按 404 / 400 处理） */
+export function resolveRunDir(evolutionDir: string, runId: string): string | null {
+  const trimmed = runId.trim();
+  if (!SAFE_RUN_ID.test(trimmed)) return null;
+  // 白名单已经排除了分隔符，真正兜底的是这一句：解析后父目录必须正好是 runs/
+  const runsRoot = path.resolve(evolutionDir, "runs");
+  const runDir = path.resolve(runsRoot, trimmed);
+  return path.dirname(runDir) === runsRoot ? runDir : null;
+}

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

@@ -0,0 +1,268 @@
+/**
+ * Web 面板的 HTTP 外壳（`/skill-evolve web` 的落地实现）。
+ *
+ * 六条硬边界：
+ * 1. **只绑 127.0.0.1 且不做鉴权**：面板能看到会话摘要与技能 diff，凭据换不来安全，绑地址才是；
+ * 2. **写操作只有四个入口**：`POST /approve`、`POST /reject`、`POST /action`、`POST /toggle?field=`，
+ *    其余路径一律 405；
+ *    GET 路由是白名单（`/`、`/api/state`、`/log`、`/diff`），绝不把 runs/ 当静态文件服务 ——
+ *    那等于把 `.pi/evolution` 整个暴露成文件下载器（`/log` 只回两个日志文件的末 200 行、
+ *    `/diff` 只回一个 run 的 02-proposal.diff，且 runId 都过了白名单 + 目录校验）；
+ * 3. **写操作的会话保护**：启动时生成 csrf 嵌进表单，POST 必须带对；Host / Origin 只认本机当前端口。
+ *    面板是「本机同一个浏览器点按钮」用的，任何跨站请求都该被拒在门外；
+ * 4. **web 层不写盘**：开关 / 派发 / 采纳 / 清理都是 `index.ts` 注入的回调，走与 TUI 完全相同的路径；
+ *    本层唯一自己做的写入是审计日志（见 ./audit-log.ts）—— 那是「谁点了什么」的旁证，不属于业务；
+ * 5. **端口占用是常态不是异常**：`EADDRINUSE` 返回结构化结果让命令回一句人话，不把栈甩进会话；
+ * 6. **不阻止进程退出**：`unref()` + 幂等 `close()`，面板是附属物，pi 退出时不能因为它挂住。
+ */
+import * as crypto from "node:crypto";
+import * as http from "node:http";
+import { handleLog, handlePost, type WriteContext, type WriteHooks } from "./actions.ts";
+import { collectControls } from "./activity.ts";
+import { readAudit } from "./audit-log.ts";
+import { collectWebState } from "./data.ts";
+import { parseListQuery, parsePanelView } from "./filter.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";
+import { renderRunPage } from "./render-run.ts";
+import { renderSkillPage, renderSkillsPage } from "./render-skills.ts";
+import { handleDiff, readRunDetail } from "./run-detail.ts";
+import { parseDays, readSkillDetail, readSkills } from "./skills.ts";
+
+/** 默认端口：7788 是面板约定值（TUI 提示与文档里都写这个），改它得同时改文档 */
+export const DEFAULT_WEB_PORT = 7788;
+export const DEFAULT_WEB_HOST = "127.0.0.1";
+
+export { MAX_BODY_BYTES };
+export type { WebAction, ToggleHook, RunHook } from "./actions.ts";
+
+export interface WebPanelOptions extends WriteHooks {
+  evolutionDir: string;
+  port?: number;
+  host?: string;
+  /** CSRF 令牌：不给就启动时随机生成；单测注入固定值便于构造合法请求 */
+  csrf?: string;
+}
+
+export interface WebPanel {
+  url: string;
+  host: string;
+  port: number;
+  /** 本实例的表单令牌：同一个面板单例复用同一个值（index.ts 单例打开） */
+  csrf: string;
+  /** 幂等：重复调用都返回同一已完成状态，不抛 ERR_SERVER_NOT_RUNNING */
+  close(): Promise<void>;
+}
+
+export type WebPanelErrorCode = "EADDRINUSE" | "EACCES" | "UNKNOWN";
+
+export type WebPanelResult =
+  | { ok: true; panel: WebPanel }
+  | { ok: false; code: WebPanelErrorCode; message: string };
+
+/** 「最近操作」显示几条：10 条够看出刚才谁点了什么，再多就要翻日志了 */
+const RECENT_ACTIONS = 10;
+
+/** 路由层的上下文就是写操作上下文：读写共用一份（evolutionDir / csrf / 回调 / 端口） */
+type RouteContext = WriteContext;
+
+/** 一个 GET 的完整应答：详情页的 404 要带状态码，不能只用返回字符串 */
+interface GetResult {
+  status: number;
+  body: string;
+  type: string;
+}
+
+/**
+ * 读盘渲染：控制条、最近操作、筛选都在这里一次性读好传给渲染层（渲染层不碰磁盘）。
+ *
+ * 四类页面：`?view=run&runId=`（run 详情）/ `?view=skills`（技能管理）/ `?view=skill&name=`（技能详情）/ 五个列表页。
+ * 详情页的 runId 不合法或目录不存在一律 404 —— 靠 resolveRunDir 的目录校验，不靠字符串过滤。
+ */
+function renderGet(ctx: RouteContext, url: URL): GetResult {
+  const err = url.searchParams.get("err");
+  const msg = url.searchParams.get("msg");
+  const notice = err !== null ? { kind: "err" as const, text: err } : msg !== null ? { kind: "msg" as const, text: msg } : null;
+  const controls = collectControls(ctx.evolutionDir);
+  const state = collectWebState({ evolutionDir: ctx.evolutionDir });
+  const view = parsePanelView(url.searchParams.get("view"));
+  const days = parseDays(url.searchParams.get("days"));
+  if (view === "run") {
+    const runId = url.searchParams.get("runId") ?? "";
+    const detail = readRunDetail(ctx.evolutionDir, runId);
+    if (!detail) return { status: 404, body: `404：没有这个 run（runId=${runId}）\n`, type: TEXT_TYPE };
+    return { status: 200, body: renderRunPage(detail, { state }), type: HTML_TYPE };
+  }
+  if (view === "skills") {
+    const skills = readSkills(ctx.evolutionDir, { days, telemetryOn: controls.telemetry });
+    return {
+      status: 200,
+      body: renderSkillsPage(skills, state, { csrf: ctx.csrf, canWrite: writable(ctx), controls }),
+      type: HTML_TYPE,
+    };
+  }
+  if (view === "skill") {
+    const name = url.searchParams.get("name") ?? "";
+    // 没给技能名就当点了「技能管理」：一个空名字的详情页没有任何信息可看
+    if (name.length === 0) {
+      const skills = readSkills(ctx.evolutionDir, { days, telemetryOn: controls.telemetry });
+      return {
+        status: 200,
+        body: renderSkillsPage(skills, state, { csrf: ctx.csrf, canWrite: writable(ctx), controls }),
+        type: HTML_TYPE,
+      };
+    }
+    const detail = readSkillDetail(ctx.evolutionDir, name, { days, telemetryOn: controls.telemetry });
+    return { status: 200, body: renderSkillPage(detail, state), type: HTML_TYPE };
+  }
+  return {
+    status: 200,
+    body: renderPage(state, view, {
+      csrf: ctx.csrf,
+      // 一对审批动作要么都能点、要么都不显示：只显示一个会让人以为另一半也能用
+      canWrite: writable(ctx),
+      notice,
+      controls,
+      audit: readAudit(ctx.evolutionDir, RECENT_ACTIONS),
+      filter: parseListQuery(url.searchParams),
+    }),
+    type: HTML_TYPE,
+  };
+}
+
+/** 面板是否可写：审批回调成对注入才算（历史口径，保持这一条，别按单个动作判断） */
+function writable(ctx: RouteContext): boolean {
+  return Boolean(ctx.onApprove && ctx.onReject);
+}
+
+/** 路由白名单：任何不在表里的路径都是 404，不拼磁盘路径 */
+function route(ctx: RouteContext, request: http.IncomingMessage, response: http.ServerResponse): void {
+  const method = (request.method ?? "GET").toUpperCase();
+  // 用固定 base 解析：req.url 是相对路径，直接 new URL 会抛
+  let url: URL;
+  try {
+    url = new URL(request.url ?? "/", `http://${DEFAULT_WEB_HOST}`);
+  } catch {
+    sendText(response, 400, "400：请求路径解析失败\n");
+    return;
+  }
+  if (method === "POST") {
+    // 405 / 415 / 403 等各道校验都在 handlePost 里，这里只负责别把拒绝变成未捕获异常
+    void handlePost(ctx, request, response, url).catch((error: unknown) => {
+      console.error(`[skill-evolve] Web 面板写操作处理失败：${String(error)}`);
+      if (!response.headersSent) sendText(response, 500, "500：写操作处理失败，详见 pi 日志\n");
+      else response.end();
+    });
+    return;
+  }
+  if (method !== "GET") {
+    response.setHeader("allow", "GET");
+    sendText(response, 405, "405：面板只接受 GET 与 /approve、/reject、/action、/toggle 的 POST\n");
+    return;
+  }
+  if (url.pathname === "/") {
+    const result = renderGet(ctx, url);
+    sendText(response, result.status, result.body, result.type);
+    return;
+  }
+  if (url.pathname === "/api/state") {
+    sendText(response, 200, `${JSON.stringify(collectWebState({ evolutionDir: ctx.evolutionDir }), null, 2)}\n`, "application/json; charset=utf-8");
+    return;
+  }
+  if (url.pathname === "/log") {
+    handleLog(ctx.evolutionDir, response, url);
+    return;
+  }
+  if (url.pathname === "/diff") {
+    handleDiff(ctx.evolutionDir, response, url);
+    return;
+  }
+  sendText(response, 404, `404：没有 ${url.pathname}（只提供 /、/api/state、/log 与 /diff）\n`);
+}
+
+function describeFailure(
+  code: WebPanelErrorCode,
+  host: string,
+  port: number,
+  detail: string,
+  evolutionDir: string,
+): string {
+  if (code === "EADDRINUSE") {
+    // 先判读「占端口的是不是本机面板」：命中就给地址与 pid；看不出来才提醒别乱 kill
+    const record = readWebPid(evolutionDir);
+    if (record && isAlive(record.pid)) {
+      return `Web 面板已在 ${record.url} 运行（pid ${record.pid}，起于 ${new Date(record.startedAt).toISOString()}）。要换端口：/skill-evolve web --port 7799`;
+    }
+    return `Web 面板没起来：${host}:${port} 已被占用（多半是已经有一个面板在跑）。换端口：/skill-evolve web --port 7799（不是本机面板记录的 pid，可能是别的服务；不要直接 kill，先 lsof -nP -iTCP:${port} -sTCP:LISTEN 看 COMMAND）`;
+  }
+  if (code === "EACCES") return `Web 面板没起来：没有权限监听 ${host}:${port}（换一个 >1024 的端口）`;
+  return `Web 面板没起来：${detail}`;
+}
+
+export function startWebPanel(options: WebPanelOptions): Promise<WebPanelResult> {
+  const port = options.port ?? DEFAULT_WEB_PORT;
+  const host = options.host ?? DEFAULT_WEB_HOST;
+  // 每次启动新令牌：面板重启后旧页面的表单立刻失效（旧页面本来就点不动了）
+  const csrf = options.csrf ?? crypto.randomUUID();
+  let actualPort = port;
+  const ctx: RouteContext = {
+    evolutionDir: options.evolutionDir,
+    csrf,
+    ...(options.onApprove ? { onApprove: options.onApprove } : {}),
+    ...(options.onReject ? { onReject: options.onReject } : {}),
+    ...(options.onToggle ? { onToggle: options.onToggle } : {}),
+    ...(options.onRunNow ? { onRunNow: options.onRunNow } : {}),
+    ...(options.onCleanup ? { onCleanup: options.onCleanup } : {}),
+    port: () => actualPort,
+  };
+  const server = http.createServer((request, response) => {
+    try {
+      route(ctx, request, response);
+    } catch (error) {
+      // 读盘炸了也只回一句：网页永远不该把栈吐给用户，日志里有原文
+      console.error(`[skill-evolve] Web 面板渲染失败：${String(error)}`);
+      if (!response.headersSent) sendText(response, 500, "500：读 .pi/evolution 出错，详见 pi 日志\n");
+      else response.end();
+    }
+  });
+
+  return new Promise<WebPanelResult>((resolve) => {
+    let settled = false;
+    const onError = (error: NodeJS.ErrnoException): void => {
+      if (settled) return;
+      settled = true;
+      server.removeListener("listening", onListening);
+      const code: WebPanelErrorCode =
+        error.code === "EADDRINUSE" ? "EADDRINUSE" : error.code === "EACCES" ? "EACCES" : "UNKNOWN";
+      resolve({ ok: false, code, message: describeFailure(code, host, port, error.message, options.evolutionDir) });
+    };
+    const onListening = (): void => {
+      if (settled) return;
+      settled = true;
+      server.removeListener("error", onError);
+      // 起监听之后再出错（客户端重置等）只记日志：不能让它变成未捕获异常
+      server.on("error", (error) => console.error(`[skill-evolve] Web 面板运行时错误：${String(error)}`));
+      // 面板是附属物：pi 退出时不该被它挂着
+      server.unref();
+      const address = server.address();
+      actualPort = address && typeof address === "object" ? address.port : port;
+      const url = `http://${host}:${actualPort}`;
+      // 落盘「谁持有面板」：端口被占时命令能分清是本机面板还是别的服务（见 ./panel-pid.ts）
+      writeWebPid(options.evolutionDir, { pid: process.pid, host, port: actualPort, url, startedAt: Date.now() });
+      let closed = false;
+      const close = async (): Promise<void> => {
+        if (closed) return;
+        closed = true;
+        server.closeAllConnections();
+        await new Promise<void>((done) => server.close(() => done()));
+        // 只删自己写的记录：文件里是别的 pid 就留着，别替另一个实例抹掉活面板
+        clearWebPid(options.evolutionDir, process.pid);
+      };
+      resolve({ ok: true, panel: { url, host, port: actualPort, csrf, close } });
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(port, host);
+  });
+}

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

@@ -0,0 +1,87 @@
+/**
+ * 页面骨架与顶部导航：五个列表页 + 技能管理页 + 两个详情页共用同一份。
+ *
+ * 为什么抽出来：run 详情页与技能详情页也要状态栏、六个 tab、内联样式，
+ * 各自复制一遍必然出现「点进详情页 tab 高亮错页、状态栏数字少算一个」。
+ * 这里只拼字符串：不读盘、不发请求、不引外部资源 —— 数据由调用方读好传进来。
+ */
+import type { WebState, WebView } from "./data.ts";
+import { STYLE } from "./style.ts";
+
+/** 导航里的 tab 与顺序（用户 2026-11-08 点名要的顺序：已采纳独立、技能管理排最后） */
+export const TAB_ORDER = ["pending", "approvals", "applied", "done", "reports", "skills"] as const;
+export type TabView = (typeof TAB_ORDER)[number];
+
+export const VIEW_LABEL: Record<TabView, string> = {
+  pending: "待处理",
+  approvals: "待审批",
+  applied: "已采纳",
+  done: "已处理",
+  reports: "复盘报告",
+  skills: "技能管理",
+};
+
+/**
+ * 当前高亮的 tab。详情页传 `null`：它们不在导航里（要 runId / 技能名才能进来），
+ * 硬highlight 某个 tab 等于骗人 —— 点那个 tab 回不到这一页。
+ */
+export type ActiveTab = WebView | "skills" | null;
+
+/** 导航：`<a href>` 只用枚举值拼，绝不把 query 原样回显 */
+export function tabs(active: ActiveTab): string {
+  return TAB_ORDER.map((item) => {
+    const className = item === active ? ' class="active"' : "";
+    return `<a href="/?view=${item}"${className}>${VIEW_LABEL[item]}</a>`;
+  }).join("\n");
+}
+
+/** 状态栏：全是数字，安全；「待批 N」「已采纳 N」都直接链到对应页（用户就是点那个数字的） */
+export function statusBar(state: WebState): string {
+  const percent = (state.summary.rollbackRate * 100).toFixed(0);
+  return [
+    `复盘中 ${state.summary.reviewing}`,
+    `卡死 ${state.summary.stale}`,
+    `待批 <a href="/?view=approvals">${state.summary.pendingApprovals}</a>`,
+    `已采纳 <a href="/?view=applied">${state.summary.appliedTotal}</a>`,
+    `回滚率 ${percent}%`,
+  ].join(" · ");
+}
+
+export interface ShellInput {
+  state: WebState;
+  /** 页面标题：进 `<title>`，页面上不再重复一遍 */
+  title: string;
+  active: ActiveTab;
+  /** `<head>` 里的额外标签（目前只有待处理页的 5 秒自刷新） */
+  head?: string;
+  /** 导航上方的「控制条 + 横幅」 */
+  top?: string;
+  /** `<main>` 内容 */
+  body: string;
+  /** 页脚内容（列表页传「最近操作 + 只读说明」） */
+  foot?: string;
+}
+
+export function shellPage(input: ShellInput): string {
+  return `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+${input.head ?? ""}<title>技能进化 · ${input.title}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<h1>技能进化面板</h1>
+<p class="bar">${statusBar(input.state)}</p>
+${input.top ?? ""}<nav>
+${tabs(input.active)}
+</nav>
+${input.body}
+<footer>
+${input.foot ?? ""}
+</footer>
+</body>
+</html>
+`;
+}