pi-skill-evolve 0.0.0-stage → 0.1.0

package/extensions/skill-evolve/lib/web/diff-lines.ts

@@ -0,0 +1,141 @@
+/**
+ * 统一 diff 的解析与渲染（纯函数：不读盘、不拼页面、不发请求）。
+ *
+ * 为什么自己写而不塞进 render-run.ts：解析（行号计数、hunk 边界）是最容易出错的一段，
+ * 单独一个文件才能用喂字符串的方式把 hunk 计数、`\ No newline`、`<script>` 这些边界一个个钉住。
+ *
+ * 三条纪律：
+ * 1. **全部转义**：diff 里出现 `<` `&` `-->` 是常态，渲染前逐行 escapeHtml，绝不拼原始字符串；
+ * 2. **行号靠 hunk 头推**：`@@ -1,3 +1,4 @@` 只给起点，之后的增删各自推进哪一列必须算对，
+ *    算错的后果是「用户对着行号去改文件，改错行」；
+ * 3. **超长先截断**：一个技能 SKILL.md 的 diff 可能上千行，一次全渲会把页面卡住；
+ *    截断后由调用方给「完整 diff」下载链接（`GET /diff?runId=`）。
+ */
+import { escapeHtml } from "./text.ts";
+
+/** 页面内联预览行数上限：超过就只渲前 400 行 + 下载链接 */
+export const DIFF_PREVIEW_LINES = 400;
+
+/** 一行的角色：文件头 / hunk 头 / 增 / 删 / 上下文 / 其它元信息（`diff --git`、`\ No newline`） */
+export type DiffLineKind = "file" | "hunk" | "add" | "del" | "ctx" | "meta";
+
+export interface DiffLine {
+  kind: DiffLineKind;
+  /** 原文（未转义，渲染时才转义） */
+  text: string;
+  /** 旧文件行号；增行与元信息为 null */
+  oldLine: number | null;
+  /** 新文件行号；删行与元信息为 null */
+  newLine: number | null;
+}
+
+/** `@@ -旧起点[,旧行数] +新起点[,新行数] @@ 可选的小节标题` */
+const HUNK_HEADER = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/;
+
+/**
+ * 逐行解析统一 diff。
+ *
+ * 行号规则（与 `git diff` / `patch` 的输出一致）：
+ * - `@@` 头把两个计数器重置为头里给的起点；
+ * - 上下文行两边都加一；
+ * - `+` 只推进新行号，`-` 只推进旧行号；
+ * - hunk 之外的行（`diff --git`、`index`、`\ No newline`）不给行号。
+ */
+export function parseDiffLines(text: string): DiffLine[] {
+  const raw = text.split(/\r?\n/);
+  // 末尾换行会 split 出一个空串：它不是一个空行，丢掉它，否则行号与真实文件差一行
+  if (raw.length > 0 && raw[raw.length - 1] === "") raw.pop();
+  const lines: DiffLine[] = [];
+  let oldCursor = 0;
+  let newCursor = 0;
+  let inHunk = false;
+  for (const line of raw) {
+    const hunk = HUNK_HEADER.exec(line);
+    if (hunk) {
+      oldCursor = Number(hunk[1]);
+      newCursor = Number(hunk[2]);
+      inHunk = true;
+      lines.push({ kind: "hunk", text: line, oldLine: null, newLine: null });
+      continue;
+    }
+    if (line.startsWith("--- ") || line.startsWith("+++ ")) {
+      inHunk = false;
+      lines.push({ kind: "file", text: line, oldLine: null, newLine: null });
+      continue;
+    }
+    if (line.startsWith("\\")) {
+      // ""：不算行，也不推计数器
+      lines.push({ kind: "meta", text: line, oldLine: null, newLine: null });
+      continue;
+    }
+    if (inHunk && line.startsWith("+")) {
+      lines.push({ kind: "add", text: line, oldLine: null, newLine: newCursor });
+      newCursor += 1;
+      continue;
+    }
+    if (inHunk && line.startsWith("-")) {
+      lines.push({ kind: "del", text: line, oldLine: oldCursor, newLine: null });
+      oldCursor += 1;
+      continue;
+    }
+    if (inHunk) {
+      // 上下文行（含以空格开头、以及被裁掉前导空格的空行）
+      lines.push({ kind: "ctx", text: line, oldLine: oldCursor, newLine: newCursor });
+      oldCursor += 1;
+      newCursor += 1;
+      continue;
+    }
+    lines.push({ kind: "meta", text: line, oldLine: null, newLine: null });
+  }
+  return lines;
+}
+
+const KIND_CLASS: Record<DiffLineKind, string> = {
+  file: "dl file",
+  hunk: "dl hunk",
+  add: "dl add",
+  del: "dl del",
+  ctx: "dl ctx",
+  meta: "dl meta",
+};
+
+function lineNumber(value: number | null, width: number): string {
+  return value === null ? " ".repeat(width) : String(value).padStart(width, " ");
+}
+
+/** 行号列宽度：取本段最大行号的位数（截断后按可见段算，避免 5 位行号把 3 位全挤歪） */
+function numberWidth(lines: readonly DiffLine[]): number {
+  let widest = 1;
+  for (const line of lines) {
+    for (const value of [line.oldLine, line.newLine]) {
+      if (value !== null) widest = Math.max(widest, String(value).length);
+    }
+  }
+  return widest;
+}
+
+/** 渲染成 `<pre class="diff">`；每行 `<span class="ln old">` + `<span class="ln new">` + 原文 */
+export function renderDiffLines(lines: readonly DiffLine[]): string {
+  const width = numberWidth(lines);
+  const rows = lines.map((line) => {
+    const old = lineNumber(line.oldLine, width);
+    const next = lineNumber(line.newLine, width);
+    return `<span class="${KIND_CLASS[line.kind]}"><span class="ln old">${old}</span><span class="ln new">${next}</span><span class="tx">${escapeHtml(line.text)}</span></span>`;
+  });
+  return `<pre class="diff">${rows.join("\n")}</pre>`;
+}
+
+export interface DiffView {
+  html: string;
+  /** diff 总行数（截断前的） */
+  total: number;
+  /** 是否被截断（调用方据此加「完整 diff」下载链接） */
+  truncated: boolean;
+}
+
+/** 解析 + 渲染 + 截断一步到位：`maxLines` 默认 400，只渲前 400 行 */
+export function renderDiff(text: string, maxLines: number = DIFF_PREVIEW_LINES): DiffView {
+  const lines = parseDiffLines(text);
+  const shown = lines.slice(0, maxLines);
+  return { html: renderDiffLines(shown), total: lines.length, truncated: lines.length > shown.length };
+}

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

