personal-bot 0.2.3 → 0.2.5

package/src/extension/dsh/command.ts

@@ -0,0 +1,78 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type {} from "@deepseek-ai/dsh-commands";
+import { Type, type Static } from "typebox";
+import { object, json } from "../../common/json.js";
+import { requireThat, schema } from "../../common/validation.js";
+import { prepareWorkspace } from "../../services/workspace/workspace-preparation.js";
+import { executeAgent, type AgentInput } from "../../tools/agents/actions.js";
+import { dshAgentActionSchema } from "../../tools/agents/dsh-contract.js";
+import { executeTeam, executeTeamMessage } from "../../tools/teams/actions.js";
+import { teamActionSchema, teamParametersSchema, teamMessageActionSchema, teamMessageParametersSchema } from "../../tools/teams/contract.js";
+import { dshStatus, type PbotManagement } from "./management.js";
+import type { DshWorkspaces } from "./workspace.js";
+
+const validAgent = schema(dshAgentActionSchema), validTeam = schema(teamActionSchema), validMessage = schema(teamMessageActionSchema);
+const chatSchema = Type.Object({ agentId: Type.String({ minLength: 1 }), text: Type.Optional(Type.String({ maxLength: 24000 })),
+  delivery: Type.Optional(Type.Union([Type.Literal("steer"), Type.Literal("followUp")])),
+  files: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { maxItems: 32 })) }, { additionalProperties: false });
+const validChat = schema(chatSchema);
+const usage = '用法：/pbot status | init | python setup | agent {"action":…} | chat {"agentId":…,"text":…} | team {"action":…} | post {"teamId":…,"text":…} | history {"action":…} | records {"agentId":…}';
+
+export function registerDshCommand(ctx: Context, workspaces: DshWorkspaces, management: PbotManagement) {
+  ctx.commands.register({ name: "pbot", description: "Personal Bot 工作区与协作管理", recordInput: false,
+    input: { hint: "status | init | python setup | agent/chat/team/post/history/records JSON", attachments: true },
+    async handler({ agent, rawInput, signal, attachments, commandId }) {
+      signal.throwIfAborted();
+      const workspace = await workspaces.get(agent);
+      signal.throwIfAborted();
+      const command = rawInput.trim(), split = command.search(/\s/);
+      const verb = split < 0 ? command : command.slice(0, split);
+      requireThat(verb === "chat" || !attachments.length, "输入框附件仅用于 chat 人工对话。");
+      if (command === "init") {
+        await prepareWorkspace(workspace.root); workspace.check();
+        return { kind: "success", text: "资料目录已准备；已有文件保留。" };
+      }
+      if (command === "python setup") {
+        const result = await workspaces.preparePython(); workspace.check();
+        return { kind: "success", text: JSON.stringify(result, null, 2) };
+      }
+      if (!command || command === "status") return { kind: "success", text: JSON.stringify(dshStatus(workspaces, workspace), null, 2) };
+      requireThat(split >= 0, usage);
+      const input: unknown = JSON.parse(command.slice(split));
+      requireThat(object(input), "命令参数必须是 JSON 对象。");
+      let result: unknown;
+      switch (verb) {
+        case "agent": {
+          requireThat(validAgent(input), "dsh 专家参数无效或包含不支持的宿主选项。");
+          const selection = agent.model.current();
+          const output = await executeAgent(workspace.agents, input as AgentInput, workspace.owner, selection ? {
+            provider: selection.provider, model: selection.model,
+            ...(selection.reasoningEffort && (!input.provider || input.provider === selection.provider) && (!input.model || input.model === selection.model)
+              ? { thinking: selection.reasoningEffort } : {}),
+          } : {});
+          result = output.structuredContent; break;
+        }
+        case "chat": {
+          requireThat(validChat(input), "人工对话参数无效。");
+          const args = input as Static<typeof chatSchema>;
+          result = await workspace.expert(args.agentId).interact(args.text ?? "", args.delivery, args.files, attachments, signal); break;
+        }
+        case "team": {
+          requireThat(validTeam(input), "团队参数无效。");
+          result = executeTeam(workspace.teams, workspace.agents, input as Static<typeof teamParametersSchema>, workspace.owner).structuredContent; break;
+        }
+        case "post": {
+          const args = { ...input, action: "post" as const };
+          requireThat(input.action === undefined && validMessage(args), "公共消息参数无效。");
+          result = executeTeamMessage(workspace.teams, args as Static<typeof teamMessageParametersSchema>,
+            { kind: "user", owner: workspace.owner }, commandId).structuredContent; break;
+        }
+        case "history": result = await management.history({ parentSessionId: agent.id, input: json(input) }, signal); break;
+        case "records": result = await management.expert({ parentSessionId: agent.id, input: json(input) }, signal); break;
+        default: throw new Error(usage);
+      }
+      workspace.check();
+      return { kind: "success", text: JSON.stringify(result, null, 2) };
+    },
+  });
+}

