oss-sync f5c7666f6b feat: initial public release (MAESTRO)

2026-06-03 05:08:00 +00:00

4.8 KiB

Raw Blame History

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

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

ツール一覧

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

標準フロー

SearchMicrosoftLearn({ query: "azure managed identity" }) で候補 URL を一覧取得
興味のある URL を FetchMicrosoftLearn({ url }) で取得 (初回はオンライン、2 回目以降はキャッシュ)
キャッシュに溜まってきたら 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 がエラーを返すが、キャッシュ検索は引き続き使える

4.8 KiB Raw Blame History