dsh-tool-chaos

English · 简体中文

面向 DeepSeek Harness 工具流水线的确定性故障注入与证据化韧性测试。

dsh-tool-chaos 在隔离 DSH 环境中执行完整实验：基线 → dry-run → 故障注入 → PASS / FAIL / INCONCLUSIVE。它帮助插件与 Agent 作者在故障真正发生前，验证重试、fallback、取消、策略拒绝和不可信结果处理是否符合预期。

当前状态：0.1.0-next.0 预发布版。DSH 仍处于 developer preview，请固定版本并查看已验证兼容矩阵。

核心能力

• 五种 DSH 原生 action：deny、error、delay、abort、block。
• 匹配和采样可复现，不使用运行时随机数。
• 默认禁用、默认 dry-run、注入次数有上限，全局通配必须显式启用。
• 输出 JSON 与 Markdown 报告、结构化 decision event 和三态结论。
• 同时提供 Cordis 插件、零运行时依赖 CLI、TypeScript 引擎 API、Codex Plugin 与 Agent Skill。

快速开始

npm 预发布包目前尚未发布。当前可用路径是源码 checkout 加本地 tarball：

git clone https://github.com/cyanseek/dsh-tool-chaos.git
cd dsh-tool-chaos
npm ci
npm run build
npm pack --silent

dsh plugin --profile chaos-demo add ./dsh-tool-chaos-0.1.0-next.0.tgz
dsh --profile chaos-demo --dump-config

有效配置中应同时出现 tool-chaos 和 tool-chaos-reporter。安装完成后两者都不会改变运行行为：主插件默认禁用，reporter 也默认禁用。

生成一份完整 dry-run overlay：

node bin/dsh-tool-chaos.mjs init .dsh-chaos/retry.patch.yml --preset retry

检查生成的工具匹配、任务和断言，再在一次性 profile 中运行：

node bin/dsh-tool-chaos.mjs run \
  --mode dry-run \
  --profile chaos-demo \
  --patch .dsh-chaos/retry.patch.yml \
  --task "调用 web_fetch，并从一次临时故障中恢复" \
  --expect "预期的稳定文本" \
  --no-install \
  --json

dry-run 必须显示预期的 dryRun: true decision，同时不改变工具执行。只有命中完全准确后，才应运行真实故障实验。

从固定 GitHub commit 安装

DSH 可以直接安装本仓库：

dsh plugin --profile chaos-demo add \
  github:cyanseek/dsh-tool-chaos#<commit-sha>

pnpm 10+ 可能按安全策略阻止 Git 依赖的 prepare 脚本。遇到这种情况时，先审查固定 commit 的源码，再把 pnpm 输出的精确 package key 写入该 profile 的 pnpm-workspace.yaml：

allowBuilds:
  dsh-tool-chaos@https://codeload.github.com/cyanseek/dsh-tool-chaos/tar.gz/<commit-sha>: true

重新执行安装并检查有效配置。这个授权意味着允许安装阶段执行包代码；经过审查的 tarball 路径更简单。

卸载并验证移除：

dsh plugin --profile chaos-demo remove dsh-tool-chaos
dsh --profile chaos-demo --dump-config

配置

安装后的默认配置无法注入故障：

- id: tool-chaos
  config:
    enabled: false
    dryRun: true
    seed: dsh-tool-chaos
    allowGlobalWildcard: false
    rules: []

一条有限 dry-run 规则如下：

- id: tool-chaos
  config:
    enabled: true
    dryRun: true
    seed: retry-suite-v1
    allowGlobalWildcard: false
    rules:
      - id: first-github-error
        tool: github_*
        action: error
        scope: root
        argumentsPattern: ''
        probability: 1
        afterMatches: 0
        every: 1
        maxInjections: 1
        delayMs: 1000
        message: deterministic GitHub transport failure

tool 是区分大小写、锚定全字符串的 glob；argumentsPattern 针对键稳定排序后的 JSON。DSH patch row 会整体替换该 row 的 config，所以每份 overlay 都必须重述所有依赖字段。

故障 action

Action	DSH 流水线阶段	行为
deny	tools/pre-execute	分发前拒绝
error	tools/execute	不执行工具主体，返回结构化注入错误
delay	tools/execute	增加支持取消的延迟
abort	tools/execute	中止派生 signal，并恢复上游 signal
block	tools/post-execute	执行工具后扣留其结果

