embedded-debug-loop

C/C++ の組み込み機器のデバッグを、利用者のルールに従ったビルド・デプロイ・実機ログの分析を PDS のループで繰り返して自律的に進めるプラグイン

できること

組み込み機器（C/C++）の不具合を、実機で調べて直すためのプラグインです。調査プロンプトと、機器の情報、ソースコードの場所、ルールを渡すと、AI がソースの調査と修正、ログの追加、ビルド、実機へのデプロイ、実機のログの分析を、成功条件を満たすまで繰り返します。最後に、結論、結果、各試行の PDS の表、変えたソースコードの差分が得られます。

embedded-debug-loop は、GitHub Copilot CLI のプラグインです。作業の設定・開始・監視・結果の確認は、ブラウザーの画面（Web管理画面）で行います。作業は、統括・作業・検証の3種類のエージェントが、計画 → 実行 → 評価 を繰り返して進めます。

使い方

初めて使う前に、下の「使うために要る準備」を1回行います。

チャットで頼む（K-03）

チャットに、調査プロンプトを書いて頼みます。目的、成功条件、守ってほしい制約を書くと、そのとおりに進みます。たとえば次のように書きます（ファイルの場所は、手元の作業フォルダのものに読み替えてください）。

inputs/src にあるC言語のセンサー値平均化のプログラムで、実機のシェルコンソールのログに出る平均値が期待値と違います。原因を調べて直してください。成功条件：実機のログに「AVG=25」と出ること。機器の情報は inputs/device.md、ログ追加・クロスコンパイル・デプロイのルールは inputs/rules/log.md、inputs/rules/build.md、inputs/rules/deploy.md にあります。制約：inputs/src/dbg_log.h は変更しないこと。

成功条件や材料が足りないときは、AI がチャットで質問します。質問に答えると、調査を始めます。

用意するもの

• C/C++ のソースコードのフォルダ（ローカル PC 上）。画面の「ローカルPC上のソースコードの場所」に入れます。
• 組み込み機器の情報（IP アドレス、接続方法、ログインや転送先など）。画面の「組み込み機器のIPアドレス」「組み込み機器のその他の情報」に入れます。
• クロスコンパイルに必要な情報（ツールチェーンや環境設定のファイルの場所など）。画面の「クロスコンパイルに必要な情報」に入れます。
• 3つのルール（スキル）：log-insertion-rules（ログ追加）、cross-compile-rules（クロスコンパイル）、deploy-rules（デプロイと実機のログの取り方）。初めは汎用のひな形が入っているので、対象の機器に合わせて書き換えます。書き換えのしかたは、docs/customize-rules.md にあります。
• 画面の設定：繰り返しの上限の回数と、各 AI（まとめ役、ソースコード担当、ビルド・デプロイ担当、確認役）のモデルとエフォートレベル。エフォートレベルは、作業の始めに各 AI の設定へ反映されます（K-17）。

できたものの場所

終わった後の画面で、「変えたソースコードの差分」と「改善用のログ」のファイルを開けます。実行中に取った実機のログも、画面から開けます。作業フォルダの場所は、画面に示されます。

頼んだ後は、ブラウザーの画面で進めます。

1. チャットに、Web管理画面の URL が示されます。URL には合言葉が入っています。ブラウザーで開きます。この URL は、embedded-debug-loop を動かしているマシンのブラウザーからだけ開けます。
2. 画面で、役割（統括・作業・検証）ごとに使うモデル、繰り返しの上限の回数、この作業だけの設定を決めて、開始ボタンを押します。Copilot CLI のモデルが Auto のときは、役割ごとのモデルが効かないことがあります。そのことと、実際に動いたモデルが画面に示されます。
3. 実行中は、画面で、各エージェントの状態と担当、今が計画・実行・評価のどれか、エージェント間のデータの受け渡しを見られます。止めるときは、止めるボタンを押します。
4. 終わったら、画面で、各エージェントの実行結果、検証結果、まとめ、終わった理由、課題の一覧を見られます。

使うために要る準備

次の3つを、最初に1回行います。

1. インストールする

このリポジトリのフォルダを、手元のマーケットプレイスとして登録してから、プラグインを入れます。

copilot plugin marketplace add <このリポジトリのフォルダの場所>
copilot plugin install embedded-debug-loop@embedded-debug-loop

• <このリポジトリのフォルダの場所> には、このフォルダの絶対パスを書きます。
• Copilot CLI の中では、/plugin marketplace add <フォルダの場所> と /plugin install embedded-debug-loop@embedded-debug-loop でも入れられます。
• フォルダを直接指定する入れ方（copilot plugin install ./フォルダ）は、Copilot CLI 1.0.102 が「廃止予定」と表示するので、マーケットプレイスを通す入れ方にしています。
• 手元のフォルダのマーケットプレイスから入れたプラグインは、フォルダの中身を直したあと、/restart か新しいセッション（Copilot CLI の1つの会話。/clear で新しいセッションになります）で反映されます。

2. 試験的機能を有効にする

画面を動かす仕組み（エクステンション。Copilot CLI が起動する別のプログラム）は、試験的な機能です（Copilot CLI 1.0.102 の時点）。有効にしないと、embedded-debug-loop は使えません。試験的な機能なので、Copilot CLI の更新で使い方が変わることがあります。

初めて使うときは、--experimental を付けて Copilot CLI を起動します。一度付けると設定に残るので、次からは付けなくても有効です。

copilot --experimental

すでに起動しているときは、チャットで次のように打ちます。Copilot CLI が自動で再起動して、有効になります。再起動すると、今の会話は終わります。再起動の後は、まだ信頼していないフォルダでは、フォルダを信頼するかの確認が出て、続けて次の「3. 読み込むときの確認を許可する」の確認が出ます（読み込みの確認は、続けて2回出ることがあります）。

