@feng0531/dsh-execution-bus 0.12.1 → 1.0.0

package/docs/INTEGRATION.md

@@ -1,4 +1,6 @@
-# 同类项目源码参考与整合（0.5.0–0.12.1）
+# 同类项目源码参考与整合（0.5.0–0.12.1，历史）
+
+> 历史文档：记录 0.x 执行总线阶段的第三方参考。1.0 起产品为声明式运行时，相关来源与边界见 [声明式运行时](<DECLARATIVE-RUNTIME.md>)；本页保留为历史。
 
 ## 本轮交付
 

package/docs/PRODUCT.md

@@ -2,55 +2,28 @@
 
 ## 产品边界
 
-萧何是 DSH 内的可选执行协调插件，提供独立可选择的 PTC 派生预设，不是 PTC 替代传输层，也不全局接管终端、编辑或其他工具。实际业务 Handler 为 host.read、host.glob、host.grep（只读、幂等）与 host.edit、host.write、host.pwsh（有副作用、非幂等）；test 是兼容保留的诊断 Handler，只有明确诊断需求时使用。测试能力存在不代表其他工具或命令已接入总线。
+萧何是 DSH 内的可选**声明式运行时**插件：模型提交 DAG 计划，运行时按依赖执行宿主工具（read/glob/grep/edit/write/pwsh），负责并行、只读重试、超时、结果落盘、取消与重启后恢复。它不是模型、不是通用工作流引擎、不接管全部工具；权限、沙箱与审批仍由宿主管理。
 
-0.8.0 在 DSH 0.2.1-rc.2 基线上补入只读搜索 Handler host.glob / host.grep 与有副作用命令 Handler host.pwsh，沿用 0.7.0 的幂等声明与宿主工具工厂，不以更名宣称完成生产环境认证。当前真实模型、桌面 UI 和实际沙箱尚未完整验收；同进程内存状态不支持跨重启恢复。
+1.0 移除了 0.x 的执行总线（`execution_bus`、`./core` 导出与总线预设），旧版本保留在 npm/git 历史，不再维护。
 
-0.9.0 增加 PTC 预算到期后的分离等待：宿主中断 PTC 子调用时，已受理执行只解除等待、继续运行，可用同 requestId 的 status/result 取回或用 cancel 取消；其他中断原因仍按取消处理。该区分依据 DSH 0.2.1-rc.2 的中断原因字符串，不是公开稳定契约，宿主升级需复核。
-
-0.10.0 改善模型侧的采用条件：模式说明写明使用场景并给出调用示例；工具声明把 payload 改为按 Handler 的判别联合，PTC SDK 与原生声明直接显示每个 Handler 的必填/可选字段。wire 协议、字段、错误码与 Handler 行为不变，只改变模型可见的提示与 schema。
-
-0.11.0 根据 pilot 收紧为收益导向触发：重复提交/重试去重、预算结束后继续/跨步骤取回、多等待者同一执行才用总线，时长本身不是理由；新增简化调用（requestId+handler+input，messageId 自动生成）与控制（requestId+type），完整 v1 消息仍兼容；快照在复用时带 reused:true，并新增只读的会话采用率统计脚本。
-
-0.12.0 补充调度隔离：Handler 可声明调度类别、舱壁、资源键与 payload 唯一任务；内置写 Handler 按文件路径互斥；状态快照增加 longRunning 与等待原因。参考来源与许可见 [整合说明](<INTEGRATION.md>)，未引入第三方运行依赖；fast-check 仅用于开发属性测试。
-
-0.12.1 修正 0.12.0 的默认行为风险：内置 host.* 关闭 payload 去重（文件/权限/工作目录变化后旧结果会静默过期），只保留核心 Handler 能力供扩展自担失效责任；等待老化不封顶，避免 default 类别饥饿；唯一复用副本计入保留字节并写入时间戳；waitReason 区分 bulkhead 与 resource；注册时校验并冻结调度选项、拒绝 accessor/原型污染键；validate/resources 内同步 close 后不再插入不可结算记录；消息身份改存摘要，降低同 requestId 多条消息的内存占用。
-
-## 入口及配置层次
+## 入口与配置
 
 | 入口 | 谁使用 | 责任 |
 |---|---|---|
-| 包级 bundle /preset | 目标 DSH 配置加载器 | 读取 ptc 声明快照，注册独立萧何预设 |
-| Agent 内 /mode | 萧何预设末尾插件行 | 保留原 PTC 组合，追加总线工具和说明 |
-| /test-mode | 旧配置兼容 | 直接映射同一个正式 mode 模块，不维护第二份实现 |
-| 包根入口 | 明确自行组装的宿主 | 注册 execution_bus、execution_bus_state，不派生 PTC |
-| /core | 可信嵌入方 | 自行注册 Handler 的内存核心，不提供外部身份认证 |
-
-正式代码在 src/mode.ts，src/test-mode.ts 只重导出。package exports 的新旧入口均映射 dist/mode.js，避免 Cordis 因插件模块身份不同而重复激活；旧物理构建文件仍兼容重导出。不要同时配置两行别名。预设 ID execution-bus-test 和配置行 ID preset-execution-bus-test 是历史兼容身份，不继续用于推荐显示名称。
-
-## 模块职责
-
-| 模块 | 负责 | 不负责 |
-|---|---|---|
-| product | 固定身份、容量/准入默认值、工具参数与提示契约 | 不提供用户可覆盖的运行时配置入口 |
-| preset | 声明派生、兼容检查和宿主注册 | 不偷偷重写源 ptc 或持久配置 |
-| mode / test-mode 兼容层 | 作用域说明与工具安装 | 不改宿主权限/沙箱/呈现，不加载第二套 PTC |
-| plugin | 工具身份校验、可信执行上下文和宿主工具派发 | 不自行文件读取、搜索或创建通用命令执行端 |
-| bus / json | 请求校验、幂等冲突、调度、取消、终态与有界状态 | 不以超时推定副作用失败、不自动重跑 |
-| execution | Job 投影、活跃工具交付与关闭所有权 | 不作为第二个执行状态机 |
-| handlers | 宿主工具转发（read/glob/grep/edit/write/pwsh）和明确诊断 Handler | 不把测试当成通用业务执行 |
-| diagnostics | 有界数值轨迹 | 不保留请求内容、错误原文或充当授权审计 |
+| 包级 bundle /preset | DSH 配置加载器 | 读取 ptc 声明快照，注册独立预设 `xiao-he-runtime` |
+| Agent 内 /mode | 预设末尾插件行 | 追加运行时工具与模式说明 |
+| `./test-mode` | 兼容别名 | 与 /mode 同一模块 |
 
-## 兼容和错误规则
+普通任务继续用原工具；运行时只处理“能写成稳定 DAG”的协调工作，简单一次性操作不包装。
 
-稳定工具名、请求协议和历史预设身份保留。协议校验/背压错误与执行快照中的固定错误码分层；宿主服务错误继续保持真实失败，不统一吞掉，也不把 error 文本写入数值诊断。完整错误词汇见协议说明，本轮不重命名既有错误码。
+## 非目标
 
