personal-bot 0.2.3 → 0.2.5

package/src/integrations/dsh/history.ts

@@ -0,0 +1,76 @@
+import { realpath } from "node:fs/promises";
+import type { Context } from "@deepseek-ai/cordis";
+import type { SessionEvent, SessionHeader } from "@deepseek-ai/dsh-session";
+import { SessionId } from "@deepseek-ai/dsh-session";
+import type {} from "@deepseek-ai/dsh-session-query";
+import type { HistoryExchange, HistoryLocation, HistorySession, HistorySource } from "../../model/history.js";
+import { requireThat } from "../../common/validation.js";
+import { finalDshAnswer } from "./messages.js";
+
+type Question = Extract<SessionEvent, { type: "user/message" }>;
+type Answer = Extract<SessionEvent, { type: "assistant/message" }>;
+const text = (content: Question["data"]["content"]) => content.flatMap(block => block.type === "text" ? [block.text] :
+  block.type === "image" ? ["[图片 " + (block.attachment.name ?? block.attachment.attachmentId) + "]"] :
+    block.type === "file" ? ["[附件 " + (block.attachment.name ?? block.attachment.attachmentId) + "]"] : []).join("\n");
+
+/** Archive questions and the final/partial answer; raw tool records stay in the native log. */
+export function projectDshHistory(header: SessionHeader, events: readonly SessionEvent[], name = ""): HistorySession {
+  const exchanges: HistoryExchange[] = [];
+  let users: Question[] = [], answer: Answer | undefined;
+  const finish = (completed = false) => {
+    if (users.length) {
+      const entries = [...users, ...(answer ? [answer] : [])];
+      const body = answer ? answer.data.message.content.filter(block => block.type === "text").map(block => block.text).join("\n") : "";
+      exchanges.push({ entryIds: entries.map(event => "dsh:" + event.seq), from: new Date(users[0]!.time).toISOString(),
+        to: new Date(entries.at(-1)!.time).toISOString(),
+        completed: completed && Boolean(answer && finalDshAnswer(answer).trim()),
+        text: users.map(event => (event.data.source.kind === "user" ? "用户：\n" : "协调者要求：\n") + text(event.data.content)).join("\n\n") +
+          (body ? "\n\n助手：\n" + body : "") });
+    }
+    users = []; answer = undefined;
+  };
+  for (const event of events) {
+    if (event.type === "turn/start") finish();
+    else if (event.type === "user/message" && ["user", "pbot-input"].includes(event.data.source.kind)) users.push(event);
+    else if (event.type === "assistant/message" && users.length) answer = event;
+    else if (event.type === "turn/end") finish(event.data.reason.kind === "completed");
+  }
+  finish();
+  return { sessionId: header.id, name: name || exchanges[0]?.text.replace(/\s+/g, " ").slice(0, 80) || "",
+    branches: exchanges.length ? [exchanges] : [] };
+}
+
+export class DshHistory implements HistorySource {
+  readonly host = "dsh";
+  constructor(private readonly ctx: Context, private readonly root: string, private readonly relatedSessions: () => string[] = () => []) {}
+  async scan(location: HistoryLocation, signal?: AbortSignal) {
+    requireThat(location.host === "dsh", "dsh 历史只读取 dsh 原生会话。");
+    signal?.throwIfAborted();
+    const records = await this.ctx.sessionQuery.listSessions(signal), selected = new Set<string>(), warnings: string[] = [];
+    try { for (const id of this.relatedSessions()) selected.add(id); } catch (error) { warnings.push("专家引用：" + String(error)); }
+    if (location.sessionId) selected.add(location.sessionId);
+    for (const record of records) {
+      signal?.throwIfAborted();
+      if ((record.header.origin !== "subagent" || !record.header.parentSession) && record.header.cwd &&
+        await realpath(record.header.cwd).catch(() => record.header.cwd) === this.root) selected.add(record.header.id);
+    }
+    // Native subagents may use a different cwd while still belonging to a workspace's parent.
+    for (let changed = true; changed;) {
+      changed = false;
+      for (const record of records) if (record.header.origin === "subagent" && record.header.parentSession && selected.has(record.header.parentSession) && !selected.has(record.header.id)) {
+        selected.add(record.header.id); changed = true;
+      }
+    }
+    const sessions: HistorySession[] = [];
+    for (const id of selected) {
+      signal?.throwIfAborted();
+      try {
+        using observation = await this.ctx.sessionQuery.observeSession(SessionId(id), { ...(signal ? { signal } : {}), projectionMode: "none" });
+        const title = await this.ctx.sessionQuery.readTitle(SessionId(id), signal);
+        const session = projectDshHistory(observation.header, observation.events, title?.title);
+        if (session.branches.length) sessions.push(session);
+      } catch (error) { signal?.throwIfAborted(); warnings.push(id + ": " + String(error)); }
+    }
+    return { sessions, warnings };
+  }
+}

