(代替: 開発用には `claude --plugin-dir /path/to/kunglao-agent` を使用します。)

### 2. ワークスペースの初期化```
/kunglao-agent:init ~/cases/synth-dropper --type windows

独立したレビュアーが結果を判断できるようにブリーフを書きます: **分析目標**(何を知る必要があるか)、**検証ロジック**(何が回答を信頼できるものにするか — 例:「署名は同じ入力から再現可能でなければならない」)、**制約**(例:「ホスト上で実行しない」)。すべては `task_spec.yaml` に記録され、そこからループが自らを駆動します。一般的な要求がどのように適切に形成された記述になるかについては、[タスクの記述方法](#how-to-state-the-task)を参照してください。

### 4. 成果物を読む```
claim-register.yaml   # every claim terminal, with verifier sign-off
facts/F<NNN>.md       # byte-anchored, reproducible, frontmatter contract
evidence/_index.json  # every fact → raw artifact (sha256 + path)
runs/                 # session audit trail

**Oracle の基準:** すべてのペア（保留されたものを含む）におけるバイト単位で完全な再現 — そして単独で実行される再現。

### 「我要解密」 — 「復号したい」

**通常、2つの異なるターゲットのいずれかを意味する — どちらかを明示すること:**

- **(a) キャプチャした1つのボディを復号する** — このデータに関する単発の回答:「このキャプチャしたキャッシュファイルの平文を生成せよ。」
- **(b) 復号機能** — アルゴリズム + 鍵復元。明日キャプチャするデータに対して再利用可能。

適切に形成された (a):```
> Sample: the v7.2 APK; behavior: the local config cache
>   files/.cfg/v2.dat is encrypted at rest.
> Criterion: produce the plaintext of the captured v2.dat and validate
>   it against what the app renders (field names and values match the
>   screenshot captured alongside).

**Oracle の基準:** (a) 平文がアプリのレンダリング結果と一致して検証されること、(b) アルゴリズムと鍵が特定され、カナリアのラウンドトリップがデバイス生成の暗号文とバイト単位で同一であること。「一度復号できた」ではどちらも満たさない。

### 「帮我分析这个协议」 — 「このプロトコルを分析して」

**通常の意味:** ワイヤフォーマットの復元 — フレーミング、フィールドの意味論、そして実行可能なコーデック。```
> Sample: the Android chat app; behavior: the TCP protocol on
>   gateway.example.com:443, as captured in gateway-session.pcap.
> Criterion: a codec that round-trips every captured frame byte-exact,
>   and decodes the held-out frame to fields matching the observed app
>   behavior.
> Attach: captures/gateway-session.pcap — 40 frames, plus 1 held-out
>   frame kept out of the analysis.

**Oracle のアンカー:** 名前付きのクラス/メソッド/ネイティブ関数、およびその時点でキャプチャした値を再現するフック。

### これらに共通するもの

- **サンプルと挙動を名指しする** — カテゴリではなく、どのパラメータ、エントリ、フローか。「我要纯算」はカテゴリであり、「api.example.com/v2/* の `sign` ヘッダを生成する署名器」はターゲットである。
- **成功はデータでなければならない。** キャプチャした入力/出力ペアを添付する。伏せられたペアこそがチェックを誠実にする — 再現は決して見なかったデータに過剰適合できない。
- **Oracle はあなたが述べた最終状態から導出される。** 曖昧な記述、曖昧な検証、漂流する分析。
- **制約は計画を変える。** 静的のみ? デバイスが利用可能? どのチャネル? 最初に明言すること — それが作業開始前にルートを決める([Bring your own environment](#bring-your-own-environment) を参照)。

## サブコマンド

| コマンド | 使用する場面 | 何をするか |
|---|---|---|
| `/kunglao-agent:init <workspace> [--type windows\|linux\|android\|web\|macos] [--lane malware\|algorithm\|protocol\|web\|data\|app]` | エンゲージメントの開始時、最初に | ワークスペースをスキャフォールドし、タイプに応じてツールチェーンをプローブし、`CLAUDE.md` と `.mcp.json` を書き込む。必須ツールが欠けている場合は修正ガイダンスとともに HARD 拒否する |
| `/kunglao-agent:analysis <workspace>` (エイリアス `analyze`) | init の後 — タスクを述べて開始する | 目標 / 検証ロジック / 制約を一度だけ収集し、その後収束ループを実行する: レポートまで dispatch / verify サイクルを繰り返す |
| `/kunglao-agent:resume <workspace>` | クラッシュ、再起動、または「どこまでやったっけ?」の後 | 読み取り専用のブレークポイント概要(ヘルス、未解決のクレーム、実行中のワーカー、クラッシュタイムライン)と、状態機械からの次のアクション |
| `/kunglao-agent:upgrade <workspace> [--dry-run]` | プラグイン更新後、古いワークスペースで(またはアップグレードプロンプトがスタンプの遅れを告げたとき) | ワークスペースのスキャフォールド(フック、テンプレート、イベント語彙)を現在のプラグインバージョンに移行する。`--dry-run` はプレビュー。ユーザーデータ(クレーム、ファクト、エビデンス)は決して触れられない — バイトドリフトは RC=4 で拒否する |
| `/kunglao-agent:help` | それ以外すべて | 使用法一覧を出力する |

典型的な順序: `init` がワークスペースを作成 → `analysis` がタスクを述べて開始 → (何かおかしくなれば `resume`) → 収束時にレポートを読む → プラグイン更新後に古いワークスペースを `upgrade`。

## 実行の様子

*エンゲージメントの形 — 何を入力し、何が返り、どこを見るか。* 合成例: 小さな Windows ドロッパーが `~/cases/synth-dropper` に着地する:```bash
/kunglao-agent:init ~/cases/synth-dropper --type windows   # probes Ghidra, VM reachability
/kunglao-agent:analysis ~/cases/synth-dropper
> "What does this binary do, and where does it phone home?"

## 長期的な自律性

実際のエンゲージメントは20分のチャットではありません。kunglao-agentは、人間がすべてのステップを導かなくても問題に取り組み続けます：

- **数時間から数日間、無人で実行** — スケジュールされたハートビートが訪問の合間もループを動かし続け、停止したループは黙って死ぬのではなくフラグが立てられます。
- **障害から回復** — 死んだワーカーやスタックしたワーカーは交換され、その質問は再キューイングされます。ブロックされた作業はアイドル状態になるのではなく自己回復します。
- **クラッシュや再起動を乗り越える** — `/kunglao-agent:resume <workspace>` がディスク上の状態から状況を再構築し、次のアクションを明示します。
- **チャットではなくディスクに記憶** — クレーム、ファクト、エビデンス、完全な監査証跡がワークスペースに存在するため、どのセッションでもエンゲージメントを再開できます。

ターゲットと質問を与えれば、数時間から数日間その問題に取り組み、障害から回復し、収束した時点で判定を読むことができます。

## 良い結果を得るために

- **静的アクセス可能なターゲットを投入する。** ループは静的優先です。アンパックされたAPK、難読化されていないバンドル、ストリップされていないバイナリは、動的作業を強いられるものよりもはるかに速く収束します。
- **必要になる前に動的レッグをセットアップする。** 主要な質問に実行が必要な場合は、まずチャネルを選択してください（[Bring your own environment](#bring-your-own-environment) を参照） — initは`local`上の動的タスクをHARD拒否します。
- **「動作中」と「スタック」の見分け方** — `runs/`内の新しいエントリはループが生きていることを意味します。ハートビートが死んでいる、または新しいファクトなしに同じ決定が繰り返される場合は生きていません — `/kunglao-agent:resume <workspace>` が診断し、次の動きを明示します。

## ターゲット別ツールチェーン

init時に選択する`--type`が、どのHARDティアのツールをインストールしなければならないかを固定します。ガイダンスは折りたたまれています — ターゲットを展開してください。**すべてのタイプで2つのMCPサーバーが必要です：** `ghidra`（`claude mcp add ghidra -- <path>/bridge-mcp-ghidra.exe`）と`sequential-thinking`（`claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking`）。

<details>
<summary><strong>windows (PE32+ x86-64)</strong> — ネイティブWindowsバイナリ</summary>

| Tier | Tool | Install |
|---|---|---|
| HARD | `pefile` (Python) | `pip install pefile` |
| HARD | `die` (Detect It Easy) | `KUNGLAO_DIE` env または PATH 上 — [ntinfo.com](https://ntinfo.com) |
| HARD | `floss` (FLARE FLOSS) | [flare-floss docs](https://github.com/mandiant/flare-floss) に従う |
| HARD | Ghidra または IDA | いずれか一方；[Internals](#internals) を参照 |
| HARD (T2/T3) | VMware + vmr-shell、または ssh/docker チャネル | [Bring your own environment](#bring-your-own-environment) を参照 |
| HARD (T2/T3) | `frida-server`（リネーム済み、カスタムポート） | デバイス/VM側バイナリ、デフォルトポート1337 |

Windows T3動的は`x64dbg` MCPも使用します；`volatility`（メモリフォレンジック）とIDA-Pro MCPはオプションです — [Internals](#internals) のMCPマニフェストを参照してください。

</details>

<details>
<summary><strong>linux (ELF)</strong> — ネイティブLinuxバイナリ / ファームウェア / メモリイメージ</summary>

| Tier | Tool | Install |
|---|---|---|
| HARD | `file`, `readelf`, `objdump` | `binutils` パッケージ |
| HARD | Ghidra または IDA | いずれか一方 |
| HARD (T2/T3) | VMware + vmr-shell、または ssh/docker コントロールプレーン | [Bring your own environment](#bring-your-own-environment) を参照 |
| HARD (T2/T3) | `frida-server`（リネーム済み、カスタムポート） | デバイス側バイナリ、ポート1337 |
| WARN | `gdbserver`（ホスト側PATH）、`strace`、`ltrace` | オプションの追加ツール |

`ssh-mcp`はリモート / クラウド / dockerホスト用のsshコントロールプレーンを有効にします。

</details>

<details>
<summary><strong>android (APK / DEX / native .so)</strong> — 最も難しいターゲットタイプ、HARD項目が最多</summary>

| Tier | Tool | Install |
|---|---|---|
| HARD | `aapt` または `aapt2`（または `unzip` フォールバック） | Android SDK build-tools |
| HARD | `jadx` (DEX → Java デコンパイラ) | [skylot/jadx](https://github.com/skylot/jadx) |
| HARD | `apktool` (APK リソースのデコード/再ビルド) | [iBotPeaches/Apktool](https://github.com/iBotPeaches/Apktool) |
| HARD | `gitnexus` (デコンパイル後のグラフ) | `npm i -g gitnexus` |
| HARD | Ghidra または IDA | APKにネイティブ`.so`が含まれる場合のみ |
| HARD | `adb` + `ro.debuggable=1` の **root化されたデバイス** | platform-tools + デバイス上のカスタムfrida |
| HARD | `frida-server`（リネーム済み、カスタムポート1337） | デバイス側バイナリ |
| HARD | `android_server` (IDA リモートデバッグ) | デバイス側バイナリ、ポート23946 |
| WARN | `apkid` | `pip install apkid` |
| WARN | `baksmali` | [smali releases](https://github.com/baksmali/smali/releases) から |

</details>

<details>
<summary><strong>web &amp; macos (ベータ)</strong> — 最小限のツールチェーン、設計上HARD項目なし</summary>

| Tier | Tool | Install |
|---|---|---|
| WARN | `camoufox-reverse` MCP (web) | フック / トレース / ネットワークキャプチャ用のアンチ検出Firefox |
| WARN | `docker` (web チャネルのデフォルト) | Docker Desktop、または`KUNGLAO_CHANNEL=ssh`を明示的に設定 |
| WARN | `lipo`, `otool`, `nm`, `codesign`, `xattr` (macOS) | Xcode Command Line Tools |
| WARN | `ghidra` MCP (macOS) | 推奨 — [Internals](#internals) のマニフェストを参照 |

どちらもベータ段階のターゲットです：不足している機能は、init時ではなく、ループが実際にそれを必要とした時点で表面化します。macOSの動的作業は`ssh`チャネル（Macホストへ）を使用します；オプションのx64dbgブラウザデバッグパスには、上記のWindowsツールチェーンをインストールしてください。

</details>

上記すべての単一マニフェストソース — いつでもプローブできます：`python scripts/mcp_probe.py <ws> --type <windows|linux|android|web|macos>`（exit 1 = HARD欠落）。

## Bring your own environment

動的デバッグには、エージェントが操作できる実行コントロールプレーンが必要です。`KUNGLAO_CHANNEL`は5つのファーストクラスチャネルのいずれかを選択します — 環境にすでにあるものを使用してください；いずれも劣化モードではありません：

| Channel | What it drives | Prerequisites |
|---|---|---|
| `vmr` (デフォルト) | VMware VM、**任意のゲストOS** — スナップショット/リバートワークフローがその代替不可能な価値 | vmr-shell スキル；`KUNGLAO_VM_HOST` + ポート9876/1337 |
| `ssh` | ssh到達可能な任意のマシン：ベアメタル、クラウドVM、Mac、リモートdockerホスト | 鍵認証 — プローブは実際のBatchMode `ssh ... true`を実行 |
| `docker` | ローカルまたはリモートのdockerデーモン — `docker exec`は任意の制御パスと等価 | `docker version`が正常；オプションの`KUNGLAO_DOCKER_CONTAINER` |
| `adb` | Androidエミュレータまたは実機 | `adb devices`に表示される；frida用に`adb forward tcp:1337 tcp:1337` |
| `local` | **ホスト上での静的解析のみ** | なし — レッドラインを参照 |

> **`local`レッドライン：** localは**静的**作業専用です — ホスト上でサンプルを実行、デバッグ、注入しては決してなりません。動的要件がある場合は`KUNGLAO_CHANNEL`を`vmr`/`ssh`/`docker`/`adb`に切り替えます；initは`local`上の動的タスクをHARD拒否します。

チャネルプローブは動的タスクに対してのみ実行されます（静的のみのタスクはスキップされます）。`ssh`チャネルの実行は**ssh-mcp**コントロールプレーン（`npm i -g ssh-mcp`）を経由します；プレーンなCLI sshがフォールバックです。ssh経由のリモートdockerには、`KUNGLAO_DOCKER_CONTAINER`を設定してください。

## Configuration

4つの変数でほとんどのセットアップをカバーできます：

| Variable | Default | Meaning |
|---|---|---|
| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | unset | unsetまたは`0`のままにする必要があります — truthy値はディスパッチをteammateチャネル経由にルーティングし、拒否されます |
| `KUNGLAO_CHANNEL` | `vmr` | 動的実行コントロールプレーン：`vmr` \| `ssh` \| `docker` \| `adb` \| `local` — [Bring your own environment](#bring-your-own-environment) を参照 |
| `KUNGLAO_VM_HOST` | unset | 動的解析用のVM/ホスト（vmr-shell :9876、Frida :1337） |
| `GHIDRA_HOME` | unset | Ghidraインストールルート（`support/analyzeHeadless.bat`を含む必要があります） |

ほとんど不要：`KUNGLAO_DOCKER_CONTAINER`（`ssh`/`docker`チャネル用のdocker実行ターゲット）、`KUNGLAO_FRIDA_PORT`（デフォルト1337）、`KUNGLAO_DIE`（DIEパス、PATHにフォールバック）、`KUNGLAO_CLAUDE_JSON`（ユーザーレベルMCPレジストリのテストオーバーライド）。

## Safety

- サンプルはホスト上で決して実行されません — `block_malware_exec`フックがそれを強制します；動的作業はVM/コンテナ/デバイス専用で実行され、セッションごとの認可が必要です。
- グラウンドトゥルースの階層：生のアーティファクト > ローカルツール > サンドボックス > 脅威インテリジェンス（CTIは反証可能な仮説であり、真実ではありません）。
- メーカー・チェッカー：ワーカーは自己検証を決して行いません；検証者はメーカーの結論を決して読みません。
- Bins、設定、フックは決してコミットされません；シークレットはワークスペースとリポジトリから除外されます。

## Development

コントリビューションを歓迎します。ワークフロー：`dev`からブランチを切り、変更ごとに1ブランチ、`dev`へPRを戻します。```bash
git worktree add .worktrees/<name> -b <name> dev
uv sync --locked
uv run python -m pytest -q
gh pr create --base dev