-单一策略定义不表示开放 YAML 调参：宿主插件目前使用固定默认值；core 构造参数仍按原契约使用。新增配置界面需单独定义校验、升级与误配置回归，不能只在文档放不存在的 config 键。
+- 不做跨进程/分布式执行、不做 exactly-once 副作用回滚、不做跨重启的在途副作用恢复。
+- 不替代宿主后台 Job、Teams、Skills、Goals；这些仍是长任务、并行扇出、流程复用的首选。
+- 不承诺真实模型/桌面 UI/实际沙箱验收，只提供组件与真实 ToolRuntime 测试证据。
 
-## 交付要求
+## 维护契约
 
-- 修改身份、默认策略或工具提示时，验证共享 product 契约与实际宿主状态工具一致。
-- 新旧 mode 必须指向同一个模块，派生预设必须使用正式入口。
-- 严格包白名单覆盖正式模块、兼容转发与类型文件；生产隔离安装通过包导出导入两入口核对身份。
-- 继续全量 core、真实宿主生命周期及 Node PTC 回归，不用文档测试替代桌面验收。
-- 完整验证后统一标签 CI 和正式发布；发布不自动安装/重启日常 DSH。
+- 工具名与公开导出变更必须升主版本；工具 schema 变更需同步文档与测试。
+- 运行记录格式带 `version:1`；破坏兼容需迁移或拒绝旧记录。
+- 发布门禁：全量测试、包白名单、标签 CI 四矩阵、npm 后公开校验、GitHub Release。

package/docs/RETROSPECTIVE.md

@@ -0,0 +1,51 @@
+# 复盘：萧何（dsh-execution-bus）为什么没有成为“更优的 PTC 模式”
+
+> **后续（2026-10）**：项目已按新方向改造为 **1.0 声明式运行时**（`runtime_run`）；下文的 0.x 结论仍成立——原“执行总线模式”不再维护，0.12.1 是最后的总线版本，本文保留为历史复盘。
+
+> 结论先行：作为“通用 PTC 更优模式”的产品假设**未被证据支持**；0.x 执行总线冻结于 **0.12.1**，不再做功能发版。本文记录做了什么、被证伪了什么、留下了什么、以及什么条件下才值得重启（该条件促成了 1.0 的运行时方向）。
+
+## 一、做了什么
+
+从 0.7.0 到 0.12.1，项目实现了：会话级有界总线（并发/队列/记录/结果字节/保留期）、按会话轮转与类别优先级+老化的调度、Handler 舱壁与文件资源键互斥、requestId 去重与终态复用、PTC 预算到期后的分离等待（宿主 Job 投影 + 同 requestId 取回）、宿主工具 Handler（read/glob/grep/edit/write/pwsh/test）、预设派生与模式入口、简化调用 + 类型化 schema、只读会话诊断与采用率统计，以及四矩阵 CI 与逐字节发布门禁。
+
+工程上是扎实的：**128 项测试**全绿，真实 Node PTC 验证了预算分离与外部中断，发布链路对 npm/GitHub 制品做了逐字节一致校验。
+
+## 二、被证伪的核心假设
+
+| 假设 | 证据 | 结论 |
+|---|---|---|
+| “总线让日常任务更快/更优” | 3 任务×2 臂 A/B：普通任务两臂 6/6 成功、**0 次总线调用**、耗时无一致差异 | 普通任务上≈PTC，无增益 |
+| “默认引导走总线更好” | 指引级 A/B：总线优先 18 次调用 vs 可选 11 次；一次性长命令 106.3s vs 71s（含约 19s 排队延迟） | 总线优先是负收益 |
+| “payload 去重能省重复执行” | 0.12.0 内置 host.* 去重导致陈旧读（read→write→read 返回旧内容），已回滚 | 需要 cwd/内容版本/失效模型，裸去重有害 |
+| “存在真实用户需求” | npm 周/月下载 1094（旧版本各 130–156、新版本低，像镜像抓取）；GitHub 0 star/0 fork/0 issue、14 天 11 次浏览 1 访客；本地 156 会话仅 11 用过总线（多为 pilot/审查） | 无外部采用 |
+
+## 三、根因
+
+1. **定位错误**：把“执行协调层”包装成“可选模式/更优模式”。协调收益是**条件性**的（重复/重试、跨预算、多等待者、共享容量/资源锁），不是通用增益。
+2. **没有绝对优势**：原生 PTC + 后台 Job（run_in_background + job_output）已覆盖大部分长任务；总线只多出“统一快照 + 复用语义”，且纯内存、重启即失、无真取消/持久化。
+3. **宿主契约脆弱**：依赖私有中断原因字符串 run_code settled、单实例、无持久化/跨进程接口；升级即可能破坏核心语义。
+4. **需求池太小**：DSH 插件生态本身很小，且没有暴露“多 Agent 共享执行/持久化 exactly-once”这类总线能赢、原生给不了的需求。
+
+## 四、仍可复用的资产
+
+- **PTC 预算分离机制**：run_code settled → 只停止等待、执行继续、宿主 Job 保留（见 [宿主兼容性](<host-compatibility.md>)）。
+- **宿主 Job 投影 / ExecutionOwner**：把 core completion、取消、Job 生命周期和工具交付统一管理。
+- **预设代际（generation）作用域**：插件实例按预设修订共享，跨会话共享容量/资源锁。
+- **幂等/去重语义与陷阱**：requestId 冲突、终态复用、reused:true、payload 去重需失效模型。
+- **工程方法**：128 测试、四矩阵 CI、逐字节发布门禁、证据导向的 A/B 与 pilot——这些比代码更可迁移。
+
+## 五、什么条件才值得重启
+
+- 出现**真实用户报告**的“原生工具解决不了”的需求：多 Agent 共享同一次长执行、跨重启的 exactly-once 副作用、跨进程资源串行。
+- 宿主开放**持久化/真取消/稳定中断契约**，使插件能做出原生做不到的保证。
+- 或把 core 泛化为 **host-agnostic 的持久执行层**（另一个项目，而不是继续修模式层）。
+
+## 六、归档处置
+
+- 冻结于 0.12.1，不再发功能版；仓库保留作参考实现。
+- 不推荐新项目采用；若误装，请改用原生工具与后台 Job。历史发布说明与证据见 [0.12.1 发布说明](<releases/0.12.1.md>) 与 [验证记录](<validation.md>)。
+- npm 已无进一步发布；如需对已发布版本加弃用说明，可在已登录的 npm 环境执行：
+
+    npm deprecate @feng0531/dsh-execution-bus "实验性插件：作为通用 PTC 模式未获采用，已冻结于 0.12.1；保留作 DSH 插件/执行总线参考实现，不推荐新项目采用。"
+
+（本机 npm 未登录，本说明未实际执行。）

package/docs/host-compatibility.md

@@ -1,80 +1,17 @@
-# 宿主兼容性与接入原理
+# 宿主兼容性
 
-## 兼容目标
+目标宿主：DSH **0.2.1-rc.2**、Cordis 4.0.4、Node ≥22。
 
