genoffice

genoffice — ターミナルから GenOffice を利用

genoffice は GenOffice と一緒にインストールされます。まず genoffice --version を実行してください。コマンドが見つからない場合、GenOffice は起動のたびにランチャーのディレクトリを ~/.genoffice/launcher（Windows：%USERPROFILE%\.genoffice\launcher）に書き込みます。その1行を読み取り、以下の genoffice の代わりに、bash からは "<dir>/genoffice" を、PowerShell / cmd からは "<dir>\genoffice.cmd" を引用符で囲んで実行してください。ファイルがない場合のデフォルトの場所：macOS /Applications/GenOffice.app/Contents/Resources/cli、Windows %LOCALAPPDATA%\Programs\GenOffice\resources\cli、Linux /opt/GenOffice/resources/cli。すべてのコマンドはアプリ独自のエンジンでヘッドレス実行されます。マシン外へデータを送信するのは search、image、media のみで、送信先は GenOffice で設定されたプロバイダーです。

プログラムが出力を読み取る場合は、必ず --json を追加してください。標準出力には、次のいずれかの JSON オブジェクトが出力されます：{ "status": "ok" | "partial", "command", "summary", "output_path"?, "warnings"?, "detail"? }（partial：--best-effort / --stop-on-error を指定した apply がファイルを書き込んだものの、一部の操作に失敗した場合）、または { "status": "error", "code", "error", "message", "suggestion"?, "detail"? }。終了コード：0 成功、1 使用方法の誤りまたは拒否された操作、2 ファイルが見つからない / 出力ファイルがすでに存在する / ファイルが GenOffice で開かれている、3 変換に失敗、4 アプリを利用できない。error は機械可読な理由（「コマンドが失敗した場合」の表を参照）、suggestion は次の手順を示す1文です。コマンド、オプション、操作名、要素 ID、シート名に1文字だけの入力ミスがある場合は、did you mean "…"? も含まれます。detail にはフィールドとして事実が含まれます（index、op、error、reason、valid_range、available、supported、usage を含む failures[]、sheets、options、commands）。message は解析しないでください。

コマンド

