DEV Community

Cover image for Apidog CLIのDeepSeek Harnessでの使い方
Akira
Akira

Posted on Originally published at apidog.com

Apidog CLIのDeepSeek Harnessでの使い方

DeepSeek Harnessは、ワークスペースを読み込み、ファイルを編集し、bashツールでコマンドを実行し、その出力から次のアクションを決めるループです。しかし、APIテストがGUIのApidogに閉じていると、エージェントはテストを実行できません。誰かが手動でクリックするまで、APIの検証はループの外に残ります。

今すぐApidogを試す

解決策は、DeepSeek Harnessの命令ファイルにApidog CLIの実行方法を登録することです。Apidog CLIはnpmパッケージ apidog-cli として提供され、Apidogで作成したテストシナリオをターミナルから実行できます。

CLIをインストールし、DeepSeek Harnessがその存在と実行コマンドを認識できるようにすると、エージェントはユニットテストと同じようにApidogシナリオを実行できます。

  1. コマンドを実行する
  2. 終了コードを確認する
  3. 失敗した場合はレポートを読む
  4. コードを修正して再実行する

APIの動作を毎回コードから推測するよりも、1つのコマンドで検証結果を取得するほうが効率的です。CLIは「APIは正しいか？」という問いを終了コードとレポートに変換し、エージェントはその分のコンテキストを修正作業に使えます。

このガイドでは、一般的なインストール手順では扱われにくいDeepSeek Harness固有の設定を説明します。

  • DeepSeek Harnessが読み込む命令ファイル
  • bashツールから apidog run を実行する方法
  • テスト結果と終了コードを確認する方法
  • 実際にテストが実行されたか検証する方法

CLIをまだインストールしていない場合は、先にAIコーディングエージェントでApidog CLIをインストールする方法を確認してください。npmインストール、認証、初回実行を説明しています。

この記事では、apidog --version がバージョン番号を表示し、使用するPCが認証済みであることを前提にします。

ここで言及するDeepSeek Harnessについて

コマンドラインでは dsh として知られるDeepSeek Harnessは、2026年8月13日にDeepSeekがV4-ProとともにAPIでリリースしたオープンソースのエージェントハーネスです。

MITライセンスで公開されており、github.com/deepseek-ai/deepseek-harnessで確認できます。npx @deepseek-ai/dsh web で起動すると、http://127.0.0.1:3080 にローカルWeb UIが提供されます。

Web UIでワークスペース、つまり起動時に選択したプロジェクトディレクトリを指定すると、エージェントはそのディレクトリ内で次の操作を実行できます。

  • ファイルの読み書き
  • コマンドの実行
  • アクティブなパーミッションポリシーで承認が必要な操作の確認

ここで重要なのは、DeepSeek Harnessが開発者プレビューであることです。READMEでは、互換性を損なう変更が発生する可能性が警告されています。この記事で扱うファイル名や設定キーは2026年8月後半時点のものとして扱い、動作しない場合はリポジトリのドキュメントと照合してください。

また、dshの機能はCordisアーキテクチャに基づくプラグインとして構成されています。そのため、実際に設定するときは次の点を確認することが重要です。

  • プロジェクトルールを読み込むプラグインは何か
  • どのファイル名が読み込まれるか
  • bashツールがどのような実行環境を使うか

詳細はDeepSeek Harnessとは何かを参照してください。既存ツールとの比較については、DeepSeek Harness vs Claude Codeで説明しています。

ステップ1: AGENTS.md にCLIの実行ルールを追加する

DeepSeek Harnessは、@deepseek-ai/dsh-agent-instructions プラグインを通じてワークスペースの命令を読み込みます。

設定カタログによると、ローダーはセッションの作業ディレクトリから、.git で識別されるプロジェクトルートまで上位ディレクトリを辿ります。そして、各ディレクトリで次のファイルを探します。

  1. AGENTS.md
  2. CLAUDE.md（AGENTS.md がない場合のフォールバック）
  3. AGENTS.local.md または CLAUDE.local.md（ローカルオーバーレイ）

さらに、$DSH_HOME（デフォルトは ~/.dsh）にあるユーザーグローバルの AGENTS.md もプロジェクト全体に適用されます。1MiBを超えるファイルは無視されますが、通常のルールファイルがこのサイズに達することはほとんどありません。

プロジェクトルートの AGENTS.md に、次のブロックを追加します。

## API testing with the Apidog CLI

