@feng0531/dsh-execution-bus 0.1.0 → 0.1.2

package/README.md

@@ -1,54 +1,112 @@
 # 执行总线 / Execution Bus
 
-DSH 独立插件 **@feng0531/dsh-execution-bus 0.1.0**，用于让模型提出一次执行请求后，由程序排队、等待和收集结果，而不是反复询问是否完成。
+**让模型发出一次执行请求，由程序负责排队、等待和收取结果。**
 
-**当前是第一阶段可运行原型、部分完成，不是完整生产验收。只做插件，不修改 DSH。** 不增加模型或 Agent，不是工作流引擎、PTC 包装或任意命令执行服务，也不会改动其他插件。它不能解决模型理解错误、不断改变方案等所有推理问题。
+DSH 独立插件：`@feng0531/dsh-execution-bus` · 当前版本 **0.1.2**
 
-## 已实现
+> 当前是早期可运行版本，不是完整生产验收版。已验证真实 DSH 组件和脚本模型驱动的内存会话；真实模型、桌面界面和 PTC 完整链路尚未验收。**不支持重启后恢复任务。**
 
-- 版本化协议和运行时校验；有界 FIFO、并发限制、请求冲突检测、同请求执行复用。
-- 原工具调用异步等待终态；复用宿主 Job 进度、取消和等待，无模型轮询。
-- test：延迟、百分比、成功、失败、合作取消。
-- host.read：出队时通过宿主工具注册表调用现有 read，保留当前身份、工作目录、权限及输出限制，不自行读文件或启动进程。
-- 内存结果保存、大小限制、清理和关闭；失败日志不包含异常原文。
+## 它解决什么问题？
 
-## 明确不支持 / 未验证
+执行一个稍慢的任务时，模型不应该反复问“做完了吗”，也不应该因为等得久就重新执行。执行总线把这些协调工作交给程序：
 
-- 不持久化，不支持重启保留队列或恢复原工具调用，不自动重跑。
-- 真实 AgentLoop 内存会话提交/继续已通过脚本适配器验证；GUI 实际展示、真实模型继续推理、磁盘会话提交与 PTC 完整链路未验证。
-- 没有外部 Handler 传输、跨插件 Handler 服务、非幂等执行对账；不是全要求验收完成版。
+| 问题 | 执行总线的处理方式 |
+|---|---|
+| 请求提交后不知道是否接收 | 校验参数后受理；队列满则明确拒绝，不假装成功 |
+| 任务还没完成，模型反复查询 | 原工具调用保持异步等待，完成后才返回 |
+| 同一次请求重复提交 | 在同一会话、同一存活实例和保存期内，共用一次执行 |
+| 重复或迟到的进度到达 | 按序号处理，忽略旧进度和终态后的进度 |
+| 取消时不确定任务是否真的停了 | 区分“已请求取消”和“已确认取消” |
 
-详见 [宿主调用链与兼容性](docs/host-compatibility.md)、[协议和状态](docs/protocol.md)、[验证记录](docs/validation.md)。
+它只是**执行协调层**，不是新的模型或 Agent，不是工作流引擎，也不是对所有工具的全局拦截器。它不能解决模型理解错误、反复改变方案等推理问题。
 
-## 构建与测试
+## 它如何运作？
 
-需要 Node.js >=22（本次使用 24.21.0）和 npm。开发环境依赖安装限定本仓库，不触及日常 DSH。
+可以把它理解为一个“执行服务台”：会话递交带编号的请求，服务台排队，指定处理器执行，最后把回执交回原来的窗口。
 