/settings experimental on

3. 読み込むときの確認を許可する

embedded-debug-loop を読み込むとき、Copilot CLI がチャットに確認を出します。題は Extension "plugin:embedded-debug-loop:embedded-debug-loop" wants elevated permissions で、本文は次のとおりです。

This extension wants to: skip tool permission prompts, register hooks, handle permission requests.
Denying will prevent this extension from loading.

Copilot CLI 1.0.101 から、この確認は必ずあなたに出ます。許可を自動で判定する設定（Assisted の許可）を使っていても、自動では許可されません。

確認の意味は次のとおりです。

• skip tool permission prompts（ツールの許可の確認を省く）：embedded-debug-loop の記録のツールは、確認なしで動きます。画面に出す状態を書くだけで、ファイルやコマンドなど外を変えません。
• register hooks（フックを登録する）：止めた実行のエージェントのツールと、統括エージェントに許していないツール（ファイルの書き込みやコマンドなど。統括は、それらを作業エージェントに頼みます）を拒むために、Copilot CLI の「ツールを使ってよいか」の問い合わせを受けます。
• handle permission requests（許可の求めを扱う）：エージェントの許可の求めを見て、画面に「チャットで確認を待っています」と示します。embedded-debug-loop は許可の求めに答えません。許可も拒否も、あなたがチャットで行います。

許可する理由は、断ると読み込まれず、画面で開始も監視もできないからです。選び方は次のとおりです。

初めて使うときと、/settings experimental on で再起動した後は、フォルダを信頼するかの確認の後に、この確認が続けて2回出ることがあります。

実行中に気をつけること

• 実行中は /clear を使わないでください。/clear をすると、画面の更新が止まり、前の画面の URL では開けなくなります。そのときは、チャットでもう一度作業を頼み、示された画面を開くと、前の実行が途中で切れたことが示されます。
• 実行中の確認には、チャットで答えます。ファイルの書き込みやコマンドの実行の許可、AI クレジットの上限の確認、エージェントからの質問が、チャットに出ます。画面には、チャットで確認を待っていることと、何の確認かが示されます。画面からは答えられません。
• 止めた後、チャットに確認が残っていることがあります。その確認には、「Yes」と答えても「No」と答えても、ツールは動きません。
• 止めきれなかったエージェントがいるときは、画面にそのエージェントと止め方（チャットで Esc を2回押す、または Copilot CLI を終える）が示されます。

任せたいツールを前もって許可する

確認のたびにチャットに戻る手間を減らすには、Copilot CLI を起動するときに、任せたいツールを --allow-tool で指定します。指定は、その起動の間だけ有効です。

すべてを任せる指定（--allow-all-tools、--allow-all、--yolo）もあります。公式のドキュメントは、隔離した環境でだけ使うよう強く勧めています。

うまく始まらないとき

チャットで作業を頼んでも画面の URL が示されないときは、embedded-debug-loop のエクステンションが読み込まれていません。次のどれかです。

• 試験的機能を有効にしていない：copilot --experimental で起動し直します。すでに起動しているときは、チャットで /settings experimental on と打ちます（自動で再起動します）。
• 読み込むときの確認を断った：Copilot CLI を起動し直して、出た確認を許可します。選び方は「3. 読み込むときの確認を許可する」にあります。
• エクステンションを使わない設定（/extensions mode の Disabled）にしている：/extensions mode で Load & Augment か Load Only に戻します。Disabled は、次に Copilot CLI を起動したときにも残ります。

課題の一覧と Issue の起票

終わった後の画面に、課題の一覧と、embedded-debug-loop 自身を改善するための Issue の案が並びます。案ごとの承認ボタンを押すと、その案が embedded-debug-loop 自身の GitHub リポジトリに Issue として起票されます。承認していない案は起票されません。

起票できるようにするには、次の手順を行います。起票できないときも案は並び、この手順が画面に示されます。

1. embedded-debug-loop を GitHub に公開します。

2. plugin.json の repository に、そのリポジトリの URL（例：https://github.com/OWNER/REPO）を書きます。そのあと、手元のフォルダのマーケットプレイスからインストールしたときは、Copilot CLI を終了して起動し直すか、/clear で新しい会話を始めます。GitHub からインストールしたときは、直した plugin.json を GitHub に送り、次のコマンドで embedded-debug-loop をアンインストールしてから、もう一度インストールします。

   copilot plugin uninstall embedded-debug-loop
   copilot plugin install embedded-debug-loop@embedded-debug-loop
   

3. gh（GitHub の公式のコマンド）を入れて、ログインします。

   gh auth login
   

試験

構造の検査と部品の試験は、リポジトリの1つのコマンドで動かせます。モデルを使わないので、AI クレジットを使いません。plugin-creator を入れていなくても動きます。

python3 tests/run.py

• 最初に、試験に要る道具がそろっているかを確かめ、足りなければ足りない道具を示して止まります。
• 段階ごとの合否と、不合格の試験とその理由が出ます。同じ内容がファイルにも書かれ、終了コードでも合否が分かります。
• embedded-debug-loop を直した後も、同じコマンドで試験をやり直せます。

EVAL（実際のモデルで課題を実行して採点する試験）は、plugin-creator を入れた Copilot CLI で、embedded-debug-loop の試験を頼むと行われます。tests/eval/ の課題と合否の基準を使います。AI クレジットを使うので、始める前に、実行の回数と使う AI クレジットの見込みが示されます。よいと答えてから始まります。