- To test the API, run the Apidog scenario. Do not click through the GUI.
- Command: apidog run -t <scenario_id> -e <env_id> -r cli
- Exit code 0 means every assertion passed. Non-zero means a failure; read the report and fix the code.
- The machine is already authenticated. Never add an --access-token flag and never put a token in this file.
Enter fullscreen mode Exit fullscreen mode

この設定をチャットではなくルールファイルに保存する理由は、次のとおりです。

  • セッションごとに同じ指示を入力する必要がない
  • リポジトリをクローンしたチームメンバーにも適用できる
  • エージェントがシナリオIDを推測しなくて済む
  • 新しいセッションでも同じ検証フローを再利用できる

複数プロジェクトで共通の習慣を使う場合は、~/.dsh/AGENTS.md に次のようなルールを置けます。

APIの変更は、必ずプロジェクトに登録された apidog run コマンドで検証する。

一方、実際のシナリオIDや環境IDは、各リポジトリの AGENTS.md に記述します。

ステップ2: Apidogから実行コマンドを取得する

シナリオIDと環境IDを手入力で推測する必要はありません。Apidogで次の操作を行います。

  1. テストシナリオを開く
  2. CI/CD タブに移動する
  3. 生成されたコマンドをコピーする
  4. AGENTS.md のコマンドに貼り付ける

生成されるコマンドは、たとえば次の形式です。

apidog run -t 123456 -e 789012 -r cli
Enter fullscreen mode Exit fullscreen mode

各オプションの意味は次のとおりです。

  • -t: テストシナリオID
  • -e: 実行対象の環境ID
  • -r cli: 結果をインライン表示するCLIレポーター

-t と -e には、ApidogのCI/CDタブに表示された実際の値を使用してください。

AGENTS.md には、次のように具体的なIDを設定します。

## API testing with the Apidog CLI

- Run this command after changing API behavior:
  apidog run -t 123456 -e 789012 -r cli
- Exit code 0 means success. A non-zero exit code means failure.
- Read the CLI report, fix the implementation, and run the command again.
Enter fullscreen mode Exit fullscreen mode

ステップ3: エージェントにテストを実行させる

ワークスペースを選択した状態で、dsh Web UIからセッションを開始します。

命令ローダーが AGENTS.md をエージェントのコンテキストに追加しているため、API変更を行ったあと、次のように依頼できます。

Apidogテストシナリオを実行して、終了コードと失敗したアサーションを教えてください。
Enter fullscreen mode Exit fullscreen mode

エージェントはbashツールを通じて、AGENTS.md に記載した apidog run コマンドを実行します。

bashツールの作業ディレクトリに注意する

ツールカタログによると、デフォルトのbashツールは各コマンドを新しいシェルで実行します。

そのため、次の状態は呼び出し間で保持されません。

  • カレントディレクトリ
  • 環境変数
  • シェル関数

workdir が渡されない場合、コマンドはセッションのワークスペースから実行されます。

したがって、次のような2段階の実行は期待どおりに動作しない可能性があります。

cd api
Enter fullscreen mode Exit fullscreen mode

続けて別の呼び出しで、

apidog run -t 123456 -e 789012 -r cli
Enter fullscreen mode Exit fullscreen mode

を実行しても、cd api の結果は保持されません。

サブディレクトリから実行する必要がある場合は、AGENTS.md に完全なコマンドを1行で記述します。

cd api && apidog run -t 123456 -e 789012 -r cli
Enter fullscreen mode Exit fullscreen mode

終了コードとサンドボックス

ゼロ以外の終了コードは、明示的な [exit code: N] マーカーとして返されます。出力が長く、末尾が切り詰められた場合でも、合否を判断するためのシグナルを確認できます。

また、コマンドはファイルサンドボックス下で実行される場合があります。ブロックされた操作は通常のコマンド失敗ではなく、ポリシー拒否として報告されます。

読み取り中心のテスト実行では問題になりにくいものの、HTMLレポーターが ./apidog-reports にファイルを書き込む場合は、アクティブなポリシーによって実行が拒否される可能性があります。

初回実行時の承認

実行時にクリックや承認が必要かどうかは、パーミッションポリシーによって決まります。

ユーザーガイドによると、Web UIはポリシー上で承認が必要な操作の前に確認を表示します。

apidog run の実行確認が表示されたら、内容を確認して承認してください。ステージング環境に対するテストシナリオは、通常、読み取り中心の検証コマンドです。ただし、対象環境やシナリオの内容は事前に確認してください。