-```powershell
-npm ci --ignore-scripts
-npm test
-npm run build
-npm pack --ignore-scripts
-npm run verify:package
-npm run test:install
+### 一次请求的完整流程
+
+```mermaid
+flowchart TD
+    A[DSH 会话中的模型提出请求] --> B[调用 execution_bus 工具]
+    B --> C{参数有效且容量允许?}
+    C -->|否| D[明确返回校验错误或背压错误]
+    C -->|是| E{同一会话已有相同 requestId?}
+    E -->|输入不同| F[拒绝请求编号冲突]
+    E -->|输入相同| G[复用已有执行或保存结果]
+    E -->|新请求| H[受理并进入内存队列]
+    H --> I[有空闲名额后分发给 Handler]
+    I --> J[测试处理器 或 宿主 read 工具管线]
+    J -.进度.-> K[宿主 Job 状态更新]
+    J --> L[记录最终执行状态与结果]
+    G --> M[原工具调用异步等待结果]
+    L --> M
+    M --> N[由 DSH 把结果提交给原工具调用]
+    N --> O[会话继续推理]
 ```
 
-标签 CI、四矩阵测试与受控发布见 [发布流程](docs/RELEASING.md)。采用[非商业源码公开许可证](LICENSE)，非 OSI 开源许可证；正式发布必须通过同标签 CI 和工作流门禁。发布不安装或重启 DSH。
+**图里的“等待”不是阻塞宿主线程，也不是让模型不断查询。** 工具返回的是一个尚未完成的异步操作，DSH 在它完成后继续。队列执行与等待同时进行；进度更新走宿主任务机制，不把每条进度变成聊天消息。
+
+若阅读器不支持 Mermaid，上图的主线是：
+
+```text
+模型提出请求 → 工具校验 → 内存排队 → Handler 执行
+                                         │
+                       进度 → 宿主 Job 状态
+                                         │
+原工具调用保持等待 ← 最终状态与结果 ←──────┘
+         │
+         └→ DSH 提交原调用结果 → 会话继续
+```
+
+### 谁负责什么？
+
+| 部分 | 责任 |
+|---|---|
+| 模型 | 提出请求，收到结果后继续判断 |
+| 执行总线 | 请求编号、排队、并发、重复请求、状态和结果保存 |
+| Handler（处理器） | 完成某一种具体工作，响应取消并报告进度 |
+| DSH 宿主 | 工具调用身份、权限、执行管线、Job 任务状态和原调用结果提交 |
+
+**受理 ≠ 执行成功，执行完成 ≠ 会话已经收到结果。** 插件只沿原工具调用返回，不通过追加聊天消息伪造恢复。
+
+## 现在能执行哪些任务？
+
+| Handler 名称 | 用途 | 输入 |
+|---|---|---|
+| `test` | 检查延迟、进度、成功、失败和取消 | `delayMs`：0–30000；`fail`：布尔值 |
+| `host.read` | 经由 DSH 现有 `read` 工具读取文本 | `file_path`；可选 `offset` 和 `limit`，最多 100 行 |
+
+`host.read` 在出队时重新进入宿主工具管线，沿用宿主当前权限、会话工作目录及输出限制。插件不自行启动命令、不提供任意远程执行服务。它也不会强制将现有工具改成总线调用。
+
+## 安装前先确认
+
+- 兼容目标：**DSH 0.2.0-rc.2 / Cordis 4.0.4**，Node.js 22 或以上。其他宿主版本未承诺兼容。
+- 建议先选择**隔离的 DSH 配置**试用，不直接更改日常环境。
+- 目标组合需要可见的工具注册表、Job 服务、现有 Job 控制工具；读取任务还需要宿主 `read`。
+- 安装 npm 包不等于插件已经加载；**只有当前会话能看到 `execution_bus` 工具，才可直接调用。**
+
+### 安装步骤
 
-测试会在隔离 Cordis 上下文运行真实宿主组件；Agent 身份为夹具，不调用真实模型。安装包只含编译入口、类型与文档，不包含宿主源码快照、测试环境或 node_modules。源码构建需要整个仓库。
+1. 备份目标配置、依赖声明和锁文件，记录当前插件清单。
+2. 在你选定的隔离 DSH 配置依赖目录安装固定版本，不要在 DSH 程序安装目录执行：
 
-## 安装：仅在你明确决定的隔离 DSH 配置中
+   ```powershell
+   npm install --ignore-scripts @feng0531/dsh-execution-bus@0.1.2
+   ```
 
-本次**未安装到你的 DSH**。兼容目标精确为 DSH 0.2.0-rc.2 / Cordis 4.0.4；先确认你要操作的配置目录和宿主实际版本。不要向运行时安装目录复制文件或修改 ASAR。
+   这是 npm 目录示例。若目标配置使用 pnpm，应沿用其包管理器，不混用锁文件。遇到宿主 peer 版本冲突就停止，不用强制安装绕过。
 
-1. 备份目标配置文件、依赖声明和 lockfile，记录当前插件清单。先停止目标隔离实例的工作，不动日常会话。
-2. 在隔离配置的依赖目录安装本地 tgz，禁用生命周期脚本；避免升级宿主依赖。若 peer 不匹配，停止安装，不用 force/legacy-peer-deps 绕过。
-3. 在目标实例已有的插件加载配置中加入包名。必须位于可见 tools、jobs、现有 tool-jobs controller 和 read 的组合内。包导出标准 Cordis name / inject / apply；不提供未验证的全局配置键。
-4. 由使用者自行启动/重载隔离实例，确认 execution_bus 工具可见。配置结构随宿主组合而异，不承诺“一条配置适用于所有版本”。
+3. 在该实例现有插件加载配置中加入包名，并放在具备上述服务的组合内。配置结构依宿主组合而定，本项目不提供未经验证的通用配置键。
+4. 按宿主正常方式加载，由你决定是否需要重载或重启。确认本会话出现 `execution_bus` 后再测试。
 
-## 使用
+**发布或本仓库测试不会替你安装、升级或重启 DSH，也不需要修改 DSH 源码或 ASAR。**
 
-直接工具入口 execution_bus 的请求参数：
+## 先跑一个例子
+
+插件加载后，让 Agent 调用 `execution_bus`，参数如下。它会等待处理器完成，而不是立即只返回任务编号。
+
+### 例一：约一秒后成功
 
 ```json
 {
@@ -56,22 +114,116 @@ npm run test:install
   "messageId": "message-001",
   "requestId": "operation-001",
   "type": "request",
-  "payload": {"handler": "test", "input": {"delayMs": 1000, "fail": false}}
+  "payload": {
+    "handler": "test",
+    "input": { "delayMs": 1000, "fail": false }
+  }
 }
 ```
 
-调用会等待约一秒，再返回 succeeded 等终态，不需要 status 循环。真实只读任务把 payload 改为 {"handler":"host.read","input":{"file_path":"README.md","limit":20}}，路径相对于可信宿主会话工作目录。
+完成后，返回值中的 `state` 为 `succeeded`，`result` 为 `{ "ok": true }`。把 `fail` 改成 `true` 并使用新的 `requestId`，可以验证失败路径。不要为了等待这个例子而循环调用 `status`。
+
+### 例二：读取会话工作目录中的文本
+
+保留上面的消息结构，使用新的消息编号和请求编号，将 `payload` 改为：
+
+```json
+{
+  "handler": "host.read",
+  "input": { "file_path": "README.md", "limit": 20 }
+}
+```
+
+相对路径由宿主当前会话工作目录解析，不由模型指定新的工作目录或权限。读取敏感文件的内容仍可能进入宿主会话记录，请只请求确有需要的内容。
+
+### 两种编号不要混淆
+
+- **`messageId`：这条消息的编号。** 新的请求消息或控制消息使用新的编号。
+- **`requestId`：这一次逻辑操作的编号。** 同一次操作重发沿用它；不同操作必须换编号，即使参数完全相同。
+
+同一 `requestId` 搭配不同输入会被拒绝；不同会话不能读取或取消彼此的任务。重复执行保护仅在当前插件实例和保存期内有效，不是永久保证。
 
-若当前 DSH 是 PTC 模式，在 run_code 内 await tools.execution_bus(同上对象)，而非直接工具调用；这不会解除 run_code 的时间预算。PTC 端到端尚未验收。
+### 查询、重取和取消
 
-手工查询/重取/取消：保留 requestId，换新 messageId，type 改为 status / result / cancel，payload 为 {}。不同会话无法读取或取消其他会话请求。cancelRequested 不等于已取消；读取执行状态字段判断。不要因为等待或通信超时就换 requestId 重新执行。
+这三个入口用于人工诊断或恢复当前实例中的结果，**不是正常执行所需的模型轮询步骤**：
+
+```json
+{
+  "protocolVersion": 1,
+  "messageId": "message-002",
+  "requestId": "operation-001",
+  "type": "cancel",
+  "payload": {}
+}
+```
+
+将 `type` 换成 `status` 查询状态，换成 `result` 重取保存结果。取消中的任务要看最终 `state`；`cancelRequested: true` 只表示取消请求已经发出，不表示任务已停止或副作用已撤销。
+
+### 如果宿主使用 PTC 模式
+
+PTC 是 DSH 的程序化工具调用入口。在 `run_code` 内使用 `await tools.execution_bus(请求对象)`，而不是直接调用折叠后的工具名。执行总线不会解除 `run_code` 自身的时间预算；PTC 完整进程链路尚未验收。
+
+## 如何理解任务状态？
+
+```mermaid
+stateDiagram-v2
+    [*] --> queued: 已受理并排队
+    queued --> running: 开始执行
+    queued --> cancelled: 排队时确认取消
+    running --> succeeded: 执行成功且结果可保存
+    running --> failed: 执行异常
+    running --> cancelled: 处理器确认取消
+    running --> unknown: 结果不可保存或取消结果不明确
+```
+
+| 状态 | 含义 |
+|---|---|
+| `queued` | 已受理，尚未执行；不代表成功 |
+| `running` | 正在执行；等待窗口超时不自动把它变成失败 |
+| `succeeded` | 执行成功且总线保存了结果 |
+| `failed` | 处理器执行失败 |
+| `cancelled` | 已确认取消 |
+| `unknown` | 不能可靠保留或确认结果，不可盲目重跑有副作用操作 |
+
+执行终态不会再改成另一个终态。取消与成功竞争时，若处理器最终正常返回，仍可能是成功。`delivery` 是另一个字段：`pending` 表示尚未走到返回标记，`returned` 只表示插件已走到工具返回路径，**不证明会话结果已经写入磁盘或模型已经消费**。
+
+## 容量与重要限制
+
+默认并发 **2**，排队上限 **32**，最多保存 **256** 条任务记录，单结果最多 **64 KiB**，完成结果保存 **1 小时**，在新请求和查询时清理过期记录。队列或记录满时拒绝新任务；宿主 Job 自身也有容量限制。
+
+- **全部状态在内存中。** 受理没有落盘，插件关闭或进程崩溃后，不能依靠它恢复原调用或保证请求不丢失。
+- **不自动重跑任务。** 通信超时不等于执行失败，取消不等于回滚。
+- **不承诺端到端 exactly-once。** 当前实例的请求复用不能代替外部副作用对账。
+- 当前没有远端执行端、跨插件 Handler 注册服务或非幂等操作对账能力。
+- 未证明真实模型轮次、主动查询次数或总耗时的提升比例。
+
+## 不安装也能测试吗？
+
+可以。开发者在本仓库运行：
+
+```powershell
+npm ci --include=dev --ignore-scripts
+npm run test:flow       # 流程回归 + 真实宿主组件 + 脚本模型驱动的 AgentLoop
+npm run check           # 全量编译和测试
+npm run verify:package  # 检查公开包内容
+npm run test:install    # 临时目录安装，不操作日常 DSH
+```
+
+这些测试不等于“当前聊天会话直接调用插件”。真实 AgentLoop 测试使用脚本模型适配器；工具组件测试使用测试 Agent。具体边界见[流程测试说明](<docs/FLOW-TEST.md>)。构建候选安装包可运行 `npm run pack:candidate`。
 
 ## 卸载与回滚
 
-先停止新请求并等待已有操作终态，或请求合作取消。然后从目标隔离实例插件加载配置移除包名，按宿主正常生命周期卸载；卸载会取消并等待本插件受理的任务。不要强杀并假定外部操作已回滚。
+先停止新请求，等待已有任务完成或请求合作取消，再从目标实例加载配置中移除插件，按宿主生命周期卸载。不要强杀后假定外部工作已撤销。
+
+若试用失败，恢复安装前备份的配置、依赖声明和锁文件，由你决定何时重新加载实例。内存结果会丢失；宿主已有会话日志不属于本插件卸载范围，不要删除。
+
+## 进一步阅读
 
-若首次试用失败，恢复前述配置/依赖/锁文件备份，再由使用者自行启动目标实例。tgz 不写宿主文件、系统服务、全局命令或磁盘任务库，无专属磁盘数据迁移。进程关闭会丢失内存结果；宿主已有会话日志不在插件卸载范围内，不删除它们。
+- [协议和投递语义](<docs/protocol.md>)：字段、状态、重复处理与取消规则。
+- [宿主兼容性与源码调用链](<docs/host-compatibility.md>)：为什么可以等待，为什么不能跨重启恢复。
+- [验证记录](<docs/validation.md>)、[0.1.2 发布说明](<docs/releases/0.1.2.md>)：已验证与未验证范围。
+- [维护者发布流程](<docs/RELEASING.md>)：标签 CI、安装包校验与正式发布门禁。
 
-## 减少反复的验证
+## 许可
 
-真实模型参与轮次、主动状态查询次数、重复执行次数和总耗时对照：**未验证**，不提供提升比例。自动化测试只证明等待和状态机制，不替代同条件真实模型对比。
+采用[非商业源码公开许可证](<LICENSE>)，**不是 OSI 开源许可证**。商业项目内部使用及有偿交付需要另行书面授权；第三方独立依赖仍受各自原许可证约束。

package/dist/bus.js

@@ -41,6 +41,14 @@ export function parse(raw) {
         throw Error("MESSAGE_TOO_LARGE");
     return structuredClone(m);
 }
+function freezeJson(value) {
+    if (value && typeof value === "object") {
+        for (const child of Object.values(value))
+            freezeJson(child);
+        Object.freeze(value);
+    }
+    return value;
+}
 const terminal = (s) => !["queued", "running"].includes(s);
 /** Volatile single-process bus; no acceptance durability or automatic execution retry. */
 export class ExecutionBus {
@@ -206,6 +214,7 @@ export class ExecutionBus {
             throw Error("EXPECTED_CONTROL");
         if (Object.keys(m.payload).length)
             throw Error("INVALID_CONTROL");
+        this.sweep();
         const e = this.get(owner, m.requestId);
         const previous = e.messages.get(m.messageId), fingerprint = canonical(m);
         if (previous && previous !== fingerprint)
@@ -240,7 +249,7 @@ export class ExecutionBus {
         if (error)
             e.view.error = error;
         this.emit(e, state, { state });
-        e.resolve(this.view(e));
+        e.resolve(freezeJson(this.view(e)));
         e.listeners.clear();
     }
     pump() {
@@ -278,7 +287,14 @@ export class ExecutionBus {
                     this.emit(e, "progress", { percent: pct });
                 },
             });
-            const json = JSON.stringify(result);
+            let json;
+            try {
+                json = JSON.stringify(result);
+            }
+            catch {
+                this.finish(e, "unknown", undefined, "RESULT_NOT_RETAINED");
+                return;
+            }
             if (json === undefined ||
                 Buffer.byteLength(json) > this.options.resultBytes) {
                 this.finish(e, "unknown", undefined, "RESULT_NOT_RETAINED");

package/docs/FLOW-TEST.md

@@ -0,0 +1,38 @@
+# 不安装插件的流程测试
+
+## 本次执行方式与边界
+
+当前会话没有 execution_bus 工具，桌面配置未安装本插件。本次由当前会话运行测试命令，在独立进程中加载本仓库编译产物及真实 DSH npm 组件；不修改日常配置、不热注入运行宿主、不重启 DSH。
+
+这能验证真实 AgentLoop、SessionStore、ToolRuntime、Job 与 read 组件路径；不等于本会话实际调用 execution_bus，不验证真实桌面 UI、PTC 进程或真实模型。真实 AgentLoop 测试使用脚本模型适配器，read 组件测试使用测试 Agent 身份。两条测试不能合称当前会话端到端通过。
+
+## 重复运行
+
+1. npm ci --include=dev --ignore-scripts
+2. npm run test:flow：流程回归、真实宿主执行组件、真实 AgentLoop 原调用结果关联。
+3. npm run check：包含核心队列、安全和发布门禁的全部测试。
+4. npm run verify:package：包白名单。
+
+流程包括：正常成功/失败、读文件、权限拒绝、匿名请求拒绝、重复请求只新增一个 Job、工具取消、插件关闭、进度不作为聊天消息、原调用只提交一次后才继续下一模型适配器请求。
+
+## 本次可复现问题
+
+| 问题 | 修复前证据 | 本地修复 | 影响范围 |
+|---|---|---|---|
+| core 返回的 done 结果对象共享且可修改 | 第一个消费者将 state/result 改写后，第二次同请求取得被修改值 | 深度冻结终态快照 | core 扩展接入；不能据此声称模型能修改宿主冻结结果 |
+| Handler 完成但结果 JSON.stringify 抛错被记为 failed | 返回 BigInt 的一次执行被误记 failed | 保存异常为 unknown / RESULT_NOT_RETAINED，不重跑 | 当前内置只读/测试返回值正常；扩展 Handler 有风险 |
+| 结果超期查询未检查 TTL | 无新 request 时，过期 result 仍可读 | command 查询前 sweep | 查询/重取/取消均遵守结果保存期 |
+
+三个测试在修复前均失败；修复后全量 24/24 通过。这些修复归入 0.1.1 补丁发布；不改变已有 0.1.0 标签或公开包。发布状态以 GitHub Release 和 npm 公开结果为准。
+
+## 优化建议
+
+1. 已优化：终态结果不可变；保存失败明确区分执行失败；查询触发 TTL 回收，无常驻清理定时器。
+2. 后续可优化：完成请求重取无需新建短暂 Job；现在不会重复执行，但会产生不必要的 UI 生命周期事件。
+3. 后续可优化：每个重复附着仍注册一个空进度监听器；可将进度观察者绑定到共享逻辑请求，避免消耗 32 个监听者限额。
+4. 后续可优化：宿主 read 取消错误仍统一映射 HOST_READ_FAILED，保守归为 unknown。应保留经过白名单验证的取消类型，而不泄露原始异常文本。
+5. 不建议盲目改动：取消一个附着工具会请求取消整个逻辑执行，是当前明确语义；改成仅取消等待者需要单独设计宿主 drain、Job 通知和结果留存，不能只 Promise.race 后抛弃原执行。
+
+## 真实当前会话测试前提
+
+只有宿主通过正常插件加载向当前 Agent 注册工具后，才可能真正执行 await tools.execution_bus。当前没有暴露可用的临时插件注册工具，不能用额外 Node 进程、伪造 sessionId 或追加聊天结果来替代。若后续要测试真实当前会话，需要另行授权安装/加载并确认工具可见；本次未执行安装。

package/docs/RELEASING.md

@@ -14,7 +14,7 @@
 
 ## 发布门禁
 
-用户已授权 0.1.0 正式发布，并确认沿用 dsh-vcs 的非商业源码公开许可证。该许可不是 OSI 开源许可证，限制商业项目内部使用与有偿交付，具体以 LICENSE 为准。后续发布仍需明确授权与工作流确认，不表示实际模型验收通过。
+用户已授权 0.1.0 正式发布，并确认沿用 dsh-vcs 的非商业源码公开许可证。该许可不是 OSI 开源许可证，限制商业项目内部使用与有偿交付，具体以 LICENSE 为准。用户已持续授权本项目每轮改动完成并验证通过后主动正式发布，无需逐次提醒；仍必须通过工作流确认与完整门禁，不表示实际模型验收通过。版本采用 vX.Y.Z：X 大版本、Y 小版本/新增功能、Z BUG 修复；发布不自动安装或重启 DSH。
 
 准备正式发布前：由用户明确授权；确定 LICENSE 与包 license 字段；检查公开材料、第三方许可和敏感信息；更新版本、锁文件与发布说明；提交并推送已批准的版本标签；等待四矩阵通过。
 

package/docs/releases/0.1.0.md

@@ -14,4 +14,4 @@
 
 ## 验证
 
-真实宿主组件与 AgentLoop 内存会话采用脚本模型隔离测试；不能当作真实模型端到端通过。具体本地测试数与检查结果见 docs/validation.md。GitHub Actions 四矩阵及正式发布尚未执行。
+真实宿主组件与 AgentLoop 内存会话采用脚本模型隔离测试；不能当作真实模型端到端通过。具体本地测试数与检查结果见 docs/validation.md。2026-10-15 正式发布完成：Windows/Ubuntu × Node 22/24 四项标签 CI 全部通过，发布工作流成功。npm latest 为 0.1.0；npm 与 GitHub 实际下载包均为 22,017 字节，与候选逐字节一致，SHA-256 为 9b5f57d829c2238d0bed8548e17633a67b15a5358b792df0d492071a261529ce。

package/docs/releases/0.1.1.md

@@ -0,0 +1,18 @@
+# 执行总线 0.1.1
+
+## 本版变化
+
+本版为 BUG 修复，无新增业务执行能力。
+
+- 修复 core 多个结果消费者共享可修改终态快照，可能污染后续重复请求结果的问题；终态快照改为深度冻结。
+- 修复 Handler 已完成但返回值无法 JSON 序列化时被误记执行失败的问题；记录为 unknown / RESULT_NOT_RETAINED，不自动重跑。
+- 修复没有新请求时过期结果仍能查询/重取的问题；控制消息入口补上 TTL 清理。
+- 增加不安装插件的可复用流程测试命令 npm run test:flow，以及三项修复前失败、修复后通过的回归测试。
+
+## 安装与许可
+
+npm 包 @feng0531/dsh-execution-bus@0.1.1，兼容目标 DSH 0.2.0-rc.2；建议先用隔离配置。非商业源码公开许可，具体以 LICENSE 为准。发布不自动安装、升级或重启日常 DSH。
+
+## 验证与限制
+
+本地全量 24/24 测试通过；真实宿主组件、AgentLoop 内存会话均为隔离测试，模型侧使用脚本适配器，不等于当前会话直接调用 execution_bus。真实模型、GUI、PTC 和桌面沙箱未验收；不持久化、不支持跨重启恢复。正式发布仍需同标签四矩阵 CI、包白名单、候选一致性、隔离安装与公开 npm 包核验全部通过。

package/docs/releases/0.1.2.md

@@ -0,0 +1,20 @@
+# 执行总线 0.1.2
+
+## 本版变化
+
+文档易用性补丁，不改变插件执行逻辑或工具参数。
+
+- 按使用者阅读顺序重写 README：用途、运作方式、安装、示例、状态、限制、测试和回滚。
+- 新增请求处理流程图及状态转换图，并提供纯文本流程，方便不支持 Mermaid 的阅读器。
+- 用服务台类比解释 Handler、模型、执行总线与宿主的职责；区分受理成功、执行完成和结果交付。
+- 补全请求编号与消息编号、真实只读示例、取消语义、PTC 入口和“不安装测试”的边界。
+
+## 安装与限制
+
+固定版本包 @feng0531/dsh-execution-bus@0.1.2。兼容目标仍为 DSH 0.2.0-rc.2，非商业源码公开许可。不会自动安装或重启 DSH。
+
+非持久化，不支持跨重启恢复原调用；真实模型、桌面界面、沙箱与 PTC 完整链路仍未验收，流程图不表示这些能力已实测。
+
+## 验证
+
+沿用完整测试与标签四矩阵 CI、包内容检查、生产依赖隔离安装和两端公开包一致性门禁。图示根据现有工具等待及状态实现核对；GitHub 页面实际 Mermaid 渲染不作为宿主 GUI 验收。

package/docs/validation.md

@@ -40,7 +40,7 @@ npm test：**21/21 通过**。本地 tgz 已在 artifacts/package-check 独立
 
 参考 dsh-vcs 配置标签/手动 CI：Windows/Ubuntu × Node 22/24；普通分支和 PR 不触发。新增版本/锁文件/标签一致性、包严格白名单、全新临时目录生产依赖安装、工作流 YAML 契约和许可证缺失拒绝测试。本地 Windows/Node 24 的 check、verify:package、pack:candidate、test:install 通过，npm audit 为 0 漏洞。
 
-发布仅手动确认后运行，需精确标签 CI 成功且四份候选与重建包逐字节一致；先 npm 上传并验证公开实际字节，再创建 GitHub Release。用户已确认非商业许可证并授权正式发布；预检仍验证明确确认词及完整 LICENSE。远端 CI、Actions environment 审批和真实发布均未执行。
+发布仅手动确认后运行，需精确标签 CI 成功且四份候选与重建包逐字节一致；先 npm 上传并验证公开实际字节，再创建 GitHub Release。用户已确认非商业许可证并授权正式发布；预检仍验证明确确认词及完整 LICENSE。2026-10-15：v0.1.0 标签 CI 四矩阵成功（运行 38705851984），联合发布成功（38706021548）。GitHub Release 非草稿、非预发布；npm latest 为 0.1.0。公开 npm/GitHub 包均为 22,017 字节，与候选逐字节一致，SHA-256：9b5f57d829c2238d0bed8548e17633a67b15a5358b792df0d492071a261529ce。npm-release 环境此前不存在，未配置维护者保护审批，发布使用用户授权及工作流明确确认门禁。
 
 ## 已完成 / 部分完成 / 后续
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feng0531/dsh-execution-bus",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "private": false,
   "license": "SEE LICENSE IN LICENSE",
@@ -27,6 +27,7 @@
     "test": "npm run build && node --test test/*.test.mjs",
     "pack": "npm pack",
     "check": "npm test",
+    "test:flow": "npm run build && node --test test/flow-regression.test.mjs test/host.test.mjs test/agent-loop.test.mjs",
     "prepack": "npm run check && npm run verify:package",
     "verify:package": "node scripts/verify-package.mjs",
     "test:install": "node scripts/test-install.mjs",