package/src/integrations/dsh/input.ts

@@ -0,0 +1,66 @@
+import { basename, extname } from "node:path";
+import type { Context } from "@deepseek-ai/cordis";
+import { createUserMessage, type FileBlock, type ImageBlock } from "@deepseek-ai/dsh-llm";
+import type { AttachmentAdmissionPart, ImageMediaType } from "@deepseek-ai/dsh-attachment";
+import type { FsTarget } from "@deepseek-ai/dsh-fs";
+import type { AgentDescriptor, AgentMessage } from "../../model/agent.js";
+import { requireThat } from "../../common/validation.js";
+import "./messages.js";
+
+const imageTypes: Record<string, ImageMediaType> = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif" };
+
+/** Native file attachments remain verbatim; image admission uses the host's policy. */
+async function contentFor(ctx: Context, cwd: string, message: string, files: readonly string[], signal: AbortSignal) {
+  const content: AttachmentAdmissionPart[] = [];
+  let imageCount = 0, imageBytes = 0;
+  for (const path of files) {
+    signal.throwIfAborted();
+    const target = await ctx.fs.resolve(path, { cwd, signal });
+    const before = await ctx.fs.stat(target, signal);
+    requireThat(before?.type === "file", "附件必须是普通文件：" + path);
+    const name = basename(path), mediaType = imageTypes[extname(path).toLowerCase()];
+    if (mediaType) {
+      const limits = ctx.attachments.imageLimits;
+      requireThat(++imageCount <= limits.maxImagesPerMessage &&
+        (before.size === undefined || imageBytes + before.size <= limits.maxMessageImageBytes), "图片附件超过宿主消息准入上限。");
+      const data = await ctx.fs.readBytes(target, signal, limits.maxImageBytes);
+      imageBytes += data.byteLength;
+      requireThat(imageBytes <= limits.maxMessageImageBytes, "图片附件超过宿主消息准入上限。");
+      content.push({ type: "image", mediaType, name, data: Buffer.from(data).toString("base64") });
+    } else {
+      async function* bytes(file: FsTarget) {
+        let offset = 0;
+        for (;;) {
+          signal.throwIfAborted();
+          const chunk = await ctx.fs.readByteRange(file, { offset, length: 256 * 1024 }, signal);
+          if (!chunk.length) break;
+          yield chunk; offset += chunk.length;
+        }
+        requireThat((await ctx.fs.stat(file, signal))?.version === before?.version, "读取期间附件已变化：" + path);
+      }
+      content.push({ type: "file", attachment: await ctx.attachments.saveFileStream({ data: bytes(target), name, signal }) });
+    }
+    requireThat((await ctx.fs.stat(target, signal))?.version === before.version, "读取期间附件已变化：" + path);
+    content.push({ type: "text", text: "附件原始路径：" + JSON.stringify(path) + "。原生附件保留本次文件内容；需要查看时使用宿主提供的附件路径。" });
+  }
+  content.push({ type: "text", text: message || "请处理所附文件。" });
+  const admitted = await ctx.attachments.admitPromptContent(content);
+  signal.throwIfAborted(); return admitted;
+}
+
+export async function dshInput(ctx: Context, d: AgentDescriptor, request: AgentMessage, signal: AbortSignal) {
+  const content = await contentFor(ctx, d.cwd, request.message, request.files, signal);
+  return createUserMessage({ content, source: { kind: "pbot-input", form: "relay",
+    requestId: request.requestId, generation: request.generation, parentSessionId: d.parentSessionId } });
+}
+
+/** Command attachments have already passed native upload admission; the caller never supplies arbitrary references. */
+export async function dshHumanInput(ctx: Context, cwd: string, text: string, files: readonly string[],
+  attachments: readonly (ImageBlock | FileBlock)[], signal: AbortSignal) {
+  requireThat(files.length + attachments.length <= 32, "一次最多附加 32 个文件。");
+  requireThat(!files.length || !attachments.length, "一次对话请选择服务器文件或输入框附件，不能同时使用。");
+  signal.throwIfAborted();
+  const content = attachments.length ? [...attachments, { type: "text" as const, text: text || "请处理所附文件。" }] :
+    await contentFor(ctx, cwd, text, files, signal);
+  signal.throwIfAborted(); return createUserMessage({ content, source: { kind: "user" } });
+}

