@feng0531/dsh-execution-bus 0.2.11 → 0.3.0

package/README.md

@@ -4,9 +4,9 @@
 
 “萧何”是产品与模式显示名，执行总线是其技术功能；不新增人物 Agent，不进行角色扮演。仓库 dsh-execution-bus、npm 包名、execution_bus 工具名及 execution-bus-test 预设 ID 保持不变。历史版本发布说明保留当时名称。
 
-DSH 独立插件：`@feng0531/dsh-execution-bus` · 当前版本 **0.2.11**
+DSH 独立插件：`@feng0531/dsh-execution-bus` · 当前版本 **0.3.0**
 
-> 当前是早期可运行版本，不是完整生产验收版。已验证真实 DSH 组件和脚本模型驱动的内存会话；真实模型、桌面界面和 PTC 完整链路尚未验收。**不支持重启后恢复任务。**
+> 萧何模式从宿主已声明的 PTC 组合派生，保留日常工具，再叠加可选执行总线。已验证隔离的真实 Node PTC → 原 read + 总线调用，以及脚本模型内存会话；真实模型、桌面界面与实际沙箱仍未验收。**不支持重启后恢复任务。**
 
 ## 它解决什么问题？
 
@@ -31,23 +31,30 @@ DSH 独立插件：`@feng0531/dsh-execution-bus` · 当前版本 **0.2.11**
 ```mermaid
 flowchart TD
     A[DSH 会话中的模型提出请求] --> B[调用 execution_bus 工具]
-    B --> C{参数有效且容量允许?}
-    C -->|否| D[明确返回校验错误或背压错误]
+    B --> C{参数和可信上下文有效?}
+    C -->|否| D[返回校验错误]
     C -->|是| E{同一会话已有相同 requestId?}
     E -->|输入不同| F[拒绝请求编号冲突]
-    E -->|输入相同| G[复用已有执行或保存结果]
-    E -->|新请求| H[受理并进入内存队列]
-    H --> I[有空闲名额后分发给 Handler]
+    E -->|输入相同| G[校验消息及附着额度后复用执行或结果]
+    E -->|新请求| Q{队列与记录容量允许?}
+    Q -->|否| R[返回背压错误]
+    Q -->|是| H[内存受理并申请宿主 Job]
+    H --> V{宿主 Job 准入成功?}
+    V -->|否| W[取消尚未执行的请求并返回服务错误]
+    V -->|是| P[进入程序等待与队列分发]
+    P --> I[有空闲名额后分发给 Handler]
     I --> J[测试处理器 或 宿主 read 工具管线]
     J -.进度.-> K[宿主 Job 状态更新]
     J --> L[记录最终执行状态与结果]
-    G --> M[原工具调用异步等待结果]
+    G --> M[等待已有执行或立即读取终态结果]
     L --> M
     M --> N[由 DSH 把结果提交给原工具调用]
     N --> O[会话继续推理]
 ```
 
-**图里的“等待”不是阻塞宿主线程，也不是让模型不断查询。** 工具返回的是一个尚未完成的异步操作，DSH 在它完成后继续。队列执行与等待同时进行；进度更新走宿主任务机制，不把每条进度变成聊天消息。
+上图表示正常执行路径；工具校验、策略拒绝、取消或服务异常可能令外层调用返回错误，不能把箭头理解为每次请求必然执行成功。已保存的终态结果复用不申请新 Job。
+
+**图里的“等待”不是阻塞宿主线程，也不是让模型不断查询。** 工具返回的是一个尚未完成的异步操作，DSH 在它完成后继续。队列执行与等待同时进行；进度更新走宿主任务机制，不把每条进度变成聊天消息。正常已等待的 Job 完成通知可由宿主抑制；等待服务故障时不承诺没有额外宿主通知。
 
 若阅读器不支持 Mermaid，上图的主线是：
 
@@ -81,13 +88,19 @@ flowchart TD
 
 `host.read` 在出队时重新进入宿主工具管线，沿用宿主当前权限、会话工作目录及输出限制。插件不自行启动命令、不提供任意远程执行服务。它也不会强制将现有工具改成总线调用。
 
-## 在 Agent 预设中选择测试模式
+## 选择“萧何”预设
+
+包内提供标准 DSH bundle patch（预设组合补丁）。宿主正常加载后会收到“萧何 / Xiao He”预设定义，由既有设置 → Agent 预设 → **自定义**列表展示。建议选择它新建专门会话，不改默认选择或正在使用的普通会话。已有会话的切换受宿主空白会话检查约束。**实际桌面卡片展示尚未验收**，不能把注册表测试当作界面已通过。
+
+**0.3.0 起不再是只读验证模式。** 加载时读取宿主 `ptc` 预设的组合声明快照，保留原工具、平台表达式、禁用项和配置，只追加萧何总线与说明。不再强制 native 呈现或添加只读白名单；终端、写入、搜索、技能等能力是否可用，取决于原 PTC 配置和宿主服务。其他预设和默认模式不被修改，原 PTC 会话看不到新增总线。
+
+普通任务仍通过 `run_code` 调用原工具；**总线目前只支持 test 和 host.read，不接管任意命令、安装或全部工具**。例如更新插件应使用原终端能力并遵守宿主授权；专用插件管理工具若在源 PTC 中禁用，萧何不会擅自启用。命令受理、返回 Job ID 不等于执行完成。
 
-从 0.2.0 起，包内提供标准 DSH bundle patch。通过宿主正常加载这个 bundle 后，设置 → Agent 预设 → **自定义**区域会收到“萧何 / Xiao He”预设定义；选择它创建一个新测试会话。不要把它设成默认，也不要修改正在使用的普通会话。宿主一般只允许空白会话切换预设。
+升级提示：预设 ID 保持兼容，但从旧版只读模式升级后能力范围扩大，使用者须审阅后加载；本次不自动升级日常配置。它不是进程沙箱，同一预设会话共享总线容量，结果按会话隔离。派生是加载时快照，不自动跟随源预设热编辑；源 PTC 更新后应按宿主正常流程重新加载派生行，旧会话遵循宿主版本保留规则。
 
-该预设只在自己的作用域注册 execution_bus，使用原生工具调用，不改其他会话的 PTC 模式。它没有 shell 行；宿主文件工具套件会声明 read/write/edit 等工具，但测试模式的执行 guard 只允许总线、read 和 Job 控制，写入/编辑即使可见也会拒绝。它不是进程级沙箱，读取边界仍由宿主权限决定；同一测试预设的会话共享有界队列容量，但请求结果按会话隔离。
+源组合中的相对模块名、include 子文件缺少公开基准地址信息，当前明确拒绝派生，不能称为兼容所有自定义 PTC。遇到该诊断应先将源组合整理成可解析的显式模块行，不能绕过或回退成只读工具集。缺失 ptc 声明时注册器最多等候约 5 秒后明确失败。
 
-**不要同时把包根入口作为全局工具插件加载**：那是手工集成入口，会使 execution_bus 全局可见，失去此预设的可见性隔离。仅安装 npm 包也不保证卡片立即出现，需要加载包声明的 bundle patch。当前桌面未安装此版本，卡片实机展示尚未验证。
+**不要同时把包根入口作为全局工具插件加载**：那是手工集成入口，会使 execution_bus 全局可见，失去此预设的可见性隔离。仅安装 npm 包也不保证卡片立即出现，需要加载包声明的 bundle patch。项目发布不会自动安装到任何读者的宿主，卡片是否可用需要在目标实例实际检查。
 
 ## 安装前先确认
 
@@ -102,7 +115,7 @@ flowchart TD
 2. 在你选定的隔离 DSH 配置依赖目录安装固定版本，不要在 DSH 程序安装目录执行：
 
    ```powershell
-   npm install --ignore-scripts @feng0531/dsh-execution-bus@0.2.11
+   npm install --ignore-scripts @feng0531/dsh-execution-bus@0.3.0
    ```
 
    这是 npm 目录示例。若目标配置使用 pnpm，应沿用其包管理器，不混用锁文件。遇到宿主 peer 版本冲突就停止，不用强制安装绕过。
@@ -148,7 +161,7 @@ flowchart TD
 
 ### 两种编号不要混淆
 
-- **`messageId`：这条消息的编号。** 新的请求消息或控制消息使用新的编号。
+- **`messageId`：这条消息的编号。** 新操作/控制消息使用新编号；同一条消息的重复投递可沿用原编号及原内容。
 - **`requestId`：这一次逻辑操作的编号。** 同一次操作重发沿用它；不同操作必须换编号，即使参数完全相同。
 
 同一 `requestId` 搭配不同输入会被拒绝；不同会话不能读取或取消彼此的任务。重复执行保护仅在当前插件实例和保存期内有效，不是永久保证。
