@feng0531/dsh-execution-bus 0.9.0 → 0.10.0

package/README.md

@@ -4,7 +4,7 @@
 
 “萧何”是产品与模式显示名，执行总线是其技术功能；不新增人物 Agent，不进行角色扮演。仓库 dsh-execution-bus、npm 包名、execution_bus 工具名及 execution-bus-test 预设 ID 保持不变。历史版本发布说明保留当时名称。
 
-DSH 独立插件：`@feng0531/dsh-execution-bus` · 当前版本 **0.9.0**
+DSH 独立插件：`@feng0531/dsh-execution-bus` · 当前版本 **0.10.0**
 
 > 萧何模式从宿主已声明的 PTC 组合派生，保留日常工具，再叠加可选执行总线。已验证隔离的真实 Node PTC → 原 read + 总线调用，以及脚本模型内存会话；真实模型、桌面界面与实际沙箱仍未验收。**不支持重启后恢复任务。**
 
@@ -130,7 +130,7 @@ flowchart TD
 2. 在你选定的隔离 DSH 配置依赖目录安装固定版本，不要在 DSH 程序安装目录执行：
 
    ```powershell
-   npm install --ignore-scripts @feng0531/dsh-execution-bus@0.9.0
+   npm install --ignore-scripts @feng0531/dsh-execution-bus@0.10.0
    ```
 
    这是 npm 目录示例。若目标配置使用 pnpm，应沿用其包管理器，不混用锁文件。遇到宿主 peer 版本冲突就停止，不用强制安装绕过。
@@ -201,6 +201,8 @@ flowchart TD
 
 PTC 是 DSH 的程序化工具调用入口。在 `run_code` 内使用 `await tools.execution_bus(请求对象)`，而不是直接调用折叠后的工具名。执行总线不会解除 `run_code` 自身的时间预算。已有真实 Node PTC 隔离进程读文件和调用总线的验证，但尚未进行实际模型/桌面沙箱全链路验收。
 
+**0.10.0 起，模式说明与工具声明给出明确触发条件。** 仅当预计单次宿主操作超过约 30 秒、同一逻辑操作可能重复提交（沿用 requestId）、任务需要在 `run_code` 预算结束后继续、或多个步骤需要等待同一执行时，才使用 `execution_bus`；其余任务继续用原工具，避免为简单调用增加包装。工具声明改为按 Handler 的判别联合（`host.read`/`host.glob`/`host.grep`/`host.edit`/`host.write`/`host.pwsh`/`test`），PTC SDK 与原生声明里可直接看到每个 Handler 的必填字段，而不是泛型 `payload`。
+
 **0.9.0 起，预算到期不再连带取消已受理执行。** `run_code` 因时间预算到期或程序结束时，宿主会中断其中的工具子调用；总线把这种中断视为**只停止等待**：已受理执行与宿主 Job 继续，程序返回预算错误后，可在后续 `run_code` 中用同一 `requestId` 的 `status`/`result` 取回结果，或用 `cancel` 取消。用户主动中断、会话取消、沙箱模式变化等其他原因仍会请求取消整个执行。该识别依赖 DSH 0.2.1-rc.2 的中断原因字符串（见[宿主兼容性](<docs/host-compatibility.md>)），不是宿主公开稳定契约；进程退出仍会丢失全部内存状态，保留期一小时。
 
 ## 如何理解任务状态？
@@ -276,7 +278,7 @@ npm run test:install    # 临时目录安装，不操作日常 DSH
 
 - [协议和投递语义](<docs/protocol.md>)：字段、状态、重复处理与取消规则。
 - [宿主兼容性与源码调用链](<docs/host-compatibility.md>)：为什么可以等待，为什么不能跨重启恢复。
-- [验证记录](<docs/validation.md>)、[0.9.0 发布说明](<docs/releases/0.9.0.md>)：已验证与未验证范围。
+- [验证记录](<docs/validation.md>)、[0.10.0 发布说明](<docs/releases/0.10.0.md>)：已验证与未验证范围。
 - [同类项目源码整合](<docs/INTEGRATION.md>)：固定来源、采用范围、许可与验证边界。
 - [维护者发布流程](<docs/RELEASING.md>)：标签 CI、安装包校验与正式发布门禁。
 

