mcpField
A
apifox-cli

apifox-cli

github.com/apifox開発17579 回インストール16 週間前に更新
リポジトリ

apifox-cli について

apifox-cli は、Apifox CLI の利用手順をエージェントに案内するスキルです。コマンドやスキーマの確認から書き込み前の検証まで扱い、プロジェクト選択やブランチ権限、重要操作の確認事項も示します。

主な機能

  1. 01CLI 出力に基づくコマンドとスキーマ確認
  2. 02書き込み前のリソースデータ検証
  3. 03プロジェクトとブランチの選択案内
  4. 04トークンとローカル設定の保護
  5. 05破壊的操作前の確認

活用シーン

  1. 01Apifox リソース変更の準備と検証
  2. 02AI ブランチでの変更作業
  3. 03コマンドやスキーマエラーの対処

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/apifox/apifox-cli-skills --skill apifox-cli

インストール後、Claude Code で/apifox-cliを入力して読み込まれたか確認します。

詳細

Apifox CLI

Apifox CLI を使ってユーザーのリクエストを完了してください。記憶に頼って payload を組み立てず、まず CLI の --help、cli-schema、cli-schema validate、agentHints.nextSteps を使って次の手順を判断してください。

新しいセッションでの確認

  • Apifox CLI のタスクを初めて処理するときは、まず CLI が使用可能かを簡単に確認します：apifox --version、apifox --help。
  • apifox が存在しない場合、またはバージョンを出力できない場合は、先に CLI をインストールします：npm i -g apifox-cli@latest --registry=https://registry.npmmirror.com/。
  • インストール後、apifox login --with-token <TOKEN> を実行してログインします。API アクセストークンは、Apifox クライアントまたはウェブ版の「ユーザーアイコン → アカウント設定 → API アクセストークン」から作成できます。
  • 毎回、デフォルトでアップグレードしないでください。コマンドの実行結果からバージョンが古い、unknown command、パラメーター不足が旧バージョンに起因すると疑われる場合、またはユーザーのタスクで新機能が必要な場合に限り、アップグレードを提案してください。

基本的な使い方

apifox --help
apifox <command> --help
apifox <command> <subcommand> --help

よく使うグローバルパラメーター：

--project <projectId>     项目 ID
--branch <branchName>     分支名；纯数字值兼容旧 branchId
--access-token <token>    覆盖当前登录 token
--api-base-url <url>      私有部署地址

ログインとプロジェクト

  • 未ログインの場合、ユーザーに API アクセストークンを提供してもらい、次を実行します：apifox login --with-token <TOKEN>。
  • Apifox CLI の認証情報は ~/.apifox/config.toml に保存されます。トークンをログに出力したり、リポジトリにコミットしたり、通常のチャット要約に記載したりしないでください。
  • ユーザーがプロジェクトを指定していない場合は、まず現在のワークスペースに .apifox/settings.json があるか確認します。そこに普段使うデフォルトの projectId があれば、そのプロジェクトを優先して使用します。
  • プロジェクト ID は「プロジェクト設定 - 基本設定 - プロジェクト ID」から取得するようユーザーに案内できます。または、先に apifox project list を実行し、コマンドの実行対象となるプロジェクトをユーザーに確認してもらいます。
  • ローカルの設定ファイルに書き込む前に、必ずユーザーに確認してください。

書き込みの標準手順

必須：create または update コマンドを実行する前に、リソースの定義とデータ形式を完全に取得し、実行前に cli-schema validate で書き込み内容が正確であることを検証してください。具体的な手順は次のとおりです。

  1. 対応するリソース操作コマンドの JSON schema を確認します：apifox cli-schema get <schemaKey>
  2. リソースの JSON データファイルを生成します。
  3. 検証します：apifox cli-schema validate <schemaKey> --file <path>
  4. validate で問題がないことを確認してから、実際の create または update コマンドを実行します。

コマンドの実行結果が返されたら、JSON 出力内の agentHints.nextSteps を優先して読み取り、処理の続行または復旧に使用してください。

CLI の情報を優先

  • 具体的なコマンド、パラメーター、schema key は、現在の CLI の出力に従ってください：apifox <command> --help、apifox cli-schema list、agentHints.nextSteps。
  • このスキルと現在の CLI 出力が一致しない場合は、現在の CLI 出力に従って実行し、このスキル内の事実に関する記述も合わせて修正してください。

CLI の書き込み権限に関する宣言

  • 書き込みの実行が AI（CLI の実行元）の権限によって制限されており、ユーザーから指定がない場合は、ユーザーに代わって選択せず、まず書き込み方法を確認してください。対象ブランチでの直接編集権限を有効にするか、AI ブランチ上で対象ブランチのデータを編集するかを確認します。
  • メインブランチ、イテレーションブランチ、または汎用ブランチのデータを直接編集する必要がある場合は、Apifox クライアントのバージョン 2.8.32+ で「プロジェクト設定 - 機能設定 - AI 機能設定 - 外部 AI 編集権限」を開き、直接編集権限のスイッチを有効にするようユーザーに案内してください。
  • ユーザーが AI ブランチを選択した場合、手順は次のとおりです： step1：AI ブランチを作成し、ソースブランチを指定します； step2：実際の必要に応じて、ソースブランチのリソースをインポート（pick-to）します； step3：ユーザーの要望に従って AI ブランチを編集します； step4：完了後、マージリクエストを作成するか、マージするかをユーザーに確認してください。
  • CLI からマージ／マージリクエストを直接実行するには、ソースブランチと対象ブランチの両方で直接編集権限のスイッチが有効になっている必要があります。有効でない場合は、該当するブランチタイプの権限スイッチを先に有効にするか、クライアントから手動でマージを実行するようユーザーに案内してください。

AI ブランチについて

  • AI ブランチは、AI／自動化によるプロジェクトリソースの変更に使用する分離ブランチです。ソースブランチを直接変更してしまうことを防ぎます。
  • AI ブランチとソースブランチの間に差分がない状態が 24 時間続くと、自動的にアーカイブされます。
  • AI ブランチは初期状態では空であり、ソースブランチのリソースが自動的に clone されることはありません。ソースブランチにある既存のリソースを編集または削除する前に、AI ブランチにインポートしてください。
  • AI ブランチでリソースを新規作成する場合、事前のインポートは不要です。
  • AI ブランチでの変更はソースブランチに自動反映されません。完了後、すぐにマージするか、マージリクエストを作成するかを必ずユーザーに確認してください。
  • 対象のメインブランチが保護されている（isProtected）場合は、merge を直接実行せず、merge-request を優先してください。

必ずユーザーに確認する事項

  • ログイン token、ローカル設定への書き込み、プライベートデプロイのアドレス。
  • AI ブランチの作成／切り替え、ソースブランチのリソースの AI ブランチへのインポート。
  • 削除、アーカイブ、上書きインポート、一括更新などの破壊的な操作。
  • AI ブランチの変更をソースブランチに merge／merge-request すること。
  • CLI をアップグレードするかどうか。

障害からの復旧

現象対応
未ログインapifox login --with-token <TOKEN>
プロジェクトが不明apifox project list
コマンドのパラメーターが不明apifox <command> --help
パラメーターまたは schema のエラー先に cli-schema get／cli-schema validate を実行
AI の書き込みが制限されているAI ブランチ／権限スイッチについて説明し、ユーザーに選択してもらう
プライベートデプロイ--api-base-url https://your-server を追加

コメント

Markdown 対応