@@ -167,11 +180,11 @@ flowchart TD
 }
 ```
 
-将 `type` 换成 `status` 查询状态，换成 `result` 重取保存结果。取消中的任务要看最终 `state`；`cancelRequested: true` 只表示取消请求已经发出，不表示任务已停止或副作用已撤销。
+将 `type` 换成 `status` 查询状态，换成 `result` 重取保存结果；两者都立即返回当前快照，运行中不会替你等待终态。该示例如果在前面的成功请求之后执行，任务早已完成，取消只返回原终态；要验证运行中取消，需要由另一个并发控制调用在任务未完成时发出。取消中的任务要看最终 `state`；`cancelRequested: true` 只表示取消请求已经发出，不表示任务已停止或副作用已撤销。
 
 ### 如果宿主使用 PTC 模式
 
-PTC 是 DSH 的程序化工具调用入口。在 `run_code` 内使用 `await tools.execution_bus(请求对象)`，而不是直接调用折叠后的工具名。执行总线不会解除 `run_code` 自身的时间预算；PTC 完整进程链路尚未验收。
+PTC 是 DSH 的程序化工具调用入口。在 `run_code` 内使用 `await tools.execution_bus(请求对象)`，而不是直接调用折叠后的工具名。执行总线不会解除 `run_code` 自身的时间预算。已有真实 Node PTC 隔离进程读文件和调用总线的验证，但尚未进行实际模型/桌面沙箱全链路验收。
 
 ## 如何理解任务状态？
 
@@ -199,10 +212,10 @@ stateDiagram-v2
 
 ## 容量与重要限制
 
-默认并发 **2**，排队上限 **32**，最多保存 **256** 条任务记录，单结果最多 **64 KiB**，完成结果保存 **1 小时**，在新请求和查询时清理过期记录。队列或记录满时拒绝新任务；宿主 Job 自身也有容量限制。
+默认并发 **2**，排队上限 **32**，最多保存 **256** 条任务记录，单结果最多 **64 KiB**，完成结果保留期 **1 小时**，在新请求和查询时惰性清理；不是一小时一到即定时删除。队列或记录满时拒绝新任务；宿主 Job 自身也有容量限制。
 
 - **全部状态在内存中。** 受理没有落盘，插件关闭或进程崩溃后，不能依靠它恢复原调用或保证请求不丢失。
-- **不自动重跑任务。** 通信超时不等于执行失败，取消不等于回滚。
+- **不自动重跑任务。** 通信超时不等于执行失败，取消不等于回滚。Job 等待服务异常会在原执行排空后返回服务错误，执行可能已成功；应核对原 requestId 的状态，不要换编号盲目重跑。
 - **不承诺端到端 exactly-once。** 当前实例的请求复用不能代替外部副作用对账。
 - 当前没有远端执行端、跨插件 Handler 注册服务或非幂等操作对账能力。
 - 未证明真实模型轮次、主动查询次数或总耗时的提升比例。
@@ -231,7 +244,7 @@ npm run test:install    # 临时目录安装，不操作日常 DSH
 
 - [协议和投递语义](<docs/protocol.md>)：字段、状态、重复处理与取消规则。
 - [宿主兼容性与源码调用链](<docs/host-compatibility.md>)：为什么可以等待，为什么不能跨重启恢复。
-- [验证记录](<docs/validation.md>)、[0.2.11 发布说明](<docs/releases/0.2.11.md>)：已验证与未验证范围。
+- [验证记录](<docs/validation.md>)、[0.3.0 发布说明](<docs/releases/0.3.0.md>)：已验证与未验证范围。
 - [维护者发布流程](<docs/RELEASING.md>)：标签 CI、安装包校验与正式发布门禁。
 
 ## 许可

package/THIRD_PARTY_NOTICES.md

@@ -1,5 +1,5 @@
 # 第三方说明
 
-本包没有捆绑 DSH、Cordis、TypeScript、测试依赖或宿主源码快照。DSH 与 Cordis 作为宿主 peer 使用，其独立包分别受原许可证约束，本项目非商业许可证不限制第三方已授予的权利。开发依赖不进入本项目 tgz。
+本包没有捆绑 DSH、Cordis、TypeScript、测试依赖或宿主源码快照。DSH 与 Cordis 作为宿主 peer 使用，其独立包分别受原许可证约束，本项目非商业许可证不限制第三方已授予的权利。开发依赖不进入本项目 tgz。js-yaml 为 MIT 许可的独立运行依赖，由包管理器按声明安装，不捆绑进 tgz；其源码和许可见 https://github.com/nodeca/js-yaml ，本项目许可不限制其原有权利。
 
 CI 与发布组织方式参考 dsh-vcs，并按本项目执行能力重新实现；本包不含 Monaco、React 或 SVN 实现。

package/cordis.patch.yml

@@ -1,25 +1,6 @@
-# Registers a selectable custom preset, not a global execution_bus tool.
+# Add a separate selectable preset, deriving the host's configured PTC declaration.
+# Does not patch preset-ptc, selectedDefault or global tools.
 - insert:
     - id: preset-execution-bus-test
-      name: '@deepseek-ai/dsh-agent-preset'
-      config:
-        id: execution-bus-test
-        name: 萧何 / Xiao He
-        description: 独立执行模式：请求排队、异步等待、进度和取消；当前支持受控验证与只读文件。不修改默认模式，禁止命令和写入执行；不支持重启恢复。
-        order: 20
-        plugins:
-          - id: execution-bus-persona
-            name: '@deepseek-ai/dsh-persona'
-            config:
-              prefix: >-
-                你正在萧何模式中；这是执行请求协调模式，不是人物角色扮演。只使用 execution_bus、只读文件和任务控制工具。
-                请求只提交一次并等待结果，不循环查询进度；同一逻辑操作重发沿用 requestId。
-                默认先用 test Handler 做延迟成功、失败和取消测试，读取真实文件须有用户要求。
-                cancelRequested 不代表已取消，unknown 不代表执行失败。禁止声称跨重启恢复或完整模型性能提升。
-              suffix: 'Your working directory is {{cwd}}.'
-          - id: execution-bus-file-tools
-            name: '@deepseek-ai/dsh-tool-fs'
-          - id: execution-bus-job-tools
-            name: '@deepseek-ai/dsh-tool-jobs'
-          - id: execution-bus-scoped-runtime
-            name: '@feng0531/dsh-execution-bus/test-mode'
+      name: '@feng0531/dsh-execution-bus/preset'
+      config: {}

package/dist/preset.d.ts

@@ -0,0 +1,12 @@
+import { Context, Service } from "@deepseek-ai/cordis";
+import type { PresetDefinition } from "@deepseek-ai/dsh-agent-preset-registry";
+export declare const PRESET_ID = "execution-bus-test";
+/** Capture the host-declared composition without evaluating !!js or changing disabled rows. */
+export declare function derivePreset(content: string): PresetDefinition;
+/** Host-plane registrar. readDocument is a public serialized declaration, not a private registry read. */
+export default class XiaoHePreset {
+    private ctx;
+    static inject: string[];
+    constructor(ctx: Context);
+    [Service.init](): AsyncGenerator<() => Promise<void>, void, unknown>;
+}

package/dist/preset.js

@@ -0,0 +1,73 @@
+import { Service } from "@deepseek-ai/cordis";
+import { entryListProblem } from "@deepseek-ai/dsh-agent-preset-registry";
+import { entryListSchema } from "@deepseek-ai/cordis-plugin-include";
+import { load } from "js-yaml";
+import { setTimeout as pause } from "node:timers/promises";
+export const PRESET_ID = "execution-bus-test";
+/** Capture the host-declared composition without evaluating !!js or changing disabled rows. */
+export function derivePreset(content) {
+    if (Buffer.byteLength(content) > 1048576)
+        throw Error("PTC_PRESET_TOO_LARGE");
+    const plugins = load(content, { schema: entryListSchema });
+    const problem = entryListProblem(plugins);
+    if (problem)
+        throw Error("Invalid PTC preset: " + problem);
+    const rows = plugins;
+    const inspect = (entries) => {
+        for (const row of entries) {
+            if (row.id === "xiao-he-execution-bus" ||
+                row.name?.startsWith("@feng0531/dsh-execution-bus"))
+                throw Error("PTC_PRESET_ALREADY_CONTAINS_BUS");
+            // readDocument does not publish the declaring baseUrl. Do not silently
+            // rebase relative modules/includes into the registrar's different context.
+            if (row.name?.startsWith(".") ||
+                row.name === "@deepseek-ai/cordis-plugin-include")
+                throw Error("PTC_PRESET_RELATIVE_BASE_UNSUPPORTED");
+            if (row.group && Array.isArray(row.config))
+                inspect(row.config);
+        }
+    };
+    inspect(rows);
+    return {
+        id: PRESET_ID,
+        name: "萧何 / Xiao He",
+        order: 20,
+        description: "继承宿主 PTC 工具组合，叠加执行请求排队、等待与结果回传。普通任务使用原工具，授权和沙箱由宿主管理；不支持重启恢复。",
+        plugins: [
+            ...rows,
+            {
+                id: "xiao-he-execution-bus",
+                name: "@feng0531/dsh-execution-bus/test-mode",
+            },
+        ],
+    };
+}
+/** Host-plane registrar. readDocument is a public serialized declaration, not a private registry read. */
+export default class XiaoHePreset {
+    ctx;
+    static inject = ["agentPresets"];
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async *[Service.init]() {
+        let document;
+        for (let attempt = 0; attempt < 50; attempt++) {
+            try {
+                document = await this.ctx.agentPresets.readDocument("ptc");
+                break;
+            }
+            catch (error) {
+                if (!(error instanceof Error) ||
+                    !("code" in error) ||
+                    error.code !== "agent-preset/not-found")
+                    throw error;
+                if (attempt === 49)
+                    throw Error("Xiao He requires a declared ptc preset. Load the host PTC preset before this bundle.");
+                await pause(100);
+            }
+        }
+        if (!document)
+            throw Error("PTC_PRESET_UNAVAILABLE");
+        yield await this.ctx.agentPresets.register(derivePreset(document.content));
+    }
+}

package/dist/test-mode.d.ts

@@ -1,5 +1,5 @@
 import type { Context } from "@deepseek-ai/cordis";
 export declare const name = "execution-bus-test-mode";
 export declare const inject: string[];
-/** Must be mounted inside the host's preset scope, never in the global composition. */
+/** An additive preset row: presentation, tool inventory and authority belong to the host PTC composition. */
 export declare function apply(ctx: Context): void;

package/dist/test-mode.js

@@ -1,24 +1,15 @@
 import { scopeOf } from "@deepseek-ai/dsh-scope";
 import { apply as applyBus } from "./plugin.js";
-export const name = "execution-bus-test-mode";
-export const inject = ["tools", "jobs"];
-/** Must be mounted inside the host's preset scope, never in the global composition. */
+export const name = "execution-bus-test-mode"; // legacy export identity, intentionally stable
+export const inject = ["tools", "jobs", "systemPrompt"];
+/** An additive preset row: presentation, tool inventory and authority belong to the host PTC composition. */
 export function apply(ctx) {
     if (scopeOf(ctx) === undefined)
         throw Error("Xiao He mode requires an Agent preset scope");
-    ctx.tools.presentAs("native");
-    const allowed = new Set([
-        "execution_bus",
-        "read",
-        "job_list",
-        "job_output",
-        "job_kill",
-    ]);
-    // Scope-local file suite also declares write/edit; the execution guard denies them.
-    // restrict() only accepts known GLOBAL tool names, so it cannot filter sibling preset rows.
-    // Restriction filters inherited tools; a guard also fences tools registered by sibling preset rows.
-    ctx.tools.guard((exec) => allowed.has(exec.name)
-        ? undefined
-        : "Xiao He mode allows only bus, read and job controls");
+    ctx.effect(() => ctx.systemPrompt.section({
+        name: "XIAO_HE_EXECUTION_BUS",
+        order: 1700,
+        text: "你正在萧何模式中。这不是角色扮演。保留宿主 PTC 的日常工具能力与权限规则。普通编辑、搜索、命令、安装和其他工作使用原工具，不要声称此模式只读。execution_bus 是可选协调入口，目前只支持 test 与 host.read，不支持任意命令，不要强制所有任务走总线。通过 run_code 调用 await tools.execution_bus(...)，受原有时间预算约束。总线请求只提交一次并等待结果，不循环查询；同一逻辑操作重发沿用 requestId。cancelRequested 不等于已取消，unknown 不代表执行失败，不承诺跨重启恢复。后台命令仅返回 Job ID 不代表命令已经完成。",
+    }));
     applyBus(ctx);
 }

package/docs/FLOW-TEST.md

@@ -1,38 +1,51 @@
-# 不安装插件的流程测试
+# 不安装到日常 DSH 的流程测试
 
-## 本次执行方式与边界
+## 适合什么场景？
 
-当前会话没有 execution_bus 工具，桌面配置未安装本插件。本次由当前会话运行测试命令，在独立进程中加载本仓库编译产物及真实 DSH npm 组件；不修改日常配置、不热注入运行宿主、不重启 DSH。
+先验证代码行为，而不改日常 DSH 配置。命令在独立 Node 进程中加载本仓库产物和真实 DSH npm 组件，不向正在使用的宿主注入插件，也不重启宿主。
 
-这能验证真实 AgentLoop、SessionStore、ToolRuntime、Job 与 read 组件路径；不等于本会话实际调用 execution_bus，不验证真实桌面 UI、PTC 进程或真实模型。真实 AgentLoop 测试使用脚本模型适配器，read 组件测试使用测试 Agent 身份。两条测试不能合称当前会话端到端通过。
+**由聊天会话启动测试，不等于该聊天会话直接调用了 execution_bus。** 真实模型、GUI、PTC 进程和桌面沙箱结论不能由此替代。
 
-## 重复运行
+## 如何运行
 
-1. npm ci --include=dev --ignore-scripts
-2. npm run test:flow：流程回归、真实宿主执行组件、真实 AgentLoop 原调用结果关联。
-3. npm run check：包含核心队列、安全和发布门禁的全部测试。
-4. npm run verify:package：包白名单。
+```powershell
+npm ci --include=dev --ignore-scripts
+npm run test:flow
+npm run check
+npm run verify:package
+npm run test:install
+```
 
-流程包括：正常成功/失败、读文件、权限拒绝、匿名请求拒绝、重复请求只新增一个 Job、工具取消、插件关闭、进度不作为聊天消息、原调用只提交一次后才继续下一模型适配器请求。
+| 命令 | 实际范围 |
+|---|---|
+| `test:flow` | 三个固定测试文件：早期流程回归、真实宿主工具组件、脚本适配器驱动的 AgentLoop |
+| `check` | 编译并运行全部测试；包括后续 Job 故障、卸载、预设隔离等回归 |
+| `verify:package` | 检查候选打包清单及导出，不安装日常宿主 |
+| `test:install` | 在临时目录安装生产依赖并验证根入口/简化注册，结束后清理 |
 
-## 本次可复现问题
+`test:flow` 不是全部集成测试的别名；发布前必须运行 `check`。临时安装不是桌面插件管理器安装。完整验证层次见[验证范围](<validation.md>)。
 
-| 问题 | 修复前证据 | 本地修复 | 影响范围 |
-|---|---|---|---|
-| 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 公开结果为准。
+- 正常受理与异步返回，两个会话不串线，同键冲突拒绝。
+- 并发重复请求共用执行/Job；终态结果在宿主槽位满时仍可复用。
+- 查询额度、附着容量、取消保留槽及过期结果清理。
+- 合作取消、晚取消、未知结果不自动重跑。
+- 深层/非 JSON 结果拒绝，结果和通知不可变，异步观察者拒绝隔离。
+- 已受理 Handler 与替换注册并存，旧注销函数不破坏新注册。
+- 宿主 read 真正经过工具管线；前置拒绝仍生效。
+- Job 先行移除、等待/清理异常与卸载交错。
+- 派生预设成功激活、原 ptc 声明不变、普通 Agent 不可见总线、write/edit 保留且宿主策略可拒绝。
+- 真实 Node PTC 进程调用原 read 与总线；测试使用显式非约束策略，不代表桌面沙箱通过。
 
-## 优化建议
+以上是场景摘要，不表示真实模型/宿主 GUI 已通过。
 
-1. 已优化：终态结果不可变；保存失败明确区分执行失败；查询触发 TTL 回收，无常驻清理定时器。
-2. 后续可优化：完成请求重取无需新建短暂 Job；现在不会重复执行，但会产生不必要的 UI 生命周期事件。
-3. 后续可优化：每个重复附着仍注册一个空进度监听器；可将进度观察者绑定到共享逻辑请求，避免消耗 32 个监听者限额。
-4. 后续可优化：宿主 read 取消错误仍统一映射 HOST_READ_FAILED，保守归为 unknown。应保留经过白名单验证的取消类型，而不泄露原始异常文本。
-5. 不建议盲目改动：取消一个附着工具会请求取消整个逻辑执行，是当前明确语义；改成仅取消等待者需要单独设计宿主 drain、Job 通知和结果留存，不能只 Promise.race 后抛弃原执行。
+## 测试之外仍需注意
 
-## 真实当前会话测试前提
+- 宿主 read 的错误目前被适配层统一映射为 `HOST_READ_FAILED`；在取消后可能保守记为 `unknown`，不能把它当作取消已确认。
+- 相同逻辑请求的取消是请求级取消，不能简单用 Promise.race 放弃执行来改成等待者级取消。
+- 当前没有远端 Handler 传输或持久化恢复；测试没有提供这些能力。
 
-只有宿主通过正常插件加载向当前 Agent 注册工具后，才可能真正执行 await tools.execution_bus。当前没有暴露可用的临时插件注册工具，不能用额外 Node 进程、伪造 sessionId 或追加聊天结果来替代。若后续要测试真实当前会话，需要另行授权安装/加载并确认工具可见；本次未执行安装。
+## 要直接在聊天会话中试用
+
+需要先通过宿主正常加载插件，并让目标 Agent 看得到 `execution_bus`。建议加载可选“萧何”预设，新建专门会话；不要全局注入工具。安装/加载需使用者自行授权，是否重启由使用者决定。只启动另一个 Node 进程、伪造 sessionId 或追加聊天结果，都不算恢复原工具调用。参见[使用说明](<../README.md>)。

package/docs/RELEASING.md

@@ -1,29 +1,58 @@
-# 测试与发布流程
+# 维护者发布流程
 
-参考 dsh-vcs 的标签 CI 与联合发布流程，针对纯后端执行总线适配。没有复制 SVN、Monaco 或浏览器 layout 检查，因为本项目没有这些依赖和前端。
+此文面向维护者，使用者从[README](<../README.md>)开始。流程参考 dsh-vcs，使用本项目实际工作流和脚本；没有 SVN 或浏览器布局任务。
 
-## 触发策略
+## 1. 版本与说明
 
-普通分支 push 和 pull_request 不触发 CI。仅 vX.Y.Z 标签 push 和手动 workflow_dispatch 触发 CI；Windows/Ubuntu × Node 22/24 四项矩阵运行相同的构建、测试、包白名单、候选打包和生产依赖隔离安装。手动分支 CI 不能替代正式发布所需的同标签 push CI。
+采用 vX.Y.Z：X 为大版本，Y 为小版本/新增功能，Z 为 BUG 或文档纠错补丁。每轮完成且验证通过的改动主动正式发布；没有确认问题时不为发版本制造改动。
 
-## 本地验证
+包版本、锁文件根版本和标签必须一致，每版提供独立中文发布说明。说明围绕本版变化、使用影响、验证和限制，不把开发流水账当用户文档。保留旧发布说明的版本语境，不移动已有标签、不替换已上传的同版本包。
 
-依次运行 npm ci --include=dev --ignore-scripts、npm run check、npm run verify:package、npm run pack:candidate、npm run test:install。test:install 默认新打包，也允许传入一个本地 tgz。安装目录在系统临时目录中，结束后清理，不操作用户 DSH 配置。
+发布前核对非商业许可证、第三方说明和公开文件，排除凭据、私人材料、宿主源码快照及开发制品。产品显示名为萧何 / Xiao He；仓库、npm 包、工具和预设技术标识保持兼容。
 
-每个版本必须有独立中文发布说明 docs/releases/X.Y.Z.md，注明实际模型/桌面/跨重启等未验证项。package.json、package-lock.json 根版本及标签必须一致。不移动已有标签。
+## 2. 本地验证
 
-## 发布门禁
+```powershell
+npm ci --include=dev --ignore-scripts
+npm run check
+npm run verify:package
+npm run pack:candidate
+npm run test:install -- artifacts/candidate/feng0531-dsh-execution-bus-X.Y.Z.tgz
+```
 
-用户已授权 0.1.0 正式发布，并确认沿用 dsh-vcs 的非商业源码公开许可证。该许可不是 OSI 开源许可证，限制商业项目内部使用与有偿交付，具体以 LICENSE 为准。用户已持续授权本项目每轮改动完成并验证通过后主动正式发布，无需逐次提醒；仍必须通过工作流确认与完整门禁，不表示实际模型验收通过。版本采用 vX.Y.Z：X 大版本、Y 小版本/新增功能、Z BUG 修复；发布不自动安装或重启 DSH。
+把示例 X.Y.Z 替换为待发版本。包安装校验在系统临时目录运行，只检查生产依赖、入口及简化注册；不是实际桌面验收。候选生成命令不自行保证源码已重建，必须按上述顺序先执行 check。
 
-准备正式发布前：由用户明确授权；确定 LICENSE 与包 license 字段；检查公开材料、第三方许可和敏感信息；更新版本、锁文件与发布说明；提交并推送已批准的版本标签；等待四矩阵通过。
+## 3. 标签 CI
 
-从 main 手动运行 Publish GitHub and npm，输入已存在标签及确认词 publish-execution-bus。推荐为 npm-release environment 配置必须审批的维护者及适当分支限制，并配置 NPM_AUTOMATION_TOKEN。仓库环境审批和 token 均需要维护者配置，本次没有配置远端。
+只有匹配格式的版本标签 push 和手动 workflow_dispatch 触发 [CI](https://github.com/f-e-n-g-0531/dsh-execution-bus/blob/main/.github/workflows/ci.yml)；普通分支 push、PR 不触发。标签检查会进一步严格校验格式及版本一致性。
 
-工作流重新检查标签版本与许可证，运行本地检查，生成候选，查询该精确标签/提交的最新 push CI 为 success，下载四个矩阵候选并逐字节核对。然后隔离安装同一候选、保留制品，仅 npm 上传步骤取得凭据。npm 公开元数据 integrity 与实际下载字节必须一致，才创建 GitHub Release；附件是同一个 tgz 与 SHA256SUMS.txt。不自动覆盖已有 Release。
+创建新 vX.Y.Z 标签后，等待 Windows/Ubuntu × Node 22/24 四项全部成功。各项编译、测试、检查包、生成候选，再安装该项的同一 tgz，并上传候选和 SHA-256 文件。手动分支 CI 不能替代同标签 push CI。
 
-npm 与 GitHub 不是原子发布。如果上传后公开包 404，不盲目重传；先只读对账，再重跑原工作流。已有 npm 同版本必须 integrity 相同才跳过上传；不匹配立即停止。发布过程没有自动重试上传，公开可见性最多查询十次。
+失败后先定位。需要修改冻结源码或测试时使用新的版本/标签，不强推覆盖。制品过期或缺少任何一份时，发布门禁会拒绝，需要先恢复可核验的同标签 CI。
 
-## 验证边界
+## 4. 联合发布
 
-本地 Windows/Node 24 的脚本验证不等于 GitHub 四平台已成功。远端工作流、token、environment 审批、上传和两端公开包核验在执行前都属于未验证。CI 中的脚本模型适配器不是实际模型评测，包入口夹具不是桌面安装验收。发布不自动安装或重启 DSH。
+从 main 手动运行 [Publish GitHub and npm](https://github.com/f-e-n-g-0531/dsh-execution-bus/blob/main/.github/workflows/release.yml)，输入已验证标签和确认词 publish-execution-bus。工作流并非由普通分支推送自动发布。
+
+仓库需配置 NPM_AUTOMATION_TOKEN，具有指定包发布权限并满足 npm 策略；密钥仅提供给上传步骤，不写源码、日志或文档。工作流声明 npm-release environment，但**声明环境不等于已经配置维护者审批规则**，规则需要仓库维护者单独设置。本项目历史发布使用明确用户授权和工作流确认，不能称为人工环境审批已验收。
+
+发布步骤：
+
+1. 检出指定标签，校验标签/版本/许可证/发布说明。
+2. 重新安装、检查和打包。
+3. 要求同一提交、同一标签的最新 push CI 成功，下载四份候选，与本次候选逐字节比较。
+4. 对同一 tgz 做隔离安装，保留发布候选制品。
+5. 查询 npm 已有版本：存在且 integrity 相同则跳过上传；不一致停止。确实未找到时才上传固定 tgz，禁用生命周期脚本。
+6. 有界核对公开 npm 元数据 integrity 和实际下载字节；成功后才创建非草稿、非预发布 GitHub Release，上传同一个 tgz 与 SHA256SUMS.txt。
+
+## 5. 失败恢复与发布后核验
+
+npm 与 GitHub 不是原子发布。上传显示成功但公开包仍 404 时，门禁会停止并保留候选。**不要盲目重传，不另造版本绕过，不先创建 Release。** 先只读检查公开元数据和实际包；确认与原候选相同后恢复原失败任务，使上传步骤核对已有 integrity 并跳过。若仍不公开，则报告发布未完成，继续保留原标签/制品。
+
+公开核验当前最多查询十次；网络异常或非预期状态也可能立即失败，不能解释成“必定等足十次”或“上传失败”。已有 GitHub Release 不自动覆盖；已经完成的发布仅补记证据，不替换附件。
+
+最终核对 npm 指定版本和 latest、GitHub 非草稿/非预发布、两端真实下载大小和 SHA-256 与候选一致。源码或 npm 包内的发布说明是在上传前冻结的，不能含尚未发生的通过结论；发布后的事实以 Actions、公开制品和版本化记录为准。
+
+## 6. 安装边界
+
+正式发布不自动安装、升级或重启任何日常 DSH。桌面卡片、实际模型、权限/沙箱或 PTC 端到端未验收项必须如实披露，不能用 CI、注册表测试或替代服务器冒充当前页面通过。

package/docs/host-compatibility.md

@@ -1,44 +1,77 @@
-# 宿主调查与兼容性
+# 宿主兼容性与接入原理
 
-## 结论：只做插件
+## 兼容目标
 
-调查日期：2026-10-15。当前桌面安装的 runtime 和各 DSH 组件均为 **0.2.0-rc.2**，Cordis 4.0.4。源码来自安装 ASAR，只读提取到项目开发证据目录；未改安装文件。插件针对这个精确版本编译。不能据此推断旧版、新版均兼容。
+源码调查基线为 **2026-10-15 的 DSH 0.2.0-rc.2、Cordis 4.0.4**。本项目用同版本 npm 组件编译和隔离测试；这不是对任意旧版、新版宿主的兼容保证，也不是对读者当前安装版本的自动检测。Node.js 要求为 22 或以上；CI 使用 Node 22、24。
 
-**A. 纯插件可实现**：注册工具、同进程异步等待原调用、可信 Agent 归属、排队及幂等请求、调用现有 read 工具全管线、Job 进度与取消。无需模型参与等待。
+本项目只做插件，没有修改宿主源码、ASAR 或其他插件。
 
-**B. 当前缺少的能力（仅记录，不修改宿主）**：跨进程重新认领原工具调用的公开契约，以及工具结果写入会话日志的持久化确认。若将来宿主提供，至少需要以 session + call-event-seq + callId 进行 CAS 认领、单次提交和可查询提交凭证，且必须在中断恢复合成结果前参与恢复。现在不实现、不伪造这些 API。
+## 接入链路
 
-**C. 本版降级**：受理、队列、结果与交付标记均为内存态。停止/崩溃后不可续接；不会自动重跑。新调用查询只能在当前插件实例的保存期内重取，不能当作恢复原调用。整体交付属于第一阶段、部分完成，不是完整跨重启总线。
+```text
+AgentLoop 发起工具调用
+  → ToolRuntime 校验、策略与可信身份绑定
+  → execution_bus 工具体
+  → 内存去重/排队，宿主 Job 记录和程序等待
+  → test Handler 或经 ToolRuntime 再调用宿主 read
+  → 保存执行结果，清理 Job
+  → 工具体返回
+  → AgentLoop 关联原工具调用并继续会话
+```
 
-## 实际调用链和源码位置
+等待由 Promise 完成，不阻塞宿主线程，不为正常等待反复调用模型。进度只交给 Job 机制；宿主的前后置策略、取消和最终会话提交仍有权改变外层工具结果。
 
-以下均为本机只读提取的**实际发布构建源码**，不是臆测的源码仓库路径。安装归档无法直接被普通文件工具当目录访问，提取脚本只向本项目写入。
+### 与 PTC 的关系
 
-1. [Agent 调度器:506–532](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-agent-loop/lib/index.js#L506-L532)：requireInitiator 得到 Agent，产生 callId、arguments、agent、signal；runGroup 调度且等待结果。不在等待期间请求模型。
-2. [工具注册:2878–2886](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tools/lib/index.js#L2878-L2886)：ctx.tools.register 是作用域 effect，卸载自动移除。工具 execute 可以返回 Promise。
-3. [可信执行身份:3131–3175](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tools/lib/index.js#L3131-L3175)：注册表生成 token，保留 callId、rootCallId、agent、signal，快照参数。
-4. [前置策略:3225](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tools/lib/index.js#L3225) → [执行 waterfall 与工具体:3294–3331](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tools/lib/index.js#L3294-L3331) → [后置策略:3504](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tools/lib/index.js#L3504) → [最终 tools/result:3417](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tools/lib/index.js#L3417)。插件只调用公开 execute，不直接调用 read 的定义体，不跳过这些策略。
-5. [可选 PTC:1294–1307](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tools/lib/index.js#L1294-L1307)：子调用继承 agent、rootCallId，带 parent token；在原 run_code 时间预算内等待。[超时策略:4–6](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tool-call-timeout-policy/lib/index.js#L4-L6) 是协作式取消并 drain，不代表外部副作用失败。插件不改全局工具呈现、不拦截其他工具。
-6. [宿主 read:174](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tool-fs/lib/index.js#L174)：cwd 来自 exec.agent.session.header；[实际读取和输出限制:348](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tool-fs/lib/index.js#L348)。嵌套 read 在出队时重新进工具管线，沿用当时宿主权限和 fs 实现；插件没有独立 shell、spawn 或文件读取能力。read 的只读访问边界由宿主实际组合的 fs/权限实现决定，不能把 cwd 当作沙箱。隔离测试的 LocalFS 不等于桌面沙箱验证。
-7. [Job start:412–491](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-jobs-local/lib/index.js#L412-L491)：已有 owner 校验、controller admission、输出环、进度句柄、首终态约束；[等待:510](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-jobs-local/lib/index.js#L510)、[进度:717–729](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-jobs-local/lib/index.js#L717-L729)。插件只补排队、请求冲突和结果复用，不再造通用 Job 注册表。
-8. [完成通知抑制:268–270](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tool-jobs/lib/index.js#L268-L270)：awaited 为 true 时不追加完成通知；插件先注册 wait 再等待终态，并移除已收集 Job。每 60 秒等待窗口续等由程序执行，不调用模型，不把超时改为失败。
-9. [原调用结果提交:680–706](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-agent-loop/lib/index.js#L680-L706)：宿主将结果关联原 callId 和 call-event-seq；插件只 return，不追加 tool/result 或聊天消息。
-10. [中断恢复:717–730](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-session/lib/index.js#L717-L730) 和 [interruptedTurnClosers:904](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-session/lib/index.js#L904)：为未保存结果生成 outcome unknown，不会复活内存中的 Promise。[Agent 恢复:1950](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-agent-loop/lib/index.js#L1950) 使用这个保守闭合机制。
+PTC 是可选入口：外层 `run_code` 可以调用同一个工具。它不是总线本身，也不会因使用本插件取消自身时间预算。0.3.0 起，“萧何”从目标宿主 ptc 的公开声明派生，保留呈现与全部声明行，不再强制 native 或施加只读 guard。派生组合加入可选总线，其他预设不变。真实 Node PTC 隔离进程已验证原 read 与总线共存；不是桌面/真实模型/实际沙箱的全链路验收。
 
-## 插件扩展方式
+## 源码证据定位
 
-- 工具：ctx.tools.register；服务：Cordis Service 的标准构造注册（例如 [JobRegistry:106–110](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-jobs/lib/index.js#L106-L110)）。本插件没有替换宿主服务。
-- 事件：ctx.on / ctx.waterfall / ctx.emit；副作用生命周期 ctx.effect，异步 disposer 用于取消并等待处理中的任务。本插件未注册全局工具拦截器。
-- 界面：本版不注册自定义前端，复用现有 Jobs 进度事件和默认工具卡片。宿主原有客户端插件体系不是必需依赖；尚未完成该体系全部入口调查，不能提供未核实的 UI 注册示例。
-- 持久化：宿主会话日志有持久化；本地 Job 注册表注释明确是 process-local。二者不能混同为插件可恢复执行权。
+下表位置来自调查时实际安装包的发布构建文件，均是组件内部的 `lib/index.js` 行号，**不是上游 TypeScript 源文件行号**。要复核，请取得相同版本包后定位组件与符号；宿主升级后行号可能变化。
 
-## 名称核对
+| 环节 | 组件、构建行号与符号 | 结论 |
+|---|---|---|
+| 调用与调度 | `@deepseek-ai/dsh-agent-loop`：506–532，`runGroup` 调度路径 | 绑定原调用并等待工具返回 |
+| 注册与卸载 | `@deepseek-ai/dsh-tools`：2878–2886，工具注册；3294–3331，`dispatchToolBody` | 注册为作用域副作用，工具体可异步等待 |
+| 身份与策略 | `@deepseek-ai/dsh-tools`：3131–3175、3225、3504、3417 | 生成可信 token、保留 agent/callId/rootCallId，执行前后策略及结果通知 |
+| PTC 子调用 | `@deepseek-ai/dsh-tools`：1294–1307 | 子调用携带 agent、rootCallId 和 parent token；不是任意身份注入 |
+| 文件读取 | `@deepseek-ai/dsh-tool-fs`：174、348，read 注册/执行路径 | 工作目录来自会话；输出和文件边界由宿主组合决定 |
+| 任务与等待 | `@deepseek-ai/dsh-jobs-local`：412–491 `start`、510 `wait`、717–729 `updateProgress` | 所属访问、容量、进度、取消、首终态与程序等待可复用 |
+| 完成通知 | `@deepseek-ai/dsh-tool-jobs`：268–270 | 正常已等待的完成通知不再额外报告；异常等待通道不承诺这一抑制仍完整生效 |
+| 会话结果提交 | `@deepseek-ai/dsh-agent-loop`：680–706 | 宿主按 callId 和调用事件序号写入结果，插件不自行追加聊天消息 |
+| 中断闭合 | `@deepseek-ai/dsh-session`：717–730、904；`@deepseek-ai/dsh-agent-loop`：1950 | 未保存结果保守闭合为未知，不恢复旧 Promise |
+| 预设注册 | `@deepseek-ai/dsh-agent-preset-registry`：500–539 `register`/`activate` | 独立组合作用域，可供所选 Agent 加入 |
 
-- [npm 官方接口](https://registry.npmjs.org/@feng0531%2Fdsh-execution-bus) 在调查时返回 404：未发现可见同名包，不代表预留成功或拥有发布权限。
-- 现有本地 origin 是 https://github.com/f-e-n-g-0531/dsh-execution-bus.git ，git ls-remote 读取 HEAD 为 06299e9425d6ba197c0d2e04bf8818ddfe471edf。仓库名称已经存在，与当前工作区既有 remote 一致，未创建、推送或修改远程；GitHub API 限流未拿到账户所有权证明。
-- 中文“执行总线”和英文“Execution Bus”是描述性显示名称，不是唯一名称或商标授权结论。
+开发仓库中的提取脚本可在原调查安装布局下生成本地快照；该布局是开发证据，不是用户必需依赖。快照不进入仓库或 npm 包，因此本文不再提供指向未分发快照的相对链接。
 
-## 验证分层
+## 插件能力与边界
 
-真实 npm 宿主组件隔离冒烟：已运行（真实 ToolRuntime / LocalJobs / read / LocalFS，测试 Agent 夹具）。
-真实 AgentLoop + AgentRegistry + SessionStore 内存会话：脚本 LlmAdapter 隔离测试已通过，原工具成功结果只提交一次，再进入下一适配器请求。不是实际模型评测。真实桌面 GUI、磁盘会话持久化提交、真实模型推理续接、PTC 进程端到端：**未验证**。没有安装日常环境，也没有重启或使用模型凭据。组件测试不能替代这些结论。
+### 当前可用
+
+- 标准 Cordis 工具注册、异步等待及生命周期清理。
+- 复用宿主工具管线和 Job 服务，不自行启动进程或实现独立 HTTP 执行服务。
+- bundle patch 加载派生注册器，从已声明 ptc 读取组合快照并注册可选预设，由宿主既有 Agent 预设界面消费元数据，不需要自定义前端。readDocument 在宿主注释中用于查看声明，本插件只读取其序列化数据再注册独立预设，并不认领源预设的运行实例或私有基准地址。
+- 同预设范围内共享有界总线，但查询/取消按宿主 Agent 的会话身份分隔。
+
+旧版只读 guard 在 0.3.0 移除，预设保留源 ptc 的工具与权限，不再削减普通写入/命令能力，也不自动启用源组合禁用行。它不是进程或权限沙箱，不隔离进程资源消耗。宿主 cwd 只是路径解析基准，不是文件访问围栏。
+
+派生使用 readDocument 序列化声明及宿主 YAML 方言，不访问注册表私有字段，不求值 !!js。它是加载时快照；没有公开的源声明 baseUrl，因此拒绝相对模块或 include 文件，避免错误重定位。完整自定义预设等价性不可仅由模块行保留推断，外部依赖和宿主注入仍需原实例验证。
+
+### 当前不提供
+
+- 接管所有现有工具或更改默认 Agent 预设。
+- 持久化受理、跨重启恢复或重新认领原工具调用。
+- 工具结果已写入会话磁盘日志的持久化回执。
+- 远端执行端、通用工作流或有副作用操作的对账能力。
+
+若未来要跨重启接续，需要宿主公开稳定的认领/提交契约；本项目不虚构这样的 API，也不通过聊天消息绕过。
+
+## 故障处理
+
+正常等待使用宿主 Job 窗口续等。等待服务异常后，先排空原执行并保留原服务错误；然后按原 owner 对确切 Job 最多检查 20 次、每次间隔 10 毫秒，尝试清理终态记录。这些是错误恢复检查，不是模型轮询或重跑任务。
+
+宿主 rc.2 没有类型化 Job not-found 错误码。对先行移除的幂等处理仅匹配本调用创建的 Job 的精确错误消息，并确认原 owner 查询中记录已不存在。其他错误不被冒充成功。持续故障时可能遗留记录，不合作 Handler 可能阻碍关闭。
+
+## 哪些是真实验证？
+
+真实组件、真实 AgentLoop 内存会话和真实预设注册表均有隔离测试；模型侧是脚本适配器，部分 Agent 身份是夹具。桌面卡片渲染、实际权限提示/沙箱、磁盘结果提交和真实模型继续推理均未验收。详见[验证范围](<validation.md>)。

package/docs/protocol.md

@@ -1,52 +1,101 @@
-# 协议 v1、状态与投递
+# 协议 v1：请求、状态与结果
 
-## 输入
+本文面向调用者和 core Handler 开发者。消息示例见[使用说明](<../README.md>)，兼容版本见[宿主说明](<host-compatibility.md>)。
 
-严格无损 JSON，最大 16 KiB，不接受额外顶层字段。JSON 值最大深度 64、访问节点最多 65536；拒绝非有限数字、负零、undefined、函数、符号、稀疏数组、访问器属性、特殊对象和循环引用；数组只接受当前运行域的原生 Array.prototype，拒绝数组子类、自定义原型及跨域数组。messageId / requestId 为 1–128 位字母、数字、下划线、点、冒号或短横线。
+## 1. 请求结构
 
+```json
+{
+  "protocolVersion": 1,
+  "messageId": "message-001",
+  "requestId": "operation-001",
+  "type": "request",
+  "payload": { "handler": "test", "input": { "delayMs": 1000, "fail": false } }
+}
+```
 
-type 为 request 时 payload 为 {handler,input}；type 为 status / result / cancel 时 payload 必须为 {}。不支持其他类型或版本。sessionId、权限、工作目录不能出现在输入中，可信归属只能由宿主工具上下文绑定。
+| 字段 | 规则 |
+|---|---|
+| `protocolVersion` | 必须为数字 1 |
+| `messageId` | 单请求范围内一条消息的编号；相同编号不同内容拒绝 |
+| `requestId` | 同一逻辑执行的稳定编号；同会话内重复输入复用执行，不同输入拒绝冲突 |
+| `type` | `request`、`status`、`result` 或 `cancel` |
+| `payload` | request 必须为 `{handler,input}`；其他三种类型必须为 `{}` |
 
-- messageId 标识一条消息；同请求内同 messageId 不同内容拒绝。普通消息记账最多 128 条，超过拒绝普通新消息。首次有效取消可使用额外一个保留槽，最多 129 条；之后的新取消不再增加记账，已记录消息 ID 的冲突检查仍生效，不会因查询耗尽额度而丧失取消路径。
-- requestId 是一次逻辑操作的稳定幂等键；作用域为当前插件实例 + 宿主 session。相同 requestId 不同 handler/input 拒绝冲突，相同输入使用新 requestId 仍是新操作。
-- 输入规范排序后的摘要仅用于同 requestId 冲突比较，不作永久参数去重。保存期后旧键会失效，调用者不得因此盲目重跑有副作用操作。
-- callId / rootCallId / Agent / parent token 来自宿主；通过工具原本的 Promise 关联结果，不依赖模型提供的身份。
+两个 ID 都只接受 1–128 位字母、数字、下划线、点、冒号和短横线；不接受其他顶层字段。身份、权限和工作目录不能由消息另行指定。宿主工具上下文中的 Agent、调用 ID 与 token 才是可信关联。
 
-## 输出
+请求最大 16 KiB。输入和结果采用严格 JSON：深度最多 64，访问节点最多 65536；拒绝非有限数字、负零、undefined、函数、符号、稀疏数组、访问器、特殊对象和循环引用。普通对象接受当前运行域 Object.prototype 或 null 原型；数组只接受当前运行域 Array.prototype。跨运行域值须先转换为受支持的纯数据，不能假定任意 JavaScript 对象都可传入。
 
-核心 submit 返回 accepted 事件和 done Promise。受理只意味着已进入内存记录和队列，durable:false；不是成功。事件包含 protocolVersion、messageId、requestId、correlationId（首次请求 messageId）、sequence、type、payload。每请求 sequence 单调递增，accepted 是当前序号的快照，不占新增序号。
+### 去重与消息额度
 
-事件类型：accepted、started、progress、cancel_requested、succeeded、failed、cancelled、unknown。进度只接受 Handler 正整数序号递增的百分比，重复、乱序、终态后进度丢弃。进程内投递，无外部消息接收端，也不支持任意远端终态注入；终态只由总线持有的执行 Promise 结算。事件及其 payload 在投递前深度冻结，观察者不得修改请求关联、序号、类型或进度内容。每个附着拥有独立观察者注册和名额，即使复用同一回调；detach 幂等且只移除自己的通知，不影响其他附着或执行结果。观察者是最佳努力通知：同步抛错及异步 Promise 拒绝均被隔离，不记录异常原文；不等待观察者完成，不保证关闭前异步通知已经完成，观察者须自行管理资源。
+- 逻辑键是 **当前存活总线实例 + 宿主会话身份 + requestId**。不同会话不能查询/取消彼此记录；同预设仍共享容量。
+- 对参数规范排序后的摘要仅用于同 requestId 的冲突比较，不用于永久按参数去重。相同参数的新 requestId 仍是新操作。
+- 普通消息最多记账 128 条，含首次请求、重复请求及查询。满后拒绝普通新消息；首次尚未确认的有效取消可使用一个额外控制槽，最多 129 条。已记账消息的冲突检查不因控制槽而放松。
+- 活跃观察者附着最多 32 个；每个附着独立占名额，即使共用回调。附着被拒绝时不占用新消息编号/额度。
+- 终态超期清理后旧请求键失效，不应把此机制用于长期避免外部副作用重复。
 
-工具的 request 保持 pending，最终返回 RecordView（requestId,state,sequence,cancelRequested,delivery,result?,error?,progress?）；status/result/cancel 返回同一种当前快照。工具不会提前返回 accepted 或 taskId，也不会用聊天进度消息唤醒模型。Job 的 UI progress 只含状态/百分比。
+## 2. 工具返回和 core 事件
 
-## 状态转换
+**工具 request 不提前返回 accepted 或仅 taskId。** 它异步等待后返回执行快照；校验、容量、宿主服务等也可能令外层工具调用返回错误，而非执行快照。
 
-queued → running → succeeded / failed / cancelled / unknown。
-queued → cancelled。终态不可变；取消终态任务只返回原状态。
+快照字段：`requestId`、`state`、`sequence`、`cancelRequested`、`delivery`，以及可选 `result`、`error`、`progress`。`status`、`result`、`cancel` 均返回当前快照；`result` 在运行中也只返回当前状态，不额外等待。
 
-运行中取消先置 cancelRequested 并触发 AbortSignal，不立即声称 cancelled。Handler 用 AbortError 确认取消后才 cancelled；收到取消仍成功返回则 success 获胜；取消后其他异常为 unknown。Handler 必须合作取消并等待自身资源停止，不能把部分副作用当作已撤销。初版内置 Handler 仅为受控测试和只读宿主 read，没有非幂等写操作。
+core 的 `submit()` 返回 `accepted`、`done` Promise 和取消/解除通知/返回标记句柄。accepted 只是内存受理或已有记录的快照，`durable:false`，不代表执行成功；终态重取也不代表重新执行。
 
-异常是固定错误码，不将异常堆栈/原文写日志。结果遵守同样的严格 JSON 深度/节点与值约束；过大、会丢失信息或不可保存的结果进入 unknown / RESULT_NOT_RETAINED，不因结果传输失败自动执行一次。执行结束不等于交付，delivery 单独记录 pending / returned；returned 仅代表插件已走到工具返回路径，**不是会话持久化提交确认**。done 快照保留当时的 pending，后续查询可见 returned。宿主可能因取消/后置策略改变最终工具结果，插件不声称已确认模型收到。
+通知包含版本、消息 ID、请求 ID、关联 ID（correlationId）、请求内序号、类型与 payload。accepted 的 correlationId 对应本次提交消息，序号是当前快照；后续事件关联首次请求 messageId，新增序号。类型包括 started、progress、cancel_requested 和 succeeded、failed、cancelled、unknown 四种终态事件。
 
-## 容量和清理
+Handler 报告的进度序号必须递增；重复、乱序及终态后进度忽略，百分比须在 0–100 内。事件及 payload 在通知前冻结。每个附着独立解除通知，detach 不取消执行；取消是另一个操作。观察者抛错或异步拒绝被隔离，不记录异常原文，也不等待观察者资源完成。
 
-默认并发 2，待分发队列 32，记录 256，单结果 JSON 64 KiB；所有请求先经上限检查，满则 BACKPRESSURE，不自动重试。Job 仍受宿主自己的每 owner 容量限制。队列不提供公平性 SLA，单会话可占满实例。core 不传配置时使用默认值；传入配置必须完整包含五项正安全整数，不接受部分配置、额外字段或访问器，缺项立即 INVALID_OPTIONS。core 构造时复制并冻结容量配置，之后修改调用方原对象不改变总线限制；没有动态配置更新接口。重复附着只有成功取得观察者名额后才提交新消息记账，WAITER_LIMIT 拒绝不占用消息 ID 或额度。
+## 3. 执行状态和交付标记
 
-终态自完成后保存一小时；新受理及控制消息查询时惰性清理，可通过 core.sweep 主动清理。无定时器常驻、无磁盘结果存储、无日志输出。插件关闭先停止受理，取消队列与运行任务，等待合作 Handler，清理内存；不合作的 Handler 会阻碍关闭，插件无法安全硬杀同进程代码。
+```text
+queued → running → succeeded / failed / cancelled / unknown
+   └────────────→ cancelled
+```
 
-敏感文件结果仍可能进入宿主原有工具会话日志，本插件不具备任意文本秘密识别能力。只请求确实需要的内容；不将敏感内容放入请求标识。结果长度检查发生在 Handler 返回后，扩展 Handler 自身也必须限制分配，不可把此检查当成防止超大对象构造的内存沙箱。
+终态不可再改成另一终态：
 
-## 投递语义、超时和恢复
+| 状态 | 含义 |
+|---|---|
+| queued | 内存已受理，尚未开始 |
+| running | 正在执行 |
+| succeeded | Handler 正常返回，结果可验证、保存 |
+| failed | 未在取消中的 Handler 执行异常 |
+| cancelled | 排队时取消，或运行 Handler 用 AbortError 确认取消 |
+| unknown | 取消后异常未确认，或执行结果不能可靠保存 |
 
-在同一个存活实例/保存期内，同 session + requestId 多次投递共用一次执行；每个实际工具调用独立取得一次响应。这不是端到端 exactly-once，同一请求重复调用仍会增加宿主工具调用记录。终态状态和结算锁避免一次执行被重复完成；不会额外主动提交会话结果。
+`cancelRequested` 只表示发出了 AbortSignal，不代表停止或回滚。取消后正常返回且结果可保存，成功可获胜；取消后其他异常保守记为 unknown。取消某个正在等待的重复调用，会请求取消整个逻辑执行，不是仅退出该等待者。
 
-无网络传输层，因此自动通信重试次数为 **0**，也不自动重试执行。宿主 Job 60 秒窗口超时只是程序续等，不改变执行状态、不触发模型查询。PTC 外层仍有自己的时限和取消语义。
+执行完成与结果交付分开。`pending`/`returned` 只是插件返回路径的标记；done 快照保留当时值，后续查询可看到更新。**returned 不证明宿主磁盘提交或模型已消费**。外层取消/后置策略仍可能改变返回值。
 
-本版不做持久化：受理/运行/结果/交付任一阶段进程崩溃都会丢失插件记录。宿主日志可能记录请求和结果，不代表插件恢复了执行。跨重启需人工结合宿主 outcome unknown 和外部实际状态处理；不能自动重跑非幂等操作。本版不实现对账钩子或跨进程重试，扩展有副作用 Handler 前必须另行设计这些能力。
+错误也须分层：Handler 异常原文不进入保存结果，使用 HANDLER_FAILED 等固定码；不合法、过大或快照不可保存结果为 unknown / RESULT_NOT_RETAINED。宿主 wait/remove 等服务错误可能作为外层工具错误传出，不能笼统声称所有错误都已脱敏或都是固定码。不要把宿主服务错误文本当成业务执行失败凭据。
 
-## 扩展 Handler
+## 4. 容量、保存与关闭
 
-core 导出 ExecutionBus、Handler 和 Capability 类型。register(name,handler) 返回幂等注销函数，绑定唯一注册令牌；旧函数不会删除后来同名注册，即使复用同一 Handler 对象。同名活跃注册拒绝。Handler 提供 validate 和 async run，执行上下文仅有 requestId、signal、progress 与最小执行 capability，不传聊天历史。注销不影响已受理任务捕获的 Handler；关闭时等待它们。
+| 默认配置 | 值 |
+|---|---|
+| 并发执行 | 2 |
+| 待分发队列 | 32 |
+| 任务记录 | 256 |
+| 单结果 JSON | 64 KiB |
+| 终态保留期 | 自完成起 1 小时 |
 
-当前插件内置注册 test 与 host.read。尚未公开 Cordis Handler 注册服务，其他插件不能假定存在 ctx.executionBus；跨插件动态注册属于后续事项。
+新执行请求受队列和记录容量限制；运行中重复附着受消息/监听名额限制；未过期终态复用不申请新 Job。宿主新 Job 准入还有独立容量要求。没有公平性 SLA，单会话可能占满总线。
+
+core 不传配置时用默认值；显式配置必须完整包含 concurrency、queueLimit、recordLimit、resultBytes、retentionMs 五项正安全整数。拒绝缺项、额外字段与访问器；构造时复制冻结，无动态更新接口。
+
+保留期通过新请求或控制消息触发惰性清理，也可调用实例 `sweep()`；不是精确的一小时定时删除，闲置时记录可能继续占内存，但后续正常查询会先清理过期记录。无磁盘任务库。结果大小检查在 Handler 返回后进行，Handler 自身也必须限制内存分配。敏感返回内容仍可能进入宿主会话日志，本插件不是秘密识别器。
+
+关闭停止受理，取消队列和运行任务，等待合作 Handler。正常路径复用 Job 窗口等待；服务异常后仍先排空执行，再有界检查记录并保留原服务错误。持续故障可能留记录到宿主生命周期清理，不合作 Handler 可能阻碍关闭。
+
+## 5. 重试与恢复语义
+
+当前没有网络传输层，自动通信重试与执行重试均为 0。正常 Job 的 60 秒窗口只由程序续等，不自动改为失败；异常清理有界检查也不是模型轮询或执行重试。
+
+同存活实例、保存期内的请求复用不是端到端 exactly-once；每个实际工具调用仍有自己的宿主结果记录。没有外部终态注入接口，也没有跨重启恢复：任一阶段进程崩溃都会丢失插件内存状态。宿主日志不能复活旧 Promise，不追加聊天消息冒充原调用恢复。
+
+## 6. 扩展 Handler
+
+包的 `./core` 导出 ExecutionBus、Handler、Capability 类型。Handler 只接收输入、requestId、signal、progress 和可选最小 capability，不接收聊天历史。register 返回绑定唯一注册令牌的幂等注销函数，不会误删后来同名注册；已受理请求继续持有原 Handler。
+
+内置 test 和 host.read 没有非幂等写能力。当前没有 ctx.executionBus 服务、远端传输、跨插件动态注册或外部副作用对账契约。扩展有副作用 Handler 前必须另行设计授权、幂等与崩溃对账，不能仅依赖本版请求键。

package/docs/releases/0.1.0.md

@@ -1,5 +1,7 @@
 # 执行总线 0.1.0
 
+> 历史版本说明：名称、能力和验证结论以该版本发布时为准，不代表当前版本状态。当前行为与限制请阅读 [README](<../../README.md>) 和[验证范围](<../validation.md>)。已发布标签及安装包不会因本文后续澄清而改变。
+
 ## 本版变化
 
 第一阶段纯插件原型：版本化协议、有界队列、请求复用与冲突检查、原工具异步等待、宿主 Job 进度、受控测试 Handler 和宿主只读 read 接入。测试与发布流程参考 dsh-vcs，标签触发四矩阵 CI，正式发布独立手动门禁。
@@ -14,4 +16,4 @@
 
 ## 验证
 
-真实宿主组件与 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。
+真实宿主组件与 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

@@ -1,5 +1,7 @@
 # 执行总线 0.1.1
 
+> 历史版本说明：名称、能力和验证结论以该版本发布时为准，不代表当前版本状态。当前行为与限制请阅读 [README](<../../README.md>) 和[验证范围](<../validation.md>)。已发布标签及安装包不会因本文后续澄清而改变。
+
 ## 本版变化
 
 本版为 BUG 修复，无新增业务执行能力。

package/docs/releases/0.1.2.md

@@ -1,5 +1,7 @@
 # 执行总线 0.1.2
 
+> 历史版本说明：名称、能力和验证结论以该版本发布时为准，不代表当前版本状态。当前行为与限制请阅读 [README](<../../README.md>) 和[验证范围](<../validation.md>)。已发布标签及安装包不会因本文后续澄清而改变。
+
 ## 本版变化
 
 文档易用性补丁，不改变插件执行逻辑或工具参数。

package/docs/releases/0.2.0.md

@@ -1,5 +1,7 @@
 # 执行总线 0.2.0
 
+> 历史版本说明：名称、能力和验证结论以该版本发布时为准，不代表当前版本状态。当前行为与限制请阅读 [README](<../../README.md>) 和[验证范围](<../validation.md>)。已发布标签及安装包不会因本文后续澄清而改变。
+
 ## 新增功能
 
 新增可选 Agent 预设“执行总线测试 / Execution Bus Test”，通过标准 dsh.bundle.patch 声明，出现在宿主 Agent 预设自定义列表。无需修改宿主前端或 DSH 源码。不会改变默认模式或已有会话。

package/docs/releases/0.2.1.md

@@ -1,5 +1,7 @@
 # 执行总线 0.2.1
 
+> 历史版本说明：名称、能力和验证结论以该版本发布时为准，不代表当前版本状态。当前行为与限制请阅读 [README](<../../README.md>) 和[验证范围](<../validation.md>)。已发布标签及安装包不会因本文后续澄清而改变。
+
 ## 本版变化
 
 规范正式产品命名：Agent 预设显示名统一为“执行总线 / Execution Bus”，不再带“测试 / Test”。用途、只读限制及验证边界保留在描述中，不用显示名称暗示完整生产验收。

package/docs/releases/0.2.10.md

@@ -1,5 +1,7 @@
 # 萧何 / Xiao He 0.2.10
 
+> 历史版本说明：名称、能力和验证结论以该版本发布时为准，不代表当前版本状态。当前行为与限制请阅读 [README](<../../README.md>) 和[验证范围](<../validation.md>)。已发布标签及安装包不会因本文后续澄清而改变。
+
 ## BUG 修复
 
 Job 等待通道或清理服务异常时，不再在执行仍运行中提前结束原工具调用。保留调用方取消监听，等待原执行和宿主 outcome 达到终态，再尽力清理并返回原服务错误。不会因通信失败自动重跑或误记执行失败。

package/docs/releases/0.2.11.md

@@ -1,5 +1,7 @@
 # 萧何 / Xiao He 0.2.11
 
+> 历史版本说明：名称、能力和验证结论以该版本发布时为准，不代表当前版本状态。当前行为与限制请阅读 [README](<../../README.md>) 和[验证范围](<../validation.md>)。已发布标签及安装包不会因本文后续澄清而改变。
+
 ## BUG 修复
 
 移除等待异常排空对作用域内 Job 终态观察者的依赖，修复等待服务先失败、随后 Agent/插件作用域卸载时，监听器先被解除导致原调用及卸载永久等待的问题。

package/docs/releases/0.2.12.md

@@ -0,0 +1,19 @@
+# 萧何 / Xiao He 0.2.12
+
+## 文档纠错与整理
+
+本版只整理对外文档，不修改插件运行逻辑或工具参数。
+
+- 重组使用、协议、兼容性、验证和维护说明，统一当前名称与版本语境。
+- 纠正验证文档中“21 项测试、尚未发布/推送”等过时状态；用 v0.2.11 的冻结证据与未验收清单分层说明，不预写本版发布成功。
+- 移除指向未分发宿主快照的失效相对链接，保留组件名、构建符号、版本和定位行号。
+- 修正流程图：先判断重复请求，终态结果复用不需要新 Job 准入；补充取消示例的并发要求和立即返回状态语义。
+- 纠正错误分层、TTL 惰性清理、协议关联与容量说明，区分固定 Handler 错误码和宿主服务错误。
+- 将已经修复的短暂 Job 问题从“待优化”移除，说明 test:flow 不覆盖全部后续集成用例。
+- 历史发布说明增加版本语境提示；保留当时名称、缺陷与验证事实，不重写标签或公开包。
+
+## 验证与限制
+
+执行全量回归、对外文档链接检查、示例协议验证、包白名单及生产隔离安装；本版正式发布仍需标签四矩阵和候选一致性门禁。文档检查不等于 Mermaid 页面实际渲染或宿主 GUI 验收。
+
+DSH 0.2.0-rc.2，非商业源码公开许可。真实模型、桌面卡片、实际沙箱及 PTC 完整链路未验收，不支持跨重启恢复；发布不自动安装或重启 DSH。

package/docs/releases/0.2.2.md

@@ -1,5 +1,7 @@
 # 执行总线 0.2.2
 
+> 历史版本说明：名称、能力和验证结论以该版本发布时为准，不代表当前版本状态。当前行为与限制请阅读 [README](<../../README.md>) 和[验证范围](<../validation.md>)。已发布标签及安装包不会因本文后续澄清而改变。
+
 ## BUG 修复
 
 - 终态提交先准备返回快照再更新状态；深层结果或快照构造失败会明确结算为 unknown / RESULT_NOT_RETAINED，避免原工具调用和关闭流程永久等待。

package/docs/releases/0.2.3.md

@@ -1,5 +1,7 @@
 # 萧何 / Xiao He 0.2.3
 
+> 历史版本说明：名称、能力和验证结论以该版本发布时为准，不代表当前版本状态。当前行为与限制请阅读 [README](<../../README.md>) 和[验证范围](<../validation.md>)。已发布标签及安装包不会因本文后续澄清而改变。
+
 ## 名称统一
 
 统一当前产品显示名为“萧何 / Xiao He”，覆盖 Agent 预设卡片、工具说明、任务标签、模式提示、README、npm 描述和新 GitHub Release 标题。“执行总线”保留为技术功能描述，不代表新增人物 Agent 或角色扮演能力。
@@ -8,6 +10,6 @@
 
 ## 验证与限制
 
-本版只调整名称和文字，不混入已审核但尚未修复的异步观察者异常隔离、数组子类 JSON 保真问题。它们仍影响 core 扩展边界，不能将更名称为缺陷已修复。全量回归、预设隔离、标签四矩阵、包校验和同包安装按既有门禁执行。
+本版只调整名称和文字，不混入已审核但尚未修复的异步观察者异常隔离、数组子类 JSON 保真问题。它们仍影响 core 扩展边界，不能将更名表述为缺陷已修复。全量回归、预设隔离、标签四矩阵、包校验和同包安装按既有门禁执行。
 
 实际桌面未安装，不保证当前界面立即出现卡片；用户已选择只发布暂不安装。真实模型、桌面 GUI 和 PTC 全链路仍未验收，不支持跨重启恢复。非商业源码公开许可，不自动安装或重启 DSH。

package/docs/releases/0.2.4.md

@@ -1,5 +1,7 @@
 # 萧何 / Xiao He 0.2.4
 
+> 历史版本说明：名称、能力和验证结论以该版本发布时为准，不代表当前版本状态。当前行为与限制请阅读 [README](<../../README.md>) 和[验证范围](<../validation.md>)。已发布标签及安装包不会因本文后续澄清而改变。
+
 ## BUG 修复
 
 - 隔离事件观察者返回 Promise 的异步拒绝，避免异步日志/通知回调形成未处理 rejection 并导致进程退出。通知不阻塞执行或终态结算，不将观察者异常原文写入日志。

package/docs/releases/0.2.5.md

@@ -1,5 +1,7 @@
 # 萧何 / Xiao He 0.2.5
 
+> 历史版本说明：名称、能力和验证结论以该版本发布时为准，不代表当前版本状态。当前行为与限制请阅读 [README](<../../README.md>) 和[验证范围](<../validation.md>)。已发布标签及安装包不会因本文后续澄清而改变。
+
 ## BUG 修复
 
 - Handler 注销函数绑定唯一注册令牌并支持幂等清理。旧注销函数重复执行不会误删后来同名注册，即使复用相同 Handler 对象。已受理请求继续使用它捕获的旧 Handler，新请求使用当前注册。

package/docs/releases/0.2.6.md

@@ -1,5 +1,7 @@
 # 萧何 / Xiao He 0.2.6
 
+> 历史版本说明：名称、能力和验证结论以该版本发布时为准，不代表当前版本状态。当前行为与限制请阅读 [README](<../../README.md>) 和[验证范围](<../validation.md>)。已发布标签及安装包不会因本文后续澄清而改变。
+
 ## BUG 修复
 
 - 重复附着在取得观察者名额后才提交消息记账，WAITER_LIMIT 拒绝不再占用消息编号或耗尽后续查询/结果重取额度。已有重复识别和取消保留槽语义不变。

package/docs/releases/0.2.7.md

@@ -1,5 +1,7 @@
 # 萧何 / Xiao He 0.2.7
 
+> 历史版本说明：名称、能力和验证结论以该版本发布时为准，不代表当前版本状态。当前行为与限制请阅读 [README](<../../README.md>) 和[验证范围](<../validation.md>)。已发布标签及安装包不会因本文后续澄清而改变。
+
 ## BUG 修复
 
 - core 构造器补齐完整配置校验：不传参数仍使用默认值；显式配置须包含 concurrency、queueLimit、recordLimit、resultBytes、retentionMs 五项正安全整数。缺项、额外字段、非对象及访问器立即 INVALID_OPTIONS，避免受理后因缺少并发配置而不执行。不扩展部分配置契约。

package/docs/releases/0.2.8.md

@@ -1,5 +1,7 @@
 # 萧何 / Xiao He 0.2.8
 
+> 历史版本说明：名称、能力和验证结论以该版本发布时为准，不代表当前版本状态。当前行为与限制请阅读 [README](<../../README.md>) 和[验证范围](<../validation.md>)。已发布标签及安装包不会因本文后续澄清而改变。
+
 ## BUG 修复
 
 已终态且仍在保存期的重复请求直接返回保存结果，不再申请新的宿主 Job，修复其他任务占满 Job 容量时，相同请求重发错误返回 HOST_JOB_UNAVAILABLE 的问题。

package/docs/releases/0.2.9.md

@@ -1,5 +1,7 @@
 # 萧何 / Xiao He 0.2.9
 
+> 历史版本说明：名称、能力和验证结论以该版本发布时为准，不代表当前版本状态。当前行为与限制请阅读 [README](<../../README.md>) 和[验证范围](<../validation.md>)。已发布标签及安装包不会因本文后续澄清而改变。
+
 ## BUG 修复
 
 修复终态 Job 被其他合法订阅者先行移除时，原工具调用错误返回 unknown job、无法交付已有执行结果的问题。等待及清理路径仅对当前调用创建的确切 Job 未找到错误、且同一 owner 查询确认已不存在时做幂等处理；继续等待原执行结果，不把记录移除当作成功。权限及其他服务异常仍明确失败，不一概吞掉。

package/docs/releases/0.3.0.md

@@ -0,0 +1,21 @@
+# 萧何 / Xiao He 0.3.0
+
+## 能力补全
+
+本版将萧何从只读验证模式改为“宿主 PTC 工具组合 + 可选执行总线”。加载时读取目标宿主已声明的 ptc 组合快照，保留原配置、平台表达式和禁用项，再追加总线和使用说明。移除萧何的 native 强制呈现与只读白名单。原预设、默认选择及技术 ID 不变。
+
+普通终端、编辑、搜索、技能、委派等任务仍调用原工具，经过宿主原有授权、沙箱与工作目录规则，不强制走总线。总线仍仅支持 test / host.read；不能把命令启动或 Job ID 当成完成。源 PTC 中禁用的专用插件管理工具不会自动启用。
+
+## 升级注意
+
+**旧只读模式升级后工具能力扩大。** 请先审阅目标 PTC 配置再加载，新建专门会话验证；不自动安装或重启日常 DSH。需要宿主先提供 ptc 声明，缺失时最多等待约 5 秒后报错，不静默回退。源预设编辑不会自动热同步；按宿主正常方式重载派生行后，新会话使用新快照，已有会话遵循宿主版本保留规则。
+
+公开 readDocument 不提供原声明 baseUrl，因此本版拒绝含相对模块/include 文件的组合，避免错误重定位；不声称兼容全部自定义 PTC。源预设的组件缺失、策略禁止或禁用项会继续影响能力。
+
+## 验证
+
+声明保真测试覆盖分组、禁用管理工具、!!js 平台表达式；真实 Cordis 生命周期和 AgentPresetRegistry 验证派生注册、write/edit 保留、宿主拒绝策略继续生效、原 PTC 未被修改、原 Agent 不可见总线。真实 Node PTC 子进程验证 run_code 同时调用原 read 和执行总线。
+
+PTC 测试采用显式 danger-full-access 策略与测试 Agent，不能视为桌面沙箱、真实模型或所有日常工具的全链路验收。不提供真实模型性能提升比例。无持久化或跨重启恢复能力。
+
+非商业源码公开许可，宿主兼容目标仍为 DSH 0.2.0-rc.2。

package/docs/validation.md

@@ -1,61 +1,58 @@
-# 验证记录与交付状态
+# 验证范围与使用限制
 
-日期：2026-10-15。Node 24.21.0，Windows，宿主精确兼容目标 0.2.0-rc.2。全部开发改动仅在当前独立仓库，未修改/重启 DSH，未发布 npm、未推送远程、未安装用户日常配置。
+本文说明当前版本的证据边界，不是生产环境认证。当前预设能力基线为 **v0.3.0**；总线执行核心沿用此前验证，新增的是宿主 PTC 声明派生与叠加模式。验证环境为 Windows、Node.js 24.21.0，宿主组件锁定 DSH 0.2.0-rc.2、Cordis 4.0.4。
 
-## 自动化测试
+## 已验证什么？
 
-npm test：**21/21 通过**。本地 tgz 已在 artifacts/package-check 独立目录完成 npm 安装及入口 import 验证（不是 DSH 插件管理器安装）。测试名称是断言集合，不等于 21 项完整产品验收。
+| 层次 | 检查内容 | 能说明什么 |
+|---|---|---|
+| 总线核心 | 参数、队列、并发、重复请求、冲突、取消竞争、结果保存、TTL、监听与注销 | 程序内部约束及已覆盖异常路径可重复检查 |
+| 真实宿主组件 | Cordis、ToolRuntime、LocalJobs、LocalFS、文件工具 | 请求经过真实工具管线；权限拒绝、Job 进度、共享任务与清理逻辑有效；Agent 身份为夹具 |
+| 真实会话循环 | AgentLoop、AgentRegistry、SessionStore；脚本模型适配器 | 内存会话中原工具结果只提交一次，完成后再进入下一次适配器调用 |
+| 预设隔离 | AgentPresetRegistry 与 Loader | 派生预设可激活；源 ptc 声明不变、普通 Agent 不可见总线；原 write/edit/Job 工具保留，宿主前置策略拒绝仍有效 |
+| 故障注入 | 克隆失败、观察者拒绝、Job 等待/清理异常、先行移除与卸载交错 | 指定故障下的回归约束；不证明所有故障组合都已覆盖 |
+| 候选包 | 严格文件白名单、临时目录生产依赖安装、入口注册 | 包可安装和加载；安装验证使用简化宿主夹具，不是桌面插件管理器验收 |
 
-- 正常请求、受理不冒充成功、原 Promise 等待、终态只有一次、交付标记分离。
-- 两个 session 同 requestId 结果独立，第三会话查询/取消拒绝。
-- 同请求共用执行，同键不同输入冲突；同参数新键为不同操作。
-- 重复/乱序/迟到进度丢弃，观察者抛错不影响执行。
-- 等待时间短于执行时仍保持运行，不生成失败。
-- 排队取消、运行取消、晚取消、完成竞争；取消未确认为 unknown；unknown 不自动重跑。
-- 队列/记录容量背压、并发为一时第二任务保持 queued、控制消息上限。
-- Handler 异常、未知 Handler、未知消息类型/版本、伪造身份字段、输入越界、结果过大、异常敏感文本不泄漏。
-- 关闭合作任务并拒绝新受理；终态 TTL 清理，不误清理运行任务。
+v0.2.11 本地回归基线为 **48/48 通过**；本版新增声明保真、真实注册生命周期及真实 Node PTC 桥接测试，最新数量以命令输出为准。测试项数量是用例数量，不是全部产品验收条数。当前结果请重新运行下述命令；文档测试数不应代替实际输出。
 
-真实宿主**组件**隔离测试使用 npm 原版 Cordis + ToolRuntime + LocalJobs + LocalFS + tool-fs。Agent/agents 注册表是夹具，没有运行真实 AgentLoop 或模型。测试通过实际 read 工具读取本仓库包声明，通过真实 pre-execute 拒绝读操作，确认权限管线仍在；测试进度事件、awaited 终态、Job 移除、重复请求并发、调用中断、插件作用域卸载和工具注销。
+```powershell
+npm ci --include=dev --ignore-scripts
+npm run check
+npm run verify:package
+npm run test:install
+```
 
-## 真实宿主循环隔离验证
+## 已发布不等于已在日常环境验收
 
-另有独立测试运行真实 AgentLoop、AgentRegistry、SessionStore、ToolRuntime 和 Jobs；模型侧是确定性 Scripted LlmAdapter，不访问网络或凭据。适配器先产生一次 execution_bus 请求，宿主等待成功终态并记录一次 tool/result，toolCallId 为 original-call，随后才进行第二次适配器调用并完成回答。无模型轮询、无额外聊天进度消息。这是实际宿主循环和内存会话闭环，不是实际模型评测，也没有验证磁盘持久化。
+项目已经正式发布到 npm 与 GitHub，不再是“仅有本地源码、尚未推送”。v0.2.11 的[标签 CI](https://github.com/f-e-n-g-0531/dsh-execution-bus/actions/runs/38741066848)和[发布工作流](https://github.com/f-e-n-g-0531/dsh-execution-bus/actions/runs/38741256031)均成功。
 
-## 未验证（不是通过）
+该版本公开 npm 与 GitHub tgz 均为 **37,036 字节**，与候选逐字节一致，SHA-256：
 
-| 项目 | 状态与原因 |
-|---|---|
-| 当前桌面真实模型 → 原调用 → 结果 → 模型继续 | 未验证；未安装到日常宿主，也未启用真实模型凭据 |
-| GUI Jobs 实际可视展示 | 未验证；仅证明进度事件进入真实 Job 注册表 |
-| 当前 Windows 授权提示和文件沙箱集成 | 未验证；测试使用 LocalFS 和前置拒绝策略，不代表桌面沙箱 |
-| PTC 完整进程入口和超时 | 源码核查/类型兼容；未执行真实 PTC 冒烟 |
-| 真实模型面对重复终态的继续行为 | 真实循环的单次结果提交已验证；真实模型及外部终态重投链路未验证 |
-| 跨重启恢复原调用 | 不支持，不能用新消息冒充 |
-| 受理/运行/结果/交付四阶段持久化崩溃注入 | 未实现持久化，不声称通过；当前实例丢失的边界测试通过 |
-| 模型轮次、主动查询、重复执行、总耗时对照 | 全部未验证；不捏造提升比例 |
-| 插件管理器完整安装、卸载与回滚 | 未验证；仅包构建/内容检查及 Cordis effect 注销 |
-
-## CI 与发布流程检查
-
-参考 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。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 环境此前不存在，未配置维护者保护审批，发布使用用户授权及工作流明确确认门禁。
-
-## 已完成 / 部分完成 / 后续
+```text
+eb95b4e51675f5f1821275e0812ef4dd4984b1aba45a52fbc6bab3518bbf6f38
+```
 
-已完成：可编译独立插件、协议/状态核心、测试 Handler、真实只读执行管线适配、宿主 Job 进度事件、自动化测试和中文文档。
+这只证明那个冻结版本的制品事实，不代表任何后续版本已发布，也不代表此刻 npm latest 永远保持该版本。最新状态请看 [npm](https://www.npmjs.com/package/@feng0531/dsh-execution-bus) 与 [GitHub Releases](https://github.com/f-e-n-g-0531/dsh-execution-bus/releases)。每次正式发布另须通过同标签 Windows/Ubuntu × Node 22/24 四矩阵及制品一致性门禁。
 
-部分完成：会话闭环已验证到真实 AgentLoop/内存 Session，使用脚本适配器；真实模型与磁盘会话仍未验证。显示名称体现在工具说明和 Job 标签，未提供插件市场 UI 元数据。Handler core 可扩展，尚无跨插件服务。
+## 未验证或不支持
 
-未实现：持久化、跨重启重关联、非幂等 Handler 对账、远端传输与通信重试（当前零重试）、自定义 UI。只做插件的约束保持不变。
-
-下一步应先在用户明确授权的隔离 DSH 配置进行真实模型/AgentLoop/PTC/GUI 冒烟，再决定持久化范围。不应先上线任意命令或有副作用执行 Handler。
-
-## 已知限制
-
-- 并发重复附着现在共享一个宿主 Job 和程序等待者；回归测试断言只新增一个 Job。Job admission 首次失败会取消尚未执行的受理请求。从 0.2.8 起，保存期内已终态请求的重复提交直接复用保存结果，不再新建短暂 Job，也不受新的 Job 容量准入影响；新任务仍受宿主容量限制。
-- 同一逻辑请求的任一等待工具被取消，会请求取消共享执行；这是本版明确的请求级取消规则，不是独立等待者取消。
-- returned 不证明宿主已经持久化或模型已经消费，取消/后置策略仍可能改变最终宿主结果。
-- 核心不是独立安全边界；可信插件可以注册 Handler，恶意同进程插件不在威胁模型内。
-- 本地源码证据快照不包含在 npm 包中；文档相对证据链接适用于开发仓库提取后阅读，安装包读者应使用所列组件名及构建行号查对应版本。
+| 项目 | 当前结论 |
+|---|---|
+| 当前桌面真实模型发起请求并继续推理 | 未验收；脚本适配器不是实际模型 |
+| 当前桌面预设卡片、进度界面、授权提示和实际沙箱 | 未验收；组件事件和 LocalFS 测试不等于桌面 UI/沙箱 |
+| 实际模型/桌面 PTC 与时间预算、沙箱行为 | 真实 Node PTC 隔离子进程已调用原 read 和总线；使用显式 danger-full-access 测试策略与测试 Agent，不是桌面沙箱/真实模型验收 |
+| 从真实 tgz 经宿主插件管理器加载预设、卸载与回滚 | 未完成完整桌面流程；源码工作区的 Loader 测试不能替代 |
+| 磁盘会话结果提交及重启恢复原调用 | 未验收磁盘提交；本插件不支持跨重启恢复 |
+| 减少真实模型轮次、状态查询或总耗时的对照 | 未验证，不给提升比例 |
+| 长期运行、所有卸载/服务故障组合 | 未穷尽；持续故障仍有清理限制 |
+
+## 需要知道的运行约束
+
+1. 受理、队列、结果及交付标记均在内存。进程关闭会丢失，宿主会话日志不等于插件恢复执行权。
+2. 同一预设的会话共享总线容量，结果访问按会话隔离；不是独立进程或资源安全隔离。
+3. 取消任一正在等待的重复调用会请求取消整个逻辑执行，不是仅停止该等待者。
+4. 已终态且未过期的请求可直接复用结果，不申请新 Job；仍须通过身份、冲突及消息额度检查。
+5. 等待服务异常后先排空原执行，再有界检查宿主记录；服务持续不可用时记录可能留到所属生命周期清理。不合作 Handler 仍可能阻碍关闭。
+6. `returned` 不是宿主持久化或模型消费确认；外层取消和后置策略仍可能改变最终工具结果。
+
+开发者可阅读[流程测试说明](<FLOW-TEST.md>)、[协议](<protocol.md>)和[宿主兼容性](<host-compatibility.md>)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feng0531/dsh-execution-bus",
-  "version": "0.2.11",
+  "version": "0.3.0",
   "type": "module",
   "private": false,
   "license": "SEE LICENSE IN LICENSE",
@@ -17,7 +17,8 @@
   "exports": {
     ".": "./dist/plugin.js",
     "./core": "./dist/bus.js",
-    "./test-mode": "./dist/test-mode.js"
+    "./test-mode": "./dist/test-mode.js",
+    "./preset": "./dist/preset.js"
   },
   "files": [
     "dist",
@@ -27,7 +28,11 @@
     "README.md",
     "docs"
   ],
-  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
   "engines": {
     "node": ">=22"
   },
@@ -45,23 +50,33 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/dsh-scope": "0.2.0-rc.2",
+    "@deepseek-ai/cordis-plugin-include": "~1.0.9",
+    "@deepseek-ai/dsh-agent-preset-registry": "0.2.0-rc.2",
     "@deepseek-ai/dsh-jobs": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-scope": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.2",
     "@deepseek-ai/dsh-tools": "0.2.0-rc.2"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-agent-loop": "0.2.0-rc.2",
     "@deepseek-ai/dsh-agent-preset": "0.2.0-rc.2",
     "@deepseek-ai/dsh-agent-preset-registry": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-agent-tool-presentation": "0.2.0-rc.2",
     "@deepseek-ai/dsh-fs-local": "0.2.0-rc.2",
     "@deepseek-ai/dsh-jobs": "0.2.0-rc.2",
     "@deepseek-ai/dsh-jobs-local": "0.2.0-rc.2",
     "@deepseek-ai/dsh-persona": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-ptc-runtime-node": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-subprocess-local": "0.2.0-rc.2",
     "@deepseek-ai/dsh-tool-fs": "0.2.0-rc.2",
     "@deepseek-ai/dsh-tool-jobs": "0.2.0-rc.2",
+    "@types/js-yaml": "4.0.9",
     "@types/node": "^22",
     "prettier": "3.6.2",
     "typescript": "~5.9.3",
     "yaml": "2.9.1"
+  },
+  "dependencies": {
+    "js-yaml": "4.3.2"
   }
 }