7049a874f3
Open-source release of MAESTRO, an agent orchestration platform that runs LLM-driven tasks through sandboxed tools, with a web UI. Apache-2.0. See README.md and docs/ (getting-started, configuration, architecture).
113 lines
4.8 KiB
Markdown
113 lines
4.8 KiB
Markdown
# 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` がエラーを返すが、キャッシュ検索は引き続き使える
|