pi-skill-evolve 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,164 @@
+/**
+ * 技能管理页（`?view=skills`）与技能详情页（`?view=skill&name=...`）的渲染。
+ *
+ * 一行一个技能，字段顺序按「先看规模、再看效果、最后看该不该动手」：
+ * 技能名 · 曝光/加载/加载率 · 最近一次相关 run · 三个状态标签。
+ *
+ * 空态分两种，绝不含糊成一句「暂无数据」：
+ * - 采集关着 → 「没有遥测数据（采集关着）」，并指路去开（页面顶部控制条就是开关）；
+ * - 采集开着但窗口内没事件 → 「最近 N 天没有遥测事件」，说明是没跑过还是窗口太窄。
+ */
+import type { WebState } from "./data.ts";
+import type { WebControls } from "./activity.ts";
+import { renderControlBar } from "./render-controls.ts";
+import type { SkillDetail, SkillRow, SkillsView } from "./skills.ts";
+import { SKILL_DAYS } from "./skills.ts";
+import { shellPage } from "./shell.ts";
+import { escapeHtml, formatStamp, shortRunId } from "./text.ts";
+
+/** 加载率：没曝光时写「—」而不是 0%（0% 会被当成「一百次曝光一次没加载」） */
+export function rateText(rate: number | null): string {
+  return rate === null ? "—" : `${(rate * 100).toFixed(0)}%`;
+}
+
+/** 采集关着时曝光/加载写「—」：0 会被读成「这技能没人用」，实际是「没采到」 */
+function countText(unknown: boolean, value: number): string {
+  return unknown ? "—" : String(value);
+}
+
+/** 三个状态标签各自一色，且**不合并**：每个标签对应一个不同的处置动作 */
+export function skillTags(row: SkillRow): string {
+  const tags: string[] = [];
+  if (row.hasPendingProposal) tags.push(`<span class="tag warn">有待批提案</span>`);
+  if (row.hasBaseline) tags.push(`<span class="tag fail">存量违规</span>`);
+  if (row.missingCursorStub) tags.push(`<span class="tag">缺 .cursor stub</span>`);
+  return tags.length > 0 ? tags.join(" ") : `<span class="hint">—</span>`;
+}
+
+function skillHref(name: string, days: number): string {
+  return `/?view=skill&name=${encodeURIComponent(name)}&days=${days}`;
+}
+
+function runHref(runId: string): string {
+  return `/?view=run&runId=${encodeURIComponent(runId)}`;
+}
+
+/** 窗口切换：只给白名单里的三个值，当前那个不再是链接 */
+function dayLinks(current: number): string {
+  const parts = SKILL_DAYS.map((days) =>
+    days === current
+      ? `<span class="on">近 ${days} 天</span>`
+      : `<a href="${escapeHtml(`/?view=skills&days=${days}`)}">近 ${days} 天</a>`,
+  );
+  return `<p class="days">统计窗口：${parts.join(" · ")}</p>`;
+}
+
+/** 遥测空态的两种说法（采集关着 / 开着但没数据） */
+function telemetryNote(view: SkillsView): string {
+  if (view.events > 0) return "";
+  if (!view.telemetryOn) {
+    return `<p class="warn">没有遥测数据（采集关着）：曝光与加载都是 0 是因为没采集，不是技能没被用。
+用顶部控制条打开采集后会开始记录。</p>`;
+  }
+  return `<p class="hint">最近 ${view.days} 天没有遥测事件：采集开着，但这段时间没有会话记录。</p>`;
+}
+
+export interface RenderSkillsOptions {
+  /** 从哪一页链进来的（详情页的返回链接） */
+  back?: { view: string; label: string };
+}
+
+/** 列表页要能就地开关采集（曝光/加载就是它采的），所以把控制条数据一起传进来 */
+export interface SkillsPageControls {
+  csrf?: string;
+  canWrite?: boolean;
+  controls?: WebControls | null;
+  now?: number;
+}
+
+export function renderSkillsPage(view: SkillsView, state: WebState, options: SkillsPageControls = {}): string {
+  const top = options.controls
+    ? `${renderControlBar(options.controls, {
+        view: "skills",
+        now: options.now ?? Date.now(),
+        csrf: options.csrf,
+        canWrite: options.canWrite,
+      })}\n`
+    : "";
+  const head = `<thead><tr><th>技能</th><th>曝光</th><th>加载</th><th>加载率</th><th>最近一次相关 run</th><th>状态</th></tr></thead>`;
+  // 采集关着（且确实一个事件都没有）时曝光/加载是「不知道」而不是 0：写 0 会被读成「这技能没人用」
+  const unknown = !view.telemetryOn && view.events === 0;
+  const rows = view.rows.map((row) => {
+    const last =
+      row.lastRunId === null
+        ? `<span class="hint">—</span>`
+        : `<a href="${escapeHtml(runHref(row.lastRunId))}">${escapeHtml(shortRunId(row.lastRunId))}</a> <span class="hint">${escapeHtml(formatStamp(row.lastRunAt))}</span>`;
+    return `<tr><td><a href="${escapeHtml(skillHref(row.name, view.days))}">${escapeHtml(row.name)}</a></td><td>${countText(unknown, row.exposed)}</td><td>${countText(unknown, row.loaded)}</td><td>${rateText(row.rate)}</td><td>${last}</td><td>${skillTags(row)}</td></tr>`;
+  });
+  const body =
+    view.rows.length === 0
+      ? `<p class="empty">.pi/skills 下没有技能目录：先确认工作区根路径对不对（面板从 .pi/evolution 往上两层推断）。</p>`
+      : `<table class="tbl">
+${head}
+<tbody>
+${rows.join("\n")}
+</tbody>
+</table>`;
+  return shellPage({
+    state,
+    title: "技能管理",
+    active: "skills",
+    top,
+    body: `<main>
+<h2>技能（${view.rows.length} 个，窗口 ${view.days} 天）</h2>
+${dayLinks(view.days)}
+${telemetryNote(view)}
+${body}
+</main>`,
+    foot: `只读：曝光 = 含该技能的 advertised 轮数（同一轮重复算一次，disabled 不计），加载 = loaded 事件数。
+遥测原文在 <code>.pi/evolution/telemetry/</code>。`,
+  });
+}
+
+/** 技能详情：统计一行 + 历史提案表（每个 run 一行，带 verdict 与 diff 链接） */
+export function renderSkillPage(detail: SkillDetail, state: WebState, options: RenderSkillsOptions = {}): string {
+  const back = options.back ?? { view: "skills", label: "技能管理" };
+  const row = detail.row;
+  const unknown = !detail.telemetryOn && detail.events === 0;
+  const stats =
+    row === null
+      ? `<p class="hint">${escapeHtml(detail.name)} 不在 .pi/skills 目录里（可能已改名或删除），下面只列历史提案。</p>`
+      : `<p class="kv-line">
+曝光 <b>${countText(unknown, row.exposed)}</b> · 加载 <b>${countText(unknown, row.loaded)}</b> · 加载率 <b>${rateText(row.rate)}</b> · 窗口 ${detail.days} 天
+</p>
+<p class="kv-line">状态：${skillTags(row)}</p>`;
+  // 第一列表头点明「点进去就是 diff 视图」：用户要的 diff 就藏在这个 runId 后面
+  const head = `<thead><tr><th>run（点进看 diff）</th><th>状态</th><th>时间</th><th>提案</th><th>verdict</th><th>action</th></tr></thead>`;
+  const rows = detail.runs.map((run) => {
+    const delta = `${run.type} +${run.added}/-${run.removed}`;
+    return `<tr><td><a href="${escapeHtml(runHref(run.runId))}">${escapeHtml(shortRunId(run.runId))}</a></td><td>${escapeHtml(run.status)}</td><td>${escapeHtml(formatStamp(run.at))}</td><td>${escapeHtml(delta)}</td><td>${escapeHtml(run.verdict)}</td><td>${escapeHtml(run.action)}</td></tr>`;
+  });
+  const table =
+    detail.runs.length === 0
+      ? `<p class="empty">还没有针对 ${escapeHtml(detail.name)} 的提案：runs/ 里没有 skill=${escapeHtml(detail.name)} 的 02-proposal.json。</p>`
+      : `<table class="tbl">
+${head}
+<tbody>
+${rows.join("\n")}
+</tbody>
+</table>`;
+  return shellPage({
+    state,
+    title: `技能 ${detail.name}`,
+    active: "skills",
+    body: `<main>
+<p class="hint"><a href="/?view=${escapeHtml(back.view)}">← 回${escapeHtml(back.label)}</a></p>
+<h2>${escapeHtml(detail.name)}</h2>
+${stats}
+<h2>历史提案</h2>
+${table}
+</main>`,
+    foot: `只读：历史提案来自 runs/*/02-proposal.json，点 run 进详情页看 diff 与评审证据。`,
+  });
+}
+

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