-源码调查基线为 **2026-10-15 的 DSH 0.2.0-rc.2、Cordis 4.0.4**；0.6.0 起兼容目标与 npm 依赖升级为 **DSH 0.2.1-rc.2**（Cordis ~4.0.4），本文调用链行号仍来自 0.2.0-rc.2 调查快照，宿主升级后可能已变化，需按实际安装包复核。本项目用兼容目标版本的 npm 组件编译和隔离测试；这不是对任意旧版、新版宿主的兼容保证，也不是对读者当前安装版本的自动检测。Node.js 要求为 22 或以上；CI 使用 Node 22、24。
+## 依赖的宿主契约
 
-本项目只做插件，没有修改宿主源码、ASAR 或其他插件。
+- 工具注册与执行：`ctx.tools.register` / `ctx.tools.execute`；运行时用父工具调用的 `exec.token` 作为 `parent`，沿用宿主权限、工作目录与沙箱。
+- 预设派生：通过 `agentPresets.readDocument("ptc")` 读取公开声明，再用 `register` 注册派生预设；不修改默认预设或全局工具。
+- 模式提示：`ctx.systemPrompt.section` 追加运行时说明。
 
-## 接入链路
+## 已知边界
 
-```text
-AgentLoop 发起工具调用
-  → ToolRuntime 校验、策略与可信身份绑定
-  → execution_bus 工具体
-  → 内存去重/排队，宿主 Job 记录和程序等待
-  → test Handler 或经 ToolRuntime 再调用宿主工具（read/glob/grep/edit/write/pwsh）
-  → 保存执行结果，清理 Job
-  → 工具体返回
-  → AgentLoop 关联原工具调用并继续会话
-```
+- 运行时在宿主进程内执行；不依赖私有 PTC 中断字符串，也不保证跨宿主版本。
+- 计划步骤使用宿主工具自身 schema；宿主升级导致工具参数变化时需同步计划示例。
+- 运行记录为本地文件，不参与宿主会话日志恢复。
 
-等待由 Promise 完成，不阻塞宿主线程，不为正常等待反复调用模型。进度只交给 Job 机制；宿主的前后置策略、取消和最终会话提交仍有权改变外层工具结果。
-
-### 与 PTC 的关系
-
-PTC 是可选入口：外层 `run_code` 可以调用同一个工具。它不是总线本身，也不会因使用本插件取消自身时间预算。0.3.0 起，“萧何”从目标宿主 ptc 的公开声明派生，保留呈现与全部声明行，不再强制 native 或施加只读 guard。派生组合加入可选总线，其他预设不变。真实 Node PTC 隔离进程已验证原 read 与总线共存；不是桌面/真实模型/实际沙箱的全链路验收。
-
-## 源码证据定位
-
-下表位置来自调查时实际安装包的发布构建文件，均是组件内部的 `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；不是任意身份注入 |
-| PTC 子调用中断 | `@deepseek-ai/dsh-tools`：1282–1285 外层中断转发；1376、1508 子调用信号取自 `runController`；1514 程序结束/预算到期后以固定字符串中断残留子调用 | 外层中断原因与程序结束原因可区分；固定字符串是 rc.2 构建细节，不是公开稳定契约 |
-| 文件读取 | `@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 包，因此本文不再提供指向未分发快照的相对链接。
-
-## 插件能力与边界
-
-### 当前可用
-
-- 标准 Cordis 工具注册、异步等待及生命周期清理。
-- 复用宿主工具管线和 Job 服务，不自行启动进程或实现独立 HTTP 执行服务。
-- bundle patch 加载派生注册器，从已声明 ptc 读取组合快照并注册可选预设，由宿主既有 Agent 预设界面消费元数据，不需要自定义前端。readDocument 在宿主注释中用于查看声明，本插件只读取其序列化数据再注册独立预设，并不认领源预设的运行实例或私有基准地址。
-- 同预设范围内共享有界总线，但查询/取消按宿主 Agent 的会话身份分隔。
-- PTC 预算到期后的分离等待（0.9.0）：程序结束只停止等待，已受理执行与宿主 Job 继续，同会话可用同一 requestId 取回结果；其他中断原因仍取消。该识别依赖 rc.2 固定中断原因，未知原因保守按取消处理。
-
-旧版只读 guard 在 0.3.0 移除，预设保留源 ptc 的工具与权限，不再削减普通写入/命令能力，也不自动启用源组合禁用行。它不是进程或权限沙箱，不隔离进程资源消耗。宿主 cwd 只是路径解析基准，不是文件访问围栏。
-
-派生使用 readDocument 序列化声明及宿主 YAML 方言，不访问注册表私有字段，不求值 !!js。它是加载时快照；没有公开的源声明 baseUrl，因此拒绝相对模块或 include 文件，避免错误重定位。完整自定义预设等价性不可仅由模块行保留推断，外部依赖和宿主注入仍需原实例验证。
-
-### 当前不提供
-
-- 接管所有现有工具或更改默认 Agent 预设。
-- 持久化受理、跨重启恢复或重新认领原工具调用。
-- 工具结果已写入会话磁盘日志的持久化回执。
-- 远端执行端、通用工作流或有副作用操作的对账能力。
-- 跨宿主版本稳定的 PTC 中断原因契约；0.9.0 的预算分离等待只按 rc.2 实际使用的固定字符串识别，宿主升级后需复核。
-
-若未来要跨重启接续，需要宿主公开稳定的认领/提交契约；本项目不虚构这样的 API，也不通过聊天消息绕过。
-
-## 故障处理
-
-正常等待使用宿主 Job 窗口续等。等待服务异常后，先排空原执行并保留原服务错误；然后按原 owner 对确切 Job 最多检查 20 次、每次间隔 10 毫秒，尝试清理终态记录。这些是错误恢复检查，不是模型轮询或重跑任务。
-
-宿主 rc.2 没有类型化 Job not-found 错误码。对先行移除的幂等处理仅匹配本调用创建的 Job 的精确错误消息，并确认原 owner 查询中记录已不存在。其他错误不被冒充成功。持续故障时可能遗留记录，不合作 Handler 可能阻碍关闭。
-
-## 哪些是真实验证？
-
-真实组件、真实 AgentLoop 内存会话和真实预设注册表均有隔离测试；模型侧是脚本适配器，部分 Agent 身份是夹具。桌面卡片渲染、实际权限提示/沙箱、磁盘结果提交和真实模型继续推理均未验收。详见[验证范围](<validation.md>)。
+升级宿主后至少重跑 `npm run check` 与真实 ToolRuntime 集成测试。

package/docs/protocol.md

@@ -1,148 +1,40 @@
-# 协议 v1：请求、状态与结果
+# 协议与运行语义（1.0）
 
-本文面向调用者和 core Handler 开发者。消息示例见[使用说明](<../README.md>)，兼容版本见[宿主说明](<host-compatibility.md>)。
+## 工具
 