package/dist/product.d.ts

@@ -23,6 +23,161 @@ export declare const HANDLER_LIMITS: Readonly<{
     readPathChars: 2048;
     diagnosticDelayMs: 30000;
 }>;
+/** request 的 {handler,input} 判别联合；控制消息为空对象。 */
+export declare const PAYLOAD_SCHEMA: {
+    readonly description: "request 必须匹配某个 Handler 的 {handler,input}；status/result/cancel 的 payload 必须为空对象 {}。";
+    readonly oneOf: readonly [...{
+        type: "object";
+        additionalProperties: false;
+        required: string[];
+        properties: {
+            handler: {
+                type: "string";
+                const: "host.read" | "host.glob" | "host.grep" | "host.edit" | "host.write" | "host.pwsh" | "test";
+            };
+            input: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["delayMs", "fail"];
+                readonly properties: {
+                    readonly delayMs: {
+                        readonly type: "integer";
+                        readonly description: "Diagnostic delay in milliseconds (0-30000).";
+                    };
+                    readonly fail: {
+                        readonly type: "boolean";
+                        readonly description: "Settle as a controlled failure when true.";
+                    };
+                };
+            } | {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["file_path"];
+                readonly properties: {
+                    readonly file_path: {
+                        readonly type: "string";
+                        readonly description: "Path resolved against the session working directory.";
+                    };
+                    readonly offset: {
+                        readonly type: "integer";
+                        readonly description: "1-based first line to read.";
+                    };
+                    readonly limit: {
+                        readonly type: "integer";
+                        readonly description: "Maximum lines to read (<=100).";
+                    };
+                };
+            } | {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["pattern"];
+                readonly properties: {
+                    readonly pattern: {
+                        readonly type: "string";
+                        readonly description: "Glob pattern; a bare pattern matches basenames at any depth.";
+                    };
+                    readonly path: {
+                        readonly type: "string";
+                        readonly description: "Directory to search; defaults to the session working directory.";
+                    };
+                };
+            } | {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["pattern"];
+                readonly properties: {
+                    readonly pattern: {
+                        readonly type: "string";
+                        readonly description: "Ripgrep regular expression.";
+                    };
+                    readonly path: {
+                        readonly type: "string";
+                        readonly description: "File or directory to search; defaults to the session working directory.";
+                    };
+                    readonly include: {
+                        readonly type: "string";
+                        readonly description: "One positive glob filter; negation and comma lists are rejected.";
+                    };
+                };
+            } | {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["file_path", "old_string", "new_string"];
+                readonly properties: {
+                    readonly file_path: {
+                        readonly type: "string";
+                        readonly description: "File to edit.";
+                    };
+                    readonly old_string: {
+                        readonly type: "string";
+                        readonly description: "Literal text to replace.";
+                    };
+                    readonly new_string: {
+                        readonly type: "string";
+                        readonly description: "Replacement text.";
+                    };
+                    readonly replace_all: {
+                        readonly type: "boolean";
+                        readonly description: "Replace every occurrence.";
+                    };
+                };
+            } | {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["file_path", "content"];
+                readonly properties: {
+                    readonly file_path: {
+                        readonly type: "string";
+                        readonly description: "File to write.";
+                    };
+                    readonly content: {
+                        readonly type: "string";
+                        readonly description: "Full file content.";
+                    };
+                };
+            } | {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["description", "command"];
+                readonly properties: {
+                    readonly description: {
+                        readonly type: "string";
+                        readonly description: "Clear, concise description of what the command does (shown in the UI).";
+                    };
+                    readonly command: {
+                        readonly type: "string";
+                        readonly description: "PowerShell command to execute.";
+                    };
+                    readonly timeoutMs: {
+                        readonly type: "number";
+                        readonly description: "Positive timeout in milliseconds.";
+                    };
+                    readonly workdir: {
+                        readonly type: "string";
+                        readonly description: "Working directory; defaults to the session working directory.";
+                    };
+                    readonly run_in_background: {
+                        readonly type: "boolean";
+                        readonly description: "Return a host Job id immediately instead of waiting.";
+                    };
+                    readonly sandbox_permissions: {
+                        readonly type: "string";
+                        readonly enum: readonly ["workspace-write", "danger-full-access"];
+                        readonly description: "Narrowest wider sandbox mode; must be paired with justification.";
+                    };
+                    readonly justification: {
+                        readonly type: "string";
+                        readonly description: "Required with sandbox_permissions; one sentence of reason.";
+                    };
+                };
+            };
+        };
+    }[], {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {};
+    }];
+};
 export declare const REQUEST_PARAMETERS: {
     readonly type: "object";
     readonly additionalProperties: false;
@@ -34,16 +189,170 @@ export declare const REQUEST_PARAMETERS: {
         };
         readonly messageId: {
             readonly type: "string";
+            readonly description: "Unique id of this message; reuse only when redelivering the same message.";
         };
         readonly requestId: {
             readonly type: "string";
+            readonly description: "Stable id of one logical operation; reuse it when the same operation is submitted again.";
         };
         readonly type: {
             readonly type: "string";
             readonly enum: readonly ["request", "status", "result", "cancel"];
+            readonly description: "request submits work; status/result read the saved snapshot; cancel requests cancellation.";
         };
         readonly payload: {
-            readonly type: "object";
+            readonly description: "request 必须匹配某个 Handler 的 {handler,input}；status/result/cancel 的 payload 必须为空对象 {}。";
+            readonly oneOf: readonly [...{
+                type: "object";
+                additionalProperties: false;
+                required: string[];
+                properties: {
+                    handler: {
+                        type: "string";
+                        const: "host.read" | "host.glob" | "host.grep" | "host.edit" | "host.write" | "host.pwsh" | "test";
+                    };
+                    input: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["delayMs", "fail"];
+                        readonly properties: {
+                            readonly delayMs: {
+                                readonly type: "integer";
+                                readonly description: "Diagnostic delay in milliseconds (0-30000).";
+                            };
+                            readonly fail: {
+                                readonly type: "boolean";
+                                readonly description: "Settle as a controlled failure when true.";
+                            };
+                        };
+                    } | {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["file_path"];
+                        readonly properties: {
+                            readonly file_path: {
+                                readonly type: "string";
+                                readonly description: "Path resolved against the session working directory.";
+                            };
+                            readonly offset: {
+                                readonly type: "integer";
+                                readonly description: "1-based first line to read.";
+                            };
+                            readonly limit: {
+                                readonly type: "integer";
+                                readonly description: "Maximum lines to read (<=100).";
+                            };
+                        };
+                    } | {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["pattern"];
+                        readonly properties: {
+                            readonly pattern: {
+                                readonly type: "string";
+                                readonly description: "Glob pattern; a bare pattern matches basenames at any depth.";
+                            };
+                            readonly path: {
+                                readonly type: "string";
+                                readonly description: "Directory to search; defaults to the session working directory.";
+                            };
+                        };
+                    } | {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["pattern"];
+                        readonly properties: {
+                            readonly pattern: {
+                                readonly type: "string";
+                                readonly description: "Ripgrep regular expression.";
+                            };
+                            readonly path: {
+                                readonly type: "string";
+                                readonly description: "File or directory to search; defaults to the session working directory.";
+                            };
+                            readonly include: {
+                                readonly type: "string";
+                                readonly description: "One positive glob filter; negation and comma lists are rejected.";
+                            };
+                        };
+                    } | {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["file_path", "old_string", "new_string"];
+                        readonly properties: {
+                            readonly file_path: {
+                                readonly type: "string";
+                                readonly description: "File to edit.";
+                            };
+                            readonly old_string: {
+                                readonly type: "string";
+                                readonly description: "Literal text to replace.";
+                            };
+                            readonly new_string: {
+                                readonly type: "string";
+                                readonly description: "Replacement text.";
+                            };
+                            readonly replace_all: {
+                                readonly type: "boolean";
+                                readonly description: "Replace every occurrence.";
+                            };
+                        };
+                    } | {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["file_path", "content"];
+                        readonly properties: {
+                            readonly file_path: {
+                                readonly type: "string";
+                                readonly description: "File to write.";
+                            };
+                            readonly content: {
+                                readonly type: "string";
+                                readonly description: "Full file content.";
+                            };
+                        };
+                    } | {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["description", "command"];
+                        readonly properties: {
+                            readonly description: {
+                                readonly type: "string";
+                                readonly description: "Clear, concise description of what the command does (shown in the UI).";
+                            };
+                            readonly command: {
+                                readonly type: "string";
+                                readonly description: "PowerShell command to execute.";
+                            };
+                            readonly timeoutMs: {
+                                readonly type: "number";
+                                readonly description: "Positive timeout in milliseconds.";
+                            };
+                            readonly workdir: {
+                                readonly type: "string";
+                                readonly description: "Working directory; defaults to the session working directory.";
+                            };
+                            readonly run_in_background: {
+                                readonly type: "boolean";
+                                readonly description: "Return a host Job id immediately instead of waiting.";
+                            };
+                            readonly sandbox_permissions: {
+                                readonly type: "string";
+                                readonly enum: readonly ["workspace-write", "danger-full-access"];
+                                readonly description: "Narrowest wider sandbox mode; must be paired with justification.";
+                            };
+                            readonly justification: {
+                                readonly type: "string";
+                                readonly description: "Required with sandbox_permissions; one sentence of reason.";
+                            };
+                        };
+                    };
+                };
+            }[], {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly properties: {};
+            }];
         };
     };
 };