@@ -0,0 +1,136 @@
+/**
+ * Web 面板的服务端渲染：纯字符串拼 HTML，不引模板库、不发任何外部请求、不依赖 JS。
+ *
+ * 这一版只负责**列表页**：控制条 → 横幅 → 导航 → 筛选 → 列表 → 分页 → 最近操作 → 页脚。
+ * 页面骨架（`<head>` / 状态栏 / 六个 tab / 页脚）在 ./shell.ts；
+ * 列表行在 ./render-rows.ts，控制条/筛选/分页/最近操作在 ./render-controls.ts，
+ * 技能管理页在 ./render-skills.ts，run 详情页在 ./render-run.ts ——
+ * 拆开是因为合在一起必然破 300 行，而拆开之后每段都能单独看。
+ *
+ * 渲染层不读盘：`controls`（开关与最后活动）与 `audit`（最近操作）都由服务端读好传进来。
+ * 拿不到开关状态时**不渲染控制条**，而不是猜一个「已开」——顶部写错状态比不写更糟。
+ *
+ * 展开交互交给 `<details>`：零 JS，刷新即最新，坏处只是不能记住展开状态 —— 面板不需要。
+ */
+import type { AuditEntry } from "./audit-log.ts";
+import type { WebControls } from "./activity.ts";
+import type { WebState, WebView } from "./data.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";
+import { VIEW_LABEL, shellPage } from "./shell.ts";
+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。",
+};
+
+/** 页脚按视图分：只有待审批页能点，其它页要把「去哪批」写清楚 */
+function footer(view: WebView, canWrite: boolean): string {
+  const api = `机器可读副本：<a href="/api/state">/api/state</a>。`;
+  if (view === "approvals") {
+    if (!canWrite) {
+      return `本实例只读：没注入审批回调，页面上不能点批准 —— 采纳请回 TUI 跑 <code>/skill-evolve approve &lt;runId&gt;</code>。${api}`;
+    }
+    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}`;
+}
+
+/**
+ * 列表区：筛选表单 + 列表 + 分页。待审批页不给筛选也不分页 ——
+ * 它必须在一屏里看全（每个都等着人点），筛掉一部分只会制造「怎么还有没批的」。
+ */
+function listSection(view: WebView, page: ViewPage, filter: ListFilter, ctx: RowContext): string {
+  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>`;
+  return `<main>
+${renderFilterForm(view, filter)}
+${list}
+${renderPagination(view, page, filter)}
+</main>`;
+}
+
+export interface RenderOptions {
+  /** 表单 CSRF token：只读实例不传，按钮就不渲染 */
+  csrf?: string;
+  /** 是否允许渲染写操作按钮：只有注入了回调的实例才 true */
+  canWrite?: boolean;
+  /** 上一步动作的结果 / 错误（来自 303 的 msg / err），页面顶部一条横幅 */
+  notice?: { kind: "msg" | "err"; text: string } | null;
+  /** 控制条数据（开关状态 + 最后活动）：不传就不渲染控制条 */
+  controls?: WebControls | null;
+  /** 最近操作；不传就不渲染「最近操作」区（空数组则渲染成「还没有记录」） */
+  audit?: readonly AuditEntry[] | null;
+  /** 列表筛选；不传按默认（全部技能 / 全部状态 / 最近 7 天 / 第 1 页） */
+  filter?: ListFilter;
+  /** 现时（单测注入固定时钟） */
+  now?: number;
+}
+
+export function renderPage(state: WebState, view: WebView, options: RenderOptions = {}): string {
+  const csrf = options.csrf ?? "";
+  const writable = options.canWrite === true && csrf.length > 0;
+  const now = options.now ?? Date.now();
+  // 渲染层不自带筛选：不传就是「全部、第 1 页」；产品默认的 7 天由 HTTP 层（parseListQuery）给
+  const filter = options.filter ?? NO_FILTER;
+  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 notice = options.notice
+    ? `<p class="notice${options.notice.kind === "err" ? " err" : ""}">${escapeHtml(options.notice.text)}</p>\n`
+    : "";
+  const top = [
+    options.controls ? renderControlBar(options.controls, { view, now, csrf, canWrite: writable }) : "",
+    notice.trimEnd(),
+  ]
+    .filter((part) => part.length > 0)
+    .map((part) => `${part}\n`)
+    .join("");
+  const audit = options.audit ? `${renderAudit(options.audit)}\n` : "";
+  return shellPage({
+    state,
+    title: VIEW_LABEL[view],
+    active: view,
+    head: refresh,
+    top,
+    body: listSection(view, page, filter, ctx),
+    foot: `${audit}${footer(view, writable)}`,
+  });
+}

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

