@pi-harness/pi-harness 0.1.2 → 0.1.3

package/packages/core/src/plugins/plan-execute.ts

@@ -0,0 +1,76 @@
+import type { Context } from "@deepseek-ai/cordis";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+
+type PlanStatus = "pending" | "in_progress" | "done" | "skipped";
+type PlanStep = { id: number; title: string; status: PlanStatus };
+type Plan = { title: string; steps: PlanStep[] };
+
+function requirePlan(plan: Plan | undefined): Plan {
+  if (!plan) throw new Error("No plan exists; create one with plan_create first");
+  return plan;
+}
+
+export default {
+  name: "pi-plan-execute",
+  inject: ["piPluginUi", "piTools"],
+  apply(context: Context) {
+    let plan: Plan | undefined;
+    const create = context.piTools.register(
+      defineTool({
+        name: "plan_create",
+        label: "Create plan",
+        description: "Create or replace a structured execution plan with ordered steps.",
+        promptSnippet: "create an execution plan before making a multi-step change",
+        parameters: Type.Object({ title: Type.String(), steps: Type.Array(Type.String()) }),
+        execute(_toolCallId, params): Promise<AgentToolResult<Plan>> {
+          return Promise.resolve().then(() => {
+            const title = params.title.trim();
+            const steps = params.steps.map((step) => step.trim());
+            if (!title) throw new Error("Plan title cannot be empty");
+            if (steps.length === 0 || steps.length > 50 || steps.some((step) => !step)) throw new Error("Plan must contain 1-50 non-empty steps");
+            plan = { title, steps: steps.map((step, index) => ({ id: index + 1, title: step, status: "pending" })) };
+            return { content: [{ type: "text" as const, text: `Plan created: ${title} (${steps.length} steps)` }], details: plan };
+          });
+        },
+      }),
+    );
+    const advance = context.piTools.register(
+      defineTool({
+        name: "plan_advance",
+        label: "Advance plan",
+        description: "Update one plan step to pending, in-progress, done, or skipped.",
+        promptSnippet: "update the current plan step status",
+        parameters: Type.Object({
+          step: Type.Number(),
+          status: Type.Union([Type.Literal("pending"), Type.Literal("in_progress"), Type.Literal("done"), Type.Literal("skipped")]),
+        }),
+        execute(_toolCallId, params): Promise<AgentToolResult<Plan>> {
+          return Promise.resolve().then(() => {
+            const current = requirePlan(plan);
+            const index = Math.trunc(params.step) - 1;
+            if (index < 0 || index >= current.steps.length) throw new Error(`Unknown plan step: ${params.step}`);
+            current.steps[index] = { ...current.steps[index]!, status: params.status };
+            return { content: [{ type: "text" as const, text: `Step ${params.step} is now ${params.status}` }], details: current };
+          });
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "plan-execute-panel",
+      pluginId: "@pi-harness/core/plugins/plan-execute",
+      title: "Plan Execute",
+      description: "把复杂任务拆成可追踪步骤，并实时推进执行状态。",
+      icon: "☷",
+      read: () => {
+        const steps = plan?.steps ?? [];
+        return { title: plan?.title ?? null, completed: steps.filter((step) => step.status === "done").length, total: steps.length, steps };
+      },
+    });
+    context.effect(() => () => {
+      create();
+      advance();
+      disposePanel();
+    });
+  },
+};

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

@@ -0,0 +1,232 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { basename, join, 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";
+import { parse } from "yaml";
+
+const maxScanEntries = 50;
+const packageNamePattern = /^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/u;
+const coreRowIds = new Set(["tools", "session", "llm", "web", "permission", "agent"]);
+const ignoredScanDirectories = new Set([".git", "node_modules", ".pi", "dist", "build"]);
+
+export function isPluginRepositoryName(name: string): boolean {
+  return (
+    name.length > 0 &&
+    !ignoredScanDirectories.has(name) &&
+    !name.startsWith(".") &&
+    (name.startsWith("dsh-") || name.startsWith("pi-") || name.endsWith("-plugin"))
+  );
+}
+const schemaChecks = [
+  { code: "no-manifest", label: "package.json exists and is valid JSON" },
+  { code: "invalid-name-format", label: "package name follows npm naming rules" },
+  { code: "missing-main-or-types", label: "main or types entry is declared" },
+  { code: "no-source-entry", label: "a source entry or src directory exists" },
+  { code: "no-patch", label: "Runtime patch or bundle declaration exists" },
+  { code: "malformed-patch", label: "patch root is a sequence of entries" },
+  { code: "duplicate-row-id", label: "patch row ids are unique" },
+  { code: "core-row-id", label: "patch does not replace core rows" },
+  { code: "missing-profile-install-example", label: "README contains a profile install example" },
+  { code: "core-modification-required", label: "installation does not require changing host source" },
+  { code: "no-build-script", label: "package declares a build script" },
+  { code: "missing-ts-ext-imports", label: "TypeScript relative imports include extensions" },
+] as const;
+
+type CheckStatus = "passed" | "failed" | "warning";
+type Check = { code: string; status: CheckStatus; message: string };
+export interface PluginCheckReport {
+  repo: string;
+  path: string;
+  kind: "registry" | "unknown";
+  verdict: "pass" | "warn" | "fail";
+  checks: { total: number; passed: number; failed: number; warned: number; skipped: number };
+  errors: Array<{ code: string; message: string }>;
+  warnings: Array<{ code: string; message: string }>;
+  suggestions: string[];
+}
+export interface PluginCheckScanReport {
+  root: string;
+  scanned: number;
+  reports: PluginCheckReport[];
+}
+
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function addIssue(checks: Check[], code: string, status: "failed" | "warning", message: string): void {
+  checks.push({ code, status, message });
+}
+function asObject(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}
+
+async function checkRepository(path: string, strict: boolean): Promise<PluginCheckReport> {
+  const root = resolve(path);
+  const checks: Check[] = [];
+  const suggestions: string[] = [];
+  let manifest: Record<string, unknown> | undefined;
+  try {
+    const parsed = JSON.parse(await readFile(join(root, "package.json"), "utf8")) as unknown;
+    manifest = asObject(parsed);
+  } catch {
+    addIssue(checks, "no-manifest", "failed", "package.json is missing or invalid JSON");
+  }
+  if (manifest !== undefined) checks.push({ code: "no-manifest", status: "passed", message: "package.json is readable" });
+  const packageName = typeof manifest?.name === "string" ? manifest.name : "";
+  if (packageName === "" || !packageNamePattern.test(packageName)) addIssue(checks, "invalid-name-format", "failed", "package name is not a valid npm name");
+  else checks.push({ code: "invalid-name-format", status: "passed", message: "package name is valid" });
+  const main = typeof manifest?.main === "string" ? manifest.main : undefined;
+  const types = typeof manifest?.types === "string" ? manifest.types : undefined;
+  if (main === undefined && types === undefined) addIssue(checks, "missing-main-or-types", "failed", "package.json declares neither main nor types");
+  else checks.push({ code: "missing-main-or-types", status: "passed", message: "an entry point is declared" });
+  if (await isDirectory(join(root, "src"))) checks.push({ code: "no-source-entry", status: "passed", message: "src directory exists" });
+  else if (main !== undefined && (await isDirectory(join(root, "dist"))))
+    checks.push({ code: "no-source-entry", status: "passed", message: "dist directory exists" });
+  else addIssue(checks, "no-source-entry", "failed", "no src or dist entry directory found");
+  const scripts = asObject(manifest?.scripts);
+  if (typeof scripts?.build === "string") checks.push({ code: "no-build-script", status: "passed", message: "build script exists" });
+  else addIssue(checks, "no-build-script", "warning", "package has no build script");
+  let readme: string;
+  try {
+    readme = await readFile(join(root, "README.md"), "utf8");
+  } catch {
+    readme = "";
+  }
+  let patchSource: string | undefined;
+  for (const filename of ["cordis.patch.yml", "dsh.bundle.patch"]) {
+    try {
+      patchSource = await readFile(join(root, filename), "utf8");
+      break;
+    } catch {
+      // Try the next supported patch filename.
+    }
+  }
+  if (patchSource === undefined) addIssue(checks, "no-patch", "failed", "no runtime patch or bundle declaration found");
+  else {
+    try {
+      const parsed = parse(patchSource) as unknown;
+      if (!Array.isArray(parsed)) addIssue(checks, "malformed-patch", "failed", "patch root must be a sequence");
+      else {
+        checks.push({ code: "malformed-patch", status: "passed", message: "patch root is a sequence" });
+        const ids = parsed.flatMap((entry) => {
+          const row = asObject(entry);
+          return typeof row?.id === "string" ? [row.id] : [];
+        });
+        if (new Set(ids).size !== ids.length) addIssue(checks, "duplicate-row-id", "failed", "patch contains duplicate row ids");
+        else checks.push({ code: "duplicate-row-id", status: "passed", message: "patch row ids are unique" });
+        if (ids.some((id) => coreRowIds.has(id))) addIssue(checks, "core-row-id", "failed", "patch attempts to replace a core row");
+        else checks.push({ code: "core-row-id", status: "passed", message: "patch does not replace core rows" });
+      }
+    } catch (error) {
+      addIssue(checks, "malformed-patch", "failed", "patch could not be parsed: " + (error instanceof Error ? error.message : String(error)));
+    }
+  }
+  if (/(?:dsh|pi)\s+plugin\s+--profile\s+\S+\s+add/iu.test(readme))
+    checks.push({ code: "missing-profile-install-example", status: "passed", message: "README has a profile install example" });
+  else addIssue(checks, "missing-profile-install-example", "warning", "README has no standard profile install example");
+  if (/(?:git\s+apply|cp\s+.*(?:monorepo|src\/)|modify\s+.*core)/iu.test(readme))
+    addIssue(checks, "core-modification-required", "failed", "README requires host source modification");
+  else checks.push({ code: "core-modification-required", status: "passed", message: "README does not require host source changes" });
+  if (await isDirectory(join(root, "src"))) {
+    const sourceDir = join(root, "src");
+    const files = (await readdir(sourceDir, { recursive: true })).filter((entry): entry is string => typeof entry === "string" && /\.(?:ts|tsx)$/u.test(entry));
+    const sources = await Promise.all(files.map((file) => readFile(join(sourceDir, file), "utf8")));
+    if (sources.some((source) => /from\s+["'][.][^"']*["']/u.test(source)))
+      addIssue(checks, "missing-ts-ext-imports", "warning", "a TypeScript relative import omits its file extension");
+    else checks.push({ code: "missing-ts-ext-imports", status: "passed", message: "relative imports include extensions or no source files were found" });
+  }
+  const errors = checks.filter((check) => check.status === "failed").map(({ code, message }) => ({ code, message }));
+  const warnings = checks.filter((check) => check.status === "warning").map(({ code, message }) => ({ code, message }));
+  if (errors.some((entry) => entry.code === "no-manifest" || entry.code === "missing-main-or-types"))
+    suggestions.push("Add a valid package.json with main/types and a buildable entry point.");
+  if (errors.some((entry) => entry.code === "no-patch" || entry.code === "malformed-patch"))
+    suggestions.push("Add a valid runtime patch sequence with a unique plugin row id.");
+  if (warnings.some((entry) => entry.code === "missing-profile-install-example"))
+    suggestions.push("Document the standard pi plugin --profile web add installation command.");
+  const verdict = errors.length > 0 || (strict && warnings.length > 0) ? "fail" : warnings.length > 0 ? "warn" : "pass";
+  const passed = checks.filter((check) => check.status === "passed").length;
+  return {
+    repo: basename(root),
+    path: root,
+    kind: manifest === undefined ? "unknown" : "registry",
+    verdict,
+    checks: { total: checks.length, passed, failed: errors.length, warned: warnings.length, skipped: Math.max(0, schemaChecks.length - checks.length) },
+    errors,
+    warnings,
+    suggestions,
+  };
+}
+
+function schemaReport(): { checks: Array<{ code: string; label: string }>; verdict: "pass" } {
+  return { checks: [...schemaChecks], verdict: "pass" };
+}
+
+export default {
+  name: "pi-plugin-check",
+  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  apply(context: Context, config: { scanLimit?: number }) {
+    const scanLimit = Math.max(1, Math.min(maxScanEntries, Math.trunc(config.scanLimit ?? maxScanEntries)));
+    let latest: PluginCheckReport | PluginCheckScanReport | ReturnType<typeof schemaReport> | undefined;
+    const run = async (action: "check" | "scan" | "schema", requestedPath: string | undefined, strict: boolean): Promise<unknown> => {
+      if (action === "schema") {
+        latest = schemaReport();
+        return latest;
+      }
+      const target = resolve(context.piHarnessLaunch.cwd, requestedPath ?? ".");
+      if (action === "check") {
+        latest = await checkRepository(target, strict);
+        return latest;
+      }
+      const entries = await readdir(target, { withFileTypes: true });
+      const candidates = entries
+        .filter((entry) => entry.isDirectory() && isPluginRepositoryName(entry.name))
+        .slice(0, scanLimit)
+        .map((entry) => join(target, entry.name));
+      const reports = await Promise.all(candidates.map((candidate) => checkRepository(candidate, strict)));
+      latest = { root: target, scanned: reports.length, reports };
+      return latest;
+    };
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "plugin_check",
+        label: "Check plugins",
+        description: "Read-only health checks for Pi Harness plugin repositories; never modifies or builds the inspected path.",
+        promptSnippet: "check a Pi Harness plugin repository",
+        parameters: Type.Object({
+          action: Type.Union(["check", "scan", "schema"]),
+          path: Type.Optional(Type.String({ description: "Repository path for check, parent directory for scan" })),
+          strict: Type.Optional(Type.Boolean({ description: "Treat warnings as errors" })),
+        }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<unknown>> {
+          const action = params.action;
+          if (action !== "check" && action !== "scan" && action !== "schema") throw new Error("plugin_check action must be check, scan, or schema");
+          const details = await run(action, params.path, params.strict === true);
+          const text =
+            action === "schema"
+              ? schemaChecks.length + " plugin health checks available."
+              : action === "scan"
+                ? "Scanned " + (details as PluginCheckScanReport).scanned + " plugin repositories."
+                : (details as PluginCheckReport).repo + ": " + (details as PluginCheckReport).verdict;
+          return { content: [{ type: "text", text }], details };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "plugin-check-panel",
+      pluginId: "@pi-harness/core/plugins/plugin-check",
+      title: "Plugin Check",
+      description: "只读检查插件清单、patch 和构建陷阱，不修改或构建被检仓库。",
+      icon: "✓",
+      read: () => ({ scanLimit, latest: latest ?? null }),
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};

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

@@ -0,0 +1,47 @@
+import type { Context } from "@deepseek-ai/cordis";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+
+type ReloadState = { status: "idle" | "reloaded" | "failed"; reason: string; reloadedAt?: string; error?: string };
+
+export default {
+  name: "pi-plugin-dev",
+  inject: ["piPluginUi", "piTools"],
+  apply(context: Context) {
+    let latest: ReloadState = { status: "idle", reason: "" };
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "plugin_dev_reload",
+        label: "Reload Pi plugins",
+        description: "Reload the current Pi session so local extension and plugin changes take effect.",
+        promptSnippet: "reload the live Pi session after changing a local plugin",
+        parameters: Type.Object({ reason: Type.Optional(Type.String({ description: "Why the reload is being requested" })) }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<ReloadState>> {
+          const reason = params.reason?.trim() || "manual plugin reload";
+          try {
+            const runtime = context.get("piRuntime") as { session: { reload(): Promise<void> } } | undefined;
+            if (runtime === undefined) throw new Error("Pi runtime is not available; enable the runtime plugin before reloading");
+            await runtime.session.reload();
+            latest = { status: "reloaded", reason, reloadedAt: new Date().toISOString() };
+            return { content: [{ type: "text", text: `Pi plugins reloaded: ${reason}` }], details: latest };
+          } catch (error) {
+            latest = { status: "failed", reason, error: error instanceof Error ? error.message : String(error) };
+            throw error;
+          }
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "plugin-dev-panel",
+      pluginId: "@pi-harness/core/plugins/plugin-dev",
+      title: "Plugin Dev",
+      description: "在本地插件改动后重载当前 Pi session。",
+      icon: "↻",
+      read: () => latest,
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};

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

@@ -0,0 +1,108 @@
+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 defaultRegistryUrl = "https://registry.npmjs.org";
+const defaultSearchKeyword = "pi-harness";
+const defaultLimit = 10;
+const maxQueryLength = 120;
+const maxKeywordLength = 64;
+
+type PluginSearchResult = { name: string; version: string; description: string; score: number; npm: string };
+type PluginSearchReport = { query: string; total: number; results: PluginSearchResult[] };
+
+function normalizeRegistryUrl(url: string | undefined): string {
+  const value = (url ?? defaultRegistryUrl).trim().replace(/\/+$/, "");
+  if (!/^https?:\/\//iu.test(value)) throw new Error("Plugin registry URL must use http or https");
+  return value;
+}
+
+export interface PluginFinderConfig {
+  registryUrl?: string;
+  limit?: number;
+  keyword?: string;
+}
+
+export const Config: z<PluginFinderConfig> = z.object({
+  registryUrl: z.string().default(defaultRegistryUrl),
+  limit: z.number().default(defaultLimit),
+  keyword: z.string().default(defaultSearchKeyword),
+});
+
+function normalizeSearchKeyword(keyword: string | undefined): string {
+  const value = (keyword ?? defaultSearchKeyword).trim();
+  if (value.length > maxKeywordLength || /\s/iu.test(value) || !/^[a-z0-9][a-z0-9._-]*$/iu.test(value))
+    throw new Error(`Plugin registry keyword must be 1-${maxKeywordLength} ASCII characters without whitespace`);
+  return value;
+}
+
+export default {
+  name: "pi-plugin-finder",
+  inject: ["piPluginUi", "piTools"],
+  Config,
+  apply(context: Context, config: PluginFinderConfig) {
+    const registryUrl = normalizeRegistryUrl(config.registryUrl);
+    const limit = Math.max(1, Math.min(25, Math.trunc(config.limit ?? defaultLimit)));
+    const keyword = normalizeSearchKeyword(config.keyword);
+    let latest: PluginSearchReport | undefined;
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "plugin_search",
+        label: "Search plugins",
+        description: "Search the configured npm registry for Pi Harness plugins. This is read-only and never installs packages.",
+        promptSnippet: "search the plugin registry for an extension",
+        parameters: Type.Object({ query: Type.String({ description: "Plugin name or capability keywords" }) }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<PluginSearchReport>> {
+          const query = params.query.trim();
+          if (query.length < 2 || query.length > maxQueryLength) throw new Error(`Plugin search query must contain 2-${maxQueryLength} characters`);
+          const search = new URLSearchParams({ text: `keywords:${keyword} ${query}`, size: String(limit) });
+          const response = await fetch(`${registryUrl}/-/v1/search?${search.toString()}`, { headers: { accept: "application/json" } });
+          if (!response.ok) throw new Error(`Plugin registry returned HTTP ${response.status}`);
+          const payload = (await response.json()) as { total?: unknown; objects?: unknown };
+          const objects = Array.isArray(payload.objects) ? payload.objects : [];
+          const results = objects.flatMap((entry): PluginSearchResult[] => {
+            if (entry === null || typeof entry !== "object") return [];
+            const item = entry as { package?: unknown; score?: unknown };
+            if (item.package === null || typeof item.package !== "object") return [];
+            const pkg = item.package as { name?: unknown; version?: unknown; description?: unknown; links?: unknown };
+            if (typeof pkg.name !== "string" || typeof pkg.version !== "string") return [];
+            const links = pkg.links !== null && typeof pkg.links === "object" ? (pkg.links as { npm?: unknown }) : {};
+            const score = item.score !== null && typeof item.score === "object" ? (item.score as { final?: unknown }).final : undefined;
+            return [
+              {
+                name: pkg.name,
+                version: pkg.version,
+                description: typeof pkg.description === "string" ? pkg.description : "",
+                score: typeof score === "number" && Number.isFinite(score) ? score : 0,
+                npm: typeof links.npm === "string" ? links.npm : `${registryUrl}/${pkg.name}`,
+              },
+            ];
+          });
+          latest = { query, total: typeof payload.total === "number" && Number.isFinite(payload.total) ? payload.total : results.length, results };
+          return {
+            content: [
+              {
+                type: "text",
+                text: results.length === 0 ? `No plugins found for ${query}.` : results.map((result) => `${result.name}@${result.version}`).join("\n"),
+              },
+            ],
+            details: latest,
+          };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "plugin-finder-panel",
+      pluginId: "@pi-harness/core/plugins/plugin-finder",
+      title: "Plugin Finder",
+      description: "只读搜索 npm Registry 中的 Pi Harness 插件，不会自动安装或执行未审核代码。",
+      icon: "⌕",
+      read: () => ({ registryUrl, keyword, limit, query: latest?.query ?? null, total: latest?.total ?? 0, results: latest?.results ?? [] }),
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};

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

@@ -0,0 +1,179 @@
+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 defaultApiUrl = "https://api.github.com";
+const defaultLimit = 10;
+const maxLimit = 25;
+const maxQueryLength = 80;
+const maxResponseBytes = 1024 * 1024;
+const radarTopics = ["topic:dsh-plugin", "topic:deepseek-harness"];
+
+export interface PluginRadarConfig {
+  apiUrl?: string;
+  limit?: number;
+}
+
+export interface PluginRadarResult {
+  name: string;
+  fullName: string;
+  url: string;
+  description: string;
+  stars: number;
+  language: string | null;
+  updatedAt: string;
+  topics: string[];
+}
+
+export interface PluginRadarReport {
+  query: string;
+  total: number;
+  results: PluginRadarResult[];
+  fetchedAt: string;
+  sources: string[];
+}
+
+function normalizeApiUrl(url: string | undefined): string {
+  const value = (url ?? defaultApiUrl).trim().replace(/\/+$/u, "");
+  if (!/^https:\/\//iu.test(value)) throw new Error("GitHub API URL must use HTTPS");
+  return value;
+}
+
+function normalizeQuery(value: string): string {
+  const query = value.trim();
+  if (query.length > maxQueryLength) throw new Error(`Plugin radar query must contain 0-${maxQueryLength} characters`);
+  return query;
+}
+
+function clampLimit(value: number | undefined): number {
+  return Math.max(1, Math.min(maxLimit, Math.trunc(value ?? defaultLimit)));
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}
+
+function asString(value: unknown, fallback: string): string {
+  return typeof value === "string" ? value : fallback;
+}
+
+function asNonNegativeInteger(value: unknown): number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : 0;
+}
+
+function asTopics(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string").slice(0, 12) : [];
+}
+
+function parseResults(payload: unknown): { total: number; results: PluginRadarResult[] } {
+  const root = asRecord(payload);
+  const items = root?.items;
+  const results = Array.isArray(items)
+    ? items.flatMap((entry): PluginRadarResult[] => {
+        const item = asRecord(entry);
+        if (item === undefined) return [];
+        const fullName = asString(item.full_name, "").trim();
+        const name = asString(item.name, "").trim();
+        const url = asString(item.html_url, "").trim();
+        if (fullName === "" || name === "" || !/^https:\/\/github\.com\//iu.test(url)) return [];
+        return [
+          {
+            name,
+            fullName,
+            url,
+            description: asString(item.description, ""),
+            stars: asNonNegativeInteger(item.stargazers_count),
+            language: typeof item.language === "string" ? item.language : null,
+            updatedAt: asString(item.updated_at, ""),
+            topics: asTopics(item.topics),
+          },
+        ];
+      })
+    : [];
+  return { total: asNonNegativeInteger(root?.total_count) || results.length, results };
+}
+
+async function readJson(response: Response): Promise<unknown> {
+  const body = await response.text();
+  if (new TextEncoder().encode(body).byteLength > maxResponseBytes) throw new Error("GitHub plugin radar response exceeded 1 MiB limit");
+  try {
+    return JSON.parse(body) as unknown;
+  } catch (error) {
+    throw new Error(`GitHub plugin radar returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+}
+
+async function searchPlugins(apiUrl: string, limit: number, rawQuery: string, signal?: AbortSignal): Promise<PluginRadarReport> {
+  const query = normalizeQuery(rawQuery);
+  const keyword = query.replaceAll('"', "");
+  const batches = await Promise.all(
+    radarTopics.map(async (topic) => {
+      const search = new URLSearchParams({
+        q: keyword === "" ? topic : `${topic} "${keyword}"`,
+        sort: "stars",
+        order: "desc",
+        per_page: String(limit),
+      });
+      const response = await fetch(`${apiUrl}/search/repositories?${search.toString()}`, {
+        headers: { accept: "application/vnd.github+json", "user-agent": "pi-harness-plugin-radar", "x-github-api-version": "2022-11-28" },
+        ...(signal === undefined ? {} : { signal }),
+      });
+      if (!response.ok) throw new Error(`GitHub plugin radar returned HTTP ${response.status}`);
+      return parseResults(await readJson(response)).results;
+    }),
+  );
+  const unique = new Map<string, PluginRadarResult>();
+  for (const item of batches.flat()) {
+    const current = unique.get(item.fullName);
+    if (current === undefined || item.stars > current.stars) unique.set(item.fullName, item);
+  }
+  const results = [...unique.values()].sort((left, right) => right.stars - left.stars || left.fullName.localeCompare(right.fullName)).slice(0, limit);
+  return { query, total: results.length, results, fetchedAt: new Date().toISOString(), sources: [...radarTopics] };
+}
+
+export default {
+  name: "pi-plugin-radar",
+  inject: ["piPluginUi", "piTools"],
+  apply(context: Context, config: PluginRadarConfig) {
+    const apiUrl = normalizeApiUrl(config.apiUrl);
+    const limit = clampLimit(config.limit);
+    let latest: PluginRadarReport | undefined;
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "plugin_radar_search",
+        label: "Search DSH plugins",
+        description: "Search GitHub for DSH and DeepSeek Harness plugins, sorted by stars. Read-only; never installs packages.",
+        promptSnippet: "find popular DSH plugins on GitHub",
+        parameters: Type.Object({
+          query: Type.Optional(Type.String({ description: "Capability or repository keywords; empty searches the full DSH ecosystem" })),
+        }),
+        async execute(_toolCallId, params, signal): Promise<AgentToolResult<PluginRadarReport>> {
+          latest = await searchPlugins(apiUrl, limit, params.query ?? "", signal);
+          const text =
+            latest.results.length === 0 ? "No DSH plugins found." : latest.results.map((item) => `${item.fullName} (${item.stars} stars)`).join("\n");
+          return { content: [{ type: "text", text }], details: latest };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "plugin-radar-panel",
+      pluginId: "@pi-harness/core/plugins/plugin-radar",
+      title: "Plugin Radar",
+      description: "只读发现 GitHub 上的 DSH 插件，按 Star 排序，不会自动安装代码。",
+      icon: "⌁",
+      read: () => ({
+        apiUrl,
+        limit,
+        query: latest?.query ?? null,
+        total: latest?.total ?? 0,
+        fetchedAt: latest?.fetchedAt ?? null,
+        sources: latest?.sources ?? [...radarTopics],
+        results: latest?.results ?? [],
+      }),
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};