personal-bot 0.0.0-stage → 0.1.1

package/resources/skills/research-evidence/references/hypothesis-checks.md

@@ -0,0 +1,33 @@
+# 关键假设验证
+
+用于探索性研究的选题、实验安排和受阻后的方向判断，尽早取得能改变决策的证据。
+
+## 找出决定方向的假设
+
+从目标和已有证据识别：哪些条件必须成立，结论才有意义；哪项不成立会改变方案；哪些检验依赖其他条件先成立。
+
+区分研究假设与方法前提。例如，策略是否具有样本外效果是研究假设；数据是否覆盖所需时期、能否按实际可知时间构造输入，是方法前提。
+
+对影响决策的假设，梳理现有支持与反对证据、尚不确定的条件、失败后果、可用检验及其成本。
+
+## 选择最有用的下一次检验
+
+优先选择不同结果会改变后续决策、能较早取得证据且成本适当的检验。必要时先核实数据与方法前提，再投入更大规模的实验。
+
+最小检验可以使用已有数据、较小样本或较简单的方法，但要说明它能够排除什么、仍不能证明什么。
+
+执行前明确与本次判断有关的内容：
+
+- 要区分的假设或替代解释，以及可观测结果。
+- 所需数据与资源、方法、比较基准和主要限制。
+- 哪些结果支持继续，哪些要求修改或停止，哪些仍无法区分假设。
+
+判据来自目标、领域依据或用户约束。看到结果后修改判据时，记录修改原因，并区分探索所得的解释与按原判据得到的结果。
+
+## 根据结果调整
+
+先判断检验是否有效执行。数据缺失、程序失败或方法不适用不等于研究假设被否定；代理指标改善也不自动证明最终目标达成。
+
+有效结果削弱关键假设时，比较继续排查、修改方法、缩小问题或停止该方向的价值。结果仍不确定时，根据下一项证据区分解释的能力决定是否继续。
+
+保留支撑方向判断的假设、判据、实际观测和产物引用。复用结果时保留检验条件与适用范围。

package/resources/templates/workspace-agents.md

@@ -0,0 +1,13 @@
+# 工作区资料入口
+
+## 目录树
+
+```text
+./
+├── areas/          # 长期目标、约束、建议、决策与复盘
+├── projects/       # 任务结论、必要数据与复现代码
+├── knowledge/      # 可复用知识、方法与参考资料
+├── providers/      # 能力提供方导航与手册
+├── scratch/        # 临时文件、运行环境与计算产物
+└── agents/         # coordinator.md 与 general-purpose.md 的职责补充
+```

package/scripts/README.md

@@ -0,0 +1,13 @@
+# 维护脚本
+
+## Python 环境准备
+
+`setup-python.py` 创建当前用户的共享 venv，按 requirements.lock 安装依赖。Personal Bot 加载后自动调用；也可独立执行，或通过 /pbot python setup 重试。
+
+脚本不接受解释器路径，不修改工作区资料或历史记录。路径、激活和失败处理见 [Python 说明](../python/README.md)。
+
+## 构建清理
+
+`clean-dist.mjs` 由 npm run build 调用，仅清理仓库内生成的 dist/，供 TypeScript 重新编译测试导入。
+
+本包不提供工作区升级命令或历史转换脚本。插件安装和更新由 Pi 原生包管理或用户维护的源码目录负责。

package/scripts/setup-python.py

