DeeSeek Harness 事故振り返りとエンジニアリング文化

dsh リポジトリは、「あるべきでないのに発生した」あらゆるバグを事故報告書(postmortem)として書き残し、テスト・ドキュメント・ルールのレベルで防御を残します。

この振り返り文化とテスト規律を理解すれば、サンプル プロジェクトでも活用できます。dsh を使いこなすだけでなく、メンテナーのように考えられるようになります。

一言で言うと、バグの価値はその修正行にあるのではなく、なぜプロセスが見逃したのか、そして同種の問題が次回明確にエラーになるようにどのような防御を追加したのかにあります。


振り返り文化:四つの問い

事故報告書が記録するのは、バグが存在すべきでない場所(実ユーザー、マージ済みのPR、リリース済みバージョン)に現れた、ということです。

注目すべきはなぜ我々のプロセスがそれを見逃したのかであり、単なる修正行ではありません。

それは回顧的な失敗の記録であり、次の四つの問いに答えます。

四つの問い何に答えるのか
何が壊れたのか忙しい読者が30秒で要点を吸収できる短い段落で
メカニズムは何か平易な言葉で根本原因を明確にし、個人を非難しない
なぜすべてのセーフティネットが防げなかったのか一度きりの書き間違いではなく、テスト・ツール・規約の欠陥を見つける
どのような防御を追加したのかテスト、AGENTS.md ルール、ADR により、同種のバグが次回明確にエラーを出すようにする

すべてのバグが振り返りを書く価値があるわけではありません。

バグが次の三つの条件をすべて満たす場合にのみ書きます。隠れている(メカニズムが一目瞭然ではなく、注意深いエンジニアでも苦労して再導出しなければならない)、システム的な(見逃しの原因がテスト・ツール・規約の欠陥である)、再発見のコストが高い(実際のデバッグ時間を消費し、次回もそうなる)。

事故复盘流程与测试金字塔图


四つの実例

リポジトリには現在4件の事故報告書があり、それぞれが再発しやすいある種のエンジニアリングミスに対応しています。

以下で一つずつ紹介します。重点は「なぜ見逃されたか」と「どのような防御を追加したか」です。

ポストモーテム 0001

ACP サーバーが接続時にクラッシュ:export default がプラグインの inject を失った。

何が壊れたか:エディター(Zed)が接続すると、最初のsession/newが即座にエラーを報告した。cannot get property "agents" without inject。

メカニズム:プラグインは余分なexport default applyを書き、Loader のunwrapExportsが裸の関数を取得し、名前空間上のinjectを丸ごと失った。

なぜセーフティネットは防げなかったか:178件のグリーンユニットテスト + 100%行カバレッジがすべてあるのに、すべてのテストは手動でctx.plugin(...)マウントされており、実際の Loader のロードパスを迂回していました。

追加した防御:default export の削除;キー不要の実際の Loader スモークテストを追加;ルール「実際のエントリパスをテストせよ、行カバレッジは動作カバレッジではない」。

ポストモーテム 0002

ファイルシステムスナップショットツールが `!!js` というリテラルオブジェクトによって恒久的に無効化された。

何が壊れたか:7つのファイルシステムシナリオがレジストリに存在しないツールを呼び出し、UNKNOWN_TOOL。

メカニズム:作者はdisabled: !!js ...を使ってファイルシステムプラグインを条件的に有効化しようとしたが、Cordis はプラグインconfig内部でのみ JS 式を評価する;直接disabled設定項目を読むと、それは truthy オブジェクトとして見えていた。

なぜセーフティネットは防げなかったか:スナップショット更新は「決定論的なリプレイ」を「正しい動作」とみなしていました。回帰が安定して再現されることは証明しましたが、ファイルシステムツールが実際に登録されたことは証明していません。

追加した防御:明示的なファイルシステムオーバーレイに変更;静的設定ガードが Loader 設定項目メタデータ内の式ノードを拒否;スナップショットフレームワークが構造化UNKNOWN_TOOL結果を拒否。

ポストモーテム 0003