@@ -0,0 +1,203 @@
+/**
+ * 列表筛选 + 分页：五个列表页（待处理 / 待审批 / 已采纳 / 已处理 / 复盘报告）共用一套 query 语义。
+ *
+ * 为什么全用 GET query：面板零 JS，筛选必须能拷链接、能进浏览历史、刷新即最新；
+ * 为什么页码在这里算而不是在渲染层：同一份 filter 决定「取哪 20 条」与「第 X / Y 页」，
+ * 两处各算一次必然出现「页脚说 3 页、列表只有 2 页内容」。
+ *
+ * 筛选参数怎么落到条目上（三页字段名不同，这一层是唯一的转换点）：
+ * - `skill` 精确匹配（不是模糊）：技能名本身就是完整标识，模糊匹配只会让人找不到自己要的那一个；
+ * - `status` 精确匹配：待处理页没有 status 字段，用 kind 一一映射（running/stale/reviewed 同名，
+ *   approval 映射成 `approval` —— 页面上看到的就是这个词）；
+ * - `range` 按条目自己的时间字段算：待处理/已处理用 `at`，报告用 `startedAt`；取不到时间的一律**不**落进带范围的筛选
+ *   （宁可让它只在 `range=all` 出现，也不能让「不知道时间」冒充「最近 7 天」）。
+ */
+import type { AppliedItem, ApprovalItem, DoneItem, PendingItem, RunReport, WebState, WebView } from "./data.ts";
+import { WEB_VIEWS } from "./data.ts";
+
+export const PAGE_SIZE = 20;
+export const RANGE_KEYS = ["24h", "7d", "30d", "all"] as const;
+export type RangeKey = (typeof RANGE_KEYS)[number];
+export const DEFAULT_RANGE: RangeKey = "7d";
+export const RANGE_LABEL: Record<RangeKey, string> = {
+  "24h": "最近 24 小时",
+  "7d": "最近 7 天",
+  "30d": "最近 30 天",
+  all: "全部时间",
+};
+
+/** 状态下拉的可选值：既有 run 终态，也有待处理页自己的两种（running / stale） */
+export const STATUS_OPTIONS = ["running", "stale", "reviewed", "applied", "rejected", "failed", "analyzed"] as const;
+
+export interface ListFilter {
+  skill: string;
+  /** 空串 = 全部 */
+  status: string;
+  range: RangeKey;
+  /** 从 1 开始；非法或越界都在 paginate 里归位，不在这里猜 */
+  page: number;
+}
+
+export const NO_FILTER: ListFilter = { skill: "", status: "", range: "all", page: 1 };
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** 范围起点；`all` 返回 null 表示不限 */
+export function rangeStart(range: RangeKey, now: number): number | null {
+  switch (range) {
+    case "24h":
+      return now - DAY_MS;
+    case "7d":
+      return now - 7 * DAY_MS;
+    case "30d":
+      return now - 30 * DAY_MS;
+    default:
+      return null;
+  }
+}
+
+/** 解析 query：缺省 range 用默认 7d，缺省 page 用 1；未知值一律回落默认，不报错（筛选是浏览工具，不该 400） */
+export function parseListQuery(params: URLSearchParams): ListFilter {
+  const range = params.get("range") ?? "";
+  const page = Number.parseInt(params.get("page") ?? "1", 10);
+  return {
+    skill: (params.get("skill") ?? "").trim(),
+    status: (params.get("status") ?? "").trim(),
+    range: (RANGE_KEYS as readonly string[]).includes(range) ? (range as RangeKey) : DEFAULT_RANGE,
+    page: Number.isFinite(page) && page >= 1 ? page : 1,
+  };
+}
+
+/**
+ * 分页结果就是渲染层唯一的数据来源：`page` 是归位之后的真实页码（越界会被夹到最后一页），
+ * `pages` 至少是 1（空列表也要显示「第 1 / 1 页，共 0 条」，否则页脚会消失，人以为筛选坏了）。
+ */
+export function paginate<T>(
+  rows: readonly T[],
+  page: number,
+): { rows: T[]; page: number; pages: number; total: number } {
+  const total = rows.length;
+  const pages = Math.max(1, Math.ceil(total / PAGE_SIZE));
+  const current = Math.min(Math.max(1, Math.trunc(page)), pages);
+  const start = (current - 1) * PAGE_SIZE;
+  return { rows: rows.slice(start, start + PAGE_SIZE), page: current, pages, total };
+}
+
+/** 列表页的数据形状：`view` 是判别字段，渲染层据此拿到强类型的 rows */
+export type ViewPage =
+  | { view: "pending"; rows: PendingItem[]; page: number; pages: number; total: number }
+  | { view: "approvals"; rows: ApprovalItem[]; page: 1; pages: 1; total: number }
+  | { view: "applied"; rows: AppliedItem[]; page: number; pages: number; total: number }
+  | { view: "done"; rows: DoneItem[]; page: number; pages: number; total: number }
+  | { view: "reports"; rows: RunReport[]; page: number; pages: number; total: number };
+
+const PENDING_STATUS: Record<PendingItem["kind"], string> = {
+  running: "running",
+  stale: "stale",
+  reviewed: "reviewed",
+  approval: "approval",
+};
+
+/** 时间是否落进范围：`at` 为 null 的条目只有不限范围时才出现（见文件头「不冒充最近 N 天」） */
+function inRange(at: number | null, filter: ListFilter, now: number): boolean {
+  const start = rangeStart(filter.range, now);
+  if (start === null) return true;
+  return at !== null && at >= start;
+}
+
+function skillMatched(skill: string, filter: ListFilter): boolean {
+  return filter.skill.length === 0 || skill === filter.skill;
+}
+
+function statusMatched(status: string, filter: ListFilter): boolean {
+  return filter.status.length === 0 || status === filter.status;
+}
+
+/** 报告页的技能名藏在提案里：没有提案（还没到出稿那一步）就是空串，只在「全部技能」时命中 */
+function reportSkill(item: RunReport): string {
+  return item.proposal?.skill ?? "";
+}
+
+/** 待处理没有分页（它天然很短，且有 5 秒自动刷新，翻页会把人翻丢） */
+export function buildViewPage(state: WebState, view: WebView, filter: ListFilter, now: number): ViewPage {
+  if (view === "approvals") {
+    return { view, rows: state.approvals, page: 1, pages: 1, total: state.approvals.length };
+  }
+  if (view === "applied") {
+    // 已采纳页的状态只有一个值（applied），下拉里选别的就什么都不剩 —— 这是筛选的真结果，不是 bug
+    const rows = state.applied.filter(
+      (item) =>
+        skillMatched(item.skill, filter) &&
+        (filter.status.length === 0 || filter.status === "applied") &&
+        inRange(item.appliedAt, filter, now),
+    );
+    return { view, ...paginate(rows, filter.page) };
+  }
+  if (view === "done") {
+    const rows = state.done.filter(
+      (item) => skillMatched(item.skill, filter) && statusMatched(item.status, filter) && inRange(item.at, filter, now),
+    );
+    return { view, ...paginate(rows, filter.page) };
+  }
+  if (view === "reports") {
+    const rows = state.reports.filter(
+      (item) =>
+        skillMatched(reportSkill(item), filter) &&
+        statusMatched(item.status, filter) &&
+        inRange(item.startedAt, filter, now),
+    );
+    return { view, ...paginate(rows, filter.page) };
+  }
+  const rows = state.pending.filter(
+    (item) =>
+      skillMatched(item.skill, filter) &&
+      statusMatched(PENDING_STATUS[item.kind], filter) &&
+      inRange(item.at, filter, now),
+  );
+  return { view, ...paginate(rows, filter.page) };
+}
+
+/** 生成翻页链接：必须带上其它筛选参数，否则点下一页等于把筛选清空 */
+export function pageHref(view: WebView, filter: ListFilter, page: number): string {
+  const params = new URLSearchParams({ view, range: filter.range, page: String(page) });
+  if (filter.skill.length > 0) params.set("skill", filter.skill);
+  if (filter.status.length > 0) params.set("status", filter.status);
+  return `/?${params.toString()}`;
+}
+
+/**
+ * `?view=` → 页面名。只认白名单，其它（含 null、空串、`../`）一律回落待处理页 ——
+ * 这个值会进 `<a href>` 与 303 的 location，所以必须是枚举而不是原样回显。
+ */
+export function parseView(raw: string | null): WebView {
+  return (WEB_VIEWS as readonly string[]).includes(raw ?? "") ? (raw as WebView) : "pending";
+}
+
+/**
+ * 面板上的全部页面：五个列表页 + 技能管理 + 两个详情页。
+ *
+ * 详情页（run / skill）与技能管理页**需要额外参数**（runId / name / days），所以它们不能进 `VIEW_ORDER`,
+ * 也不能靠 `parseView` 认 —— 这是两件事，两个函数各自负责一件事。
+ */
+export const PANEL_VIEWS = [...WEB_VIEWS, "skills", "skill", "run"] as const;
+export type PanelView = (typeof PANEL_VIEWS)[number];
+
+/** `?view=` → 全页面名；只认白名单，其余（含 null、`../`）回落待处理页 */
+export function parsePanelView(raw: string | null): PanelView {
+  return (PANEL_VIEWS as readonly string[]).includes(raw ?? "") ? (raw as PanelView) : "pending";
+}
+
+/**
+ * 303 回跳只能落在「能显示横幅」的页：列表页 + 技能管理。
+ * 详情页回跳会丢参数（`?view=run` 没有 runId 就是 404），所以它们一律归一成待处理页。
+ */
+export function parseRedirectView(raw: string | null): WebView | "skills" {
+  const view = parsePanelView(raw);
+  if (view === "skills") return "skills";
+  return (WEB_VIEWS as readonly string[]).includes(view) ? (view as WebView) : "pending";
+}
+
+/** 是不是「什么都没筛」（默认 range=7d、第 1 页）：待处理页的自动刷新靠它决定 URL 要不要带参数 */
+export function isDefaultFilter(filter: ListFilter): boolean {
+  return filter.skill.length === 0 && filter.status.length === 0 && filter.page === 1 && filter.range === DEFAULT_RANGE;
+}

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

