pi-dynamic-help 0.1.0 → 0.2.1

package/src/state/migrate.ts

@@ -0,0 +1,80 @@
+import { STATE_VERSION } from "../constants.js";
+import { canonicalName, compactSourceRef, displayName, makeItemKey } from "../identity.js";
+import type { HelpState, IndexedItem, LegacyHelpState, ResourceKind, ResourceScope } from "../types.js";
+
+export function emptyState(): HelpState {
+  return { version: STATE_VERSION, items: {} };
+}
+
+export 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 fallbackSourceLabel(kind: ResourceKind, sourceRef: string, scope?: ResourceScope): string {
+  if (sourceRef === "builtin") return kind === "tool" ? "内置工具" : "内置";
+  if (sourceRef === "sdk") return kind === "tool" ? "SDK 工具" : "SDK";
+  if (sourceRef.startsWith("pkg:")) return `npm:${sourceRef.slice("pkg:".length)}`;
+  if (sourceRef.startsWith("npm:")) return sourceRef;
+  if (sourceRef.startsWith("mcp:")) return sourceRef === "mcp:gateway" ? "内置网关" : "MCP 服务器";
+  if (sourceRef.startsWith("local:")) return scope === "project" ? "项目本地" : "本地包";
+  return sourceRef;
+}
+
+export function mergeItem(existing: IndexedItem | undefined, next: IndexedItem): IndexedItem {
+  if (!existing) return next;
+
+  return {
+    ...existing,
+    ...next,
+    description: next.description ?? existing.description,
+    sourceLabel: next.sourceLabel || existing.sourceLabel,
+    sourceRef: next.sourceRef || existing.sourceRef,
+    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 normalizeRawItem(raw: Partial<IndexedItem> & { key?: string; kind?: ResourceKind; name?: string; source?: string }): IndexedItem | undefined {
+  if (!raw.kind || !raw.name) return undefined;
+
+  const sourceRef = compactSourceRef(raw.sourceRef ?? raw.source ?? legacySourceFromKey(raw.key) ?? raw.packageName ?? raw.sourceLabel);
+  const name = canonicalName(raw.kind, raw.name);
+  const key = makeItemKey(raw.kind, name, sourceRef);
+  return {
+    key,
+    kind: raw.kind,
+    name,
+    displayName: raw.displayName ?? displayName(raw.kind, name),
+    description: raw.description,
+    sourceLabel: raw.sourceLabel || fallbackSourceLabel(raw.kind, sourceRef, raw.scope),
+    sourceRef,
+    scope: raw.scope,
+    packageName: raw.packageName,
+    useCount: raw.useCount ?? 0,
+    lastUsedAt: raw.lastUsedAt,
+    lastSeenAt: raw.lastSeenAt,
+    pinned: raw.pinned,
+  };
+}
+
+export function migrateState(state: LegacyHelpState | HelpState): HelpState {
+  const items: Record<string, IndexedItem> = {};
+
+  for (const raw of Object.values(state.items ?? {})) {
+    const next = normalizeRawItem(raw);
+    if (!next) continue;
+    items[next.key] = mergeItem(items[next.key], next);
+  }
+
+  return {
+    version: STATE_VERSION,
+    items,
+    lastRefresh: state.lastRefresh,
+  };
+}

package/src/state/store.ts

@@ -0,0 +1,70 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { HelpState, LegacyHelpState, PersistResult } from "../types.js";
+import { emptyState, migrateState } from "./migrate.js";
+
+export interface StatePaths {
+  stateDir: string;
+  stateFile: string;
+  legacyStateFile: string;
+}
+
+export function createStatePaths(agentDir: string): StatePaths {
+  const stateDir = join(agentDir, "state", "pi-dynamic-help");
+  return {
+    stateDir,
+    stateFile: join(stateDir, "state.json"),
+    legacyStateFile: join(agentDir, "state", "dynamic-help.json"),
+  };
+}
+
+function parseJsonFile<T>(path: string): { ok: true; value: T } | { ok: false; error: unknown } | { ok: undefined } {
+  if (!existsSync(path)) return { ok: undefined };
+  try {
+    return { ok: true, value: JSON.parse(readFileSync(path, "utf-8")) as T };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+
+function timestamp(): string {
+  return new Date().toISOString().replace(/[-:]/g, "").replace(/\..*$/, "").replace("T", "-");
+}
+
+export function backupCorruptState(path: string): string | undefined {
+  if (!existsSync(path)) return undefined;
+  const backup = join(dirname(path), `state.corrupt-${timestamp()}.json`);
+  renameSync(path, backup);
+  return backup;
+}
+
+export function loadState(paths: StatePaths): { state: HelpState; warnings: string[] } {
+  const warnings: string[] = [];
+  const current = parseJsonFile<LegacyHelpState | HelpState>(paths.stateFile);
+  if (current.ok === true) return { state: migrateState(current.value), warnings };
+  if (current.ok === false) {
+    try {
+      const backup = backupCorruptState(paths.stateFile);
+      warnings.push(`状态文件损坏，已备份为 ${backup}`);
+    } catch (error) {
+      warnings.push(`状态文件损坏，且备份失败：${String(error)}`);
+    }
+  }
+
+  const legacy = parseJsonFile<LegacyHelpState>(paths.legacyStateFile);
+  if (legacy.ok === true) return { state: migrateState(legacy.value), warnings };
+  if (legacy.ok === false) warnings.push("旧状态文件无法解析，已忽略");
+  return { state: emptyState(), warnings };
+}
+
+export function saveState(paths: StatePaths, state: HelpState): PersistResult {
+  try {
+    mkdirSync(paths.stateDir, { recursive: true });
+    const tmp = `${paths.stateFile}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
+    renameSync(tmp, paths.stateFile);
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, warning: `帮助状态保存失败：${String(error)}` };
+  }
+}

package/src/state/usage.ts

@@ -0,0 +1,60 @@
+import { MAX_ITEMS } from "../constants.js";
+import { normalizeSearch } from "../identity.js";
+import type { HelpState, IndexedItem, ResourceKind } from "../types.js";
+import { mergeItem } from "./migrate.js";
+
+export 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.displayName ?? a.name).localeCompare(b.displayName ?? b.name);
+}
+
+export function upsertItem(state: HelpState, item: IndexedItem): IndexedItem {
+  const merged = mergeItem(state.items[item.key], item);
+  state.items[item.key] = merged;
+  return merged;
+}
+
+export function recordUsage(state: HelpState, key: string, now = Date.now()): void {
+  const item = state.items[key];
+  if (!item) return;
+  item.useCount = (item.useCount ?? 0) + 1;
+  item.lastUsedAt = now;
+  item.lastSeenAt = now;
+}
+
+export function recordUsageByName(state: HelpState, kind: ResourceKind, name: string, now = Date.now()): void {
+  const matches = Object.values(state.items).filter((item) => item.kind === kind && (item.name === name || item.displayName === name));
+  if (matches.length === 0) return;
+  const target = [...matches].sort(sortItems)[0];
+  if (!target) return;
+  recordUsage(state, target.key, now);
+}
+
+export function findMatches(state: HelpState, query: string): IndexedItem[] {
+  const normalizedQuery = normalizeSearch(query);
+  if (!normalizedQuery) return [];
+  return Object.values(state.items)
+    .filter((item) => normalizeSearch([item.name, item.displayName, item.description, item.sourceLabel, item.packageName, item.sourceRef, item.kind].join(" ")).includes(normalizedQuery))
+    .sort(sortItems);
+}
+
+export 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];
+  }
+}

package/src/types.ts

@@ -0,0 +1,56 @@
+export type ResourceKind = "command" | "tool" | "package" | "mcp";
+
+export type ResourceScope = "project" | "user" | "temporary" | "builtin";
+
+export interface IndexedItem {
+  key: string;
+  kind: ResourceKind;
+  name: string;
+  displayName?: string;
+  description?: string;
+  sourceLabel: string;
+  sourceRef: string;
+  scope?: ResourceScope;
+  packageName?: string;
+  useCount: number;
+  lastUsedAt?: number;
+  lastSeenAt?: number;
+  pinned?: boolean;
+}
+
+export interface HelpState {
+  version: 3;
+  items: Record<string, IndexedItem>;
+  lastRefresh?: number;
+}
+
+export interface LegacyHelpState {
+  version?: number;
+  items?: Record<string, Partial<IndexedItem> & { key?: string; kind?: ResourceKind; name?: string; source?: string; origin?: string }>;
+  lastRefresh?: number;
+}
+
+export interface McpServerEntry {
+  name: string;
+  mode: string;
+  lifecycle?: string;
+  command?: string;
+  url?: string;
+}
+
+export interface PackageEntry {
+  name: string;
+  scope: ResourceScope;
+}
+
+export interface ResourceIndex {
+  commands: IndexedItem[];
+  tools: IndexedItem[];
+  mcp: IndexedItem[];
+  packages: IndexedItem[];
+}
+
+export interface PersistResult {
+  ok: boolean;
+  warning?: string;
+}