pi-dynamic-help 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- Initial package extraction for the dynamic `/help` dashboard.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikumiiku
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# pi-dynamic-help
+
+Dynamic `/help` dashboard for [Pi](https://pi.dev). It summarizes loaded slash commands, tools, MCP servers, and installed Pi packages, then shows them in a concise TUI markdown panel.
+
+## Install
+
+Local development install:
+
+```bash
+pi install /absolute/path/to/pi-dynamic-help
+```
+
+Temporary test run without adding it to settings:
+
+```bash
+pi -e /absolute/path/to/pi-dynamic-help
+```
+
+NPM install:
+
+```bash
+pi install npm:pi-dynamic-help
+```
+
+After installing, run `/reload` or restart Pi if the command is not visible immediately.
+
+## Commands
+
+- `/help` — open the dynamic help dashboard.
+- `/help refresh` — refresh the resource index and usage counters.
+- `/help search <term>` — filter the dashboard by a term.
+- `/help pin <term>` — pin the best matching resource.
+- `/help unpin <term>` — unpin the best matching resource.
+
+## What it indexes
+
+- Slash commands registered by Pi, packages, prompt templates, and extensions.
+- Active tools exposed to the agent.
+- MCP gateway and configured MCP servers.
+- Packages listed in user and project Pi settings.
+
+The dashboard keeps command/tool/package/MCP sections separate so the resource type is clear.
+
+## State and migration
+
+Runtime metadata is stored under the user's Pi agent state directory:
+
+```text
+~/.pi/agent/state/pi-dynamic-help/state.json
+```
+
+The old local-extension state file, if present, is read as a migration source:
+
+```text
+~/.pi/agent/state/dynamic-help.json
+```
+
+The old file is not deleted. Migration preserves usage counts, pinned items, and timestamps where possible. The package normalizes source keys idempotently to avoid repeated `local:local:...` prefixes.
+
+Runtime state is not part of the npm package and should not be committed or published.
+
+## Privacy and safety
+
+This extension reads local Pi settings and MCP configuration files to build the dashboard. It does not upload this information. Like all Pi extensions, it runs locally with the permissions of your Pi process, so install only from sources you trust.
+
+## Development
+
+```bash
+npm install
+npm run check
+npm run test
+npm run pack:dry
+```
+
+Useful local smoke test:
+
+```bash
+TMP_AGENT_DIR=$(mktemp -d /tmp/pi-dynamic-help-agent-XXXXXX)
+PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi install /absolute/path/to/pi-dynamic-help
+PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi --no-session -p "/help"
+PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi --no-session -p "/help refresh"
+PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi --no-session -p "/help search mcp"
+PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi --no-session -p "/help pin bash"
+PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi --no-session -p "/help unpin bash"
+```
+
+## Troubleshooting
+
+- `/help` does not appear: run `/reload` or restart Pi.
+- State looks stale: run `/help refresh`.
+- A pin targets the wrong resource: use a more specific search term with `/help pin <term>` or undo it with `/help unpin <term>`.
+- Installed package is not shown: confirm it is listed in `~/.pi/agent/settings.json` or project `.pi/settings.json`, then run `/help refresh`.

package/extensions/help.ts

@@ -0,0 +1,845 @@
+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";
+
+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);
+	});
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "pi-dynamic-help",
+  "version": "0.1.0",
+  "description": "Dynamic /help dashboard for Pi commands, tools, MCP servers, and packages.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "help",
+    "extension"
+  ],
+  "license": "MIT",
+  "author": "Mikumiiku",
+  "files": [
+    "extensions",
+    "prompts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "vitest run",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/help.ts"
+    ],
+    "prompts": [
+      "./prompts/help-brief.md"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.78.0",
+    "@earendil-works/pi-tui": "^0.78.0",
+    "@types/node": "^24.12.4",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/prompts/help-brief.md

@@ -0,0 +1,15 @@
+---
+description: Brief fallback help for Pi
+---
+
+Give a concise overview of the current Pi setup.
+
+Prioritize:
+- the most relevant slash commands
+- core built-in tools that are likely useful right now
+- MCP servers and their usage patterns
+- installed packages that are likely useful right now
+- the shortest examples for asking for brainstorming, planning, implementation, review, and goal-driven work
+
+Use Chinese section headings with English aliases in parentheses only when helpful.
+Keep it short, direct, and organized under technical headings: Commands, Tools, MCP Servers, Packages.