-## 1. 请求结构
+| 工具 | 输入 | 返回 |
+|---|---|---|
+| `runtime_run` | `{ plan, async? }` | 同步：运行摘要与步骤状态；`async:true`：`{ runId, state:"running" }` |
+| `runtime_status` | `{}` 或 `{ runId }` | 最近运行列表或指定运行元数据（不含结果） |
+| `runtime_result` | `{ runId }` | 运行摘要 + 已保存步骤结果（`truncated/bytes` 标记） |
+| `runtime_cancel` | `{ runId }` | 取消后的运行摘要 |
+| `runtime_resume` | `{ runId }` | 恢复后的运行摘要；仅 `interrupted` 可恢复 |
 
-```json
-{
-  "protocolVersion": 1,
-  "messageId": "message-001",
-  "requestId": "operation-001",
-  "type": "request",
-  "payload": { "handler": "test", "input": { "delayMs": 1000, "fail": false } }
-}
-```
+## 计划（plan）
 
-| 字段 | 规则 |
-|---|---|
-| `protocolVersion` | 必须为数字 1 |
-| `messageId` | 单请求范围内一条消息的编号；相同编号不同内容拒绝 |
-| `requestId` | 同一逻辑执行的稳定编号；同会话内重复输入复用执行，不同输入拒绝冲突 |
-| `type` | `request`、`status`、`result` 或 `cancel` |
-| `payload` | request 必须为 `{handler,input}`；其他三种类型必须为 `{}` |
+`plan = { goal?, concurrency?, steps[] }`；`step = { id, tool, input, depends_on?, retry?, timeout_ms? }`。
 
-两个 ID 都只接受 1–128 位字母、数字、下划线、点、冒号和短横线；不接受其他顶层字段。身份、权限和工作目录不能由消息另行指定。宿主工具上下文中的 Agent、调用 ID 与 token 才是可信关联。
+- 允许工具：`read/glob/grep/edit/write/pwsh`；`retry` 只允许 `read/glob/grep`（0–3）。
+- 约束：1–32 步；计划 ≤64KiB；并发 1–4；单步超时 1s–600s；`id` 唯一、依赖必须存在、禁止环。
+- 步骤输入原样交给宿主工具管线，按工具自身 schema 与权限执行。
 
-请求最大 16 KiB。输入和结果采用严格 JSON：深度最多 64，访问节点最多 65536；拒绝非有限数字、负零、undefined、函数、符号、稀疏数组、访问器、特殊对象和循环引用。普通对象接受当前运行域 Object.prototype 或 null 原型；数组只接受当前运行域 Array.prototype。跨运行域值须先转换为受支持的纯数据，不能假定任意 JavaScript 对象都可传入。
+## 状态
 
-### 去重与消息额度
+- 运行：`running | succeeded | failed | cancelled | interrupted`。
+- 步骤：`pending | running | succeeded | failed | cancelled | unknown`。
+- `interrupted` 表示进程重启/退出时运行未完成；启动时把 `running` 步骤改为 `unknown`。
 
-- 逻辑键是 **当前存活总线实例 + 宿主会话身份 + requestId**。不同会话不能查询/取消彼此记录；同一预设修订（generation）的会话共享总线容量。
-- 对参数规范排序后的摘要仅用于同 requestId 的冲突比较，不用于永久按参数去重。相同参数的新 requestId 默认仍是新操作；仅显式声明 `dedupe:"payload"` 的幂等 Handler 可复用同会话已成功的 payload 结果（0.12.1 起内置 host.* 不声明）。
-- 普通消息最多记账 128 条，含首次请求、重复请求及查询。满后拒绝普通新消息；首次尚未确认的有效取消可使用一个额外控制槽，最多 129 条。已记账消息的冲突检查不因控制槽而放松。
-- 活跃观察者附着最多 32 个；每个附着独立占名额，即使共用回调。附着被拒绝时不占用新消息编号/额度。
-- 终态超期清理后旧请求键失效，不应把此机制用于长期避免外部副作用重复。
+## 持久化与恢复
 
-## 2. 工具返回和 core 事件
+- 记录路径：`DSH_HOME/tmp/xiaohe-runtime/runs/<runId>.json`（`XIAOHE_RUNTIME_DIR` 可覆盖）；原子写，损坏记录忽略，默认保留最近 100 条。
+- 恢复只针对 `interrupted`：只读步骤重新排队；副作用在途步骤标 `failed/RUNTIME_INTERRUPTED`。**不保证 exactly-once**。
+- 运行记录按会话隔离：status/result/cancel/resume 只允许所有者会话。
+- 单步结果 >64KiB 只保存截断标记，避免无界内存/磁盘。
 
-**工具 request 不提前返回 accepted 或仅 taskId。** 它异步等待后返回执行快照；校验、容量、宿主服务等也可能令外层工具调用返回错误，而非执行快照。
+## 错误码（运行时）
 
-快照字段：`requestId`、`state`、`sequence`、`cancelRequested`、`delivery`，以及可选 `result`、`error`、`progress`；0.11.0 起，附着到已有执行的返回快照可带可选 `reused:true`。`status`、`result`、`cancel` 均返回当前快照；`result` 在运行中也只返回当前状态，不额外等待。
+`INVALID_PLAN`、`PLAN_TOO_LARGE`、`PLAN_DUPLICATE_ID`、`PLAN_UNKNOWN_DEP`、`PLAN_CYCLE`、`PLAN_UNKNOWN_TOOL`、`PLAN_RETRY_DENIED`、`RUNTIME_NOT_FOUND`、`RUNTIME_INVALID_STATE`、`RUNTIME_STEP_TIMEOUT`、`RUNTIME_CANCELLED`、`RUNTIME_INTERRUPTED`、`RUNTIME_STEP_FAILED`、`RUNTIME_BUSY`、`OWNING_SESSION_REQUIRED`、`CLOSED`。预设派生错误沿用 `PTC_PRESET_*`。
 
