@pi-harness/pi-harness 0.1.2 → 0.1.4

package/packages/core/src/plugins/plugin-stars.ts

@@ -0,0 +1,205 @@
+import type { Context } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+
+const defaultSourceUrl = "https://raw.githubusercontent.com/ywsldxk/dsh-plugin-stars/main/data/plugins.json";
+const maxResponseBytes = 2 * 1024 * 1024;
+const maxQueryLength = 120;
+const maxLimit = 50;
+
+export interface PluginStarsEntry {
+  id: string;
+  name: string;
+  fullName: string;
+  description: string;
+  htmlUrl: string;
+  homepage?: string;
+  npmName?: string;
+  stars: number;
+  updatedAt: string;
+  license?: string;
+  topics: string[];
+}
+
+export interface PluginStarsReport {
+  source: string;
+  generatedAt: string;
+  total: number;
+  query: string;
+  results: PluginStarsEntry[];
+  fetchedAt: 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 text(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function nonNegativeInteger(value: unknown): number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : -1;
+}
+
+function topics(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value
+        .filter((item): item is string => typeof item === "string" && item.trim() !== "")
+        .map((item) => item.trim())
+        .slice(0, 24)
+    : [];
+}
+
+function normalizedEntry(value: unknown): PluginStarsEntry | undefined {
+  const item = record(value);
+  if (item === undefined) return undefined;
+  const id = text(item.id);
+  const name = text(item.name);
+  const fullName = text(item.fullName);
+  const htmlUrl = text(item.htmlUrl);
+  const stars = nonNegativeInteger(item.stars);
+  if (id === "" || name === "" || !/^[^/\s]+\/[^/\s]+$/u.test(fullName) || !/^https:\/\/github\.com\//iu.test(htmlUrl) || stars < 0) return undefined;
+  const homepage = text(item.homepage);
+  const npmName = text(item.npmName);
+  const license = text(item.license);
+  return {
+    id,
+    name,
+    fullName,
+    description: text(item.description),
+    htmlUrl,
+    ...(homepage === "" ? {} : { homepage }),
+    ...(npmName === "" ? {} : { npmName }),
+    stars,
+    updatedAt: text(item.updatedAt),
+    ...(license === "" ? {} : { license }),
+    topics: topics(item.topics),
+  };
+}
+
+export function parsePluginStarsPayload(payload: unknown): { source: string; generatedAt: string; plugins: PluginStarsEntry[] } {
+  const root = record(payload);
+  const plugins = Array.isArray(root?.plugins)
+    ? root.plugins.flatMap((item) => {
+        const entry = normalizedEntry(item);
+        return entry === undefined ? [] : [entry];
+      })
+    : [];
+  return { source: text(root?.source) || "dsh-plugin-stars", generatedAt: text(root?.generatedAt), plugins };
+}
+
+export function searchPluginStars(report: { plugins: readonly PluginStarsEntry[] }, query = ""): PluginStarsEntry[] {
+  const normalizedQuery = query.trim().toLowerCase();
+  if (normalizedQuery.length > maxQueryLength) throw new Error(`Plugin stars query must contain 0-${maxQueryLength} characters`);
+  return [...report.plugins]
+    .filter(
+      (entry) => normalizedQuery === "" || [entry.name, entry.fullName, entry.description, ...entry.topics].join(" ").toLowerCase().includes(normalizedQuery),
+    )
+    .sort((left, right) => right.stars - left.stars || left.fullName.localeCompare(right.fullName));
+}
+
+function sourceUrl(raw: string): string {
+  let url: URL;
+  try {
+    url = new URL(raw.trim());
+  } catch {
+    throw new Error("Plugin stars source URL is invalid");
+  }
+  if (url.protocol !== "https:" || url.username !== "" || url.password !== "") throw new Error("Plugin stars source URL must be HTTPS without credentials");
+  return url.toString();
+}
+
+async function fetchReport(
+  url: string,
+  timeoutMs: number,
+  signal?: AbortSignal,
+): Promise<{ source: string; generatedAt: string; plugins: PluginStarsEntry[] }> {
+  const controller = new AbortController();
+  const onAbort = (): void => controller.abort(signal?.reason);
+  signal?.addEventListener("abort", onAbort, { once: true });
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { signal: controller.signal, headers: { accept: "application/json", "user-agent": "pi-harness-plugin-stars" } });
+    if (!response.ok) throw new Error(`Plugin stars source returned HTTP ${response.status}`);
+    const body = await response.text();
+    if (Buffer.byteLength(body, "utf8") > maxResponseBytes) throw new Error("Plugin stars source exceeded the 2 MiB limit");
+    let payload: unknown;
+    try {
+      payload = JSON.parse(body) as unknown;
+    } catch (error) {
+      throw new Error(`Plugin stars source returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    return parsePluginStarsPayload(payload);
+  } catch (error) {
+    if (controller.signal.aborted)
+      throw new Error(signal?.aborted ? "Plugin stars request was cancelled" : `Plugin stars request timed out after ${timeoutMs} ms`, { cause: error });
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", onAbort);
+  }
+}
+
+export interface PluginStarsConfig {
+  sourceUrl?: string;
+  limit?: number;
+  timeoutMs?: number;
+}
+
+export const Config: z<PluginStarsConfig> = z.object({
+  sourceUrl: z.string().default(defaultSourceUrl),
+  limit: z.number().default(10),
+  timeoutMs: z.number().default(15_000),
+});
+
+export default {
+  name: "pi-plugin-stars",
+  inject: ["piPluginUi", "piTools"],
+  Config,
+  apply(context: Context, config: PluginStarsConfig) {
+    const source = sourceUrl(config.sourceUrl ?? defaultSourceUrl);
+    const limit = Math.max(1, Math.min(maxLimit, Math.trunc(config.limit ?? 10)));
+    const timeoutMs = Math.max(1_000, Math.min(60_000, Math.trunc(config.timeoutMs ?? 15_000)));
+    let latest: PluginStarsReport | undefined;
+    const unregister = context.piTools.register(
+      defineTool({
+        name: "plugin_stars_search",
+        label: "Plugin Stars",
+        description: "Read the curated DSH Plugin Stars ranking, filter it locally, and return sorted repository evidence. Never installs plugins.",
+        promptSnippet: "search the curated DSH plugin ranking",
+        parameters: Type.Object({ query: Type.Optional(Type.String({ description: "Plugin name, repository, capability, or topic" })) }),
+        async execute(_toolCallId, params, signal): Promise<AgentToolResult<PluginStarsReport>> {
+          const payload = await fetchReport(source, timeoutMs, signal);
+          const query = params.query?.trim() ?? "";
+          const results = searchPluginStars(payload, query).slice(0, limit);
+          latest = { source: payload.source, generatedAt: payload.generatedAt, total: results.length, query, results, fetchedAt: new Date().toISOString() };
+          return {
+            content: [
+              {
+                type: "text",
+                text:
+                  results.map((entry, index) => `${index + 1}. ${entry.fullName} · ${entry.stars} stars\n${entry.htmlUrl}`).join("\n\n") ||
+                  "No ranked plugins matched.",
+              },
+            ],
+            details: latest,
+          };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "plugin-stars-panel",
+      pluginId: "@pi-harness/core/plugins/plugin-stars",
+      title: "Plugin Stars",
+      description: "读取 dsh-plugin-stars 策展榜单，按 Star 和关键词查看社区插件，不自动安装。",
+      icon: "★",
+      read: () => ({ source, limit, timeoutMs, latest: latest ?? null }),
+    });
+    context.effect(() => () => {
+      unregister();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/prompt-guard.ts

@@ -0,0 +1,122 @@
+import type { Context } from "@deepseek-ai/cordis";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+
+const maxPromptBytes = 128 * 1024;
+type Risk = "safe" | "review" | "blocked";
+type Finding = { code: string; severity: "medium" | "high"; message: string };
+type PromptGuardReport = { source: string; risk: Risk; score: number; scannedChars: number; findings: Finding[] };
+type Pattern = { code: string; severity: Finding["severity"]; score: number; message: string; pattern: RegExp };
+
+const patterns: readonly Pattern[] = [
+  {
+    code: "instruction_override",
+    severity: "high",
+    score: 5,
+    message: "检测到试图覆盖已有指令的文本。",
+    pattern: /\bignore\s+(?:all\s+)?(?:previous|earlier|above)\s+instructions\b/iu,
+  },
+  {
+    code: "secret_exfiltration",
+    severity: "high",
+    score: 5,
+    message: "检测到可能要求外传 API key、token 或密码的文本。",
+    pattern: /\b(?:api[\s_-]?key|token|password|secret)\b.{0,120}\b(?:send|upload|post|share|curl|wget)\b/iu,
+  },
+  { code: "remote_payload", severity: "medium", score: 2, message: "检测到从远程地址加载或执行内容的文本。", pattern: /\b(?:curl|wget)\s+https?:\/\//iu },
+  {
+    code: "system_prompt_probe",
+    severity: "medium",
+    score: 2,
+    message: "检测到探测系统或开发者提示词的文本。",
+    pattern: /\b(?:system|developer)\s+(?:prompt|message|instruction)s?\b/iu,
+  },
+  {
+    code: "hidden_instruction",
+    severity: "medium",
+    score: 2,
+    message: "检测到要求隐藏执行意图或绕过披露的文本。",
+    pattern: /\b(?:do not|don't)\s+(?:tell|show|disclose)\s+(?:the\s+)?(?:user|human)\b/iu,
+  },
+];
+
+function inspect(text: string, source: string): PromptGuardReport {
+  if (Buffer.byteLength(text, "utf8") > maxPromptBytes) throw new Error(`Prompt guard input must be at most ${maxPromptBytes} bytes`);
+  const findings = patterns.filter((item) => item.pattern.test(text)).map(({ code, severity, message }) => ({ code, severity, message }));
+  const score = findings.reduce((total, finding) => total + (patterns.find((item) => item.code === finding.code)?.score ?? 0), 0);
+  const highFindings = findings.filter((finding) => finding.severity === "high").length;
+  const risk: Risk = highFindings >= 2 || score >= 8 ? "blocked" : findings.length > 0 ? "review" : "safe";
+  return { source: source.trim().slice(0, 64) || "unknown", risk, score, scannedChars: text.length, findings };
+}
+
+function messageText(message: unknown): string {
+  if (message === null || typeof message !== "object") return "";
+  const content = (message as { content?: unknown }).content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter(
+      (item): item is { type: "text"; text: string } =>
+        item !== null && typeof item === "object" && (item as { type?: unknown }).type === "text" && typeof (item as { text?: unknown }).text === "string",
+    )
+    .map((item) => item.text)
+    .join("\n");
+}
+
+export default {
+  name: "pi-prompt-guard",
+  inject: ["piPluginUi", "piTools"],
+  apply(context: Context) {
+    let scans = 0;
+    let latest: PromptGuardReport | undefined;
+    const onSessionEvent = context.on("pi/session-event", (event) => {
+      if (event.type !== "message_start" || event.message.role !== "user") return;
+      try {
+        latest = inspect(messageText(event.message), "message_start");
+        scans += 1;
+      } catch {
+        latest = {
+          source: "message_start",
+          risk: "review",
+          score: 0,
+          scannedChars: 0,
+          findings: [{ code: "input_limit", severity: "medium", message: "输入超过 Prompt Guard 扫描上限。" }],
+        };
+        scans += 1;
+      }
+    });
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "prompt_guard_scan",
+        label: "Prompt guard scan",
+        description: "Scan text for prompt injection, secret exfiltration, and remote payload indicators without retaining the source text.",
+        promptSnippet: "scan untrusted text for prompt injection risks",
+        parameters: Type.Object({ text: Type.String(), source: Type.Optional(Type.String()) }),
+        execute(_toolCallId, params): Promise<AgentToolResult<PromptGuardReport>> {
+          return Promise.resolve().then(() => {
+            const report = inspect(params.text, params.source ?? "tool");
+            latest = report;
+            scans += 1;
+            return {
+              content: [{ type: "text" as const, text: `${report.risk}: ${report.findings.length} finding(s), score ${report.score}.` }],
+              details: report,
+            };
+          });
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "prompt-guard-panel",
+      pluginId: "@pi-harness/core/plugins/prompt-guard",
+      title: "Prompt Guard",
+      description: "扫描潜在提示词注入和秘密外传风险，只保留摘要，不保存原文。",
+      icon: "⊘",
+      read: () => ({ scans, risk: latest?.risk ?? "safe", latest: latest ?? null }),
+    });
+    context.effect(() => () => {
+      onSessionEvent();
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/prompt-library.ts

@@ -0,0 +1,165 @@
+import type { Context } from "@deepseek-ai/cordis";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+
+const customType = "pi-harness/prompt-library";
+const maxTitleLength = 120;
+const maxPromptLength = 8_000;
+const maxTagLength = 40;
+const maxTags = 10;
+const maxTemplates = 100;
+
+export interface PromptTemplateInput {
+  title: string;
+  prompt: string;
+  tags?: string[];
+}
+
+export interface PromptTemplate {
+  id: string;
+  title: string;
+  prompt: string;
+  tags: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface PromptLibraryState {
+  templates: PromptTemplate[];
+}
+
+function bounded(value: string, field: string, maxLength: number): string {
+  const text = value.trim();
+  if (!text) throw new Error(`${field} is required`);
+  if (text.length > maxLength) throw new Error(`${field} must be ${maxLength.toLocaleString()} characters or fewer`);
+  return text;
+}
+
+function normalizeTags(values: string[] | undefined): string[] {
+  const tags = values ?? [];
+  if (tags.length > maxTags) throw new Error(`tags must contain ${maxTags} items or fewer`);
+  return [...new Set(tags.map((tag) => tag.trim()).filter(Boolean))].map((tag) => bounded(tag, "tag", maxTagLength));
+}
+
+export function createPromptTemplate(input: PromptTemplateInput, id: string, timestamp: string): PromptTemplate {
+  return {
+    id,
+    title: bounded(input.title, "title", maxTitleLength),
+    prompt: bounded(input.prompt, "prompt", maxPromptLength),
+    tags: normalizeTags(input.tags),
+    createdAt: timestamp,
+    updatedAt: timestamp,
+  };
+}
+
+function readState(context: Context): PromptLibraryState {
+  const entry = [...context.piSession.manager.getEntries()].reverse().find((item) => item.type === "custom" && item.customType === customType);
+  if (entry?.type !== "custom" || entry.data === undefined || entry.data === null || typeof entry.data !== "object") return { templates: [] };
+  const value = entry.data as { templates?: unknown };
+  if (!Array.isArray(value.templates)) return { templates: [] };
+  const templates = value.templates.flatMap((item): PromptTemplate[] => {
+    if (item === null || typeof item !== "object") return [];
+    const candidate = item as Partial<PromptTemplate>;
+    if (typeof candidate.id !== "string" || typeof candidate.title !== "string" || typeof candidate.prompt !== "string") return [];
+    return [
+      {
+        id: candidate.id,
+        title: candidate.title,
+        prompt: candidate.prompt,
+        tags: Array.isArray(candidate.tags) ? candidate.tags.filter((tag): tag is string => typeof tag === "string") : [],
+        createdAt: typeof candidate.createdAt === "string" ? candidate.createdAt : new Date(0).toISOString(),
+        updatedAt: typeof candidate.updatedAt === "string" ? candidate.updatedAt : new Date(0).toISOString(),
+      },
+    ];
+  });
+  return { templates: templates.slice(-maxTemplates) };
+}
+
+function persist(context: Context, state: PromptLibraryState): void {
+  context.piSession.manager.appendCustomEntry(customType, state);
+}
+
+function filterTemplates(state: PromptLibraryState, query: string | undefined): PromptTemplate[] {
+  const normalized = query?.trim().toLocaleLowerCase() ?? "";
+  if (!normalized) return state.templates;
+  return state.templates.filter((template) => `${template.title} ${template.prompt} ${template.tags.join(" ")}`.toLocaleLowerCase().includes(normalized));
+}
+
+export default {
+  name: "pi-prompt-library",
+  inject: ["piSession", "piPluginUi", "piTools"],
+  apply(context: Context) {
+    let sequence = 0;
+    let latest = readState(context);
+    const unregister = context.piTools.register(
+      defineTool({
+        name: "prompt_library",
+        label: "Prompt library",
+        description: "Save, search, update, and delete reusable prompt templates in the current Pi session.",
+        promptSnippet: "manage reusable prompts for the current project",
+        parameters: Type.Object({
+          action: Type.Union([Type.Literal("save"), Type.Literal("list"), Type.Literal("delete")]),
+          id: Type.Optional(Type.String()),
+          title: Type.Optional(Type.String()),
+          prompt: Type.Optional(Type.String()),
+          tags: Type.Optional(Type.Array(Type.String())),
+          query: Type.Optional(Type.String()),
+        }),
+        execute(_toolCallId, params): Promise<AgentToolResult<PromptLibraryState & { selected?: PromptTemplate }>> {
+          return Promise.resolve().then(() => {
+            const state = readState(context);
+            if (params.action === "save") {
+              const now = new Date().toISOString();
+              const existing = params.id?.trim() ? state.templates.find((template) => template.id === params.id?.trim()) : undefined;
+              const template = existing
+                ? {
+                    ...existing,
+                    title: bounded(params.title ?? existing.title, "title", maxTitleLength),
+                    prompt: bounded(params.prompt ?? existing.prompt, "prompt", maxPromptLength),
+                    tags: normalizeTags(params.tags ?? existing.tags),
+                    updatedAt: now,
+                  }
+                : createPromptTemplate(
+                    { title: params.title ?? "", prompt: params.prompt ?? "", ...(params.tags === undefined ? {} : { tags: params.tags }) },
+                    `prompt-${Date.now()}-${++sequence}`,
+                    now,
+                  );
+              const templates = existing
+                ? state.templates.map((item) => (item.id === existing.id ? template : item))
+                : [...state.templates, template].slice(-maxTemplates);
+              latest = { templates };
+              persist(context, latest);
+              return { content: [{ type: "text" as const, text: `Prompt ${template.id} saved.` }], details: { ...latest, selected: template } };
+            }
+            if (params.action === "delete") {
+              const id = params.id?.trim();
+              if (!id) throw new Error("id is required when action is delete");
+              if (!state.templates.some((template) => template.id === id)) throw new Error(`Prompt was not found: ${id}`);
+              latest = { templates: state.templates.filter((template) => template.id !== id) };
+              persist(context, latest);
+              return { content: [{ type: "text" as const, text: `Prompt ${id} deleted.` }], details: latest };
+            }
+            latest = state;
+            const templates = filterTemplates(state, params.query);
+            return {
+              content: [{ type: "text" as const, text: templates.map((template) => `${template.id}: ${template.title}`).join("\n") || "No prompts found." }],
+              details: { templates },
+            };
+          });
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "prompt-library-panel",
+      pluginId: "@pi-harness/core/plugins/prompt-library",
+      title: "Prompt Library",
+      description: "保存和检索可复用的提示词模板，数据跟随当前会话。",
+      icon: "✎",
+      read: () => ({ total: latest.templates.length, templates: latest.templates }),
+    });
+    context.effect(() => () => {
+      unregister();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/readme-gen.ts

@@ -0,0 +1,147 @@
+import { lstat, mkdir, readFile, realpath, rename, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import type { Context } from "@deepseek-ai/cordis";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+
+export type ReadmeMetadata = { name: string; version: string; description: string; scripts: string[]; plugins: string[] };
+export type ReadmeReport = ReadmeMetadata & { markdown: string };
+export type ReadmeWriteReport = { path: string; bytes: number; overwritten: boolean };
+
+export function renderReadme(metadata: ReadmeMetadata): string {
+  const { name, version, description, scripts, plugins } = metadata;
+  return [
+    `# ${name}`,
+    "",
+    description,
+    "",
+    `Version: ${version}`,
+    "",
+    "## Scripts",
+    "",
+    ...(scripts.length ? scripts.map((script) => `- \`npm run ${script}\``) : ["- No npm scripts declared."]),
+    "",
+    "## Runtime plugins",
+    "",
+    ...(plugins.length ? plugins.map((plugin) => `- \`${plugin}\``) : ["- No runtime plugins reported."]),
+    "",
+  ].join("\n");
+}
+
+async function generate(context: Context): Promise<ReadmeReport> {
+  const path = join(context.piHarnessLaunch.cwd, "package.json");
+  const source = await readFile(path, "utf8");
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(source) as unknown;
+  } catch (error) {
+    throw new Error(`Invalid package.json: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("package.json root must be an object");
+  const packageJson = parsed as Record<string, unknown>;
+  const name = typeof packageJson.name === "string" ? packageJson.name : "Unnamed project";
+  const version = typeof packageJson.version === "string" ? packageJson.version : "unknown";
+  const description = typeof packageJson.description === "string" ? packageJson.description : "";
+  const scripts =
+    packageJson.scripts !== null && typeof packageJson.scripts === "object" && !Array.isArray(packageJson.scripts)
+      ? Object.keys(packageJson.scripts).sort()
+      : [];
+  const loader = context.get("loader") as { entries(): Iterable<{ disabled?: boolean | null; options: { name: string } }> } | undefined;
+  const plugins =
+    loader === undefined
+      ? []
+      : [...loader.entries()]
+          .filter((entry) => !entry.disabled)
+          .map((entry) => entry.options.name)
+          .filter((plugin) => !plugin.startsWith("cordis:"))
+          .sort();
+  const metadata = { name, version, description, scripts, plugins };
+  return { ...metadata, markdown: renderReadme(metadata) };
+}
+
+function outputPath(root: string, requested: string): string {
+  const value = requested.trim() || "README.generated.md";
+  if (value.length > 512 || value.includes("\\")) throw new Error("README output path must be a relative POSIX path of at most 512 characters");
+  const resolvedRoot = resolve(root);
+  const target = resolve(resolvedRoot, value);
+  const remainder = relative(resolvedRoot, target);
+  if (remainder === ".." || remainder.startsWith(`..${"/"}`) || remainder.startsWith("/")) throw new Error("README output path must stay inside the workspace");
+  return target;
+}
+
+export async function writeReadmeFile(root: string, markdown: string, requestedPath: string, confirm: boolean): Promise<ReadmeWriteReport> {
+  if (!confirm) throw new Error("Writing a README requires confirm=true");
+  const workspace = await realpath(resolve(root));
+  const target = outputPath(workspace, requestedPath);
+  const parent = dirname(target);
+  await mkdir(parent, { recursive: true });
+  const realParent = await realpath(parent);
+  const parentRemainder = relative(workspace, realParent);
+  if (parentRemainder === ".." || parentRemainder.startsWith(`..${"/"}`) || parentRemainder.startsWith("/"))
+    throw new Error("README output path must stay inside the workspace");
+  let overwritten = false;
+  try {
+    const metadata = await lstat(target);
+    if (metadata.isSymbolicLink() || !metadata.isFile()) throw new Error("README output path must be a regular file and cannot be a symbolic link");
+    overwritten = true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  const temporary = join(parent, `.${basename(target)}.${randomUUID()}.tmp`);
+  await writeFile(temporary, markdown, { encoding: "utf8", mode: 0o600 });
+  await rename(temporary, target);
+  return { path: relative(workspace, target), bytes: Buffer.byteLength(markdown, "utf8"), overwritten };
+}
+
+export default {
+  name: "pi-readme-gen",
+  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  apply(context: Context) {
+    let latest: ReadmeReport | undefined;
+    let lastWrite: ReadmeWriteReport | undefined;
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "readme_report",
+        label: "README report",
+        description: "Generate a Markdown project overview from the local package manifest and active Pi runtime plugins.",
+        promptSnippet: "generate a project README overview",
+        parameters: Type.Object({}),
+        async execute(): Promise<AgentToolResult<ReadmeReport>> {
+          latest = await generate(context);
+          return { content: [{ type: "text", text: latest.markdown }], details: latest };
+        },
+      }),
+    );
+    const unregisterWrite = context.piTools.register(
+      defineTool({
+        name: "readme_write",
+        label: "Write README",
+        description: "Write the generated Markdown to a workspace file only after explicit confirmation; defaults to README.generated.md.",
+        promptSnippet: "write the generated README to a confirmed workspace path",
+        parameters: Type.Object({ outputPath: Type.Optional(Type.String()), confirm: Type.Boolean() }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<ReadmeWriteReport>> {
+          const report = latest ?? (latest = await generate(context));
+          lastWrite = await writeReadmeFile(context.piHarnessLaunch.cwd, report.markdown, params.outputPath ?? "README.generated.md", params.confirm);
+          return { content: [{ type: "text", text: `README written: ${lastWrite.path} (${lastWrite.bytes} bytes)` }], details: lastWrite };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "readme-gen-panel",
+      pluginId: "@pi-harness/core/plugins/readme-gen",
+      title: "README Generator",
+      description: "从当前项目清单生成 Markdown 概览；写入文件需要显式确认，默认不会覆盖 README。",
+      icon: "▰",
+      read: () =>
+        latest === undefined
+          ? { generated: false, lastWrite: lastWrite ?? null }
+          : { generated: true, name: latest.name, scripts: latest.scripts.length, plugins: latest.plugins.length, lastWrite: lastWrite ?? null },
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      unregisterWrite();
+      disposePanel();
+    });
+  },
+};