package/src/integrations/dsh/messages.ts

@@ -0,0 +1,22 @@
+import { lastAssistantStreamChunk, type UserMessage } from "@deepseek-ai/dsh-llm";
+import type { SessionEvent } from "@deepseek-ai/dsh-session";
+
+/** Producer metadata travels with native messages and never grants task authorization. */
+declare module "@deepseek-ai/dsh-llm" {
+  interface MessageSourceMap {
+    "pbot-input": { kind: "pbot-input"; form: "relay"; requestId: string; generation: string; parentSessionId: string };
+    "pbot-team-context": { kind: "pbot-team-context"; form: "relay"; teamId: string; seqs: number[] };
+    "pbot-results": { kind: "pbot-results"; form: "notice"; summary: string; keys: string[] };
+  }
+}
+
+export function finalDshAnswer(event: Extract<SessionEvent, { type: "assistant/message" }>) {
+  const { message, interrupted, stream } = event.data;
+  if (interrupted || message.content.some(block => block.type === "tool-call") || lastAssistantStreamChunk(stream, "finish")?.reason.kind !== "stop") return "";
+  return message.content.filter(block => block.type === "text").map(block => block.text).join("\n");
+}
+
+export function requestSource(message: UserMessage, generation: string) {
+  const source = message.source;
+  return source.kind === "pbot-input" && source.generation === generation ? source : undefined;
+}

package/src/integrations/dsh/notifications.ts

@@ -0,0 +1,46 @@
+import type { SessionEvent } from "@deepseek-ai/dsh-session";
+import type { UserMessage } from "@deepseek-ai/dsh-llm";
+import type {} from "@deepseek-ai/dsh-tool-executor-ptc";
+import { object } from "../../common/json.js";
+import "./messages.js";
+
+function keys(value: unknown, field: string) {
+  if (!object(value)) return [];
+  const items = value[field];
+  return Array.isArray(items) && items.every(item => typeof item === "string") ? items as string[] : [];
+}
+
+/** Only committed native context or successful model tool results claim notices.
+ * PTC inner reads require their enclosing transport to have committed success. */
+export function deliveredDshNotices(events: readonly SessionEvent[]) {
+  const delivered = new Set<string>();
+  const reads = new Set<string>(), nested = new Map<string, string[]>();
+  for (const event of events) {
+    if (event.type === "turn/start" || event.type === "step/start" || event.type === "turn/end") { reads.clear(); nested.clear(); }
+    if (event.type === "user/message" && event.data.source.kind === "pbot-results") {
+      for (const key of keys(event.data.source, "keys")) delivered.add(key);
+    }
+    if (event.type === "tool/call" && event.data.name === "pbot_agent") {
+      try { const args: unknown = JSON.parse(event.data.arguments); if (object(args) && args.action === "read") reads.add(event.data.callId); } catch { /* An invalid call cannot claim a report. */ }
+    }
+    if (event.type === "tool/ptc-dispatch" && event.data.name === "pbot_agent" && !event.data.isError &&
+      object(event.data.arguments) && event.data.arguments.action === "read") {
+      const values = nested.get(event.data.rootCallId) ?? [];
+      values.push(...keys(event.data.meta, "pbotAgentReadKeys")); nested.set(event.data.rootCallId, values);
+    }
+    if (event.type === "tool/result") {
+      const message = event.data.message;
+      if (!message.isError) {
+        if (reads.has(message.toolCallId)) for (const key of keys(event.data.meta, "pbotAgentReadKeys")) delivered.add(key);
+        for (const key of nested.get(message.toolCallId) ?? []) delivered.add(key);
+      }
+      reads.delete(message.toolCallId); nested.delete(message.toolCallId);
+    }
+  }
+  return delivered;
+}
+
+/** Pending inbox entries prevent duplicate submission, but are not delivery receipts. */
+export function pendingDshNotices(messages: readonly UserMessage[]) {
+  return messages.flatMap(message => message.source.kind === "pbot-results" ? keys(message.source, "keys") : []);
+}