@@ -52,5 +361,5 @@ export declare const STATE_PARAMETERS: {
     readonly properties: {};
     readonly additionalProperties: false;
 };
-export declare const REQUEST_DESCRIPTION = "\u8427\u4F55 / Xiao He. Submit a version 1 request and WAIT for its terminal result in this tool call. Reuse requestId only for the same logical operation. Business handlers: host.read {file_path,offset?,limit?<=100}, host.glob {pattern,path?}, host.grep {pattern,path?,include?} (read-only, terminal reuse allowed); host.edit {file_path,old_string,new_string,replace_all?}, host.write {file_path,content}, host.pwsh {description,command,timeoutMs?,workdir?,run_in_background?,sandbox_permissions?,justification?} (mutating, terminal reuse denied). Diagnostic handler only: test {delayMs:0..30000,fail:boolean}; never use it to perform real work. Control status/result/cancel use empty payload. A PTC program end (including run_code budget expiry) only stops waiting: accepted work continues and the same requestId can be retrieved with status/result or cancelled. Acceptance is volatile, not success. No polling or restart resume.";
+export declare const REQUEST_DESCRIPTION = "\u8427\u4F55 / Xiao He. Submit a version 1 request and WAIT for its terminal result in this tool call. Use only when a host operation is expected to exceed ~30s, may be retried as the same logical operation (reuse requestId), must outlive a run_code budget end, or several steps must await one execution; otherwise call the original tool directly. messageId is per message; requestId is per logical operation. Control status/result/cancel use an empty payload; their snapshot is read-only. A PTC program end (including run_code budget expiry) only stops waiting: accepted work continues and the same requestId can be retrieved with status/result or cancelled. Diagnostic handler only: test {delayMs:0..30000,fail:boolean}; never use it to perform real work. Acceptance is volatile, not success. No polling or restart resume.";
 export declare const MODE_INSTRUCTIONS: string;

