前言¶

在 DSH 插件或 Agent 开发中，故障路径和恢复行为往往需要单独验证。dsh-tool-chaos 把这类验证做成可复现实验：先做 dry-run，确认匹配与边界，再决定是否进入真实注入，并输出 JSON / Markdown 报告与三态 verdict。下面介绍它的定位、安装、典型用法和注意事项。

这是什么¶

dsh-tool-chaos 是一个 DSH 插件，由 cyanseek 维护，采用 MIT 许可，当前版本为 0.1.0-next.0 prerelease。它面向 DeepSeek Harness tool pipeline，提供 deterministic fault injection、autonomous resilience experiments 和 machine-readable evidence。

DSH 的理念是“一切皆插件”；社区目录是独立站点，不等于官方应用商店，也不代表与 DeepSeek 或幻方有官方从属关系。

由于 DSH 仍在 developer preview，使用 dsh-tool-chaos 时应 pin 版本，并核对 tested compatibility matrix。

核心能力¶

• 五种 DSH-native actions：deny、error、delay、abort、block。
• 可复现的 matching 和 sampling，没有 runtime randomness。
• 默认 disabled 和 dry-run，注入 bounded，global wildcard 需要显式 opt-in。
• 输出 JSON 和 Markdown reports，包含 structured decision events 和三态 verdict。
• 提供 Native Cordis plugin、zero-runtime-dependency CLI、TypeScript engine API，以及 Codex/Agent Skill surfaces。

安装与启用¶

当前 npm prerelease 尚未发布；npx dsh-tool-chaos 只有在 npm prerelease 发布后才可用。现在可先用本地 tarball 路径安装：

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

安装后默认不能注入故障。默认值如下：

enabled: false
dryRun: true
allowGlobalWildcard: false
rules: []

如果要从 GitHub 固定 commit 安装，使用 pinned 形式：

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

pnpm 10+ 可能会拦截 Git 依赖的 prepare script。若发生，先审查 pinned source，再把 pnpm 打印的精确 package key 写入该 profile 的 pnpm-workspace.yaml。

典型用法¶

先初始化一个 patch 文件：

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

然后在 disposable profile 上做 dry-run：

node bin/dsh-tool-chaos.mjs run \
  --mode dry-run \
  --profile chaos-demo \
  --patch .dsh-chaos/retry.patch.yml \
  --task "Use web_fetch and recover from one transient failure" \
  --expect "expected stable phrase" \
  --no-install \
  --json

这一步保持 dry-run。先做 dry-run，确认 exact intended match 可见后，再决定是否进入真实实验。

如果要接入 Codex，可以使用仓库中的 Codex plugin 安装入口：

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

如果要使用 TypeScript engine API，入口是：

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

适用场景与注意¶

dsh-tool-chaos 适合插件作者和 Agent 作者在 DSH tool pipeline 上验证故障路径、恢复行为，并保留机器可读证据。使用前注意以下几点：

• 使用 disposable profiles，以及 synthetic 或 read-only test inputs。
• 在 exact intended match 可见前，保持 dryRun: true。
• 精确 global * 需要 allowGlobalWildcard: true。
• 默认每条规则最多注入一次。
• runtime plugin 不 rewrite arguments、不读文件、不访问网络。
• abort 是 cooperative；对于忽略 AbortSignal 的同进程 tool，无法 hard-kill。
• production/shared profiles、external mutations、credentials、broad targeting、privilege changes，都需要独立 safeguards 和 explicit authorization。
• 不要把 skipped 或 unobservable checks 表示成 success。
• 插件以当前 dsh 进程权限运行，安装前应检查源码与 MIT 许可证。
• npm prerelease 尚未发布，npx dsh-tool-chaos 只有在 npm prerelease 发布后才可用。

结尾¶

dsh-tool-chaos 的价值，是把“故障时能不能恢复”从口头判断变成可复现实验和结构化证据。它当前仍处于 prerelease，适合先在小范围、受控的 DSH 工具链中使用。

当前资料未提供目录页 URL；GitHub 仓库：cyanseek/dsh-tool-chaos。