package/src/extension/dsh/files.ts

@@ -0,0 +1,61 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { ToolExecution, ToolExecutionToken } from "@deepseek-ai/dsh-tools";
+import { parsePatch } from "@deepseek-ai/dsh-fs-patch";
+import type {} from "@deepseek-ai/dsh-user-approval";
+import { object } from "../../common/json.js";
+import { requireThat } from "../../common/validation.js";
+import { mutationScope } from "../../services/workspace/workspace-files.js";
+
+/** Native filesystem mutations share the original workspace's confirmation rule.
+ * This does not confine Bash, Python, MCP, or other extensions. */
+export function registerDshFileEvents(ctx: Context, agent: Agent, root: string, expert: boolean, check: () => void) {
+  const lifetime = new AbortController();
+  const mutations = new Set(["write", "edit", "apply_patch"]);
+  const captured = new Map<ToolExecutionToken, { cwd: string; keys: string[]; approved: boolean }>();
+  ctx.effect(() => () => { lifetime.abort(); captured.clear(); });
+  async function targets(exec: Readonly<ToolExecution>) {
+    check(); const args = exec.arguments;
+    requireThat(exec.agent === agent && object(args), "文件操作会话或参数无效。");
+    const signal = AbortSignal.any([lifetime.signal, exec.signal]); signal.throwIfAborted();
+    let paths: string[];
+    if (exec.name === "apply_patch") {
+      requireThat(typeof args.input === "string", "补丁参数无效。");
+      paths = parsePatch(args.input).flatMap(operation => [operation.path, ...(operation.kind === "update" && operation.moveTo ? [operation.moveTo] : [])]);
+    } else {
+      requireThat(typeof args.file_path === "string" && args.file_path.trim().length > 0, "文件路径无效。");
+      paths = [args.file_path];
+    }
+    const anchor = ctx.fs.processPathFromHostPath(root);
+    requireThat(anchor !== undefined, "原生文件系统未映射当前工作区。");
+    const cwd = ctx.workingDirectory.get(agent.session);
+    const resolved = await Promise.all(paths.map(path => ctx.fs.resolve(path, { cwd, signal })));
+    signal.throwIfAborted(); check();
+    const outside = resolved.map(target => ctx.fs.processPath(target)).filter(path => mutationScope(anchor, path) === "outside");
+    return { cwd, keys: resolved.map(target => target.targetKey), outside, signal };
+  }
+  ctx.on("tools/pre-execute", async (exec, next) => {
+    if (!mutations.has(exec.name)) return next();
+    const value = await targets(exec), record = { cwd: value.cwd, keys: value.keys, approved: !value.outside.length };
+    captured.set(exec.token, record);
+    if (value.outside.length && expert) return { kind: "deny", reason: "专家不能修改工作区外文件。" };
+    const policy = await next(); value.signal.throwIfAborted(); check();
+    if (policy.kind === "deny" || policy.kind === "cancel" || !value.outside.length) return policy;
+    const scopeReason = "Personal Bot: confirm changes outside the original workspace: " + JSON.stringify(value.outside);
+    const reason = [policy.kind === "ask" ? policy.reason : undefined, scopeReason].filter(Boolean).join("\n");
+    const outcome = await ctx.approval.request({ agent, toolName: exec.name, callId: exec.callId, signal: value.signal, reason,
+      displayReason: { en: reason, "zh-CN": "允许本次修改原工作区之外的文件：" + value.outside.join("、") + (policy.kind === "ask" && policy.reason ? "\n" + policy.reason : "") } });
+    value.signal.throwIfAborted(); check();
+    record.approved = outcome === "allowed-once";
+    return record.approved ? { kind: "allow" } : { kind: "deny", reason: "用户未确认文件修改。" };
+  });
+  ctx.on("tools/execute", async (exec, next) => {
+    if (!mutations.has(exec.name)) return next();
+    const record = captured.get(exec.token);
+    requireThat(record?.approved, "文件操作没有有效的范围检查或确认。");
+    const value = await targets(exec);
+    requireThat(record.cwd === value.cwd && record.keys.length === value.keys.length && record.keys.every((key, index) => key === value.keys[index]), "确认期间文件路径或工作目录已变化。");
+    return next();
+  });
+  ctx.on("tools/result", exec => { captured.delete(exec.token); });
+}

package/src/extension/dsh/history.ts

