# Microsoft Learn 検索 / キャッシュツール

`learn.microsoft.com` を検索するための 4 つのツール群。オンライン検索とローカルキャッシュ (魚拓) を統合する。

## ツール一覧

| ツール | 用途 |
|--------|------|
| `SearchMicrosoftLearn` | オンライン検索 + ローカルキャッシュヒットを統合して返す |
| `FetchMicrosoftLearn` | ページを取得し Markdown 化してキャッシュに保存 |
| `SearchMicrosoftLearnCache` | キャッシュ済みページのみ FTS5 全文検索 (オフライン) |
| `RefreshMicrosoftLearnCache` | キャッシュ済みページを強制再取得 |

## 標準フロー

1. `SearchMicrosoftLearn({ query: "azure managed identity" })` で候補 URL を一覧取得
2. 興味のある URL を `FetchMicrosoftLearn({ url })` で取得 (初回はオンライン、2 回目以降はキャッシュ)
3. キャッシュに溜まってきたら `SearchMicrosoftLearnCache({ query })` でオフライン検索可能

## キャッシュ仕様

- 場所: `data/ms-learn-cache/pages.sqlite`
- DB: SQLite + FTS5 (external content)、ロケール (`en-us` / `ja-jp` 等) 横断検索
- TTL: なし (永続)。古さが気になったら `RefreshMicrosoftLearnCache` で個別に再取得
- 1 ページ = HTML から `<main>` / `<article>` を抽出して minimal markdown 化したもの

## SearchMicrosoftLearn

### 引数

| 名前 | 型 | 必須 | 説明 |
|------|----|------|------|
| `query` | string | yes | 自然言語キーワード |
| `locale` | string | no | `en-us` (デフォルト)、`ja-jp` 等 |
| `products` | string[] | no | 製品スコープ (例: `["azure"]`、`["dotnet"]`)。省略時は Learn 全範囲 |
| `top` | integer | no | 取得件数 (デフォルト 10、最大 25) |

### 出力例

```
## Online results (5)
- [Managed identities for Azure resources](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview) [cached]
  Managed identities provide an automatically managed identity in Microsoft Entra ID...
- [Use a managed identity to connect to Azure SQL](https://learn.microsoft.com/en-us/azure/azure-sql/database/authentication-aad-overview)
  ...

## Cache hits (2)
- [Managed identity types](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview)
  ... two types of <mark>managed</mark> identities ...
```

`[cached]` マーカーが付いている結果は `FetchMicrosoftLearn` を呼ばなくても直近のキャッシュから即取り出せます。

### 注意

- locale はデフォルト `en-us`。日本語版は遅延・取りこぼしが多いので、特別な理由がない限り `en-us` を推奨
- `products` 絞り込みは Learn 検索 API の仕様に依存。指定しなくても困らない場面が多い
- オンライン検索が失敗した場合 (rate limit / network) はキャッシュ検索のみで結果を返す

## FetchMicrosoftLearn

### 引数

| 名前 | 型 | 必須 | 説明 |
|------|----|------|------|
| `url` | string | yes | `https://learn.microsoft.com/...` で始まる URL |

### 挙動

- URL 正規化: クエリ文字列とハッシュは削除して比較
- キャッシュヒット時は HTTP リクエストを発生させず、保存済みの Markdown を返す
- ヒットしない場合は HTTP 取得 → HTML から `<main>` 抽出 → minimal markdown 変換 → SQLite 保存

### 出力

冒頭にメタデータ行 (`Cached (age=...)` または `Fetched and cached (...)`) + 本文 markdown。

## SearchMicrosoftLearnCache

オフライン専用。FTS5 のクエリ構文をそのまま使えるが、デフォルトはスペース区切りの AND 検索 (各単語をフレーズ扱い)。

### 引数

| 名前 | 型 | 必須 | 説明 |
|------|----|------|------|
| `query` | string | yes | 検索クエリ |
| `top` | integer | no | 取得件数 (デフォルト 10、最大 25) |

### 出力

ヒットしたページ毎に `[title](url)` + ハイライト付きスニペット (`<mark>` タグ)。

## RefreshMicrosoftLearnCache

キャッシュ済みページの内容が古いと判断したときに使う。HTTP 取得を強制し既存レコードを上書き。

### 引数

| 名前 | 型 | 必須 | 説明 |
|------|----|------|------|
| `url` | string | yes | 再取得する URL |

## 設定

`config.yaml` の追加設定は不要。`data/ms-learn-cache/` ディレクトリは初回呼び出し時に自動作成される。

## 制限事項

- HTML→Markdown 変換は Learn の構造に最適化した最小実装。汎用 HTML には使えない
- Learn 以外のドメインは拒否 (`learn.microsoft.com` のみ)
- ページ内の画像は取得しない (テキスト検索のみ用途)
- API レート制限に当たった場合は `SearchMicrosoftLearn` がエラーを返すが、キャッシュ検索は引き続き使える