@feng0531/dsh-execution-bus 0.12.0 → 1.0.0

package/dist/runtime/plan.js

@@ -0,0 +1,185 @@
+import { ERRORS } from "../error-codes.js";
+/** 声明式运行时只允许调用这些宿主工具；新增工具需同时更新幂等性判断。 */
+export const RUNTIME_TOOLS = Object.freeze([
+    "read",
+    "glob",
+    "grep",
+    "edit",
+    "write",
+    "pwsh",
+]);
+export const IDEMPOTENT_TOOLS = new Set([
+    "read",
+    "glob",
+    "grep",
+]);
+export const RUNTIME_LIMITS = Object.freeze({
+    steps: 32,
+    planBytes: 64 * 1024,
+    idChars: 64,
+    retry: 3,
+    timeoutMinMs: 1000,
+    timeoutMaxMs: 600000,
+    concurrencyMax: 4,
+    goalChars: 500,
+    resultBytes: 64 * 1024,
+});
+const PLAN_KEYS = new Set(["goal", "steps", "concurrency"]);
+const STEP_KEYS = new Set([
+    "id",
+    "tool",
+    "input",
+    "depends_on",
+    "retry",
+    "timeout_ms",
+]);
+const ID_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+function invalid() {
+    throw Error(ERRORS.INVALID_PLAN);
+}
+function isPlainObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+export function parsePlan(raw) {
+    if (!isPlainObject(raw))
+        invalid();
+    for (const key of Reflect.ownKeys(raw)) {
+        if (typeof key !== "string" || !PLAN_KEYS.has(key))
+            invalid();
+        const descriptor = Object.getOwnPropertyDescriptor(raw, key);
+        if (!("value" in descriptor) || !descriptor.enumerable)
+            invalid();
+    }
+    let bytes = 0;
+    try {
+        bytes = Buffer.byteLength(JSON.stringify(raw));
+    }
+    catch {
+        invalid();
+    }
+    if (bytes > RUNTIME_LIMITS.planBytes)
+        throw Error(ERRORS.PLAN_TOO_LARGE);
+    const goal = raw.goal;
+    if (goal !== undefined) {
+        if (typeof goal !== "string" ||
+            goal.length > RUNTIME_LIMITS.goalChars)
+            invalid();
+    }
+    const concurrency = raw.concurrency ?? 2;
+    if (typeof concurrency !== "number" ||
+        !Number.isSafeInteger(concurrency) ||
+        concurrency < 1 ||
+        concurrency > RUNTIME_LIMITS.concurrencyMax)
+        invalid();
+    if (!Array.isArray(raw.steps))
+        invalid();
+    if (raw.steps.length < 1 || raw.steps.length > RUNTIME_LIMITS.steps)
+        invalid();
+    const ids = new Set();
+    const steps = raw.steps.map((value) => {
+        const step = parseStep(value);
+        if (ids.has(step.id))
+            throw Error(ERRORS.PLAN_DUPLICATE_ID);
+        ids.add(step.id);
+        return step;
+    });
+    for (const step of steps) {
+        for (const dep of step.dependsOn) {
+            if (dep === step.id)
+                invalid();
+            if (!ids.has(dep))
+                throw Error(ERRORS.PLAN_UNKNOWN_DEP);
+        }
+    }
+    assertAcyclic(steps);
+    return {
+        ...(goal === undefined ? {} : { goal: goal }),
+        steps,
+        concurrency,
+    };
+}
+function parseStep(value) {
+    if (!isPlainObject(value))
+        invalid();
+    for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== "string" || !STEP_KEYS.has(key))
+            invalid();
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!("value" in descriptor) || !descriptor.enumerable)
+            invalid();
+    }
+    const id = value.id;
+    if (typeof id !== "string" ||
+        !ID_PATTERN.test(id) ||
+        id.length > RUNTIME_LIMITS.idChars)
+        invalid();
+    const tool = value.tool;
+    if (typeof tool !== "string" || !RUNTIME_TOOLS.includes(tool))
+        throw Error(ERRORS.PLAN_UNKNOWN_TOOL);
+    if (!isPlainObject(value.input))
+        invalid();
+    const dependsOn = value.depends_on ?? [];
+    if (!Array.isArray(dependsOn) || dependsOn.length > RUNTIME_LIMITS.steps)
+        invalid();
+    const deps = [];
+    for (const dep of dependsOn) {
+        if (typeof dep !== "string" || !ID_PATTERN.test(dep))
+            invalid();
+        if (deps.includes(dep))
+            invalid();
+        deps.push(dep);
+    }
+    const retry = value.retry ?? 0;
+    if (typeof retry !== "number" ||
+        !Number.isSafeInteger(retry) ||
+        retry < 0 ||
+        retry > RUNTIME_LIMITS.retry)
+        invalid();
+    if (retry > 0 && !IDEMPOTENT_TOOLS.has(tool))
+        throw Error(ERRORS.PLAN_RETRY_DENIED);
+    const timeoutMs = value.timeout_ms ?? 120000;
+    if (typeof timeoutMs !== "number" ||
+        !Number.isSafeInteger(timeoutMs) ||
+        timeoutMs < RUNTIME_LIMITS.timeoutMinMs ||
+        timeoutMs > RUNTIME_LIMITS.timeoutMaxMs)
+        invalid();
+    return {
+        id,
+        tool: tool,
+        input: structuredClone(value.input),
+        dependsOn: deps,
+        retry,
+        timeoutMs,
+    };
+}
+function assertAcyclic(steps) {
+    const indegree = new Map();
+    const children = new Map();
+    for (const step of steps) {
+        indegree.set(step.id, step.dependsOn.length);
+        for (const dep of step.dependsOn) {
+            const list = children.get(dep) ?? [];
+            list.push(step.id);
+            children.set(dep, list);
+        }
+    }
+    const ready = [...indegree.entries()]
+        .filter(([, degree]) => degree === 0)
+        .map(([id]) => id);
+    let visited = 0;
+    while (ready.length) {
+        const id = ready.pop();
+        visited++;
+        for (const child of children.get(id) ?? []) {
+            const degree = (indegree.get(child) ?? 0) - 1;
+            indegree.set(child, degree);
+            if (degree === 0)
+                ready.push(child);
+        }
+    }
+    if (visited !== steps.length)
+        throw Error(ERRORS.PLAN_CYCLE);
+}

