@feng0531/dsh-execution-bus 0.1.1 → 0.1.2

package/README.md

@@ -1,54 +1,112 @@
 # 执行总线 / Execution Bus
 
-DSH 独立插件 **@feng0531/dsh-execution-bus 0.1.1**，用于让模型提出一次执行请求后，由程序排队、等待和收集结果，而不是反复询问是否完成。
+**让模型发出一次执行请求，由程序负责排队、等待和收取结果。**
 
-**当前是第一阶段可运行原型、部分完成，不是完整生产验收。只做插件，不修改 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/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/package.json

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