package/src/integrations/dsh/resources.ts

@@ -0,0 +1,44 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import { FileSystemSkillProvider } from "@deepseek-ai/dsh-skill-filesystem";
+import type {} from "@deepseek-ai/dsh-working-directory";
+import type {} from "@deepseek-ai/dsh-tools";
+import { agentText } from "../agent-resources.js";
+import { resourceRoot } from "../../common/paths.js";
+import { requireThat } from "../../common/validation.js";
+import type { AgentOptions } from "../../model/agent.js";
+
+export async function dshResources(ctx: Context, agent: Agent, root: string,
+  role: "coordinator" | "general-purpose", python: () => { state: string; directory?: string; error?: string }, check: () => void) {
+  let text = await agentText(role, root);
+  const workspace = await readFile(join(resourceRoot, "prompts/workspace.md"), "utf8");
+  check();
+  ctx.systemPrompt.section({ name: "pbot:role", order: 1, text: () => text, interpolate: false });
+  ctx.systemPrompt.section({ name: "pbot:workspace", order: 2, text: workspace, interpolate: false });
+  ctx.systemPrompt.context({ name: "pbot:environment", order: 300, required: true, interpolate: false,
+    text: () => JSON.stringify({ host: "dsh", workspaceRoot: root, cwd: ctx.workingDirectory.get(agent.session), resourceRoot, python: python() }) });
+  ctx.skills.registerProvider(control => new FileSystemSkillProvider(ctx, control, {
+    providerName: "pbot", includeDefaultRoots: false, customSkillDirs: [join(root, ".agents/skills")],
+    bundledSkillDir: join(resourceRoot, "skills"), watch: false,
+  }));
+  ctx.on("agent/pre-step", async (_payload, next) => {
+    check(); text = await agentText(role, root); check();
+    return next();
+  });
+}
+
+/** Map the expert's native loadout; this is not isolation from Bash, CLI, or MCP. */
+export function dshExpertTools(ctx: Context, agent: Agent, options: AgentOptions) {
+  const names = new Set(ctx.tools.definitions(agent).map(tool => tool.name));
+  const forbidden = new Set(["pbot_agent", "pbot_team", "pbot_history", "subagent", "list_subagent_models", "list_agents", "send_message", "interrupt_agent"]);
+  if (options.noSkills) forbidden.add("skill");
+  if (options.tools) {
+    for (const name of options.tools) requireThat((names.has(name) || name === "pbot_team_message") && !forbidden.has(name), "专家工具不可用：" + name);
+    ctx.tools.restrict({ allow: options.tools.filter(name => name !== "pbot_team_message") });
+  }
+  const deny = [...forbidden].filter(name => names.has(name));
+  if (deny.length) ctx.tools.restrict({ deny });
+  return !options.tools || options.tools.includes("pbot_team_message");
+}

package/src/integrations/dsh/schema.ts