Command	What it does
genoffice info <file> [--password <pw>]	メタデータと構造の概要（docx のブロックと見出し、pptx のスライド、xlsx のシート、pdf のページ）
genoffice convert <file> --to <fmt> [--out <path>] [--force]	pdf→docx/pptx/xlsx、csv→xlsx、xls/xlsb/ods→xlsx、md→docx/html、docx→html/md、html→docx、xlsx→csv（--sheet）、および docx/xlsx/pptx/md/html→pdf
genoffice create --type pptx --ops <file> --out <path>	スライド操作のリストから新しいデッキを作成します
genoffice create --type pptx --spec <dir|file> [--outline <file>] --out <path> [--render [dir]] [--audit]	ページ仕様ファイル（スライドごとに1つ、名前順）または1つのデッキ仕様ファイルから新しいデッキを作成します。ピクセル単位で配置するテキスト、図形、画像を指定します（デザイン済みデッキの作成方法。以下を参照）
genoffice create --type xlsx --from <data.csv | table.json> [--header] [--decimal ,] --out <path>	CSV または2次元配列／{sheets:[{name,rows}]}から新しいブックを作成します。"=..."セルは数式です。--headerを指定すると1行目を固定し、範囲にフィルターを設定します
genoffice create --type docx --from <text.md | fragment.html> --out <path>	Markdown または制限付き HTML フラグメントから新しい Word 文書を作成します
genoffice create --type pdf --from <document> --out <path>	md/html/docx/xlsx/pptx ファイルから GenOffice レンダラーで PDF を出力します
genoffice slides read <pptx> [--slide n] [--full | --max-chars n] [--layouts] [--units in|cm|pt|px] / genoffice slides apply <pptx> --ops <file> [--dry-run]	ID、ジオメトリ（boxとsizeは EMU 単位。--unitsを指定すると、指定したunitに変換されます）、テキストのプレビュー（300文字で切り詰め、末尾は…(+n chars)となり、truncated: trueが付きます。--max-charsで上限を変更できます。--fullでは全文、すべての表の行、発表者ノートを表示します）を確認してから、ops で編集します。テキスト要素にはeffective（最初の run のフォントサイズ／ファミリー／色／太字／斜体、および段落の配置）と、各値の取得元を示すsrc（run、paragraph defRPr、shape lstStyle、layout placeholder、master placeholder、master titleStyle／bodyStyle、presentation defaultTextStyle、theme major／minor）が含まれます。setFontは run レベルに書き込み、これらすべてを上書きします。applyThemeはテーマのフォントと色を変更します。ハイパーリンクを持つ要素にはlink（url、スライドへのジャンプ、または PowerPoint のaction：nextslide／previousslide／firstslide／lastslide／lastslideviewed／endshow）が含まれます。setLinkとsetTextの run のlinkフィールドは、同じ3種類を書き込みます。
genoffice slides audit <pptx> [--slide n] / genoffice slides render <pptx> --out <dir> [--scale 2]	ジオメトリを監査します（out_of_bounds、off_slide、text_overflow、text_overflow_width、overlap、picture_distorted＝ボックスの縦横比がトリミング済みの元画像と5％超異なる）。issues[]にはcode、level、path（s_n/e_*）と、overlap以外の場合はsetTransform op のsuggestが含まれます。これはそのままslides applyに渡せます。確認用に、スライドごとに PNG を1つ出力します
genoffice render <file> --out <dir> [--page n] [--scale 2] [--el e_12 [--pad px]] [--grid [--cols 4] [--tile 320]]	GenOffice レンダラーでレイアウトした docx、xlsx、pptx、md、html、pdf ファイルのページごとに PNG を1つ出力します。文書やブックの完了を報告する前に、レンダリング結果を確認してください。--el（pptx）を指定すると、1つの要素に合わせてページをトリミングした画像（<stem>-NN-e_12.png。ID はslides readで確認できます）も出力され、小さなボックスも読みやすくなります。--gridを指定すると、すべてのページを1枚のコンタクトシート（<stem>-grid.png。行優先で配置し、タイルの位置はgrid.tilesに記載）にも出力され、デッキ全体を一度に確認できます
genoffice slides check <outline.json|page.json> / genoffice slides replace <pptx> --slide n --spec <page.json>	デッキのアウトラインを検証します（エラーがある場合は終了コード1）。または、1つのページファイルを作成して監査し、アウトラインの該当エントリーおよび style.md と照合します。ページファイルから1枚のスライドを再作成します。他のスライドには変更を加えません
genoffice sheet read <xlsx> [--sheet name] [--range A1:D20] [--cols A,C:E] [--max-rows n] [--where formula|error|empty|number|text] [--stats] [--formats] / genoffice sheet apply <xlsx> --ops <file> | --cells <file> / genoffice sheet check <xlsx>	範囲とfeatures（シートのペイン、フィルター、グラフ、表、ルールの件数。範囲内の結合セルとリンク。--formatsを指定するとセルの書式、列幅、行の高さも追加）を読み取ります。--cols（指定した列のみ。columnsに列名を記載）、--max-rows（rowsShown／rowsTotalと、続きを取得するための--rangeを記載したnote）、--where（指定した種類のセルのみを{ref, value, formula}として出力し、グリッドは表示しません）、--stats（件数、使用範囲、シートのリストのみを出力し、セルは表示しません）で出力を小さくできます。ブック DSL またはセルアドレスを使って編集します。checkは数式エラー、存在しないシートへの参照、壊れた定義名、データ範囲から外れたグラフ範囲、###列（set_col_widthの提案付き）、プレースホルダーテキスト、既存のルールを一覧表示します
genoffice docs read <docx> [--range a-b] [--html] [--full \ / genoffice docs compare <original.docx> <revised.docx> --out <redline.docx> [--author name] [--date ] [--granularity word	char] [--ignore formatting,case,whitespace]`
genoffice merge <template.docx|pptx|xlsx> --data <values.json | inline JSON> --out <path> [--force] [--strict]	JSON オブジェクトから Word、PowerPoint、Excel のテンプレート内の{{key}}プレースホルダーを入力します。ネストされたオブジェクトはドット区切りのキーa.bに展開され、波括弧内の空白も許容されます。各エンジン独自の検索／置換（Word、PowerPoint：テキスト、表、発表者ノート）と、型を保持するset_cellへの書き込み（Excel：セル全体を占めるプレースホルダーには値の型が引き継がれ、数値は数値のままです。置換されたテキストは=で始まってもテキストのままです）を使用します。何が起きたかはdetail.used_keys、detail.unused_keys、detail.unresolved_placeholders[]（{placeholder, key, reason: no_key | split_placeholder | unreachable_nested, location}。location はブロックインデックス／スライド＋要素 ID／シート＋セル）で確認できます。未解決のプレースホルダーはそのまま残り、--strictでエラーにしない限りunresolved_placeholder警告が付きます。split_placeholderは、Word で書式の異なる複数の run に{{…}}が分割されている状態です。テンプレートで1つの run に入力し直してください（PowerPoint では run をまたぐプレースホルダーも入力できます）。unreachable_nestedは、ネストされた pptx グループ内（またはグループ内の表）にあるため、デッキのfindReplaceで到達できないことを示します。グループ解除してください。Word の表で何も入力されない場合、その表は変更されません
genoffice pdf read <pdf> [--page n | --range a-b] [--password <pw>] [--full | --max-chars n]	PDF のテキストレイヤーをページごとに読み取ります。1始まりのpage、width_pt／height_pt、4000文字で切り詰めたtext（末尾は…(+n chars)となり、truncated: trueが付きます。--max-charsで上限を変更でき、--fullで上限を解除してすべてのページを読み取ります）に加え、ページ数、encrypted、タイトル／作成者／生成元のメタデータを返します。--page／--rangeを指定しない場合は最初の20ページを返し、残りのページはdetail.truncatedに記載されます。スキャンされたページのテキストは空です（convert --to docxは OCR を実行します）
genoffice guide <slides|docs|sheets> [group|op|design|spec] [--json] [--index] [--fingerprint]	各ドメインの op リファレンスです。applyが検証に使うものと同じ定義から生成されます（ops を記述する前にお読みください）。リクエストに応じて、1つのグループまたは1つの op とその JSON スキーマを表示します。デッキの作成にはslides design／slides specを使用します
genoffice search <query> [--images] [--max n]	GenOffice で設定されたプロバイダーを使ってウェブ／画像を検索します。detail.results[]は{title,url,snippet}です
genoffice image <prompt> [--out f.png] [--aspect 16:9] [--ref a.png,b.png] [--model <name>]	設定済みのプロバイダーで画像を生成して保存します。detail.mime、output_path
genoffice media <file|url> [--ask <question>]	画像、動画、音声ファイルを説明するか、質問に回答します。回答はsummaryとdetail.textに含まれます
genoffice capabilities	GenOffice で設定されているクラウド機能（検索、画像検索、画像生成、メディア分析）と、アプリがインストールされているかどうかを表示します。ネットワーク呼び出しは行いません
genoffice open <file> [--slide n [--el e_12] | --block n | --range [Sheet!]B2:D5 | --page n]	（ユーザーがそこでファイルを見たいと求めた場合に限り）GenOffice アプリでファイルを開きます。対象を指定すると、そのスライド要素／ブロック／範囲／ページまでスクロールして選択し、ユーザーが同じ位置を見られるようにします（target_not_found／out_of_rangeが返される場合は、有効な ID または範囲も返されます）
genoffice selection <file> --json	ファイルを表示しているエディターでユーザーが選択した内容を返します：{slide, elements[], types[]}、{blocks:[a,b], text, collapsed}、{sheet, range, values?}または{page, text?}。編集前に、そこから「これ」／「ここ」が何を指すのか判断してください。ファイルを表示しているタブがない場合はfile_not_open_in_guiを返します
genoffice skill list / genoffice skill install <agent|all> [--dir <path>] [--force] / genoffice skill path	このマシンで見つかったコーディングエージェント（Claude Code、Codex、Cursor、Gemini CLI、Copilot、OpenCode、Windsurf）と、それぞれが持つスキルのバージョンを表示します。このスキルを各エージェントのスキルディレクトリにコピーまたは更新するか、同梱の SKILL.md を出力します。このコマンドまたは「設定」→「インテグレーション」でのクリックなしに、何かがインストールされることはありません
--ops - と --cells - は標準入力を読み込みます。--out の既定値は、入力ファイルのフォルダーに新しい拡張子で出力（convert）するか、入力ファイルを直接編集（apply）するかです。不明なオプションは拒否されます（終了コード 1）。mcp サーバーは既定で標準入出力を使用します。mcp [--http <port> [--host <addr>] [--token <secret>]] を指定すると、代わりに Streamable HTTP で提供されます。`genoffice mcp install <agent	all> [--dir ] [--force] は、標準入出力サーバーをコーディングエージェントの MCP 設定に登録します（mcp uninstall で削除し、mcp list` で各エージェントを表示します）。

MCP クライアントとしての genoffice mcp からは、次のように利用できます。

• ツールは各コマンドに 1 対 1 で対応します（info、convert、create_docx / create_xlsx / create_pptx / create_pdf、docs_read / docs_apply / docs_check、sheet_read / sheet_apply / sheet_check、slides_read / slides_apply / slides_audit / slides_render / slides_check / slides_replace、render、guide、capabilities、search、image、media、open、selection）。ops、cells、specs、Markdown はインラインで渡し、結果は --json のエンベロープ形式になります（バッチの一部が失敗した partial は isError ではありません。最初のテキストブロックに失われた ops が列挙されます）。open と selection は標準入出力でのみ使用できます。
• deck_start / deck_page / deck_build / deck_replace は、上記の段階的なデッキ作成フローです。デッキフォルダーを状態として使用します。具体的な内容を含む短いデッキであれば、create_pptx を 1 回呼び出すだけで作成できます。
• op の参照先はリソースです。genoffice://guide/docs、…/sheets、…/slides、…/slides/design、…/slides/spec。
• ops、cells、data には、guide <domain> --json の op ごとのスキーマが含まれます（各 op に 1 つのバリアントがあり、op、フィールド、必須項目を指定します）。コンテキストの予算が限られているクライアント向けに、mcp --compact-schemas（または GENOFFICE_MCP_COMPACT_SCHEMAS=1）を指定すると、プレーンな配列として通知されます。
• --http：ファイルは呼び出しとともに送信します（PUT /files/<name> でファイルをアップロードすると URL が返されます。すべてのパスパラメーターに http(s) URL も指定できます。out を省略すると、ファイルのダウンロード URL が返されます）。
• GenOffice アプリは、127.0.0.1:3093（Settings → Integrations）で独自の MCP サーバーを実行します。このサーバーのツール（create_session、read_document、apply_ops、apply_slide_ops、apply_sheet_ops、read_pdf、open_documents）は、表示中のエディターで既に開いているドキュメントを編集します。genoffice mcp はディスク上のファイルを操作します。

使用するコマンド

タスク	コマンドパス	対象外
短い概要からプレゼンテーションを作成する	guide slides design → style.md + outline.json → ページごとに slides check → create --type pptx --spec → render --grid → slides audit	既存のデッキを編集する（slides apply）；フィクスチャデッキ（create --type pptx --ops）
既存のデッキのテキスト、画像、またはスライドを1つ変更する	slides read → slides apply --ops → slides audit → render --page	デッキ全体のスタイルを変更する（applyTheme op、または段階的な手順で再構築する）
データからワークブックを作成する	create --type xlsx --from data.csv | table.json → 書式やグラフには sheet apply --ops → sheet check	既存ファイルの1つのセルを修正する（sheet apply --cells）
既存のワークブックのセル、書式、グラフ、ルールを編集する	sheet read → guide sheets <op> → sheet apply --ops → sheet check	refresh_pivot、セッションテーブル、図形（エディターが必要なため拒否されます）
テキストからWord文書を作成する	create --type docx --from report.md | fragment.html → docs check → render	実際のWebページ（convert page.html --to docx）
既存のWord文書を編集する	docs read → docs apply --ops → docs check	テキストを読む（convert --to md または docs read --full）
ユーザーのファイルをソース資料として読む	convert --to md/csv または <domain> read --full --json	Officeファイルに対する unzip/cat；render（テキストではなくピクセル）
ファイル形式を変更する	convert <file> --to <fmt>	内容を変更すること（先に編集し、その後で変換する）
ページの見た目を確認する	render（--page、--el、--grid）	テキストやIDを抽出する（read）
ユーザーに特定の場所を示す、または選択した内容を操作する	open <file> --slide/--el/--block/--range/--page → selection <file> --json	内容を読む（read）；ユーザーが開いていないファイル（selectionにはタブが必要です）
opのフィールドを調べる	guide <domain> [group|op] [--json]	このファイルから推測すること：ガイドはバリデーターから生成され、常に最新です
別のエージェント（または新しいマシン）にこのスキルを渡す	skill list → skill install <agent>（または skill path を実行してファイルをコピー）	スキルを手作業で記述すること；install-cli（genofficeをPATHに追加します）

Behaviour to know

• Word (docs)：1 回のバッチ内のブロックインデックスは逐次反映されます。insert_content で 2 つのブロックを追加すると、後続のインデックスは 2 つずつずれます。一致するブロックがないターゲットがあると、バッチ全体が失敗します（終了コード 1）。findReplace は表のセルには適用されません（表では replace_blocks を使用してください）。制限されたセット以外のタグは、通知なく削除されます。convert docx→md は GFM を出力します。& < > はエンティティになり、数式は $…$ になり、画像は削除されて detail.skipped に件数が記録されます。create --from x.md は相対パスで参照されているローカル画像を埋め込みます。insert_image はローカルパス（現在のディレクトリを基準とし、次に ops ファイルを基準とします）、data: URL、または http(s) URL（png/jpg/gif）を受け取り、afterBlockIndex が指定されていない場合は末尾に追加します。edit_chart のターゲットには、docs read が kind chart として一覧表示するブロックを指定します。set_header_footer は {PAGE} / {NUMPAGES} トークンを含むプレーンテキストを書き込みます。view: "first" を指定すると、先頭ページのみ別のヘッダー／フッターを設定する機能が有効になります。コメント ID は docs read --comments で取得します。add_comment は文書テキストを変更せずに、ブロックまたはブロック内の正確な text 範囲（複数の一致箇所から選ぶ場合は occurrence を指定）に新しいスレッドを紐付けます。返信のあるスレッドのルートに対して delete_comment を実行するには、withReplies: true が必要です。リビジョン ID（r1、r2、…）は docs read --revisions で取得でき、位置に基づきます。そのため、accept_changes / reject_changes の前に編集を行った場合は、もう一度読み込んでください。insertField は SEQ 番号、REF テキスト、DATE、MERGEFIELD をローカルで計算します。PAGE / NUMPAGES / AUTHOR 形式の結果は、Word で開くと再計算されるプレースホルダーです（docs check では情報として報告されます）。そのため、ファイルを引き渡す際にはその旨を伝えてください。edit_note / delete_note のノート ID は docs read --notes で取得します。edit_note は 1 つのノート内で findReplace を実行し（{ id, find, replace, matchCase? }。脚注と文末脚注で ID が共有されている場合に限り kind を指定）、ノートの ID、参照記号、書式を維持します。findReplace 自体はノートのテキストには適用されません。define_style は指定したフィールドのみを更新します（既存のスタイルでは、それ以外のフィールドは維持されます）。applyStyle は docs read --styles にある段落スタイル ID を受け取り、見出しスタイルの場合はブロックを見出しに変換します。text: null を指定した set_watermark はウォーターマークを削除します。insert_picture / insert_text_box の長さには、2.54cm / 1in / 72pt / 96px またはポイントを指定できます。set_page_setup は、すべてのセクション、または 1 つのセクション（section: N または blockIndex）の用紙／向き／余白／段組み／titlePg／ページ番号を変更します。長さは "2.54cm" / "1in" / "72pt" で指定します。insert_section_break はブロックの後でセクションを分割します（分割後のセクションは set_page_setup section: N で変更します）。docs read --sections は、各セクションとそのブロック範囲を一覧表示します。ネイティブ表では、構造操作として insertTableRow / deleteTableRow / insertTableColumn / deleteTableColumn（0 始まり、position: "before"|"after"、count）、mergeTableCells / splitTableCell（グリッドの range / cell。既存の結合セルをまたぐ結合は拒否されます）、setTableCellFormat（塗りつぶし、vAlign、罫線、twips または "2.5cm" 単位の width）、setTableStyle（docs read の tableStyles にあるスタイル ID と表示フラグ）を使用できます。nodeType: "table" を指定してターゲットにします。docs read には各表の rows、cols、結合された merged セルが表示されます。
• Excel (sheet)：ops は順番に実行され、それぞれ直前の結果を反映します。insert_rows / delete_cols の後続の ops は、移動後のグリッドを対象とします（移動後に書き込まれた数式は指定どおりに保存され、移動前に書き込まれた数式は既存の数式と同様に移動します）。バッチ内で先に追加または名前変更されたシートは、新しい名前で指定します。ルール、リンク、ノート、フィルター、ビジュアルは、そのシートに対する行／列操作の後に実行する必要があります。また、定義名の操作はシートまたは行／列の操作と同じバッチに含められません。= で始まる文字列を set_cell に指定すると数式が書き込まれます。type: "text" を指定すると、文字列としてそのまま保持されます。セル以外にも、sheet apply --ops はグラフ（add_chart、xl/charts/chartN.xml に対する edit_chart）、画像や図形、Excel テーブル、ウィンドウ枠の固定、非表示の行／列、チェック済みの値を含むフィルター、条件付き書式、データの入力規則、ハイパーリンク、ノート、ページ設定、シートの保護、定義名、タブの順序／表示状態を書き込みます（すべてのフィールドについては genoffice guide sheets を参照してください）。--cells の style には、format_range.format と同じオブジェクト（{bold, fillColor, numberFormat, …}）を指定します。色は #RRGGBB、またはブックのテーマに従うテーマスロット（"accent1"、明るくした "accent1+40%"、暗くした "dk2-25%" など）、あるいは {theme, tint} で指定します。fill: {pattern: "lightGray", fg, bg?} または fill: {gradient: {angle, stops: [{position, color}]}} を指定すると、パターン塗りつぶしやグラデーション塗りつぶしを書き込みます。--formats はスロット、色調、解決後の rgb とともに、それらの情報を返します。sheet read は生の値（0.25、シリアル日付）と数式を別々に返し、features（シート全体のウィンドウ枠、フィルター、グラフ、テーブル、ルールの件数、および範囲内の結合セルとリンク）も返します。また、--formats を指定すると、書式が設定されたセル、列幅（px）、行の高さ（pt）も返します。convert --to csv は表示テキスト（パーセント、日付）を UTF-8（BOM 付き）、CRLF の行末で返します。対象はアクティブなシートですが、--sheet で指定できます。create --from x.csv では、先頭行の sep=; を認識します。ISO 日付（2024-01-01、2024-01-02 09:30）は日付書式が適用された実際の日付になり、--decimal , を指定すると 1.234,5 を 1234.5 として読み取ります。ローカルエンジンで評価できない関数（FILTER、SORT、UNIQUE、LET、…）を使用する数式は、キャッシュ値なしで書き込まれ、Excel で開くと計算されます。スピル数式は動的配列として保存されるため、Excel 365 でスピルします。formulas_not_cached 警告には、それらのセルが記載されます。
• PowerPoint (slides)：画像操作（addPicture、replacePicture、addMedia、setImageFill、setBackground）の bytes には、ローカルパスまたは data URL を指定します。拡張子は自動的に判定されます。setText の run は、フィールドを明示的に設定しない限り（bold: false など）、要素の最初の run のスタイルを継承します。1 回の apply バッチ内の ops は順番に実行されるため、後続の op は先行する op が追加したスライドを対象にできます。アトミックモードでは、すべての op が適用されない限り何も書き込みません。--best-effort（以前の --isolation per_op）と --stop-on-error は、適用された内容を書き込み、status: "partial" を返します。作成された要素には新しい e_* ID が割り当てられます。ターゲットを指定する前に、もう一度 slides read を実行してください。convert pptx→pdf はアプリのエクスポートと同様にレンダリングされ、各スライドが 1 枚のビットマップになり、テキストレイヤーはありません。すべての EMU 長さフィールド（box、offset、dx/dy、wEmu/hEmu、colWidthsEmu、insets）には、単位の接尾辞を含む文字列（"2.54cm"、"1in"、"10mm"、"12pt"、"96px"）も指定できます。slides read は、各ページの animations[]（seq、el、effect、kind、trigger、durationMs、delayMs、direction）を一覧表示します。addAnimation / removeAnimation / reorderAnimation は、タイムライン内の 1 つの項目を編集します（presetXml は、PowerPoint からエクスポートされたエフェクトをそのまま渡します）。insertEquation は LaTeX から組版済みの数式を追加します（PowerPoint ではレンダリングされ、プレビューには線形式のテキストが表示されます）。
• アプリ内の変換（→pdf、docx→html、html→docx、create --type pdf、render）：呼び出しごとに非表示の GenOffice プロセスが起動し、所要時間は 1～6 秒、タイムアウトは最大 180 秒です。並行して安全に実行できます。実際の Web ページには html→docx で html2docx を使用します。<formula> を含む制限付き HTML フラグメントは、代わりに create --type docx --from fragment.html を通して処理します。
• クラウド（search、image、media）：--images は detail.images[] {title,imageUrl,sourceUrl,source,width,height} を返します。プロバイダーが返す件数は --max より少ない場合があります。image はプロバイダーが実際に使用した形式で保存します（output_path で確認できます。.png を指定しても .jpg が返されることがあり、その場合は detail.note に記載されます）。--aspect / --size はローカルで検証されます。

ワークフロー

1. genoffice info または genoffice <domain> read --json を使って構造を確認します：ブロックインデックス（docx）、s_<n> / e_* ID と EMU のジオメトリ（pptx）、シート名とセルの値（xlsx）。
2. genoffice guide <domain> で操作のフィールドを確認し（1 つの操作のスキーマは guide <domain> <op> --json）、ops JSON を自分で作成します。
3. バッチが大きい場合は genoffice <domain> apply --dry-run を実行します。拒否された操作は、実行ツールの使用方法を示す行とともに op_rejected として返されます。その操作を修正し、バッチ全体を再送信します。デフォルトではアトミックです。拒否時、ファイルは変更されず、detail.batch は {total, applied: 0, failed, skipped} になります。--best-effort は適用可能なすべての操作を適用し、--stop-on-error は最初に拒否される操作まで順に適用します。どちらもファイルを書き込み、失敗した操作は detail.failures に、件数は detail.batch に含めて status: "partial"（終了コードは 0）を返します。プログラムでは終了コードだけでなく、status も確認する必要があります。
4. 以下の QA ゲートを通過させてから、出力パスを報告します。

注意点

落とし穴	ルール
slides read/audit/render/replace --slide n と op の対象 { "slide": n } は0 始まりです。render --page n は1 始まりです。docx のブロックインデックスは 0 始まりです	s_0 は PNG の 1 ページ目です。
--ops -、--cells -、--spec - は標準入力を読み込みます（--from は読み込みません）。それ以外の値には、既存のファイルを指定する必要があります	存在しないパスは空のバッチではなく、file_not_found になります。
構造編集によって番号が振り直されます。addElement の後は新しい e_* ID、スライド追加後は s_*、insert_content／delete_blocks の後は docx のブロックインデックスが変わります	1 つのバッチ内ではインデックスは都度更新されます（後続の op には先行する結果が反映されます）。次のバッチの前に、もう一度 read を実行してください。
EMU フィールド（offset、box、dx／dy、wEmu／hEmu、colWidthsEmu、insets）には、整数または "2.54cm"、"1in"、"10mm"、"12pt"、"96px" のような単位付き文字列を指定します	914400 を自分で乗算しないでください。slides read は EMU の整数を返します。
CSV のインポートでは、先頭行の sep=; が尊重されて削除され、ISO 形式の日付は実際の日付に変換されます。1.234,5 には --decimal , を指定します	--header を指定すると 1 行目が固定され、フィルターが追加されます。指定しない場合、先頭行はデータとして扱われます。
ローカルエンジンで評価できない数式（FILTER、SORT、UNIQUE、LET、LAMBDA など）は、キャッシュ値なしで書き込まれます	formulas_not_cached 警告に該当する数式が一覧表示されます。Excel でファイルを開くまで、sheet read には数式のみが表示され、値は表示されません。エラーではありません。
sheet apply は、ファイル内の現在のタブ名をタブに表示されたとおりに指定してシートを指定します	sheet_not_found には detail.sheets と did you mean が含まれます。
構造的なシート op（行、列、シートの挿入／削除）を実行すると、同じバッチ内で後続する op のアドレスもずれます。定義名の op はシートや行／列の op と混在させないでください	後続の op には、ずれた後の座標を指定してください（または構造 op を最後に配置してください）。ルール、リンク、メモ、フィルター、ビジュアルは、対象シートの行／列 op の後に配置してください。
GenOffice でファイルをタブ表示している場合、apply は拒否されます（終了コード 2、file_open_in_gui）	タブを閉じるようユーザーに依頼するか、--out other.ext を指定してください。--force は、エディターによる上書きをユーザーが了承した場合に限り使用してください。
create／convert／image は上書きしません（終了コード 2、output_exists）。既存ファイルへの apply --out も拒否されます	別の名前を選ぶか、ユーザーが置き換えを依頼した場合は --force を指定してください。
apply --best-effort／--stop-on-error（以前の slides apply --isolation per_op）は、終了コード 0 で status: "partial" を返します。check／audit は問題を detail に含めて終了コード 0 を返します	status、detail.batch、detail.failures／detail.issues を確認してください。終了コード 0 は「問題なし」を意味しません。
デッキの仕様は 1280×720 キャンバス上の px 単位で、op は EMU 単位です	1 つのファイル内で両者を混在させないでください。
convert pptx→pdf にはテキストレイヤーがありません。convert docx→md は画像を除外します（detail.skipped）	すべての語句が必要な場合は docs read --full を使用してください。
docs findReplace は表のセルをスキップします。insert_content 内の未知の HTML タグは、通知なしに除去されます	表ブロックには replace_blocks を使用してください。制限された HTML セットの範囲内に収めてください（guide docs）。

コマンドが失敗した場合

error に基づいて分岐し、suggestion の指示に従ってから、バッチ全体を再送してください（アトミック適用では何も書き込まれていません）。detail には事実がフィールドとして含まれているため、message を解析しないでください。

error	次のコマンド
unknown_command, unknown_option	suggestion の did you mean を使用します。detail.commands／detail.options に有効な項目が一覧表示されます。このスキルがアプリより古い場合は、genoffice <command> --help を実行します
missing_argument, invalid_argument	message で指定されたフラグを修正します。genoffice <command> --help にフラグが表示されます
invalid_json	ops ファイルを再シリアライズします。--ops - を使ってパイプで渡す場合は、引用符を確認します
unknown_op	detail.failures[].supported と did_you_mean を確認します。一覧は genoffice guide <domain> で確認できます
op_rejected	detail.failures[].usage は実行ツールの使用方法を示す行です。スキーマは genoffice guide <domain> <op> --json で確認し、該当する操作を修正します
unresolved_placeholder	merge --strict を実行します。detail.unresolved_placeholders[] に各プレースホルダーとその場所が示されます。キーを --data に追加するか、テンプレート内の split_placeholder を修正して、再実行します
target_not_found	detail.failures[].available に、そのスライド上または一致するブロックの ID が一覧表示されます。それ以外の場合は、genoffice <domain> read <file> --json を実行して対象を指定し直します
out_of_range	detail.failures[].valid_range（または detail.valid_range）を確認します。現在の件数は read で確認できます
sheet_not_found	detail.sheets にファイル内のタブ名が表示されます。その名前をそのまま使用します
file_not_found	パスを確認します（現在のディレクトリからの相対パスです）。--ops では、- は標準入力を意味します
output_exists	別の --out を指定するか、ユーザーが置き換えを求めている場合は --force を指定します
file_open_in_gui	ユーザーにタブを閉じてもらうか、--out を指定して書き込みます。--force は同意がある場合に限ります
file_not_open_in_gui	selection／open --el を使うには、ファイルがタブで開かれている必要があります。まず genoffice open <file> を実行し、次にユーザーに選択を依頼します
outside_allowed_roots	GENOFFICE_ALLOWED_ROOTS の範囲内に留まり、別の場所を試さないでください
resource_limit	パッケージのパーツが多すぎるか大きすぎる、圧縮率が不自然に高い、またはエントリパスがアーカイブの外に出ています。detail に該当するエントリと制限が示されます。再試行せず、ユーザーに伝えてください
unsupported	detail.supported にこのコマンドが受け付ける項目が一覧表示されます。上の表から別の方法を選んでください
conversion_failed, app_unavailable	ファイルまたはアプリに問題があります。一度だけ再試行してください。capabilities --json でアプリが見つからないと示された場合は、ユーザーに伝えてください（PDF および →html／html→ の方法には GenOffice が必要です）
app_crashed	ヘッドレスエクスポート中に GenOffice がクラッシュしました（detail.signal）。一度だけ再試行してください。再発した場合は、ユーザーに伝え、ドキュメント名と suggestion に記載されたクラッシュログのパスを伝えてください
成功した結果にも、warnings[]（{code, message, suggestion?}）が含まれる場合があります。formulas_not_cached、op_warning（シートの操作が調整された）、images_dropped（convert docx→md）、output_renamed（image がプロバイダーの実際の拡張子で保存された）、unresolved_placeholder（merge で値のないプレースホルダーがそのまま残された）です。内容を確認し、重要な点を報告してください。再試行はしないでください。

「完了」と伝える前に

成果物ごとに、毎回次の3行を確認してください。

成果物	1. 確認	2. 表示	3. 報告
スライドデッキ	slides audit deck.pptx --json → detail.issues が空であること（そうでない場合は suggest の操作を適用）	render deck.pptx --out shots --grid --json を実行し、コンタクトシートを開く	.pptx のパスと、そのままにした箇所
ワークブック	sheet check book.xlsx --json → formula_error、missing_sheet_ref、number_overflow がないこと（set_col_width の提案を適用）	render book.xlsx --out shots --json を実行し、シートの PNG を確認	.xlsx のパス。キャッシュされていない数式があれば、その名前を報告
ドキュメント	docs check report.docx --json → 修正可能な broken_ref、placeholder_left、field_not_evaluated がないこと	render report.docx --out shots --json を実行し、1ページ目と最終ページを確認	.docx のパス

check／audit は、問題が見つかったかどうかにかかわらず終了コード 0 を返します。検出結果は detail.issues[] にあり、安定した code、path、および可能な場合は、そのまま apply に渡せる suggest 操作が含まれます。ユーザーが GenOffice でファイルを表示するよう求めない限り、genoffice open は実行しないでください。

ユーザーのファイルを読む

ユーザーから渡されたソース資料（スライドにするレポートや、要約するワークブックなど）は、genoffice ではなく、あなたが読みます。md、txt、csv、pdf、画像は直接開いてください。Office ファイルは ZIP 形式の XML なので、まず CLI を使用してください。

• docx：全文を取得するには genoffice convert file.docx --to md --out file.md を使います（画像は除外されます）。インデックス付きのブロックを取得するには、genoffice docs read file.docx --full --json または --html を使います。
• xlsx：シート全体を表示テキストとして取得するには genoffice convert file.xlsx --to csv --sheet <name> --out file.csv を使います。生の値を取得するには genoffice sheet read file.xlsx --range A1:H200 --json を使います（--range を指定しない場合は、500 行で停止し、truncated: true と表示されます。まず --stats でワークブックのサイズを確認し、幅広いシートや行数の多いシートをページ分けするには --cols／--max-rows を使います。数式のみを取得するには --where formula を使います）。
• pptx：すべてのスライドのテキスト、表、発表者ノートを取得するには genoffice slides read file.pptx --full --json を使います。ページを確認する必要がある場合は genoffice slides render file.pptx --out shots を使います。
• pdf：自分で PDF を開けない場合（パスワード保護されたファイルの場合や、ページサイズとメタデータが必要な場合）は、genoffice pdf read file.pdf --range 1-20 --json を使います。

内容から数値や表現を取得してください。Office ファイル自体に対して cat や unzip を実行しないでください。

デッキの作成

ユーザーがどんなに短くてもプレゼンテーションを求めた場合、ops を手作業で配置しないでください。GenOffice アプリ自体が使う段階的なパイプラインに従ってください。モデルであるあなたが設計し、genoffice がエンジンとなります。各段階はファイルとして作成され、CLI が次の段階を開始する前に確認します。ops（create --ops、slides apply）は、すでに存在するデッキを編集するためのものです。

1. セッションごとに genoffice guide slides design を一度実行し、続けて genoffice guide slides spec を実行します。genoffice capabilities --json を一度実行すると、GenOffice で検索、画像検索、画像生成が設定されているか確認できます。設定されている場合に限り、事実情報や写真のために利用し、そうでない場合は写真を使わないページを計画します。
2. デッキ用のフォルダーを作成します。スタイルシートを deck/style.md に記述します（色、フォント、レイアウトのバリエーション、スタイルを一文で表したもの）。次にアウトラインを deck/outline.json に記述します（核となるフックと、ページごとにタイトル、種類、レイアウト、実際の数値を含む概要、image_queries を一つずつ）。その後、genoffice slides check deck/outline.json --json を実行し、先に進む前にすべてのエラーを修正します。ユーザーから確認を求められた場合にのみ、アウトラインを見せます。
3. ページごとに一段階ずつ進めます。deck/style.md と該当ページのアウトライン項目を読み直し、写真を決めて、deck/pages/NN.json に記述します（項目の title、type、layout を反映したページオブジェクトを一つ）。genoffice slides check deck/pages/NN.json --json を実行します。このコマンドは一つ上のフォルダーにある outline.json と style.md を見つけ、そのページを項目 N および配色と照合します。detail.audit、detail.outline.findings、detail.style.offPalette が空になるまで修正してから、次のページに進みます（アウトラインと一致しない場合は終了コード 1 になります）。複数のページを一つのファイルに書いたり、一度に作成したりしないでください。
4. genoffice create --type pptx --spec deck/pages --outline deck/outline.json --out deck/deck.pptx --json を実行します（アウトラインのページにファイルがない場合、またはページが項目と一致しない場合は実行を拒否します）。次に genoffice slides render deck/deck.pptx --out deck/shots --json を実行して PNG を確認し、genoffice slides audit deck/deck.pptx --json でジオメトリに関する指摘を確認します。ページをファイル内で修正し、genoffice slides replace deck/deck.pptx --slide n --spec deck/pages/NN.json --json を実行します。修正は最大 2 回までです。
5. パスを報告します。写真には genoffice search --images の結果、genoffice image、またはユーザーが提供したローカルファイルを使います。写真の代わりに灰色のボックスを描かないでください。数値はユーザーの資料または genoffice search から取得します。数値が例示用の場合は、その旨を伝えます。

既存のデッキの編集

スライド一枚の書き直し、新しいタイトル、画像の差し替えには、段階的なパイプラインではなく ops を使い、デッキ独自のデザインを維持します。

1. 要素 ID と現在のテキストを確認するには genoffice slides read deck.pptx --slide n --full --json を実行します。テキストだけではページの見た目がわからない場合は、genoffice slides render deck.pptx --slide n --out shots --json を実行します。
2. 既存の要素には setText を使います（スタイルを指定せずに残した runs は、元のフォント、サイズ、色を継承します）。新しいコンテンツには addElement / addPicture を使い、削除する要素には deleteElement を使います。ユーザーが元のファイルを残したい場合は、--out を指定して書き込みます。
3. 編集後に genoffice slides audit deck.pptx --slide n --json を実行します。同じボックス内の文が長くなると、はみ出すことがあります。返された suggest ops を適用してボックスを広げるか移動し、もう一度レンダリングして確認します。
4. 編集した要素の ID は変わるため、ops を二度目に実行する前に slides read を再実行します。slides replace --slide n --spec は spec からページを再構築するもので、段階的なパイプラインで作成したデッキに使います。ユーザーが用意したデッキのスタイル変更には使いません。

例

ops からデッキを作成（既存デッキの編集、またはフィクスチャの場合。人向けのプレゼンテーションは上記の段階的な手順で作成します）：

[
  {
    "op": "addElement",
    "target": { "slide": 0 },
    "kind": "textbox",
    "offset": { "x": 914400, "y": 685800, "cx": 7315200, "cy": 914400 },
    "paragraphs": [{ "runs": [{ "text": "Q3 Review", "bold": true, "fontSize": 36 }] }]
  },
  { "op": "addBlankSlide", "target": { "slide": 0 } },
  {
    "op": "addTable",
    "target": { "slide": 1 },
    "rows": 3,
    "cols": 3,
    "offset": { "x": 914400, "y": 1828800, "cx": 7315200, "cy": 2286000 }
  }
]

genoffice create --type pptx --ops deck.json --out q3.pptx --json

数式を含むワークブックを作成し、その後、書式設定したヘッダーを追加：

echo '[["item","qty","price"],["Apple",2,1.5],["Total","=SUM(B2:B2)",""]]' > table.json
genoffice create --type xlsx --from table.json --out sales.xlsx
echo '[{"op":"format_range","range":"A1:C1","format":{"bold":true,"fillColor":"#FFFF00"}}]' | genoffice sheet apply sales.xlsx --ops - --json

Markdown から Word を作成し、その後、ブロック 0 の後に段落を挿入：

genoffice create --type docx --from report.md --out report.docx
echo '[{"op":"insert_content","afterBlockIndex":0,"html":"<p>Executive summary.</p>"}]' | genoffice docs apply report.docx --ops -

パスのルール

• 絶対パス、または現在のディレクトリからの相対パスを渡してください。genoffice が --out パスの外や編集中のファイル以外に書き込むことはありません。
• create と convert は、--force を指定しない限り、既存の出力ファイルを上書きしません。apply は --out を指定しない場合、ファイルを直接編集します。別の既存ファイルを --out に指定する場合も、--force が必要です。
• GenOffice ウィンドウで現在開いているファイルを genoffice が書き換えようとすると、処理を拒否します（終了コード 2、メッセージ「GenOffice has this file open」）。そのタブを閉じてもらうか、--out で別のパスに書き込むか、エディターが変更を上書きする可能性を承知のうえで --force を指定してください。
• 環境変数 GENOFFICE_ALLOWED_ROOTS が設定されている場合、genoffice は指定されたディレクトリ内でのみ読み書きします（それ以外では終了コード 2）。必ずその範囲内で作業してください。実行したすべてのコマンドは ~/.genoffice/cli-audit.jsonl に記録されます（GENOFFICE_AUDIT_LOG で保存先を変更、または記録を無効化できます）。GENOFFICE_USER_DATA は、genoffice がデフォルト以外の GenOffice プロファイル（開いているドキュメントのレジストリ、AI 設定）を使用するよう指定します。
• 画像操作（addPicture、setImageFill、addMedia）では、bytes フィールドにローカルファイルのパスを指定できます。genoffice がそのファイルを読み込みます。

制限事項

• PDF への変換は GenOffice アプリ内で実行されます（非表示で、1 回あたり数秒かかります）。GenOffice がインストールされているか、GENOFFICE_APP_BIN でその場所が指定されている必要があります。同じ条件は docx→html と html→docx にも当てはまります。
• add_pivot は、targetCell のセルにピボットの値を書き込みます（ファイル内にすでに存在するシート上で、そこに値や数式がないことが条件です）。さらに、Excel が更新できるネイティブのピボットも作成します。ソースの数式はファイルから評価されるため、先行するバッチで設定してください。add_sparkline はデータ行ごとにセル内スパークラインを 1 つ書き込みます（1 回の操作につき最大 200 行）。convert_to_values は、数式をワークブックエンジンがファイルから計算した値に置き換えます（エラーの結果は数式のままです。セルの編集は先行するバッチで行ってください）。set_page_setup では、printTitles、header／footer、rowBreaks／colBreaks も設定できます。ライブエディターが引き続き必要な Excel 操作（refresh_pivot、セッションで作成されたテーブルや図形の編集）は、理由を示して拒否されます。add_conditional_format と set_data_validation は、シートにすでにあるルールに追加します（ルールが設定済みの範囲に対する set_data_validation はそのルールを置き換え、null はルールを削除します）。clear_conditional_formats はルールをすべて消去して新たに設定できる状態にします。
• 書き込み後に数式がワークブックエンジンで評価されるため、sheet read とキャッシュ値を読み取るツールでは数値を取得できます。