package/dist/runtime/service.d.ts

@@ -0,0 +1,66 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { ToolRunContext } from "@deepseek-ai/dsh-tools";
+import { RunStore } from "./store.js";
+import type { RunRecord, StepRecord } from "./store.js";
+export interface RunSummary {
+    runId: string;
+    state: RunRecord["state"];
+    goal?: string;
+    error?: string;
+    createdAt: number;
+    updatedAt: number;
+    finishedAt?: number;
+    durationMs: number;
+    steps: Array<{
+        id: string;
+        tool: string;
+        state: StepRecord["state"];
+        attempts: number;
+        error?: string;
+    }>;
+}
+/** 每个预设作用域一个运行时服务：运行记录落盘、按会话隔离、可取消/恢复。 */
+export declare class RuntimeService {
+    private readonly ctx;
+    private readonly store;
+    private readonly active;
+    constructor(ctx: Context, store?: RunStore);
+    dispose(): void;
+    run(raw: unknown, exec: ToolRunContext, background?: boolean): Promise<RunSummary | {
+        runId: string;
+        state: "running";
+    }>;
+    status(raw: unknown, exec: ToolRunContext): RunSummary | {
+        runs: {
+            updatedAt: number;
+            stepCount: number;
+            goal?: string | undefined;
+            runId: string;
+            state: import("./store.js").RunState;
+        }[];
+    };
+    result(raw: unknown, exec: ToolRunContext): {
+        results: Record<string, import("./store.js").StoredResult>;
+        finished: boolean;
+        runId: string;
+        state: RunRecord["state"];
+        goal?: string;
+        error?: string;
+        createdAt: number;
+        updatedAt: number;
+        finishedAt?: number;
+        durationMs: number;
+        steps: Array<{
+            id: string;
+            tool: string;
+            state: StepRecord["state"];
+            attempts: number;
+            error?: string;
+        }>;
+    };
+    cancel(raw: unknown, exec: ToolRunContext): RunSummary;
+    resume(raw: unknown, exec: ToolRunContext): Promise<RunSummary>;
+    private sessionId;
+    private owned;
+    private executor;
+}