@@ -0,0 +1,26 @@
+import type { TSchema } from "typebox";
+import type { JsonSchemaNode } from "@deepseek-ai/dsh-tools";
+import { requireThat } from "../../common/validation.js";
+
+/** Remove TypeBox's non-JSON metadata before passing a schema to the native host. */
+export function dshParameters(value: TSchema): Record<string, unknown> {
+  return JSON.parse(JSON.stringify(value)) as Record<string, unknown>;
+}
+
+/** Collaboration result unions are disjoint. rc.1 enforces structural oneOf schemas;
+ * the producing tool also validates the complete contract, including these bounds. */
+export function dshOutputSchema(value: TSchema): JsonSchemaNode {
+  const bounds = new Set(["minLength", "maxLength", "pattern", "minimum", "maximum", "minItems", "maxItems"]);
+  const supported = new Set(["type", "required", "additionalProperties", "enum", "const", "description", "title", "default", "examples"]);
+  function convert(node: Record<string, unknown>): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(node)) {
+      if (key === "anyOf") result.oneOf = (item as Record<string, unknown>[]).map(convert);
+      else if (key === "properties") result.properties = Object.fromEntries(Object.entries(item as Record<string, Record<string, unknown>>).map(([name, child]) => [name, convert(child)]));
+      else if (key === "items") result.items = convert(item as Record<string, unknown>);
+      else if (!bounds.has(key)) { requireThat(supported.has(key), "dsh 输出 schema 不支持字段：" + key); result[key] = item; }
+    }
+    return result;
+  }
+  return convert(dshParameters(value)) as JsonSchemaNode;
+}

package/src/integrations/dsh/session.ts

@@ -0,0 +1,67 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent, AgentHandle, AgentSetup } from "@deepseek-ai/dsh-agent";
+import { SessionId } from "@deepseek-ai/dsh-session";
+import { ReasoningEffortId } from "@deepseek-ai/dsh-llm";
+import type { SessionHeader } from "@deepseek-ai/dsh-session";
+import type {} from "@deepseek-ai/dsh-session-persistence";
+import type { AgentDescriptor } from "../../model/agent.js";
+import { requireThat } from "../../common/validation.js";
+
+function validateHeader(d: AgentDescriptor, header: SessionHeader) {
+  requireThat(header.id === d.agentId && header.cwd === d.cwd && header.parentSession === d.parentSessionId &&
+    header.origin === "subagent" && !header.isSeeded, "dsh 专家会话身份、父会话或工作目录不匹配。");
+}
+
+/** Read access must neither claim a writer nor activate an Agent. */
+export async function readDshAgentSession(ctx: Context, d: AgentDescriptor) {
+  const reader = await ctx.sessionPersistence.open(SessionId(d.agentId), "read");
+  try {
+    validateHeader(d, reader.header);
+    return { header: reader.header, events: (await reader.read()).events };
+  } finally {
+    await reader.close();
+  }
+}
+
+/** An empty Agent is not recoverable until this native barrier has materialized it. */
+export async function flushDshAgent(agent: Agent) {
+  requireThat(await agent.ctx.sessions.flush(agent.session), "dsh 会话没有持久化屏障。");
+}
+
+export async function openDshAgent(ctx: Context, d: AgentDescriptor, parent: Agent, resume: boolean,
+  setup: AgentSetup, signal: AbortSignal): Promise<AgentHandle> {
+  signal.throwIfAborted();
+  requireThat(parent.id === d.parentSessionId && ctx.agents.get(parent.id) === parent, "dsh 父会话已失效。");
+  if (resume) await readDshAgentSession(ctx, d);
+  await flushDshAgent(parent);
+  signal.throwIfAborted();
+  const compose: AgentSetup = async (agentCtx, agent) => {
+    validateHeader(d, agent.session.header);
+    if (resume) agent.inbox.clear();
+    const commit = await setup(agentCtx, agent);
+    await flushDshAgent(agent);
+    return commit;
+  };
+  const agentOptions = { ...(d.options.provider ? { provider: d.options.provider } : {}),
+    ...(d.options.model ? { model: d.options.model } : {}),
+    ...(d.options.thinking ? { reasoningEffort: ReasoningEffortId(d.options.thinking) } : {}) };
+  return resume
+    ? ctx.agents.resume({ resumeSessionId: SessionId(d.agentId), parentAgent: parent, agentOptions, setup: compose, signal })
+    : ctx.agents.create({ sessionId: SessionId(d.agentId), parentAgent: parent,
+      meta: { cwd: d.cwd, parentSession: parent.id, origin: "subagent", delegationDepth: 1 },
+      agentOptions, setup: compose, signal });
+}
+
+/** A report refers to one durable turn boundary, never the latest answer. */
+export async function readDshReport(ctx: Context, d: AgentDescriptor, reference: string) {
+  const match = /^dsh:(0|[1-9]\d*)$/.exec(reference);
+  requireThat(match, "dsh 报告位置无效。");
+  const end = Number(match[1]);
+  requireThat(Number.isSafeInteger(end), "dsh 报告位置无效。");
+  const { events } = await readDshAgentSession(ctx, d);
+  const boundary = events[end];
+  requireThat(boundary?.type === "turn/end", "dsh 报告结束位置不存在。");
+  const last = events.slice(0, end).findLast(event => event.type === "assistant/message" && event.data.turn === boundary.data.turn);
+  return last?.type === "assistant/message"
+    ? last.data.message.content.filter(block => block.type === "text").map(block => block.text).join("\n") : "";
+}

