@feng0531/dsh-execution-bus 0.11.0 → 0.11.2

package/README.md

@@ -4,7 +4,7 @@
 
 “萧何”是产品与模式显示名，执行总线是其技术功能；不新增人物 Agent，不进行角色扮演。仓库 dsh-execution-bus、npm 包名、execution_bus 工具名及 execution-bus-test 预设 ID 保持不变。历史版本发布说明保留当时名称。
 
-DSH 独立插件：`@feng0531/dsh-execution-bus` · 当前版本 **0.11.0**
+DSH 独立插件：`@feng0531/dsh-execution-bus` · 当前版本 **0.11.2**
 
 > 萧何模式从宿主已声明的 PTC 组合派生，保留日常工具，再叠加可选执行总线。已验证隔离的真实 Node PTC → 原 read + 总线调用，以及脚本模型内存会话；真实模型、桌面界面与实际沙箱仍未验收。**不支持重启后恢复任务。**
 
@@ -130,7 +130,7 @@ flowchart TD
 2. 在你选定的隔离 DSH 配置依赖目录安装固定版本，不要在 DSH 程序安装目录执行：
 
    ```powershell
-   npm install --ignore-scripts @feng0531/dsh-execution-bus@0.11.0
+   npm install --ignore-scripts @feng0531/dsh-execution-bus@0.11.2
    ```
 
    这是 npm 目录示例。若目标配置使用 pnpm，应沿用其包管理器，不混用锁文件。遇到宿主 peer 版本冲突就停止，不用强制安装绕过。