@@ -0,0 +1,68 @@
+/**
+ * 面板的 HTTP 底层小工具：发响应、303 回跳、Host/Origin 校验、读表单体。
+ *
+ * 抽出来只有一个理由：写操作（actions.ts）与路由（server.ts）都要用，而这套校验必须只有一份 ——
+ * 两处各写一遍，迟早出现「/action 比 /approve 松一点」的洞。
+ */
+import type * as http from "node:http";
+
+export const HTML_TYPE = "text/html; charset=utf-8";
+export const TEXT_TYPE = "text/plain; charset=utf-8";
+export const FORM_TYPE = "application/x-www-form-urlencoded";
+/** 表单请求体上限：几个 hidden 字段 + runId，2KB 已经是一百倍余量；超了就是有人在探 */
+export const MAX_BODY_BYTES = 2048;
+
+export function sendText(res: http.ServerResponse, status: number, text: string, type = TEXT_TYPE): void {
+  res.writeHead(status, { "content-type": type, "cache-control": "no-store" });
+  res.end(text);
+}
+
+/**
+ * 303 回跳：结果首行进 query，页面顶部渲染成横幅；绝不把错误变成 500 页。
+ * `view` 决定回哪一页 —— 审批动作回待审批页，控制条动作回点按钮时那一页。
+ */
+export function sendBack(
+  res: http.ServerResponse,
+  key: "msg" | "err",
+  text: string,
+  view = "approvals",
+): void {
+  // 首行够用：approve 的结论是多行五闸明细，全塞进 URL 只会又长又难读
+  const line = text.split("\n")[0]!.trim().slice(0, 300) || (key === "msg" ? "完成" : "失败（无详情）");
+  res.writeHead(303, {
+    location: `/?view=${view}&${key}=${encodeURIComponent(line)}`,
+    "content-type": TEXT_TYPE,
+    "cache-control": "no-store",
+  });
+  res.end(`${line}\n`);
+}
+
+/**
+ * Host / Origin 校验：只认本机当前端口。
+ *
+ * 浏览器同源表单提交一定带 `Origin: http://<Host>`，所以两者一致就够了；
+ * 命令行 curl 不带 Origin（也就不带浏览器自动附带的凭据），此时靠 csrf 兜底。
+ */
+export function sourceDenied(request: http.IncomingMessage, port: number): string | null {
+  const host = String(request.headers.host ?? "").toLowerCase();
+  if (host !== `127.0.0.1:${port}` && host !== `localhost:${port}`) {
+    return "Host 头不在白名单（只认 127.0.0.1 / localhost 的当前端口）";
+  }
+  const origin = request.headers.origin;
+  if (origin !== undefined && origin.toLowerCase() !== `http://${host}`) return "Origin 头与面板地址不一致";
+  return null;
+}
+
+/** 读表单请求体：超过上限返回 null（继续把剩余的流读掉，避免客户端卡在写一半） */
+export function readBody(request: http.IncomingMessage, limit: number): Promise<string | null> {
+  return new Promise((resolve) => {
+    const chunks: Buffer[] = [];
+    let total = 0;
+    request.on("data", (chunk: Buffer) => {
+      total += chunk.length;
+      if (total <= limit) chunks.push(chunk);
+    });
+    request.on("end", () => resolve(total > limit ? null : Buffer.concat(chunks).toString("utf8")));
+    request.on("error", () => resolve(null));
+  });
+}

