故障注入测试cyanseek/dsh-tool-chaos

dsh-tool-chaos

English · 简体中文

CI

面向 DeepSeek Harness 工具管线的确定性故障注入与有证据支撑的韧性测试。

dsh-tool-chaos 通过 baseline → dry-run → fault injection → PASS / FAIL / INCONCLUSIVE 运行一个隔离的 DSH 实验。它帮助插件和 Agent 作者在这些路径意外失败之前，验证重试、回退、取消、策略拒绝和不可信结果的行为。

状态：0.1.0-next.0 预发布版。DSH 仍处于开发者预览阶段，因此请固定版本并查看已测试兼容性矩阵。

亮点

- 五个 DSH 原生动作：deny、error、delay、abort 和 block。
- 可复现的匹配与采样；无运行时随机性。
- 默认禁用并处于 dry-run 模式，具有有界注入和显式的全局通配符选择加入。
- JSON 和 Markdown 报告，包含结构化决策事件和三态判定。
- 原生 Cordis 插件、零运行时依赖 CLI、TypeScript 引擎 API，以及 Codex/Agent Skill 接口。

快速开始

npm 预发布版尚未发布。目前可用的途径是源码检出和本地构建的 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 覆盖配置：

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 "Use web_fetch and recover from one transient failure" \
--expect "expected stable phrase" \
--no-install \
--json

dry-run 必须显示预期的 dryRun: true 决策，同时保持工具执行不变。只有在匹配完全一致后，才运行真实实验。

从固定的 GitHub 提交安装

DSH 可以直接安装此仓库：

dsh plugin --profile chaos-demo add \
github:cyanseek/dsh-tool-chaos#

pnpm 10+ 可能会故意阻止 Git 依赖的 prepare 脚本。如果发生这种情况，请查看固定的源码，并将 pnpm 打印的确切包键 复制到该 profile 的 pnpm-workspace.yaml 中：

allowBuilds:
dsh-tool-chaos@https://codeload.github.com/cyanseek/dsh-tool-chaos/tar.gz/: 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: []

一个有界的预览规则如下所示：

- 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 补丁行会替换某一行的完整 config，因此每个 overlay 都必须重新声明它所依赖的所有键。

故障操作

| 操作 | DSH 流水线阶段 | 行为 |
|---|---|---|
| deny | tools/pre-execute | 在派发前拒绝 |
| error | tools/execute | 返回结构化注入错误，而不运行工具主体 |
| delay | tools/execute | 添加可中止的延迟 |
| abort | tools/execute | 中止派生的信号并恢复上游信号 |
| block | tools/post-execute | 运行工具，然后扣留其结果 |

每个决策都会发出 tool-chaos/decision。可选报告器会将其转换为以 DSH_TOOL_CHAOS_EVENT  为前缀的稳定 stderr JSONL 边界。

证据与判定

CLI 会写入一份 JSON 事实来源报告和一份 Markdown 摘要。报告包含配置哈希、有界的进程元数据、解析后的 chaos 决策、断言、判定以及复现命令。除非明确要求，否则原始命令输出会被排除。

| 判定 | 含义 |
|---|---|
| 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]
dsh-tool-chaos codex [--cwd path] [--json]

自动化应使用 --json，而不是抓取人类可读的输出。

Codex 与 Agent Skill

该仓库包含一个 Codex 市场插件和一个开放的 Agent Skill。从检出目录安装 Codex 插件：

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

启动一个新线程并调用：

$dsh-chaos-test Prove the retry path survives one deterministic GitHub tool error.

有关源码检出工作流，请参阅 Codex 集成。npx dsh-tool-chaos ... 命令仅在 npm 预发布版发布后才可用。

编程式引擎

dsh-tool-chaos/engine 导出不导入任何 Cordis 或 DSH 运行时：

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' },
})

请参阅引擎示例。

安全边界

- 使用一次性配置文件和合成或只读测试输入。
- 在确切的预期匹配可见之前，保持 dryRun: true。
- 精确的全局 * 需要 allowGlobalWildcard: true。
- 默认情况下，每条规则最多注入一次。
- 运行时插件不会重写参数、读取文件或访问网络。
- abort 是协作式的；忽略 AbortSignal 的同进程工具无法被强制终止。
- 绝不要将跳过或不可观测的检查表示为成功。

生产/共享配置文件、外部变更、凭据、广泛目标定位或权限变更需要单独的保护措施和明确授权。

兼容性

| 层面 | 已验证状态 |
|---|---|
| 测试 | 严格 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 使用者 | 安装、重复添加、配置转储以及只读无头 dry-run 预览通过 |
| GitHub 源码 | 使用 pnpm 11.7.0 时，固定提交安装、重复安装、配置转储、卸载和重新安装均通过 |
| npm | 未发布；未做出任何 npm 可用性声明 |

证据于 2026 年 8 月 14 日使用隔离配置文件和合成只读输入收集。有关精确矩阵和限制，请参阅兼容性。

文档

- CLI 与机器 API
- 报告 schema
- 架构
- Codex 集成
- 兼容性
- 贡献指南
- 安全
- 支持
- 更新日志

开发

npm ci
npm run sync:skill
npm run check

兼容性声明必须由通过测试的确切环境和命令作为依据。

许可证

MIT