pi-agent-rust

Pi Agent Rust

60 秒で起動

export CARGO_TARGET_DIR="/data/tmp/pi_agent_rust/${USER:-agent}"
export TMPDIR="/data/tmp/pi_agent_rust/${USER:-agent}/tmp"
mkdir -p "$TMPDIR"

rch exec -- cargo check --all-targets
rch exec -- cargo clippy --all-targets -- -D warnings
cargo fmt --check
bash tests/installer_regression.sh

症状からの切り分け

症状	最初に実行する 3 つのコマンド
プロバイダーストリーミング／ツール呼び出しのリグレッション	cargo test provider_streaming -- --nocapture ; `rg -n "stream
セッションのリプレイ／インデックスの不整合	cargo test session -- --nocapture ; `rg -n "Session
拡張機能のポリシー／ランタイムの失敗	cargo test extension -- --nocapture ; `rg -n "policy
インストーラー／アンインストーラー／スキルの問題	bash tests/installer_regression.sh ; `rg -n "AGENT_SKILL_STATUS
対話モードと RPC の不一致	cargo test e2e_rpc -- --nocapture ; `rg -n "interactive

より詳しい診断には、references/DEBUGGING-PLAYBOOKS.md を参照してください。

必ず守ること

• 最初に AGENTS.md を読み、その指示に正確に従ってください。
• ファイルを削除したり、破壊的な Git／ファイルシステムコマンドを実行したりしないでください。
• 変更は既存ファイル内で行い、同じ目的の別バージョンのファイルは作成しないでください。
• ドキュメントやスクリプトでは main のセマンティクスを使用し、master は導入しないでください。
• 高速なテキスト調査には rg を、構造的なマッチングやリファクタリングには ast-grep を優先してください。
• 負荷の高いコンパイル／テストには rch exec -- <cargo ...> を優先してください。
• 重要な変更の後は、コンパイル／リント／フォーマットのチェックと、関連性が最も高い小規模なリグレッションテストを実行してください。

基本ワークフロー

• 調査：変更範囲と不変条件を特定します。
• 実装：失敗時の動作を明確にした、動作に焦点を当てた最小限のパッチを作成します。
• 検証：対象を絞ったテストを先に実行し、必要に応じて範囲を広げます。
• UX を確認：エラー／ステータスの出力が明確で、一貫しており、曖昧さがないことを確認します。
• ドキュメントを同期：フラグ／動作／ユーザー向けガイダンスを変更した場合は、README.md を更新します。

変更ファイル -> 必須テスト

変更ファイル（例）	最低限必要なテスト
install.sh、uninstall.sh、.claude/skills/pi-agent-rust/**	bash -n install.sh uninstall.sh tests/installer_regression.sh ; shellcheck -x install.sh uninstall.sh tests/installer_regression.sh ; bash tests/installer_regression.sh ; bash scripts/skill-smoke.sh
src/providers/**、src/provider.rs、src/sse.rs	cargo test provider_streaming ; cargo test conformance
src/session.rs、src/session_index.rs、src/session_test.rs	cargo test session ; cargo test conformance
src/extensions.rs、src/extensions_js.rs	cargo test extension ; cargo test conformance
src/tools.rs	cargo test tools ; cargo test conformance
src/interactive.rs、src/rpc.rs、src/main.rs	cargo test e2e_rpc ; cargo test conformance

まだ実行しないこと

対象を絞った再現確認と重点的なテスト範囲の結果から必要性が示された後にのみ、以下を実行してください。

• より限定的なテスト範囲ですでに再現できている場合に、ワークスペース全体で広範な cargo test を実行すること。
• 変更ファイルの影響範囲を確認する前に、複数の領域にまたがる負荷の高いテストを実行すること。
• 中核となる失敗箇所のテストがまだ不安定な状態で、コンフォーマンステストを繰り返し一通り実行すること。

重要なコマンド

# Fast recon
git status --short
rg -n "install|uninstall|skill|checksum|sigstore|completion|provider|session|extension" \
  install.sh uninstall.sh README.md tests/installer_regression.sh src/

# Installer + skill safety gates
bash -n install.sh uninstall.sh tests/installer_regression.sh
shellcheck -x install.sh uninstall.sh tests/installer_regression.sh
bash tests/installer_regression.sh
bash scripts/skill-smoke.sh

# Rust gates
rch exec -- cargo check --all-targets
rch exec -- cargo clippy --all-targets -- -D warnings
cargo fmt --check

コマンドの詳しい一覧は、references/COMMANDS.md を参照してください。 インシデントの詳細なトリアージについては、references/DEBUGGING-PLAYBOOKS.md を参照してください。

重要なファイル

• src/main.rs: CLI のエントリーポイントとモードの振り分け。
• src/agent.rs: エージェントループとツールの反復処理。
• src/provider.rs: プロバイダートレイトの契約。
• src/providers/: プロバイダーの実装とファクトリーの配線。
• src/tools.rs: 組み込みツール（read、write、edit、bash、grep、find、ls）。
• src/session.rs: JSONL セッションの永続化。
• src/session_index.rs: セッションインデックスとメタデータキャッシュ。
• src/extensions.rs + src/extensions_js.rs: 拡張機能のポリシーと QuickJS ブリッジ。
• src/interactive.rs + src/rpc.rs: TUI と RPC/stdin のインターフェイス。
• install.sh + uninstall.sh: インストールのライフサイクル、移行、スキル管理。
• tests/installer_regression.sh: インストーラーの回帰テストハーネス。
• scripts/skill-smoke.sh: スキルの整合性とインライン同期の検証。

既知の落とし穴

• 互換性のあるリリースコンテキストを伴わないカスタムアーティファクトのインストールパスは、明示的にガードされていない場合、誤ったフォールバックが発生することがあります。
• 部分的な結果や失敗の分岐が明示されていないと、複数の結果が混在した場合にスキルのステータスが誤解を招くことがあります。
• アンインストールロジックでは、マーカーチェックと想定される配置先パスの形状の両方を必ず検証する必要があります。
• stdout がデータ受け渡しに使われる場合、インストーラーの進行状況やステータスのテキストは stderr に出力してください。
• 明示的にチェックしないと、バンドルされたスキルとインラインのフォールバックに気付かないうちに差異が生じることがあります。

パッチのパターン

パターン 1：混在する結果のステータスを明確化

# BEFORE: everything collapsed into "skipped custom"
if [ "$skipped_custom" -ge 1 ]; then
  AGENT_SKILL_STATUS="skipped (existing custom skill)"
fi

# AFTER: distinguish custom-skip from write failure
if [ "$skipped_custom" -ge 1 ] && [ "$failed_writes" -ge 1 ]; then
  AGENT_SKILL_STATUS="partial (custom skill kept; other install failed)"
elif [ "$skipped_custom" -ge 1 ]; then
  AGENT_SKILL_STATUS="skipped (existing custom skill)"
fi

パターン 2：スキルを安全に置き換える

# BEFORE: remove destination before validating copy result
rm -rf "$destination"
cp "$source" "$destination/SKILL.md"

# AFTER: stage then atomically move into place
staged="$(mktemp -d ...)"
cp "$source" "$staged/SKILL.md"
mv "$staged" "$destination"

失敗時のトリアージ

• インストーラーの概要とステータスが一致しない場合： install.sh 内の AGENT_SKILL_STATUS、CHECKSUM_STATUS、COMPLETIONS_STATUS を追跡します。
• インストール／アンインストールの安全性に懸念がある場合： 両方のスクリプトでマーカーチェックと想定される配置先のガードを確認します。
• プロバイダー／セッション／拡張機能のリグレッションがある場合： 症状別ルーターを使い、その後 references/DEBUGGING-PLAYBOOKS.md に従います。
• ドキュメントにずれがある場合： README.md のフラグや例が現在のインストーラーの動作と一致していることを確認します。

完了条件

• 変更ファイルのマトリクスにある最低限のテストに合格していること。
• 変更した箇所のコンパイル／lint／フォーマットチェックに合格していること。
• インストーラー／スキルの変更が tests/installer_regression.sh と scripts/skill-smoke.sh に合格していること。
• 失敗時の動作が明示され、予期しないサイレントフォールバックがないこと。
• スキルのドキュメントとインラインのフォールバックが一致し、最新の状態に保たれていること。