package/dist/product.js

@@ -23,16 +23,127 @@ export const HANDLER_LIMITS = Object.freeze({
     readPathChars: 2048,
     diagnosticDelayMs: 30000,
 });
+/** 每个 Handler 的模型可见输入声明。只用于工具 schema/SDK 生成；运行时仍由 Handler.validate 严格校验。 */
+const INPUT_SCHEMAS = {
+    test: {
+        type: "object",
+        additionalProperties: false,
+        required: ["delayMs", "fail"],
+        properties: {
+            delayMs: { type: "integer", description: "Diagnostic delay in milliseconds (0-30000)." },
+            fail: { type: "boolean", description: "Settle as a controlled failure when true." },
+        },
+    },
+    "host.read": {
+        type: "object",
+        additionalProperties: false,
+        required: ["file_path"],
+        properties: {
+            file_path: { type: "string", description: "Path resolved against the session working directory." },
+            offset: { type: "integer", description: "1-based first line to read." },
+            limit: { type: "integer", description: "Maximum lines to read (<=100)." },
+        },
+    },
+    "host.glob": {
+        type: "object",
+        additionalProperties: false,
+        required: ["pattern"],
+        properties: {
+            pattern: { type: "string", description: "Glob pattern; a bare pattern matches basenames at any depth." },
+            path: { type: "string", description: "Directory to search; defaults to the session working directory." },
+        },
+    },
+    "host.grep": {
+        type: "object",
+        additionalProperties: false,
+        required: ["pattern"],
+        properties: {
+            pattern: { type: "string", description: "Ripgrep regular expression." },
+            path: { type: "string", description: "File or directory to search; defaults to the session working directory." },
+            include: { type: "string", description: "One positive glob filter; negation and comma lists are rejected." },
+        },
+    },
+    "host.edit": {
+        type: "object",
+        additionalProperties: false,
+        required: ["file_path", "old_string", "new_string"],
+        properties: {
+            file_path: { type: "string", description: "File to edit." },
+            old_string: { type: "string", description: "Literal text to replace." },
+            new_string: { type: "string", description: "Replacement text." },
+            replace_all: { type: "boolean", description: "Replace every occurrence." },
+        },
+    },
+    "host.write": {
+        type: "object",
+        additionalProperties: false,
+        required: ["file_path", "content"],
+        properties: {
+            file_path: { type: "string", description: "File to write." },
+            content: { type: "string", description: "Full file content." },
+        },
+    },
+    "host.pwsh": {
+        type: "object",
+        additionalProperties: false,
+        required: ["description", "command"],
+        properties: {
+            description: { type: "string", description: "Clear, concise description of what the command does (shown in the UI)." },
+            command: { type: "string", description: "PowerShell command to execute." },
+            timeoutMs: { type: "number", description: "Positive timeout in milliseconds." },
+            workdir: { type: "string", description: "Working directory; defaults to the session working directory." },
+            run_in_background: { type: "boolean", description: "Return a host Job id immediately instead of waiting." },
+            sandbox_permissions: { type: "string", enum: ["workspace-write", "danger-full-access"], description: "Narrowest wider sandbox mode; must be paired with justification." },
+            justification: { type: "string", description: "Required with sandbox_permissions; one sentence of reason." },
+        },
+    },
+};
+/** Handler 名列表同时决定 request payload 的联合分支顺序。 */
+const HANDLER_NAMES = [
+    "host.read",
+    "host.glob",
+    "host.grep",
+    "host.edit",
+    "host.write",
+    "host.pwsh",
+    "test",
+];
+/** request 的 {handler,input} 判别联合；控制消息为空对象。 */
+export const PAYLOAD_SCHEMA = {
+    description: "request 必须匹配某个 Handler 的 {handler,input}；status/result/cancel 的 payload 必须为空对象 {}。",
+    oneOf: [
+        ...HANDLER_NAMES.map((handler) => ({
+            type: "object",
+            additionalProperties: false,
+            required: ["handler", "input"],
+            properties: {
+                handler: { type: "string", const: handler },
+                input: INPUT_SCHEMAS[handler],
+            },
+        })),
+        { type: "object", additionalProperties: false, properties: {} },
+    ],
+};
 export const REQUEST_PARAMETERS = {
     type: "object",
     additionalProperties: false,
     required: ["protocolVersion", "messageId", "requestId", "type", "payload"],
     properties: {
         protocolVersion: { type: "integer", const: 1 },
-        messageId: { type: "string" },
-        requestId: { type: "string" },
-        type: { type: "string", enum: ["request", "status", "result", "cancel"] },
-        payload: { type: "object" },
+        messageId: {
+            type: "string",
+            description: "Unique id of this message; reuse only when redelivering the same message.",
+        },
+        requestId: {
+            type: "string",
+            description: "Stable id of one logical operation; reuse it when the same operation is submitted again.",
+        },
+        type: {
+            type: "string",
+            enum: ["request", "status", "result", "cancel"],
+            description: "request submits work; status/result read the saved snapshot; cancel requests cancellation.",
+        },
+        payload: PAYLOAD_SCHEMA,
     },
 };
 export const STATE_PARAMETERS = {
@@ -40,8 +151,8 @@ export const STATE_PARAMETERS = {
     properties: {},
     additionalProperties: false,
 };
-export const REQUEST_DESCRIPTION = "萧何 / Xiao He. Submit a version 1 request and WAIT for its terminal result in this tool call. Reuse requestId only for the same logical operation. Business handlers: host.read {file_path,offset?,limit?<=100}, host.glob {pattern,path?}, host.grep {pattern,path?,include?} (read-only, terminal reuse allowed); host.edit {file_path,old_string,new_string,replace_all?}, host.write {file_path,content}, host.pwsh {description,command,timeoutMs?,workdir?,run_in_background?,sandbox_permissions?,justification?} (mutating, terminal reuse denied). Diagnostic handler only: test {delayMs:0..30000,fail:boolean}; never use it to perform real work. Control status/result/cancel use empty payload. A PTC program end (including run_code budget expiry) only stops waiting: accepted work continues and the same requestId can be retrieved with status/result or cancelled. Acceptance is volatile, not success. No polling or restart resume.";
-export const MODE_INSTRUCTIONS = "你正在萧何模式中。这不是角色扮演。保留宿主 PTC 的日常工具能力与权限规则。普通编辑、搜索、命令、安装和其他工作使用原工具，不要声称此模式只读。execution_bus 是可选协调入口，实际业务 Handler 为 host.read、host.glob、host.grep（只读，可复用终态结果）与 host.edit、host.write、host.pwsh（有副作用，终态结果不可复用）；test 仅用于用户明确要求的诊断，不做真实工作，不要强制所有任务走总线。通过 run_code 调用 await tools.execution_bus(...)，受原有时间预算约束。每会话排队上限 " +
+export const REQUEST_DESCRIPTION = "萧何 / Xiao He. Submit a version 1 request and WAIT for its terminal result in this tool call. Use only when a host operation is expected to exceed ~30s, may be retried as the same logical operation (reuse requestId), must outlive a run_code budget end, or several steps must await one execution; otherwise call the original tool directly. messageId is per message; requestId is per logical operation. Control status/result/cancel use an empty payload; their snapshot is read-only. A PTC program end (including run_code budget expiry) only stops waiting: accepted work continues and the same requestId can be retrieved with status/result or cancelled. Diagnostic handler only: test {delayMs:0..30000,fail:boolean}; never use it to perform real work. Acceptance is volatile, not success. No polling or restart resume.";
+export const MODE_INSTRUCTIONS = "你正在萧何模式中。这不是角色扮演。保留宿主 PTC 的日常工具能力与权限规则。普通编辑、搜索、命令、安装和其他工作使用原工具，不要声称此模式只读。execution_bus 是可选协调入口，只在以下情况使用：预计单次宿主操作超过约 30 秒；同一逻辑操作可能重复提交或需要重试核对（沿用 requestId）；任务需要在 run_code 时间预算结束后继续或取回结果；多个步骤需要等待同一执行。其余情况直接用原工具，不要为简单调用增加总线包装。实际业务 Handler 为 host.read、host.glob、host.grep（只读，可复用终态结果）与 host.edit、host.write、host.pwsh（有副作用，终态结果不可复用）；test 仅用于用户明确要求的诊断，不做真实工作。示例：await tools.execution_bus({protocolVersion:1,messageId:\"<消息编号>\",requestId:\"<逻辑操作编号>\",type:\"request\",payload:{handler:\"host.read\",input:{file_path:\"README.md\"}}})；messageId 每条消息唯一，同一逻辑操作重发沿用 requestId。通过 run_code 调用 await tools.execution_bus(...)，受原有时间预算约束。每会话排队上限 " +
     ADMISSION_DEFAULTS.sessionQueueLimit +
     "，排队超过 " +
     ADMISSION_DEFAULTS.maxQueueWaitMs / 1000 +

package/docs/PRODUCT.md

@@ -8,6 +8,8 @@
 
 0.9.0 增加 PTC 预算到期后的分离等待：宿主中断 PTC 子调用时，已受理执行只解除等待、继续运行，可用同 requestId 的 status/result 取回或用 cancel 取消；其他中断原因仍按取消处理。该区分依据 DSH 0.2.1-rc.2 的中断原因字符串，不是公开稳定契约，宿主升级需复核。
 
+0.10.0 改善模型侧的采用条件：模式说明写明仅在预计 >30 秒、可能重复提交、预算结束后继续或跨步骤等待同一执行时使用总线，并给出调用示例；工具声明把 payload 改为按 Handler 的判别联合，PTC SDK 与原生声明直接显示每个 Handler 的必填/可选字段。wire 协议、字段、错误码与 Handler 行为不变，只改变模型可见的提示与 schema。
+
 ## 入口及配置层次
 
 | 入口 | 谁使用 | 责任 |

package/docs/protocol.md

@@ -122,4 +122,6 @@ core 实例的 `diagnostics()` 返回只读用途的独立快照：阶段计数
 
 包的 `./core` 导出 ExecutionBus、Handler、Capability 类型。Handler 只接收输入、requestId、signal、progress 和可选最小 capability，不接收聊天历史。register 返回绑定唯一注册令牌的幂等注销函数，不会误删后来同名注册；已受理请求继续持有原 Handler。
 
+0.10.0 起，模型可见的工具体声明把 `payload` 改为按 Handler 的判别联合（每个 `host.*`/test 的 `input` 字段与必填项）；这是提示与 SDK 类型层的变化，wire 结构、校验、错误码与保存语义不变。
+
 内置 test、host.read、host.glob 与 host.grep 没有副作用；host.edit、host.write 与 host.pwsh 是非幂等写/命令 Handler，通过 `Handler.idempotent=false` 显式声明，其终态结果复用被 `MUTATING_REUSE_DENIED` 拒绝，运行中的重复附着仍只等待同一执行。0.8.0 新增宿主工具输入错误码 INVALID_GLOB_INPUT、INVALID_GREP_INPUT 与 INVALID_PWSH_INPUT；协议既有错误码不改名。host.pwsh 的后台结果只是宿主 Job ID，不是完成回执。当前没有 ctx.executionBus 服务、远端传输、跨插件动态注册或外部副作用对账契约。扩展有副作用 Handler 前必须显式声明幂等并另行设计授权与崩溃对账，不能仅依赖本版请求键。

package/docs/releases/0.10.0.md

@@ -0,0 +1,19 @@
+# 萧何 / Xiao He 0.10.0
+
+## 让总线可被采用：触发条件与类型化声明
+
+本版不改变执行机制，专门改善“模式被选中但总线从未被调用”的采用问题。
+
+- 模式说明新增明确触发条件：仅在预计单次宿主操作超过约 30 秒、同一逻辑操作可能重复提交（沿用 requestId）、任务需要在 `run_code` 时间预算结束后继续、或多个步骤需要等待同一执行时才使用总线；其余任务继续直接用原工具，并给出一条调用示例与 messageId/requestId 语义。
+- `execution_bus` 的模型可见参数从泛型 `payload: Record<string, JsonValue>` 改为按 Handler 的判别联合（`host.read` / `host.glob` / `host.grep` / `host.edit` / `host.write` / `host.pwsh` / `test` + 空控制 payload）。PTC SDK 与原生工具声明现在直接显示每个 Handler 的必填/可选字段；wire 结构、校验、错误码、状态机与 Handler 行为不变。
+- 工具描述同步写明触发条件与编号语义；诊断 Handler 仍标注仅用于明确诊断。
+- 代价：模型可见声明变大。模式说明 916 字符（+319），`execution_bus` 的 SDK 参数声明约 4.1KB（原泛型声明约 1.3KB）；是否换来更高的真实采用率与更好的结果，需要 pilot 与同任务 A/B 对照验证。
+- 新增 4 项回归（判别联合结构、合法/未知 Handler 校验、SDK 渲染、提示触发条件），并扩展真实 Node PTC 用例断言装配后的 SDK 含类型化声明。
+
+## 升级说明
+
+需要 DSH 0.2.1-rc.2。本版只有模型可见提示与工具 schema 变化；请求结构、字段、预设、工具名、错误码与 Handler 行为均不变。不自动安装、重写日常配置或重启 DSH。
+
+## 验证与限制
+
+本地全量 105 项测试通过。真实模型采用率、轮次/耗时收益未验证，需 pilot 与 A/B 对照；真实模型、桌面 UI 与实际沙箱仍未完整验收。若 pilot 显示声明开销不值得，可回退为较短的泛型声明。

package/docs/validation.md

@@ -1,6 +1,6 @@
 # 验证范围与使用限制
 
-本文说明当前版本的证据边界，不是生产环境认证。当前能力基线为 **v0.9.0**，在 0.5.0 的会话准入/排队、0.7.0 的宿主工具转发与 0.8.0 的搜索/命令 Handler 上，补入 PTC 预算到期后的分离等待；预设沿用 v0.3.0 的宿主 PTC 声明派生方式。验证环境为 Windows、Node.js 24.21.0，宿主组件锁定 DSH 0.2.1-rc.2、Cordis 4.0.4。
+本文说明当前版本的证据边界，不是生产环境认证。当前能力基线为 **v0.10.0**，在 0.5.0 的会话准入/排队、0.7.0 的宿主工具转发、0.8.0 的搜索/命令 Handler 与 0.9.0 的预算分离等待上，改善模型侧采用条件（触发说明、类型化工具声明）；预设沿用 v0.3.0 的宿主 PTC 声明派生方式。验证环境为 Windows、Node.js 24.21.0，宿主组件锁定 DSH 0.2.1-rc.2、Cordis 4.0.4。
 
 ## 已验证什么？
 
@@ -45,6 +45,7 @@ eb95b4e51675f5f1821275e0812ef4dd4984b1aba45a52fbc6bab3518bbf6f38
 | 从真实 tgz 经宿主插件管理器加载预设、卸载与回滚 | 未完成完整桌面流程；源码工作区的 Loader 测试不能替代 |
 | 真实 glob/grep/pwsh 工具实现 | 未在测试环境启用：真实搜索工具依赖打包 ripgrep 与 subprocess 服务，真实 pwsh 依赖 shell/sandbox/审批组合；本版只验证按 handler 名转发、输入校验、幂等分流与失败固定码 |
 | 跨版本 PTC 中断原因 | 分离等待只识别 DSH 0.2.1-rc.2 实际使用的固定中断原因字符串；宿主升级后未知原因保守按取消处理，需复核 |
+| 模式采用率与效果 | 未验证。0.10.0 只改善触发说明与工具声明可读性；真实模型是否更常使用总线、是否带来更少轮次/更短耗时，需要 pilot 与同任务 A/B 对照，不能由 schema 或测试推断 |
 | 磁盘会话结果提交及重启恢复原调用 | 未验收磁盘提交；本插件不支持跨重启恢复 |
 | 减少真实模型轮次、状态查询或总耗时的对照 | 未验证，不给提升比例 |
 | 长期运行、所有卸载/服务故障组合 | 未穷尽；持续故障仍有清理限制 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feng0531/dsh-execution-bus",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "private": false,
   "license": "SEE LICENSE IN LICENSE",