personal-bot 0.2.2 → 0.2.4

package/src/integrations/pi/history.ts

@@ -0,0 +1,107 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parseSessionEntries, SessionManager, type ExtensionContext, type SessionEntry, type SessionMessageEntry } from "@earendil-works/pi-coding-agent";
+import type { HistoryExchange, HistoryLocation, HistorySession, HistorySource, HistorySummarizer } from "../../model/history.js";
+import { requireThat } from "../../common/validation.js";
+import { resourceRoot } from "../../common/paths.js";
+
+function text(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.flatMap(block => block.type === "text" ? [String(block.text)] : block.type === "image" ? ["[图片]"] : []).join("\n");
+}
+function exchanges(branch: SessionEntry[]): HistoryExchange[] {
+  const result: HistoryExchange[] = [];
+  let users: SessionMessageEntry[] = [], partial: SessionMessageEntry | undefined;
+  const finish = (answer?: SessionMessageEntry, completed = false) => {
+    if (!users.length) return;
+    const entries = [...users, ...(answer ? [answer] : [])];
+    result.push({ entryIds: entries.map(entry => entry.id), from: users[0]!.timestamp, to: entries.at(-1)!.timestamp, completed,
+      text: users.map(entry => "用户：\n" + text("content" in entry.message ? entry.message.content : "")).join("\n\n") +
+        (answer && "content" in answer.message ? "\n\n助手：\n" + text(answer.message.content) : "") });
+    users = []; partial = undefined;
+  };
+  for (const entry of branch) {
+    if (entry.type !== "message") continue;
+    const message = entry.message;
+    if (message.role === "user") {
+      if (partial?.message.role === "assistant" && ["aborted", "error"].includes(partial.message.stopReason)) finish(partial);
+      users.push(entry);
+    } else if (message.role === "assistant" && users.length) {
+      partial = entry;
+      if (message.stopReason === "stop" && !message.content.some(block => block.type === "toolCall")) finish(entry, true);
+    }
+  }
+  finish(partial);
+  return result;
+}
+
+/** Parse in memory; never open a writable SessionManager or migrate native JSONL. */
+export function projectHistory(content: string): HistorySession {
+  const parsed = parseSessionEntries(content), header = parsed[0];
+  requireThat(header?.type === "session", "缺少 Pi 会话头。");
+  const manager = SessionManager.inMemory(header.cwd, undefined, parsed), entries = manager.getEntries();
+  const parents = new Set(entries.map(entry => entry.parentId));
+  const tips = entries.filter(entry => !parents.has(entry.id));
+  return { sessionId: header.id, name: manager.getSessionName() ?? "", branches: tips.map(tip => exchanges(manager.getBranch(tip.id))).filter(branch => branch.length) };
+}
+
+export const historyLocation = (ctx: ExtensionContext): HistoryLocation => {
+  const file = ctx.sessionManager.getSessionFile();
+  return { directory: ctx.sessionManager.getSessionDir(), ...(file ? { file } : {}) };
+};
+export class PiHistory implements HistorySource {
+  constructor(private readonly root: string, private readonly relatedFiles: () => string[] = () => []) {}
+  async scan(location: HistoryLocation, signal?: AbortSignal) {
+    const lists = await Promise.all([SessionManager.list(this.root, undefined, undefined, signal),
+      SessionManager.list(this.root, location.directory, undefined, signal)]);
+    const files = new Set([...lists.flat().map(session => session.path), ...this.relatedFiles(), ...(location.file ? [location.file] : [])]);
+    const sessions: HistorySession[] = [], warnings: string[] = [];
+    for (const file of files) {
+      signal?.throwIfAborted();
+      try {
+        const session = projectHistory(await readFile(file, { encoding: "utf8", signal }));
+        if (session.branches.length) {
+          session.name ||= session.branches[0]![0]!.text.replace(/\s+/g, " ").slice(0, 80);
+          sessions.push(session);
+        }
+      } catch (error) {
+        signal?.throwIfAborted();
+        // Pi reserves a filename before the first message; copied archives may also outlive their native files.
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") warnings.push(`${file}: ${String(error)}`);
+      }
+    }
+    return { sessions, warnings };
+  }
+}
+
+export async function historySummarizer(ctx: ExtensionContext): Promise<HistorySummarizer> {
+  const model = ctx.model;
+  requireThat(model, "请先选择 Pi 模型。");
+  const systemPrompt = await readFile(join(resourceRoot, "prompts/history-summary.md"), "utf8");
+  const budget = Math.max(2000, Math.min(24000, Math.floor(model.contextWindow / 2)));
+  const ask = async (content: string, signal: AbortSignal) => {
+    signal.throwIfAborted();
+    const response = await ctx.modelRegistry.streamSimple(model, { systemPrompt,
+      messages: [{ role: "user", content, timestamp: Date.now() }] }, { signal, reasoning: "low", maxTokens: 2048, transport: "sse" }).result();
+    signal.throwIfAborted();
+    requireThat(response.stopReason === "stop", response.errorMessage ?? "历史摘要未完成：" + response.stopReason);
+    const answer = response.content.filter(part => part.type === "text").map(part => part.text).join("\n").trim();
+    requireThat(answer, "历史摘要为空。");
+    return answer;
+  };
+  return async (text, signal) => {
+    while (text.length > budget) {
+      const parts: string[] = [];
+      for (let offset = 0; offset < text.length;) {
+        let end = Math.min(text.length, offset + budget);
+        if (end < text.length && /[\uD800-\uDBFF]/.test(text[end - 1]!)) end--;
+        parts.push(await ask(text.slice(offset, end), signal)); offset = end;
+      }
+      const smaller = parts.join("\n\n");
+      requireThat(smaller.length < text.length, "历史摘要未缩短，稍后重试。");
+      text = smaller;
+    }
+    return ask(text, signal);
+  };
+}