@@ -0,0 +1,144 @@
+"""Create or verify the current user's shared pbot virtual environment."""
+
+import argparse
+import fcntl
+import json
+import os
+from pathlib import Path
+import re
+import stat
+import subprocess
+import sys
+import tempfile
+import venv
+
+REQUIREMENTS = Path(__file__).resolve().parent.parent / "python" / "requirements.lock"
+INSPECT = """
+import importlib.metadata as m, json, sys
+print(json.dumps({
+    "prefix": sys.prefix, "basePrefix": sys.base_prefix,
+    "version": list(sys.version_info[:3]),
+    "packages": {d.metadata["Name"]: d.version for d in m.distributions()}
+}))
+"""
+
+
+def directory():
+    if sys.platform == "darwin":
+        return Path.home() / "Library/Application Support/pbot/python/.venv"
+    data = os.environ.get("XDG_DATA_HOME", "")
+    root = Path(data) if os.path.isabs(data) else Path.home() / ".local/share"
+    return root / "pbot/python/.venv"
+
+
+def normalize(name):
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def locked_packages():
+    result = {}
+    for line in REQUIREMENTS.read_text().splitlines():
+        if not line.strip() or line.startswith("#"):
+            continue
+        match = re.fullmatch(r"([A-Za-z0-9_.-]+)==([A-Za-z0-9_.+!-]+)", line)
+        if not match:
+            raise ValueError("requirements.lock 必须逐行使用 name==version。")
+        name, version = match.groups()
+        key = normalize(name)
+        if key in result:
+            raise ValueError("requirements.lock 存在重复依赖。")
+        result[key] = version
+    if not result:
+        raise ValueError("requirements.lock 不能为空。")
+    return result
+
+
+def inspect_environment(target):
+    if target.is_symlink():
+        raise ValueError("共享环境目录不能是符号链接。")
+    if not target.exists():
+        return None
+    config = target / "pyvenv.cfg"
+    if not target.is_dir() or not config.is_file() or config.is_symlink():
+        raise ValueError("共享环境位置已被非 venv 数据占用；不会覆盖或删除。")
+    if re.search(r"include-system-site-packages\s*=\s*true", config.read_text(), re.I):
+        raise ValueError("共享 venv 不能继承系统 site-packages。")
+    info = json.loads(subprocess.check_output([str(target / "bin/python"), "-I", "-B", "-c", INSPECT], text=True))
+    if Path(info["prefix"]).resolve() != target.resolve() or info["prefix"] == info["basePrefix"]:
+        raise ValueError("解释器不属于共享 venv；不会修改其他 Python 环境。")
+    if info["version"][:2] < [3, 11]:
+        raise ValueError("共享环境需要 Python 3.11+；不会自动替换其基础解释器。")
+    info["packages"] = {normalize(name): version for name, version in info["packages"].items()}
+    return info
+
+
+def plan(target):
+    required = locked_packages()
+    current = inspect_environment(target)
+    installed = (current or {}).get("packages", {})
+    return {
+        "directory": str(target), "python": str(target / "bin/python"),
+        "current": current, "required": required,
+        "changes": [{"package": name, "from": installed.get(name), "to": version}
+                    for name, version in required.items() if installed.get(name) != version],
+    }
+
+
+def setup(target):
+    target.parent.mkdir(parents=True, exist_ok=True)
+    # Never unlink this file: concurrent installers must lock the same inode.
+    fd = os.open(str(target) + ".lock", os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW, 0o600)
+    try:
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            raise ValueError("共享环境锁必须是普通文件。")
+        # Concurrent startups wait, then inspect again rather than apply stale plans.
+        fcntl.flock(fd, fcntl.LOCK_EX)
+        actual = plan(target)
+        if actual["current"] is None:
+            venv.EnvBuilder(with_pip=True).create(target)
+        python = str(target / "bin/python")
+
+        def run(args):
+            subprocess.run([python, "-I", "-B", *args], check=True, pass_fds=(fd,),
+                           stdout=sys.stderr, env={**os.environ, "PIP_CONFIG_FILE": os.devnull})
+
+        current = inspect_environment(target)
+        if "pip" not in current["packages"]:
+            run(["-m", "ensurepip"])
+        pip = ["-m", "pip", "--isolated", "--disable-pip-version-check"]
+        if actual["changes"]:
+            with tempfile.TemporaryDirectory(prefix="pbot-python-") as temp:
+                locked = Path(temp) / "requirements.txt"
+                locked.write_text("".join(name + "==" + version + "\n" for name, version in actual["required"].items()))
+                run([*pip, "download", "--only-binary=:all:", "--no-deps", "-r", str(locked), "--dest", temp])
+                run([*pip, "install", "--no-index", "--find-links", temp, "--no-deps", "-r", str(locked)])
+        run([*pip, "check"])
+        verified = inspect_environment(target)
+        if any(verified["packages"].get(name) != version for name, version in actual["required"].items()):
+            raise RuntimeError("安装后版本检查未通过。")
+        run(["-c", "import matplotlib; matplotlib.use('Agg'); "
+             "import numpy, pandas, talib, backtesting, scipy, statsmodels.api, "
+             "matplotlib.pyplot, sklearn, pyarrow, openpyxl, seaborn; "
+             "assert talib.SMA(numpy.arange(1., 6.), 3)[-1] == 4."])
+        return {"directory": str(target), "python": python, "packages": verified["packages"]}
+    finally:
+        os.close(fd)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--check", action="store_true", help="只检查共享环境，不创建或安装")
+    args = parser.parse_args()
+    if sys.platform not in ("linux", "darwin") or sys.version_info < (3, 11):
+        raise RuntimeError("需要 Linux/macOS 和 Python 3.11+。")
+    target = directory()
+    print(json.dumps(plan(target) if args.check else setup(target), ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except (Exception, KeyboardInterrupt) as error:
+        print(str(error), file=sys.stderr)
+        print("共享 Python 环境未就绪。请检查 Python 3.11+、venv/ensurepip、网络、安装权限和 wheel；修复后执行 /pbot python setup 或重启。不会删除现有环境、改用系统环境安装或编译 C 库。", file=sys.stderr)
+        sys.exit(1)

package/src/common/files.ts

@@ -0,0 +1,25 @@
+import { open, realpath, rename, unlink, link } from "node:fs/promises";
+import { join, dirname, basename } from "node:path";
+import { randomUUID } from "node:crypto";
+import { requireThat } from "./validation.js";
+
+export async function atomicFile(path: string, content: string, exclusive = false) {
+  const temp = path + "." + randomUUID();
+  const handle = await open(temp, "wx", 0o600);
+  try { await handle.writeFile(content); await handle.sync(); }
+  finally { await handle.close(); }
+  try {
+    if (exclusive) await link(temp, path);
+    else await rename(temp, path);
+    const directory = await open(dirname(path), "r");
+    try { await directory.sync(); } finally { await directory.close(); }
+  } finally { await unlink(temp).catch(error => { if (error.code !== "ENOENT") throw error; }); }
+}
+export async function mutationTarget(path: string): Promise<string> {
+  try { return await realpath(path); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    const parent = dirname(path); requireThat(parent !== path, "无法定位目标路径。");
+    return join(await mutationTarget(parent), basename(path));
+  }
+}

package/src/common/json.ts

@@ -0,0 +1,14 @@
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+export function object(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function canonical(value: unknown): string {
+  if (value === null || typeof value === "boolean" || typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" && Number.isFinite(value)) return JSON.stringify(value);
+  if (Array.isArray(value)) return "[" + value.map(canonical).join(",") + "]";
+  if (object(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)) {
+    return "{" + Object.keys(value).sort().map(key => JSON.stringify(key) + ":" + canonical(value[key])).join(",") + "}";
+  }
+  throw new Error("需要有限、可序列化的 JSON 值。");
+}
+export function json(value: unknown): Json { return JSON.parse(canonical(value)) as Json; }

package/src/common/paths.ts

@@ -0,0 +1,3 @@
+import { fileURLToPath } from "node:url";
+
+export const resourceRoot = fileURLToPath(new URL("../../resources/", import.meta.url));

package/src/common/validation.ts

@@ -0,0 +1,14 @@
+import { Ajv } from "ajv";
+import addFormats from "ajv-formats";
+import type { ValidateFunction } from "ajv";
+import { object } from "./json.js";
+
+export function schema(value: unknown): ValidateFunction {
+  if (!object(value)) throw new Error("需要对象形式的 JSON Schema。");
+  const ajv = new Ajv({ strict: false, allErrors: false, validateFormats: true, coerceTypes: false, useDefaults: false, removeAdditional: false });
+  addFormats.default(ajv);
+  return ajv.compile(value);
+}
+export function requireThat(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}

package/src/common/version.ts

@@ -0,0 +1,15 @@
+import { readFileSync } from "node:fs";
+import { object } from "./json.js";
+import { requireThat } from "./validation.js";
+
+/** Before 1.0, the minor release defines compatibility; afterwards, the major does. */
+export function releaseLine(version: string): string {
+  const parts = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.exec(version);
+  requireThat(parts, "pbot 发布版本必须使用 MAJOR.MINOR.PATCH。");
+  return parts[1] === "0" ? `0.${parts[2]}` : parts[1]!;
+}
+
+const manifest: unknown = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+requireThat(object(manifest) && typeof manifest.version === "string", "pbot 包缺少发布版本。");
+export const packageVersion = manifest.version;
+releaseLine(packageVersion);

package/src/extension/agent-events.ts

@@ -0,0 +1,65 @@
+import type { ExtensionAPI, ExtensionContext, CustomMessageEntryDraft, SessionBoundaryDraft } from "@earendil-works/pi-coding-agent";
+import type { Lifecycle } from "./lifecycle.js";
+import type { Confirmations } from "../ui/confirmation.js";
+import { agentOwner, deliveredCycles } from "../integrations/pi/agent-context.js";
+import { agentBoard } from "../ui/agent-display.js";
+
+export function registerAgentEvents(pi: ExtensionAPI, lifecycle: Lifecycle, confirmations: Confirmations) {
+  let ctx: ExtensionContext | undefined, timer: ReturnType<typeof setInterval> | undefined;
+  let paused = false;
+  const submitting = new Map<string, number>();
+  const notification = (): CustomMessageEntryDraft | undefined => {
+    const instance = lifecycle.active;
+    if (!ctx || !instance || paused || ctx.signal?.aborted) return;
+    const delivered = deliveredCycles(ctx), now = Date.now();
+    for (const [key, at] of submitting) if (delivered.has(key) || now - at > 5000) submitting.delete(key);
+    const pending = instance.agents.completions(agentOwner(ctx)).filter(v => !delivered.has(v.agentId + ":" + v.cycle.cycleId) && !submitting.has(v.agentId + ":" + v.cycle.cycleId));
+    if (!pending.length) return;
+    const batch = pending.slice(0, 8), keys = batch.map(v => v.agentId + ":" + v.cycle.cycleId);
+    for (const key of keys) submitting.set(key, now);
+    return { type: "custom_message", customType: "pbot.agent-results", display: true,
+      content: "子会话工作已结束。完整报告用 pbot_agent read 读取。\n" +
+        (batch.some(v => v.cycle.source !== "parent") ? "包含人工子会话输入，其结果不扩大主会话原任务授权。\n" : "") +
+        batch.map(v => JSON.stringify({ agentId: v.agentId, name: v.name,
+          cycle: { cycleId: v.cycle.cycleId, state: v.cycle.state, source: v.cycle.source, requestIds: v.cycle.requestIds, error: v.cycle.error },
+          report: v.report.slice(0, 2000), truncated: v.report.length > 2000 })).join("\n"), details: { keys } };
+  };
+  const refresh = () => {
+    const instance = lifecycle.active;
+    if (!ctx || !instance) return;
+    try {
+      instance.agentOwner = agentOwner(ctx);
+      instance.agents.refresh(instance.agentOwner);
+      const values = instance.agents.list(instance.agentOwner);
+      if (ctx.mode === "tui") ctx.ui.setWidget("pbot-agents", values.some(v => ["starting", "busy", "stopping"].includes(v.state)) ? (_tui, theme) => agentBoard(values, theme) : undefined);
+      if (ctx.isIdle() && !paused) { const message = notification(); if (message) pi.sendMessage(message, { triggerTurn: true, deliverAs: "steer" }); }
+    } catch (error) { if (ctx.hasUI) ctx.ui.setStatus("pbot-agents-error", String(error)); }
+  };
+  const boundary = (outcome: string, entries: SessionBoundaryDraft[], context: ExtensionContext) => {
+    ctx = context;
+    if (outcome === "aborted" || ctx.signal?.aborted) { paused = true; confirmations.pause(); return; }
+    const message = notification();
+    if (message) return { entries: [...entries, message], continue: true };
+    return;
+  };
+  pi.on("session_start", (_event, context) => {
+    ctx = context; paused = false; confirmations.resume(); submitting.clear();
+    if (timer) clearInterval(timer);
+    if (lifecycle.active) { lifecycle.active.agentOwner = agentOwner(ctx); timer = setInterval(refresh, 1000); timer.unref(); }
+    refresh();
+  });
+  pi.on("input", (_event, context) => { ctx = context; paused = false; confirmations.resume(); });
+  pi.on("before_agent_start", (_event, context) => { ctx = context; });
+  pi.on("session_tree", (_event, context) => { ctx = context; submitting.clear(); refresh(); });
+  pi.on("turn_end", (event, context) => boundary(event.outcome, event.entries, context));
+  pi.on("agent_before_settle", (event, context) => boundary(event.outcome, event.entries, context));
+  pi.on("agent_settled", (event, context) => {
+    ctx = context; if (event.aborted) { paused = true; confirmations.pause(); }
+  });
+  pi.on("tool_result", event => {
+    if (event.toolName !== "pbot_agent") return;
+    const keys = (event.details as { agentReadKeys?: string[] } | undefined)?.agentReadKeys;
+    if (keys?.length) pi.appendEntry("pbot.agent-read", { keys, toolCallId: event.parentToolCallId ?? event.toolCallId });
+  });
+  pi.on("session_shutdown", () => { if (timer) clearInterval(timer); timer = undefined; submitting.clear(); ctx = undefined; });
+}

package/src/extension/agents-command.ts

@@ -0,0 +1,49 @@
+import { spawn } from "node:child_process";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Text, type TUI } from "@earendil-works/pi-tui";
+import type { WorkspaceInstance } from "./lifecycle.js";
+import { agentOwner } from "../integrations/pi/agent-context.js";
+import { tmuxName } from "../integrations/pi/pi-agents.js";
+import { agentSummary } from "../ui/agent-display.js";
+import type { Confirmations } from "../ui/confirmation.js";
+
+export async function showAgents(_pi: ExtensionAPI, instance: WorkspaceInstance, ctx: ExtensionCommandContext, confirmations: Confirmations) {
+  instance.check();
+  const owner = agentOwner(ctx), values = instance.agents.list(owner);
+  if (ctx.mode !== "tui") { ctx.ui.notify(JSON.stringify(values), "info"); return; }
+  if (!values.length) { ctx.ui.notify("没有子会话；用 pbot_agent start 创建。", "info"); return; }
+  if (confirmations.presenting) { ctx.ui.notify("请先处理主会话批准。", "info"); return; }
+  const options = values.map(v => agentSummary(v) + (v.owned ? "" : " · 其他分支"));
+  const selected = await ctx.ui.select("pbot 子会话", options);
+  const value = values[options.indexOf(selected ?? "")]; if (!value) return;
+  if (!value.owned) { ctx.ui.notify("请返回所属分支操作。", "info"); return; }
+  const action = await ctx.ui.select(value.name, ["进入 TUI", "阅读报告", "补充要求", "重命名", "停止", "恢复并继续"]);
+  if (action === "停止") { instance.agents.stop(value.agentId, owner); return; }
+  if (action === "重命名") { const name = await ctx.ui.input("名称"); if (name?.trim()) instance.agents.rename(value.agentId, name.trim(), owner); return; }
+  if (action === "补充要求" || action === "恢复并继续") {
+    const message = await ctx.ui.editor("任务或补充要求");
+    if (message?.trim()) {
+      if (action === "补充要求") instance.agents.send(value.agentId, message, "steer", owner);
+      else instance.agents.resume(value.agentId, message, owner);
+    }
+    return;
+  }
+  if (action === "阅读报告") {
+    const page = instance.agents.read(value.agentId, owner);
+    await ctx.ui.editor("子会话报告（查看不领取通知）", page.report || page.error || page.state); return;
+  }
+  if (action !== "进入 TUI") return;
+  if (!instance.agents.host.alive(value.agentId)) { ctx.ui.notify("子会话已停止，请携新要求恢复。", "info"); return; }
+  let tui: TUI | undefined;
+  await ctx.ui.custom<void>((terminal, _theme, _keys, done) => { tui = terminal; queueMicrotask(() => done()); return new Text("", 0, 0); });
+  if (!tui) return;
+  const terminal = tui;
+  terminal.stop();
+  try {
+    const code = await new Promise<number | null>(resolve => {
+      const child = spawn("tmux", [process.env.TMUX ? "switch-client" : "attach-session", "-t", "=" + tmuxName(value.agentId)], { stdio: "inherit" });
+      child.on("error", () => resolve(null)); child.on("close", resolve);
+    });
+    if (code !== 0) ctx.ui.notify("无法进入子会话。", "error");
+  } finally { terminal.start(); terminal.requestRender(true); }
+}

package/src/extension/command.ts

@@ -0,0 +1,43 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { packageVersion } from "../common/version.js";
+import { prepareWorkspace } from "../services/workspace/workspace-preparation.js";
+import type { Confirmations } from "../ui/confirmation.js";
+import type { Lifecycle } from "./lifecycle.js";
+import { showAgents } from "./agents-command.js";
+
+export function registerCommand(pi: ExtensionAPI, lifecycle: Lifecycle, confirmations: Confirmations) {
+  pi.registerCommand("pbot", {
+    description: "工作区：init、status、agents、python setup",
+    getArgumentCompletions: prefix => {
+      if (/\s/.test(prefix)) return null;
+      return ["init", "status", "agents", "python"]
+        .filter(command => command.startsWith(prefix))
+        .map(command => ({ value: command, label: command }));
+    },
+    handler: async (args, ctx) => {
+      const [, command, argument = ""] = args.trim().match(/^(\S+)(?:\s+([\s\S]*))?$/) ?? [];
+      confirmations.resume();
+      if (command === "init" && !argument) {
+        await ctx.waitForIdle();
+        const instance = lifecycle.get();
+        await prepareWorkspace(instance.root);
+        ctx.ui.notify("资料目录已准备；已有 AGENTS.md 保持不变。", "info");
+        return;
+      }
+      if (command === "status" && !argument) {
+        const instance = lifecycle.get();
+        ctx.ui.notify(JSON.stringify({ workspaceRoot: instance.root, release: packageVersion, python: instance.pythonEnvironment.status }, null, 2), "info"); return;
+      }
+      if (command === "agents") { await showAgents(pi, lifecycle.get(), ctx, confirmations); return; }
+      if (command === "python" && argument === "setup") {
+        const instance = lifecycle.get(), cancel = instance.signal(ctx.signal);
+        await ctx.waitForIdle();
+        ctx.ui.notify("正在准备共享 Python 环境；安装可能需要数分钟。", "info");
+        const result = await instance.preparePython(cancel);
+        ctx.ui.notify(JSON.stringify(result, null, 2), "info");
+        return;
+      }
+      ctx.ui.notify("用法：/pbot init | status | agents | python setup", "info");
+    },
+  });
+}

package/src/extension/events.ts

@@ -0,0 +1,62 @@
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+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 type { Confirmations } from "../ui/confirmation.js";
+import type { Lifecycle } from "./lifecycle.js";
+
+export function registerEvents(pi: ExtensionAPI, lifecycle: Lifecycle, confirmations: Confirmations) {
+  pi.on("session_start", async (_event, ctx) => {
+    try {
+      await lifecycle.open(ctx.cwd);
+      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);
+      }
+    } catch (error) {
+      if (ctx.hasUI) ctx.ui.notify(error instanceof Error ? error.message : "pbot 启动失败。", "error");
+      else throw error;
+    }
+  });
+  pi.on("resources_discover", () => lifecycle.active ? { skillPaths: [join(resourceRoot, "skills")] } : {});
+  pi.on("before_agent_start", async (event, ctx) => {
+    const instance = lifecycle.active;
+    if (!instance) return;
+    instance.cancelWork();
+    const role = await agentText("coordinator", instance.root);
+    const workspace = await readFile(join(resourceRoot, "prompts/workspace.md"), "utf8");
+    instance.check();
+    event.systemPromptOptions.sections.pbot_workspace = workspace;
+    event.systemPromptOptions.sections.pbot_environment = JSON.stringify({
+      workspaceRoot: instance.root, cwd: ctx.cwd, resourceRoot, python: instance.pythonEnvironment.status,
+    });
+    event.systemPromptOptions.sections.pbot = role;
+  });
+  pi.on("input", () => { lifecycle.active?.cancelWork(); });
+  pi.on("agent_end", () => { lifecycle.active?.cancelWork(); });
+  pi.on("session_before_switch", () => { lifecycle.active?.cancelWork(); });
+  pi.on("session_before_fork", () => { lifecycle.active?.cancelWork(); });
+  pi.on("session_before_tree", () => { lifecycle.active?.cancelWork(); });
+  pi.on("session_shutdown", event => lifecycle.close(event.reason === "reload"));
+  pi.on("tool_call", async (event, ctx) => {
+    const instance = lifecycle.active;
+    if (["write", "edit"].includes(event.toolName) && "path" in event.input && typeof event.input.path === "string") {
+      const path = event.input.path.replace(/^@/, "").replace(/[\u00a0\u2000-\u200a\u202f\u205f\u3000]/g, " ");
+      const expanded = /^file:\/\//.test(path) ? fileURLToPath(path)
+        : path === "~" ? homedir() : path.startsWith("~/") ? join(homedir(), path.slice(2)) : path;
+      const target = resolve(ctx.cwd, expanded);
+      if (!instance) return;
+      const cancel = instance.signal(ctx.signal);
+      try {
+        await instance.authorizeFile(target, event.input,
+          value => confirmations.ask(ctx, "确认修改工作区外文件", value, cancel), cancel);
+      } catch (error) { return { block: true, reason: error instanceof Error ? error.message : String(error) }; }
+    }
+    return;
+  });
+}

package/src/extension/lifecycle.ts

@@ -0,0 +1,77 @@
+import { realpath } from "node:fs/promises";
+import { activatePython } from "../integrations/python-activation.js";
+import { requireThat } from "../common/validation.js";
+import { authorizeMutation } from "../services/workspace/workspace-files.js";
+import type { AgentOwner } from "../model/agent.js";
+import type { PythonEnvironmentService } from "../services/workspace/python-environment-service.js";
+import type { AgentService } from "../services/agents/agent-service.js";
+import type { CallAccess } from "../tools/access.js";
+
+export class WorkspaceInstance implements CallAccess {
+  readonly #controller = new AbortController();
+  #work = new AbortController();
+  #closing: Promise<void> | undefined;
+  #restorePython: (() => void) | undefined;
+  constructor(readonly root: string, readonly pythonEnvironment: PythonEnvironmentService, readonly agents: AgentService) {}
+  async preparePython(signal?: AbortSignal) {
+    this.check();
+    this.#restorePython?.();
+    this.#restorePython = undefined;
+    const result = await this.pythonEnvironment.setup(signal);
+    this.check();
+    this.#restorePython ??= activatePython(result.directory);
+    return result;
+  }
+  check() {
+    requireThat(!this.#controller.signal.aborted, "pbot 工作区实例已关闭。");
+  }
+  signal(signal?: AbortSignal) {
+    this.check();
+    return AbortSignal.any([this.#controller.signal, this.#work.signal, ...(signal ? [signal] : [])]);
+  }
+  async authorizeFile(path: string, change: unknown, confirm: (value: unknown) => Promise<boolean>, signal: AbortSignal) {
+    this.check();
+    await authorizeMutation(this.root, path, change, confirm, signal);
+    this.check();
+  }
+  agentOwner: AgentOwner | undefined;
+  cancelWork() {
+    this.#work.abort();
+    this.#work = new AbortController();
+  }
+  close(preserveAgents = false): Promise<void> {
+    if (this.#closing) return this.#closing;
+    this.#controller.abort();
+    this.#work.abort();
+    this.#closing = (async () => {
+      try {
+        const results = await Promise.allSettled([this.agents.close(this.agentOwner, preserveAgents), this.pythonEnvironment.close()]);
+        const errors = results.filter(result => result.status === "rejected").map(result => result.reason);
+        if (errors.length) throw new AggregateError(errors, "工作区关闭失败。");
+      } finally { this.#restorePython?.(); this.#restorePython = undefined; }
+    })();
+    return this.#closing;
+  }
+}
+export class Lifecycle {
+  #active: WorkspaceInstance | undefined;
+  constructor(private readonly create: (root: string) => WorkspaceInstance,
+    private readonly register: (instance: WorkspaceInstance) => void, private readonly hide: () => void) {}
+  get active() { return this.#active; }
+  get() {
+    requireThat(this.#active, "pbot 工作区实例不可用。");
+    this.#active.check(); return this.#active;
+  }
+  async open(root: string) {
+    await this.close();
+    const instance = this.create(await realpath(root));
+    this.#active = instance;
+    try { this.register(instance); }
+    catch (error) { await this.close(); throw error; }
+  }
+  async close(preserveAgents = false) {
+    const old = this.#active;
+    this.#active = undefined;
+    try { await old?.close(preserveAgents); } finally { this.hide(); }
+  }
+}