-core 的 `submit()` 返回 `accepted`、`done` Promise、只读 `snapshot()` 及取消/解除通知/返回标记句柄。accepted 只是内存受理或已有记录的快照，`durable:false`，不代表执行成功；终态重取也不代表重新执行。0.9.0 的 `snapshot()` 只供停止等待时读取当前视图，不改变交付标记。
-
-通知包含版本、消息 ID、请求 ID、关联 ID（correlationId）、请求内序号、类型与 payload。accepted 的 correlationId 对应本次提交消息，序号是当前快照；后续事件关联首次请求 messageId，新增序号。类型包括 started、progress、cancel_requested 和 succeeded、failed、cancelled、unknown 四种终态事件。
-
-Handler 报告的进度序号必须递增；重复、乱序及终态后进度忽略，百分比须在 0–100 内。事件及 payload 在通知前冻结。每个附着独立解除通知，detach 不取消执行；取消是另一个操作。派发开始时固定本批名单，派发期间新增监听从下个事件开始接收；已解除且尚未轮到的回调跳过。回调中触发的嵌套事件按序排在当前批之后，不跨越当前通知。观察者抛错或异步拒绝被隔离，不记录异常原文，也不等待观察者资源完成。
-
-## 3. 执行状态和交付标记
-
-```text
-queued → running → succeeded / failed / cancelled / unknown
-   └────────────→ cancelled
-```
-
-终态不可再改成另一终态：
-
-| 状态 | 含义 |
-|---|---|
-| queued | 内存已受理，尚未开始 |
-| running | 正在执行 |
-| succeeded | Handler 正常返回，结果可验证、保存 |
-| failed | 未在取消中的 Handler 执行异常 |
-| cancelled | 排队时取消，或运行 Handler 用 AbortError 确认取消 |
-| unknown | 取消后异常未确认，或执行结果不能可靠保存 |
-
-`cancelRequested` 只表示发出了 AbortSignal，不代表停止或回滚。取消后正常返回且结果可保存，成功可获胜；取消后其他异常保守记为 unknown。取消某个正在等待的重复调用，会请求取消整个逻辑执行，不是仅退出该等待者。
-
-执行完成与结果交付分开。`pending`/`returned` 只是插件返回路径的标记；done 快照保留当时值，后续查询可看到更新。**returned 不证明宿主磁盘提交或模型已消费**。外层取消/后置策略仍可能改变返回值。
-
-### 外层调用结束与时间预算（0.9.0）
-
-PTC 程序结束（含 `run_code` 时间预算到期）时，宿主以固定原因中断其中的工具子调用。总线对**已受理**请求只解除本次等待，不请求取消：执行与宿主 Job 继续，同一会话可用同一 requestId 的 `status`/`result` 取回（受记录保留期限制），或发送 `cancel`。用户/会话主动中断、沙箱模式变化等其他原因仍请求取消整个执行。
-
-这条区分依据 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. 容量、保存与关闭
-
-| 默认配置 | 值 |
-|---|---|
-| 并发执行 | 2 |
-| 待分发队列 | 32 |
-| 任务记录 | 256 |
-| 单结果 JSON | 64 KiB |
-| 终态保留期 | 自完成起 1 小时 |
-
-新执行请求受队列和记录容量限制；运行中重复附着受消息/监听名额限制；未过期终态复用不申请新 Job。宿主新 Job 准入还有独立容量要求。已受理的排队任务按会话轮转，各会话内部 FIFO；不抢占运行任务，没有完成时间 SLA，core 未启用会话配额时单会话可占满队列；宿主插件启用每会话16项，但终态记录与多会话总量仍可占满容量，不保证其他会话一定获得入队名额。
-
-core 不传配置时用默认值；显式配置必须完整包含 concurrency、queueLimit、recordLimit、resultBytes、retentionMs 五项正安全整数。拒绝缺项、额外字段与访问器；构造时复制冻结，无动态更新接口。
-
-保留期通过新请求或控制消息触发惰性清理，也可调用实例 `sweep()`；不是精确的一小时定时删除，闲置时记录可能继续占内存，但后续正常查询会先清理过期记录。无磁盘任务库。结果大小检查在 Handler 返回后进行，Handler 自身也必须限制内存分配。敏感返回内容仍可能进入宿主会话日志，本插件不是秘密识别器。
-
-关闭幂等且可重入，多次 close 返回同一 Promise。core 先停止受理，取消队列和运行任务，排空后清理内存；宿主执行所有者继续等原工具交付路径及 Job 关联结束，再释放。等待某个 Handler 的通知回调里不应反向 await 整个关闭完成。正常路径复用 Job 窗口等待；服务异常后仍先排空执行，再有界检查记录并保留原服务错误。持续故障可能留记录到宿主生命周期清理，不合作 Handler 可能阻碍关闭。
-
-## 5. 重试与恢复语义
-
-当前没有网络传输层，自动通信重试与执行重试均为 0。正常 Job 的 60 秒窗口只由程序续等，不自动改为失败；异常清理有界检查也不是模型轮询或执行重试。
-
-同存活实例、保存期内的请求复用不是端到端 exactly-once；每个实际工具调用仍有自己的宿主结果记录。没有外部终态注入接口，也没有跨重启恢复：任一阶段进程崩溃都会丢失插件内存状态。宿主日志不能复活旧 Promise，不追加聊天消息冒充原调用恢复。
-
-## 6. 准入与会话状态（0.5.0）
-
-原五项 core options 不变。第二构造参数 AdmissionPolicy 可含 sessionQueueLimit、maxQueueWaitMs，均为 1..2147483647 安全整数，省略表示不启用该约束。策略复制冻结，未知键和访问器拒绝。宿主插件启用每会话排队 16、排队 120000ms，普通请求不可覆盖策略。
-
-相同 requestId 的复用先于新准入检查，不重复占槽或重置原期限。每会话超额返回 SESSION_BACKPRESSURE，不受理、不占 requestId；全局/记录容量仍优先返回 BACKPRESSURE。两者只限制准入，不保留所有会话的专用槽。终态记录仍可占满 recordLimit。
-
-期限使用单调时钟，计时器及出队前均检查，超期只将 queued 结算 failed / QUEUE_WAIT_TIMEOUT，不调用 Handler、不设置 cancelRequested、不重试，沿原 done/Job 返回。开始运行、取消或关闭时清除计时器。事件循环繁忙会令通知晚于期限，但不会让超期任务出队执行。已运行任务继续遵守原执行/取消规则。
-
-execution_bus_state 工具仅接受 {}，从宿主 Agent 取 sessionId，拒绝匿名或自报身份，关闭后拒绝查询。它读取 core inspect 的不可变快照，不创建 Job、不改变消息额度；查询会做正常终态 TTL 清理。不包含输入/输出，不访问其他会话。最多 50 条、活跃优先，其后按受理次序倒序列出终态；总数未截断，truncated 提示列表截断。元数据含 requestId、state、delivery、cancelRequested、固定 error/progress、waitReason（concurrency/bulkhead/resource/dispatch）、longRunning（运行超过 30 秒）、queueMs/runMs/remainingQueueMs。phase terminal 只表示执行终态且尚未标记返回，不代表可推断宿主 Job 清理进度。
-
-core inspect(trustedOwner) 要求非空 sessionId，但不提供鉴权，可信身份和访问控制属于嵌入宿主。勿把 core 的任意 owner 参数直接暴露给远端。状态不是持久审计/模型消费回执，不应循环调用。
-
-## 7. 诊断
-
-core 实例的 `diagnostics()` 返回只读用途的独立快照：阶段计数、最近 128 条 `{operation,stage,elapsedMs}` 轨迹、关闭阶段、队列/运行/记录数及保留结果字节数。operation 是实例内递增数值，不是消息或会话 ID；elapsedMs 以单调时钟计算，阶段时间均相对受理时间，可相减得到排队/执行/返回延迟。复用计数仅在附着受理成功时增加；返回阶段按逻辑结果首次标记，不代表每个工具调用都持久化。
-
-宿主执行所有者另有内部 Job 创建/释放/异常聚合轨迹，不作为模型工具或公开服务导出；其 operation 是独立编号，不能与 core 轨迹按编号关联。数据只在内存，不保存参数、结果、Handler 名称、请求/会话 ID、异常文本或聊天记录。总计数会持续累积，128 槽环形轨迹有界且按时间顺序导出；结果字节只在保存/过期/关闭时更新，查询不读取结果内容或重复序列化。异常计数不等于每次清理最终失败。
-
-## 8. 扩展 Handler
-
-包的 `./core` 导出 ExecutionBus、Handler、Capability 类型。Handler 只接收输入、requestId、signal、progress 和可选最小 capability，不接收聊天历史。register 返回绑定唯一注册令牌的幂等注销函数，不会误删后来同名注册；已受理请求继续持有原 Handler。
-
-0.10.0 起，模型可见的工具体声明把 `payload` 改为按 Handler 的判别联合（每个 `host.*`/test 的 `input` 字段与必填项）；这是提示与 SDK 类型层的变化，wire 结构、校验、错误码与保存语义不变。
-
-0.11.0 起，模型可传简化输入：请求 `{requestId, handler, input, messageId?}`、控制 `{requestId, type, messageId?}`；插件在进入总线前补齐完整 v1 消息，完整 v1 消息仍被接受。返回快照在附着已有执行时追加可选 `reused:true`，只表示复用了逻辑执行，不代表外部副作用对账。
-
-0.12.0 扩展 Handler 可选声明：`queue`（调度类别，内置 fs/diagnostic/command）、`maxConcurrency`（同一 Handler 舱壁）、`resources(input)`（资源键串行）、`dedupe:"payload"`（幂等 Handler 的唯一任务复用）。调度和资源锁按总线实例生效；插件实例由同一预设修订（generation）的会话共享，跨进程/跨代际不保证。资源键是调用方提供的字符串，不是 OS 文件锁。唯一任务只复用 succeeded 终态，失败/取消/unknown 不缓存；命中时返回快照带 `reused:true`，且不会再次执行 Handler。
-
-0.12.1 起内置 host.read/host.glob/host.grep **不再声明** `dedupe:"payload"`：文件、权限或工作目录变化后缓存结果可能过期，扩展 Handler 如声明该能力需自行承担失效责任。同时 `waitReason` 区分 `bulkhead`（Handler 舱壁）与 `resource`（资源锁）。
-
-内置 test、host.read、host.glob 与 host.grep 没有副作用；host.edit、host.write 与 host.pwsh 是非幂等写/命令 Handler，通过 `Handler.idempotent=false` 显式声明，其终态结果复用被 `MUTATING_REUSE_DENIED` 拒绝，运行中的重复附着仍只等待同一执行。0.8.0 新增宿主工具输入错误码 INVALID_GLOB_INPUT、INVALID_GREP_INPUT 与 INVALID_PWSH_INPUT；协议既有错误码不改名。host.pwsh 的后台结果只是宿主 Job ID，不是完成回执。当前没有 ctx.executionBus 服务、远端传输、跨插件动态注册或外部副作用对账契约。扩展有副作用 Handler 前必须显式声明幂等并另行设计授权与崩溃对账，不能仅依赖本版请求键。
-
-
-## 9. 错误词汇（0.12.1 补录）
-
-错误码值即协议 v1 稳定词汇，不得重命名；完整定义见 `src/error-codes.ts`。
-
-- 协议解析：`INVALID_OBJECT`、`UNKNOWN_FIELD`、`UNSUPPORTED_VERSION`、`INVALID_ID`、`UNSUPPORTED_TYPE`、`MESSAGE_TOO_LARGE`。
-- 严格 JSON：`JSON_LIMIT`、`INVALID_JSON`、`CYCLIC_JSON`、`INVALID_JSON_ARRAY`、`INVALID_JSON_OBJECT`、`INVALID_JSON_KEY`、`INVALID_JSON_PROPERTY`。
-- 总线调度与准入：`CLOSED`、`EXPECTED_REQUEST`、`INVALID_REQUEST`、`REQUEST_CONFLICT`、`MESSAGE_CONFLICT`、`MESSAGE_LIMIT`、`UNKNOWN_HANDLER`、`BACKPRESSURE`、`SESSION_BACKPRESSURE`、`WAITER_LIMIT`、`EXPECTED_CONTROL`、`INVALID_CONTROL`、`NOT_FOUND`、`UNTRUSTED_CONTEXT`、`OWNING_SESSION_REQUIRED`、`QUEUE_WAIT_TIMEOUT`、`RESULT_NOT_RETAINED`、`CANCELLED`、`CANCELLATION_UNCONFIRMED`、`HANDLER_FAILED`、`INVALID_ADMISSION_POLICY`、`INVALID_OPTIONS`、`DUPLICATE_HANDLER`、`MUTATING_REUSE_DENIED`、`INVALID_HANDLER_OPTIONS`、`INVALID_RESOURCES`。
-- 宿主投影：`DUPLICATE_EXECUTION_HANDLE`、`INVALID_STATE_QUERY`、`HOST_READ_FAILED`、`HOST_TOOL_FAILED`、`HOST_JOB_UNAVAILABLE`。
-- 预设派生：`PTC_PRESET_TOO_LARGE`、`PTC_PRESET_ALREADY_CONTAINS_BUS`、`PTC_PRESET_RELATIVE_BASE_UNSUPPORTED`、`PTC_PRESET_UNAVAILABLE`。
-- 内置 Handler：`INVALID_TEST_INPUT`、`INVALID_READ_INPUT`、`INVALID_EDIT_INPUT`、`INVALID_WRITE_INPUT`、`INVALID_GLOB_INPUT`、`INVALID_GREP_INPUT`、`INVALID_PWSH_INPUT`、`READ_LIMIT`、`CONTROLLED_FAILURE`、`HOST_CAPABILITY_REQUIRED`。
+## 兼容性
 