package/dist/runtime/service.js

@@ -0,0 +1,185 @@
+import { randomUUID } from "node:crypto";
+import { ERRORS } from "../error-codes.js";
+import { RuntimeExecutor } from "./executor.js";
+import { parsePlan } from "./plan.js";
+import { RunStore } from "./store.js";
+const MAX_ACTIVE_RUNS = 8;
+const RUN_KEYS = new Set(["plan", "async"]);
+const RUN_ID_KEYS = new Set(["runId"]);
+function summary(run) {
+    return {
+        runId: run.runId,
+        state: run.state,
+        ...(run.goal === undefined ? {} : { goal: run.goal }),
+        ...(run.error === undefined ? {} : { error: run.error }),
+        createdAt: run.createdAt,
+        updatedAt: run.updatedAt,
+        ...(run.finishedAt === undefined ? {} : { finishedAt: run.finishedAt }),
+        durationMs: Math.max(0, (run.finishedAt ?? Date.now()) - run.createdAt),
+        steps: run.steps.map((step) => ({
+            id: step.id,
+            tool: step.tool,
+            state: step.state,
+            attempts: step.attempts,
+            ...(step.error === undefined ? {} : { error: step.error }),
+        })),
+    };
+}
+function plain(raw, keys) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw Error(ERRORS.INVALID_PLAN);
+    const value = raw;
+    for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== "string" || !keys.has(key))
+            throw Error(ERRORS.INVALID_PLAN);
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!("value" in descriptor) || !descriptor.enumerable)
+            throw Error(ERRORS.INVALID_PLAN);
+    }
+    return value;
+}
+/** 每个预设作用域一个运行时服务：运行记录落盘、按会话隔离、可取消/恢复。 */
+export class RuntimeService {
+    ctx;
+    store;
+    active = new Map();
+    constructor(ctx, store) {
+        this.ctx = ctx;
+        this.store = store ?? new RunStore();
+        this.store.markInterrupted();
+        this.store.prune(100);
+    }
+    dispose() {
+        for (const entry of this.active.values())
+            entry.controller.abort();
+        this.active.clear();
+    }
+    async run(raw, exec, background = false) {
+        const sessionId = this.sessionId(exec);
+        const input = plain(raw, RUN_KEYS);
+        const plan = parsePlan(input.plan);
+        if (input.async !== undefined && typeof input.async !== "boolean")
+            throw Error(ERRORS.INVALID_PLAN);
+        if (this.active.size >= MAX_ACTIVE_RUNS)
+            throw Error(ERRORS.RUNTIME_BUSY);
+        const executor = this.executor(exec);
+        const run = executor.createRun(sessionId, plan);
+        const controller = new AbortController();
+        const promise = executor
+            .execute(run, controller.signal)
+            .catch((error) => {
+            run.state = "failed";
+            run.error = ERRORS.RUNTIME_STEP_FAILED;
+            run.finishedAt = Date.now();
+            try {
+                this.store.save(run);
+            }
+            catch { }
+            throw error;
+        });
+        this.active.set(run.runId, { controller, promise });
+        void promise
+            .finally(() => this.active.delete(run.runId))
+            .catch(() => { });
+        if (background === true || input.async === true)
+            return { runId: run.runId, state: "running" };
+        return summary(await promise);
+    }
+    status(raw, exec) {
+        const sessionId = this.sessionId(exec);
+        const input = plain(raw, RUN_ID_KEYS);
+        if (input.runId === undefined) {
+            return {
+                runs: this.store
+                    .list(20)
+                    .filter((run) => run.ownerSessionId === sessionId)
+                    .map((run) => ({
+                    runId: run.runId,
+                    state: run.state,
+                    ...(run.goal === undefined ? {} : { goal: run.goal }),
+                    updatedAt: run.updatedAt,
+                    stepCount: run.steps.length,
+                })),
+            };
+        }
+        const run = this.owned(input.runId, sessionId);
+        return summary(run);
+    }
+    result(raw, exec) {
+        const sessionId = this.sessionId(exec);
+        const input = plain(raw, RUN_ID_KEYS);
+        if (typeof input.runId !== "string")
+            throw Error(ERRORS.RUNTIME_NOT_FOUND);
+        const run = this.owned(input.runId, sessionId);
+        return {
+            ...summary(run),
+            results: run.results,
+            finished: run.state !== "running" && run.state !== "interrupted",
+        };
+    }
+    cancel(raw, exec) {
+        const sessionId = this.sessionId(exec);
+        const input = plain(raw, RUN_ID_KEYS);
+        if (typeof input.runId !== "string")
+            throw Error(ERRORS.RUNTIME_NOT_FOUND);
+        const run = this.owned(input.runId, sessionId);
+        const active = this.active.get(run.runId);
+        if (active)
+            active.controller.abort();
+        else
+            this.executor(exec).cancel(run);
+        try {
+            this.store.save(run);
+        }
+        catch { }
+        return summary(run);
+    }
+    async resume(raw, exec) {
+        const sessionId = this.sessionId(exec);
+        const input = plain(raw, RUN_ID_KEYS);
+        if (typeof input.runId !== "string")
+            throw Error(ERRORS.RUNTIME_NOT_FOUND);
+        const run = this.owned(input.runId, sessionId);
+        if (run.state !== "interrupted")
+            throw Error(ERRORS.RUNTIME_INVALID_STATE);
+        const executor = this.executor(exec);
+        const controller = new AbortController();
+        const promise = executor.resume(run, controller.signal);
+        this.active.set(run.runId, { controller, promise });
+        void promise
+            .finally(() => this.active.delete(run.runId))
+            .catch(() => { });
+        return summary(await promise);
+    }
+    sessionId(exec) {
+        if (!exec.agent)
+            throw Error(ERRORS.OWNING_SESSION_REQUIRED);
+        return String(exec.agent.id);
+    }
+    owned(runId, sessionId) {
+        if (typeof runId !== "string")
+            throw Error(ERRORS.RUNTIME_NOT_FOUND);
+        const run = this.store.load(runId);
+        if (!run || run.ownerSessionId !== sessionId)
+            throw Error(ERRORS.RUNTIME_NOT_FOUND);
+        return run;
+    }
+    executor(exec) {
+        const self = this;
+        const invoke = async (tool, input, signal) => {
+            const result = await self.ctx.tools.execute({
+                name: tool,
+                callId: (String(exec.callId) + ":runtime:" + randomUUID()),
+                rootCallId: exec.rootCallId,
+                parent: exec.token,
+                agent: exec.agent,
+                arguments: input,
+                signal,
+            });
+            if (result.isError)
+                throw Error(ERRORS.RUNTIME_STEP_FAILED);
+            return result.value;
+        };
+        return new RuntimeExecutor(this.store, invoke);
+    }
+}

