find-document

name

find-document

description

「Box にあったあの資料」「先週共有された PDF」「<キーワード>含むファイル」「あの議事録どこ」「あの Google Doc」「Sheets の <X>」「Google Slides で説明したやつ」「あの Gmail」「Gmail に来てた件」「Google Calendar の予定」と頼まれたら、opshub MCP の search (FTS5) で本文ベース横断検索を実行し、Box / Slack / GitHub / MS365 (Outlook / Calendar / OneDrive) / Teams / Box Drive / OneDrive Drive / Office 文書 (Word / Excel / PowerPoint) / Google Workspace (Docs / Slides / Sheets) / Gmail (`gmail_message`、Phase 14) / Google Calendar (`google_calendar`、Phase 14) を横断して該当 source を返す。本文取得は読み取り経路のみで、外部 SaaS を直接叩かない。意味検索ハイブリッドが必要な場合は recall.search を補助的に併用してもよい。

find-document — opshub の本文ベース横断検索で資料を引く

opshub MCP server (opshub mcp serve、ADR-0022) の search (FTS5、Phase 12 H1 で MCP に露出) で、Phase 10 Sub-issue B (#214 merged) の本文ベース SQLite FTS5 横断検索を使い、Box / Slack / GitHub / MS365 (Outlook / Calendar / OneDrive) / Teams / Box Drive / OneDrive Drive / Office 文書 (Word / Excel / PowerPoint) / Google Workspace (Docs / Slides / Sheets) / Gmail / Google Calendar を横断して該当ファイル / メッセージを引く。Phase 11 で Teams chat (teams_message)、Outlook 本文 deep retention (ms365_outlook)、Office 文書抽出 (word_document / excel_spreadsheet / powerpoint_slide_deck、markitdown 経由) が追加され、onedrive_drive ローカル FS connector も検索対象に入った (ADR-0025、Phase 11 plan §3 F1-F6)。Phase 13 で Google Workspace 由来 (google_doc / google_slides / google_sheets、Drive API files.export → markitdown 経由) と catch-all (google_workspace_file、metadata-only) が追加された (ADR-0025 §決定 (d')+(j)、Phase 13 plan §3 G1-G5)。Phase 14 で Gmail (gmail_message、google_mail connector) と Google Calendar (google_calendar、google_calendar connector) が追加され、Outlook / ms365_calendar と symmetric な本文 / アジェンダ検索が可能になった (ADR-0010 §改訂、Phase 14 plan §3)。

ADR-0020 (本文ローカル保持) で、要約 (summary) ではなく本文に対する hit が返るため、固有名詞や細部のキーワードでも引ける (Phase 10 plan §3-B)。

本 skill の前身は Phase 10 で導入された Tier 1 でしたが、Phase 12 H1 で find-document に rename + search (FTS5) MCP tool の直接利用に変更しました（詳細は docs/phase-12-plan.md §3 H1-c）。

何が起きるか

1. ユーザーが「あの資料」「先週共有された〜」「<キーワード>含むファイル」と頼む
2. ホストが本 skill を発火
3. ホストが search を呼ぶ（FTS5 ベースの本文 hit が最も精度高い）
4. 補助的に recall.search を呼んで意味検索 hit も統合（任意、Step 2）
5. 戻り値の items[] / hits[] を整形 (source_type 別にグルーピング、新しい順) して返す
6. ユーザーがリンク (url / 元の external_id) からブラウザで開く

呼び出し順 (MCP tool)

Step 1: search (FTS5) で本文ベース横断検索

tool: search
input:
  query: "<キーワード or トピック>"
  limit: 30
  connector_name: "<box | slack | github | ms365 | teams | box_drive | onedrive_drive | google_workspace | google_mail | google_calendar>"   # 任意

search は SQLite FTS5 の sources_fts 仮想表に MATCH を投げ、sources projection に join 戻して title / url / summary を返す。ホストが渡すクエリ文字列は phrase quote されるため、FTS5 の syntax 文字 (括弧 / コロン等) をエスケープする必要はない（ADR-0022 改訂 §決定、Phase 12 H1）。

戻り値の items[] 各行は {entity_id, connector_name, source_type, title, url, snippet, score}。score は -bm25 降順。

Step 2 (任意): 意味検索ハイブリッドが欲しい場合は recall.search を併用

固有名詞や明示的なキーワードでなく、似た意味 / 言い換えでも当てたい場合は recall.search も呼んで結果を統合する。

tool: recall.search
input:
  query: "<キーワード or トピック>"
  entity_type: "source"
  limit: 20

recall.search は ADR-0012 hybrid recall (sqlite-vec embedding + FTS5 + graph 補強)。search の純粋な FTS5 hit と比べ、意味的に近いものを引く可能性がある一方、embedder のコスト・呼び出し時間が発生する。固有名詞検索の主力は search で十分。

Step 3 (任意): source_type / connector で絞り込み

ユーザーが「Box の」「Slack の」と source 種別を絞っている場合、search の connector_name 引数で絞るか、ホスト側で items[] を source_type でフィルタする。

ユーザー語彙	source_type	connector
Box にあるあの〜	box_event / box_drive_file	box / box_drive
Slack の〜	slack_message	slack
GitHub の〜	issue / pull_request / notification	github
Outlook / メール	ms365_outlook	ms365
カレンダー予定	ms365_calendar	ms365
OneDrive のファイル (Graph 経由)	ms365_onedrive	ms365
Teams のチャット	teams_message	teams
Word 文書	word_document	box_drive / onedrive_drive
Excel スプレッドシート	excel_spreadsheet	box_drive / onedrive_drive
PowerPoint スライド	powerpoint_slide_deck	box_drive / onedrive_drive
OneDrive Desktop (ローカル FS)	onedrive_drive_file	onedrive_drive
Google Docs	google_doc	google_workspace
Google Sheets	google_sheets	google_workspace
Google Slides	google_slides	google_workspace
Google Drive 上のその他 (PDF / image / folder etc.)	google_workspace_file	google_workspace
Gmail メッセージ	gmail_message	google_mail
Google Calendar イベント	google_calendar	google_calendar

source_type 値は connector 実装の SSOT (src/opshub/connectors/<name>/{api,mapper}.py の source_type=... リテラル) に対応する。GitHub connector は github_ prefix を持たず素の issue / pull_request / notification を発行する点に注意 (Phase 10 監査で SKILL.md ↔ 実装間の drift として固定済)。Phase 11 で追加された word_document / excel_spreadsheet / powerpoint_slide_deck は box_drive / onedrive_drive の content_extraction = true opt-in が必要 (markitdown 経由、ADR-0025)。Phase 13 で追加された google_doc / google_slides / google_sheets も同じく google_workspace の content_extraction = true opt-in が必要 (Drive API files.export → MS Office mediatype → markitdown 経由、ADR-0025 §決定 (j))。google_workspace_file (catch-all 非 native) は Drive が 403 fileNotExportable を返すため content_extraction = true 設定下でも metadata-only path で body = summary 等の非空文字列が persist される (epic #470 で sources.body NOT NULL 化、ADR-0020 §(d'))。Phase 14 で追加された gmail_message (google_mail connector) は Gmail API users.messages.get(format=full) から MIME body を抽出し、google_calendar (google_calendar connector) は Calendar API events.list の summary + description を本文として持つ (mapper SSOT: src/opshub/connectors/google_mail/mapper.py の GMAIL_SOURCE_TYPE = "gmail_message" および src/opshub/connectors/google_calendar/mapper.py の GOOGLE_CALENDAR_SOURCE_TYPE = "google_calendar"、ADR-0010 §改訂)。

Step 4 (任意): 特定 hit の詳細を引く

特定 hit の詳細をユーザーが知りたい場合、その entity_id を source.get に渡して row を取得する。

tool: source.get
input:
  source_id: "<entity_id from search hits>"

本文全体を context window に詰めない (ADR-0022 §(d) context 効率原則)。

出力フォーマット (ホスト側)

# 「<クエリ>」の検索結果

## Box (n 件)
- [<title>] (<date>) — <snippet 抜粋>
  → <url>

## Slack (n 件)
- ...

## GitHub (n 件)
- ...

## MS365 (n 件)
- Outlook (`ms365_outlook`、body deep retention 含む): ...
- Calendar (`ms365_calendar`): ...
- OneDrive (`ms365_onedrive`、Graph 経由 metadata): ...

## Teams (n 件)
- [<channel/chat title>] (<date>) — <snippet 抜粋>  ← `teams_message`

## Box Drive (ローカル sync、n 件)
- <rel_path> (<mtime>) — <snippet 抜粋>

## OneDrive Drive (ローカル sync、n 件)
- <rel_path> (<mtime>) — <snippet 抜粋>  ← `onedrive_drive_file`

## Office 文書 (markitdown 抽出、n 件)
- <rel_path> (<mtime>) — <snippet 抜粋>  ← `word_document` / `excel_spreadsheet` / `powerpoint_slide_deck`

## Google Workspace (Drive API export → markitdown、n 件)
- <title> (<modified>) — <snippet 抜粋>  ← `google_doc` / `google_slides` / `google_sheets` / `google_workspace_file` (catch-all、本文なし)

## Gmail (Phase 14、n 件)
- [<件名>] (<date>) — <snippet 抜粋>  ← `gmail_message`

## Google Calendar (Phase 14、n 件)
- [<会議タイトル>] (<start>) — <snippet 抜粋>  ← `google_calendar`

自律範囲

• read tool のみ — search / recall.search / source.get (readOnlyHint=true)。確認なしで呼んでよい
• 外部 SaaS への問い合わせは発生しない (search は opshub ローカル DB のみ)
• 取得した本文を agent context に丸ごと注入しない (snippet ベースで表示)

できないこと / やらない

• 外部 SaaS の最新を直接 fetch する (connector.sync は write tool、本 skill 外。ユーザーが明示的に「同期して」と頼んだ場合のみ別経路で人確認付き)
• ファイルのダウンロード / 外部送信
• 検索 hit を opshub の durable state (task / inbox / decision) に自動追記 — task.create 等は別 skill / 人確認付き
• 本文を agent context に full payload で渡す (ADR-0022 §(d))

参考

• ADR-0012 改訂 (本文 embedding、Phase 10 §18)
• ADR-0020 改訂 (本文ローカル保持、Phase 11 で Outlook body deep retention 追加)
• ADR-0022 改訂 (MCP Server Surface、Phase 12 H1 で search (FTS5) 露出)
• ADR-0025 (Office 文書本文抽出、markitdown 経由)
• ADR-0010 §改訂 (connector contract、Phase 11 で Teams 追加、Phase 13 で Google Workspace 追加、Phase 14 で Gmail + Google Calendar 追加)
• ADR-0014 §改訂 (SaaS token storage、Phase 13 で Google Refresh Token rotation pin を 3 件目として追加、Phase 14 で Gmail / Google Calendar も同一 OAuth + rotation scheme)
• Phase 10 Sub-issue B (#214 merged、本文 FTS5 / search command)
• Phase 11 plan (docs/phase-11-plan.md)
• Phase 12 plan (docs/phase-12-plan.md §3 H1)
• Phase 13 plan (docs/phase-13-plan.md §3 G1-G5、Google Workspace 8 番目の connector)
• Phase 14 plan (docs/phase-14-plan.md、Gmail + Google Calendar 9・10 番目の connector)
• docs/assistant-agent.md (Skill catalog SSOT)
• docs/google-workspace-setup.md (Google OAuth + Drive API setup、Gmail / Calendar scope は Phase 14 で追加)