package/extensions/skill-evolve/lib/web/json-read.ts

@@ -0,0 +1,33 @@
+/**
+ * 只读面板的防御式 JSON 读取：`runs/` 里的文件随时可能「写到一半被 kill」，
+ * 所以所有解析都走这里 —— 读不到 / 坏 JSON 一律 null，调用方各自退化成空，绝不让一页 500。
+ */
+import * as fs from "node:fs";
+import { DISPOSITIONS } from "../attribution.ts";
+
+export function readJson<T>(file: string): T | null {
+  try {
+    const raw = fs.readFileSync(file, "utf8");
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}
+
+export function asText(value: unknown, fallback = ""): string {
+  return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+
+export function asNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+export function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
+}
+
+/** 归因编码（A~E / semantic / F / G）加一句中文标签：光看字母没人知道 B 是 frontmatter 坏 */
+export function reasonLabel(code: string): string {
+  const disposition = DISPOSITIONS[code as keyof typeof DISPOSITIONS];
+  return disposition ? `${code} ${disposition.label}` : code;
+}

package/extensions/skill-evolve/lib/web/panel-pid.ts

@@ -0,0 +1,99 @@
+/**
+ * 「谁持有 Web 面板」的落盘记录：`.pi/evolution/locks/web.json`。
+ *
+ * 为什么要有它：面板的 HTTP 服务跑在 pi 进程内（见 ./server.ts），端口被占时
+ * `lsof -ti:7788 | xargs kill` 会连 pi 一起杀掉。把「pid + 地址 + 起于何时」写下来，
+ * 说「端口被占」时才能分清「本机面板在跑」与「别的服务占了端口」，清理动作不必靠猜 PID。
+ *
+ * 三条边界：
+ * 1. **只记事实，不承担互斥**：跨进程互斥是 lib/lock.ts 的 dispatch 目录锁；这份文件坏了当没有，
+ *    绝不能让面板因为记录文件起不来；
+ * 2. **写失败只记日志**：此时面板已经监听成功，丢记录顶多让「占用提示」少一层判读依据；
+ * 3. **删记录要比 pid**：只有文件里的 pid 就是调用方时才删，否则会抹掉另一个实例的活记录。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isPidAlive } from "../lock.ts";
+
+/** 记录文件的相对位置（相对 evolutionDir）；绝对路径见 webPidFile() */
+export const WEB_PID_FILE = path.join("locks", "web.json");
+
+export interface WebPidInfo {
+  /** 持有面板的进程（= pi 主进程）pid */
+  pid: number;
+  host: string;
+  /** 实际监听端口：`port: 0` 时是内核分配的端口，不是请求值 */
+  port: number;
+  /** 面板地址（`http://host:port`），提示语直接给用户复制 */
+  url: string;
+  /** 起监听的毫秒戳 */
+  startedAt: number;
+}
+
+export function webPidFile(evolutionDir: string): string {
+  return path.join(evolutionDir, WEB_PID_FILE);
+}
+
+/** 默认日志口：面板已经在跑，记录写失败只能落日志，不能反过来把面板搞挂 */
+const defaultLog = (msg: string): void => console.error(msg);
+
+/**
+ * 写记录（原子）：先写 `web.json.tmp` 再 rename —— 同盘 rename 是原子的，
+ * 读方永远看不到半截 JSON。任何失败都只记日志、不抛、不留 `.tmp` 垃圾。
+ */
+export function writeWebPid(evolutionDir: string, info: WebPidInfo, log: (msg: string) => void = defaultLog): void {
+  const file = webPidFile(evolutionDir);
+  const tmp = `${file}.tmp`;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(tmp, `${JSON.stringify(info)}\n`, "utf8");
+    fs.renameSync(tmp, file);
+  } catch (error) {
+    log(`[skill-evolve] 写 Web 面板记录失败（面板本身照常运行）：${String(error)}`);
+    try {
+      fs.rmSync(tmp, { force: true });
+    } catch {
+      // 读方只认 web.json，.tmp 清不掉也不影响判读
+    }
+  }
+}
+
+/**
+ * 读记录：坏 JSON、类型不对、字段缺失都返回 null（调用方一律按「没有记录」处理）。
+ * `port` / `startedAt` 也要求合法，否则提示语会出现 `NaN` 或 1970 年这种假信息。
+ */
+export function readWebPid(evolutionDir: string): WebPidInfo | null {
+  try {
+    const raw: unknown = JSON.parse(fs.readFileSync(webPidFile(evolutionDir), "utf8"));
+    if (!raw || typeof raw !== "object") return null;
+    const info = raw as Partial<WebPidInfo>;
+    const { pid, host, port, url, startedAt } = info;
+    if (!Number.isInteger(pid) || (pid as number) <= 0) return null;
+    if (typeof host !== "string" || host.length === 0) return null;
+    if (!Number.isInteger(port) || (port as number) <= 0) return null;
+    if (typeof url !== "string" || url.length === 0) return null;
+    if (typeof startedAt !== "number" || !Number.isFinite(startedAt)) return null;
+    return { pid: pid as number, host, port: port as number, url, startedAt: startedAt as number };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 删记录：只有文件里的 pid 等于调用方 pid 时才删。
+ * 别人的记录（或读不出来的坏记录）一律不动 —— 无法证明是自己写的，就不该改。
+ */
+export function clearWebPid(evolutionDir: string, callerPid: number, log: (msg: string) => void = defaultLog): void {
+  const record = readWebPid(evolutionDir);
+  if (!record || record.pid !== callerPid) return;
+  try {
+    fs.rmSync(webPidFile(evolutionDir), { force: true });
+  } catch (error) {
+    log(`[skill-evolve] 删 Web 面板记录失败：${String(error)}`);
+  }
+}
+
+/** pid 是否存活：与跨进程锁同一条判据（EPERM = 进程在、只是无权发信号，同样算活） */
+export function isAlive(pid: number): boolean {
+  return isPidAlive(pid);
+}