Web エージェントは、セッションを担う GUI ではなく、代替サーバーを検収してしまった。

何が壊れたか:エージェントは GUI ソースを変更したが、現在のセッションがどの URL に対応し、どのプロセスが担っているのかを把握していなかった。

メカニズム:それは裸の Vite が返す HTTP 200 を成功とみなした(実際は白画面)。その後、別のポートで動く代替dsh webサーバーを検収し、3081 ポートを決して調べなかった。

なぜセーフティネットは防げなかったのか:Web コンポジションはモデルに現在の GUI・規範 URL・実行モードの識別情報を提供しなかった;最初の回帰テストはさらに「プロセスタイムアウト」を「フェイルファスト」と偽装し、誤検知を生んだ。

{'translated_text': '追加した防御:ランチャーが規範的なループバックURLと実際の本番/開発モード(環境変数+プロンプトセクション)を公開;独立Viteサービスモードは設定段階で起動を拒否;階層のな実際のパステストがCLI・プロンプト・ランタイムの事実・ブラウザHMRをカバー。'}

ポストモーテム 0004

Landlock の部分的な強制通知により、子プロセスの失敗が誤って分類された。

何が壊れたか:古い Landlock ABI のカーネル上で、ripgrep がマッチなしで終了コード 1 により正常終了したのに、SANDBOX_UNAVAILABLEサンドボックス障害として表示された。

メカニズム:launcher が無害なlandlock-run: partial enforcement (older Landlock ABI)通知を出力;harness は大文字小文字を区別しないlandlock-run: 部分文字列で通知と任意の非ゼロ終了を組み合わせ、runner の失敗と誤判定した。

なぜセーフティネットは防げなかったか:サンドボックス結果タイプは一群の部分文字列しか表現できず、「Landlock 失敗は終了コード125 + 致命的診断行でなければならない」を表現できない;テストマトリクスは「通知に続いて非ゼロの子プロセス終了」という組み合わせを決して構築しなかった。

追加した防御:RunnerFailureRule許可終了コード・行単位の致命的署名・正確な除外を備えた情報行を運ぶ;ファイルシステム検索はctx.subprocessバンドルされた ripgrep を直接実行し、サンドボックス化された bash を経由しない。

4つのケースをまとめて見ると、共通の教訓が導き出せる:テストは実際のエントリパスを通らなければならない。

手動マウント、すべてをモックする、スナップショット更新を検収とみなす——これらはすべて「ユニットテストは全部グリーンなのに製品は壊れている」を可能にする。


テストの四層

リポジトリのテスト戦略は階層的であり、各層が下の層では捉えられない盲点を補います。

階層コマンド何を捕捉するか
ユニットテストpnpm run testvitest でパッケージ内テストを実行。境界・エラーパス・イベント順序・並行競合を優先
カバレッジゲートpnpm run test:coverageファイルごとに100%カバレッジ;未カバーの行は往々にして削除すべきデッドコード
実 API e2epnpm run test:e2e鍵付きで実際のプロバイダー API を呼び出す;鍵がなければ自動スキップし、keyless CI はグリーンを維持
スナップショットpnpm run test:snapshot / test:web鍵なしの期待出力が外部向けの動作をカバー;ブラウザスナップショットは Chromium のリプレイで比較

リポジトリは DeepSeek 自身のものなので、特別な原則があります:推論はここでは安価なので、実 API テストを惜しまない。

鍵なしのテストは基盤となる経路しか証明できません;鍵付きで実行して初めて、エージェントが実際のモデルと連携して正常に動作することを証明できます。

最も価値が高いのはスモークテストです:実際のサンプルを起動し、プロンプトを1つ送り、外部の世界を確認します。

それらは「ユニットテストが全てグリーンなのに製品が壊れている」という、mock では発見できない問題を捕捉できます。

行カバレッジは必要条件であり、決して十分条件ではありません。

それは行が実行されたことを証明しますが、機能が期待どおりに動作することを証明しません。

0001 のケースで100%カバレッジでもなお2つの統合バグを見逃したことが、最も良い注釈です。