+1.0 移除了 0.x 的 `execution_bus` 工具、完整 v1 消息信封、`./core` 导出与旧预设 ID；工具与导出变更属于主版本破坏。0.12.1 是最后一个总线版本。

package/docs/releases/1.0.0.md

@@ -0,0 +1,33 @@
+# 萧何 / Xiao He 1.0.0
+
+## 从执行总线切换为声明式运行时
+
+本版把项目从 0.x 的“执行总线模式”整体改造为**声明式运行时**：模型提交 DAG 计划，运行时负责并行、只读重试、超时、落盘、取消与重启后恢复。
+
+## 破坏性变更
+
+- 移除 `execution_bus` / `execution_bus_state` 工具、完整 v1 消息信封与 `./core` 导出。
+- 预设 ID 从 `execution-bus-test` 改为 `xiao-he-runtime`；bundle patch 行随之调整。
+- 工具面改为 `runtime_run` / `runtime_status` / `runtime_result` / `runtime_cancel` / `runtime_resume`。
+- 0.12.1 是最后一个总线版本，保留在 npm/git 历史与标签中，不再维护。
+
+## 新能力
+
+- 计划：DAG（`depends_on`）、并发 1–4、只读 `retry`、单步超时、32 步/64KiB 上限、严格 schema 校验。
+- 执行：独立步骤并行、依赖顺序、结果落盘、单步结果 >64KiB 截断。
+- 生命周期：`async`、status/result/cancel/resume；启动时把残留 `running` 标记为 `interrupted`。
+- 隔离：运行记录按会话隔离；工具经宿主管线并沿用父调用权限。
+
+## 明确不做
+
+- 不保证 exactly-once：崩溃时在途副作用可能已发生，只能标记 `unknown/failed`。
+- 不做跨进程/分布式执行、不做跨重启的在途副作用恢复。
+- 不替代后台 Job / Teams / Skills / Goals。
+
+## 升级说明
+
+需要 DSH 0.2.1-rc.2。旧总线用户请保留 0.12.1 或迁移到 `runtime_run` 计划；本版不自动安装/重启 DSH，也不迁移旧运行记录（旧记录不读取）。
+
+## 验证与限制
+
+本地全量 **27** 项测试通过（见 `npm run check` 输出）；真实模型、桌面 UI 与实际沙箱未完整验收；崩溃恢复仅验证逻辑与标记，未做真实进程 kill 端到端验收。