package/dist/runtime/store.d.ts

@@ -0,0 +1,45 @@
+import type { Plan } from "./plan.js";
+export type RunState = "running" | "succeeded" | "failed" | "cancelled" | "interrupted";
+export type StepState = "pending" | "running" | "succeeded" | "failed" | "cancelled" | "unknown";
+export interface StepRecord {
+    id: string;
+    tool: string;
+    state: StepState;
+    attempts: number;
+    startedAt?: number;
+    finishedAt?: number;
+    error?: string;
+}
+export interface StoredResult {
+    value?: unknown;
+    truncated?: true;
+    bytes?: number;
+}
+export interface RunRecord {
+    version: 1;
+    runId: string;
+    ownerSessionId: string;
+    goal?: string;
+    plan: Plan;
+    state: RunState;
+    steps: StepRecord[];
+    results: Record<string, StoredResult>;
+    createdAt: number;
+    updatedAt: number;
+    finishedAt?: number;
+    error?: string;
+}
+export declare function defaultRunRoot(): string;
+/** 纯文件持久化运行记录；原子写入，损坏记录忽略，不做跨进程锁。 */
+export declare class RunStore {
+    readonly root: string;
+    constructor(root?: string);
+    pathFor(runId: string): string;
+    save(run: RunRecord): void;
+    load(runId: string): RunRecord | undefined;
+    list(limit?: number): RunRecord[];
+    remove(runId: string): void;
+    prune(max?: number): void;
+    /** 启动时把上次进程留下的 running 记录标记为 interrupted；不自动重跑副作用步骤。 */
+    markInterrupted(): number;
+}

