@feng0531/dsh-execution-bus 0.4.0 → 0.4.1

package/README.md

@@ -4,7 +4,7 @@
 
 “萧何”是产品与模式显示名，执行总线是其技术功能；不新增人物 Agent，不进行角色扮演。仓库 dsh-execution-bus、npm 包名、execution_bus 工具名及 execution-bus-test 预设 ID 保持不变。历史版本发布说明保留当时名称。
 
-DSH 独立插件：`@feng0531/dsh-execution-bus` · 当前版本 **0.4.0**
+DSH 独立插件：`@feng0531/dsh-execution-bus` · 当前版本 **0.4.1**
 
 > 萧何模式从宿主已声明的 PTC 组合派生，保留日常工具，再叠加可选执行总线。已验证隔离的真实 Node PTC → 原 read + 总线调用，以及脚本模型内存会话；真实模型、桌面界面与实际沙箱仍未验收。**不支持重启后恢复任务。**
 
@@ -115,7 +115,7 @@ flowchart TD
 2. 在你选定的隔离 DSH 配置依赖目录安装固定版本，不要在 DSH 程序安装目录执行：
 
    ```powershell
-   npm install --ignore-scripts @feng0531/dsh-execution-bus@0.4.0
+   npm install --ignore-scripts @feng0531/dsh-execution-bus@0.4.1
    ```
 
    这是 npm 目录示例。若目标配置使用 pnpm，应沿用其包管理器，不混用锁文件。遇到宿主 peer 版本冲突就停止，不用强制安装绕过。
@@ -250,7 +250,7 @@ npm run test:install    # 临时目录安装，不操作日常 DSH
 
 - [协议和投递语义](<docs/protocol.md>)：字段、状态、重复处理与取消规则。
 - [宿主兼容性与源码调用链](<docs/host-compatibility.md>)：为什么可以等待，为什么不能跨重启恢复。
-- [验证记录](<docs/validation.md>)、[0.4.0 发布说明](<docs/releases/0.4.0.md>)：已验证与未验证范围。
+- [验证记录](<docs/validation.md>)、[0.4.1 发布说明](<docs/releases/0.4.1.md>)：已验证与未验证范围。
 - [维护者发布流程](<docs/RELEASING.md>)：标签 CI、安装包校验与正式发布门禁。
 
 ## 许可

package/dist/bus.d.ts

