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

dsh-tool-chaos

开发版本 0.1.0-next.1（GitHub 源码版，未发布 npm 包）：2026-09-28 在 Windows Node.js 24.11.1、DSH 0.1.7-rc.2 上完成本地验证。适配 ToolCallId 和 TypeScript 7；故障注入继续默认关闭。 本轮未重跑真实模型端到端及原生 macOS 验证。

English · 简体中文

CI

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

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

当前状态：0.1.0-next.1 开发候选版（未发布）。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.1.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#

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/: 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]
dsh-tool-chaos codex [--cwd path] [--json]

自动化应读取 --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 开发快照 | Windows Node 24.11.1 下的 @deepseek-ai/dsh-tools@0.1.7-rc.2 运行时集成和全部 32 项测试通过（2026 年 9 月 28 日） |
| 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