ステップ4: レポートを読む

実行結果が失敗になった場合は、CLIレポートを確認します。

-r cli を指定すると、エージェントは次の情報をインラインで取得できます。

  • 実行されたリクエスト
  • 各アサーション
  • 期待値
  • 実際の値
  • 失敗したステータスコードやフィールド

たとえば、次のような問題を直接特定できます。

  • 期待値が200なのに500が返っている
  • total フィールドがレスポンスに存在しない
  • 通貨コードが想定と異なる

ブラウザで開いたり、チームメンバーに共有したりするレポートが必要な場合は、HTMLレポーターを追加します。

apidog run -t 123456 -e 789012 -r cli,html
Enter fullscreen mode Exit fullscreen mode

html レポーターは、自己完結型のレポートを ./apidog-reports に書き込みます。

エージェントがその場で結果を判断できるように、レポーターの一覧には cli も残してください。

エンドツーエンドの編集・テスト・修正ループ

たとえば、エージェントがチェックアウトAPIのハンドラーを編集しているとします。

CLIがない場合、エージェントのループは次のように終わる可能性があります。

コードは正しそうです。

AGENTS.md にApidog CLIのルールを追加すると、ループは次のように変わります。

  1. エージェントがハンドラーを編集する
  2. apidog run -t 123456 -e 789012 -r cli を実行する
  3. 終了コードを確認する
  4. CLIレポートを読む
  5. 失敗していればコードを修正する
  6. 同じコマンドを再実行する

成功時は終了コード0です。失敗時は、たとえば次のような情報を読み取ります。

  • [exit code: 1]
  • 200を期待している箇所で500が返った
  • total フィールドが欠落している
  • 通貨コードが誤っている

これにより、API契約の検証が、ユニットテストと同じ編集・テスト・修正サイクルに組み込まれます。

この方法では、エージェントがAPIの動作を確認するために、すべてのルートファイルを再読する必要がありません。期待される動作は、Apidogで作成したシナリオにすでに定義されています。

役割分担は明確です。

  • dsh: コードを編集する
  • Apidog CLI: APIレイヤーを検証する
  • Apidog: テストシナリオを視覚的に作成する

エージェントは、検証を決定論的なCLIに委任し、修正が必要な部分の判断にコンテキストを使えます。

dshが実際にテストを実行したことを確認する

エージェントが、実際には実行していない処理を完了したように報告することがあります。特に開発者プレビューのハーネスでは、エージェントの要約だけを信頼せず、次の3段階で確認してください。

1. bash呼び出しを確認する

dsh Web UIには、セッション中のツール呼び出しと出力が表示されます。

次のような文字列を含むbash呼び出しを探してください。

apidog run -t 123456 -e 789012 -r cli
Enter fullscreen mode Exit fullscreen mode

エージェントが「テストを実行した」と説明しているのに、該当するbash呼び出しが表示されない場合、実際には実行せずに結果を要約した可能性があります。

その場合は、次のように依頼してください。

テストを実行し、apidog runの生の出力を表示してください。
Enter fullscreen mode Exit fullscreen mode

2. 終了コードを確認する

次のように直接質問します。

そのapidog runコマンドの終了コードは何でしたか？
Enter fullscreen mode Exit fullscreen mode

失敗時には、ハーネスから明示的な [exit code: N] マーカーが返されます。

エージェントの要約が「テストは合格した」と述べていても、マーカーがゼロ以外なら、マーカーの内容を優先してください。

3. シナリオIDと環境IDを確認する

「シナリオが見つかりません」というエラーが出た場合、エージェントがIDを捏造した、または誤って記憶している可能性があります。

次の2か所で -t と -e の値を比較してください。

  • リポジトリの AGENTS.md
  • ApidogのCI/CDタブ

ルールファイルに記載されたIDと、Apidogが生成したコマンドが基準です。エージェントが入力した別のIDは推測として扱ってください。

オプション: 仕様アクセス用にApidog MCPサーバーを追加する

シナリオの実行は、実装後の検証を担当します。コードを書く前にエージェントへAPI仕様を読ませたい場合は、MCPを使う方法があります。

ただし、2026年8月後半時点では、MCPサポートはDeepSeek HarnessのコアREADMEやユーザーガイドに正式には文書化されていません。

現時点で利用できるのは、エコシステムの他のプラグインと同様、dsh-plugin GitHubトピックから見つかるコミュニティプラグイン hyqhyq3/dsh-mcp-manager です。