package/dist/runtime/store.js

@@ -0,0 +1,102 @@
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ERRORS } from "../error-codes.js";
+const RUN_ID = /^run-[0-9a-z-]{8,80}$/;
+const RECORD_BYTES = 4 * 1024 * 1024;
+export function defaultRunRoot() {
+    if (process.env.XIAOHE_RUNTIME_DIR)
+        return path.resolve(process.env.XIAOHE_RUNTIME_DIR);
+    const home = process.env.DSH_HOME ?? path.join(os.homedir(), ".dsh");
+    return path.join(home, "tmp", "xiaohe-runtime", "runs");
+}
+/** 纯文件持久化运行记录；原子写入，损坏记录忽略，不做跨进程锁。 */
+export class RunStore {
+    root;
+    constructor(root = defaultRunRoot()) {
+        this.root = root;
+        mkdirSync(this.root, { recursive: true });
+    }
+    pathFor(runId) {
+        if (!RUN_ID.test(runId))
+            throw Error(ERRORS.RUNTIME_NOT_FOUND);
+        return path.join(this.root, runId + ".json");
+    }
+    save(run) {
+        const target = this.pathFor(run.runId);
+        const json = JSON.stringify(run);
+        if (Buffer.byteLength(json) > RECORD_BYTES)
+            throw Error(ERRORS.RUNTIME_INVALID_STATE);
+        const temp = target + ".tmp";
+        writeFileSync(temp, json, "utf8");
+        renameSync(temp, target);
+    }
+    load(runId) {
+        let text;
+        try {
+            text = readFileSync(this.pathFor(runId), "utf8");
+        }
+        catch {
+            return undefined;
+        }
+        try {
+            const value = JSON.parse(text);
+            if (value?.version !== 1 || value.runId !== runId)
+                return undefined;
+            if (!Array.isArray(value.steps) || typeof value.plan !== "object")
+                return undefined;
+            return value;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    list(limit = 20) {
+        let names = [];
+        try {
+            names = readdirSync(this.root);
+        }
+        catch {
+            return [];
+        }
+        const runs = [];
+        for (const name of names) {
+            if (!name.endsWith(".json"))
+                continue;
+            const run = this.load(name.slice(0, -".json".length));
+            if (run)
+                runs.push(run);
+        }
+        runs.sort((a, b) => b.updatedAt - a.updatedAt);
+        return runs.slice(0, limit);
+    }
+    remove(runId) {
+        rmSync(this.pathFor(runId), { force: true });
+    }
+    prune(max = 100) {
+        for (const run of this.list(10000).slice(max))
+            this.remove(run.runId);
+    }
+    /** 启动时把上次进程留下的 running 记录标记为 interrupted；不自动重跑副作用步骤。 */
+    markInterrupted() {
+        let count = 0;
+        for (const run of this.list(1000)) {
+            if (run.state !== "running")
+                continue;
+            run.state = "interrupted";
+            run.error = ERRORS.RUNTIME_INTERRUPTED;
+            run.finishedAt ??= Date.now();
+            for (const step of run.steps) {
+                if (step.state === "running") {
+                    step.state = "unknown";
+                    step.error = ERRORS.RUNTIME_INTERRUPTED;
+                    step.finishedAt ??= Date.now();
+                }
+            }
+            run.updatedAt = Date.now();
+            this.save(run);
+            count++;
+        }
+        return count;
+    }
+}

package/docs/DECLARATIVE-RUNTIME.md

@@ -0,0 +1,44 @@
+# 声明式运行时（1.0 迁移中）
+
+> 状态：**第一阶段已落地**（运行时内核 + 工具 + 落盘恢复 + 测试），旧 `execution_bus` 暂保留为兼容；后续版本移除旧总线并统一文档。
+
+## 它是什么
+
+模型不再在 `run_code` 里写循环/等待，而是提交一份**计划（plan）**：
+
+```json
+{
+  "goal": "读取两个文件并汇总",
+  "concurrency": 2,
+  "steps": [
+    { "id": "a", "tool": "read", "input": { "file_path": "README.md" } },
+    { "id": "b", "tool": "read", "input": { "file_path": "package.json" } },
+    { "id": "c", "tool": "pwsh", "input": { "description": "汇总", "command": "echo ok" }, "depends_on": ["a", "b"] }
+  ]
+}
+```
+
+运行时负责：DAG 校验、独立步骤并行、只读步骤重试、每步超时、结果落盘、取消与重启后恢复。模型只表达意图和依赖，不写编排代码。
+
+## 工具
+
+| 工具 | 作用 |
+|---|---|
+| `runtime_run` | 提交计划；默认等待完成并返回步骤状态，`async:true` 立即返回 `runId` |
+| `runtime_status` | 无 runId 列出最近运行；带 runId 返回步骤状态（不含结果） |
+| `runtime_result` | 读取已保存的步骤结果（单步 >64KiB 只返回 truncated/bytes） |
+| `runtime_cancel` | 停止调度、传播取消 |
+| `runtime_resume` | 显式恢复 `interrupted` 运行（只读步骤重排，副作用在途步骤标 failed） |
+
+## 语义与边界
+
+- 允许工具：`read/glob/grep/edit/write/pwsh`；`retry` 只允许 `read/glob/grep`。
+- 计划上限：32 步、64KiB、并发 1–4、单步超时 1s–600s。
+- 运行记录保存在 `DSH_HOME/tmp/xiaohe-runtime/runs`（可用 `XIAOHE_RUNTIME_DIR` 覆盖），按会话隔离。
+- 崩溃/重启后运行标记 `interrupted`；在途步骤 `unknown`。**不保证 exactly-once**：副作用可能已发生，恢复时副作用步骤标 `failed/RUNTIME_INTERRUPTED`，只读步骤可重排。
+- 不做跨进程执行、不做分布式队列；运行时随宿主进程退出。
+- 计划质量是新的失败来源；稳定、可枚举的流程适合，探索型任务仍用 PTC 原工具。
+
+## 与旧 execution_bus 的关系
+
+旧总线（`execution_bus` 工具）提供 requestId 去重、预算分离等待与宿主 Job 投影；声明式运行时提供更上层的计划编排与恢复。两者当前共存，文档与预设会在后续版本收敛到运行时，旧总线冻结为历史参考。

package/docs/FLOW-TEST.md

@@ -1,56 +1,9 @@
-# 不安装到日常 DSH 的流程测试
+# 流程测试说明
 
-## 适合什么场景？
+1. 安装候选包并在隔离 DSH 配置中加载 bundle，确认预设 **xiao-he-runtime** 出现且默认预设未变。
+2. 在会话中调用 `runtime_run` 提交一个两步计划（read + echo），确认返回 `succeeded` 与步骤状态。
+3. 提交 `async:true` 计划，用 `runtime_status`/`runtime_result` 取回；用 `runtime_cancel` 验证取消。
+4. 重启宿主后检查 `runtime_status`：未完成运行应为 `interrupted`，用 `runtime_resume` 恢复只读步骤。
+5. 验证普通 Agent 看不到 `runtime_*` 工具，宿主写策略拒绝仍生效。
 
-先验证代码行为，而不改日常 DSH 配置。命令在独立 Node 进程中加载本仓库产物和真实 DSH npm 组件，不向正在使用的宿主注入插件，也不重启宿主。
-
-**由聊天会话启动测试，不等于该聊天会话直接调用了 execution_bus。** 真实模型、GUI、PTC 进程和桌面沙箱结论不能由此替代。
-
-## 如何运行
-
-```powershell
-npm ci --include=dev --ignore-scripts
-npm run test:flow
-npm run check
-npm run verify:package
-npm run test:install
-```
-
-| 命令 | 实际范围 |
-|---|---|
-| `test:flow` | 三个固定测试文件：早期流程回归、真实宿主工具组件、脚本适配器驱动的 AgentLoop |
-| `check` | 编译并运行全部测试；包括后续 Job 故障、卸载、预设隔离等回归 |
-| `verify:package` | 检查候选打包清单及导出，不安装日常宿主 |
-| `test:install` | 在临时目录安装生产依赖并验证根入口/简化注册，结束后清理 |
-| `metrics:sessions` | 只读扫描本机会话日志，汇总总线请求/Handler/复用标记/错误，用于采用率观察 |
-
-`test:flow` 不是全部集成测试的别名；发布前必须运行 `check`。临时安装不是桌面插件管理器安装。完整验证层次见[验证范围](<validation.md>)。
-
-`metrics:sessions` 只读取本地会话日志，不发送网络请求，也不代表模型效果对比；它是采用率与异常观察工具，不是 A/B 基准。
-
-## 已覆盖的代表场景
-
-- 正常受理与异步返回，两个会话不串线，同键冲突拒绝。
-- 并发重复请求共用执行/Job；终态结果在宿主槽位满时仍可复用。
-- 查询额度、附着容量、取消保留槽及过期结果清理。
-- 合作取消、晚取消、未知结果不自动重跑。
-- 深层/非 JSON 结果拒绝，结果和通知不可变，异步观察者拒绝隔离。
-- 已受理 Handler 与替换注册并存，旧注销函数不破坏新注册。
-- 宿主 read/glob/grep/edit/write/pwsh 真正经过工具管线；前置拒绝仍生效（搜索与命令的转发测试使用宿主工具桩，不代表真实工具实现）。
-- Job 先行移除、等待/清理异常与卸载交错。
-- 派生预设成功激活、原 ptc 声明不变、普通 Agent 不可见总线、write/edit 保留且宿主策略可拒绝。
-- 真实 Node PTC 进程调用原 read 与总线；测试使用显式非约束策略，不代表桌面沙箱通过。
-- 真实 Node PTC 预算到期后，已受理总线执行继续并可同 requestId 取回；外部中断仍请求取消执行。
-
-以上是场景摘要，不表示真实模型/宿主 GUI 已通过。
-
-## 测试之外仍需注意
-
-- 宿主工具调用失败在转发层使用固定码（host.read 为 `HOST_READ_FAILED`，其余为 `HOST_TOOL_FAILED`），进入总线后统一结算为 `failed` / `HANDLER_FAILED`，错误原文不保存；取消后可能保守记为 `unknown`，不能把它当作取消已确认。
-- 相同逻辑请求的取消是请求级取消，不能简单用 Promise.race 放弃执行来改成等待者级取消。
-- 当前没有远端 Handler 传输或持久化恢复；测试没有提供这些能力。
-- 预算分离等待依据 DSH 0.2.1-rc.2 的内部中断原因字符串；换宿主版本需重新验证，未知原因保守按取消处理。
-
-## 要直接在聊天会话中试用
-
-需要先通过宿主正常加载插件，并让目标 Agent 看得到 `execution_bus`。建议加载可选“萧何”预设，新建专门会话；不要全局注入工具。安装/加载需使用者自行授权，是否重启由使用者决定。只启动另一个 Node 进程、伪造 sessionId 或追加聊天结果，都不算恢复原工具调用。参见[使用说明](<../README.md>)。
+边界：测试夹具使用测试 Agent 与工具桩，不代表真实模型、桌面 UI 或实际沙箱验收。