pi-skill-evolve 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,202 @@
+/**
+ * 技能管理页（`?view=skills`）与技能详情页（`?view=skill&name=...`）的数据聚合。
+ *
+ * 「技能改进」这件事有两个真相来源，这里把它们并为一行：
+ * - `.pi/skills/*\/SKILL.md` 目录 = **有哪些技能**（目录是权威，不是遥测里出现过的名字）；
+ * - `.pi/evolution/telemetry/*.jsonl` = **曝光与加载**（advertised / loaded 事件，默认看最近 30 天）。
+ *
+ * 三个状态标签**不合并**（用户明确要求）：有待批提案 / 存量违规 / 缺 .cursor stub。
+ * 合成就得二选一显示，而这三件事的处置动作完全不同（去批 / 去改 / 去补 stub）。
+ *
+ * 只读：这里只读目录与 jsonl，不写任何文件。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { baselinePath, readBaseline } from "../baseline.ts";
+import { listSkillDirs } from "../hard-rules.ts";
+import { readQueue } from "../queue.ts";
+import { listRuns } from "../runs.ts";
+import { readEvents, ratio, type TelemetryEvent } from "../telemetry.ts";
+import { asRecord, asText } from "./json-read.ts";
+
+/** 允许的统计窗口（白名单）：URL 上的 `?days=` 只认这三个值，其余回落默认 */
+export const SKILL_DAYS = [7, 30, 90] as const;
+export const DEFAULT_SKILL_DAYS = 30;
+/** 详情页要列历史提案，扫的 run 数比列表页多：一个技能一年可能被改几十次 */
+const RUN_SCAN_LIMIT = 200;
+
+/**
+ * 允许没有 `.cursor/skills/<名>/SKILL.md` 的路由 stub 的技能。
+ * 依据 AGENTS.md 明文例外：描述 pi 自身机制的技能不加 Cursor 路由（Cursor 没有对应物，加了是误导）。
+ */
+const CURSOR_STUB_EXEMPT = new Set(["nested-agents-md", "pi-deepseek-search"]);
+
+export interface SkillRow {
+  name: string;
+  /** 曝光：最近 N 天里「含这个技能的 advertised 轮数」（同一轮重复只算一次，disabled 不计） */
+  exposed: number;
+  /** 加载：loaded 事件数（`ok === false` 不计） */
+  loaded: number;
+  /** 加载率：loaded / exposed；exposed 为 0 时 null（页面写「—」，不能写 0%） */
+  rate: number | null;
+  /** 最近一次相关 run（proposal.skill === name 的最新一条）；没有就是 null */
+  lastRunId: string | null;
+  lastRunAt: number | null;
+  /** 状态标签一：队列里有 pending 且是它的提案 */
+  hasPendingProposal: boolean;
+  /** 状态标签二：baseline.json 里有它一条违规 */
+  hasBaseline: boolean;
+  /** 状态标签三：`.cursor/skills/<名>/SKILL.md` 不存在（豁免名单除外） */
+  missingCursorStub: boolean;
+}
+
+export interface SkillsView {
+  days: number;
+  rows: SkillRow[];
+  /** 采集开关：关着时页面要写「没有遥测数据（采集关着）」而不是一屏 0 */
+  telemetryOn: boolean;
+  /** 窗口内遥测事件总数（0 = 采集开着但没数据，与「关着」是两种空态） */
+  events: number;
+}
+
+export interface SkillRunRow {
+  runId: string;
+  status: string;
+  at: number | null;
+  type: string;
+  added: number;
+  removed: number;
+  verdict: string;
+  action: string;
+}
+
+export interface SkillDetail {
+  name: string;
+  days: number;
+  row: SkillRow | null;
+  runs: SkillRunRow[];
+  /** 采集总开关与窗口内事件数：关着且没事件时，曝光/加载是「不知道」而不是 0 */
+  telemetryOn: boolean;
+  events: number;
+}
+
+/** 工作区根：约定 evolutionDir 恒为 `<cwd>/.pi/evolution`，所以往上两层就是仓库根 */
+export function workspaceRoot(evolutionDir: string): string {
+  return path.dirname(path.dirname(path.resolve(evolutionDir)));
+}
+
+function hasFile(file: string): boolean {
+  try {
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** 曝光按「轮」算：同一轮 advertised 里同名的技能只计一次（disabled 的不算曝光） */
+function countExposure(events: readonly TelemetryEvent[]): Map<string, number> {
+  const exposure = new Map<string, number>();
+  for (const event of events) {
+    if (asText(event.kind) !== "advertised") continue;
+    const seen = new Set<string>();
+    for (const item of Array.isArray(event.skills) ? event.skills : []) {
+      const record = asRecord(item);
+      if (!record || record.disabled === true) continue;
+      const name = asText(record.name);
+      if (name.length > 0) seen.add(name);
+    }
+    for (const name of seen) exposure.set(name, (exposure.get(name) ?? 0) + 1);
+  }
+  return exposure;
+}
+
+function countLoaded(events: readonly TelemetryEvent[]): Map<string, number> {
+  const loaded = new Map<string, number>();
+  for (const event of events) {
+    if (asText(event.kind) !== "loaded") continue;
+    if (event.ok === false) continue; // 读失败不算加载
+    const name = asText(event.skill);
+    if (name.length > 0) loaded.set(name, (loaded.get(name) ?? 0) + 1);
+  }
+  return loaded;
+}
+
+export interface SkillsOptions {
+  /** 统计窗口天数，只接受 SKILL_DAYS 里的值 */
+  days?: number;
+  now?: number;
+  telemetryOn?: boolean;
+}
+
+/** 归一窗口：非法值（含 `?days=9999`）回落 30，避免有人用 URL 拉全量历史 */
+export function parseDays(raw: string | null): number {
+  const value = Number(raw);
+  return (SKILL_DAYS as readonly number[]).includes(value) ? value : DEFAULT_SKILL_DAYS;
+}
+
+/** 技能列表：目录为准，遥测补曝光/加载，队列/baseline/cursor 补三个标签 */
+export function readSkills(evolutionDir: string, options: SkillsOptions = {}): SkillsView {
+  const days = options.days ?? DEFAULT_SKILL_DAYS;
+  const now = options.now ?? Date.now();
+  const root = workspaceRoot(evolutionDir);
+  const events = readEvents(path.join(evolutionDir, "telemetry"), days, now);
+  const exposure = countExposure(events);
+  const loaded = countLoaded(events);
+  const pending = new Set(readQueue(evolutionDir).filter((item) => item.status === "pending").map((item) => item.skill));
+  const baseline = readBaseline(baselinePath(evolutionDir));
+  const offending = new Set((baseline?.violations ?? []).map((item) => item.skill));
+  // 最近一次相关 run：listRuns 已按派生时间倒序，第一个命中的就是最新的
+  const lastRun = new Map<string, { runId: string; at: number | null }>();
+  for (const run of listRuns(evolutionDir, RUN_SCAN_LIMIT)) {
+    const skill = run.proposal?.skill;
+    if (!skill || lastRun.has(skill)) continue;
+    lastRun.set(skill, { runId: run.runId, at: run.dispatchedAt });
+  }
+  const rows: SkillRow[] = listSkillDirs(path.join(root, ".pi", "skills")).map((name) => {
+    const exposed = exposure.get(name) ?? 0;
+    const loadCount = loaded.get(name) ?? 0;
+    return {
+      name,
+      exposed,
+      loaded: loadCount,
+      rate: exposed === 0 ? null : ratio(loadCount, exposed),
+      lastRunId: lastRun.get(name)?.runId ?? null,
+      lastRunAt: lastRun.get(name)?.at ?? null,
+      hasPendingProposal: pending.has(name),
+      hasBaseline: offending.has(name),
+      missingCursorStub: !CURSOR_STUB_EXEMPT.has(name) && !hasFile(path.join(root, ".cursor", "skills", name, "SKILL.md")),
+    };
+  });
+  return { days, rows, telemetryOn: options.telemetryOn === true, events: events.length };
+}
+
+/** 技能详情：这一行的统计 + 它所有历史提案（每个 run 一行，带 verdict 与 diff 链接） */
+export function readSkillDetail(
+  evolutionDir: string,
+  name: string,
+  options: SkillsOptions = {},
+): SkillDetail {
+  const view = readSkills(evolutionDir, options);
+  const runs: SkillRunRow[] = [];
+  for (const run of listRuns(evolutionDir, RUN_SCAN_LIMIT)) {
+    if (run.proposal?.skill !== name) continue;
+    runs.push({
+      runId: run.runId,
+      status: run.status,
+      at: run.dispatchedAt,
+      type: run.proposal.type,
+      added: run.proposal.added,
+      removed: run.proposal.removed,
+      verdict: run.review?.verdict ?? "—",
+      action: run.review?.action ?? "—",
+    });
+  }
+  return {
+    name,
+    days: view.days,
+    row: view.rows.find((row) => row.name === name) ?? null,
+    runs,
+    telemetryOn: view.telemetryOn,
+    events: view.events,
+  };
+}

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

@@ -0,0 +1,107 @@
+/**
+ * 面板的内联样式：单文件放着是因为只有一处消费（render.ts），拆出来只是为了把 render.ts 压在 300 行内。
+ * 不引外部 CSS：面板必须离线可用，一条网络请求都不发。
+ */
+export const STYLE = `
+:root { color-scheme: dark }
+* { box-sizing: border-box }
+body { margin: 0; padding: 24px; background: #0f1115; color: #d7dce5;
+  font: 14px/1.6 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace }
+h1 { margin: 0 0 4px; font-size: 18px; font-weight: 600 }
+.bar { margin: 0 0 16px; color: #8d99ae }
+.bar a { color: #7cc4ff; text-decoration: none }
+.notice { margin: 0 0 12px; padding: 8px 12px; border-left: 2px solid #3f9d5a; background: #131a17; color: #b6e2c4 }
+.notice.err { border-left-color: #c05c5c; background: #1a1313; color: #f0bdbd }
+nav { display: flex; gap: 12px; margin-bottom: 16px; border-bottom: 1px solid #232733; padding-bottom: 8px }
+nav a { color: #8d99ae; text-decoration: none; padding: 2px 8px; border-radius: 4px }
+nav a:hover { background: #1a1f29 }
+nav a.active { color: #0f1115; background: #7cc4ff }
+ul { list-style: none; margin: 0; padding: 0 }
+li.row { border-bottom: 1px solid #1c202a; padding: 8px 0 }
+summary.head { cursor: pointer; color: #cfe3ff }
+span.head { color: #cfe3ff }
+pre { margin: 8px 0 0; padding: 12px; background: #141821; border-left: 2px solid #2b3342;
+  white-space: pre-wrap; word-break: break-word; color: #aeb7c4 }
+.empty { color: #6f7a8c; padding: 24px 0 }
+.acts { display: flex; gap: 8px; margin-top: 8px }
+.acts form { display: inline; margin: 0 }
+button { font: inherit; color: #0f1115; background: #7cc4ff; border: 0; border-radius: 4px; padding: 2px 12px; cursor: pointer }
+button.reject { background: #6f7a8c; color: #0f1115 }
+button.danger { background: #c05c5c; color: #fff }
+button:hover { filter: brightness(1.1) }
+/* 顶部控制条：开关状态、切换/立即复盘按钮、最后活动 */
+.ctl { display: flex; align-items: center; gap: 10px; flex-wrap: wrap;
+  margin: 0 0 16px; padding: 8px 12px; background: #141821; border: 1px solid #232733; border-radius: 6px }
+.ctl form { display: inline; margin: 0 }
+.ctl .state { padding: 1px 8px; border-radius: 4px }
+.ctl .state.on { background: #16301f; color: #b6e2c4 }
+.ctl .state.off { background: #2a1f1f; color: #e6b0b0 }
+.ctl .act { color: #8d99ae }
+/* 单个开关：状态 + 后果说明 + 按钮竖排，两个开关之间靠 .ctl 的 gap 分隔 */
+.ctl .sw { display: inline-flex; align-items: center; gap: 6px }
+.ctl .hint { color: #8d99ae; font-size: 12px }
+.warn { margin: 6px 0 0; padding: 6px 10px; border-left: 3px solid #b58900;
+  background: #2a2418; color: #e8d9a8 }
+/* 筛选表单与翻页：零 JS，样式也要看得出它们是一组 */
+.filter { display: flex; align-items: center; gap: 12px; flex-wrap: wrap;
+  margin: 0 0 12px; padding: 8px 12px; background: #141821; border: 1px solid #232733; border-radius: 6px }
+.filter label { color: #8d99ae }
+.filter input, .filter select { font: inherit; color: #d7dce5; background: #0f1115;
+  border: 1px solid #2b3342; border-radius: 4px; padding: 1px 6px }
+.page { display: flex; gap: 12px; align-items: center; margin: 12px 0 0; color: #8d99ae }
+.page a { color: #7cc4ff; text-decoration: none }
+.page .count { color: #6f7a8c }
+.off { color: #3f4654 }
+a.btn { color: #7cc4ff; text-decoration: none; padding: 2px 10px; border: 1px solid #2b3342; border-radius: 4px }
+a.btn:hover { background: #1a1f29 }
+/* 最近操作：结果分三色，ok / partial / error 扫一眼就能分开 */
+.audit { margin-top: 24px; padding-top: 12px; border-top: 1px solid #232733 }
+.audit h2 { margin: 0 0 8px; font-size: 14px; font-weight: 600; color: #8d99ae }
+.audit li { padding: 2px 0; color: #aeb7c4 }
+.audit .when { color: #6f7a8c }
+.audit code { font: inherit; color: #cfe3ff }
+.ok { color: #7fc78f }
+.partial { color: #d6b25e }
+.fail { color: #e08585 }
+/* 表格：评审 blocking / 五闸 / 发现 / 技能管理都用同一套，避免每处各写一份颜色 */
+.tbl { border-collapse: collapse; width: 100%; margin: 8px 0 0; font-size: 13px }
+.tbl th, .tbl td { border-bottom: 1px solid #1c202a; padding: 4px 8px; text-align: left; vertical-align: top }
+.tbl th { color: #8d99ae; font-weight: 600 }
+.tbl a { color: #7cc4ff; text-decoration: none }
+/* 状态标签：三个标签三色，合成一个就分不出该去批、去改还是去补 stub */
+.tag { display: inline-block; padding: 0 6px; border-radius: 4px; background: #1a1f29; color: #aeb7c4; font-size: 12px }
+.tag.warn { background: #2a2418; color: #e8d9a8 }
+.tag.fail { background: #2a1616; color: #f0bdbd }
+.hint { color: #8d99ae; font-size: 12px }
+.days { margin: 0 0 8px; color: #8d99ae }
+.days a { color: #7cc4ff; text-decoration: none }
+.days .on { color: #d7dce5; padding: 0 6px; background: #1a1f29; border-radius: 4px }
+/* run 详情页的概要：左标签右值，两列对齐才好扫 */
+.kv { display: grid; grid-template-columns: 6em 1fr; gap: 2px 12px; margin: 8px 0 0 }
+.kv-row { display: contents }
+.kv .k { color: #8d99ae }
+.kv .v { color: #d7dce5 }
+.kv-line { margin: 4px 0 }
+.kv .v code { font: inherit; color: #cfe3ff }
+a.run { color: #cfe3ff; text-decoration: none; border-bottom: 1px dashed #3f4654 }
+a.run:hover { border-bottom-color: #7cc4ff }
+h2 { margin: 20px 0 6px; font-size: 15px; font-weight: 600; color: #cfe3ff }
+/* diff：文件头灰底、hunk 灰字、+ 绿底、- 红底；行号两列宽固定，不随内容抹动 */
+.diff { margin: 8px 0 0; padding: 8px 0; background: #0c0e12; border: 1px solid #232733; border-radius: 6px;
+  overflow-x: auto; white-space: pre; font-size: 12.5px; line-height: 1.5 }
+.diff .dl { display: block; padding: 0 8px }
+/* 长行必须横向滚动而不是被裁掉：技能 description 动辄两三百字，截断等于看不见改了什么 */
+.diff { overflow-x: auto }
+.diff .dl { min-width: max-content }
+.diff .ln { display: inline-block; width: 4.5em; color: #4a5364; text-align: right; padding-right: 8px; user-select: none }
+.diff .tx { white-space: pre }
+.diff .file { background: #22262f; color: #b8c1d1 }
+.diff .hunk { color: #8d99ae }
+.diff .add { background: #12281a; color: #b7e7c5 }
+.diff .del { background: #2a1616; color: #f0bdbd }
+.diff .meta { color: #6f7a8c }
+/* 改后全文：长文件限高内部滚动，别把后面的评审/五闸顶到屏幕外 */
+.candidate { max-height: 480px; overflow: auto }
+footer { margin-top: 24px; padding-top: 12px; border-top: 1px solid #232733; color: #6f7a8c }
+footer a { color: #7cc4ff }
+`.trim();

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

@@ -0,0 +1,52 @@
+/**
+ * 面板上的文本格式化：转义、时间戳、短 runId。
+ *
+ * 单独一份是因为渲染层的三个文件（骨架 / 列表行 / 控制条）都要用它们，
+ * 放在其中一个里会变成「A 引 B、B 又引 A」的循环。
+ *
+ * 为什么全转义：页面里的每个字都来自 run 产物与技能文件，而复盘内容本来就是「模型写的自由文本」
+ * —— 一条 findings 里出现 `<script>` 完全可能。只要漏一个 `escapeHtml`，面板就成了本地 XSS 的跳板
+ * （面板虽只绑 127.0.0.1，但同一台机器上的任意进程/浏览器标签都能打到它）。
+ */
+
+/** 五个字符全部要转：`'` 与 `"` 用于属性值，`&` 必须先转，否则实体会被二次解码 */
+export function escapeHtml(text: string): string {
+  return text.replace(/[&<>"']/g, (char) => {
+    switch (char) {
+      case "&":
+        return "&amp;";
+      case "<":
+        return "&lt;";
+      case ">":
+        return "&gt;";
+      case '"':
+        return "&quot;";
+      default:
+        return "&#39;";
+    }
+  });
+}
+
+/** 本地时间 `YYYY-MM-DD HH:mm`：面板上全是同一时区的人在看，不折腾 ISO */
+export function formatStamp(ts: number | null): string {
+  if (ts === null || !Number.isFinite(ts)) return "—";
+  const date = new Date(ts);
+  const pad = (value: number): string => String(value).padStart(2, "0");
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+
+/**
+ * 列表里的短 runId：同一会话的 runId 都是 `<sessionHash8>-<时间戳>`，前缀一模一样，
+ * 全量打印会变成一列看不出区别的字符串。保留前 8 + 后 4，完整值放详情里。
+ */
+export function shortRunId(runId: string): string {
+  return runId.length > 16 && runId.includes("-") ? `${runId.slice(0, 8)}…${runId.slice(-4)}` : runId;
+}
+
+/**
+ * 详情第一行永远是完整 runId：列表上显示的是缩写，复制要靠这一行。
+ * 文案里带 `runId：` 前缀是因为详情区是纯文本，没有别的办法标出这一行是什么。
+ */
+export function withId(runId: string, detail: string): string {
+  return detail.length > 0 ? `runId：${runId}\n${detail}` : `runId：${runId}`;
+}

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

@@ -0,0 +1,36 @@
+/**
+ * 「清理记录」的落地：把 `runs/<runId>/` 移到 `runs/.trash/<runId>-<时间戳>/`。
+ *
+ * 为什么是移动而不是删除：清理只是把卡死的 run 从列表里挪走，数据必须还能捞回来 ——
+ * 复盘目录里有会话原文、findings、候选稿，删掉就真没了。`.trash/` 已在 .gitignore 里，
+ * 要腾空间时由人手动 rm，不由一次网页点击决定。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { resolveRunDir } from "./run-path.ts";
+
+export const TRASH_DIR = ".trash";
+
+/** 目录名里的时间戳：人读得懂，且同一 run 多次清理不会撞名 */
+function stamp(ts: number): string {
+  const date = new Date(ts);
+  const pad = (value: number): string => String(value).padStart(2, "0");
+  return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+}
+
+/**
+ * 移动成功返回一句人话（带相对路径，方便人去捞）。
+ * 失败抛 Error：所有「不该发生」的分支都在这里挡住，绝不静默跳过 —— 静默跳过会让人以为清掉了，其实还在列表里。
+ */
+export function moveRunToTrash(evolutionDir: string, runId: string, now = Date.now()): string {
+  const runDir = resolveRunDir(evolutionDir, runId);
+  if (runDir === null) throw new Error(`runId 不合法：${runId}`);
+  if (!fs.existsSync(runDir)) throw new Error(`找不到 run 目录：runs/${runId}`);
+  const trashRoot = path.join(evolutionDir, "runs", TRASH_DIR);
+  fs.mkdirSync(trashRoot, { recursive: true });
+  const target = path.join(trashRoot, `${runId}-${stamp(now)}`);
+  // rename 到已存在的目录会在部分平台上静默合并，所以先显式拒绝（同一秒内点两次就会碰到）
+  if (fs.existsSync(target)) throw new Error(`目标已存在，未移动：runs/${TRASH_DIR}/${path.basename(target)}`);
+  fs.renameSync(runDir, target);
+  return `已清理 ${runId}：移动到 runs/${TRASH_DIR}/${path.basename(target)}（可逆，没有删数据）`;
+}