package/src/model/history.ts

@@ -0,0 +1,31 @@
+export interface HistoryExchange {
+  entryIds: string[];
+  text: string;
+  from: string;
+  to: string;
+  completed: boolean;
+}
+export interface HistorySession {
+  sessionId: string;
+  name: string;
+  branches: HistoryExchange[][];
+}
+export interface HistoryNode extends HistoryExchange {
+  id: string;
+  kind: "session" | "exchange" | "summary";
+  level: number;
+  children: string[];
+  parents: string[];
+  ready: boolean;
+}
+export interface HistoryRecord {
+  id: string;
+  sessionId: string;
+  name: string;
+  nodes: HistoryNode[];
+}
+export interface HistoryLocation { directory: string; file?: string }
+export interface HistorySource {
+  scan(location: HistoryLocation, signal?: AbortSignal): Promise<{ sessions: HistorySession[]; warnings: string[] }>;
+}
+export type HistorySummarizer = (text: string, signal: AbortSignal) => Promise<string>;

package/src/pbot.ts

@@ -9,6 +9,13 @@ import { Lifecycle, WorkspaceInstance } from "./extension/lifecycle.js";
 import { registerCommand } from "./extension/command.js";
 import { registerEvents } from "./extension/events.js";
 import { registerAgentEvents } from "./extension/agent-events.js";
+import { HistoryService } from "./services/history/history-service.js";
+import { HistoryFiles } from "./storage/history-files.js";
+import { PiHistory } from "./integrations/pi/history.js";
+import { sessionRef } from "./storage/agent-files.js";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import { registerHistoryEvents } from "./extension/history.js";
 
 export default function pbot(pi: ExtensionAPI) {
   // The explicitly loaded child entry owns the child; normal discovery never grants main privileges.
@@ -16,9 +23,15 @@ export default function pbot(pi: ExtensionAPI) {
   const confirmations = new Confirmations(), registry = new ToolRegistry(pi);
   const lifecycle = new Lifecycle(root => {
     const agents = new AgentService(root, agentDirectory(), new PiAgents());
-    return new WorkspaceInstance(root, new PythonEnvironmentService(root), agents, new TeamService(root, agents.files, agents.teamFiles));
-  }, instance => registry.register(mainTools(instance.agents, instance.teams, instance)), () => registry.hide());
+    const history = new HistoryService(root, new HistoryFiles(join(root, ".pi/pbot/history")), new PiHistory(root, () =>
+      agents.files.list().filter(agent => agent.workspace === root).flatMap(agent => {
+        const file = agents.files.optional(agent.agentId, "session-ref.json", sessionRef)?.file;
+        return file ? [file] : [];
+      })), new HistoryFiles(join(getAgentDir(), "pbot/history")));
+    return new WorkspaceInstance(root, new PythonEnvironmentService(root), agents, new TeamService(root, agents.files, agents.teamFiles), history);
+  }, instance => registry.register(mainTools(instance.agents, instance.teams, instance.history, instance)), () => registry.hide());
   registerCommand(pi, lifecycle, confirmations);
   registerEvents(pi, lifecycle, confirmations);
   registerAgentEvents(pi, lifecycle, confirmations);