@@ -0,0 +1,160 @@
+/**
+ * 复盘报告视图的数据：每个跑过 `01-findings.json` 的 run 一行，另加「卡死且没产出」的 run（标 stale）。
+ * 判据仍然是 findings 能读；例外是 status=stale 的失败 run —— 它们也要在档案里有一行。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readVerify } from "../apply.ts";
+import type { RunSummary } from "../runs.ts";
+import { readRunError } from "../stale.ts";
+import { asNumber, asRecord, asText, readJson, reasonLabel } from "./json-read.ts";
+
+/** 单条报告里最多列几个技能：全量列会把 details 撑成第二份 findings */
+export const MAX_FINDING_ROWS = 5;
+
+export interface FindingRow {
+  skill: string;
+  kind: string;
+  reason: string;
+}
+
+export interface RunReport {
+  runId: string;
+  status: string;
+  trigger: string;
+  startedAt: number | null;
+  findings: { total: number; rows: FindingRow[] };
+  proposal: { type: string; skill: string; added: number; removed: number } | null;
+  review: { status: string; verdict: string | null; blocking: number } | null;
+  decision: { status: string; approver: string; at: number | null; detail: string } | null;
+  verify: { status: string; at: number | null; gates: { gate: string; name: string; ok: boolean }[] } | null;
+  /** 失败留档：卡死原因 + 日志末行（有它说明这份报告是「没跑完」而不是「没发现」） */
+  failure?: string;
+}
+
+/** findings 读不出来（缺文件 / 坏 JSON）返回 null：报告页不能拿「0 条」冒充「解析失败」 */
+function readFindings(runDir: string): RunReport["findings"] | null {
+  const raw = readJson<Record<string, unknown>>(path.join(runDir, "01-findings.json"));
+  if (!raw) return null;
+  const skills = Array.isArray(raw.skills) ? raw.skills : [];
+  const rows: FindingRow[] = [];
+  for (const entry of skills) {
+    const skill = asRecord(entry);
+    if (!skill) continue;
+    const loaded = skill.loaded === true;
+    const code = asText(skill.whyNotLoaded);
+    rows.push({
+      skill: asText(skill.name, "(未命名)"),
+      kind: loaded ? "已加载" : skill.advertised === false ? "未曝光" : "未加载",
+      reason: loaded ? "—" : code.length > 0 ? reasonLabel(code) : "未写归因",
+    });
+  }
+  return { total: rows.length, rows: rows.slice(0, MAX_FINDING_ROWS) };
+}
+
+function readReview(runDir: string): RunReport["review"] {
+  const raw = readJson<Record<string, unknown>>(path.join(runDir, "03-review.json"));
+  if (!raw) return null;
+  return {
+    status: asText(raw.status, "unknown"),
+    verdict: typeof raw.verdict === "string" ? raw.verdict : null,
+    blocking: Array.isArray(raw.blocking) ? raw.blocking.length : 0,
+  };
+}
+
+function readDecision(runDir: string): RunReport["decision"] {
+  const raw = readJson<Record<string, unknown>>(path.join(runDir, "04-decision.json"));
+  if (!raw) return null;
+  return {
+    status: asText(raw.status, "unknown"),
+    approver: asText(raw.approver, "?"),
+    at: asNumber(raw.at),
+    detail: asText(raw.detail),
+  };
+}
+
+function readVerifyGates(runDir: string): RunReport["verify"] {
+  const record = readVerify(runDir);
+  if (!record) return null;
+  const gates = Array.isArray(record.gates) ? record.gates : [];
+  return {
+    status: asText(record.status, "unknown"),
+    at: asNumber(record.at),
+    gates: gates.map((gate) => ({ gate: asText(gate.gate), name: asText(gate.name), ok: gate.ok === true })),
+  };
+}
+
+/** 触发者只在 run.json 里（listRuns 的摘要不带它）：单独读一次，坏记录当 unknown */
+function readTrigger(runDir: string): string {
+  const raw = readJson<Record<string, unknown>>(path.join(runDir, "run.json"));
+  return asText(raw?.trigger, "unknown");
+}
+
+/** runs/ 下的目录名（不看 run.json，坏掉的目录也要能被 reports 的真实判据「有没有 01-findings」筛） */
+function runDirs(evolutionDir: string): { runId: string; runDir: string }[] {
+  const root = path.join(evolutionDir, "runs");
+  let names: string[];
+  try {
+    names = fs.readdirSync(root);
+  } catch {
+    return [];
+  }
+  const found: { runId: string; runDir: string }[] = [];
+  for (const name of names) {
+    if (name.startsWith(".")) continue;
+    const runDir = path.join(root, name);
+    try {
+      if (!fs.statSync(runDir).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    found.push({ runId: name, runDir });
+  }
+  return found;
+}
+
+export function buildReports(evolutionDir: string, runs: readonly RunSummary[]): RunReport[] {
+  const summaries = new Map(runs.map((run) => [run.runId, run]));
+  const reports: RunReport[] = [];
+  for (const { runId, runDir } of runDirs(evolutionDir)) {
+    const findings = readFindings(runDir);
+    if (!findings) {
+      // 失败也要有一行档案：每条 run 都能在报告里找到，不能因为没产出就从历史里消失
+      const summary = summaries.get(runId);
+      const raw = readJson<Record<string, unknown>>(path.join(runDir, "run.json"));
+      if ((summary?.status ?? asText(raw?.status)) !== "stale") continue;
+      const error = readRunError(runDir);
+      const tail = error?.childLogTail ?? [];
+      const lastLine = tail.length > 0 ? tail[tail.length - 1]!.trim() : "";
+      reports.push({
+        runId,
+        status: "stale",
+        trigger: readTrigger(runDir),
+        startedAt: summary?.dispatchedAt ?? asNumber(raw?.dispatchedAt),
+        findings: { total: 0, rows: [] },
+        proposal: null,
+        review: readReview(runDir),
+        decision: readDecision(runDir),
+        verify: readVerifyGates(runDir),
+        failure: [
+          `原因：${error?.reason === "timeout" ? "超时（子进程还活着但超过单 run 上限）" : "子进程已退出"}`,
+          `日志末行：${lastLine.length > 0 ? lastLine : "（子进程没留下任何输出）"}`,
+        ].join("\n"),
+      });
+      continue;
+    }
+    const proposal = summaries.get(runId)?.proposal;
+    reports.push({
+      runId,
+      status: summaries.get(runId)?.status ?? "unknown",
+      trigger: readTrigger(runDir),
+      startedAt: summaries.get(runId)?.dispatchedAt ?? null,
+      findings,
+      proposal: proposal ? { type: proposal.type, skill: proposal.skill, added: proposal.added, removed: proposal.removed } : null,
+      review: readReview(runDir),
+      decision: readDecision(runDir),
+      verify: readVerifyGates(runDir),
+    });
+  }
+  return reports.sort((a, b) => (b.startedAt ?? 0) - (a.startedAt ?? 0));
+}