pi-web-ui 0.94.1 → 0.95.0

package/dist/server/tool-manager.js

@@ -34,6 +34,7 @@ export const SUBAGENT_TOOL_NAMES = [
     "subagent_stop",
     "subagent_wait_all",
     "subagent_templates",
+    "subagent_handoff",
 ];
 /** 独立宽松编辑工具（定义见 edit-soft-tool.ts）。 */
 export const EDIT_SOFT_TOOL_NAME = "edit_soft";
@@ -58,15 +59,25 @@ export const SKILL_TOOL_NAME = "skill";
 export const SCHEDULE_TASK_TOOL_NAME = "schedule_task";
 export const SCHEDULE_LIST_TOOL_NAME = "schedule_list";
 export const SCHEDULE_CANCEL_TOOL_NAME = "schedule_cancel";
+/** 持久代码求值沙箱工具（定义见 eval-tool.ts）：在受控持久内核中执行 Python 或 JS/TS 代码。 */
+export const EVAL_TOOL_NAME = "eval";
 /** 展示文件工具（定义见 present-files-tool.ts）：把图片/视频/文本作为预览卡片
  *  推到对话里，卡片带预览/本地打开/在文件夹中显示/下载/复制路径。 */
 export const PRESENT_FILES_TOOL_NAME = "present_files";
 /** 文件认领工具（定义见 claim-files-tool.ts）：声明要改哪些文件，让同项目的
  *  并行对话绕行（纯建议，不拦编辑）。 */
 export const CLAIM_FILES_TOOL_NAME = "claim_files";
+/** 任务计划看板更新工具（定义见 plan-manager.ts，Plan Mode / 步骤状态机）。 */
+export const PLAN_UPDATE_TOOL_NAME = "plan_update";
+/** 主动上下文压缩工具（定义见 compact-context-tool.ts）。 */
+export const COMPACT_CONTEXT_TOOL_NAME = "compact_context";
+/** 高可靠结构化补丁工具（定义见 patch-tool.ts）：基于内容哈希锚点与语法块的行补丁工具。 */
+export const PATCH_TOOL_NAME = "patch";
+/** 原生语言服务器工具（定义见 lsp-tool.ts）：代码定义跳转、引用查询、类型悬停与诊断。 */
+export const LSP_TOOL_NAME = "lsp";
 /** 旧工具名（持久化迁移用；新代码一律用 MARKERS_LIST_TOOL_NAME）。 */
 export const LEGACY_MARKERS_LIST_TOOL_NAME = "markers_list";