package/docs/validation.md

@@ -1,72 +1,33 @@
 # 验证范围与使用限制
 
-本文说明当前版本的证据边界，不是生产环境认证。当前能力基线为 **v0.12.1**，在 0.5.0 的会话准入/排队、0.7.0 的宿主工具转发、0.8.0 的搜索/命令 Handler、0.9.0 的预算分离等待与 0.10.0 的采用面改造上，收紧为收益导向触发并加入简化调用、复用标记与本地采用率统计；0.11.1 补充跨步骤取回姿势，0.11.3 补记指引级 A/B 证据，0.12.0 加入调度类别/舱壁/资源互斥/唯一任务与属性测试，0.12.1 关闭内置 host.* 的 payload 去重并修正老化/字节计数/等待原因/注册校验/关闭重入问题；预设沿用 v0.3.0 的宿主 PTC 声明派生方式。验证环境为 Windows、Node.js 24.21.0，宿主组件锁定 DSH 0.2.1-rc.2、Cordis 4.0.4。
+本文说明当前版本的证据边界，不是生产环境认证。当前能力基线为 **v1.0.0**，验证环境为 Windows、Node.js 24、DSH 0.2.1-rc.2、Cordis 4.0.4。
 
-## 已验证什么？
+## 已验证
 
 | 层次 | 检查内容 | 能说明什么 |
 |---|---|---|
-| 总线核心 | 参数、队列、并发、重复请求、冲突、取消竞争、结果保存、TTL、监听与注销 | 程序内部约束及已覆盖异常路径可重复检查 |
-| 真实宿主组件 | Cordis、ToolRuntime、LocalJobs、LocalFS、文件工具；host.glob/host.grep/host.pwsh 的转发测试使用宿主工具桩 | 请求经过真实工具管线；权限拒绝、Job 进度、共享任务、参数校验、幂等分流与清理逻辑有效；Agent 身份与工具实现为夹具，桩不证明真实搜索/命令工具实现 |
-| 真实会话循环 | AgentLoop、AgentRegistry、SessionStore；脚本模型适配器 | 内存会话中原工具结果只提交一次，完成后再进入下一次适配器调用 |
-| PTC 预算分离等待 | 真实 Node PTC `run_code` 以 8 秒预算等待 12 秒总线执行：预算到期后执行继续、宿主 Job 保留、同 requestId 取回结果；外部中断仍取消执行 | 在 DSH 0.2.1-rc.2 实际中断原因下成立；固定字符串不是跨版本契约 |
-| 简化调用与复用标记 | 简化请求/控制、完整 v1 消息兼容、终态与运行中复用返回 `reused:true`、非法形状拒绝 | 组件级测试确认；不改变 wire 语义与副作用边界 |
-| 采用策略 A/B（指引级） | 同一版本 0.11.2、同一模型、5 类任务各 5 个全新子会话：可选触发 vs 总线优先指引，统计总线调用/复用/耗时 | 指出可选触发更优（总线优先把一次性长命令也包装、并有约 19s 排队延迟）；非预设级、并发单机小样本，非统计显著 |
-| 调度隔离与资源互斥 | Handler queue/maxConcurrency/resources、类别优先级 + 等待老化（不封顶）、资源等待期限、waitReason（含 bulkhead）/longRunning、唯一任务只复用 succeeded | 组件级回归确认；按预设修订共享总线实例，跨进程/跨代际不保证，不是 OS 锁 |
-| 0.12.1 热修 | 内置 host.* 关闭 payload 去重、老化不封顶、唯一复用字节/时间戳、注册选项快照校验、validate/resources 内 close 重入、消息身份改摘要 | 组件级回归确认；不改变 wire 协议与工具调用形状 |
-| 属性测试 | fast-check 随机提交/重放与容量压力不变量（固定种子） | 开发依赖（MIT）；随机覆盖不是穷尽验证，种子固定保证可复现 |
-| 预设隔离 | AgentPresetRegistry 与 Loader | 派生预设可激活；源 ptc 声明不变、普通 Agent 不可见总线；原 write/edit/Job 工具保留，宿主前置策略拒绝仍有效 |
-| 故障注入 | 克隆失败、观察者拒绝、Job 等待/清理异常、先行移除与卸载交错 | 指定故障下的回归约束；不证明所有故障组合都已覆盖 |
-| 候选包 | 严格文件白名单、临时目录生产依赖安装、入口注册 | 包可安装和加载；安装验证使用简化宿主夹具，不是桌面插件管理器验收 |
+| 计划 schema | DAG、依赖、环、工具白名单、retry 限制、大小/超时/并发上限、未知字段 | 非法计划在进入执行前被拒绝 |
+| 执行器 | 独立步骤并行、依赖顺序、只读重试、超时、失败阻止依赖、取消、结果截断 | 组件级 DAG 语义可重复检查 |
+| 持久化 | 原子写、损坏记录忽略、列表/prune、启动 `running→interrupted`、恢复语义 | 文件记录与重启标记逻辑成立 |
+| 真实宿主组件 | Cordis ToolRuntime + 真实 `ctx.tools.execute` 链路（read/pwsh 桩） | 工具经真实管线执行；Agent/工具实现为夹具 |
+| 预设与模式 | 派生预设注册、默认预设不变、普通 Agent 不可见运行时、宿主策略拒绝仍有效 | 隔离与权限边界成立 |
+| 发布门禁 | 全量测试、包白名单、四矩阵 CI、npm 后逐字节校验 | 发布制品一致性 |
 
-2026-10-18 采用率 pilot（0.10.0，4 个全新队友会话）：符合条件的长命令/跨预算任务 **2/3** 真实调用了总线；1 个一次性 40 秒命令属于无收益包装，1 个跨步骤任务改用宿主后台 Job。
+本地全量 **27** 项测试通过（以 `npm run check` 实际输出为准）。
 
-2026-10-18 指引级 A/B（0.11.2，两臂各 5 个新子会话）：A 臂可选触发 11 次总线、B 臂总线优先 18 次；B 臂把一次性 40 秒命令也吸入总线，跨预算场景出现约 19s 排队延迟（106.3s vs 71s）。结论：收益导向可选触发是更好的默认，bus-first 不发布为正式第二预设。样本小、并发单机、非预设级，不替代统计意义上的效果对照。
+## 未验证或明确不支持
 
