swallow/maestro

Fork 0

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

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

5.7 KiB

Raw Blame History

Office ファイル系ツール（ReadPdf / ReadExcel / ReadDocx / ReadPPTX / PdfToImages / SplitExcelSheets / SplitDocxSections）

ローカル workspace の Office 文書・PDF を読み込むツール群。

読み取り系

ReadPdf

// 全文抽出 (page 区切りで markdown)
ReadPdf({ path: "input/manual.pdf" })

// ページ範囲を絞る
ReadPdf({ path: "input/spec.pdf", page_range: "10-25" })

// grep -n 風検索 (query mode)
ReadPdf({ path: "input/manual.pdf", query: "保証期間" })
ReadPdf({ path: "input/manual.pdf", query: "保証期間", context_lines: 5 })
ReadPdf({ path: "input/spec.pdf", query: "第\\d+条", query_mode: "regex" })

スキャン PDF（テキストレイヤなし）の場合は 自動で PdfToImages + Vision OCR にフォールバック。手動で PdfToImages → ReadImage を呼ぶ必要は通常ない。query を併用すると OCR 結果にも同じフィルタが適用される。

引数

引数	型	デフォルト	説明
`path`	string	(required)	workspace 相対の PDF パス
`page_range`	`"3"` / `"1-5"`	(全ページ)	抽出ページ範囲
`max_pages`	number	(無制限)	抽出ページ数の上限
`max_chars`	number	50,000	返却文字数の上限
`query`	string	(なし)	一致行のみ grep -n 風で返す。trim 後 empty なら全文 mode
`query_mode`	`substring` / `regex` / `iregex`	`substring`	検索モード。substring は大小無視 + metachar auto-escape
`context_lines`	number (0..20)	2	query マッチ前後の context 行数

query mode の出力例

# foo.pdf, query: "保証期間"

### Summary
- Total pages: 50
- Pages with match: 3
- Total matches: 5

### Matches

## Page 7 — 2 matches
   6:   商品は購入日より
>  7: 保証期間内に故障した場合、無償修理対象…
   8: ただし、消耗品は対象外です。
  …
> 22: 延長保証期間は最大 3 年まで…

> が一致行、空白マーカーが context 行。隣接マッチは context window が overlap したら 1 cluster にまとめられ context 重複を回避。

gotcha

MAX_MATCHES_PER_PAGE = 50: 1 ページで 50 件超のマッチは打ち切り、page header に (capped) を付与。"the" のような broad pattern を絞るシグナル
query_mode: "regex" の invalid pattern → isError: true で friendly メッセージ。substring mode は metachar をエスケープするので絶対に regex error にならない
OCR fallback path でも query 適用。スキャン PDF + キーワード検索 OK
上記 PdfToImages の手動呼び出しは DPI / 出力ファイル個別管理 がしたい時のみ。普通の "PDF を vision で読みたい" は ReadPdf 単発で済む

ReadExcel

ReadExcel({ file_path: "input/data.xlsx" })
// → 全シートのセル内容をテキスト形式で返す

巨大な Excel は token を食うので、シートを絞る場合は SplitExcelSheets を使う。

ReadDocx

ReadDocx({ file_path: "input/spec.docx" })
// → 本文 + 表を抽出

ReadPPTX

ReadPPTX({ file_path: "input/slides.pptx" })
// → 各スライドのテキスト・表・スピーカーノートを返す

変換・分割系

PdfToImages

PdfToImages({ file_path: "input/scan.pdf", dpi: 200 })
// → output/ReadPdf/page-001.png, page-002.png, ... に保存

スキャン PDF を ReadImage で扱うときの前段。

SplitExcelSheets

SplitExcelSheets({ file_path: "input/big.xlsx" })
// → output/excel/{sheetname}.md と manifest.json を生成

シート単位で別ファイルにすることで、Read で必要なものだけ取り出せる。

SplitDocxSections

SplitDocxSections({ file_path: "input/long-spec.docx" })
// → 見出しベースで分割した .md と manifest.json を生成

長い Word 文書を構造化して Read で取り回しやすくする。

ファイル選択の指針

ファイル	第一選択	フォールバック
PDF（テキストあり）	ReadPdf	-
PDF（スキャン画像）	ReadPdf（自動 OCR フォールバック）	手動 PdfToImages → ReadImage
PDF 内をキーワード検索	ReadPdf + `query`	Read → Grep（ReadPdf で出力保存後）
Excel（小〜中）	ReadExcel	-
Excel（巨大）	SplitExcelSheets → Read	-
Word（短〜中）	ReadDocx	-
Word（長文・章構成）	SplitDocxSections → Read	-
PowerPoint	ReadPPTX	-

注意

すべて workspace 内のローカルファイル（input/ または output/）が対象
URL 指定不可 → DownloadFile で先にローカル保存
全ツール read-only（書き込まない）

ファイルサイズ上限

Read 系ツールは悪意あるファイル / リソース枯渇対策として入力サイズを検証する。デフォルトは以下の通りで、config.yaml の tools セクション、または Settings UI の「Tools → Office ファイルサイズ上限」から変更可能。

ツール	デフォルト	config キー
ReadExcel	10 MB	`tools.office_excel_max_size_mb`
ReadDocx	10 MB	`tools.office_docx_max_size_mb`
ReadPdf	10 MB	`tools.office_pdf_max_size_mb`
ReadPPTX	50 MB	`tools.office_pptx_max_size_mb`
ReadPPTX 展開後	200 MB	`tools.office_pptx_max_uncompressed_mb`

PPTX の「展開後」は ZIP bomb 検知用で、ZIP 内の全エントリの非圧縮合計サイズに対する閾値。超過時は ZIP bomb detected: ... エラーとなる。

マクロ付きファイル（.xlsm / .docm / .pptm / .xlsb）は警告付きで読み込まれる（実行はされない）。

5.7 KiB Raw Blame History Unescape Escape