前言¶

在 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。