@@ -0,0 +1,69 @@
+import { join } from "node:path";
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
+import { AgentFiles } from "../../storage/agent-files.js";
+import { HistoryFiles } from "../../storage/history-files.js";
+import { HistoryService } from "../../services/history/history-service.js";
+import { DshHistory } from "../../integrations/dsh/history.js";
+import { dshHistorySummarizer } from "../../integrations/dsh/history-summary.js";
+import { finalDshAnswer } from "../../integrations/dsh/messages.js";
+
+/** One server-owned organizer per workspace, shared by its parent Sessions. */
+export class DshHistoryWork {
+  readonly service: HistoryService;
+  readonly #parents = new Set<Agent>();
+  #controller: AbortController | undefined;
+  #work: Promise<void> | undefined;
+  #closing: Promise<void> | undefined;
+  constructor(private readonly ctx: Context, root: string) {
+    const agents = new AgentFiles(dshHomePath("pbot", "subagents"), "dsh");
+    this.service = new HistoryService(root, new HistoryFiles(join(root, ".dsh/pbot/history"), "dsh"),
+      new DshHistory(ctx, root, () => agents.list().filter(value => value.workspace === root).map(value => value.agentId)),
+      undefined, new HistoryFiles(join(root, ".pi/pbot/history")));
+  }
+  attach(agent: Agent) { this.#parents.add(agent); return () => { this.#parents.delete(agent); }; }
+  cancel() { this.#controller?.abort(); }
+  schedule(agent: Agent) {
+    if (this.#closing || [...this.#parents].some(parent => parent.status !== "idle" || parent.inbox.nextTurn.length || parent.inbox.nextStep.length)) return;
+    this.cancel();
+    const controller = new AbortController(), selection = agent.model.current(), sessionId = agent.id;
+    this.#controller = controller;
+    const signal = controller.signal;
+    const work = (this.#work ?? Promise.resolve()).catch(() => {}).then(async () => {
+      signal.throwIfAborted();
+      await this.service.refresh({ host: "dsh", sessionId }, signal);
+      signal.throwIfAborted();
+      await this.service.organize(dshHistorySummarizer(this.ctx, selection, sessionId), signal);
+    }).catch(error => { if (!signal.aborted) this.ctx.logger.warn("pbot 历史整理未完成：" + String(error)); });
+    this.#work = work;
+    void work.finally(() => { if (this.#work === work) { this.#work = undefined; this.#controller = undefined; } });
+  }
+  close() {
+    if (this.#closing) return this.#closing;
+    this.cancel();
+    this.#closing = (async () => { await this.#work; await this.service.close(); this.#parents.clear(); })();
+    return this.#closing;
+  }
+}
+
+export function registerDshHistoryEvents(ctx: Context, agent: Agent, work: DshHistoryWork, check: () => void) {
+  let normal = false, final = false;
+  ctx.effect(() => work.attach(agent));
+  ctx.on("session/event", (session, event) => {
+    if (session !== agent.session) return;
+    if (event.type === "turn/start") { normal = false; final = false; }
+    if (event.type === "assistant/message") final = Boolean(finalDshAnswer(event).trim());
+    if (event.type === "agent/inbox/spliced" && event.data.inserted.some(message => message.source.kind === "user")) { normal = false; work.cancel(); }
+    if (event.type === "turn/end") normal = event.data.reason.kind === "completed" && final;
+  });
+  ctx.on("agent/pre-step", async (_payload, next) => { work.cancel(); check(); return next(); });
+  ctx.on("agent/status", ({ agent: changed, status }) => {
+    if (changed !== agent || status !== "idle" || !normal) return;
+    normal = false;
+    if (!agent.inbox.nextTurn.length && !agent.inbox.nextStep.length) {
+      try { check(); } catch (error) { if ((error as Error).name === "AbortError") return; throw error; }
+      work.schedule(agent);
+    }
+  });
+}

package/src/extension/dsh/management.ts

@@ -0,0 +1,108 @@
+import type { Context } from "@deepseek-ai/cordis";
+import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+import type {} from "@deepseek-ai/dsh-typert-registry";
+import { SessionId } from "@deepseek-ai/dsh-session";
+import { extractSessionEventText } from "@deepseek-ai/dsh-session-query";
+import { Type, type Static } from "typebox";
+import { json, type Json } from "../../common/json.js";
+import { requireThat, schema } from "../../common/validation.js";
+import { packageVersion } from "../../common/version.js";
+import { historyInput } from "../../tools/history/contract.js";
+import { executeHistory } from "../../tools/history/actions.js";
+import { pbotReadRemote } from "../../ui/dsh/remote.js";
+import type { DshWorkspaces, DshWorkspace } from "./workspace.js";
+
+const requestSchema = Type.Object({ parentSessionId: Type.String({ minLength: 1 }), input: Type.Optional(Type.Unknown()) }, { additionalProperties: false });
+const expertSchema = Type.Object({ agentId: Type.String({ minLength: 1 }), offset: Type.Optional(Type.Integer({ minimum: 0 })),
+  limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })), seq: Type.Optional(Type.Integer({ minimum: 0 })),
+  textOffset: Type.Optional(Type.Integer({ minimum: 0 })), textLimit: Type.Optional(Type.Integer({ minimum: 2, maximum: 24000 })),
+  format: Type.Optional(Type.Union([Type.Literal("text"), Type.Literal("json")])) }, { additionalProperties: false });
+const teamSchema = Type.Object({ teamId: Type.String({ minLength: 1 }), afterSeq: Type.Optional(Type.Integer({ minimum: 0 })),
+  seq: Type.Optional(Type.Integer({ minimum: 1 })), offset: Type.Optional(Type.Integer({ minimum: 0 })),
+  limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 16000 })) }, { additionalProperties: false });
+const validRequest = schema(requestSchema), validExpert = schema(expertSchema), validTeam = schema(teamSchema);
+
+export function dshStatus(workspaces: DshWorkspaces, workspace: DshWorkspace): Json {
+  workspace.check();
+  const agents = workspace.agents.list(workspace.owner);
+  return json({ host: "dsh", release: packageVersion, workspaceRoot: workspace.root, sessionId: workspace.agent.id,
+    model: workspace.agent.model.current() ?? null, python: workspaces.python.status,
+    controlError: workspace.controlError ?? null, history: workspace.history.status,
+    agents, teams: workspace.teams.list(workspace.owner, agents) });
+}
+
+/** Native Remote owns transport and access checks. These workspace reads do not admit or cancel execution. */
+export class PbotManagement extends TypertRemoteService {
+  constructor(ctx: Context, private readonly workspaces: DshWorkspaces) { super(ctx, "pbotManagement", { namespace: "pbot" }); }
+
+  private async workspace(request: Json, signal: AbortSignal) {
+    signal.throwIfAborted(); requireThat(validRequest(request), "管理查询参数无效。");
+    const args = request as Static<typeof requestSchema>;
+    const agent = this.ctx.agents.get(SessionId(args.parentSessionId));
+    requireThat(agent, "父会话未加载或已关闭，请在原生会话页面重新打开。");
+    const workspace = await this.workspaces.get(agent);
+    signal.throwIfAborted(); workspace.check();
+    return { workspace, input: args.input, signal: AbortSignal.any([signal, workspace.lifetime.signal]) };
+  }
+
+  @Remote
+  async snapshot(request: Json, signal: AbortSignal): Promise<Json> {
+    const { workspace, input } = await this.workspace(request, signal);
+    requireThat(input === undefined, "工作区状态查询不接受额外参数。");
+    return dshStatus(this.workspaces, workspace);
+  }
+
+  @Remote
+  async expert(request: Json, signal: AbortSignal): Promise<Json> {
+    const current = await this.workspace(request, signal), { workspace, input } = current;
+    requireThat(validExpert(input), "专家记录查询参数无效。");
+    const args = input as Static<typeof expertSchema>;
+    const view = workspace.agents.status(args.agentId, workspace.owner);
+    using observation = await this.ctx.sessionQuery.observeSession(SessionId(view.agentId), { projectionMode: "none", signal: current.signal });
+    workspace.check(); current.signal.throwIfAborted();
+    const header = observation.header;
+    requireThat(header.id === view.agentId && header.cwd === view.cwd && header.parentSession === workspace.agent.id &&
+      header.origin === "subagent" && !header.isSeeded, "原生专家记录的身份或归属不匹配。");
+    const events = observation.events;
+    if (args.seq !== undefined) {
+      const event = events.find(value => value.seq === args.seq);
+      requireThat(event, "原生记录位置不存在。");
+      const text = (args.format === "text" ? extractSessionEventText(event) : "") || JSON.stringify(event, null, 2), offset = args.textOffset ?? 0;
+      requireThat(offset <= text.length, "原生记录分页位置超出范围。");
+      let end = Math.min(text.length, offset + (args.textLimit ?? 12000));
+      if (end < text.length && /[\uD800-\uDBFF]/.test(text[end - 1]!)) end--;
+      return json({ agent: view, cursor: observation.cursor, seq: event.seq, offset, text: text.slice(offset, end),
+        totalLength: text.length, nextOffset: end < text.length ? end : null });
+    }
+    const limit = args.limit ?? 30, offset = args.offset ?? Math.max(0, events.length - limit);
+    requireThat(offset <= events.length, "原生记录分页位置超出范围。");
+    return json({ agent: view, header, cursor: observation.cursor, total: events.length, offset,
+      nextOffset: offset + limit < events.length ? offset + limit : null,
+      events: events.slice(offset, offset + limit).map(event => ({ seq: event.seq, type: event.type, time: event.time,
+        ...(event.type === "user/message" ? { source: event.data.source.kind } : {}), preview: extractSessionEventText(event).slice(0, 800) })) });
+  }
+
+  @Remote
+  async team(request: Json, signal: AbortSignal): Promise<Json> {
+    const { workspace, input } = await this.workspace(request, signal);
+    requireThat(validTeam(input), "团队记录查询参数无效。");
+    const args = input as Static<typeof teamSchema>;
+    return json({ team: workspace.teams.status(args.teamId, workspace.owner, workspace.agents.list(workspace.owner)),
+      page: workspace.teams.read(args.teamId, { kind: "user", owner: workspace.owner }, args) });
+  }
+
+  @Remote
+  async history(request: Json, signal: AbortSignal): Promise<Json> {
+    const current = await this.workspace(request, signal), { workspace, input } = current;
+    const result = await executeHistory(workspace.history, historyInput(input), { host: "dsh", sessionId: workspace.agent.id }, current.signal);
+    workspace.check(); current.signal.throwIfAborted(); return json(result);
+  }
+}
+
+declare module "@deepseek-ai/cordis" { interface Context { pbotManagement: PbotManagement } }
+
+export function registerDshManagement(ctx: Context, workspaces: DshWorkspaces) {
+  ctx.typert.register({ package: pbotReadRemote.package, face: "host", schemas: [],
+    model: { services: [], events: [], objects: [] }, invocations: pbotReadRemote.descriptors });
+  return new PbotManagement(ctx, workspaces);
+}