package/src/integrations/history-summary.ts

@@ -0,0 +1,20 @@
+import type { HistorySummarizer } from "../model/history.js";
+import { requireThat } from "../common/validation.js";
+
+export function reduceHistorySummary(budget: number, ask: HistorySummarizer): HistorySummarizer {
+  return async (text, signal) => {
+    while (text.length > budget) {
+      const parts: string[] = [];
+      for (let offset = 0; offset < text.length;) {
+        signal.throwIfAborted();
+        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;
+    }
+    signal.throwIfAborted(); return ask(text, signal);
+  };
+}

package/src/integrations/installation/pi-bridge.ts

@@ -0,0 +1,107 @@
+import { readFileSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { InstalledPackage } from "../../services/installation/setup-service.js";
+import { npmName } from "../../common/package-source.js";
+
+type PiSdk = typeof import("@earendil-works/pi-coding-agent");
+async function sdkAt(root: string): Promise<PiSdk> {
+  const manifest = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+  if (manifest.name !== "@earendil-works/pi-coding-agent") throw new Error("不是支持的 Pi 安装。");
+  return import(pathToFileURL(join(root, "dist/index.js")).href) as Promise<PiSdk>;
+}
+const sourceOf = (entry: unknown): string => {
+  if (typeof entry === "string") return entry;
+  if (entry && typeof entry === "object" && "source" in entry && typeof entry.source === "string") return entry.source;
+  throw new Error("无效的 Pi packages 声明。");
+};
+
+export async function inspectPackages(root: string, workspace: string): Promise<InstalledPackage[]> {
+  const sdk = await sdkAt(root), agentDir = sdk.getAgentDir();
+  // Inspect project declarations as data only. This does not load extensions, execute
+  // project npmCommand, grant project trust, or persist migrated settings.
+  const settings = sdk.SettingsManager.fromStorage({ withLock(scope, read) {
+    const file = scope === "global" ? join(agentDir, "settings.json") : join(workspace, sdk.CONFIG_DIR_NAME, "settings.json");
+    let content: string | undefined;
+    try { content = readFileSync(file, "utf8"); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+    if (content !== undefined) {
+      const value: unknown = JSON.parse(content);
+      if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`无效的 Pi 配置：${file}`);
+      const packages = (value as { packages?: unknown }).packages;
+      if (packages !== undefined) {
+        if (!Array.isArray(packages)) throw new Error(`packages 必须是数组：${file}`);
+        packages.forEach(sourceOf);
+      }
+    }
+    if (read(content) !== undefined) throw new Error("安装检查不得修改 Pi 配置。");
+  } }, { projectTrusted: true });
+  const errors = settings.drainErrors();
+  if (errors.length) throw new Error(errors.map(item => `${item.scope}: ${item.error.message}`).join("\n"));
+  const manager = new sdk.DefaultPackageManager({ cwd: workspace, agentDir, settingsManager: settings });
+  const result: InstalledPackage[] = [];
+  for (const pkg of manager.listConfiguredPackages()) {
+    const entries = (pkg.scope === "project" ? settings.getProjectSettings() : settings.getGlobalSettings()).packages ?? [];
+    const entry = entries.find(item => sourceOf(item) === pkg.source);
+    let name = npmName(pkg.source), version: string | undefined;
+    if (pkg.installedPath) {
+      let file = pkg.installedPath;
+      if ((await stat(file)).isDirectory()) file = join(file, "package.json");
+      else file = ""; // Single-file extensions have no npm identity.
+      if (file) {
+        try {
+          const manifest = JSON.parse(await readFile(file, "utf8")) as { name?: string; version?: string };
+          if (name && manifest.name !== name) throw new Error(`安装包身份不匹配：${pkg.source}`);
+          name = typeof manifest.name === "string" ? manifest.name : name;
+          version = typeof manifest.version === "string" ? manifest.version : undefined;
+        } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+      }
+    }
+    result.push({ source: pkg.source, scope: pkg.scope, filtered: pkg.filtered, entry,
+      ...(pkg.installedPath ? { installedPath: pkg.installedPath } : {}), ...(name ? { name } : {}), ...(version ? { version } : {}) });
+  }
+  return result;
+}
+
+export async function replaceProjectSource(root: string, workspace: string, old: InstalledPackage, target: string): Promise<void> {
+  const fromProject = old.scope === "project" && !npmName(old.source);
+  const fromUser = old.scope === "user" && !!npmName(old.source);
+  if (!fromProject && !fromUser) throw new Error("此操作只替换工作区自定义来源，或继承全局 npm 资源过滤。");
+  const sdk = await sdkAt(root);
+  const settings = sdk.SettingsManager.create(workspace, sdk.getAgentDir(), { projectTrusted: true });
+  const errors = settings.drainErrors();
+  if (errors.length) throw new Error(errors.map(item => item.error.message).join("\n"));
+  const packages = settings.getProjectSettings().packages ?? [];
+  const originals = fromProject ? packages : settings.getGlobalSettings().packages ?? [];
+  const previous = originals.find(entry => sourceOf(entry) === old.source);
+  if (previous === undefined || JSON.stringify(previous) !== JSON.stringify(old.entry)) throw new Error("插件配置已发生变化，请重新运行 setup。");
+  if (!packages.some(entry => sourceOf(entry) === target)) throw new Error("目标包尚未安装，保留原声明。");
+  const manager = new sdk.DefaultPackageManager({ cwd: workspace, agentDir: sdk.getAgentDir(), settingsManager: settings });
+  const installed = manager.getInstalledPath(target, "project");
+  if (!installed || !npmName(target)) throw new Error("目标 npm 包尚未安装，保留原声明。");
+  const manifest = JSON.parse(await readFile(join(installed, "package.json"), "utf8"));
+  if (manifest.name !== npmName(target)) throw new Error("目标安装包身份不符，保留原声明。");
+  // Change only declarations; do not call remove(), which deletes managed git caches.
+  const replacement = typeof previous === "string" ? target : { ...previous, source: target };
+  const next = fromProject
+    ? packages.filter(entry => sourceOf(entry) !== target).map(entry => sourceOf(entry) === old.source ? replacement : entry)
+    : packages.map(entry => sourceOf(entry) === target ? replacement : entry);
+  settings.setProjectPackages(next);
+  await settings.flush();
+  const failures = settings.drainErrors();
+  if (failures.length) throw new Error(failures.map(item => item.error.message).join("\n"));
+}
+
+async function main() {
+  const [action, root, workspace, input] = process.argv.slice(2);
+  if (!root || !workspace) throw new Error("缺少 Pi 路径或工作区。");
+  if (action === "inspect") console.log(JSON.stringify(await inspectPackages(root, workspace)));
+  else if (action === "replace" && input) {
+    const { old, target } = JSON.parse(input) as { old: InstalledPackage; target: string };
+    await replaceProjectSource(root, workspace, old, target);
+  } else throw new Error("无效的安装检查操作。");
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main().catch(error => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });
+}