dsh-tool-chaos

English · 简体中文

![CI](https://github.com/cyanseek/dsh-tool-chaos/actions/workflows/ci.yml)

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

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

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

核心能力

五种 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 集成说明](docs/CODEX.md)。只有 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' },
})

完整代码见[引擎示例](examples/engine-api.mjs)。

安全边界

使用一次性 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 和合成只读输入获得。精确矩阵与限制见[兼容性说明](docs/COMPATIBILITY.md)。

文档

[CLI 与机器 API](docs/CLI.md)
[报告 Schema](docs/REPORT-SCHEMA.md)
[架构](docs/ARCHITECTURE.md)
[Codex 集成](docs/CODEX.md)
[兼容性](docs/COMPATIBILITY.md)
[贡献指南](CONTRIBUTING.zh-CN.md)
[安全策略](SECURITY.md)
[支持](SUPPORT.md)
[变更日志](CHANGELOG.md)

开发

npm ci
npm run sync:skill
npm run check

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

许可

[MIT](LICENSE)

来源信息

安装

检查来源文件

dsh-tool-chaos

核心能力

快速开始

从固定 GitHub commit 安装

配置

故障 action

证据与结论

CLI

Codex 与 Agent Skill

编程引擎

安全边界

兼容性

文档

开发

许可

更多相关插件

dsh-landscape

dsh-autofix

dsh-native-playbook