@feng0531/dsh-execution-bus 0.5.0 → 0.6.0

package/dist/plugin.js

@@ -1,14 +1,13 @@
 import { randomUUID } from "node:crypto";
+import { ADMISSION_DEFAULTS, REQUEST_DESCRIPTION, REQUEST_PARAMETERS, STATE_PARAMETERS, } from "./product.js";
 import { ExecutionOwner } from "./execution.js";
 import { ExecutionBus, parse } from "./bus.js";
+import { ERRORS } from "./error-codes.js";
 import { testHandler, readHandler } from "./handlers.js";
 export const name = "execution-bus";
 export const inject = ["tools", "jobs"];
 export function apply(ctx) {
-    const bus = new ExecutionBus(undefined, {
-        sessionQueueLimit: 16,
-        maxQueueWaitMs: 120000,
-    });
+    const bus = new ExecutionBus(undefined, ADMISSION_DEFAULTS);
     bus.register("test", testHandler);
     bus.register("host.read", readHandler);
     const executions = new ExecutionOwner();
@@ -16,21 +15,21 @@ export function apply(ctx) {
     ctx.tools.register({
         name: "execution_bus_state",
         description: "Read a bounded metadata-only snapshot of this agent session’s bus tasks. No inputs/results, no cross-session access. Do not poll during an awaited request.",
-        parameters: { type: "object", properties: {}, additionalProperties: false },
+        parameters: STATE_PARAMETERS,
         output: {
             schema: {},
             render: (_a, v) => [{ type: "text", text: JSON.stringify(v) }],
         },
         async execute(raw, exec) {
             if (executions.phase !== "open")
-                throw Error("CLOSED");
+                throw Error(ERRORS.CLOSED);
             if (!exec.agent)
-                throw Error("OWNING_SESSION_REQUIRED");
+                throw Error(ERRORS.OWNING_SESSION_REQUIRED);
             if (!raw ||
                 typeof raw !== "object" ||
                 Array.isArray(raw) ||
                 Reflect.ownKeys(raw).length)
-                throw Error("INVALID_STATE_QUERY");
+                throw Error(ERRORS.INVALID_STATE_QUERY);
             return bus.inspect({
                 sessionId: String(exec.agent.id),
                 callId: String(exec.callId),
@@ -39,49 +38,33 @@ export function apply(ctx) {
     });
     ctx.tools.register({
         name: "execution_bus",
-        description: "萧何 / Xiao He. Submit a version 1 request and WAIT for its terminal result in this tool call. Reuse requestId only for the same logical operation. Handlers: test {delayMs:0..30000,fail:boolean}, host.read {file_path,offset?,limit?<=100}. Control types status/result/cancel use empty payload. Acceptance is volatile, not execution success. No polling needed; no restart resume.",
-        parameters: {
-            type: "object",
-            additionalProperties: false,
-            required: [
-                "protocolVersion",
-                "messageId",
-                "requestId",
-                "type",
-                "payload",
-            ],
-            properties: {
-                protocolVersion: { type: "integer", const: 1 },
-                messageId: { type: "string" },
-                requestId: { type: "string" },
-                type: {
-                    type: "string",
-                    enum: ["request", "status", "result", "cancel"],
-                },
-                payload: { type: "object" },
-            },
-        },
+        description: REQUEST_DESCRIPTION,
+        parameters: REQUEST_PARAMETERS,
         output: {
             schema: {},
             render: (_a, v) => [{ type: "text", text: JSON.stringify(v) }],
         },
         execute(raw, exec) {
             if (executions.phase !== "open")
-                return Promise.reject(Error("CLOSED"));
+                return Promise.reject(Error(ERRORS.CLOSED));
             return executions.track(dispatch(raw, exec));
         },
     });
     async function dispatch(raw, exec) {
         if (!exec.agent)
-            throw Error("OWNING_SESSION_REQUIRED");
+            throw Error(ERRORS.OWNING_SESSION_REQUIRED);
+        const agent = exec.agent;
         const owner = {
-            sessionId: String(exec.agent.id),
+            sessionId: String(agent.id),
             callId: String(exec.callId),
-        }, m = parse(raw);
+        };
+        const m = parse(raw);
         if (m.type !== "request")
             return bus.command(owner, m);
         let projection;
-        const attached = bus.submit(owner, m, (event) => projection?.progress(event), async (input, signal) => {
+        const attached = bus.submit(owner, m, (event) => projection?.progress(event), 
+        // 宿主 read 能力：出队时重新进入宿主工具管线，沿用宿主权限与工作目录。
+        async (input, signal) => {
             const result = await ctx.tools.execute({
                 name: "read",
                 callId: (String(exec.callId) +
@@ -89,43 +72,62 @@ export function apply(ctx) {
                     randomUUID()),
                 rootCallId: exec.rootCallId,
                 parent: exec.token,
-                agent: exec.agent,
+                agent,
                 arguments: input,
                 signal,
             });
             if (result.isError)
-                throw Error("HOST_READ_FAILED");
+                throw Error(ERRORS.HOST_READ_FAILED);
             return result.value;
         });
-        // Terminal reuse is a read of an existing result, not admission of new work.
-        if (attached.accepted.payload.state !== "queued" &&
-            attached.accepted.payload.state !== "running") {
-            try {
-                const value = await attached.done;
-                attached.returned();
-                return value;
-            }
-            finally {
-                attached.detach();
-            }
+        // 1) 终态复用：已有执行直接读结果，不是新工作受理、不再申请 Job。
+        const terminal = await readTerminal(attached);
+        if (terminal)
+            return terminal;
+        // 2) 新执行：取得或创建宿主 Job 投影。
+        const execution = await projectExecution(owner, m, attached, agent.id, (handle) => (projection = handle));
+        // 3) 挂接取消生命周期，等待投影结算后返回执行快照。
+        return await awaitProjection(exec, attached, execution);
+    }
+    // —— 三个职责单一的拆分函数（闭包内共享 ctx/bus/executions） ——
+    /** accepted 已是终态时直接返回现有结果；否则返回 undefined 走新执行路径。 */
+    async function readTerminal(attached) {
+        const state = attached.accepted.payload.state;
+        if (state === "queued" || state === "running")
+            return undefined;
+        try {
+            const value = await attached.done;
+            attached.returned();
+            return value;
         }
-        const abort = () => attached.cancel();
+        finally {
+            attached.detach();
+        }
+    }
+    /** 命中已存在的共享投影则复用，否则创建投影；创建失败按 HOST_JOB_UNAVAILABLE 结算。 */
+    async function projectExecution(owner, m, attached, ownerId, onProjected) {
         const jobKey = JSON.stringify([owner.sessionId, m.requestId]);
-        let execution = executions.get(jobKey);
-        if (execution)
-            attached.detach(); // only the first attachment projects progress into the shared Job
-        if (!execution) {
-            try {
-                execution = executions.create(jobKey, ctx.jobs, exec.agent.id, attached);
-                projection = execution;
-            }
-            catch {
-                abort();
-                await attached.done;
-                attached.detach();
-                throw Error("HOST_JOB_UNAVAILABLE");
-            }
+        const existing = executions.get(jobKey);
+        if (existing) {
+            // 只让第一个附着把进度投影到共享 Job；后续附着立即解除。
+            attached.detach();
+            return existing;
+        }
+        try {
+            const created = executions.create(jobKey, ctx.jobs, ownerId, attached);
+            onProjected(created);
+            return created;
         }
+        catch {
+            attached.cancel();
+            await attached.done;
+            attached.detach();
+            throw Error(ERRORS.HOST_JOB_UNAVAILABLE);
+        }
+    }
+    /** 把宿主工具调用的取消映射到执行，并等待投影结算后返回快照。 */
+    async function awaitProjection(exec, attached, execution) {
+        const abort = () => attached.cancel();
         exec.signal.addEventListener("abort", abort, { once: true });
         if (exec.signal.aborted)
             abort();

package/dist/preset.d.ts

@@ -1,6 +1,6 @@
 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";
+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. */

package/dist/preset.js

@@ -3,41 +3,44 @@ 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";
+import { PRODUCT } from "./product.js";
+import { ERRORS } from "./error-codes.js";
+export const PRESET_ID = PRODUCT.presetId;
+/** 校验派生源组合：拒绝已含总线，以及缺少公开基准地址的相对模块/include 子文件。 */
+function validateDerivation(rows) {
+    for (const row of rows) {
+        if (row.id === "xiao-he-execution-bus" ||
+            row.name?.startsWith("@feng0531/dsh-execution-bus"))
+            throw Error(ERRORS.PTC_PRESET_ALREADY_CONTAINS_BUS);
+        // readDocument 不发布声明方的 baseUrl，不能把相对模块/include
+        // 静默重定位到 registrar 的不同上下文。
+        if (row.name?.startsWith(".") ||
+            row.name === "@deepseek-ai/cordis-plugin-include")
+            throw Error(ERRORS.PTC_PRESET_RELATIVE_BASE_UNSUPPORTED);
+        if (row.group && Array.isArray(row.config))
+            validateDerivation(row.config);
+    }
+}
 /** 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");
+        throw Error(ERRORS.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);
+    validateDerivation(rows);
     return {
         id: PRESET_ID,
-        name: "萧何 / Xiao He",
+        name: PRODUCT.name,
         order: 20,
         description: "继承宿主 PTC 工具组合，叠加执行请求排队、等待与结果回传。普通任务使用原工具，授权和沙箱由宿主管理；不支持重启恢复。",
         plugins: [
             ...rows,
             {
                 id: "xiao-he-execution-bus",
-                name: "@feng0531/dsh-execution-bus/test-mode",
+                name: PRODUCT.modeEntry,
             },
         ],
     };
@@ -67,7 +70,7 @@ export default class XiaoHePreset {
             }
         }
         if (!document)
-            throw Error("PTC_PRESET_UNAVAILABLE");
+            throw Error(ERRORS.PTC_PRESET_UNAVAILABLE);
         yield await this.ctx.agentPresets.register(derivePreset(document.content));
     }
 }

package/dist/product.d.ts

@@ -0,0 +1,56 @@
+/** Stable product identities and policy. Historical IDs are compatibility contracts, not display names. */
+export declare const PRODUCT: Readonly<{
+    name: "萧何 / Xiao He";
+    packageName: "@feng0531/dsh-execution-bus";
+    presetId: "execution-bus-test";
+    presetRowId: "preset-execution-bus-test";
+    modeEntry: "@feng0531/dsh-execution-bus/mode";
+    modePluginName: "execution-bus-mode";
+}>;
+export declare const CORE_DEFAULTS: Readonly<{
+    concurrency: 2;
+    queueLimit: 32;
+    recordLimit: 256;
+    resultBytes: 65536;
+    retentionMs: 3600000;
+}>;
+export declare const ADMISSION_DEFAULTS: Readonly<{
+    sessionQueueLimit: 16;
+    maxQueueWaitMs: 120000;
+}>;
+export declare const HANDLER_LIMITS: Readonly<{
+    readLines: 100;
+    readPathChars: 2048;
+    diagnosticDelayMs: 30000;
+}>;
+export declare const REQUEST_PARAMETERS: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["protocolVersion", "messageId", "requestId", "type", "payload"];
+    readonly properties: {
+        readonly protocolVersion: {
+            readonly type: "integer";
+            readonly const: 1;
+        };
+        readonly messageId: {
+            readonly type: "string";
+        };
+        readonly requestId: {
+            readonly type: "string";
+        };
+        readonly type: {
+            readonly type: "string";
+            readonly enum: readonly ["request", "status", "result", "cancel"];
+        };
+        readonly payload: {
+            readonly type: "object";
+        };
+    };
+};
+export declare const STATE_PARAMETERS: {
+    readonly type: "object";
+    readonly properties: {};
+    readonly additionalProperties: false;
+};
+export declare const REQUEST_DESCRIPTION = "\u8427\u4F55 / Xiao He. Submit a version 1 request and WAIT for its terminal result in this tool call. Reuse requestId only for the same logical operation. Business handler: host.read {file_path,offset?,limit?<=100}. Diagnostic handler only: test {delayMs:0..30000,fail:boolean}; never use it to perform real work. Control status/result/cancel use empty payload. Acceptance is volatile, not success. No polling or restart resume.";
+export declare const MODE_INSTRUCTIONS: string;

package/dist/product.js

@@ -0,0 +1,48 @@
+/** Stable product identities and policy. Historical IDs are compatibility contracts, not display names. */
+export const PRODUCT = Object.freeze({
+    name: "萧何 / Xiao He",
+    packageName: "@feng0531/dsh-execution-bus",
+    presetId: "execution-bus-test",
+    presetRowId: "preset-execution-bus-test",
+    modeEntry: "@feng0531/dsh-execution-bus/mode",
+    modePluginName: "execution-bus-mode",
+});
+export const CORE_DEFAULTS = Object.freeze({
+    concurrency: 2,
+    queueLimit: 32,
+    recordLimit: 256,
+    resultBytes: 65536,
+    retentionMs: 3600000,
+});
+export const ADMISSION_DEFAULTS = Object.freeze({
+    sessionQueueLimit: 16,
+    maxQueueWaitMs: 120000,
+});
+export const HANDLER_LIMITS = Object.freeze({
+    readLines: 100,
+    readPathChars: 2048,
+    diagnosticDelayMs: 30000,
+});
+export const REQUEST_PARAMETERS = {
+    type: "object",
+    additionalProperties: false,
+    required: ["protocolVersion", "messageId", "requestId", "type", "payload"],
+    properties: {
+        protocolVersion: { type: "integer", const: 1 },
+        messageId: { type: "string" },
+        requestId: { type: "string" },
+        type: { type: "string", enum: ["request", "status", "result", "cancel"] },
+        payload: { type: "object" },
+    },
+};
+export const STATE_PARAMETERS = {
+    type: "object",
+    properties: {},
+    additionalProperties: false,
+};
+export const REQUEST_DESCRIPTION = "萧何 / Xiao He. Submit a version 1 request and WAIT for its terminal result in this tool call. Reuse requestId only for the same logical operation. Business handler: host.read {file_path,offset?,limit?<=100}. Diagnostic handler only: test {delayMs:0..30000,fail:boolean}; never use it to perform real work. Control status/result/cancel use empty payload. Acceptance is volatile, not success. No polling or restart resume.";
+export const MODE_INSTRUCTIONS = "你正在萧何模式中。这不是角色扮演。保留宿主 PTC 的日常工具能力与权限规则。普通编辑、搜索、命令、安装和其他工作使用原工具，不要声称此模式只读。execution_bus 是可选协调入口，实际业务 Handler 只有 host.read；test 仅用于用户明确要求的诊断，不做真实工作，不要强制所有任务走总线。通过 run_code 调用 await tools.execution_bus(...)，受原有时间预算约束。每会话排队上限 " +
+    ADMISSION_DEFAULTS.sessionQueueLimit +
+    "，排队超过 " +
+    ADMISSION_DEFAULTS.maxQueueWaitMs / 1000 +
+    " 秒且未执行会返回 QUEUE_WAIT_TIMEOUT，不自动重试。execution_bus_state 只用于用户明确诊断本会话元数据，不循环查询。请求只提交一次并等待结果，同一逻辑操作重发沿用 requestId。cancelRequested 不等于已取消，unknown 不代表执行失败，不承诺跨重启恢复。后台命令返回 Job ID 不代表已经完成。";

package/dist/protocol.d.ts

@@ -0,0 +1,49 @@
+export type State = "queued" | "running" | "succeeded" | "failed" | "cancelled" | "unknown";
+export type Owner = {
+    sessionId: string;
+    callId: string;
+};
+export type Message = {
+    protocolVersion: 1;
+    messageId: string;
+    requestId: string;
+    type: "request" | "status" | "result" | "cancel";
+    payload: Record<string, unknown>;
+};
+export type Event = {
+    protocolVersion: 1;
+    messageId: string;
+    requestId: string;
+    correlationId: string;
+    sequence: number;
+    type: string;
+    payload: Record<string, unknown>;
+};
+export type Capability = (input: Record<string, unknown>, signal: AbortSignal) => Promise<unknown>;
+export interface Handler {
+    /** 是否可安全复用终态结果。省略默认 true（可复用，向后兼容）；
+     *  显式 false = 有副作用，终态结果复用将被拒绝（运行中等待仍放行）。 */
+    readonly idempotent?: boolean;
+    validate(input: Record<string, unknown>): void;
+    run(input: Record<string, unknown>, ctx: {
+        signal: AbortSignal;
+        progress: (sequence: number, percent: number) => void;
+        requestId: string;
+        invoke?: Capability;
+    }): Promise<unknown>;
+}
+export interface RecordView {
+    requestId: string;
+    state: State;
+    sequence: number;
+    cancelRequested: boolean;
+    delivery: "pending" | "returned";
+    result?: unknown;
+    error?: string;
+    progress?: number;
+}
+export declare function object(v: unknown): Record<string, unknown>;
+/** 规范排序后的稳定摘要，只用于同 requestId 的冲突比较，不用于跨请求去重。 */
+export declare function canonical(v: unknown): string;
+export declare function parse(raw: unknown): Message;
+export declare function freezeJson<T>(value: T): T;

package/dist/protocol.js

@@ -0,0 +1,54 @@
+import { assertJson } from "./json.js";
+import { ERRORS } from "./error-codes.js";
+import { LIMITS } from "./limits.js";
+export function object(v) {
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        throw Error(ERRORS.INVALID_OBJECT);
+    return v;
+}
+/** 规范排序后的稳定摘要，只用于同 requestId 的冲突比较，不用于跨请求去重。 */
+export function canonical(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return "[" + v.map(canonical).join(",") + "]";
+    return ("{" +
+        Object.keys(v)
+            .sort()
+            .map((k) => JSON.stringify(k) +
+            ":" +
+            canonical(v[k]))
+            .join(",") +
+        "}");
+}
+export function parse(raw) {
+    assertJson(raw);
+    const m = object(raw);
+    if (Object.keys(m).some((k) => ![
+        "protocolVersion",
+        "messageId",
+        "requestId",
+        "type",
+        "payload",
+    ].includes(k)))
+        throw Error(ERRORS.UNKNOWN_FIELD);
+    if (m.protocolVersion !== 1)
+        throw Error(ERRORS.UNSUPPORTED_VERSION);
+    for (const k of ["messageId", "requestId"])
+        if (typeof m[k] !== "string" || !LIMITS.idPattern.test(m[k]))
+            throw Error(ERRORS.INVALID_ID);
+    if (!["request", "status", "result", "cancel"].includes(m.type))
+        throw Error(ERRORS.UNSUPPORTED_TYPE);
+    object(m.payload);
+    if (Buffer.byteLength(JSON.stringify(m)) > LIMITS.messageMaxBytes)
+        throw Error(ERRORS.MESSAGE_TOO_LARGE);
+    return structuredClone(m);
+}
+export function freezeJson(value) {
+    if (value && typeof value === "object") {
+        for (const child of Object.values(value))
+            freezeJson(child);
+        Object.freeze(value);
+    }
+    return value;
+}

package/dist/test-mode.d.ts

@@ -1,5 +1,2 @@
-import type { Context } from "@deepseek-ai/cordis";
-export declare const name = "execution-bus-test-mode";
-export declare const inject: string[];
-/** An additive preset row: presentation, tool inventory and authority belong to the host PTC composition. */
-export declare function apply(ctx: Context): void;
+/** @deprecated Compatibility-only forwarding entry. Use the package /mode export. */
+export { name, inject, apply } from "./mode.js";

package/dist/test-mode.js

@@ -1,15 +1,2 @@
-import { scopeOf } from "@deepseek-ai/dsh-scope";
-import { apply as applyBus } from "./plugin.js";
-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.effect(() => ctx.systemPrompt.section({
-        name: "XIAO_HE_EXECUTION_BUS",
-        order: 1700,
-        text: "你正在萧何模式中。这不是角色扮演。保留宿主 PTC 的日常工具能力与权限规则。普通编辑、搜索、命令、安装和其他工作使用原工具，不要声称此模式只读。execution_bus 是可选协调入口，目前只支持 test 与 host.read，不支持任意命令，不要强制所有任务走总线。通过 run_code 调用 await tools.execution_bus(...)，受原有时间预算约束。总线默认每会话最多排队16项，排队超过120秒且尚未开始执行会返回QUEUE_WAIT_TIMEOUT，不自动重试。execution_bus_state只用于用户明确诊断本会话的元数据状态，不在等待期间循环查询。总线请求只提交一次并等待结果，不循环查询；同一逻辑操作重发沿用 requestId。cancelRequested 不等于已取消，unknown 不代表执行失败，不承诺跨重启恢复。后台命令仅返回 Job ID 不代表命令已经完成。",
-    }));
-    applyBus(ctx);
-}
+/** @deprecated Compatibility-only forwarding entry. Use the package /mode export. */
+export { name, inject, apply } from "./mode.js";

package/docs/PRODUCT.md

@@ -0,0 +1,46 @@
+# 产品结构与维护契约
+
+## 产品边界
+
+萧何是 DSH 内的可选执行协调插件，提供独立可选择的 PTC 派生预设，不是 PTC 替代传输层，也不全局接管终端、编辑或其他工具。实际业务 Handler 为 host.read；test 是兼容保留的诊断 Handler，只有明确诊断需求时使用。测试能力存在不代表其他命令已接入总线。
+
+0.6.0 对齐 DSH 0.2.1-rc.2 并在 core 层为扩展 Handler 增加幂等声明，不以更名宣称完成生产环境认证。当前真实模型、桌面 UI 和实际沙箱尚未完整验收；同进程内存状态不支持跨重启恢复。
+
+## 入口及配置层次
+
+| 入口 | 谁使用 | 责任 |
+|---|---|---|
+| 包级 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 | 工具身份校验、可信执行上下文和宿主 read 派发 | 不自行文件读取或创建通用命令执行端 |
+| bus / json | 请求校验、幂等冲突、调度、取消、终态与有界状态 | 不以超时推定副作用失败、不自动重跑 |
+| execution | Job 投影、活跃工具交付与关闭所有权 | 不作为第二个执行状态机 |
+| handlers | 实际读取适配和明确诊断 Handler | 不把测试当成通用业务执行 |
+| diagnostics | 有界数值轨迹 | 不保留请求内容、错误原文或充当授权审计 |
+
+## 兼容和错误规则
+
+稳定工具名、请求协议和历史预设身份保留。协议校验/背压错误与执行快照中的固定错误码分层；宿主服务错误继续保持真实失败，不统一吞掉，也不把 error 文本写入数值诊断。完整错误词汇见协议说明，本轮不重命名既有错误码。
+
+单一策略定义不表示开放 YAML 调参：宿主插件目前使用固定默认值；core 构造参数仍按原契约使用。新增配置界面需单独定义校验、升级与误配置回归，不能只在文档放不存在的 config 键。
+
+## 交付要求
+
+- 修改身份、默认策略或工具提示时，验证共享 product 契约与实际宿主状态工具一致。
+- 新旧 mode 必须指向同一个模块，派生预设必须使用正式入口。
+- 严格包白名单覆盖正式模块、兼容转发与类型文件；生产隔离安装通过包导出导入两入口核对身份。
+- 继续全量 core、真实宿主生命周期及 Node PTC 回归，不用文档测试替代桌面验收。
+- 完整验证后统一标签 CI 和正式发布；发布不自动安装/重启日常 DSH。

package/docs/releases/0.5.1.md

@@ -0,0 +1,18 @@
+# 萧何 / Xiao He 0.5.1
+
+## 正式产品结构整理
+
+本版修正 test-mode 误导命名并梳理内部职责，保留执行能力和兼容规则，不通过更名宣称生产环境已全部验收。
+
+- 正式实现移至 mode 模块；新增 /mode 导出，新派生预设默认使用它。/test-mode 是同模块兼容别名，旧源/构建文件只保留重导出，不维护两套插件。
+- 产品身份、core/准入默认策略、读取/诊断限制、工具参数和模式提示集中到 product，减少重复定义漂移。
+- 真实业务 host.read 与诊断 test 明确区分：兼容保留 test，但提示模型只在用户明确诊断时使用，不将其描述成真实业务处理能力。
+- 增加正式/旧入口模块身份、默认策略与提示契约测试；真实 Loader 和生产隔离安装检查正式入口。
+
+## 升级说明
+
+先安装 0.5.1 或以上，再将 Agent 预设末尾叠加行改为 @feng0531/dsh-execution-bus/mode；旧版本没有该导出。旧配置不会自动重写且继续可用，不要同时放新旧两行。包级注册入口仍是 /preset，不能与 Agent 内入口混填。
+
+历史预设 execution-bus-test、配置行 preset-execution-bus-test、工具名和协议不改，避免已有会话关联失效。普通 PTC、权限/沙箱、每会话16项和排队120秒等策略不变，不新增运行依赖。
+
+不自动安装、重写日常配置或重启 DSH。真实模型、桌面 UI 与实际沙箱仍未完整验收；不支持跨重启恢复。

package/docs/releases/0.6.0.md

@@ -0,0 +1,20 @@
+# 萧何 / Xiao He 0.6.0
+
+## DSH 0.2.1-rc.2 兼容与 Handler 幂等约束
+
+本版把兼容目标对齐到 DSH 0.2.1-rc.2，并在 core 层为扩展 Handler 增加可声明的幂等约束。
+
+- 兼容目标升级为 DSH 0.2.1-rc.2：五个宿主 peer 依赖由 0.2.0-rc.2 升至 0.2.1-rc.2，锁文件重建。0.2.0-rc.2 宿主应继续使用 0.5.x。
+- 新增 Handler.idempotent 声明。显式 idempotent:false 时，终态结果复用被拒绝并返回 MUTATING_REUSE_DENIED；运行中的重复 attach 仍只等待同一个执行，不会二次执行。省略该字段默认幂等，保持既有 handler 与调用方行为。
+- 内置 test 与 host.read 显式声明 idempotent:true。
+- 适配 0.2.1-rc.2 新增的 workingDirectory 服务：真实宿主组件测试为 read/run_code 路径注入最小 stub，不改变插件运行逻辑。
+
+## 升级说明
+
+需要 DSH 0.2.1-rc.2。升级前先停止新请求，等待已有任务完成或请求合作取消。本版不自动安装、重写日常配置或重启 DSH。
+
+历史预设 execution-bus-test、配置行 preset-execution-bus-test、工具名、协议字段和既有错误码均不变；错误词汇仅新增 MUTATING_REUSE_DENIED。
+
+## 验证与限制
+
+本地全量 76 项测试通过（含新增幂等回归、真实宿主组件与 Node PTC 组件测试），包白名单校验通过。真实模型、桌面 UI 与实际沙箱仍未完整验收；状态仍为进程内存，不支持跨重启恢复。