pi-dynamic-help 0.1.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-dynamic-help",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Dynamic /help dashboard for Pi commands, tools, MCP servers, and packages.",
   "type": "module",
   "keywords": [
@@ -13,6 +13,7 @@
   "author": "Mikumiiku",
   "files": [
     "extensions",
+    "src",
     "prompts",
     "README.md",
     "CHANGELOG.md",
@@ -32,8 +33,8 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-coding-agent": ">=0.78.0 <1",
+    "@earendil-works/pi-tui": ">=0.78.0 <1"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.78.0",

package/src/constants.ts

@@ -0,0 +1,26 @@
+export const PACKAGE_NAME = "pi-dynamic-help";
+export const STATE_VERSION = 3;
+export const MAX_ITEMS = 250;
+export const MAX_COMMON = 8;
+export const MAX_SECTION = 16;
+
+export 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" },
+];

package/src/extension.ts

@@ -0,0 +1,154 @@
+import { homedir } from "node:os";
+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 { buildResourceIndex, readRuntimeMcpServers, readRuntimePackages } from "./resources/index.js";
+import { buildMarkdown } from "./render/markdown.js";
+import { createStatePaths, loadState, saveState } from "./state/store.js";
+import { findMatches, pruneState, recordUsageByName } from "./state/usage.js";
+import type { HelpState, ResourceIndex } from "./types.js";
+
+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 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 notifySaveWarning(ctx: ExtensionContext, warning: string | undefined): void {
+  if (warning) ctx.ui.notify(warning, "warning");
+}
+
+export function registerHelpExtension(pi: ExtensionAPI): void {
+  const paths = createStatePaths(getAgentDir());
+  const loaded = loadState(paths);
+  const state = loaded.state;
+
+  function rebuildIndex(ctx: ExtensionContext): ResourceIndex {
+    syncSessionUsage(ctx, state);
+    const index = buildResourceIndex({
+      commands: pi.getCommands(),
+      tools: pi.getAllTools(),
+      packages: readRuntimePackages(getAgentDir(), ctx.cwd),
+      mcpServers: readRuntimeMcpServers(getAgentDir(), homedir(), ctx.cwd),
+      state,
+    });
+    pruneState(state);
+    return index;
+  }
+
+  function persist(ctx: ExtensionContext): void {
+    const result = saveState(paths, state);
+    notifySaveWarning(ctx, result.warning);
+  }
+
+  pi.registerCommand("help", {
+    description: "Show a dynamic help dashboard for installed Pi resources",
+    handler: async (args, ctx) => {
+      for (const warning of loaded.warnings) ctx.ui.notify(warning, "warning");
+      loaded.warnings.length = 0;
+
+      const trimmed = args.trim();
+      const [subcommand, ...rest] = trimmed.length > 0 ? trimmed.split(/\s+/) : [""];
+      const query = rest.join(" ").trim();
+
+      if (subcommand === "refresh") {
+        rebuildIndex(ctx);
+        persist(ctx);
+        ctx.ui.notify("帮助索引已刷新", "info");
+        return;
+      }
+
+      if (subcommand === "pin" || subcommand === "unpin") {
+        rebuildIndex(ctx);
+        const matches = findMatches(state, query);
+        if (matches.length === 0) {
+          ctx.ui.notify(`未找到：${query || "<空>"}`, "warning");
+          persist(ctx);
+          return;
+        }
+
+        const target = matches[0];
+        target.pinned = subcommand === "pin";
+        target.lastSeenAt = Date.now();
+        persist(ctx);
+        ctx.ui.notify(`${subcommand === "pin" ? "已固定" : "已取消固定"}：${target.displayName ?? target.name} (${target.kind} · ${target.sourceLabel})`, "info");
+        return;
+      }
+
+      const index = rebuildIndex(ctx);
+      persist(ctx);
+      const markdown = buildMarkdown(index, state.lastRefresh, subcommand === "search" ? query : trimmed);
+      await showMarkdownPanel(ctx, markdown);
+    },
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    rebuildIndex(ctx);
+    persist(ctx);
+  });
+
+  pi.on("tool_result", async (event, ctx) => {
+    if (event.isError) return;
+    recordUsageByName(state, "tool", event.toolName);
+    if (event.toolName === "mcp") {
+      recordUsageByName(state, "mcp", "mcp");
+      const maybeInput = event as { input?: { server?: string } };
+      if (maybeInput.input?.server) recordUsageByName(state, "mcp", maybeInput.input.server);
+    }
+    pruneState(state);
+    persist(ctx);
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    pruneState(state);
+    persist(ctx);
+  });
+}

package/src/identity.ts

@@ -0,0 +1,92 @@
+import { homedir } from "node:os";
+import { basename, isAbsolute, relative } from "node:path";
+import { PACKAGE_NAME } from "./constants.js";
+import type { ResourceKind } from "./types.js";
+
+const COMPACT_PREFIXES = ["local:", "project:", "pkg:", "mcp:", "npm:", "git:", "http://", "https://"];
+
+export function normalizeSearch(value: string | undefined): string {
+  return (value ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9\u4e00-\u9fff]+/g, " ")
+    .trim();
+}
+
+export function normalizeCommandName(name: string): string {
+  return name.replace(/^\/+/, "");
+}
+
+export function displayCommandName(name: string): string {
+  return `/${normalizeCommandName(name)}`;
+}
+
+export function canonicalName(kind: ResourceKind, name: string): string {
+  return kind === "command" ? normalizeCommandName(name) : name;
+}
+
+export function displayName(kind: ResourceKind, name: string): string {
+  return kind === "command" ? displayCommandName(name) : name;
+}
+
+export 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;
+}
+
+function isOwnPackageSource(source: string): boolean {
+  return source.replace(/\\/g, "/").includes(PACKAGE_NAME);
+}
+
+export function compactSourceRef(source?: string): string {
+  if (!source) return "unknown";
+
+  const normalized = unwrapLocalWrappedCompactRef(stripRepeatedLocalPrefixes(source.replace(/\\/g, "/")));
+  if (isOwnPackageSource(normalized)) return `pkg:${PACKAGE_NAME}`;
+  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 makeItemKey(kind: ResourceKind, name: string, sourceRef: string): string {
+  return `${kind}:${sourceRef}:${canonicalName(kind, name)}`;
+}

package/src/render/markdown.ts

@@ -0,0 +1,97 @@
+import { MAX_COMMON, MAX_SECTION } from "../constants.js";
+import { normalizeSearch } from "../identity.js";
+import { sortItems } from "../state/usage.js";
+import type { IndexedItem, ResourceIndex } from "../types.js";
+
+export function escapeMarkdownInline(value: string | undefined): string {
+  return (value ?? "").replace(/([\\`*_{}\[\]()#+\-.!|>])/g, "\\$1");
+}
+
+function itemTitle(item: IndexedItem): string {
+  return escapeMarkdownInline(item.displayName ?? item.name);
+}
+
+function formatItem(item: IndexedItem): string {
+  const meta = item.sourceLabel ? [escapeMarkdownInline(item.sourceLabel)] : [];
+  if (item.scope && item.scope !== "builtin") meta.push(escapeMarkdownInline(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 ? ` — ${escapeMarkdownInline(item.description)}` : "";
+  return `- **${itemTitle(item)}**${desc}${suffix}`;
+}
+
+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 filterIndex(index: ResourceIndex, query?: string): IndexedItem[] {
+  const normalizedQuery = normalizeSearch(query);
+  return [...index.commands, ...index.tools, ...index.mcp, ...index.packages].filter((item) => {
+    if (!normalizedQuery) return true;
+    return normalizeSearch([item.name, item.displayName, item.description, item.sourceLabel, item.packageName, item.sourceRef, item.kind].join(" ")).includes(normalizedQuery);
+  });
+}
+
+export function buildMarkdown(index: ResourceIndex, updatedAt: number | undefined, query?: string): string {
+  const normalizedQuery = normalizeSearch(query);
+  const allVisible = filterIndex(index, query);
+
+  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 updated = updatedAt ? new Date(updatedAt).toLocaleString() : new Date().toLocaleString();
+  const title = normalizedQuery ? `动态帮助 · 搜索：${escapeMarkdownInline(query?.trim())}` : "动态帮助";
+
+  return [
+    `# ${title}`,
+    `_更新时间：${updated}_`,
+    "",
+    `> 已加载：${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") : "- 暂无",
+    "",
+    "### 服务器",
+    serverItems.length > 0 ? serverItems.map(formatItem).join("\n") : "- 暂无",
+    "",
+    "## 包",
+    packageItems.length > 0 ? packageItems.map(formatItem).join("\n") : "- 暂无",
+    "",
+    "## 操作",
+    "- `/help search <词>` 搜索当前索引",
+    "- `/help pin <词>` 固定匹配项",
+    "- `/help unpin <词>` 取消固定",
+    "- `/help refresh` 重新扫描并刷新使用统计",
+  ].join("\n");
+}

package/src/resources/index.ts

@@ -0,0 +1,201 @@
+import { join } from "node:path";
+import { BUILTIN_COMMANDS } from "../constants.js";
+import { canonicalName, compactSourceRef, displayName, extractPackageNameFromPath, makeItemKey } from "../identity.js";
+import type { HelpState, IndexedItem, McpServerEntry, PackageEntry, ResourceIndex, ResourceScope } from "../types.js";
+import { upsertItem } from "../state/usage.js";
+import { mergePackageEntries, readPackagesFromSettings } from "./settings.js";
+import { readMcpServersFromConfig } from "./mcp.js";
+
+export interface CommandLike {
+  name: string;
+  description?: string;
+  sourceInfo: { source?: string; scope?: ResourceScope; origin?: string };
+}
+
+export interface ToolLike {
+  name: string;
+  description?: string;
+  sourceInfo: { source?: string; scope?: ResourceScope; origin?: string };
+}
+
+export interface ResourceRuntimeInput {
+  commands: CommandLike[];
+  tools: ToolLike[];
+  packages: PackageEntry[];
+  mcpServers: McpServerEntry[];
+  state: HelpState;
+  now?: number;
+}
+
+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("../") || pkg.startsWith("/")) return "本地包";
+  return `npm:${pkg}`;
+}
+
+function packageLabelFromSource(source: string): string {
+  const pkg = extractPackageNameFromPath(source) ?? (source.startsWith("npm:") ? source.slice("npm:".length) : undefined);
+  return pkg ? `npm:${pkg}` : sourceLabelForPackage(source);
+}
+
+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") return packageLabelFromSource(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 (source.startsWith("./") || source.startsWith("../")) return sourceInfo.scope === "project" ? "项目本地" : "本地包";
+  if (source.startsWith("/")) {
+    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") return packageLabelFromSource(source);
+  if (source.startsWith("npm:") || source.startsWith("git:") || source.startsWith("http://") || source.startsWith("https://")) return source;
+  if (source.startsWith("/")) {
+    const pkg = extractPackageNameFromPath(source);
+    if (pkg) return `npm:${pkg}`;
+    return sourceInfo.scope === "project" ? "项目扩展" : "全局扩展";
+  }
+  return source;
+}
+
+function sourceLabelForMcp(server: McpServerEntry): string {
+  const bits = [server.mode === "http" ? "HTTP" : "stdio"];
+  if (server.lifecycle) bits.push(server.lifecycle);
+  return bits.join(" · ");
+}
+
+function itemBase(kind: IndexedItem["kind"], name: string, sourceRef: string): Pick<IndexedItem, "key" | "kind" | "name" | "displayName" | "sourceRef" | "useCount"> {
+  const canonical = canonicalName(kind, name);
+  return {
+    key: makeItemKey(kind, canonical, sourceRef),
+    kind,
+    name: canonical,
+    displayName: displayName(kind, canonical),
+    sourceRef,
+    useCount: 0,
+  };
+}
+
+export function buildResourceIndex(input: ResourceRuntimeInput): ResourceIndex {
+  const { commands, tools, state } = input;
+  const packages = mergePackageEntries(input.packages);
+  const now = input.now ?? Date.now();
+
+  const mergedMcp = new Map<string, McpServerEntry>();
+  for (const server of input.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 base = itemBase("command", command.name, sourceRef);
+    commandItems.push(upsertItem(state, {
+      ...base,
+      description: command.description,
+      sourceLabel: sourceLabelForCommand(command.sourceInfo),
+      scope: command.sourceInfo.scope,
+      packageName: command.sourceInfo.source,
+      lastSeenAt: now,
+    }));
+  }
+
+  for (const builtin of BUILTIN_COMMANDS) {
+    const sourceRef = "builtin";
+    const base = itemBase("command", builtin.name, sourceRef);
+    commandItems.push(upsertItem(state, {
+      ...base,
+      description: builtin.description,
+      sourceLabel: "内置",
+      scope: "builtin",
+      lastSeenAt: now,
+    }));
+  }
+
+  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 base = itemBase("tool", tool.name, sourceRef);
+    toolItems.push(upsertItem(state, {
+      ...base,
+      description: tool.description,
+      sourceLabel: sourceLabelForTool(tool.sourceInfo),
+      scope: tool.sourceInfo.scope,
+      packageName: tool.sourceInfo.source,
+      lastSeenAt: now,
+    }));
+  }
+
+  const packageItems: IndexedItem[] = [];
+  for (const pkg of packages) {
+    const sourceRef = compactSourceRef(pkg.name);
+    const base = itemBase("package", pkg.name, sourceRef);
+    packageItems.push(upsertItem(state, {
+      ...base,
+      description: "已安装包",
+      sourceLabel: sourceLabelForPackage(pkg.name),
+      scope: pkg.scope,
+      packageName: pkg.name,
+      lastSeenAt: now,
+    }));
+  }
+
+  const mcpItems: IndexedItem[] = [];
+  const gatewayBase = itemBase("mcp", "mcp", "mcp:gateway");
+  mcpItems.push(upsertItem(state, {
+    ...gatewayBase,
+    description: "显示 MCP 服务器状态",
+    sourceLabel: "内置网关",
+    scope: "builtin",
+    lastSeenAt: now,
+  }));
+
+  for (const server of mergedMcp.values()) {
+    const sourceRef = `mcp:${server.name}`;
+    const base = itemBase("mcp", server.name, sourceRef);
+    mcpItems.push(upsertItem(state, {
+      ...base,
+      description: server.url ? server.url : server.command ? server.command : "MCP 服务器",
+      sourceLabel: sourceLabelForMcp(server),
+      scope: "user",
+      packageName: server.command ?? server.url,
+      lastSeenAt: now,
+    }));
+  }
+
+  state.lastRefresh = now;
+  return { commands: commandItems, tools: toolItems, mcp: mcpItems, packages: packageItems };
+}
+
+export function readRuntimePackages(agentDir: string, cwd: string): PackageEntry[] {
+  return [
+    ...readPackagesFromSettings(join(agentDir, "settings.json"), "user"),
+    ...readPackagesFromSettings(join(cwd, ".pi", "settings.json"), "project"),
+  ];
+}
+
+export function readRuntimeMcpServers(agentDir: string, homeDir: string, cwd: string): McpServerEntry[] {
+  return [
+    ...readMcpServersFromConfig(join(homeDir, ".config", "mcp", "mcp.json")),
+    ...readMcpServersFromConfig(join(agentDir, "mcp.json")),
+    ...readMcpServersFromConfig(join(cwd, ".mcp.json")),
+    ...readMcpServersFromConfig(join(cwd, ".pi", "mcp.json")),
+  ];
+}

package/src/resources/mcp.ts

@@ -0,0 +1,31 @@
+import { existsSync, readFileSync } from "node:fs";
+import type { McpServerEntry } from "../types.js";
+
+function loadJson(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+export function readMcpServersFromConfig(path: string): McpServerEntry[] {
+  const config = loadJson(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;
+}

package/src/resources/settings.ts

@@ -0,0 +1,45 @@
+import { existsSync, readFileSync } from "node:fs";
+import type { PackageEntry, ResourceScope } from "../types.js";
+
+function loadJson(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+export function readPackagesFromSettings(path: string, scope: ResourceScope): PackageEntry[] {
+  const settings = loadJson(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;
+}
+
+export 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()];
+}