@pi-harness/pi-harness 0.1.2 → 0.1.4

package/packages/core/src/plugins/session-compare.ts

@@ -0,0 +1,180 @@
+import { readFile, stat } from "node:fs/promises";
+import { basename } from "node:path";
+import type { Context } from "@deepseek-ai/cordis";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, parseSessionEntries, SessionManager, type AgentToolResult, type SessionInfo } from "@earendil-works/pi-coding-agent";
+
+const maxSessions = 200;
+const maxSessionFileBytes = 4 * 1024 * 1024;
+const maxMessageTextLength = 4_000;
+const maxDiffMessages = 40;
+
+export interface SessionCompareMessage {
+  role: string;
+  text: string;
+}
+
+export interface SessionCompareDiff {
+  shared: number;
+  added: SessionCompareMessage[];
+  removed: SessionCompareMessage[];
+}
+
+export interface SessionCompareSide {
+  id: string;
+  name: string;
+  path: string;
+  modified: string;
+  messageCount: number;
+  roles: Record<string, number>;
+}
+
+export interface SessionCompareReport extends SessionCompareDiff {
+  left: SessionCompareSide;
+  right: SessionCompareSide;
+  changed: boolean;
+  comparedAt: string;
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}
+
+function contentText(value: unknown): string {
+  if (typeof value === "string") return value.trim();
+  if (!Array.isArray(value)) return "";
+  return value
+    .flatMap((part) => {
+      const item = record(part);
+      return item?.type === "text" && typeof item.text === "string" ? [item.text.trim()] : [];
+    })
+    .filter(Boolean)
+    .join("\n")
+    .trim();
+}
+
+export function sessionMessageEntries(entries: readonly unknown[]): SessionCompareMessage[] {
+  return entries.flatMap((entry) => {
+    const item = record(entry);
+    const message = record(item?.message);
+    if (item?.type !== "message" || typeof message?.role !== "string") return [];
+    const text = contentText(message.content);
+    return text === "" ? [] : [{ role: message.role, text }];
+  });
+}
+
+export function compareMessageEntries(left: readonly SessionCompareMessage[], right: readonly SessionCompareMessage[]): SessionCompareDiff {
+  const added: SessionCompareMessage[] = [];
+  const removed: SessionCompareMessage[] = [];
+  let shared = 0;
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftMessage = left[index];
+    const rightMessage = right[index];
+    if (leftMessage !== undefined && rightMessage !== undefined && leftMessage.role === rightMessage.role && leftMessage.text === rightMessage.text) {
+      shared += 1;
+      continue;
+    }
+    if (rightMessage !== undefined && added.length < maxDiffMessages) added.push({ ...rightMessage, text: rightMessage.text.slice(0, maxMessageTextLength) });
+    if (leftMessage !== undefined && removed.length < maxDiffMessages) removed.push({ ...leftMessage, text: leftMessage.text.slice(0, maxMessageTextLength) });
+  }
+  return { shared, added, removed };
+}
+
+function sessionName(session: SessionInfo): string {
+  return session.name?.trim() || session.firstMessage.trim() || session.id;
+}
+
+function side(session: SessionInfo, messages: readonly SessionCompareMessage[]): SessionCompareSide {
+  const roles: Record<string, number> = {};
+  for (const message of messages) roles[message.role] = (roles[message.role] ?? 0) + 1;
+  return {
+    id: session.id,
+    name: sessionName(session),
+    path: session.path,
+    modified: session.modified.toISOString(),
+    messageCount: messages.length,
+    roles,
+  };
+}
+
+async function readMessages(session: SessionInfo): Promise<SessionCompareMessage[]> {
+  const metadata = await stat(session.path);
+  if (!metadata.isFile()) throw new Error(`Session is not a file: ${session.id}`);
+  if (metadata.size > maxSessionFileBytes) throw new Error(`Session ${session.id} exceeds the ${maxSessionFileBytes}-byte comparison limit`);
+  return sessionMessageEntries(parseSessionEntries(await readFile(session.path, "utf8")));
+}
+
+function findSession(sessions: readonly SessionInfo[], requested: string): SessionInfo {
+  const value = requested.trim();
+  if (value === "") throw new Error("Session id is required");
+  const exact = sessions.find((session) => session.id === value || session.path === value || basename(session.path) === value);
+  if (exact === undefined) throw new Error(`Session was not found: ${value}`);
+  return exact;
+}
+
+async function compareSessions(context: Context, leftId: string, rightId: string): Promise<SessionCompareReport> {
+  const sessions = await SessionManager.list(context.piHarnessLaunch.cwd, context.piSession.manager.getSessionDir());
+  const bounded = sessions.slice(0, maxSessions);
+  const leftSession = findSession(bounded, leftId);
+  const rightSession = findSession(bounded, rightId);
+  const [leftMessages, rightMessages] = await Promise.all([readMessages(leftSession), readMessages(rightSession)]);
+  const diff = compareMessageEntries(leftMessages, rightMessages);
+  return {
+    ...diff,
+    left: side(leftSession, leftMessages),
+    right: side(rightSession, rightMessages),
+    changed: diff.shared !== leftMessages.length || diff.shared !== rightMessages.length,
+    comparedAt: new Date().toISOString(),
+  };
+}
+
+function renderMessage(message: SessionCompareMessage): string {
+  return `[${message.role}] ${message.text}`;
+}
+
+function renderReport(report: SessionCompareReport): string {
+  const lines = [
+    `Compared ${report.left.id} with ${report.right.id}: ${report.changed ? "changed" : "identical"}.`,
+    `Shared messages: ${report.shared}. Added in right: ${report.added.length}. Removed from left: ${report.removed.length}.`,
+  ];
+  if (report.added.length > 0) lines.push(`Added:\n${report.added.map(renderMessage).join("\n")}`);
+  if (report.removed.length > 0) lines.push(`Removed:\n${report.removed.map(renderMessage).join("\n")}`);
+  return lines.join("\n\n");
+}
+
+export default {
+  name: "pi-session-compare",
+  inject: ["piHarnessLaunch", "piSession", "piPluginUi", "piTools"],
+  apply(context: Context) {
+    let latest: SessionCompareReport | undefined;
+    const unregister = context.piTools.register(
+      defineTool({
+        name: "session_compare",
+        label: "Compare sessions",
+        description: "Compare two persisted Pi JSONL sessions by message role and text without modifying either file.",
+        promptSnippet: "compare two persisted Pi sessions",
+        parameters: Type.Object({
+          left: Type.String({ description: "Left session id or session filename" }),
+          right: Type.String({ description: "Right session id or session filename" }),
+        }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<SessionCompareReport>> {
+          latest = await compareSessions(context, params.left, params.right);
+          return { content: [{ type: "text", text: renderReport(latest) }], details: latest };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "session-compare-panel",
+      pluginId: "@pi-harness/core/plugins/session-compare",
+      title: "Session Compare",
+      description: "对比两个持久化会话的消息差异，不修改原始会话文件。",
+      icon: "⇄",
+      read: () => latest ?? { left: null, right: null, shared: 0, added: [], removed: [], changed: false, comparedAt: null },
+    });
+    context.effect(() => () => {
+      unregister();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/session-export.ts

@@ -0,0 +1,99 @@
+import { randomUUID } from "node:crypto";
+import { rename, writeFile } from "node:fs/promises";
+import type { Context } from "@deepseek-ai/cordis";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { prepareWorkspaceFile } from "../workspace-path.js";
+
+const maxOutputBytes = 1024 * 1024;
+const defaultFileName = "pi-session.md";
+
+type ExportState = { path: string; bytes: number; messages: number };
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}
+
+function contentText(value: unknown): string {
+  if (typeof value === "string") return value.trim();
+  if (!Array.isArray(value)) return "";
+  return value
+    .flatMap((part) => {
+      const item = record(part);
+      return item?.type === "text" && typeof item.text === "string" ? [item.text.trim()] : [];
+    })
+    .filter(Boolean)
+    .join("\n");
+}
+
+function heading(role: string, toolName: string | undefined): string {
+  if (role === "toolResult") return `### Tool: ${toolName?.trim() || "unknown"}`;
+  return `## ${role.slice(0, 1).toUpperCase()}${role.slice(1)}`;
+}
+
+export function renderSessionMarkdown(messages: readonly unknown[]): string {
+  const sections = messages.flatMap((message) => {
+    const item = record(message);
+    if (item === undefined || typeof item.role !== "string") return [];
+    const text = contentText(item.content);
+    return text === "" ? [] : [`${heading(item.role, typeof item.toolName === "string" ? item.toolName : undefined)}\n\n${text}`];
+  });
+  return `# Pi Harness Session\n\n${sections.length > 0 ? `${sections.join("\n\n")}\n` : ""}`;
+}
+
+function normalizedOutputPath(requested: string): string {
+  const normalized = requested.trim() || defaultFileName;
+  if (normalized.length > 256) throw new Error("Session export path must be at most 256 characters");
+  if (!normalized.toLowerCase().endsWith(".md")) throw new Error("Session export path must end with .md");
+  return normalized;
+}
+
+export default {
+  name: "pi-session-export",
+  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  apply(context: Context) {
+    let latest: ExportState | undefined;
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "session_export",
+        label: "Export session",
+        description: "Export the current Pi session as bounded Markdown without changing the conversation history.",
+        promptSnippet: "export the current session to a Markdown file",
+        parameters: Type.Object({
+          path: Type.Optional(Type.String({ description: "Markdown path relative to the workspace" })),
+          confirm: Type.Optional(Type.Boolean({ description: "Must be true to overwrite an existing file" })),
+        }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<ExportState>> {
+          const runtime = context.get("piRuntime");
+          if (runtime === undefined) throw new Error("Pi runtime is not ready");
+          const prepared = await prepareWorkspaceFile(
+            context.piHarnessLaunch.cwd,
+            normalizedOutputPath(params.path ?? defaultFileName),
+            "Session export path must stay inside the current workspace and target a regular file",
+          );
+          if (prepared.exists && params.confirm !== true) throw new Error("Session export would overwrite an existing file; retry with confirm=true");
+          const markdown = renderSessionMarkdown(runtime.session.messages);
+          const bytes = Buffer.byteLength(markdown, "utf8");
+          if (bytes > maxOutputBytes) throw new Error("Session export exceeds the 1 MiB output limit");
+          const temporary = `${prepared.target}.${randomUUID()}.tmp`;
+          await writeFile(temporary, markdown, { encoding: "utf8", mode: 0o600 });
+          await rename(temporary, prepared.target);
+          latest = { path: prepared.relativePath, bytes, messages: runtime.session.messages.length };
+          return { content: [{ type: "text", text: `Session exported to ${latest.path}.` }], details: latest };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "session-export-panel",
+      pluginId: "@pi-harness/core/plugins/session-export",
+      title: "Session Export",
+      description: "将当前会话导出为工作区内的 Markdown 文件，不改变原会话历史。",
+      icon: "⇩",
+      read: () => ({ latest: latest ?? null, maxOutputBytes }),
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/session-insights.ts

@@ -0,0 +1,47 @@
+import type { Context } from "@deepseek-ai/cordis";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type AgentToolResult, type SessionStats } from "@earendil-works/pi-coding-agent";
+
+export default {
+  name: "pi-session-insights",
+  inject: ["piPluginUi", "piTools"],
+  apply(context: Context) {
+    const runtime = () => context.get("piRuntime");
+    const readStats = (): SessionStats => {
+      const service = runtime();
+      if (service === undefined) throw new Error("Pi runtime is not ready");
+      return service.session.getSessionStats();
+    };
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "session_report",
+        label: "Session report",
+        description: "Inspect the current session token, message, tool, cost, and context statistics.",
+        promptSnippet: "inspect current session usage and context statistics",
+        parameters: Type.Object({ compact: Type.Optional(Type.Boolean({ description: "Compact the session when true" })) }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<SessionStats>> {
+          const service = runtime();
+          if (service === undefined) throw new Error("Pi runtime is not ready");
+          if (params.compact === true) await service.session.compact();
+          const report = readStats();
+          return {
+            content: [{ type: "text", text: `Session has ${report.totalMessages} messages and ${report.tokens.total} tracked tokens.` }],
+            details: report,
+          };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "session-insights-panel",
+      pluginId: "@pi-harness/core/plugins/session-insights",
+      title: "Session Insights",
+      description: "查看当前会话的消息、工具、token、成本和上下文统计，并可触发压缩。",
+      icon: "▥",
+      read: readStats,
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/session-search.ts

@@ -0,0 +1,126 @@
+import { readFile, stat } from "node:fs/promises";
+import type { Context } from "@deepseek-ai/cordis";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, parseSessionEntries, SessionManager, type AgentToolResult, type SessionInfo } from "@earendil-works/pi-coding-agent";
+
+const maxQueryLength = 120;
+const maxPreviewLength = 500;
+const maxSessions = 200;
+const maxHits = 100;
+const maxSessionFileBytes = 4 * 1024 * 1024;
+const sessionReadConcurrency = 8;
+
+export type SessionSearchHit = { role: string; text: string };
+export type SessionSearchItem = { id: string; name: string; path: string; modified: string; hits: SessionSearchHit[] };
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}
+
+function contentText(value: unknown): string {
+  if (typeof value === "string") return value.trim();
+  if (!Array.isArray(value)) return "";
+  return value
+    .flatMap((part) => {
+      const item = record(part);
+      return item?.type === "text" && typeof item.text === "string" ? [item.text.trim()] : [];
+    })
+    .filter(Boolean)
+    .join("\n");
+}
+
+function matchingPreview(text: string, normalizedQuery: string): string {
+  if (text.length <= maxPreviewLength) return text;
+  const matchIndex = text.toLocaleLowerCase().indexOf(normalizedQuery);
+  const idealStart = matchIndex - Math.floor((maxPreviewLength - normalizedQuery.length) / 2);
+  const start = Math.max(0, Math.min(idealStart, text.length - maxPreviewLength));
+  return text.slice(start, start + maxPreviewLength);
+}
+
+export function searchSessionEntries(entries: readonly unknown[], query: string): SessionSearchHit[] {
+  const normalized = query.trim().toLocaleLowerCase();
+  if (normalized.length < 1 || normalized.length > maxQueryLength) throw new Error("Session search query must contain 1-120 characters");
+  return entries.flatMap((entry) => {
+    const item = record(entry);
+    const message = record(item?.message);
+    if (item?.type !== "message" || typeof message?.role !== "string") return [];
+    const text = contentText(message.content);
+    return text.toLocaleLowerCase().includes(normalized) ? [{ role: message.role, text: matchingPreview(text, normalized) }] : [];
+  });
+}
+
+async function searchSession(session: SessionInfo, query: string): Promise<SessionSearchItem | undefined> {
+  try {
+    const metadata = await stat(session.path);
+    if (!metadata.isFile() || metadata.size > maxSessionFileBytes) return undefined;
+    const hits = searchSessionEntries(parseSessionEntries(await readFile(session.path, "utf8")), query);
+    if (hits.length === 0) return undefined;
+    return {
+      id: session.id,
+      name: session.name?.trim() || session.firstMessage.trim() || session.id,
+      path: session.path,
+      modified: session.modified.toISOString(),
+      hits,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+async function searchSessions(sessions: readonly SessionInfo[], query: string): Promise<SessionSearchItem[]> {
+  const results: SessionSearchItem[] = [];
+  for (let index = 0; index < sessions.length; index += sessionReadConcurrency) {
+    const batch = await Promise.all(sessions.slice(index, index + sessionReadConcurrency).map((session) => searchSession(session, query)));
+    results.push(...batch.filter((item): item is SessionSearchItem => item !== undefined));
+  }
+  return results;
+}
+
+export default {
+  name: "pi-session-search",
+  inject: ["piHarnessLaunch", "piSession", "piPluginUi", "piTools"],
+  apply(context: Context) {
+    let latest: { query: string; total: number; items: SessionSearchItem[] } | undefined;
+    const search = async (query: string): Promise<SessionSearchItem[]> => {
+      const normalized = query.trim();
+      if (normalized.length < 1 || normalized.length > maxQueryLength) throw new Error("Session search query must contain 1-120 characters");
+      const sessions = await SessionManager.list(context.piHarnessLaunch.cwd, context.piSession.manager.getSessionDir());
+      const items = (await searchSessions(sessions.slice(0, maxSessions), normalized)).slice(0, maxHits);
+      latest = { query: normalized, total: items.length, items };
+      return items;
+    };
+    const unregister = context.piTools.register(
+      defineTool({
+        name: "session_search",
+        label: "Search sessions",
+        description: "Search persisted Pi JSONL sessions for a bounded text query without modifying session files.",
+        promptSnippet: "search previous Pi sessions for a phrase",
+        parameters: Type.Object({ query: Type.String({ description: "Text to search for, 1-120 characters" }) }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<{ query: string; total: number; items: SessionSearchItem[] }>> {
+          const items = await search(params.query);
+          return {
+            content: [
+              {
+                type: "text",
+                text: items.map((item) => `${item.name}: ${item.hits.map((hit) => hit.text).join(" | ")}`).join("\n") || "No matching sessions found.",
+              },
+            ],
+            details: latest!,
+          };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "session-search-panel",
+      pluginId: "@pi-harness/core/plugins/session-search",
+      title: "Session Search",
+      description: "跨本地持久化会话搜索文本，只读不修改会话文件。",
+      icon: "⌕",
+      read: () => latest ?? { query: "", total: 0, items: [] },
+    });
+    context.effect(() => () => {
+      unregister();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/session.ts

@@ -2,6 +2,7 @@ import { join, resolve } from "node:path";
 import type { Context } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
 import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { assertKnownConfigKeys } from "../config.js";
 
 export interface SessionPluginConfig {
   storage?: "memory" | "jsonl";
@@ -10,7 +11,7 @@ export interface SessionPluginConfig {
 
 export const Config: z<SessionPluginConfig> = z.object({
   storage: z.union(["memory", "jsonl"]).default("jsonl"),
-  directory: z.string(),
+  directory: z.string().min(1),
 });
 
 export default {
@@ -18,10 +19,11 @@ export default {
   inject: ["piHarnessLaunch"],
   Config,
   apply(context: Context, config: SessionPluginConfig) {
+    assertKnownConfigKeys("pi-session", config, ["storage", "directory"]);
     const storage = config.storage ?? "jsonl";
     const manager = storage === "memory"
       ? SessionManager.inMemory(context.piHarnessLaunch.cwd)
-      : SessionManager.create(context.piHarnessLaunch.cwd, config.directory === undefined ? join(context.piHarnessLaunch.agentDir, "sessions") : resolve(context.piHarnessLaunch.cwd, config.directory));
+      : SessionManager.create(context.piHarnessLaunch.cwd, config.directory == null ? join(context.piHarnessLaunch.agentDir, "sessions") : resolve(context.piHarnessLaunch.cwd, config.directory));
     context.provide("piSession", { manager });
   },
 };

package/packages/core/src/plugins/skill-catalog.ts

@@ -0,0 +1,117 @@
+import { readFile } from "node:fs/promises";
+import type { Context } from "@deepseek-ai/cordis";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+import type { PiMcpServerSnapshot } from "../services.js";
+import { buildSkillInjection, type SkillInjection } from "./reverse-skill.js";
+
+const maxQueryLength = 120;
+const maxSkillBytes = 128 * 1024;
+
+export interface SkillCatalogItem {
+  name: string;
+  description: string;
+  filePath: string;
+  source: string;
+  scope: string;
+  disabled: boolean;
+}
+
+export interface SkillCatalogReport {
+  total: number;
+  skills: SkillCatalogItem[];
+  diagnostics: Array<{ type: string; message: string }>;
+}
+
+export function prepareSkillRead(name: string, content: string): SkillInjection {
+  return buildSkillInjection(content, name);
+}
+
+function queryText(value: string | undefined): string {
+  const query = (value ?? "").trim();
+  if (query.length > maxQueryLength) throw new Error(`Skill catalog query must contain 0-${maxQueryLength} characters`);
+  return query.toLocaleLowerCase();
+}
+
+function readCatalog(context: Context, query?: string): SkillCatalogReport {
+  const loaded = context.piResources.resourceLoader.getSkills();
+  const normalized = queryText(query);
+  const skills = loaded.skills
+    .map((skill): SkillCatalogItem => ({
+      name: skill.name,
+      description: skill.description,
+      filePath: skill.filePath,
+      source: skill.sourceInfo.source,
+      scope: skill.sourceInfo.scope,
+      disabled: skill.disableModelInvocation,
+    }))
+    .filter((skill) => normalized === "" || `${skill.name} ${skill.description} ${skill.source}`.toLocaleLowerCase().includes(normalized));
+  return {
+    total: skills.length,
+    skills,
+    diagnostics: loaded.diagnostics.map((diagnostic) => ({ type: diagnostic.type, message: diagnostic.message })),
+  };
+}
+
+export default {
+  name: "pi-skill-catalog",
+  inject: ["piResources", "piMcp", "piPluginUi", "piTools"],
+  apply(context: Context) {
+    const readMcp = (): { servers: readonly PiMcpServerSnapshot[] } => context.piMcp.snapshot();
+    const unregister = context.piTools.register(
+      defineTool({
+        name: "skill_catalog",
+        label: "Skill catalog",
+        description:
+          "Inspect loaded Agent Skills, safely read one skill file through a bounded data boundary, and inspect MCP status without changing configuration.",
+        promptSnippet: "inspect loaded skills or managed MCP server status",
+        parameters: Type.Object({
+          action: Type.Union([Type.Literal("list"), Type.Literal("read"), Type.Literal("mcp")]),
+          query: Type.Optional(Type.String()),
+          name: Type.Optional(Type.String()),
+        }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<SkillCatalogReport | SkillInjection | { servers: readonly PiMcpServerSnapshot[] }>> {
+          if (params.action === "mcp") {
+            const result = readMcp();
+            return {
+              content: [{ type: "text", text: result.servers.map((server) => `${server.id}: ${server.status}`).join("\n") || "No MCP servers configured." }],
+              details: result,
+            };
+          }
+          const report = readCatalog(context, params.query);
+          if (params.action === "list") {
+            return {
+              content: [{ type: "text", text: report.skills.map((skill) => `${skill.name}: ${skill.description}`).join("\n") || "No matching skills loaded." }],
+              details: report,
+            };
+          }
+          const name = (params.name ?? "").trim();
+          if (name === "") throw new Error("Skill name is required");
+          const skill = report.skills.find((candidate) => candidate.name === name);
+          if (skill === undefined) throw new Error(`Skill was not found: ${name}`);
+          const content = await readFile(skill.filePath, "utf8");
+          if (Buffer.byteLength(content, "utf8") > maxSkillBytes) throw new Error(`Skill file exceeds ${maxSkillBytes} bytes`);
+          const result = prepareSkillRead(name, content);
+          const message = result.content === null ? `Skill ${result.name} was blocked from catalog output (${result.risk}).` : result.content;
+          return { content: [{ type: "text", text: message }], details: result };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "skill-catalog-panel",
+      pluginId: "@pi-harness/core/plugins/skill-catalog",
+      title: "Skills Catalog",
+      description: "查看当前运行时加载的 Skills 与 MCP 服务器状态。",
+      icon: "✦",
+      read: () => {
+        const report = readCatalog(context);
+        const mcp = readMcp();
+        return { skillCount: report.total, skills: report.skills, diagnostics: report.diagnostics, mcpCount: mcp.servers.length, mcpServers: mcp.servers };
+      },
+    });
+    context.effect(() => () => {
+      unregister();
+      disposePanel();
+    });
+  },
+};