package/src/extension/dsh/workspace.ts

@@ -0,0 +1,206 @@
+import { realpath } from "node:fs/promises";
+import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { Context } from "@deepseek-ai/cordis";
+import type { AgentOwner } from "../../model/agent.js";
+import { DshAgents } from "../../integrations/dsh/dsh-agents.js";
+import { dshResources, dshExpertTools } from "../../integrations/dsh/resources.js";
+import { AgentService } from "../../services/agents/agent-service.js";
+import { TeamService } from "../../services/agents/team-service.js";
+import { registerDshAgentTool } from "../../tools/agents/dsh-tool.js";
+import { registerDshTeamTool, registerDshTeamMessageTool } from "../../tools/teams/dsh-tool.js";
+import { DshAgentRuntime } from "./agent-runtime.js";
+import { DshAgentEvents } from "./agent-events.js";
+import { registerDshFileEvents } from "./files.js";
+import { DshHistoryWork, registerDshHistoryEvents } from "./history.js";
+import type { HistoryService } from "../../services/history/history-service.js";
+import { registerDshHistoryTool } from "../../tools/history/dsh-tool.js";
+import { activatePython } from "../../integrations/python-activation.js";
+import { PythonEnvironmentService } from "../../services/workspace/python-environment-service.js";
+import { requireThat } from "../../common/validation.js";
+
+export const dshDependencies = ["agents", "sessions", "sessionPersistence", "sessionQuery", "llm", "tools", "systemPrompt", "skills", "fs", "attachments", "workingDirectory", "approval"];
+
+export class DshWorkspace {
+  readonly lifetime = new AbortController();
+  readonly host: DshAgents;
+  readonly agents: AgentService;
+  readonly teams: TeamService;
+  readonly history: HistoryService;
+  readonly owner: AgentOwner;
+  readonly #experts = new Map<string, DshAgentRuntime>();
+  #scope: { dispose(): Promise<void> } | undefined;
+  #events: DshAgentEvents | undefined;
+  #closing: Promise<void> | undefined;
+  constructor(readonly ctx: Context, readonly root: string, readonly agent: Agent,
+    readonly python: PythonEnvironmentService, readonly component: AbortSignal,
+    private readonly historyWork: DshHistoryWork, private readonly releaseHistory: () => Promise<void>) {
+    this.history = historyWork.service;
+    this.owner = { sessionId: agent.id, leaf: null, branch: [] };
+    this.host = new DshAgents(ctx, agent, {
+      setup: (d, _directory, generation) => async (agentCtx, child) => {
+        for (const key of ["noExtensions", "noPromptTemplates", "noContextFiles"] as const) requireThat(d.options[key] === undefined, "dsh 不支持宿主选项：" + key);
+        await agentCtx.plugin({ name: "pbot-expert", inject: dshDependencies, apply: async scope => {
+          const runtime = new DshAgentRuntime(scope, child, d, generation, this.agents.files, this.teams,
+            { check: this.check, release: () => this.host.release(d.agentId, generation) });
+          this.#experts.set(d.agentId, runtime);
+          scope.effect(() => () => { if (this.#experts.get(d.agentId) === runtime) this.#experts.delete(d.agentId); });
+          await dshResources(scope, child, root, "general-purpose", () => python.status, runtime.check);
+          const teamTool = dshExpertTools(scope, child, d.options);
+          if (teamTool) registerDshTeamMessageTool(scope, child, this.teams, runtime.actor, runtime.check);
+          registerDshFileEvents(scope, child, root, true, runtime.check);
+          runtime.initialize(teamTool);
+        } });
+        return { commit: this.check };
+      },
+      ready: (child, generation) => {
+        const runtime = this.#experts.get(child.id);
+        requireThat(runtime?.generation === generation, "专家执行组件未就绪。"); runtime.start();
+      },
+      stopping: async (child, generation) => { const runtime = this.#experts.get(child.id); if (runtime?.generation === generation) await runtime.stop(); },
+    }, this.lifetime.signal);
+    this.agents = new AgentService(root, dshHomePath("pbot", "subagents"), this.host);
+    this.teams = new TeamService(root, this.agents.files, this.agents.teamFiles);
+  }
+  check = () => { this.component.throwIfAborted(); this.lifetime.signal.throwIfAborted(); };
+  get controlError() { return this.#events?.error; }
+  async open() {
+    this.check();
+    this.#scope = await this.agent.ctx.plugin({ name: "pbot-coordinator", inject: dshDependencies, apply: async ctx => {
+      await dshResources(ctx, this.agent, this.root, "coordinator", () => this.python.status, this.check);
+      registerDshFileEvents(ctx, this.agent, this.root, false, this.check);
+      registerDshAgentTool(ctx, this.agent, this.agents, this.owner, this.check);
+      registerDshTeamTool(ctx, this.agent, this.teams, this.agents, this.owner, this.check);
+      registerDshTeamMessageTool(ctx, this.agent, this.teams, () => ({ kind: "coordinator", owner: this.owner }), this.check);
+      registerDshHistoryTool(ctx, this.agent, this.history, this.lifetime.signal, this.check);
+      registerDshHistoryEvents(ctx, this.agent, this.historyWork, this.check);
+      this.#events = new DshAgentEvents(ctx, this.agent, this.agents, this.teams, this.owner, this.check);
+      this.#events.start();
+    } });
+    this.check();
+  }
+  expert(id: string) {
+    this.check(); const view = this.agents.status(id, this.owner), runtime = this.#experts.get(id);
+    requireThat(view.owned, "专家不属于当前父会话。");
+    requireThat(view.alive, "专家已停止；需要明确恢复后才能对话。");
+    requireThat(view.state !== "starting", "专家尚未就绪，请等待启动或恢复完成。");
+    requireThat(runtime?.generation === view.generation, "原生专家由其他执行实例持有；当前组件不能接管对话。");
+    return runtime;
+  }
+  close() {
+    if (this.#closing) return this.#closing;
+    this.lifetime.abort();
+    this.#closing = (async () => {
+      const errors: unknown[] = [];
+      try { await this.#events?.close(); } catch (error) { errors.push(error); }
+      try { this.teams.pauseAll(this.owner, "父会话或执行组件关闭"); } catch (error) { errors.push(error); }
+      try { await this.agents.close(this.owner); } catch (error) { errors.push(error); }
+      try { await this.host.close(); } catch (error) { errors.push(error); }
+      this.teams.dispose();
+      try { await this.#scope?.dispose(); } catch (error) { errors.push(error); }
+      try { await this.releaseHistory(); } catch (error) { errors.push(error); }
+      if (errors.length) throw new AggregateError(errors, "dsh 工作区关闭失败；请核对执行资源和控制记录。");
+    })();
+    return this.#closing;
+  }
+}
+
+/** The execution component owns Python; closing one Session must not undo its activation. */
+export class DshWorkspaces {
+  readonly python = new PythonEnvironmentService(process.cwd());
+  readonly #parents = new Map<Agent, Promise<DshWorkspace>>();
+  readonly #parentEffects = new Map<Agent, () => Promise<void>>();
+  readonly #histories = new Map<string, { work: DshHistoryWork; users: number }>();
+  readonly #lifetime = new AbortController();
+  #restorePython: (() => void) | undefined;
+  #preparing: Promise<{ directory: string; python: string }> | undefined;
+  #closing: Promise<void> | undefined;
+  constructor(readonly ctx: Context) {}
+
+  private async history(root: string): Promise<{ work: DshHistoryWork; release(): Promise<void> }> {
+    this.#lifetime.signal.throwIfAborted();
+    let entry = this.#histories.get(root);
+    if (entry && entry.users === 0) {
+      await entry.work.close(); this.#lifetime.signal.throwIfAborted();
+      if (this.#histories.get(root) === entry) this.#histories.delete(root);
+      return this.history(root);
+    }
+    if (!entry) { entry = { work: new DshHistoryWork(this.ctx, root), users: 0 }; this.#histories.set(root, entry); }
+    const owned = entry; owned.users++;
+    let released = false;
+    return { work: owned.work, release: async () => {
+      if (released) return; released = true;
+      if (--owned.users === 0) {
+        try { await owned.work.close(); } finally { if (this.#histories.get(root) === owned) this.#histories.delete(root); }
+      }
+    } };
+  }
+
+  async open(agent: Agent) {
+    this.#lifetime.signal.throwIfAborted();
+    requireThat(this.ctx.agents.roots().includes(agent) && agent.session.header.origin !== "subagent", "专家不拥有协调者管理入口。");
+    const current = this.#parents.get(agent);
+    if (current) return current;
+    const opening = (async () => {
+      const root = await realpath(agent.session.header.cwd ?? process.cwd());
+      this.#lifetime.signal.throwIfAborted();
+      const history = await this.history(root);
+      let workspace: DshWorkspace | undefined;
+      try {
+        workspace = new DshWorkspace(this.ctx, root, agent, this.python, this.#lifetime.signal, history.work, history.release);
+        const owned = workspace;
+        const dispose = agent.ctx.effect(() => async () => {
+          this.#parents.delete(agent); this.#parentEffects.delete(agent); await owned.close();
+        });
+        this.#parentEffects.set(agent, dispose);
+        await workspace.open(); this.#lifetime.signal.throwIfAborted(); return workspace;
+      } catch (error) {
+        try {
+          const dispose = this.#parentEffects.get(agent);
+          if (dispose) await dispose(); else if (workspace) await workspace.close(); else await history.release();
+        } catch (cleanup) { throw new AggregateError([error, cleanup], "dsh 工作区装配与清理均未完成。"); }
+        throw error;
+      }
+    })();
+    this.#parents.set(agent, opening);
+    try { return await opening; }
+    catch (error) { this.#parents.delete(agent); throw error; }
+  }
+
+  async get(agent: Agent) {
+    this.#lifetime.signal.throwIfAborted();
+    requireThat(this.ctx.agents.get(agent.id) === agent, "父会话已关闭。");
+    const workspace = await this.open(agent);
+    workspace.check();
+    return workspace;
+  }
+
+  preparePython() {
+    this.#lifetime.signal.throwIfAborted();
+    if (this.#preparing) return this.#preparing;
+    this.#preparing = (async () => {
+      const result = await this.python.setup(this.#lifetime.signal);
+      this.#lifetime.signal.throwIfAborted();
+      if (!this.#restorePython) this.#restorePython = activatePython(result.directory);
+      return result;
+    })().finally(() => { this.#preparing = undefined; });
+    return this.#preparing;
+  }
+
+  close() {
+    if (this.#closing) return this.#closing;
+    this.#lifetime.abort();
+    this.#closing = (async () => {
+      try {
+        const opened = await Promise.allSettled(this.#parents.values());
+        const closed = await Promise.allSettled(opened.filter(v => v.status === "fulfilled").map(v => v.value.close()));
+        const effects = await Promise.allSettled([...this.#parentEffects.values()].map(dispose => dispose()));
+        const histories = await Promise.allSettled([...this.#histories.values()].map(value => value.work.close()));
+        await this.python.close();
+        const errors = [...new Set([...closed, ...effects, ...histories].flatMap(value => value.status === "rejected" ? [value.reason] : []))];
+        if (errors.length) throw new AggregateError(errors, "部分 dsh 工作区未能完成关闭。");
+      } finally { this.#parents.clear(); this.#parentEffects.clear(); this.#histories.clear(); this.#restorePython?.(); this.#restorePython = undefined; }
+    })();
+    return this.#closing;
+  }
+}

package/src/extension/events.ts

@@ -4,7 +4,7 @@ import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { resourceRoot } from "../common/paths.js";
-import { agentText } from "../integrations/pi/agent-resources.js";
+import { agentText } from "../integrations/agent-resources.js";
 import type { Confirmations } from "../ui/confirmation.js";
 import type { Lifecycle } from "./lifecycle.js";
 
@@ -12,12 +12,14 @@ export function registerEvents(pi: ExtensionAPI, lifecycle: Lifecycle, confirmat
   pi.on("session_start", async (_event, ctx) => {
     try {
       await lifecycle.open(ctx.cwd);
-      ctx.ui.notify("正在准备共享 Python 环境；首次安装可能需要数分钟。", "info");
+      if (ctx.mode === "tui") ctx.ui.setStatus("pbot-python", "Python 准备中");
+      else ctx.ui.notify("正在准备共享 Python 环境；首次安装可能需要数分钟。", "info");
       try { await lifecycle.get().preparePython(); }
       catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        if (ctx.hasUI) ctx.ui.notify(message, "warning"); else console.error(message);
-      }
+        if (ctx.mode === "tui") ctx.ui.notify("Python 未就绪；/pbot status 查看详情。", "warning");
+        else if (ctx.hasUI) ctx.ui.notify(message, "warning"); else console.error(message);
+      } finally { if (ctx.mode === "tui") ctx.ui.setStatus("pbot-python", undefined); }
     } catch (error) {
       if (ctx.hasUI) ctx.ui.notify(error instanceof Error ? error.message : "pbot 启动失败。", "error");
       else throw error;

package/src/extension/history.ts

@@ -1,6 +1,8 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { historyLocation, historySummarizer } from "../integrations/pi/history.js";
 import type { Lifecycle, WorkspaceInstance } from "./lifecycle.js";
+import { readPage } from "../ui/pi/reader.js";
+import { choose } from "../ui/pi/menu.js";
 
 export function registerHistoryEvents(pi: ExtensionAPI, lifecycle: Lifecycle) {
   pi.on("session_start", async (_event, ctx) => {
@@ -25,8 +27,8 @@ export function registerHistoryEvents(pi: ExtensionAPI, lifecycle: Lifecycle) {
   });
 }
 
-const label = (node: { kind: string; from: string; ready: boolean; preview: string }) =>
-  `${node.from.slice(0, 16)} · ${node.kind === "session" ? "会话" : node.kind === "summary" ? "摘要" : "问答"}${node.ready ? "" : "（待整理）"} · ${node.preview}`;
+const label = (node: { host: string; kind: string; from: string; ready: boolean; preview: string }) =>
+  `${node.host} · ${node.from.slice(0, 10)} · ${node.kind === "session" ? "会话" : node.kind === "summary" ? "摘要" : "问答"}${node.ready ? "" : "（待整理）"} · ${node.preview.replace(/\s+/g, " ").slice(0, 48)}`;
 
 export async function showHistory(instance: WorkspaceInstance, ctx: ExtensionCommandContext, query: string) {
   await instance.history.refresh(historyLocation(ctx), instance.signal(ctx.signal));
@@ -37,35 +39,36 @@ export async function showHistory(instance: WorkspaceInstance, ctx: ExtensionCom
   for (;;) {
     instance.check();
     const result = service.search({ query, offset });
-    const choices = result.matches.map((node, index) => `${index + 1}. ${label(node)} · ${node.snippet.replace(/\s+/g, " ").slice(0, 80)}`);
-    const more = "下一页", search = "重新搜索", back = "返回";
-    const selected = await ctx.ui.select(`历史：${query || "最近会话"}（${result.total}）`, [...choices, ...(result.nextOffset === null ? [] : [more]), search, back]);
+    const choices = result.matches.map((node, index) => `${index + 1}. ${label(node)}`);
+    const more = "下一页", previous = "上一页", search = "搜索", back = "返回";
+    const selected = await choose(ctx, `历史 · ${query || "最近会话"} · ${result.total} 项`, [...choices, ...(offset ? [previous] : []), ...(result.nextOffset === null ? [] : [more]), search, back]);
     if (!selected || selected === back) return;
     if (selected === more) { offset = result.nextOffset!; continue; }
+    if (selected === previous) { offset = Math.max(0, offset - 20); continue; }
     if (selected === search) {
       const value = await ctx.ui.input("全文搜索（留空列出会话）", query);
       if (value !== undefined) { query = value; offset = 0; }
       continue;
     }
-    let id = result.matches[choices.indexOf(selected)]!.id, textOffset = 0, childrenOffset = 0;
+    let current = result.matches[choices.indexOf(selected)]!, id = current.id, source = current.host, textOffset = 0, childrenOffset = 0;
     for (;;) {
       instance.check();
-      const node = service.read(id, textOffset, 12000, childrenOffset);
-      const body = "查看正文", nextText = "后续正文", nextChildren = "后续子节点", first = "回到本节点开头";
+      const node = service.read(id, textOffset, 12000, childrenOffset, source);
+      const body = "正文", nextText = "后续正文", nextChildren = "更多下级", first = "回到开头";
       const links = [...node.parents.map(parent => ({ ...parent, direction: "↑" })), ...node.children.map(child => ({ ...child, direction: "↓" }))];
       const names = links.map((value, index) => `${index + 1}. ${value.direction} ${label(value)}`);
-      const action = await ctx.ui.select(label(node), [body, ...names, ...(node.nextOffset === null ? [] : [nextText]),
+      const action = await choose(ctx, label(node), [body, ...names, ...(node.nextOffset === null ? [] : [nextText]),
         ...(node.nextChildrenOffset === null ? [] : [nextChildren]), ...(textOffset || childrenOffset ? [first] : []), back]);
       if (!action || action === back) break;
       if (action === body || action === nextText) {
         if (action === nextText) textOffset = node.nextOffset!;
-        const page = service.read(id, textOffset, 12000, childrenOffset);
-        await ctx.ui.editor(`历史正文 ${textOffset}/${page.totalLength}（修改不保存）`, page.text || "摘要尚未生成，可以展开下层节点。");
+        const page = service.read(id, textOffset, 12000, childrenOffset, source);
+        await readPage(ctx, `历史正文 · ${textOffset + 1}–${textOffset + page.text.length}/${page.totalLength}`, page.text || "摘要待整理，请展开下级记录。");
         continue;
       }
       if (action === nextChildren) { childrenOffset = node.nextChildrenOffset!; continue; }
       if (action === first) { textOffset = 0; childrenOffset = 0; continue; }
-      id = links[names.indexOf(action)]!.id; textOffset = 0; childrenOffset = 0;
+      const link = links[names.indexOf(action)]!; id = link.id; source = link.host; textOffset = 0; childrenOffset = 0;
     }
   }
 }