もう一つの原則は外部の世界を検証せよ、自己報告ではなく。

e2e のアサーションはコマンドを再実行するか、外部からファイルを再読み取りすべきです;エージェント自身の出力に対するキーワード検出は、カンニングするエージェントを通過させてしまいます。

変更されていないことをアサートするファイルはバイト単位で一致するべきです。


ドキュメント規律:一つの事実には一つの居場所

リポジトリのドキュメントは書いて終わりではなく、「ドキュメントとソースコードの乖離」を防ぐ仕組みがあります。

verify-type-equivそれはゲートです:TypeScript パーサーを使ってソースコードから型宣言のシンボルと付随する JSDoc を抽出し、ドキュメントのコードブロックがその両方に一致することを検証します。

記録された型宣言またはその JSDoc を変更すると、ゲートは失敗し、貼り付けた内容を更新するまで通りません。

これにより、ドキュメント内の型定義とソースコードは常に一致し、「ドキュメントが古いバージョンを写している」という事態は起こりません。

もう一つの規律は一つの事実には一つの居場所:各事実は1つのファイルでのみ管理され、他のファイルはそれを参照します。

例えば、ツールスキーマの「真のソース」はadding-a-tool.md、他のページは参照するだけでコピーしません。

中国語と英語のドキュメントはバイリンガルペアで保守されています。更新時にはまず、pnpm run gen-doc-graphs英文の更新を実行し、その後中国語を更新してペアを検証します。

自分のプロジェクトにも同じことが当てはまります。「唯一の事実」を一箇所に置き、同じ設定を3つのドキュメントに散在させないでください。


ハンズオン例:30秒のエグゼクティブサマリーを書く

ふりかえりの各記事は、冒頭にエグゼクティブサマリーを置き、忙しい読者が30秒で要点を吸収できるようにしています。

サンプルプロジェクトで遭遇したAgentの障害について、一度ふりかえりをしてみてください。次のテンプレートに従って書きます:

# 复盘 0005:サンプル 演示环境的工具黑名单没有生效

## 摘要
demo 环境里模型仍能调用被禁用的 fs_write,直接写入了工作区。
根因是黑名单插件用 `tools/pre-execute` 返回了 `next()`,
而真正负责拦截的守卫注册在插件卸载之后——加载顺序错了。
逃逸原因是加载顺序没有测试覆盖,`cordis.yml` 只测了「能起来」。
新增防护:给黑名单插件补一条「顺序敏感」的装配测试,
并在 AGENTS.md 记录「pre-execute 与 guard 的注册顺序」规则。

30秒サマリーの公式:何が壊れたか → 根本原因を平易な言葉で述べる → なぜ見逃されたのか → 長期的に使える教訓。


シリーズの結び

これで、DeepSeek Harness入門チュートリアルの全28記事が終わりです。

この道のりを振り返ってみましょう。第1記事でdshの四大ガードレールを理解し、インストール、Web UI、Python SDKの使い方を学びました。最初のプラグインを書くところから、プラグインのライフサイクル、サービスとスコープ、イベントシステムの理解まで。三角色モードで能力を設計し、任意のLLMを接続し、パッケージ化してリリースするところまで。最後のこの5記事で、セキュリティとエンジニアリング文化という最後のピースが埋められました。

あなたが本当に持ち帰るものは、APIの使い方だけではなく、一つの考え方です:

モデルは賢さを担い、Harnessは信頼性を担います。制約は制限ではなく、Agentを予測可能、監査可能、リプレイ可能にするための基盤です。

すべてはプラグインです。ポリシーを拡張ポイントに置き、ループの中に書き込まないことで、システムは制御を失わずに進化できます。

実際のエントリーパスは、あらゆるモックに勝ります。カバレッジ、スナップショット、スモークテストはそれぞれ役割を担い、「オールグリーンなのに壊れている」状態を防ぎます。

障害は怖くありません。怖いのは原因がわからないことです。ふりかえりの文化が、一度の事故を一連の防御策に変えます。

その他の拡張