@@ -203,6 +203,8 @@ PTC 是 DSH 的程序化工具调用入口。在 `run_code` 内使用 `await too
 
 **0.11.0 起，总线改为收益导向触发并支持简化调用。** 只在能获得协调收益时使用：同一逻辑操作可能重复提交或需要重试去重（沿用 requestId）、任务需要在 `run_code` 预算结束后继续/跨步骤取回、或多个步骤与等待者需要同一执行结果；**“操作耗时长”本身不是理由**，一次性长命令请用原工具或宿主后台 Job。工具入口支持简化调用 `{requestId, handler, input}`（messageId 可省略、自动生成）和控制 `{requestId, type:"status"|"result"|"cancel"}`，完整 v1 消息仍被接受；返回快照在复用时带 `reused: true`。工具声明仍是按 Handler 的判别联合，PTC SDK 与原生声明里可直接看到每个 Handler 的必填字段。
 
+**跨步骤取回的正确姿势（0.11.1 补充）：** 同一 `run_code` 程序内，未完成的 request 会阻塞后发工具调用的结果提交（宿主按提交顺序结算）；不要在同一个程序里“启动后立刻 status 轮询”。启动步骤只发请求并尽早结束程序，下一步再用同一 `requestId` 的 `status`/`result`（或重发同一 request）附着取回——pilot 实测单次执行、返回 `reused:true`。
+
 **0.9.0 起，预算到期不再连带取消已受理执行。** `run_code` 因时间预算到期或程序结束时，宿主会中断其中的工具子调用；总线把这种中断视为**只停止等待**：已受理执行与宿主 Job 继续，程序返回预算错误后，可在后续 `run_code` 中用同一 `requestId` 的 `status`/`result` 取回结果，或用 `cancel` 取消。用户主动中断、会话取消、沙箱模式变化等其他原因仍会请求取消整个执行。该识别依赖 DSH 0.2.1-rc.2 的中断原因字符串（见[宿主兼容性](<docs/host-compatibility.md>)），不是宿主公开稳定契约；进程退出仍会丢失全部内存状态，保留期一小时。
 
 ## 如何理解任务状态？
@@ -278,7 +280,7 @@ npm run test:install    # 临时目录安装，不操作日常 DSH
 
 - [协议和投递语义](<docs/protocol.md>)：字段、状态、重复处理与取消规则。
 - [宿主兼容性与源码调用链](<docs/host-compatibility.md>)：为什么可以等待，为什么不能跨重启恢复。
-- [验证记录](<docs/validation.md>)、[0.11.0 发布说明](<docs/releases/0.11.0.md>)：已验证与未验证范围。
+- [验证记录](<docs/validation.md>)、[0.11.2 发布说明](<docs/releases/0.11.2.md>)：已验证与未验证范围。
 - [同类项目源码整合](<docs/INTEGRATION.md>)：固定来源、采用范围、许可与验证边界。
 - [维护者发布流程](<docs/RELEASING.md>)：标签 CI、安装包校验与正式发布门禁。
 

package/dist/product.d.ts

@@ -200,5 +200,5 @@ export declare const STATE_PARAMETERS: {
     readonly properties: {};
     readonly additionalProperties: false;
 };
-export declare const REQUEST_DESCRIPTION = "\u8427\u4F55 / Xiao He. Submit a request and WAIT for its terminal snapshot; the simplified call takes {requestId, handler, input} (messageId optional) and control calls take {requestId, type:\"status\"|\"result\"|\"cancel\"}. Use only when coordination helps: the same logical operation may be retried or deduplicated (reuse requestId), work must outlive a run_code budget end, or multiple steps must await one execution. Duration alone is not a reason \u2014 for a one-off long command use the original tool or its background Job. A PTC program end only stops waiting: accepted work continues and the same requestId can be retrieved with type:\"result\" or cancelled. The snapshot may contain reused:true when this call attached to an existing execution. The full v1 envelope is still accepted. Diagnostic handler only: test {delayMs:0..30000,fail:boolean}; never use it for real work. Acceptance is volatile, not success. No polling or restart resume.";
+export declare const REQUEST_DESCRIPTION = "\u8427\u4F55 / Xiao He. Submit a request and WAIT for its terminal snapshot; the simplified call takes {requestId, handler, input} (messageId optional) and control calls take {requestId, type:\"status\"|\"result\"|\"cancel\"}. Use only when coordination helps: the same logical operation may be retried or deduplicated (reuse requestId), work must outlive a run_code budget end, or multiple steps must await one execution. Duration alone is not a reason \u2014 for a one-off long command use the original tool or its background Job. A PTC program end only stops waiting: accepted work continues and the same requestId can be retrieved with type:\"result\" or cancelled. Do not poll status inside the same run_code program as an unfinished request: end that program and retrieve in a later step. The snapshot may contain reused:true when this call attached to an existing execution. The full v1 envelope is still accepted. Diagnostic handler only: test {delayMs:0..30000,fail:boolean}; never use it for real work. Acceptance is volatile, not success. No polling or restart resume.";
 export declare const MODE_INSTRUCTIONS: string;

package/dist/product.js

@@ -146,8 +146,8 @@ export const STATE_PARAMETERS = {
     properties: {},
     additionalProperties: false,
 };
-export const REQUEST_DESCRIPTION = "萧何 / Xiao He. Submit a request and WAIT for its terminal snapshot; the simplified call takes {requestId, handler, input} (messageId optional) and control calls take {requestId, type:\"status\"|\"result\"|\"cancel\"}. Use only when coordination helps: the same logical operation may be retried or deduplicated (reuse requestId), work must outlive a run_code budget end, or multiple steps must await one execution. Duration alone is not a reason — for a one-off long command use the original tool or its background Job. A PTC program end only stops waiting: accepted work continues and the same requestId can be retrieved with type:\"result\" or cancelled. The snapshot may contain reused:true when this call attached to an existing execution. The full v1 envelope is still accepted. Diagnostic handler only: test {delayMs:0..30000,fail:boolean}; never use it for real work. Acceptance is volatile, not success. No polling or restart resume.";
-export const MODE_INSTRUCTIONS = "你正在萧何模式中。这不是角色扮演。保留宿主 PTC 的日常工具能力与权限规则。普通编辑、搜索、命令、安装和其他工作使用原工具，不要声称此模式只读。execution_bus 只在能获得协调收益时使用：① 同一逻辑操作可能重复提交或需要重试核对（沿用同一 requestId，只执行一次）；② 任务需要在 run_code 时间预算结束后继续或跨步骤取回；③ 多个步骤/等待者需要同一执行结果。仅\"操作耗时长\"不是理由：一次性长命令用原工具或宿主后台 Job。其余普通任务直接用原工具，不要为简单调用增加包装。实际业务 Handler 为 host.read、host.glob、host.grep（只读，可复用终态结果）与 host.edit、host.write、host.pwsh（有副作用，终态结果不可复用）；test 仅用于用户明确要求的诊断，不做真实工作。简化调用示例：await tools.execution_bus({requestId:\"<逻辑操作编号>\", handler:\"host.pwsh\", input:{description:\"运行测试\", command:\"pnpm test\", timeoutMs:120000}})；预算中断后用 await tools.execution_bus({requestId:\"<同一编号>\", type:\"result\"}) 取回；同一逻辑操作重发沿用 requestId，messageId 可省略（自动生成）。返回快照出现 reused:true 表示本次调用复用了已有执行。通过 run_code 调用，受原有时间预算约束。每会话排队上限 " +
+export const REQUEST_DESCRIPTION = "萧何 / Xiao He. Submit a request and WAIT for its terminal snapshot; the simplified call takes {requestId, handler, input} (messageId optional) and control calls take {requestId, type:\"status\"|\"result\"|\"cancel\"}. Use only when coordination helps: the same logical operation may be retried or deduplicated (reuse requestId), work must outlive a run_code budget end, or multiple steps must await one execution. Duration alone is not a reason — for a one-off long command use the original tool or its background Job. A PTC program end only stops waiting: accepted work continues and the same requestId can be retrieved with type:\"result\" or cancelled. Do not poll status inside the same run_code program as an unfinished request: end that program and retrieve in a later step. The snapshot may contain reused:true when this call attached to an existing execution. The full v1 envelope is still accepted. Diagnostic handler only: test {delayMs:0..30000,fail:boolean}; never use it for real work. Acceptance is volatile, not success. No polling or restart resume.";
+export const MODE_INSTRUCTIONS = "你正在萧何模式中。这不是角色扮演。保留宿主 PTC 的日常工具能力与权限规则。普通编辑、搜索、命令、安装和其他工作使用原工具，不要声称此模式只读。execution_bus 只在能获得协调收益时使用：① 同一逻辑操作可能重复提交或需要重试核对（沿用同一 requestId，只执行一次）；② 任务需要在 run_code 时间预算结束后继续或跨步骤取回；③ 多个步骤/等待者需要同一执行结果。仅\"操作耗时长\"不是理由：一次性长命令用原工具或宿主后台 Job。其余普通任务直接用原工具，不要为简单调用增加包装。实际业务 Handler 为 host.read、host.glob、host.grep（只读，可复用终态结果）与 host.edit、host.write、host.pwsh（有副作用，终态结果不可复用）；test 仅用于用户明确要求的诊断，不做真实工作。简化调用示例：await tools.execution_bus({requestId:\"<逻辑操作编号>\", handler:\"host.pwsh\", input:{description:\"运行测试\", command:\"pnpm test\", timeoutMs:120000}})；预算中断后用 await tools.execution_bus({requestId:\"<同一编号>\", type:\"result\"}) 取回；同一逻辑操作重发沿用 requestId，messageId 可省略（自动生成）。返回快照出现 reused:true 表示本次调用复用了已有执行。注意：同一 run_code 程序内，未完成的 request 会阻塞后发工具调用的结果提交；跨步骤取回请让启动步骤尽早结束程序，下一步再用同一 requestId 的 status/result 或重发 request；不要在同一程序里对未完成请求轮询状态。通过 run_code 调用，受原有时间预算约束。每会话排队上限 " +
     ADMISSION_DEFAULTS.sessionQueueLimit +
     "，排队超过 " +
     ADMISSION_DEFAULTS.maxQueueWaitMs / 1000 +

package/docs/protocol.md

@@ -74,6 +74,8 @@ PTC 程序结束（含 `run_code` 时间预算到期）时，宿主以固定原
 
 这条区分依据 DSH 0.2.1-rc.2 的内部中断原因字符串（`run_code settled`），不是宿主公开稳定契约；未知原因按取消处理。分离等待不改变内存与保留期边界：进程退出仍丢失全部状态，`returned` 仍不证明模型已取回结果。
 
+同一 PTC 程序内，未完成的 request 会阻塞后发工具调用的结果提交（宿主按提交顺序结算）。跨步骤取回应让启动步骤尽早结束程序，在后续步骤用同一 requestId 的 `status`/`result` 或重发同一 request 取回；不要在同一程序里对未完成请求轮询状态。
+
 错误也须分层：Handler 异常原文不进入保存结果，使用 HANDLER_FAILED 等固定码；不合法、过大或快照不可保存结果为 unknown / RESULT_NOT_RETAINED。宿主 wait/remove 等服务错误可能作为外层工具错误传出，不能笼统声称所有错误都已脱敏或都是固定码。不要把宿主服务错误文本当成业务执行失败凭据。
 
 ## 4. 容量、保存与关闭

package/docs/releases/0.11.1.md

@@ -0,0 +1,18 @@
+# 萧何 / Xiao He 0.11.1
+
+## 修正跨步骤取回说明（pilot 发现）
+
+本版只修正提示与文档，不改变执行机制。
+
+- pilot 发现：同一 PTC 程序内，未完成的 request 会阻塞后发工具调用的结果提交（宿主按提交顺序结算）；在同一程序里“启动后立刻 `status` 轮询”会实际阻塞到执行结束，而不是立即看到 running。
+- 模式说明与工具体描述补充正确姿势：启动步骤只发请求并尽早结束程序；下一步再用同一 requestId 的 `status`/`result` 或重发同一 request 附着取回；不要在同一程序里对未完成请求轮询状态。
+- `README` 与 `protocol.md` 同步该行为说明；无代码、协议、错误码或 Handler 行为变化。
+- 验证：全量 110 项测试通过（提示断言新增该模式的覆盖）。
+
+## 升级说明
+
+需要 DSH 0.2.1-rc.2。只影响模型可见提示与文档，不改变请求结构、状态机或结果语义。不自动安装或重启 DSH。
+
+## 验证与限制
+
+本地全量 110 项测试通过。该行为来自真实 PTC pilot 的组件观察（未做更大规模统计）；真实模型、桌面 UI 与实际沙箱仍未完整验收。

package/docs/releases/0.11.2.md

@@ -0,0 +1,16 @@
+# 萧何 / Xiao He 0.11.2
+
+## 修正 PTC 预算测试在 CI 的时序抖动
+
+- 0.11.1 的标签 CI 在 **windows-latest + Node 22** 上失败：真实 PTC 预算用例只给 `run_code` 2 秒预算，不足以覆盖 CI 冷启动 PTC 子进程的时间，导致“总线请求尚未受理就已超时”（测试夹具时序问题，不是产品缺陷）；因此 0.11.1 未发布。
+- 调整测试夹具：PTC 预算 2s→8s、被测命令 5s→12s、等待上限同步放宽，保证“已受理后预算到期”路径在慢速 CI 上稳定复现。本地连续 3 次通过。
+- 0.11.1 的提示与文档修正（同程序内不要对未完成请求轮询 status；启动步骤尽早结束程序、后续步骤用同 requestId 取回）一并包含在本版。
+- 无产品运行时代码、协议或 Handler 行为变化；全量 110 项测试通过。
+
+## 升级说明
+
+需要 DSH 0.2.1-rc.2。行为与 0.11.0 一致，仅修正提示/文档与测试时序。不自动安装或重启 DSH。
+
+## 验证与限制
+
+本地全量 110 项测试通过；PTC 预算/中断用例连跑 3 次通过。真实模型、桌面 UI 与实际沙箱仍未完整验收。

package/docs/validation.md

@@ -1,6 +1,6 @@
 # 验证范围与使用限制
 
-本文说明当前版本的证据边界，不是生产环境认证。当前能力基线为 **v0.11.0**，在 0.5.0 的会话准入/排队、0.7.0 的宿主工具转发、0.8.0 的搜索/命令 Handler、0.9.0 的预算分离等待与 0.10.0 的采用面改造上，收紧为收益导向触发并加入简化调用、复用标记与本地采用率统计；预设沿用 v0.3.0 的宿主 PTC 声明派生方式。验证环境为 Windows、Node.js 24.21.0，宿主组件锁定 DSH 0.2.1-rc.2、Cordis 4.0.4。
+本文说明当前版本的证据边界，不是生产环境认证。当前能力基线为 **v0.11.2**，在 0.5.0 的会话准入/排队、0.7.0 的宿主工具转发、0.8.0 的搜索/命令 Handler、0.9.0 的预算分离等待与 0.10.0 的采用面改造上，收紧为收益导向触发并加入简化调用、复用标记与本地采用率统计；0.11.1 仅补充跨步骤取回的正确姿势说明；预设沿用 v0.3.0 的宿主 PTC 声明派生方式。验证环境为 Windows、Node.js 24.21.0，宿主组件锁定 DSH 0.2.1-rc.2、Cordis 4.0.4。
 
 ## 已验证什么？
 

package/package.json

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