# 導入ガイド

[English](getting-started.md) · [日本語 README](../README.ja.md)

## 必要な環境

**Pi パッケージとして利用する場合**は、対応する Pi と、認証済みのプロバイダーが必要です。実行するモデルの ID と利用枠も確認してください。**ソースから利用する場合**は、Windows・PowerShell 7・Git・`node:sqlite` 対応の Node.js が必要です（Node 24 で検証）。基本スクリプトに `npm install` は不要です。

## Pi に導入する

```powershell
pi install npm:@ludi-uni/ludi-agent-kit
pi list
```

Git から導入する場合は `pi install git:github.com/ludi-uni/ludi-agent-kit` を使います。`npm install @ludi-uni/ludi-agent-kit` だけでは、Skill や拡張が Pi に登録されません。

バージョンを固定せず導入した場合は `pi update npm:@ludi-uni/ludi-agent-kit` で更新できます。`npm:@ludi-uni/ludi-agent-kit@0.1.2` のように固定した場合、その指定のままでは新しい版に進まないため、必要な版を明示して `pi install` し、`pi list` で確認してください。拡張を読み直すには Pi セッションを再起動します。

導入すると `pi-workflow`、`project-management`、`visual-verification` の Skill と、loop guard・`ludi_orchestrate` 拡張が読み込まれます。拡張は Pi プロセスの権限で動くため、利用前にソースを確認してください。子エージェント専用の `shell-gate` は全体には読み込まれません。postinstall が Pi の設定や認証情報を書き換えることもありません。

### 実行前にモデルを対応付ける

`adapters/pi/models.json` は設定例であり、**そのままで利用できるモデルや認証情報ではありません**。ソースを取得した場合は、次のように例をユーザー領域へコピーし、`pi --list-models` で利用できる ID を調べて編集してください。

```powershell
$agentDir = if ($env:PI_CODING_AGENT_DIR) { $env:PI_CODING_AGENT_DIR } else { Join-Path $HOME '.pi/agent' }
$bindingDir = Join-Path $agentDir 'ludi-agent-kit'
New-Item -ItemType Directory -Force $bindingDir | Out-Null
Copy-Item adapters/pi/models.local.example.json (Join-Path $bindingDir 'models.local.json')
pi --list-models
```

npm パッケージから利用する場合、コピー元はインストールされたパッケージ内の `adapters/pi/models.local.example.json` です。キットはユーザー領域の `models.local.json` を**読み取るだけ**で、書き込みません。ここに認証情報は保存しないでください。優先順位や移行方法は [Pi adapter: model selection（英語）](../adapters/pi/README.md#model-selection-flow) を参照してください。オーケストレータの実行前チェックは対応付けの有無だけを調べ、認証・利用枠までは確認しません。

`pi-subagents` は別パッケージです。Pi への導入だけでは `agents/*.md` を pi-subagents の役割として自動登録しません。必要なら別途導入・設定してください。`sync-pi.ps1` は**ソースから利用する場合の代替手段**であり、インストール後の必須操作ではありません。二重登録を確認せず同じパッケージに `-Apply` しないでください。

## 実行する前に

ソースを取得したディレクトリで、モデルを起動せずに計画を確認できます。

```powershell
node scripts/orchestrate.mjs --dry-run "Fix the failing test"
```

実行すると外部モデルの利用枠を消費する場合があります。先に計画と [Orchestrator のオプション・安全上の注意（英語）](orchestrator.md) を確認してください。標準の rules planner は計画用モデルを呼びません。`--planner model` は任意の有料／外部呼び出しを伴い得ます。Pi の `ludi_orchestrate` ツールは履歴の保存、状態確認、判断への回答、再開にも対応します。

## ソースから利用する場合

外部モデルを呼ばずに検証できます。

```powershell
node scripts/validate.mjs
node --test (Get-ChildItem tests -Filter '*.test.mjs' | ForEach-Object FullName)
pwsh -NoProfile -File tests/test-sync-pi.ps1
pwsh -NoProfile -File adapters/pi/sync-pi.ps1  # dry-run。-Apply の前に内容を確認
pwsh -NoProfile -File scripts/check-environment.ps1
node scripts/check-pi.mjs                      # オフライン隔離スタートアップ/RPC 登録チェック
```

`scripts/check-pi.mjs`（ネイティブ Windows + pwsh + インストール済み Pi が必要）は一時的なエージェントディレクトリを作成し、`sync-pi.ps1 -Apply`（`-ApplySettings` ではない）で展開してから、インストール済み Pi をオフライン RPC モード（`--offline --no-mcp --no-session`）で起動し、`orchestrate` コマンド・3 つの `skill:*` コマンド・物理ターゲット・メッセージ/トークン/コストがゼロであること、そして期待されるキットのリンクと loop-guard 拡張エントリが一意であることを、チェック自身が所有する一時ディレクトリを使って検証します（`--keep-temp` で検査用に残せます）。同期処理はキット内の `adapters/pi/out/`（gitignored）にあるプレビューも更新しますが、実ユーザー設定は変更しません。プロンプト送信やモデル呼び出しは一切行いません。エージェント定義はキットとの構造比較で検証します。RPC にはエージェントレジストリや拡張フック数を問い合わせる公開手段がなく、別パッケージの pi-subagents はこのチェックでは導入・検証しません。実機の Pi に対しては `node scripts/check-pi.mjs --json` で実行してください。`tests/pi-startup.test.mjs` のユニットテストはモックのみを使用し、実チェックの合格を証明するものではありません。

`sync-pi.ps1` は標準では提案を `adapters/pi/out/` に生成します。`-Apply` は Junction と `AGENTS.md` を作成し、競合をバックアップします。`auth.json` とモデルの認証情報は変更しません。`settings.json` は別途明示する `-ApplySettings` を付けた場合のみ変更されます。解決したモデルを `subagents.agentOverrides.{scout,coder,visual,reviewer}` の `model`/`thinking` だけにマージし（その他のフィールド・ロール・キーは保持）、元ファイルを `<AgentDir>/ludi-agent-kit/backup-*/settings.json` にバイト単位でバックアップし、JSON ラウンドトリップを検証し、計画取得後にファイルが変更されていれば拒否します。これは楽観的な競合検出であり、カーネルの compare-and-swap ではないため、同期実行中に settings.json を編集しないでください。反映には pi の再起動または `/reload` が必要です。project 設定や provider 別 override が優先される場合もあるため、`/subagents-models` で実効値を確認してください。

```powershell
pwsh -NoProfile -File adapters/pi/sync-pi.ps1                # まず提案を確認
pwsh -NoProfile -File adapters/pi/sync-pi.ps1 -ApplySettings # 明示した場合だけ4ロールのモデル設定を適用
```

その他の例:

```powershell
node scripts/context-pack.mjs context-pack/examples/example-fix.md --json
node scripts/resolve-capabilities.mjs routing/routing.json adapters/pi/models.json
node scripts/run-pipeline.mjs --repo <fixture-copy> --task "Fix the failing test" --dry-run
```

最後のコマンドはプレビューです。`--dry-run` を外すと scout → Context Pack → coder → テストを実行し、モデルを呼び出して対象リポジトリを書き換える可能性があります。生成物は `adapters/pi/out/` に保存されます。詳しくは [Phase 2 report（英語）](phase2-report.md) を参照してください。`node tests/e2e-real-pi.mjs` も任意実行の実モデルテストで、利用枠を消費します。

公開前には [Distribution checklist（英語）](distribution.md)、外部ツールについては [third-party dependencies（英語）](third-party.md) を参照してください。