このプラグインは、次の機能を提供します。

  • 設定にMCPページを追加
  • リモートHTTPサーバーとローカルstdioサーバーをサポート
  • ツールを mcp__<name>__* として登録
  • <workspace>/.dsh/dshmm/mcp.json からプロジェクトごとのサーバー定義を読み込む

これを使ってApidog MCPサーバーに接続できます。

Apidog MCPサーバーを使うと、エージェントはMCP経由でAPI仕様を参照できます。シナリオが失敗してから修正するのではなく、ハンドラーを書く前に実際のエンドポイントスキーマを確認できる点がメリットです。

ただし、コミュニティプラグインと開発者プレビューのホストを組み合わせる構成は、どちらか一方の更新で動作しなくなる可能性があります。したがって、MCPは追加レイヤーとして扱ってください。

主要な検証経路は、あくまで次のCLI構成です。

apidog run -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

この方法なら、シェル以外の追加コンポーネントは必要ありません。

プレビューに関する注意点と今後の展望

DeepSeek Harnessは急速に進化しており、互換性を損なう変更が発生する可能性があります。特に変更されやすいのは、次のような詳細です。

  • 命令プラグインが読み込むファイル候補
  • bashツールのサンドボックスとレポート形式
  • コミュニティMCPプラグインの設定方法

一方で、「このコマンドでAPIを検証する」とルールファイルに記述し、CLIが明確な終了コードを返すというパターン自体は移植しやすい構成です。

Claude Codeなど、他のエージェントハーネスでも同じ考え方を使えます。エージェントはコマンド出力を読み取るのが得意であり、決定論的なテスト結果があれば、検証を推測に頼らずに済むからです。

実際に試す場合は、次の手順で進めます。

  1. Apidogをダウンロードする
  2. Apidogでテストシナリオを1つ作成する
  3. CI/CDタブから apidog run コマンドをコピーする
  4. リポジトリの AGENTS.md にコマンドを追加する
  5. DeepSeek HarnessでAPIコードを変更する
  6. エージェントにシナリオを実行させる
  7. 終了コードとアサーションを確認する

次にDeepSeek HarnessがAPIコードを変更するとき、エージェントは作業完了を報告する前に、Apidogシナリオで自分の変更を検証できます。

よくある質問

DeepSeek HarnessはAGENTS.mdをネイティブに読み込みますか？

はい。@deepseek-ai/dsh-agent-instructions プラグインは、プロジェクトルートおよびセッションの作業ディレクトリより上位のディレクトリから AGENTS.md を読み込みます。

AGENTS.md がない場合は CLAUDE.md にフォールバックします。また、次のファイルも読み込まれます。

  • AGENTS.local.md
  • CLAUDE.local.md
  • ~/.dsh/AGENTS.md

すでに他のエージェント向けに AGENTS.md を管理している場合、dshはそのファイルを変更せずに読み込みます。

dshでApidog CLIを使用するためにDeepSeekの有料プランは必要ですか？

いいえ。DeepSeek HarnessはMITライセンスのオープンソースで、使用するモデルは自分で用意します。

カタログプロバイダーはAnthropic、OpenAI、Bedrock、Vertex、Azureをカバーしています。カスタムゲートウェイは、DeepSeek Harnessで任意のモデルを実行する方法で説明されているように、settings.yaml を通じて設定できます。

Apidog CLIは無料のnpmパッケージです。特定のモデルではなく、Apidogのテストシナリオと認証済みの実行環境が必要です。

エージェントの2番目のコマンドが、最初のコマンドで移動したディレクトリを忘れるのはなぜですか？

デフォルトのdsh bashツールは、呼び出しごとに新しいシェルでコマンドを実行するためです。cd の結果は、次のコマンドには引き継がれません。

対策は2つあります。

  • ツールの workdir パラメーターを指定する
  • cd と apidog run を1つのコマンドにまとめる 
cd api && apidog run -t 123456 -e 789012 -r cli
Enter fullscreen mode Exit fullscreen mode

dshは毎回確認せずにシナリオを実行できますか？

アクティブなパーミッションポリシーによって異なります。

Web UIは、そのポリシーで承認が必要な操作の前に確認を表示します。ユーザーガイドにはポリシーレベルの詳細が列挙されていないため、使用中のビルド設定を確認してください。

プロンプトが表示された場合は、実行対象と環境を確認したうえで、ステージング環境に対する apidog run を承認します。

Top comments (0)