@@ -55,6 +55,7 @@ export declare class ExecutionBus {
     private queue;
     private readyOwners;
     private running;
+    private retainedResultBytes;
     private closed;
     private telemetry;
     diagnostics(): {

package/dist/bus.js

@@ -61,6 +61,7 @@ export class ExecutionBus {
     queue = [];
     readyOwners = [];
     running = 0;
+    retainedResultBytes = 0;
     closed = false;
     telemetry = new Diagnostics();
     diagnostics() {
@@ -70,10 +71,7 @@ export class ExecutionBus {
             queued: this.queue.length,
             running: this.running,
             records: this.entries.size,
-            retainedResultBytes: [...this.entries.values()].reduce((sum, e) => sum +
-                (e.view.result === undefined
-                    ? 0
-                    : Buffer.byteLength(JSON.stringify(e.view.result))), 0),
+            retainedResultBytes: this.retainedResultBytes,
         };
     }
     closing;
@@ -173,8 +171,11 @@ export class ExecutionBus {
     }
     sweep(now = Date.now()) {
         for (const [k, e] of this.entries)
-            if (terminal(e.view.state) && now - e.created > this.options.retentionMs)
+            if (terminal(e.view.state) &&
+                now - e.created > this.options.retentionMs) {
+                this.retainedResultBytes -= e.resultBytes;
                 this.entries.delete(k);
+            }
     }
     submit(owner, raw, onEvent, invoke) {
         if (this.closed)
@@ -216,6 +217,7 @@ export class ExecutionBus {
         const done = new Promise((r) => (resolve = r));
         e = {
             trace: this.telemetry.begin(),
+            resultBytes: 0,
             invoke,
             correlationId: m.messageId,
             owner: owner.sessionId,
@@ -319,7 +321,7 @@ export class ExecutionBus {
             this.finish(e, "cancelled");
         }
     }
-    finish(e, state, result, error) {
+    finish(e, state, result, error, resultBytes = 0) {
         if (terminal(e.view.state))
             return;
         // Prepare the delivery snapshot BEFORE committing an irreversible terminal state.
@@ -334,6 +336,7 @@ export class ExecutionBus {
         }
         catch {
             state = "unknown";
+            resultBytes = 0;
             next = {
                 requestId: e.view.requestId,
                 state,
@@ -344,6 +347,8 @@ export class ExecutionBus {
             };
             snapshot = freezeJson({ ...next });
         }
+        e.resultBytes = resultBytes;
+        this.retainedResultBytes += resultBytes;
         e.created = Date.now();
         e.view = { ...next, sequence: next.sequence - 1 };
         this.telemetry.record(e.trace, "terminal");
@@ -413,7 +418,7 @@ export class ExecutionBus {
                 this.finish(e, "unknown", undefined, "RESULT_NOT_RETAINED");
                 return;
             }
-            this.finish(e, "succeeded", JSON.parse(json));
+            this.finish(e, "succeeded", JSON.parse(json), undefined, Buffer.byteLength(json));
         }
         catch (err) {
             const cancelled = e.controller.signal.aborted &&
@@ -448,6 +453,7 @@ export class ExecutionBus {
             await Promise.all(entries.map((e) => e.done));
             this.handlers.clear();
             this.entries.clear();
+            this.retainedResultBytes = 0;
             this.queue = [];
             this.readyOwners = [];
             this.shutdownPhase = "closed";

package/dist/diagnostics.d.ts

@@ -8,6 +8,8 @@ export interface Trace {
 export declare class Diagnostics {
     private next;
     private events;
+    private cursor;
+    private size;
     private counts;
     begin(): {
         operation: number;

package/dist/diagnostics.js

@@ -2,25 +2,29 @@ import { performance } from "node:perf_hooks";
 /** In-memory numeric metadata only: never accepts request/session strings, input, output or error text. */
 export class Diagnostics {
     next = 0;
-    events = [];
+    events = new Array(128);
+    cursor = 0;
+    size = 0;
     counts = {};
     begin() {
         return { operation: ++this.next, at: performance.now() };
     }
     record(context, stage) {
         this.counts[stage] = (this.counts[stage] ?? 0) + 1;
-        this.events.push({
+        this.events[this.cursor] = {
             operation: context.operation,
             stage,
             elapsedMs: Math.max(0, performance.now() - context.at),
-        });
-        if (this.events.length > 128)
-            this.events.shift();
+        };
+        this.cursor = (this.cursor + 1) % 128;
+        this.size = Math.min(this.size + 1, 128);
     }
     snapshot() {
         return {
             counts: { ...this.counts },
-            traces: this.events.map((e) => ({ ...e })),
+            traces: Array.from({ length: this.size }, (_, index) => ({
+                ...this.events[(this.cursor - this.size + 128 + index) % 128],
+            })),
         };
     }
 }

package/docs/GITHUB-COMPARISON.md

@@ -0,0 +1,38 @@
+# GitHub 源码对比与诊断优化
+
+## 调研范围
+
+本轮对比萧何 v0.4.0（55e1d66）的队列生命周期、事件通知和诊断成本。通过 GitHub 仓库检索及 raw 源码读取，使用以下固定标签，不把 star 数作为质量证明，也未构建这些项目。
+
+| 项目 | 实际查看内容 | 对萧何的结论 |
+|---|---|---|
+| [p-queue v8.1.0 实现](https://github.com/sindresorhus/p-queue/blob/v8.1.0/source/index.ts)与[测试](https://github.com/sindresorhus/p-queue/blob/v8.1.0/test/test.ts) | pending 计数、onEmpty/onIdle、abort 与 finally | 对照检查排队为空不等于运行结束；保留萧何合作取消后排空语义，不引入其超时/取消竞速直接释放槽位的行为 |
+| [EventEmitter3 5.0.1 实现](https://github.com/primus/eventemitter3/blob/5.0.1/index.js)与[测试](https://github.com/primus/eventemitter3/blob/5.0.1/test/test.js) | emit 前保存监听数组长度，移除重建监听列表 | 支持为派发明确边界；萧何 0.4.0 已有批次快照、解除后跳过和嵌套事件顺序，保持自己的公开契约，不换库 |
+| [Denque v2.1.0 实现](https://github.com/invertase/denque/blob/v2.1.0/index.js)与[测试](https://github.com/invertase/denque/blob/v2.1.0/test/denque.js) | head/tail 索引、容量和环绕行为 | 用同类索引思想自行实现固定 128 槽诊断环，不搬可增长 deque 或新增运行依赖 |
+
+一次额外 deque 候选链接返回 404，未作为实现依据。参考代码不是本项目实际运行依赖；只借鉴行为和测试思路，没有复制上游源码。
+
+## 本轮实施
+
+1. **固定诊断环**：0.4.0 达到上限后每条事件 push 再 shift，搬移旧记录；0.4.1 使用固定槽位覆盖和游标，读取时导出最近 128 条的时间顺序副本。
+2. **保留结果字节缓存**：0.4.0 每次 diagnostics 遍历记录并重新 JSON.stringify；0.4.1 复用保存时已算出的 UTF-8 字节，在终态快照保存成功后提交缓存。过期逐项扣除、关闭归零，unknown 或快照失败不计入。
+3. **行为保持**：请求协议、容量、会话轮转、合作取消、关闭阶段和通知重入语义不变；不增加任务队列依赖，也不改变宿主授权。
+
+## 可重复证据
+
+回归 test/github-comparison.test.mjs 先在旧产物运行：
+
+| 对比工作负载 | 0.4.0 实际计数 | 0.4.1 预期/回归结果 |
+|---|---|---|
+| 写入 1000 条诊断 | Array.shift 调用 872 次 | 0 次；仍只保存编号 873–1000 的 128 条 |
+| 两条保存结果，查询诊断 50 次 | 额外 JSON.stringify 100 次 | 0 次，字节数完全相同 |
+| 注入结果快照失败，再关闭 | unknown，不保存结果 | 字节计数保持 0；关闭 phase closed、queued/running 为 0 |
+
+前两项优化前断言失败，第三项在前后均通过。以上是明确工作负载下的操作次数，不是耗时加速比、模型轮次或生产吞吐结论。若结果本身仅很小或诊断很少调用，实际收益也可能很小。新增字节缓存有维护成本，因此专门覆盖 Unicode、过期和失败归零。
+
+## 暂不做
+
+- 不用开源队列直接替换当前调度器：宿主 Job 与原工具结果排空约束不同。
+- 不把 normal timeout 当作任务取消成功，不放弃仍运行的 Handler。
+- 不做无锁/线程池、消息持久化或自动副作用重跑。
+- 不因库测试通过就声称当前桌面、真实模型或沙箱验收通过。

package/docs/OPTIMIZATION.md

@@ -33,7 +33,7 @@
 
 阶段 elapsedMs 相对于本次受理的单调时钟时间：started 减 accepted 为排队时间、terminal 减 started 为执行时间、returned 减 terminal 为首次返回标记延迟。cancel_requested 与 terminal 间隔只能解释为取消请求到执行终态，未必为成功取消。
 
-查询快照会遍历最多 recordLimit 条记录计算保留结果字节数；只在开发者调用时发生。环形轨迹不会记录结果内容，但仍是内部运行信息，不作为可信审计/授权依据。进程关闭后不恢复。
+从 0.4.1 起，结果字节在保存时缓存、记录过期和关闭时扣除/归零；查询不再遍历记录或序列化结果。诊断写入使用 128 槽固定环，读取时才按时间顺序复制最多 128 条。环形轨迹不会记录结果内容，但仍是内部运行信息，不作为可信审计/授权依据。进程关闭后不恢复。
 
 ## 引擎经验来源
 

package/docs/protocol.md

@@ -98,7 +98,7 @@ core 不传配置时用默认值；显式配置必须完整包含 concurrency、
 
 core 实例的 `diagnostics()` 返回只读用途的独立快照：阶段计数、最近 128 条 `{operation,stage,elapsedMs}` 轨迹、关闭阶段、队列/运行/记录数及保留结果字节数。operation 是实例内递增数值，不是消息或会话 ID；elapsedMs 以单调时钟计算，阶段时间均相对受理时间，可相减得到排队/执行/返回延迟。复用计数仅在附着受理成功时增加；返回阶段按逻辑结果首次标记，不代表每个工具调用都持久化。
 
-宿主执行所有者另有内部 Job 创建/释放/异常聚合轨迹，不作为模型工具或公开服务导出；其 operation 是独立编号，不能与 core 轨迹按编号关联。数据只在内存，不保存参数、结果、Handler 名称、请求/会话 ID、异常文本或聊天记录。总计数会持续累积，环形轨迹有界；异常计数不等于每次清理最终失败。
+宿主执行所有者另有内部 Job 创建/释放/异常聚合轨迹，不作为模型工具或公开服务导出；其 operation 是独立编号，不能与 core 轨迹按编号关联。数据只在内存，不保存参数、结果、Handler 名称、请求/会话 ID、异常文本或聊天记录。总计数会持续累积，128 槽环形轨迹有界且按时间顺序导出；结果字节只在保存/过期/关闭时更新，查询不读取结果内容或重复序列化。异常计数不等于每次清理最终失败。
 
 ## 7. 扩展 Handler
 

package/docs/releases/0.4.1.md

@@ -0,0 +1,15 @@
+# 萧何 / Xiao He 0.4.1
+
+## 优化
+
+结合固定版本的 p-queue、EventEmitter3 和 Denque 实现/测试对照，收敛诊断热路径开销，保持 0.4.0 执行语义。
+
+- 诊断最近 128 条轨迹改为固定槽位环，写入不再 shift 搬移旧项；快照仍按时间顺序复制。
+- 保存结果时缓存字节数，过期时扣除、关闭归零；diagnostics 查询不再遍历所有结果和重复序列化。结果快照失败或 unknown 不占缓存。
+- 增加三项对比回归及可追溯 GitHub 对比说明。1000 条事件的 shift 从 872 次降为 0；两个结果查询诊断 50 次的额外序列化从 100 次降为 0。不是速度提升比例。
+
+## 兼容与验证
+
+不改变消息协议、工具或预设标识、会话轮转/通知重入/关闭契约；不新增运行依赖。全量测试、标签 Windows/Ubuntu × Node 22/24、包白名单与生产隔离安装按既有门禁执行。
+
+DSH 0.2.0-rc.2，非商业源码公开许可。真实模型、桌面 UI 和实际沙箱未验收，不支持跨重启恢复，不安装或重启日常 DSH。

package/package.json

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