+  registerHistoryEvents(pi, lifecycle);
 }

package/src/services/history/history-service.ts

@@ -0,0 +1,145 @@
+import { randomUUID } from "node:crypto";
+import type { HistoryExchange, HistoryLocation, HistoryNode, HistoryRecord, HistorySession, HistorySource, HistorySummarizer } from "../../model/history.js";
+import type { HistoryFiles } from "../../storage/history-files.js";
+import { requireThat } from "../../common/validation.js";
+
+/** Shared prefixes reuse nodes; only consecutive exchanges on one native branch can merge. */
+export function indexHistory(session: HistorySession, previous?: HistoryRecord): HistoryRecord {
+  const id = previous?.id ?? randomUUID(), nodes = new Map<string, HistoryNode>();
+  const old = new Map(previous?.nodes.map(node => [node.id, node])), changed = new Set<string>();
+  const add = (value: HistoryExchange, level: number, children: string[] = []): HistoryNode => {
+    const key = `${id}:${level}:${value.entryIds.at(-1)}`, found = nodes.get(key);
+    if (found) return found;
+    const before = old.get(key), same = before && JSON.stringify(before.children) === JSON.stringify(children) &&
+      (level ? children.every(child => !changed.has(child)) : before.text === value.text && before.completed === value.completed);
+    const node: HistoryNode = { ...value, id: key, kind: level ? "summary" : "exchange", level, children, parents: [],
+      text: level ? same ? before.text : "" : value.text, ready: level ? Boolean(same && before.ready) : true };
+    if (!same) changed.add(key);
+    nodes.set(key, node); return node;
+  };
+  const roots = new Set<string>();
+  for (const branch of session.branches) {
+    let layer = branch.map(exchange => add(exchange, 0)), level = 1;
+    while (layer.length >= 4) {
+      const count = Math.floor(layer.length / 4) * 4, next: HistoryNode[] = [];
+      layer.slice(count).forEach(node => roots.add(node.id));
+      for (let i = 0; i < count; i += 4) {
+        const children = layer.slice(i, i + 4), first = children[0]!, last = children.at(-1)!;
+        next.push(add({ entryIds: [first.entryIds[0]!, last.entryIds.at(-1)!], text: "", from: first.from, to: last.to,
+          completed: children.every(node => node.completed) }, level, children.map(node => node.id)));
+      }
+      layer = next; level++;
+    }
+    layer.forEach(node => roots.add(node.id));
+  }
+  const dates = [...nodes.values()].flatMap(node => [node.from, node.to]).sort();
+  nodes.set(id, { id, kind: "session", level: -1, entryIds: [], text: session.name, ready: true, completed: [...nodes.values()].every(node => node.completed),
+    from: dates[0] ?? "", to: dates.at(-1) ?? "", parents: [],
+    children: [...roots].sort((a, b) => nodes.get(a)!.from.localeCompare(nodes.get(b)!.from)) });
+  for (const node of nodes.values()) for (const child of node.children) nodes.get(child)!.parents.push(node.id);
+  return { id, sessionId: session.sessionId, name: session.name, nodes: [...nodes.values()] };
+}
+
+export interface HistoryQuery { query?: string; sessionId?: string; from?: string; to?: string; offset?: number; limit?: number }
+const page = <T>(values: T[], offset: number, limit: number) => ({ values: values.slice(offset, offset + limit),
+  nextOffset: offset + limit < values.length ? offset + limit : null });
+const brief = (record: HistoryRecord, node: HistoryNode) => ({ id: node.id, kind: node.kind, sessionId: record.sessionId,
+  name: record.name, preview: node.text.replace(/\s+/g, " ").slice(0, 100), from: node.from, to: node.to, ready: node.ready, completed: node.completed });
+
+export class HistoryService {
+  #records: HistoryRecord[] = [];
+  #closed = false;
+  #refresh: Promise<void> | undefined;
+  #work: Promise<void> | undefined;
+  warnings: string[] = [];
+  constructor(readonly root: string, private readonly files: HistoryFiles, private readonly source: HistorySource,
+    private previousFiles?: HistoryFiles) {}
+  check() { requireThat(!this.#closed, "历史服务已关闭。"); }
+  refresh(location: HistoryLocation, signal?: AbortSignal): Promise<void> {
+    this.check();
+    if (this.#refresh) return this.#refresh;
+    this.#refresh = this.load(location, signal).finally(() => { this.#refresh = undefined; });
+    return this.#refresh;
+  }
+  private async load(location: HistoryLocation, signal?: AbortSignal) {
+    const previous = this.files.list();
+    for (const value of previous) if ("file" in value) {
+      const { id, sessionId, name, nodes } = value;
+      this.files.save({ id, sessionId, name, nodes });
+    }
+    for (const { id, sessionId, name, nodes } of this.previousFiles?.list(this.root) ?? []) {
+      if (previous.some(record => record.sessionId === sessionId)) continue;
+      const value = { id, sessionId, name, nodes };
+      this.files.save(value); previous.push(value);
+    }
+    this.previousFiles = undefined;
+    const { sessions, warnings } = await this.source.scan(location, signal);
+    this.check(); signal?.throwIfAborted();
+    const known = new Map(this.files.list().map(record => [record.sessionId, record]));
+    for (const session of sessions) {
+      const before = known.get(session.sessionId), value = indexHistory(session, before);
+      if (JSON.stringify(before) !== JSON.stringify(value)) this.files.save(value);
+      known.set(session.sessionId, value);
+    }
+    this.#records = [...known.values()];
+    this.warnings = warnings;
+  }
+  search({ query = "", sessionId, from, to, offset = 0, limit = 20 }: HistoryQuery = {}) {
+    this.check();
+    const needle = query.trim().toLowerCase(), after = from === undefined ? -Infinity : Date.parse(from), before = to === undefined ? Infinity : Date.parse(to);
+    requireThat(!Number.isNaN(after) && !Number.isNaN(before) && after <= before, "时间范围无效，请使用 ISO 日期或时间。");
+    const matches = this.#records.filter(record => !sessionId || record.sessionId === sessionId).flatMap(record => record.nodes
+      .filter(node => (needle ? node.kind !== "session" && node.ready && node.text.toLowerCase().includes(needle) : node.kind === "session") &&
+        Date.parse(node.to) >= after && Date.parse(node.from) <= before)
+      .map(node => {
+        const start = Math.max(0, node.text.toLowerCase().indexOf(needle) - 80);
+        return { ...brief(record, node), parents: node.parents, snippet: node.text.slice(start, start + 400) };
+      })).sort((a, b) => b.to.localeCompare(a.to) || a.id.localeCompare(b.id));
+    const result = page(matches, offset, limit);
+    return { matches: result.values, total: matches.length, nextOffset: result.nextOffset, warnings: this.warnings };
+  }
+  private find(id: string) {
+    const record = this.#records.find(record => record.nodes.some(node => node.id === id));
+    const node = record?.nodes.find(node => node.id === id);
+    requireThat(record && node, "历史节点不存在，请重新搜索。");
+    return { record, node };
+  }
+  read(id: string, offset = 0, limit = 12000, childrenOffset = 0) {
+    this.check();
+    const { record, node } = this.find(id), lookup = new Map(record.nodes.map(value => [value.id, value]));
+    requireThat(offset <= node.text.length, "读取位置超出正文。");
+    if (offset && /[\uDC00-\uDFFF]/.test(node.text[offset] ?? "")) offset--;
+    let end = Math.min(node.text.length, offset + limit);
+    if (end < node.text.length && /[\uD800-\uDBFF]/.test(node.text[end - 1] ?? "")) end += end - offset === 1 ? 1 : -1;
+    const children = page(node.children, childrenOffset, 20);
+    return { ...brief(record, node), text: node.text.slice(offset, end), totalLength: node.text.length,
+      nextOffset: end < node.text.length ? end : null,
+      parents: node.parents.map(id => brief(record, lookup.get(id)!)), children: children.values.map(id => brief(record, lookup.get(id)!)),
+      nextChildrenOffset: children.nextOffset, source: { sessionId: record.sessionId, entryIds: node.entryIds }, warnings: this.warnings };
+  }
+  /** One worker per workspace instance. Failed or cancelled nodes remain pending for the next idle period. */
+  organize(summarize: HistorySummarizer, signal: AbortSignal): Promise<void> {
+    this.check();
+    const run = async () => {
+      for (const record of this.#records) {
+        const lookup = new Map(record.nodes.map(node => [node.id, node]));
+        for (const node of [...record.nodes].sort((a, b) => a.level - b.level)) {
+          this.check(); signal.throwIfAborted();
+          if (node.kind !== "summary" || node.ready) continue;
+          const children = node.children.map(id => lookup.get(id)!);
+          if (children.some(child => !child.ready)) continue;
+          const text = await summarize(children.map(child => `[${child.from} — ${child.to}${child.completed ? "" : "；未完成"}]\n${child.text}`).join("\n\n"), signal);
+          this.check(); signal.throwIfAborted();
+          // A query may have refreshed the source while this model request was running.
+          if (!this.#records.includes(record)) return;
+          requireThat(text.trim(), "历史摘要为空。");
+          node.text = text.trim(); node.ready = true; this.files.save(record);
+        }
+      }
+    };
+    const work = (this.#work ?? Promise.resolve()).catch(() => {}).then(run);
+    this.#work = work;
+    return work.finally(() => { if (this.#work === work) this.#work = undefined; });
+  }
+  async close() { this.#closed = true; await Promise.allSettled([this.#work, this.#refresh]); }
+}

package/src/services/installation/setup-service.ts

@@ -0,0 +1,145 @@
+import { npmName, ordinaryNpm } from "../../common/package-source.js";
+
+export interface PluginSpec {
+  id: string;
+  label: string;
+  description: string;
+  source: string;
+  defaultSelected: boolean;
+}
+export interface InstalledPackage {
+  source: string;
+  scope: "user" | "project";
+  name?: string;
+  version?: string;
+  installedPath?: string;
+  filtered: boolean;
+  entry: unknown;
+}
+export interface PackageChoice {
+  plugin: PluginSpec;
+  required: boolean;
+  existing: InstalledPackage[];
+  selected: boolean;
+  keep: boolean;
+  target?: string;
+  error?: string;
+}
+export interface PiInstallation { command: string; root: string; version: string }
+export interface SystemCommand { command: string; args: string[] }
+export interface SetupPlan {
+  workspace: string;
+  pi?: PiInstallation;
+  piVersion: string;
+  tmux?: SystemCommand;
+  packages: PackageChoice[];
+}
+export interface SetupResult { name: string; state: "done" | "kept" | "skipped" | "failed"; detail: string }
+export interface SetupOperations {
+  installTmux(command: SystemCommand): Promise<void>;
+  ensurePi(existing: PiInstallation | undefined, version: string): Promise<PiInstallation>;
+  installPackage(pi: PiInstallation, workspace: string, choice: PackageChoice): Promise<string>;
+  verifyKeptPackage(pi: PiInstallation, workspace: string, choice: PackageChoice): Promise<string>;
+}
+
+export const pbotPackage: PluginSpec = {
+  id: "pbot", label: "Personal Bot", description: "工作区个人助手", source: "npm:personal-bot", defaultSelected: true,
+};
+export function parseCatalog(value: unknown): PluginSpec[] {
+  if (!Array.isArray(value)) throw new Error("插件清单必须是数组。");
+  const ids = new Set(["pbot"]), names = new Set(["personal-bot"]);
+  return value.map((item: unknown) => {
+    if (!item || typeof item !== "object") throw new Error("无效插件清单项。");
+    const entry = item as Record<string, unknown>;
+    for (const field of ["id", "label", "description", "source"]) {
+      if (typeof entry[field] !== "string" || !entry[field].trim() || /[\x00-\x1f\x7f]/.test(entry[field])) {
+        throw new Error(`无效插件字段：${field}`);
+      }
+    }
+    const plugin = entry as unknown as PluginSpec;
+    const name = npmName(plugin.source);
+    if (!/^[a-z0-9-]+$/.test(plugin.id) || !name || !ordinaryNpm(plugin.source) ||
+      typeof plugin.defaultSelected !== "boolean" || ids.has(plugin.id) || names.has(name)) {
+      throw new Error(`无效或重复的插件：${plugin.id}`);
+    }
+    ids.add(plugin.id); names.add(name);
+    return { id: plugin.id, label: plugin.label, description: plugin.description,
+      source: `npm:${name}`, defaultSelected: plugin.defaultSelected };
+  });
+}
+export function packageChoices(catalog: PluginSpec[], installed: InstalledPackage[]): PackageChoice[] {
+  const first = !installed.some(pkg => pkg.name === "personal-bot");
+  return [pbotPackage, ...catalog].map(plugin => {
+    const matches = installed.filter(pkg => pkg.name === npmName(plugin.source));
+    // A project npm entry overrides the same npm identity in user settings. Different
+    // git/local identities still need an explicit decision before changing sources.
+    const localNpm = matches.some(pkg => pkg.scope === "project" && npmName(pkg.source));
+    const existing = matches.filter(pkg => !(localNpm && pkg.scope === "user" && npmName(pkg.source)));
+    const custom = existing.some(pkg => !ordinaryNpm(pkg.source));
+    return { plugin, required: plugin.id === "pbot", existing,
+      selected: plugin.id === "pbot" || (first ? plugin.defaultSelected : existing.length > 0), keep: custom };
+  });
+}
+export function parseSetupArgs(args: string[]): { action: "help" | "version" | "setup"; workspace?: string } {
+  if (!args.length || args.length === 1 && ["--help", "-h"].includes(args[0]!)) return { action: "help" };
+  if (args.length === 1 && ["--version", "-v"].includes(args[0]!)) return { action: "version" };
+  if (args[0] !== "setup") throw new Error("用法：pbot setup [--workspace <目录>]");
+  let workspace: string | undefined;
+  for (let index = 1; index < args.length; index++) {
+    const arg = args[index]!;
+    if ((arg === "--help" || arg === "-h") && args.length === 2) return { action: "help" };
+    if (arg !== "--workspace" || workspace !== undefined) throw new Error(`不支持的参数：${arg}`);
+    const value = args[++index];
+    if (!value || value.startsWith("--") || /[\x00-\x1f\x7f]/.test(value)) throw new Error("--workspace 需要目录。");
+    workspace = value;
+  }
+  return workspace === undefined ? { action: "setup" } : { action: "setup", workspace };
+}
+
+export async function executeSetup(plan: SetupPlan, operations: SetupOperations,
+  report: (result: SetupResult) => void, signal: AbortSignal): Promise<{ pi?: PiInstallation; results: SetupResult[] }> {
+  const results: SetupResult[] = [];
+  const add = (result: SetupResult) => { results.push(result); report(result); };
+  let pi: PiInstallation;
+  try {
+    signal.throwIfAborted();
+    if (plan.tmux) { await operations.installTmux(plan.tmux); add({ name: "tmux", state: "done", detail: "已安装" }); }
+    signal.throwIfAborted();
+    pi = await operations.ensurePi(plan.pi, plan.piVersion);
+    add({ name: "Pi", state: "done", detail: pi.version });
+  } catch (error) {
+    signal.throwIfAborted();
+    add({ name: "运行环境", state: "failed", detail: String(error) });
+    return { results };
+  }
+  for (const choice of plan.packages) {
+    signal.throwIfAborted();
+    const name = choice.plugin.label;
+    if (!choice.selected) { add({ name, state: "skipped", detail: "本次不处理" }); continue; }
+    if (choice.error) {
+      add({ name, state: "failed", detail: choice.error });
+      if (choice.required) return { results };
+      continue;
+    }
+    if (choice.keep) {
+      try {
+        const source = await operations.verifyKeptPackage(pi, plan.workspace, choice);
+        add({ name, state: "kept", detail: source });
+      } catch (error) {
+        signal.throwIfAborted();
+        add({ name, state: "failed", detail: String(error) });
+        if (choice.required) return { results };
+      }
+      continue;
+    }
+    try {
+      const version = await operations.installPackage(pi, plan.workspace, choice);
+      add({ name, state: "done", detail: version });
+    } catch (error) {
+      signal.throwIfAborted();
+      add({ name, state: "failed", detail: String(error) });
+      if (choice.required) return { results };
+    }
+  }
+  return { pi, results };
+}

package/src/storage/history-files.ts

@@ -0,0 +1,25 @@
+import { existsSync, mkdirSync, readdirSync } from "node:fs";
+import type { HistoryRecord } from "../model/history.js";
+import { object } from "../common/json.js";
+import { requireThat } from "../common/validation.js";
+import { readJsonFile, writeJsonFile } from "./atomic-json.js";
+import { fileId } from "./file-access.js";
+
+function record(value: unknown): HistoryRecord {
+  requireThat(object(value) && typeof value.id === "string" && typeof value.sessionId === "string" &&
+    typeof value.name === "string" && Array.isArray(value.nodes), "历史索引无效。");
+  return value as unknown as HistoryRecord;
+}
+export class HistoryFiles {
+  constructor(readonly directory: string) {}
+  list(workspace?: string) {
+    if (!existsSync(this.directory)) return [];
+    return readdirSync(this.directory).filter(name => name.endsWith(".json"))
+      .map(name => readJsonFile(this.directory, name, record))
+      .filter(value => workspace === undefined || ("workspace" in value && value.workspace === workspace));
+  }
+  save(value: HistoryRecord) {
+    mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+    writeJsonFile(this.directory, fileId(value.id) + ".json", value, record);
+  }
+}

package/src/tools/history/tool.ts

@@ -0,0 +1,42 @@
+import { Type } from "typebox";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import type { HistoryService } from "../../services/history/history-service.js";
+import type { CallAccess } from "../access.js";
+import { historyLocation } from "../../integrations/pi/history.js";
+import { requireThat } from "../../common/validation.js";
+import { markdownResult } from "../result.js";
+
+const nullableOffset = Type.Union([Type.Integer(), Type.Null()]);
+const node = Type.Object({ id: Type.String(), kind: Type.Union([Type.Literal("session"), Type.Literal("exchange"), Type.Literal("summary")]),
+  sessionId: Type.String(), name: Type.String(), preview: Type.String(), from: Type.String(), to: Type.String(), ready: Type.Boolean(), completed: Type.Boolean() });
+const resultSchema = Type.Object({
+  matches: Type.Optional(Type.Array(Type.Object({ ...node.properties, snippet: Type.String(), parents: Type.Array(Type.String()) }))),
+  total: Type.Optional(Type.Integer()), nextOffset: Type.Optional(nullableOffset),
+  node: Type.Optional(Type.Object({ ...node.properties, text: Type.String(), totalLength: Type.Integer(), nextOffset: nullableOffset,
+    parents: Type.Array(node), children: Type.Array(node), nextChildrenOffset: nullableOffset,
+    source: Type.Object({ sessionId: Type.String({ description: "原始 Pi 会话 ID；来源不保存文件路径。" }), entryIds: Type.Array(Type.String()) }), warnings: Type.Array(Type.String()) })),
+  warnings: Type.Array(Type.String()),
+});
+export function historyTool(service: HistoryService, access: CallAccess) {
+  return defineTool({ name: "pbot_history", label: "历史对话",
+    description: "查询当前工作区的 Pi 历史。search 对问答原文和各层摘要做不区分大小写的连续文本匹配；省略 query 列出会话。忘记原词时换几组词查询。read 读取命中节点并返回父子节点；沿 parents/children 的 id 展开，nextOffset 续读正文，nextChildrenOffset 续读子节点。摘要是检索线索，重要结论回到 exchange 原文核对。共享前缀可能有多个父节点。查询不调用模型，不恢复或重放旧任务。",
+    parameters: Type.Object({ action: Type.Union([Type.Literal("search"), Type.Literal("read")]),
+      query: Type.Optional(Type.String()), sessionId: Type.Optional(Type.String()),
+      from: Type.Optional(Type.String({ description: "search：ISO 日期或时间，下界。" })),
+      to: Type.Optional(Type.String({ description: "search：ISO 日期或时间，上界。" })),
+      id: Type.Optional(Type.String({ description: "read 必填：返回的节点 id。" })),
+      offset: Type.Optional(Type.Integer({ minimum: 0 })),
+      limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 24000, description: "search：最多 50 条，默认 20；read：字符数，默认 12000。" })),
+      childrenOffset: Type.Optional(Type.Integer({ minimum: 0 })),
+    }, { additionalProperties: false }), outputSchema: resultSchema,
+    async execute(_id, args, signal, _update, ctx) {
+      access.check(); signal?.throwIfAborted();
+      requireThat(args.action !== "read" || args.id, "read 需要节点 id。");
+      requireThat(args.action !== "search" || (args.limit ?? 20) <= 50, "search limit 最多 50。");
+      await service.refresh(historyLocation(ctx), signal);
+      access.check();
+      return args.action === "search" ? markdownResult(service.search(args), "历史搜索")
+        : markdownResult({ node: service.read(args.id!, args.offset, args.limit, args.childrenOffset), warnings: service.warnings }, "历史正文");
+    },
+  });
+}

package/src/tools/register.ts

@@ -8,9 +8,11 @@ import { agentTool } from "./agents/tool.js";
 import type { TeamService } from "../services/agents/team-service.js";
 import { teamTool, teamMessageTool } from "./teams/tool.js";
 import { agentOwner } from "../integrations/pi/agent-context.js";
+import type { HistoryService } from "../services/history/history-service.js";
+import { historyTool } from "./history/tool.js";
 
-export function mainTools(agents: AgentService, teams: TeamService, access: CallAccess): ToolDefinition[] {
-  return [agentTool(agents, access), teamTool(teams, agents, access), teamMessageTool(teams, access, ctx => ({ kind: "coordinator", owner: agentOwner(ctx) }))];
+export function mainTools(agents: AgentService, teams: TeamService, history: HistoryService, access: CallAccess): ToolDefinition[] {
+  return [agentTool(agents, access), teamTool(teams, agents, access), teamMessageTool(teams, access, ctx => ({ kind: "coordinator", owner: agentOwner(ctx) })), historyTool(history, access)];
 }
 export class ToolRegistry {
   readonly #registered = new Map<string, ToolDefinition>();
@@ -19,7 +21,7 @@ export class ToolRegistry {
     const promptGuidelines = readFileSync(join(resourceRoot, "prompts/tool-guidelines.md"), "utf8")
       .trim().split(/\r?\n\s*\r?\n/);
     for (const definition of tools) {
-      const tool = { ...definition, namespace: { name: "pbot", description: "Personal Bot 独立子会话与团队协作工具。" },
+      const tool = { ...definition, namespace: { name: "pbot", description: "Personal Bot 历史查询、独立子会话与团队协作工具。" },
         promptGuidelines };
       this.#registered.set(tool.name, tool); this.pi.registerTool(tool);
     }

package/src/ui/setup.ts

@@ -0,0 +1,40 @@
+import { createInterface } from "node:readline/promises";
+
+export class SetupUI {
+  constructor(private readonly controller: AbortController) {}
+  text(value: string) { console.log(value); }
+  async ask(label: string, fallback = ""): Promise<string> {
+    this.controller.signal.throwIfAborted();
+    const reader = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    reader.on("SIGINT", () => this.controller.abort(new Error("安装已取消。")));
+    reader.on("close", () => { if (!answered) this.controller.abort(new Error("输入已关闭。")); });
+    let answered = false;
+    try {
+      const value = await reader.question(label + (fallback ? " [" + fallback + "]" : "") + ": ", { signal: this.controller.signal });
+      answered = true;
+      return value.trim() || fallback;
+    } finally { answered = true; reader.close(); }
+  }
+  async confirm(label: string, fallback = true): Promise<boolean> {
+    while (true) {
+      const answer = (await this.ask(label + (fallback ? " [Y/n]" : " [y/N]"))).toLowerCase();
+      if (!answer) return fallback;
+      if (["y", "yes", "是"].includes(answer)) return true;
+      if (["n", "no", "否"].includes(answer)) return false;
+      this.text("请输入 y 或 n。");
+    }
+  }
+  async selectMany(labels: string[], defaults: number[]): Promise<number[]> {
+    labels.forEach((label, index) => this.text("  " + (defaults.includes(index) ? "[x] " : "[ ] ") + (index + 1) + ". " + label));
+    while (true) {
+      const answer = await this.ask("选择插件编号（逗号分隔，回车保留默认，0 不选）");
+      if (!answer) return defaults;
+      if (answer === "0") return [];
+      const parts = answer.split(/[,，\s]+/);
+      if (parts.every(part => /^\d+$/.test(part) && Number(part) >= 1 && Number(part) <= labels.length)) {
+        return [...new Set(parts.map(part => Number(part) - 1))];
+      }
+      this.text("请输入列表中的编号。");
+    }
+  }
+}