-此前 v0.3.0 本地回归为 **51/51 通过**；本轮新增生命周期与多会话压力回归，最新数量以命令输出为准。测试项数量是用例数量，不是全部产品验收条数。当前结果请重新运行下述命令；文档测试数不应代替实际输出。
-
-```powershell
-npm ci --include=dev --ignore-scripts
-npm run check
-npm run verify:package
-npm run test:install
-```
-
-## 已发布不等于已在日常环境验收
-
-项目已经正式发布到 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：
-
-```text
-eb95b4e51675f5f1821275e0812ef4dd4984b1aba45a52fbc6bab3518bbf6f38
-```
-
-这只证明那个冻结版本的制品事实，不代表任何后续版本已发布，也不代表此刻 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 四矩阵及制品一致性门禁。
-
-## 未验证或不支持
-
-| 项目 | 当前结论 |
+| 项目 | 结论 |
 |---|---|
-| 当前桌面真实模型发起请求并继续推理 | 未验收；脚本适配器不是实际模型 |
-| 当前桌面预设卡片、进度界面、授权提示和实际沙箱 | 未验收；组件事件和 LocalFS 测试不等于桌面 UI/沙箱 |
-| 实际模型/桌面 PTC 与时间预算、沙箱行为 | 真实 Node PTC 隔离子进程已调用原 read 和总线；使用显式 danger-full-access 测试策略与测试 Agent，不是桌面沙箱/真实模型验收 |
-| 从真实 tgz 经宿主插件管理器加载预设、卸载与回滚 | 未完成完整桌面流程；源码工作区的 Loader 测试不能替代 |
-| 真实 glob/grep/pwsh 工具实现 | 未在测试环境启用：真实搜索工具依赖打包 ripgrep 与 subprocess 服务，真实 pwsh 依赖 shell/sandbox/审批组合；本版只验证按 handler 名转发、输入校验、幂等分流与失败固定码 |
-| 跨版本 PTC 中断原因 | 分离等待只识别 DSH 0.2.1-rc.2 实际使用的固定中断原因字符串；宿主升级后未知原因保守按取消处理，需复核 |
-| 跨会话/跨进程资源互斥 | 同一预设修订（generation）的会话共享总线实例，资源锁/舱壁/容量跨会话生效；不提供 OS 级文件锁，跨进程、跨代际不保证；同一文件的相对/绝对、大小写等别名写法可能绕过文件互斥 |
-| 模式采用率与效果 | 已完成指引级 A/B（可选触发 vs 总线优先），但非预设级、并发单机小样本，不具统计显著性；轮次/耗时/成功率的大样本对照仍未完成，不能由 schema 或单元测试推断 |
-| 磁盘会话结果提交及重启恢复原调用 | 未验收磁盘提交；本插件不支持跨重启恢复 |
-| 减少真实模型轮次、状态查询或总耗时的对照 | 未验证，不给提升比例 |
-| 长期运行、所有卸载/服务故障组合 | 未穷尽；持续故障仍有清理限制 |
-
-## 需要知道的运行约束
-
-1. 受理、队列、结果及交付标记均在内存。进程关闭会丢失，宿主会话日志不等于插件恢复执行权。
-2. 同一预设修订（generation）的会话共享总线容量，已受理任务会话轮转、会话内 FIFO；结果访问按会话隔离，不是独立进程或资源安全隔离，也不保证入队名额公平。重载/升级会创建新的预设修订，旧实例状态、容量与资源锁不延续。
-3. 取消任一正在等待的重复调用会请求取消整个逻辑执行，不是仅停止该等待者。
-4. 已终态且未过期的请求可直接复用结果，不申请新 Job；仍须通过身份、冲突及消息额度检查。
-5. 等待服务异常后先排空原执行，再有界检查宿主记录；服务持续不可用时记录可能留到所属生命周期清理。不合作 Handler 仍可能阻碍关闭。
-6. `returned` 不是宿主持久化或模型消费确认；外层取消和后置策略仍可能改变最终工具结果。
-
-开发者可阅读[流程测试说明](<FLOW-TEST.md>)、[协议](<protocol.md>)和[宿主兼容性](<host-compatibility.md>)。
+| 真实模型/桌面 UI/实际沙箱 | 未验收；组件测试与桩不等于桌面/模型验收 |
+| 真实进程崩溃 + 重启恢复 | 只验证了记录标记与恢复逻辑，未做 kill 进程后的端到端恢复验收 |
+| exactly-once 副作用 | 不支持；崩溃时在途副作用可能已发生，只能标记 unknown/failed |
+| 跨进程/分布式执行 | 不支持；运行时随宿主进程退出 |
+| 大结果/长计划 | 单步结果 >64KiB 截断；计划 ≤64KiB、32 步 |
+| 宿主版本漂移 | 依赖 DSH 0.2.1-rc.2 的 ToolRuntime/preset 契约；升级需复核 |
+
+## 使用约束
+
+1. 运行记录在本地内存/磁盘；进程退出后仅保留已落盘状态，不恢复在途副作用。
+2. 计划质量由模型决定；稳定流程适合，探索型任务用原工具。
+3. 取消是合作式的：副作用步骤可能停在 unknown；不要假设取消等于回滚。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feng0531/dsh-execution-bus",
-  "version": "0.12.1",
+  "version": "1.0.0",
   "type": "module",
   "private": false,
   "license": "SEE LICENSE IN LICENSE",
@@ -12,11 +12,10 @@
     "type": "git",
     "url": "git+https://github.com/f-e-n-g-0531/dsh-execution-bus.git"
   },
-  "description": "萧何 / Xiao He: execution bus, bounded DSH handler dispatch with original-call waiting",
+  "description": "萧何 / Xiao He: declarative runtime for DSH agent tool plans (DAG execution, retries, persistence, recovery)",
   "main": "dist/plugin.js",
   "exports": {
     ".": "./dist/plugin.js",
-    "./core": "./dist/bus.js",
     "./mode": "./dist/mode.js",
     "./test-mode": "./dist/mode.js",
     "./preset": "./dist/preset.js"
@@ -38,11 +37,11 @@
     "node": ">=22"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "node scripts/clean-dist.mjs && tsc",
     "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",
+    "test:flow": "npm run build && node --test test/runtime-tools.test.mjs test/runtime-executor.test.mjs",
     "prepack": "npm run check && npm run verify:package",
     "verify:package": "node scripts/verify-package.mjs",
     "test:install": "node scripts/test-install.mjs",
@@ -54,7 +53,6 @@
     "@deepseek-ai/cordis": "~4.0.4",
     "@deepseek-ai/cordis-plugin-include": "~1.0.9",
     "@deepseek-ai/dsh-agent-preset-registry": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-jobs": "0.2.1-rc.2",
     "@deepseek-ai/dsh-scope": "0.2.1-rc.2",
     "@deepseek-ai/dsh-system-prompt": "0.2.1-rc.2",
     "@deepseek-ai/dsh-tools": "0.2.1-rc.2"