# このadvisorの動作を理解する

## 何をするものか

作業中のAIに、必要なときだけ別のモデルへ質問する `advisor` ツールを追加します。助言を返すだけで、助言に従ってファイルを編集したりコマンドを実行したりする機能はありません。

```text
あなた → 作業中のAI
           │ advisor({ question, purpose, context?, model? })
           ▼
       入力・設定の検証
           │
           ├─ ローカルへ相談の開始記録
           ▼
       独立したモデル呼び出し
       専用の指示文 + 今回の質問と背景
           │
           ├─ ローカルへ回答・使用量・費用見積もりを記録
           ▼
       作業中のAIへ助言を返す
           │
           ▼
       あなた／作業中のAIが根拠を確認し、次の行動を決める
```

拡張をロードするだけではモデルを呼びません。ただし、ツールを使える作業中のAIは、自分で呼び出しを選べます。「利用者の確認ダイアログが毎回出る」「手動実行しかできない」という仕組みではありません。具体的な未解決の相談にだけ使うようツール説明で指示しています。

## 入力は4つだけ

| 引数 | 必須 | 意味 |
| --- | --- | --- |
| `question` | はい | 何について判断してほしいか |
| `purpose` | はい | `decision`（選択）、`diagnosis`（原因の検討）、`critique`（問題点の検討） |
| `context` | いいえ | 制約、比較案、差分、エラー、確認済みの事実など |
| `model` | いいえ | 今回だけ使う `provider/model` |

たとえば：

```json
{
  "question": "独自のリトライ処理を残すべき？",
  "purpose": "decision",
  "context": "SDKに2回のリトライがあり、独自処理も3回リトライする。30秒以内に失敗を返す必要がある。",
  "model": "openai-codex/gpt-6.1-sol"
}
```

advisorはこの文章以外のコードを見ません。背景が足りなければ、有用な回答ができないことがあります。独立した呼び出しでも、渡された情報の偏りから独立しているとは限りません。

## isolationの意味

相談ごとに専用の指示文と今回の入力だけで、新しいモデル呼び出しを作ります。

- 作業中のAIのシステムプロンプト・会話履歴・ツール一覧は自動で渡しません。
- 過去の相談も引き継ぎません。
- provider用のセッションIDも相談ごとに新しくします。
- advisorに利用可能なツールは渡しません。
- ファイル内容やログは、呼び出し側が `context` に書いた場合にだけモデルへ渡ります。

**OSの別プロセスやサンドボックスではありません。** 拡張コードはPiのプロセス内で動きます。モデルの認証・通信はPiに任せます。選んだモデルの提供元へ質問と背景が送られるので、渡してよい情報だけを入力してください。

## 回答はどう使うか

モデルには次の短いセクションを求めます。

1. 推奨案
2. 根拠と簡潔な理由
3. 最も強い反対意見・不確実性
4. 最小の次の一手
5. 打ち切り／判断の条件

自由文の指示であり、必ず正しい形式・内容が返ることを保証するものではありません。助言を承認・証明として扱わず、実際のコードや利用者の目的と照合します。

## 設定と安全弁

新しい設定は通常 `~/.pi/agent/pi-advisor.json` に置きます。Piのagentディレクトリを変えた場合はそれに従います。旧版の `advisor.json` とは別です。

| 設定 | 初期値 |
| --- | --- |
| `model` | `openai-codex/gpt-6.1-sol` |
| `reasoning` | `high` |
| `maxTokens` | 4,096 |
| `timeoutMs` | 120,000（2分） |
| `maxInputChars` | 48,000（専用指示文と組み立てた入力の合計） |
| `logDirectory` | `$XDG_STATE_HOME/pi-advisor/consultations`、未設定なら `~/.local/state/pi-advisor/consultations` |

`model`引数による上書きはその呼び出しだけに適用され、設定ファイルは変わりません。不明なモデルを別モデルに自動で置き換えません。入力が長すぎると、黙って削るのではなくエラーにします。

`maxTokens` はproviderへ渡す要求値であり、生成トークン数・費用の厳密な上限ではありません。Pi 1.0.4の既定providerが使う `openai-codex-responses` アダプターは、この上限を送信しません。その場合はツール結果とローカルログに警告を付けます。ほかのproviderでも、推論予算などによって解釈が異なる場合があります。厳密な上限が必要なら、その上限が実際に適用されることを確認したproviderを使ってください。

