maestro/docs/tools/searchmicrosoftlearn.md

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 がエラーを返すが、キャッシュ検索は引き続き使える