-/** 可开关的 Agent 工具总目录（共 26 个；bash 本体与 SDK 内置 edit/read
+/** 可开关的 Agent 工具总目录（共 27 个；bash 本体与 SDK 内置 edit/read
  *  不进目录——关了 agent 就残了，不给关）。 */
 export const AGENT_TOOL_CATALOG = [
     ...TERMINAL_TOOL_NAMES.map((name) => ({
@@ -135,6 +146,31 @@ export const AGENT_TOOL_CATALOG = [
         descKey: "claimFilesEnabledDesc",
         offHintKey: "claimFilesOffHint",
     },
+    // 结构化任务计划更新（Plan Mode / Step State Machine），默认开。
+    {
+        name: PLAN_UPDATE_TOOL_NAME,
+        group: "other",
+        defaultOn: true,
+        dshVisible: true,
+        descKey: "planUpdateEnabledDesc",
+        offHintKey: "planUpdateOffHint",
+    },
+    {
+        name: PATCH_TOOL_NAME,
+        group: "other",
+        defaultOn: true,
+        dshVisible: false,
+        descKey: "patchToolEnabledDesc",
+        offHintKey: "patchToolOffHint",
+    },
+    {
+        name: LSP_TOOL_NAME,
+        group: "other",
+        defaultOn: false,
+        dshVisible: false,
+        descKey: "lspToolEnabledDesc",
+        offHintKey: "lspToolOffHint",
+    },
     // 展示文件给用户（图片/视频内联、文本开预览弹窗、本地打开按钮）：默认开，
     // 不打开模型根本不知道能“给用户看”；DSH 引擎没有该 customTool（走 shipped preset）。
     {
@@ -155,6 +191,16 @@ export const AGENT_TOOL_CATALOG = [
         descKey: "skillEnabledDesc",
         offHintKey: "skillOffHint",
     },
+    // 持久代码求值沙箱（Python / Node.js）：默认关（opt-in，防工具挤占）；
+    // DSH 引擎没有该 customTool。
+    {
+        name: EVAL_TOOL_NAME,
+        group: "other",
+        defaultOn: false,
+        dshVisible: false,
+        descKey: "evalEnabledDesc",
+        offHintKey: "evalOffHint",
+    },
     // 定时/延时唤醒：默认开（不打开 AI 根本不知道能定时；60s 间隔底线＋面板可随时取消），
     // DSH 引擎没有该 customTool（走 goal-rpc，无 customTool 注册面）。
     {
@@ -181,6 +227,16 @@ export const AGENT_TOOL_CATALOG = [
         descKey: "scheduleTaskEnabledDesc",
         offHintKey: "scheduleTaskOffHint",
     },
+    // 主动上下文压缩：默认开（让 AI 可以根据当前问题主动精简上下文）。
+    // DSH 引擎无 customTool 注册面，不接。
+    {
+        name: COMPACT_CONTEXT_TOOL_NAME,
+        group: "other",
+        defaultOn: true,
+        dshVisible: false,
+        descKey: "compactContextEnabledDesc",
+        offHintKey: "compactContextOffHint",
+    },
     // todo_list 唯一例外：行不在「其他」组，固定在上面的 markers 分区（设置页循环
     // 跳过它，见 OTHER_AGENT_TOOLS；文案 key 照给，万一哪天搬家不用补）。
     {
@@ -263,9 +319,10 @@ export function setAgentToolsEnabled(session, names, on) {
 /**
  * 全量重放（创建会话 / reload 后 / 设置变更后调）：按禁用名单把目录内工具
  * 逐个加回或剔除；目录外的工具（bash/SDK 内置/插件工具）原样不动。
+ * 支持传入 preset（预设 id），按预设白名单做二次过滤。
  * Session 未就绪时静默跳过（下次创建/reload 会再应用）。
  */
-export function applyAgentToolsGating(session, disabled) {
+export function applyAgentToolsGating(session, disabled, preset) {
     try {
         const off = new Set(disabled);
         const names = new Set(session.getActiveToolNames());
@@ -275,12 +332,155 @@ export function applyAgentToolsGating(session, disabled) {
             else
                 names.add(t.name);
         }
-        session.setActiveToolsByName([...names]);
+        const filtered = filterToolsByPreset(names, preset);
+        session.setActiveToolsByName(filtered);
     }
     catch {
         // Session 未就绪——下次创建/reload 会再应用。
     }
 }
+/** pi 引擎内置 Agent 预设名录（对齐 DSH 预设体系，会话级工具白名单）。 */
+export const PI_AGENT_PRESETS = [
+    {
+        id: "standard",
+        trust: "system",
+        isDefault: true,
+        name: "全功能",
+        description: "提供全部可用工具与扩展能力（默认）",
+        order: 0,
+    },
+    {
+        id: "minimal",
+        trust: "system",
+        isDefault: false,
+        name: "极简模式",
+        description: "仅保留 bash 与 read；插件工具、技能名录与终端引导同步隐藏",
+        order: 1,
+    },
+    {
+        id: "code",
+        trust: "system",
+        isDefault: false,
+        name: "代码开发",
+        description: "专注于代码读写与执行（bash, read, edit, write, edit_soft）；插件工具与技能名录同步隐藏",
+        order: 2,
+    },
+    {
+        id: "reader",
+        trust: "system",
+        isDefault: false,
+        name: "只读分析",
+        description: "仅保留只读工具，禁止写操作；插件工具同步隐藏（读写未知，保守处理）",
+        order: 3,
+    },
+    {
+        id: "ask",
+        trust: "system",
+        isDefault: false,
+        name: "纯对话",
+        description: "无工具问答模式，模型不调用任何工具；插件工具与技能名录同步隐藏",
+        order: 4,
+    },
+];
+/** pi 引擎权限预设选项（三档沙箱策略）。 */
+export const PI_PERMISSION_OPTIONS = [
+    {
+        value: "read-only",
+        name: "只读模式",
+        description: "禁止所有文件修改（write/edit/edit_soft）及任何非只读操作",
+    },
+    {
+        value: "workspace-write-never",
+        name: "工作区内修改",
+        description: "仅允许在当前工作区目录下修改文件，工作区外写操作一律拒绝",
+    },
+    {
+        value: "danger-full-access",
+        name: "完全权限",
+        description: "允许修改任意目录文件及执行全量操作（需要二次确认）",
+    },
+];
+/** 按预设过滤活跃工具名。 */
+export function filterToolsByPreset(tools, preset) {
+    const all = Array.from(tools);
+    if (!preset || preset === "standard")
+        return all;
+    if (preset === "ask")
+        return [];
+    if (preset === "minimal") {
+        return all.filter((n) => n === "bash" || n === "read");
+    }
+    if (preset === "code") {
+        const codeSet = new Set(["bash", "read", "edit", "write", "edit_soft"]);
+        return all.filter((n) => codeSet.has(n));
+    }
+    if (preset === "reader") {
+        const writeTools = new Set([
+            "write",
+            "edit",
+            "edit_soft",
+            "bash",
+            "terminal_create",
+            "terminal_input",
+            "terminal_close",
+            "terminal_key",
+        ]);
+        return all.filter((n) => !writeTools.has(n));
+    }
+    return all;
+}
+/**
+ * pi 预设语义总表（唯一事实源，本文件是唯一定义处）：
+ *
+ * 预设是「禁用名单之外」的第二层门控，按会话生效（conv.agentPreset），新对话
+ * 取默认预设、首轮发言后锁定。标准预设不过滤；其余预设同时约束四处：
+ *
+ * - 目录/内置工具（ActiveSet）：filterToolsByPreset 直接过滤活跃集
+ *   （standard 全留 / ask 全拔 / minimal 仅 bash+read /
+ *   code 仅 bash+read+edit+write+edit_soft / reader 拔写类）。
+ * - 插件工具（registerAgentTool 动态注册）：presetAllowsPluginTools —— 只有
+ *   standard 保留，其余已知预设一律拔掉。插件工具读写性质未知，保守按最严处理
+ *   （minimal/code/ask 是白名单语义本来就过不去；reader 是 deny 名单，
+ *   未知工具同样不放行；未知预设 id 按不过滤，与 filterToolsByPreset 同口径）。
+ * - 技能名录段（{{skills}} 名录＋全文注入）：presetShowsSkillCatalog —— 与
+ *   skill 加载工具同进退（minimal/code/ask 下 loader 不在，列出来只是噪音；
+ *   reader 下 loader 可用，保留）。子代理模板的技能白名单是显式配置，
+ *   优先级高于预设，不参与此门控。
+ * - 终端引导（TERMINAL_TOOLS_GUIDANCE）：isTerminalGuidanceOn(disabled, preset) ——
+ *   只教「开关开着且预设下仍可用」的终端工具，不教不存在的工具。
+ * - 并行提醒（parallel-work-reminder）：信息层，不按预设开关（只看
+ *   parallelReminderEnabled 开关）；但文案里的问卷指引按
+ *   presetHasQuestionnaire 切换措辞——有问卷工具时调工具，否则正文提问。
+ *   认领信息是事实层，照常展示（store 是按项目全局的）。
+ *
+ * 显式配置永远优先于预设：disabledAgentTools / disabledPluginTools /
+ * disabledSkills / 子代理模板白名单照常生效，预设只做减法不做加法
+ * （开关关掉的东西，standard 也不会加回来）。
+ */
+/**
+ * 预设是否允许插件工具（动态注册，读写未知）：只有 standard 允许；
+ * 其余已知预设一律拒绝。未知 id 按不过滤（与 filterToolsByPreset 同口径，
+ * 防手写脏配置把插件工具全灭）。
+ */
+export function presetAllowsPluginTools(preset) {
+    if (!preset || preset === "standard")
+        return true;
+    return !PI_AGENT_PRESETS.some((p) => p.id === preset);
+}
+/**
+ * 预设下是否展示技能名录段（与 skill 加载工具同进退，由 filterToolsByPreset
+ * 单源推导，不另维护名单：minimal/code/ask 藏，standard/reader 留）。
+ */
+export function presetShowsSkillCatalog(preset) {
+    return filterToolsByPreset([SKILL_TOOL_NAME], preset).includes(SKILL_TOOL_NAME);
+}
+/**
+ * 预设下问卷工具是否可用（并行提醒等服务端文案用：有则指引调工具，
+ * 无则指引正文提问——不教不存在的工具）。同样单源推导。
+ */
+export function presetHasQuestionnaire(preset) {
+    return filterToolsByPreset([ASK_USER_QUESTION_TOOL_NAME], preset).includes(ASK_USER_QUESTION_TOOL_NAME);
+}
 /**
  * 旧存档迁移：已有新字段直接归一化；否则按遗留三开关折算
  * （语义与改动前一致：terminal/edit 未设/关 = 禁用对应组；问卷未设/开 = 启用）。
@@ -337,7 +537,15 @@ export function effectiveDisabledAgentTools(s) {
         next.add(ASK_USER_QUESTION_TOOL_NAME);
     return [...next];
 }
-/** 终端使用引导是否注入（组内有任一工具启用才教 AI 用，否则就是教不存在的工具）。 */
-export function isTerminalGuidanceOn(disabled) {
-    return TERMINAL_TOOL_NAMES.some((n) => !disabled.includes(n));
+/**
+ * 终端使用引导是否注入：组内有任一工具「开关开着且预设下仍可用」才教 AI 用，
+ * 否则就是教不存在的工具（preset 缺省/standard = 只看开关，保持旧语义）。
+ */
+export function isTerminalGuidanceOn(disabled, preset) {
+    const on = TERMINAL_TOOL_NAMES.filter((n) => !disabled.includes(n));
+    if (on.length === 0)
+        return false;
+    if (!preset || preset === "standard")
+        return true;
+    return filterToolsByPreset(on, preset).length > 0;
 }

package/dist/server/workspace-snapshot.js

@@ -0,0 +1,113 @@
+/**
+ * server/workspace-snapshot.ts
+ *
+ * 工作区版本影子快照机制（Workspace Snapshot / Dual-State Rollback）。
+ *
+ * 每次用户发起新任务或运行关键操作前，为当前工作区记录轻量快照引用（Git commit SHA）。
+ * 机制：
+ * - 利用独立的临时 GIT_INDEX_FILE，通过 `git add -A` + `git write-tree` + `git commit-tree` 生成独立 commit；
+ * - 绝不改变用户现有的 HEAD、branch 指针、工作区文件或 .git/index；
+ * - 回滚时若启用 restoreWorkspace，通过 `git checkout <snapshotRef> -- .` 与 `git clean -fd` 还原物理文件。
+ */
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { gitDirOf } from "./scm.js";
+const exec = promisify(execFile);
+/** 单次 git 快照/还原命令超时时间（毫秒）。 */
+const GIT_SNAPSHOT_TIMEOUT_MS = 15_000;
+/** 执行单条 git 命令，返回 stdout。 */
+async function runGit(cwd, args, envExtra) {
+    const { stdout } = await exec("git", ["-c", "core.quotepath=false", ...args], {
+        cwd,
+        env: envExtra ? { ...process.env, ...envExtra } : process.env,
+        timeout: GIT_SNAPSHOT_TIMEOUT_MS,
+        maxBuffer: 16 * 1024 * 1024,
+        windowsHide: true,
+    });
+    return stdout.trim();
+}
+/** 检查工作区是否由 Git 管理。 */
+export async function isGitWorkspace(cwd) {
+    return (await gitDirOf(cwd)) !== null;
+}
+/**
+ * 为当前工作区创建轻量版本快照。
+ * 若当前目录不在 Git 仓库内，返回 null。
+ *
+ * 该操作纯粹在临时 index 文件中完成，绝不影响用户的实际 index 或 HEAD。
+ */
+export async function createWorkspaceSnapshot(cwd) {
+    const gitDir = await gitDirOf(cwd);
+    if (!gitDir)
+        return null;
+    const tempIndex = join(gitDir, `temp-index-snapshot-${randomUUID()}`);
+    const env = { GIT_INDEX_FILE: tempIndex };
+    try {
+        // 1. 将当前工作区所有改动（含未跟踪与新增）记录到临时 index
+        await runGit(cwd, ["add", "-A"], env);
+        // 2. 写入 tree 对象
+        const tree = await runGit(cwd, ["write-tree"], env);
+        if (!tree)
+            return null;
+        // 3. 检查是否有 HEAD commit 作为 parent
+        let hasHead = false;
+        try {
+            await runGit(cwd, ["rev-parse", "--verify", "HEAD"]);
+            hasHead = true;
+        }
+        catch {
+            hasHead = false;
+        }
+        // 4. 创建轻量 commit 对象，不关联任何分支引用
+        const commitArgs = ["commit-tree", tree];
+        if (hasHead) {
+            commitArgs.push("-p", "HEAD");
+        }
+        commitArgs.push("-m", `pi-web-ui: workspace shadow snapshot ${new Date().toISOString()}`);
+        const commitHash = await runGit(cwd, commitArgs, env);
+        return commitHash || null;
+    }
+    catch (err) {
+        console.warn(`[workspace-snapshot] 创建快照失败 (${cwd}):`, err.message);
+        return null;
+    }
+    finally {
+        // 务必清理临时 index 文件
+        try {
+            await rm(tempIndex, { force: true });
+        }
+        catch {
+            // ignore cleanup error
+        }
+    }
+}
+/**
+ * 将工作区物理文件还原到指定的快照状态。
+ *
+ * 执行步骤：
+ * 1. `git read-tree -u --reset <snapshotRef>` 将 index 与工作区重置为快照树，并删除快照之后新增的文件；
+ * 2. `git clean -fd` 清理快照之后新增的未跟踪文件与空目录。
+ */
+export async function restoreWorkspaceSnapshot(cwd, snapshotRef) {
+    const gitDir = await gitDirOf(cwd);
+    if (!gitDir) {
+        return { success: false, error: "Workspace is not a Git repository" };
+    }
+    try {
+        // 验证 snapshotRef 合法性
+        await runGit(cwd, ["rev-parse", "--verify", snapshotRef]);
+        // 1. 将 index 和工作区彻底重置到快照树状态（自动清除快照中不存在的文件）
+        await runGit(cwd, ["read-tree", "-u", "--reset", snapshotRef]);
+        // 2. 清理新产生的未跟踪文件与目录
+        await runGit(cwd, ["clean", "-fd"]);
+        return { success: true };
+    }
+    catch (err) {
+        const msg = err.message;
+        console.error(`[workspace-snapshot] 还原快照失败 (${cwd}, ${snapshotRef}):`, msg);
+        return { success: false, error: msg };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-web-ui",
-	"version": "0.94.1",
+	"version": "0.95.0",
 	"description": "Just open your browser to get all your work done — browser cockpit for AI coding agents (chat, code, files, terminal, Git in one tab)",
 	"license": "MIT",
 	"author": {
@@ -84,7 +84,7 @@
 	"dependencies": {
 		"@deepseek-ai/dsh-sdk-jsonrpc-server": "^0.1.1-rc.2",
 		"@deepseek-ai/dsh-sdk-protocol": "^0.1.1-rc.2",
-		"@earendil-works/pi-coding-agent": ">=0.85.1 <0.87.0",
+		"@earendil-works/pi-coding-agent": ">=0.85.1",
 		"@xterm/addon-fit": "^0.11.0",
 		"@xterm/xterm": "^6.0.0",
 		"compression": "^1.8.2",

package/plugin-sdk/README.md

@@ -125,4 +125,29 @@ describe("my-plugin", () => {
 | `schedule` 持久版（`{id, persistent, catchUp, label}`，落盘+补跑+进后台面板）                    | ✅                    | —                               |
 | `host.requestPermission`（动态授权：net 补主机 / llm 限模型，用户逐条确认可记住）                | ✅（基础族须已声明）  | 确认框 + 设置面板「已授权能力」 |
 
+## 反激活与清理：`host.effect(label, dispose)`
+
+宿主的每个注册面（`ui.register` / `registerAgentTool` / `registerCommand` / `route` /
+`registerProxy` / `fs.watch` / `schedule` / `registerBackgroundTask` / `events.on` /
+`onStats` / `onStreaming` / `onSettingsChanged` …）都返回注销函数，**并且**已经在宿主内部
+登记进该插件的 effect 栈：反激活（禁用、卸载、`plugins_reload`）时**逆序回卷**，插件忘了
+调用返回的注销函数也不会留下孤儿订阅/定时器/路由。
+
+你自己建的东西（`setInterval` / `addEventListener` / WebSocket / 自建缓存）挂在
+`host.effect` 上同样享受这条保障：
+
+```js
+export default definePlugin({
+	async activate(host) {
+		const timer = setInterval(() => host.log("info", "tick"), 60_000);
+		host.effect("my-timer", () => clearInterval(timer));
+		// 也可以两者都写（幂等：dispose 写成本身幂等即可）
+		const off = host.effect("my-ws", () => ws.close());
+	},
+});
+```
+
+清理抛错只记一条诊断、不阻断其它清理；`host.effect` 返回的注销函数与反激活都会调
+`dispose`，所以 `dispose` 请写成**幂等**的。
+
 完整契约见 `docs/architecture-plugins.md`。

package/plugin-sdk/index.d.ts

@@ -5,16 +5,7 @@
  */
 
 export type PluginPermissionFamily =
-	| "fs"
-	| "fs:read"
-	| "fs:write"
-	| "ui"
-	| "tools"
-	| "http"
-	| "chat"
-	| "net"
-	| "dom"
-	| "dom:anchor";
+	"fs" | "fs:read" | "fs:write" | "ui" | "tools" | "http" | "chat" | "net" | "dom" | "dom:anchor";
 
 export interface WsEntry {
 	name: string;
@@ -35,17 +26,7 @@ export interface UiSelectOption {
 }
 
 export type UiItemKind =
-	| "view"
-	| "action"
-	| "badge"
-	| "menu"
-	| "page"
-	| "organizer"
-	| "divider"
-	| "toggle"
-	| "input"
-	| "progress"
-	| "select";
+	"view" | "action" | "badge" | "menu" | "page" | "organizer" | "divider" | "toggle" | "input" | "progress" | "select";
 
 export interface UiContribution {
 	id: string;
@@ -152,13 +133,7 @@ export interface PluginHostUi {
 /** host.llm.complete：孤立无工具的一次性补全（不建对话、不进历史）。
  *  需要 manifest.permissions 含 "llm"（花用户自己的模型额度）。 */
 export interface PluginHostLlm {
-	complete(req: {
-		prompt: string;
-		system?: string;
-		model?: string;
-		maxChars?: number;
-		timeoutMs?: number;
-	}): Promise<{
+	complete(req: { prompt: string; system?: string; model?: string; maxChars?: number; timeoutMs?: number }): Promise<{
 		ok: boolean;
 		text?: string;
 		model?: string;
@@ -167,6 +142,19 @@ export interface PluginHostLlm {
 	}>;
 }
 
+/** 工具拦截守卫看到的 pre 请求（只对 bash/read 生效，全量见 server/plugin-tool-guard.ts）。 */
+export interface ToolGuardPreRequest {
+	toolName: "bash" | "read";
+	params: unknown;
+	conversationId?: string;
+}
+
+/** 工具 pre 决策：allow 放行 / deny 拒绝 / ask 待确认（暂按拒绝执行）。 */
+export type ToolGuardPreDecision =
+	| { decision: "allow" }
+	| { decision: "deny"; reason?: string; reasonEn?: string }
+	| { decision: "ask"; reason?: string; reasonEn?: string };
+
 /** 插件服务端入口拿到的宿主接口（精简：全量见 server/plugins.ts PluginHost）。 */
 export interface PluginHost {
 	broadcast(payload: unknown): void;
@@ -175,6 +163,12 @@ export interface PluginHost {
 	sendTo(clientId: string, payload: unknown): void;
 	onAttach(handler: (clientId: string) => void): () => void;
 	onToolEvent(handler: (ev: unknown) => void): () => void;
+	/** 注册工具 pre 拦截守卫（只对 bash/read 生效；要 "tools" 能力）。 */
+	onToolPre(
+		handler: (req: ToolGuardPreRequest) => ToolGuardPreDecision | void | Promise<ToolGuardPreDecision | void>,
+	): () => void;
+	/** 注册工具 post 编辑守卫（只对 bash/read 生效；要 "tools" 能力）。 */
+	onToolPost(handler: (req: unknown) => unknown): () => void;
 	onRunEvent(handler: (ev: unknown) => void): () => void;
 	getActiveConversation(): unknown;
 	onConversationChanged(handler: () => void): () => void;
@@ -219,6 +213,11 @@ export interface PluginHost {
 	 *  200 条，单条截断 500 字符，不落盘）；error 级同时走 console.error。
 	 *  用户在设置面板“界面插件”页点某插件的“日志”按需查看（级别过滤 + 清空）。 */
 	log(level?: "debug" | "info" | "warn" | "error", ...args: unknown[]): void;
+	/** 登记一条**自建**的可逆副作用（自建 setInterval / event 监听 / WebSocket…）：
+	 *  返回的注销函数与插件反激活**都会**调 dispose。宿主自己的每个注册面已在内部
+	 *  走同一个 effect 栈，这里只用于「宿主管不到的那些」—— 挂进来就不怕漏注销
+	 *  （热重载后定时器叠加、监听器堆积都是这个漏法的症状）。dispose 请写成幂等的。 */
+	effect(label: string, dispose: () => void): () => void;
 	/** 无头调用：把外部通道文本投给 agent（要 "chat" 能力；宿主未接 chatProvider
 	 *  时 reject（由 chatWait 包成 {ok:false}，插件侧用 chatWait 更省心）。 */
 	chat(req: { text: string; accountId?: string }): Promise<{
@@ -259,12 +258,7 @@ export interface PluginHost {
 		}>;
 	};
 	/** 常驻后台任务（顶栏「后台任务」面板；返回 update/unregister）。 */
-	registerBackgroundTask(task: {
-		id: string;
-		label: string;
-		stop?: () => void;
-		status?: string;
-	}): {
+	registerBackgroundTask(task: { id: string; label: string; stop?: () => void; status?: string }): {
 		update(next: Partial<{ label: string; status: string; stop: () => void }>): void;
 		unregister(): void;
 	};
@@ -340,10 +334,9 @@ export declare function defineView(view: PluginViewModule): PluginViewModule;
 export declare function defineRenderer(
 	renderers: Record<string, (code: string, ctx: PluginViewContext) => HTMLElement | null>,
 ): Pick<PluginViewModule, "renderers">;
-export declare function actionHandler(map: Record<string, (value?: string) => void>): (
-	itemId: string,
-	value?: string,
-) => void;
+export declare function actionHandler(
+	map: Record<string, (value?: string) => void>,
+): (itemId: string, value?: string) => void;
 export declare function onUiAction(action: string, handler: (itemId: string, value?: string) => void): () => void;
 export declare function getSetting<T>(host: PluginHost, key: string, fallback: T): T;
 export declare function selectOptions(list: Array<string | UiSelectOption>): UiSelectOption[];

package/plugin-sdk/index.mjs

@@ -211,18 +211,20 @@ export function createMockHost(overrides) {
 	// 订阅类：存 handler + 返回注销函数（调用本身由外层统一记进 calls）。
 	// handler 缺省取首参；fs.watch(path, handler) / events.on(topic, handler) /
 	// shortcuts.register(key, handler) 这类回调在第二参，用 sub(method, 1)。
-	const sub = (method, argIndex = 0) => (...args) => {
-		const handler = args[argIndex];
-		if (typeof handler === "function") handlersOf(method).push(handler);
-		let done = false;
-		return () => {
-			if (done) return;
-			done = true;
-			const arr = handlersOf(method);
-			const i = arr.indexOf(handler);
-			if (i >= 0) arr.splice(i, 1);
+	const sub =
+		(method, argIndex = 0) =>
+		(...args) => {
+			const handler = args[argIndex];
+			if (typeof handler === "function") handlersOf(method).push(handler);
+			let done = false;
+			return () => {
+				if (done) return;
+				done = true;
+				const arr = handlersOf(method);
+				const i = arr.indexOf(handler);
+				if (i >= 0) arr.splice(i, 1);
+			};
 		};
-	};
 	const logImpl = (levelOrArg, ...args) => {
 		const levels = ["debug", "info", "warn", "error"];
 		const level = levels.includes(levelOrArg) ? levelOrArg : "info";
@@ -243,12 +245,16 @@ export function createMockHost(overrides) {
 			try {
 				console.error("[mock-host]", text);
 			} catch {
-			/* 打印失败不影响单测 */
+				/* 打印失败不影响单测 */
 			}
 		}
 	};
 	const statImpl = (p) => ({
-		name: String(p ?? "").split(/[\\/]/).filter(Boolean).pop() ?? "",
+		name:
+			String(p ?? "")
+				.split(/[\\/]/)
+				.filter(Boolean)
+				.pop() ?? "",
 		type: "file",
 		size: 0,
 		mtime: 0,
@@ -264,6 +270,7 @@ export function createMockHost(overrides) {
 	const routeStore = [];
 	const proxyStore = [];
 	const scheduleStore = [];
+	const effectStore = [];
 	// 注册类：存定义体 + 返回只摘除本次注册的注销函数（与宿主同语义）。
 	const remember = (store, entry) => {
 		if (entry !== undefined) store.push(entry);
@@ -283,6 +290,8 @@ export function createMockHost(overrides) {
 		sendTo: noop,
 		onAttach: sub("onAttach"),
 		onToolEvent: sub("onToolEvent"),
+		onToolPre: sub("onToolPre"),
+		onToolPost: sub("onToolPost"),
 		onRunEvent: sub("onRunEvent"),
 		getActiveConversation: () => null,
 		chat: async () => okFalse("chatProvider（无头调用未接入）"),
@@ -313,8 +322,7 @@ export function createMockHost(overrides) {
 				const list = Array.isArray(items) ? items : [items];
 				const added = [];
 				for (const raw of list.slice(0, 32)) {
-					const id =
-						raw && typeof raw.id === "string" && raw.id ? raw.id : `mock-${++uiAutoId}`;
+					const id = raw && typeof raw.id === "string" && raw.id ? raw.id : `mock-${++uiAutoId}`;
 					uiItems.set(id, isPlainObject(raw) ? { ...raw, id } : { id });
 					added.push(id);
 				}
@@ -421,6 +429,12 @@ export function createMockHost(overrides) {
 			on: sub("events.on", 1),
 		},
 		log: logImpl,
+		// effect 栈：mock 里只记调用 + 返回可撤函数（真实宿主在反激活时逆序回卷）。
+		// 单测里测试 dispose 真跑的写法：拿到 off() 后调它，或断言 host.calls 里有 effect。
+		effect: (label, dispose) => {
+			const entry = { label, dispose };
+			return remember(effectStore, entry);
+		},
 		// 浏览器桥兼容（client 侧逻辑单测也能用同一个 mock）：无注入回退语义。
 		dialogs: {
 			select: async () => ({ ok: false }),
@@ -527,10 +541,12 @@ export function createMockHost(overrides) {
 		}
 	}
 	// 记录层：所有 host 方法（mock/reset 除外）先记 calls 再委托。
-	const record = (method, fn) => (...args) => {
-		calls.push({ method, args, seq: calls.length });
-		return fn(...args);
-	};
+	const record =
+		(method, fn) =>
+		(...args) => {
+			calls.push({ method, args, seq: calls.length });
+			return fn(...args);
+		};
 	for (const [key, value] of Object.entries(host)) {
 		if (key === "calls" || key === "logs" || key === "mock" || key === "reset") continue;
 		if (typeof value === "function") {