相談は1回のdispatchです。拡張独自の再試行はなく、Piにも `maxRetries: 0` を指定します。ただし、認証更新やprovider内部の通信まで「HTTPリクエストが厳密に1回」と保証するものではありません。

キャンセルや時間切れでは中断signalをPiに伝えて待機を止めます。providerが中断を無視する場合、処理や課金が継続する可能性があります。遅れて届いた使用量は初版では回収しません。

モデル呼び出し後は、正常終了・失敗・キャンセル・時間切れのいずれでも、その相談IDに属するPiのproviderリソースを解放します。親セッションや別の相談の接続は対象にしません。解放に失敗した場合は警告を付け、回答や使用量はそのまま返します。

## ログに何が入るか

相談IDでファイルとツールの結果を対応づけます。

- 質問・目的・明示的な背景
- 実際に組み立てた専用指示文と入力（ログ用の秘密値除去後）
- 設定のモデル、上書き指定、解決したモデル、応答が報告するモデル
- 時刻、所要時間、設定上限、完了・不完全・失敗・キャンセルの状態
- 回答の表示テキスト
- 入力・出力・キャッシュのトークン数、報告があれば推論トークン内訳
- Piが報告する費用見積もり、ログ保存などの警告
- package／prompt／log schemaのバージョン

隠れた思考本文、認証ヘッダー、生の通信レスポンス、providerの生エラーは保存しません。生エラーを省くため、認証失敗などの詳細な原因がこのログだけでは分からない場合があります。

### 費用の読み方

- `accounting.tokens`：Piが返したトークン内訳。
- `accounting.estimatedUsd`：Piが報告したUSD見積もり。**実際の請求金額ではありません。**
- `accounting.actualBilledUsd`：実請求額は取得しないため `null`。
- `accounting.complete`：正常に回答を完了したか。不完全な呼び出しの使用量は請求全体を表さない場合があります。
- 価格や使用量を得られない場合は不明として扱います。全費用が0の報告も、無料か価格未設定か区別できないため見積もりは `null` にします。

推論トークン数は出力トークン数の内数です。1時間キャッシュ書き込みもキャッシュ書き込みの内数です。合計に二重加算しません。定額認証の料金は、APIの従量課金換算と一致しないことがあります。

### 保存上の注意

新規ディレクトリは0700、ファイルは0600。ログはGit管理外の専用ディレクトリへ保存してください。既存のログディレクトリが他ユーザーに公開されている場合や、パスにsymlinkがある場合は保存を拒否します。失敗しても助言は返し、警告を付けます。

既知の環境変数の秘密値や一般的なトークン形式をログから除く処理はありますが、**漏えいを完全に防ぐ機能ではありません**。コードや社内情報、未知の形式の秘密値は残り得ます。モデルに送る入力やPi本体の会話ログには、このログ用の除去処理は適用されません。

完了ログは30日／100 MiBを目安に、相談完了後に古いものから整理します。複数プロセスが動く場合の厳密な容量制限ではありません。中断されたプロセスが残したpending／finalizingログは自動削除せず、必要なら停止を確認して手動で整理します。

## 後から品質をレビューする

まず1つの相談について、次を確認します。

1. 質問と必要な事実を十分に渡せていたか。
2. 回答は事実と推測を区別していたか。
3. 新しい問題を見つけたか、それとも余計な作業を増やしたか。
4. 推奨に従った結果どうなったか。
5. 得られた価値に対して時間・費用は適切だったか。

最後の実際の結果は自動では分かりません。ログと、その後の判断・検証結果を人が照合してください。初版には自動採点、複数モデル比較、自動再相談、ダッシュボードはありません。

## ソースの読む順番

1. `index.ts`：AIに見える引数とツール説明。
2. `src/config.ts`：初期値と許可する設定。
3. `src/advisor.ts`：送信する指示、モデル呼び出し、結果と費用の処理。
4. `src/logs.ts`：保存・秘密値除去・古いログの整理。
5. `tests/advisor.test.ts`：ネット接続なしで確認している挙動。

この初版は独立したrepoに置くのみで、既存のadvisorや設定を自動で置き換えません。オフラインテストは配線・制限・ログなどの仕組みを検証しますが、実際の助言が旧版より良いことや、実providerでの認証・費用計算を実証するものではありません。