每个 decision 都会发出 tool-chaos/decision。可选 reporter 会把它转换成稳定的 stderr JSONL，前缀为 DSH_TOOL_CHAOS_EVENT 。

证据与结论

CLI 会写入 JSON 真值报告和 Markdown 摘要。报告包含配置哈希、有限的进程元数据、解析后的 chaos decision、断言、结论和复现命令；除非显式要求，否则不会收录原始命令输出。

结论	含义
PASS	预期故障已发生，并且证据支持声明的恢复行为
FAIL	预期故障已发生，但至少一项恢复断言失败
INCONCLUSIVE	基线、安装、匹配、安全或观测证据不完整

退出码本身永远不足以证明韧性。

CLI

dsh-tool-chaos doctor [--profile name] [--json]
dsh-tool-chaos setup [--profile name] [--source npm-or-path] [--codex] [--json]
dsh-tool-chaos init [path] [--preset retry|timeout|nested|result-block|deny] [--force]
dsh-tool-chaos run --patch file --task prompt [--mode baseline|dry-run|experiment]
                   [--expect regex] [--profile name] [--json]
dsh-tool-chaos install-plugin [--profile name] [--source npm-or-path] [--json]
dsh-tool-chaos install-skill [--global | --project path]
dsh-tool-chaos install-codex-plugin [--dir path] [--json]
dsh-tool-chaos verify [--json]
dsh-tool-chaos prompt [--lang en|zh] <requirement...>
dsh-tool-chaos codex [--cwd path] [--json] <requirement...>

自动化应读取 --json，不要抓取面向人的文本输出。

Codex 与 Agent Skill

仓库包含 Codex marketplace plugin 和开放 Agent Skill。可以从 checkout 安装 Codex Plugin：

codex plugin marketplace add /absolute/path/to/dsh-tool-chaos
codex plugin add dsh-tool-chaos@dsh-tool-chaos

新开一个 thread 后执行：

$dsh-chaos-test 证明重试路径能够承受一次确定性的 GitHub 工具错误。

源码工作流见 Codex 集成说明。只有 npm 预发布包真正发布后，npx dsh-tool-chaos ... 才可直接使用。

编程引擎

dsh-tool-chaos/engine 不导入 Cordis 或 DSH runtime：

import { ChaosEngine, resolveConfig } from 'dsh-tool-chaos/engine'

const engine = new ChaosEngine(resolveConfig({
  enabled: true,
  dryRun: false,
  seed: 'ci-retry-v1',
  rules: [{
    id: 'first-web-error',
    tool: 'web_fetch',
    action: 'error',
    maxInjections: 1,
  }],
}))

const decision = engine.decide('execute', {
  callId: 'call-1',
  rootCallId: 'call-1',
  name: 'web_fetch',
  arguments: { url: 'https://example.test' },
})

完整代码见引擎示例。

安全边界

• 使用一次性 profile 和合成或只读测试输入。
• 在看到精确预期命中前保持 dryRun: true。
• 精确全局 * 需要 allowGlobalWildcard: true。
• 每条规则默认最多注入一次。
• 运行时插件不改写参数、不读文件、不访问网络。
• abort 是协作式取消；忽略 AbortSignal 的同进程工具无法被硬杀。
• 被跳过或无法观测的检查绝不能表示为成功。

生产/共享 profile、外部写入、凭据、宽泛目标或权限变更必须有独立安全措施和明确授权。

兼容性

表面	已验证状态
测试	严格 TypeScript 编译和 32 项单元/CLI/真实运行时测试通过
Node	本地 24.11.1；GitHub CI 的 22.19.0 与 24.x 通过
DSH	@deepseek-ai/dsh-tools@0.1.0-rc.6 运行时集成通过
Tarball consumer	安装、重复添加、配置 dump 和只读 headless dry-run preview 通过
GitHub 源码	固定 commit 安装、重复安装、配置 dump、卸载和重装在 pnpm 11.7.0 下通过
npm	尚未发布，不宣称 npm 可用

以上证据于 2026-08-14 使用隔离 profile 和合成只读输入获得。精确矩阵与限制见兼容性说明。

文档

• CLI 与机器 API
• 报告 Schema
• 架构
• Codex 集成
• 兼容性
• 贡献指南
• 安全策略
• 支持
• 变更日志

开发

npm ci
npm run sync:skill
npm run check

任何兼容性结论都必须附有实际通过的精确环境与命令。

许可

MIT