# dsh-tool-chaos

[English](README.md) · **简体中文**

[![CI](https://github.com/cyanseek/dsh-tool-chaos/actions/workflows/ci.yml/badge.svg)](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：

```bash
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：

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

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

```bash
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 可以直接安装本仓库：

```bash
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`：

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

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

卸载并验证移除：

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

## 配置

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

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

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

```yaml
- 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

```text
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：

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

新开一个 thread 后执行：

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

源码工作流见 [Codex 集成说明](docs/CODEX.md)。只有 npm 预发布包真正发布后，`npx dsh-tool-chaos ...` 才可直接使用。

## 编程引擎

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

```ts
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)

## 开发

```bash
npm ci
npm run sync:skill
npm run check
```

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

## 许可

[MIT](LICENSE)