pi-dynamic-help 0.1.0 → 0.2.0

package/extensions/help.ts

@@ -1,845 +1,6 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { basename, isAbsolute, join, relative } from "node:path";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { DynamicBorder, getAgentDir, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
-import { Container, Markdown, matchesKey, Text } from "@earendil-works/pi-tui";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerHelpExtension } from "../src/extension.js";
 
-export type ResourceKind = "command" | "tool" | "package" | "mcp";
-
-export type ResourceScope = "project" | "user" | "temporary" | "builtin";
-
-export interface IndexedItem {
-	key: string;
-	kind: ResourceKind;
-	name: string;
-	description?: string;
-	sourceLabel: string;
-	sourceRef?: string;
-	scope?: ResourceScope;
-	packageName?: string;
-	useCount: number;
-	lastUsedAt?: number;
-	lastSeenAt?: number;
-	pinned?: boolean;
-}
-
-export interface HelpState {
-	version: 2;
-	items: Record<string, IndexedItem>;
-	lastRefresh?: number;
-}
-
-interface LegacyHelpState {
-	version?: number;
-	items?: Record<string, Partial<IndexedItem> & { key?: string; kind?: ResourceKind; name?: string; source?: string; origin?: string }>;
-	lastRefresh?: number;
-}
-
-interface McpServerEntry {
-	name: string;
-	mode: string;
-	lifecycle?: string;
-	command?: string;
-	url?: string;
-}
-
-interface PackageEntry {
-	name: string;
-	scope: ResourceScope;
-}
-
-const PACKAGE_STATE_DIR = join(getAgentDir(), "state", "pi-dynamic-help");
-const STATE_FILE = join(PACKAGE_STATE_DIR, "state.json");
-const LEGACY_STATE_FILE = join(getAgentDir(), "state", "dynamic-help.json");
-const MAX_ITEMS = 250;
-const MAX_COMMON = 8;
-const MAX_SECTION = 16;
-const COMPACT_PREFIXES = ["local:", "project:", "pkg:", "mcp:", "npm:", "git:", "http://", "https://"];
-
-const BUILTIN_COMMANDS: Array<{ name: string; description: string }> = [
-	{ name: "model", description: "Switch models" },
-	{ name: "scoped-models", description: "Enable or disable models for cycling" },
-	{ name: "settings", description: "Open interactive settings" },
-	{ name: "resume", description: "Pick from previous sessions" },
-	{ name: "new", description: "Start a new session" },
-	{ name: "name", description: "Set session display name" },
-	{ name: "session", description: "Show session file, messages, tokens, and cost" },
-	{ name: "tree", description: "Navigate the current session tree" },
-	{ name: "fork", description: "Create a new session from an earlier user message" },
-	{ name: "clone", description: "Duplicate the current active branch" },
-	{ name: "compact", description: "Summarize older context" },
-	{ name: "copy", description: "Copy the last assistant message" },
-	{ name: "export", description: "Export the session to HTML" },
-	{ name: "share", description: "Upload the session as a private gist" },
-	{ name: "reload", description: "Reload extensions, skills, prompts, and context files" },
-	{ name: "hotkeys", description: "Show keyboard shortcuts" },
-	{ name: "changelog", description: "Display version history" },
-	{ name: "quit", description: "Quit Pi" },
-];
-
-const MCP_CONFIG_FILES = [
-	join(homedir(), ".config", "mcp", "mcp.json"),
-	join(getAgentDir(), "mcp.json"),
-];
-
-function ensurePackageStateDir(): void {
-	if (!existsSync(PACKAGE_STATE_DIR)) {
-		mkdirSync(PACKAGE_STATE_DIR, { recursive: true });
-	}
-}
-
-function loadJson<T>(path: string, fallback: T): T {
-	if (!existsSync(path)) {
-		return fallback;
-	}
-
-	try {
-		return JSON.parse(readFileSync(path, "utf-8")) as T;
-	} catch {
-		return fallback;
-	}
-}
-
-function saveJson(path: string, data: unknown): void {
-	ensurePackageStateDir();
-	writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`);
-}
-
-function emptyState(): HelpState {
-	return { version: 2, items: {} };
-}
-
-function loadState(): HelpState {
-	const current = loadJson<LegacyHelpState | HelpState | undefined>(STATE_FILE, undefined);
-	if (current?.items) {
-		return migrateState(current);
-	}
-
-	const legacy = loadJson<LegacyHelpState | undefined>(LEGACY_STATE_FILE, undefined);
-	const migrated = migrateState(legacy ?? emptyState());
-	if (legacy?.items) {
-		saveJson(STATE_FILE, migrated);
-	}
-	return migrated;
-}
-
-function legacySourceFromKey(key: string | undefined): string | undefined {
-	if (!key) return undefined;
-	const first = key.indexOf(":");
-	const last = key.lastIndexOf(":");
-	if (first < 0 || last <= first) return undefined;
-	return key.slice(first + 1, last);
-}
-
-function sourceLabelForLegacy(kind: ResourceKind, source?: string, scope?: ResourceScope): string {
-	if (kind === "package") return sourceLabelForPackage(source ?? "package");
-	if (kind === "mcp") return source === "mcp" ? "内置网关" : "MCP 服务器";
-	if (kind === "tool") return sourceLabelForTool({ source, scope });
-	return sourceLabelForCommand({ source, scope });
-}
-
-function mergeMigratedItem(existing: IndexedItem | undefined, next: IndexedItem): IndexedItem {
-	if (!existing) return next;
-
-	return {
-		...existing,
-		...next,
-		useCount: Math.max(existing.useCount ?? 0, next.useCount ?? 0),
-		lastUsedAt: Math.max(existing.lastUsedAt ?? 0, next.lastUsedAt ?? 0) || undefined,
-		lastSeenAt: Math.max(existing.lastSeenAt ?? 0, next.lastSeenAt ?? 0) || undefined,
-		pinned: Boolean(existing.pinned || next.pinned),
-	};
-}
-
-export function migrateState(state: LegacyHelpState | HelpState): HelpState {
-	const items: Record<string, IndexedItem> = {};
-
-	for (const raw of Object.values(state.items ?? {})) {
-		if (!raw.kind || !raw.name) continue;
-		const rawSource = raw.sourceRef ?? raw.source ?? legacySourceFromKey(raw.key) ?? raw.packageName ?? raw.sourceLabel;
-		const sourceRef = compactSourceRef(rawSource);
-		const sourceLabel = raw.sourceLabel && !isAbsolute(raw.sourceLabel) ? raw.sourceLabel : sourceLabelForLegacy(raw.kind, rawSource, raw.scope);
-		const next: IndexedItem = {
-			key: makeKey(raw.kind, raw.name, sourceRef),
-			kind: raw.kind,
-			name: raw.name,
-			description: raw.description,
-			sourceLabel,
-			sourceRef,
-			scope: raw.scope,
-			packageName: raw.packageName,
-			useCount: raw.useCount ?? 0,
-			lastUsedAt: raw.lastUsedAt,
-			lastSeenAt: raw.lastSeenAt,
-			pinned: raw.pinned,
-		};
-
-		items[next.key] = mergeMigratedItem(items[next.key], next);
-	}
-
-	return {
-		version: 2,
-		items,
-		lastRefresh: state.lastRefresh,
-	};
-}
-
-function normalize(value: string | undefined): string {
-	return (value ?? "")
-		.toLowerCase()
-		.replace(/[^a-z0-9\u4e00-\u9fff]+/g, " ")
-		.trim();
-}
-
-function extractPackageNameFromPath(source: string): string | undefined {
-	const match = source.replace(/\\/g, "/").match(/\/node_modules\/(.*)$/);
-	if (!match) return undefined;
-
-	const parts = match[1].split("/").filter(Boolean);
-	if (parts.length === 0) return undefined;
-	if (parts[0].startsWith("@")) {
-		return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : parts[0];
-	}
-
-	return parts[0];
-}
-
-function stripRepeatedLocalPrefixes(value: string): string {
-	let next = value;
-	while (next.startsWith("local:local:")) {
-		next = next.slice("local:".length);
-	}
-	return next;
-}
-
-function unwrapLocalWrappedCompactRef(value: string): string {
-	if (!value.startsWith("local:")) return value;
-
-	const inner = value.slice("local:".length);
-	if (inner === "builtin" || inner === "sdk" || inner === "unknown") return inner;
-	if (COMPACT_PREFIXES.filter((prefix) => prefix !== "local:").some((prefix) => inner.startsWith(prefix))) {
-		return inner;
-	}
-	return value;
-}
-
-export function compactSourceRef(source?: string): string {
-	if (!source) return "unknown";
-
-	const normalized = unwrapLocalWrappedCompactRef(stripRepeatedLocalPrefixes(source.replace(/\\/g, "/")));
-	if (normalized === "builtin" || normalized === "sdk" || normalized === "unknown") return normalized;
-	if (COMPACT_PREFIXES.some((prefix) => normalized.startsWith(prefix))) return normalized;
-
-	const packageName = extractPackageNameFromPath(normalized);
-	if (packageName) return `pkg:${packageName}`;
-
-	if (isAbsolute(normalized)) {
-		const homeRelative = relative(homedir(), normalized).replace(/\\/g, "/");
-		if (homeRelative && !homeRelative.startsWith("..")) {
-			return `local:${homeRelative}`;
-		}
-
-		return `local:${basename(normalized)}`;
-	}
-
-	return `local:${normalized}`;
-}
-
-export function makeKey(kind: ResourceKind, name: string, sourceRef: string): string {
-	return `${kind}:${sourceRef}:${name}`;
-}
-
-function getProjectSettingsPath(cwd: string): string {
-	return join(cwd, ".pi", "settings.json");
-}
-
-function getProjectMcpPath(cwd: string): string {
-	return join(cwd, ".mcp.json");
-}
-
-function getProjectPiMcpPath(cwd: string): string {
-	return join(cwd, ".pi", "mcp.json");
-}
-
-export function readPackagesFromSettings(path: string, scope: ResourceScope): PackageEntry[] {
-	const settings = loadJson<Record<string, unknown>>(path, {});
-	const raw = Array.isArray(settings.packages) ? settings.packages : [];
-	const values: PackageEntry[] = [];
-
-	for (const entry of raw) {
-		if (typeof entry === "string") {
-			values.push({ name: entry, scope });
-			continue;
-		}
-
-		if (!entry || typeof entry !== "object") {
-			continue;
-		}
-
-		const obj = entry as Record<string, unknown>;
-		if (typeof obj.source === "string") {
-			values.push({ name: obj.source, scope });
-			continue;
-		}
-
-		if (typeof obj.package === "string") {
-			values.push({ name: obj.package, scope });
-		}
-	}
-
-	return values;
-}
-
-function mergePackageEntries(entries: PackageEntry[]): PackageEntry[] {
-	const byName = new Map<string, PackageEntry>();
-	for (const entry of entries) {
-		const existing = byName.get(entry.name);
-		if (!existing || existing.scope !== "project") {
-			byName.set(entry.name, entry);
-		}
-	}
-	return [...byName.values()];
-}
-
-function readMcpServersFromConfig(path: string): McpServerEntry[] {
-	const config = loadJson<Record<string, unknown>>(path, {});
-	const servers = config.mcpServers;
-	if (!servers || typeof servers !== "object") {
-		return [];
-	}
-
-	const entries: McpServerEntry[] = [];
-	for (const [name, value] of Object.entries(servers as Record<string, unknown>)) {
-		if (!value || typeof value !== "object") {
-			continue;
-		}
-
-		const server = value as Record<string, unknown>;
-		const command = typeof server.command === "string" ? server.command : undefined;
-		const url = typeof server.url === "string" ? server.url : undefined;
-		const lifecycle = typeof server.lifecycle === "string" ? server.lifecycle : undefined;
-		const mode = url ? "http" : "stdio";
-
-		entries.push({ name, mode, lifecycle, command, url });
-	}
-
-	return entries;
-}
-
-function sourceLabelForCommand(sourceInfo: { source?: string; scope?: ResourceScope; origin?: string }): string {
-	const source = sourceInfo.source?.replace(/\\/g, "/");
-	if (!source) return "未知";
-	if (source === "builtin") return "内置";
-	if (source === "sdk") return "SDK";
-	if (source === "local") return sourceInfo.scope === "project" ? "项目本地" : "全局本地";
-	if (sourceInfo.origin === "package") {
-		const pkg = extractPackageNameFromPath(source) ?? (source.startsWith("npm:") ? source.slice("npm:".length) : undefined);
-		return pkg ? `npm:${pkg}` : sourceLabelForPackage(source);
-	}
-	if (source === "extension") return "扩展";
-	if (source === "prompt") return "模板";
-	if (source === "skill") return "技能";
-	if (source.startsWith("npm:") || source.startsWith("git:") || source.startsWith("http://") || source.startsWith("https://")) return source;
-	if (isAbsolute(source)) {
-		const pkg = extractPackageNameFromPath(source);
-		if (pkg) return `npm:${pkg}`;
-		return sourceInfo.scope === "project" ? "项目本地" : "全局本地";
-	}
-	return source;
-}
-
-function sourceLabelForTool(sourceInfo: { source?: string; scope?: ResourceScope; origin?: string }): string {
-	const source = sourceInfo.source?.replace(/\\/g, "/");
-	if (!source) return "未知工具";
-	if (source === "builtin") return "内置工具";
-	if (source === "sdk") return "SDK 工具";
-	if (source === "local") return sourceInfo.scope === "project" ? "项目扩展" : "全局扩展";
-	if (sourceInfo.origin === "package") {
-		const pkg = extractPackageNameFromPath(source) ?? (source.startsWith("npm:") ? source.slice("npm:".length) : undefined);
-		return pkg ? `npm:${pkg}` : sourceLabelForPackage(source);
-	}
-	if (source.startsWith("npm:") || source.startsWith("git:") || source.startsWith("http://") || source.startsWith("https://")) return source;
-	if (isAbsolute(source)) {
-		const pkg = extractPackageNameFromPath(source);
-		if (pkg) return `npm:${pkg}`;
-		return sourceInfo.scope === "project" ? "项目扩展" : "全局扩展";
-	}
-	return source;
-}
-
-function sourceLabelForPackage(pkg: string): string {
-	if (pkg.startsWith("npm:")) return pkg;
-	if (pkg.startsWith("git:")) return "git";
-	if (pkg.startsWith("http://") || pkg.startsWith("https://")) return "git";
-	if (pkg.startsWith("./") || pkg.startsWith("../") || isAbsolute(pkg)) return "本地包";
-	return `npm:${pkg}`;
-}
-
-function sourceLabelForMcp(server: McpServerEntry): string {
-	const bits = [server.mode === "http" ? "HTTP" : "stdio"];
-	if (server.lifecycle) bits.push(server.lifecycle);
-	return bits.join(" · ");
-}
-
-function upsertItem(state: HelpState, item: IndexedItem): IndexedItem {
-	const existing = state.items[item.key];
-	const merged: IndexedItem = {
-		...existing,
-		...item,
-		useCount: existing?.useCount ?? item.useCount ?? 0,
-		lastUsedAt: existing?.lastUsedAt ?? item.lastUsedAt,
-		lastSeenAt: existing?.lastSeenAt ?? item.lastSeenAt,
-		pinned: existing?.pinned ?? item.pinned ?? false,
-	};
-	state.items[item.key] = merged;
-	return merged;
-}
-
-function recordUsage(state: HelpState, key: string): void {
-	const item = state.items[key];
-	if (!item) return;
-	item.useCount = (item.useCount ?? 0) + 1;
-	item.lastUsedAt = Date.now();
-	item.lastSeenAt = Date.now();
-}
-
-function recordUsageByName(state: HelpState, kind: ResourceKind, name: string): void {
-	const matches = Object.values(state.items).filter((item) => item.kind === kind && item.name === name);
-	if (matches.length === 0) return;
-	const target = [...matches].sort(sortItems)[0];
-	if (!target) return;
-	recordUsage(state, target.key);
-}
-
-function syncSessionUsage(ctx: ExtensionContext, state: HelpState): void {
-	for (const entry of ctx.sessionManager.getBranch()) {
-		const entryType = (entry as { type?: string }).type;
-		if (entryType === "bashExecution") {
-			recordUsageByName(state, "tool", "bash");
-			continue;
-		}
-
-		if (entryType !== "message") continue;
-		const message = (entry as { message?: unknown }).message as {
-			role?: string;
-			toolName?: string;
-			content?: unknown;
-		} | undefined;
-		if (!message) continue;
-
-		if (message.role === "toolResult" && typeof message.toolName === "string") {
-			recordUsageByName(state, "tool", message.toolName);
-			if (message.toolName === "mcp") {
-				recordUsageByName(state, "mcp", "mcp");
-			}
-		}
-
-		if (message.role === "assistant" && Array.isArray(message.content)) {
-			for (const block of message.content) {
-				if (!block || typeof block !== "object") continue;
-				const toolCall = block as { type?: string; name?: string };
-				if (toolCall.type === "toolCall" && typeof toolCall.name === "string") {
-					recordUsageByName(state, "tool", toolCall.name);
-				}
-			}
-		}
-	}
-}
-
-function syncMcpUsageFromResult(state: HelpState, event: { toolName: string; input?: { server?: string } | undefined }): void {
-	if (event.toolName !== "mcp") return;
-	recordUsageByName(state, "mcp", "mcp");
-	if (event.input?.server) {
-		recordUsageByName(state, "mcp", event.input.server);
-	}
-}
-
-function pruneState(state: HelpState): void {
-	const items = Object.values(state.items);
-	if (items.length <= MAX_ITEMS) return;
-
-	const removable = items
-		.filter((item) => !item.pinned)
-		.sort((a, b) => {
-			if ((a.useCount ?? 0) !== (b.useCount ?? 0)) {
-				return (a.useCount ?? 0) - (b.useCount ?? 0);
-			}
-			return (a.lastUsedAt ?? 0) - (b.lastUsedAt ?? 0);
-		});
-
-	while (Object.keys(state.items).length > MAX_ITEMS && removable.length > 0) {
-		const victim = removable.shift();
-		if (victim) {
-			delete state.items[victim.key];
-		}
-	}
-}
-
-function sortItems(a: IndexedItem, b: IndexedItem): number {
-	if ((a.pinned ? 1 : 0) !== (b.pinned ? 1 : 0)) return (b.pinned ? 1 : 0) - (a.pinned ? 1 : 0);
-	if ((a.useCount ?? 0) !== (b.useCount ?? 0)) return (b.useCount ?? 0) - (a.useCount ?? 0);
-	if ((a.lastUsedAt ?? 0) !== (b.lastUsedAt ?? 0)) return (b.lastUsedAt ?? 0) - (a.lastUsedAt ?? 0);
-	return a.name.localeCompare(b.name);
-}
-
-function formatItem(item: IndexedItem): string {
-	const meta = item.sourceLabel && !isAbsolute(item.sourceLabel) ? [item.sourceLabel] : [];
-	if (item.scope && item.scope !== "builtin") {
-		meta.push(item.scope === "project" ? "项目" : item.scope === "user" ? "全局" : item.scope);
-	}
-	if ((item.useCount ?? 0) > 0) {
-		meta.push(`使用 ${item.useCount} 次`);
-	}
-	if (item.pinned) {
-		meta.push("已固定");
-	}
-	const suffix = meta.length > 0 ? ` · ${meta.join(" · ")}` : "";
-	const desc = item.description ? ` — ${item.description}` : "";
-	return `- **${item.name}**${desc}${suffix}`;
-}
-
-function normalizeResourceIndex(pi: ExtensionAPI, ctx: ExtensionContext, state: HelpState): { commands: IndexedItem[]; tools: IndexedItem[]; mcp: IndexedItem[]; packages: IndexedItem[] } {
-	const commands = pi.getCommands();
-	const tools = pi.getAllTools();
-	const packages = mergePackageEntries([
-		...readPackagesFromSettings(join(getAgentDir(), "settings.json"), "user"),
-		...readPackagesFromSettings(getProjectSettingsPath(ctx.cwd), "project"),
-	]);
-	const mcpServers = [
-		...readMcpServersFromConfig(MCP_CONFIG_FILES[0]),
-		...readMcpServersFromConfig(MCP_CONFIG_FILES[1]),
-		...readMcpServersFromConfig(getProjectMcpPath(ctx.cwd)),
-		...readMcpServersFromConfig(getProjectPiMcpPath(ctx.cwd)),
-	];
-
-	const mergedMcp = new Map<string, McpServerEntry>();
-	for (const server of mcpServers) {
-		mergedMcp.set(server.name, server);
-	}
-
-	const commandItems: IndexedItem[] = [];
-	for (const command of commands) {
-		const sourceRef = compactSourceRef(command.sourceInfo.source ?? command.sourceInfo.origin ?? command.sourceInfo.scope);
-		const sourceLabel = sourceLabelForCommand(command.sourceInfo);
-		const key = makeKey("command", command.name, sourceRef);
-		commandItems.push(upsertItem(state, {
-			key,
-			kind: "command",
-			name: `/${command.name}`,
-			description: command.description,
-			sourceLabel,
-			sourceRef,
-			scope: command.sourceInfo.scope,
-			packageName: command.sourceInfo.source,
-			useCount: state.items[key]?.useCount ?? 0,
-			lastUsedAt: state.items[key]?.lastUsedAt,
-			lastSeenAt: state.items[key]?.lastSeenAt,
-			pinned: state.items[key]?.pinned,
-		}));
-	}
-
-	for (const builtin of BUILTIN_COMMANDS) {
-		const sourceRef = "builtin";
-		const key = makeKey("command", builtin.name, sourceRef);
-		commandItems.push(upsertItem(state, {
-			key,
-			kind: "command",
-			name: `/${builtin.name}`,
-			description: builtin.description,
-			sourceLabel: "内置",
-			sourceRef,
-			scope: "builtin",
-			useCount: state.items[key]?.useCount ?? 0,
-			lastUsedAt: state.items[key]?.lastUsedAt,
-			lastSeenAt: state.items[key]?.lastSeenAt,
-			pinned: state.items[key]?.pinned,
-		}));
-	}
-
-	const toolItems: IndexedItem[] = [];
-	for (const tool of tools) {
-		if (tool.name === "mcp") continue;
-		const sourceRef = compactSourceRef(tool.sourceInfo.source ?? tool.sourceInfo.origin ?? tool.sourceInfo.scope);
-		const sourceLabel = sourceLabelForTool(tool.sourceInfo);
-		const key = makeKey("tool", tool.name, sourceRef);
-		toolItems.push(upsertItem(state, {
-			key,
-			kind: "tool",
-			name: tool.name,
-			description: tool.description,
-			sourceLabel,
-			sourceRef,
-			scope: tool.sourceInfo.scope,
-			packageName: tool.sourceInfo.source,
-			useCount: state.items[key]?.useCount ?? 0,
-			lastUsedAt: state.items[key]?.lastUsedAt,
-			lastSeenAt: state.items[key]?.lastSeenAt,
-			pinned: state.items[key]?.pinned,
-		}));
-	}
-
-	const packageItems: IndexedItem[] = [];
-	for (const pkg of packages) {
-		const sourceRef = compactSourceRef(pkg.name);
-		const sourceLabel = sourceLabelForPackage(pkg.name);
-		const key = makeKey("package", pkg.name, sourceRef);
-		packageItems.push(upsertItem(state, {
-			key,
-			kind: "package",
-			name: pkg.name,
-			description: "已安装包",
-			sourceLabel,
-			sourceRef,
-			scope: pkg.scope,
-			packageName: pkg.name,
-			useCount: state.items[key]?.useCount ?? 0,
-			lastUsedAt: state.items[key]?.lastUsedAt,
-			lastSeenAt: state.items[key]?.lastSeenAt,
-			pinned: state.items[key]?.pinned,
-		}));
-	}
-
-	const mcpItems: IndexedItem[] = [];
-	const gatewaySourceRef = "mcp:gateway";
-	const gatewayKey = makeKey("mcp", "mcp", gatewaySourceRef);
-	mcpItems.push(upsertItem(state, {
-		key: gatewayKey,
-		kind: "mcp",
-		name: "mcp",
-		description: "显示 MCP 服务器状态",
-		sourceLabel: "内置网关",
-		sourceRef: gatewaySourceRef,
-		scope: "builtin",
-		useCount: state.items[gatewayKey]?.useCount ?? 0,
-		lastUsedAt: state.items[gatewayKey]?.lastUsedAt,
-		lastSeenAt: state.items[gatewayKey]?.lastSeenAt,
-		pinned: state.items[gatewayKey]?.pinned,
-	}));
-	for (const server of mergedMcp.values()) {
-		const sourceRef = `mcp:${server.name}`;
-		const sourceLabel = sourceLabelForMcp(server);
-		const key = makeKey("mcp", server.name, sourceRef);
-		mcpItems.push(upsertItem(state, {
-			key,
-			kind: "mcp",
-			name: server.name,
-			description: server.url ? server.url : server.command ? server.command : "MCP 服务器",
-			sourceLabel,
-			sourceRef,
-			scope: "user",
-			packageName: server.command ?? server.url,
-			useCount: state.items[key]?.useCount ?? 0,
-			lastUsedAt: state.items[key]?.lastUsedAt,
-			lastSeenAt: state.items[key]?.lastSeenAt,
-			pinned: state.items[key]?.pinned,
-		}));
-	}
-
-	pruneState(state);
-	state.lastRefresh = Date.now();
-	saveJson(STATE_FILE, state);
-
-	return { commands: commandItems, tools: toolItems, mcp: mcpItems, packages: packageItems };
-}
-
-function selectTop(items: IndexedItem[], count: number): IndexedItem[] {
-	return [...items].sort(sortItems).slice(0, count);
-}
-
-function renderSection(title: string, items: IndexedItem[], emptyText: string): string {
-	if (items.length === 0) {
-		return [`## ${title}`, `- ${emptyText}`].join("\n");
-	}
-
-	return [`## ${title}`, items.map(formatItem).join("\n")].join("\n");
-}
-
-export function buildMarkdown(pi: ExtensionAPI, ctx: ExtensionContext, state: HelpState, query?: string): string {
-	const index = normalizeResourceIndex(pi, ctx, state);
-	const normalizedQuery = normalize(query);
-
-	const allVisible = [
-		...index.commands,
-		...index.tools,
-		...index.mcp,
-		...index.packages,
-	].filter((item) => {
-		if (!normalizedQuery) return true;
-		return normalize([item.name, item.description, item.sourceLabel, item.packageName, item.sourceRef, item.kind].join(" ")).includes(normalizedQuery);
-	});
-
-	const commonCommands = selectTop(allVisible.filter((item) => item.kind === "command"), MAX_COMMON);
-	const commonTools = selectTop(allVisible.filter((item) => item.kind === "tool"), MAX_COMMON);
-	const commonMcp = selectTop(allVisible.filter((item) => item.kind === "mcp"), MAX_COMMON);
-	const commonPackages = selectTop(allVisible.filter((item) => item.kind === "package"), MAX_COMMON);
-
-	const commandItems = selectTop(allVisible.filter((item) => item.kind === "command"), MAX_SECTION);
-	const toolItems = selectTop(allVisible.filter((item) => item.kind === "tool"), MAX_SECTION);
-	const mcpItems = selectTop(allVisible.filter((item) => item.kind === "mcp"), MAX_SECTION);
-	const packageItems = selectTop(allVisible.filter((item) => item.kind === "package"), MAX_SECTION);
-
-	const gatewayItems = mcpItems.filter((item) => item.name === "mcp");
-	const serverItems = mcpItems.filter((item) => item.name !== "mcp");
-
-	const updatedAt = state.lastRefresh ? new Date(state.lastRefresh).toLocaleString() : new Date().toLocaleString();
-	const title = normalizedQuery ? `动态帮助 · 搜索：${query?.trim()}` : "动态帮助";
-
-	const mcpUsageLines = [
-		"### 用法",
-		"- `mcp({})` 查看状态",
-		"- `mcp({ server: \"chrome-devtools\" })` 列出服务器工具",
-		"- `mcp({ search: \"screenshot\" })` 搜索工具",
-		"- `mcp({ tool: \"...\", args: '{\"...\"}' })` 调用工具",
-	].join("\n");
-
-	return [
-		`# ${title}`,
-		`_更新时间：${updatedAt}_`,
-		"",
-		`> 已加载：${index.commands.length} 条命令 · ${index.tools.length} 个工具 · ${index.mcp.length} 个 MCP 服务器 · ${index.packages.length} 个包`,
-		"",
-		renderSection("常用命令", commonCommands, "暂无"),
-		"",
-		renderSection("常用工具", commonTools, "暂无"),
-		"",
-		renderSection("常用 MCP 服务器", commonMcp, "暂无"),
-		"",
-		renderSection("常用包", commonPackages, "暂无"),
-		"",
-		"## 命令",
-		commandItems.length > 0 ? commandItems.map(formatItem).join("\n") : "- 暂无",
-		"",
-		"## 工具",
-		toolItems.length > 0 ? toolItems.map(formatItem).join("\n") : "- 暂无",
-		"",
-		"## MCP 服务器",
-		"### 网关",
-		gatewayItems.length > 0 ? gatewayItems.map(formatItem).join("\n") : "- 暂无",
-		"",
-		mcpUsageLines,
-		"",
-		"### 服务器",
-		serverItems.length > 0 ? serverItems.map(formatItem).join("\n") : "- 暂无",
-		"",
-		"## 包",
-		packageItems.length > 0 ? packageItems.map(formatItem).join("\n") : "- 暂无",
-		"",
-		"## 操作",
-		"- `/help search <词>` 搜索当前索引",
-		"- `/help pin <词>` 固定匹配项",
-		"- `/help unpin <词>` 取消固定",
-		"- `/help refresh` 重新扫描并刷新使用统计",
-		"",
-		"## 示例",
-		"- `需求分析：...`",
-		"- `系统设计：...`",
-		"- `实现：...`",
-		"- `审查：...`",
-		"- `/goal ...`",
-		"- `/brainstorm ...`",
-	].join("\n");
-}
-
-async function showMarkdownPanel(ctx: ExtensionContext, markdown: string): Promise<void> {
-	if (!ctx.hasUI) {
-		console.log(markdown);
-		return;
-	}
-
-	await ctx.ui.custom((_tui, theme, _kb, done) => {
-		const container = new Container();
-		const border = new DynamicBorder((s: string) => theme.fg("accent", s));
-		const mdTheme = getMarkdownTheme();
-
-		container.addChild(border);
-		container.addChild(new Text(theme.fg("accent", theme.bold("Pi 帮助")), 1, 0));
-		container.addChild(new Markdown(markdown, 1, 1, mdTheme));
-		container.addChild(new Text(theme.fg("dim", "按 Enter 或 Esc 关闭"), 1, 0));
-		container.addChild(border);
-
-		return {
-			render: (width: number) => container.render(width),
-			invalidate: () => container.invalidate(),
-			handleInput: (data: string) => {
-				if (matchesKey(data, "enter") || matchesKey(data, "escape")) {
-					done(undefined);
-				}
-			},
-		};
-	});
-}
-
-function findMatches(state: HelpState, query: string): IndexedItem[] {
-	const normalizedQuery = normalize(query);
-	if (!normalizedQuery) return [];
-	return Object.values(state.items)
-		.filter((item) => normalize([item.name, item.description, item.sourceLabel, item.packageName, item.sourceRef, item.kind].join(" ")).includes(normalizedQuery))
-		.sort(sortItems);
-}
-
-function refreshState(pi: ExtensionAPI, ctx: ExtensionContext, state: HelpState): void {
-	syncSessionUsage(ctx, state);
-	// Make sure MCP/package caches are always rebuilt on refresh.
-	normalizeResourceIndex(pi, ctx, state);
-	saveJson(STATE_FILE, state);
-}
-
-export default function (pi: ExtensionAPI) {
-	const state = loadState();
-
-	pi.registerCommand("help", {
-		description: "Show a dynamic help dashboard for installed Pi resources",
-		handler: async (args, ctx) => {
-			const trimmed = args.trim();
-			const [subcommand, ...rest] = trimmed.length > 0 ? trimmed.split(/\s+/) : [""];
-			const query = rest.join(" ").trim();
-
-			if (subcommand === "refresh") {
-				refreshState(pi, ctx, state);
-				ctx.ui.notify("帮助索引已刷新", "info");
-				return;
-			}
-
-			if (subcommand === "pin" || subcommand === "unpin") {
-				refreshState(pi, ctx, state);
-				const matches = findMatches(state, query);
-				if (matches.length === 0) {
-					ctx.ui.notify(`未找到：${query || "<空>"}`, "warning");
-					return;
-				}
-
-				const target = matches[0];
-				target.pinned = subcommand === "pin";
-				target.lastSeenAt = Date.now();
-				saveJson(STATE_FILE, state);
-				ctx.ui.notify(`${subcommand === "pin" ? "已固定" : "已取消固定"}：${target.name} (${target.kind} · ${target.sourceLabel})`, "info");
-				return;
-			}
-
-			refreshState(pi, ctx, state);
-			const markdown = buildMarkdown(pi, ctx, state, subcommand === "search" ? query : trimmed);
-			await showMarkdownPanel(ctx, markdown);
-		},
-	});
-
-	pi.on("session_start", async (_event, ctx) => {
-		refreshState(pi, ctx, state);
-	});
-
-	pi.on("tool_result", async (event) => {
-		if (event.isError) {
-			return;
-		}
-
-		recordUsageByName(state, "tool", event.toolName);
-		syncMcpUsageFromResult(state, event as { toolName: string; input?: { server?: string } });
-		pruneState(state);
-		saveJson(STATE_FILE, state);
-	});
-
-	pi.on("session_shutdown", async () => {
-		pruneState(state);
-		saveJson(STATE_FILE, state);
-	});
+export default function (pi: ExtensionAPI): void {
+  registerHelpExtension(pi);
 }