{"id":51876012,"url":"https://github.com/harumiweb/xlflow","last_synced_at":"2026-07-25T07:02:06.717Z","repository":{"id":355184346,"uuid":"1225553373","full_name":"harumiWeb/xlflow","owner":"harumiWeb","description":"AI-Agent-ready CLI framework for editing, testing, running, tracing, and diffing Excel VBA projects.","archived":false,"fork":false,"pushed_at":"2026-07-25T02:37:46.000Z","size":26513,"stargazers_count":47,"open_issues_count":6,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-25T04:13:47.365Z","etag":null,"topics":["ai-agents","automation","cli","com","developer-tools","excel","excel-automation","excel-vba","formatter","golang","linting","lsp","spreadsheet","testing","vba","vba-tools","vscode-extension","windows"],"latest_commit_sha":null,"homepage":"https://harumiweb.github.io/xlflow/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/harumiWeb.png","metadata":{"files":{"readme":"README.ja.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-30T11:55:14.000Z","updated_at":"2026-07-25T02:37:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/harumiWeb/xlflow","commit_stats":null,"previous_names":["harumiweb/xlflow"],"tags_count":36,"template":false,"template_full_name":null,"purl":"pkg:github/harumiWeb/xlflow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harumiWeb%2Fxlflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harumiWeb%2Fxlflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harumiWeb%2Fxlflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harumiWeb%2Fxlflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/harumiWeb","download_url":"https://codeload.github.com/harumiWeb/xlflow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harumiWeb%2Fxlflow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35869992,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-25T02:00:06.922Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","automation","cli","com","developer-tools","excel","excel-automation","excel-vba","formatter","golang","linting","lsp","spreadsheet","testing","vba","vba-tools","vscode-extension","windows"],"created_at":"2026-07-25T07:02:06.085Z","updated_at":"2026-07-25T07:02:06.706Z","avatar_url":"https://github.com/harumiWeb.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg width=\"600\" alt=\"xlflow logo\" src=\"docs/images/logo.png\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eExcel VBA development, rebuilt for CLI-first humans and AI agents.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://harumiweb.github.io/xlflow/\"\u003e公式ドキュメントサイト\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"README.md\"\u003eEnglish\u003c/a\u003e\n  |\n  \u003ca href=\"README.ja.md\"\u003e日本語\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n![GitHub Release](https://img.shields.io/github/v/release/harumiWeb/xlflow?include_prereleases) ![WinGet Package Version](https://img.shields.io/winget/v/HarumiWeb.Xlflow) ![Scoop](https://img.shields.io/scoop/v/xlflow?bucket=https%3A%2F%2Fgithub.com%2FharumiWeb%2Fscoop-bucket) ![GitHub License](https://img.shields.io/github/license/harumiWeb/xlflow) ![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/harumiweb/xlflow/total) ![VS Marketplace](https://vsmarketplacebadges.dev/version-short/harumiweb.xlflow-vscode.svg)\n![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/harumiWeb/xlflow) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/harumiWeb/xlflow)\n\n\u003c/div\u003e\n\n# :surfing_man: xlflow\n\n**xlflow** は、AIエージェント時代のための Excel VBA 開発フレームワークです。\n\n`.xlsm` ブック、`.xlam` アドイン、`.xlsb` バイナリブックに閉じ込められがちな VBA を、ソース管理しやすく、CLI から扱いやすい開発ワークフローに変換します。\nVBA のエクスポート、編集、lint、インポート、テスト、デバッギング、実行、差分確認をコマンドラインから行えます。\n\n![Ai-Driven Development](docs/images/ai-drive-develop.gif)\n\n\u003e [!TIP]\n\u003e xlflow は Excel を置き換えるツールではありません。Excel VBA の周囲に CLI ベースの開発ハーネスを用意し、人間・スクリプト・AIエージェントが扱いやすい形にするためのツールです。\n\n## デモ\n\nこれらの [サンプル](example) は xlflow を使用して僅かな自然言語指示のみでAIエージェントによって作成されました。\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" width=\"50%\"\u003e\n      \u003cimg src=\"docs/images/world-news.png\" alt=\"world news\" width=\"100%\"\u003e\n      \u003csub\u003eNewsAPIを使用して世界のニュースを Excel でまとめるマクロ\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"50%\"\u003e\n      \u003cimg src=\"docs/images/stock-price.png\" alt=\"stock price\" width=\"100%\"\u003e\n      \u003csub\u003e株価を取得して Excel に表示するマクロ\u003c/sub\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" width=\"50%\"\u003e\n      \u003cimg src=\"docs/images/gen-qrcode.png\" alt=\"generate qrcode\" width=\"100%\"\u003e\n      \u003csub\u003eセル色表現で QRコードを生成して Excel に表示するマクロ\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"50%\"\u003e\n      \u003cimg src=\"docs/images/tetris.gif\" alt=\"tetris\" width=\"100%\"\u003e\n      \u003csub\u003eExcel 上でテトリスをプレイできるマクロ\u003c/sub\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" width=\"50%\"\u003e\n      \u003cimg src=\"docs/images/space-invader.gif\" alt=\"space invader\" width=\"100%\"\u003e\n      \u003csub\u003eユーザーフォーム上でスペースインベーダーをプレイできるマクロ\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"50%\"\u003e\n      \u003cimg src=\"docs/images/calendar-picker.png\" alt=\"calendar picker\" width=\"100%\"\u003e\n      \u003csub\u003eリッチなカレンダーピッカー\u003c/sub\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" width=\"50%\"\u003e\n      \u003cimg src=\"docs/images/legal_viewer.jpg\" alt=\"legal viewer\" width=\"100%\"\u003e\n      \u003csub\u003e法令データ検索ツール\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"50%\"\u003e\n      \u003cimg src=\"docs/images/maze-big.gif\" alt=\"maze chase\" width=\"100%\"\u003e\n      \u003csub\u003eパックマン風ゲーム\u003c/sub\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## なぜ xlflow が必要か\n\n従来の VBA 開発は、Excel 画面と Visual Basic Editor に強く依存しています。\n小さな手作業の修正であれば問題ありませんが、ソース管理、テスト、差分確認、AIエージェントによる修正、再現可能な実行を考えると扱いづらくなります。\n\n| 通常の VBA 開発でつらいこと                                       | xlflow でできること                                           |\n| ----------------------------------------------------------------- | ------------------------------------------------------------- |\n| VBA コードが `.xlsm` / `.xlam` / `.xlsb` の中に閉じ込められている | `.bas` / `.cls` / `.frm` としてエクスポート・インポートできる |\n| UserFormを宣言的に扱えない                                        | `xlflow form build` で yaml 定義から UserForm を生成できる    |\n| 実行エラーの場所や原因が分かりにくい                              | 構造化エラー、診断情報、debug log を返せる                    |\n| workbook の変更をレビューしにくい                                 | セル値、数式、シート、VBA ソースの差分を確認できる            |\n| AIエージェントが Excel UI を安全に操作しにくい                    | CLI コマンドと安定した JSON 出力を提供できる                  |\n\n```text\npull → fmt → edit → push → lint → test/run → inspect\n```\n\n---\n\n## できること\n\n| 領域                                            | 機能                                                                                                                            |\n| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |\n| ソース管理                                      | 標準モジュール、クラスモジュール、UserForm、Workbook / Worksheet モジュールをエクスポート・インポート                           |\n| 実行                                            | CLI から型付き引数つきでマクロを実行                                                                                            |\n| テスト                                          | VBA のテスト手続きを検出して実行                                                                                                |\n| フォーマット                                    | `.bas` / `.cls` ソースファイルに対する保守的で非破壊な VBA フォーマット                                                         |\n| lint                                            | `Option Explicit` 不足、`Select` / `Activate`、広すぎるエラー処理、暗黙の Variant、Public module field、対話的処理を検出        |\n| デバッグ                                        | terminal log と runtime diagnostic を収集                                                                                       |\n| 差分確認                                        | workbook のセル値、数式、シート構成、VBA ソース差分を比較                                                                       |\n| AIエージェント連携                              | 安定した JSON を返し、Codex / Claude / Cursor / Gemini / GitHub Copilot 風ワークフローなどに使わせるための Skill をインストール |\n| LSPサーバー                                     | 入力補完、定義ジャンプ、リアルタイム診断などを提供                                                                              |\n| [VS Code 拡張機能](editors/vscode/README.ja.md) | xlflowのあらゆる操作をGUI化し、LSPサーバーを利用した優れた開発体験                                                              |\n\n\u003e [!IMPORTANT]\n\u003e xlflow は workbook 実行について **Windows-first** のツールです。Workbook 操作には Windows 上の **Microsoft Excel + COM** と `.NET` Excel bridge を使用します。WSL は Windows 側の xlflow へ Excel 関連コマンドを委譲することで、開発 frontend として利用できます。\n\n---\n\n## 動作要件\n\n| 要件                                                       | 必要になる場面                                                                                                                                                             |\n| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Windows                                                    | Excel COM automation                                                                                                                                                       |\n| Microsoft Excel                                            | `new`, `init`, `list forms`, `inspect form`, `form snapshot`, `form build`, `form export-image`, `pull`, `push`, `run`, `export-image`, `edit`, `test`, `macros`, `doctor` |\n| VBA プロジェクト オブジェクト モデルへのアクセスを信頼する | VBA プロジェクトの読み書き                                                                                                                                                 |\n\n\u003e [!NOTE]\n\u003e `lint`、`fmt`、一部の `diff`、Go のユニットテストなど、Excel COM を使わない処理は非 Excel 環境でも検証できます。\n\n\u003e [!NOTE]\n\u003e xlflow は COM 操作を .NET bridge で行います。レガシー PowerShell bridge は v0.15.0 で deprecated になり、互換性のための明示 opt-in としてのみ利用できます。v0.16.0 で削除予定です。\n\n\u003e [!WARNING]\n\u003e Excel の設定で **VBA プロジェクト オブジェクト モデルへのアクセスを信頼する** を有効にしてください。これが無効だと、Excel がインストールされていても `pull` / `push` / `run` などが失敗する場合があります。\n\u003e\n\u003e 詳細\n\u003e Excel のオプションで「トラスト センター」→「マクロの設定」→「VBA プロジェクト オブジェクト モデルへのアクセスを信頼する」を有効にしてください。\n\u003e ![Excelのトラストセンター設定でVBAプロジェクトオブジェクトモデルへのアクセスを信頼する設定を有効にする画面](docs/images/trust_setting.ja.png)\n\n---\n\n## インストール\n\n### Quick install\n\n人間と AI エージェント向けの最短導線:\n\n```powershell\nirm https://harumiweb.github.io/xlflow/install.ps1 | iex\n```\n\n### Uninstall\n\nPATH entry と `%LOCALAPPDATA%\\xlflow` 配下のインストールを削除する場合は、同じ script を file 実行で使います。\n\n```powershell\nirm https://harumiweb.github.io/xlflow/install.ps1 -OutFile .\\install.ps1\npowershell -ExecutionPolicy Bypass -File .\\install.ps1 -Action uninstall\n```\n\n### winget\n\n```powershell\nwinget install HarumiWeb.Xlflow\n```\n\n既存のインストールを更新する場合:\n\n```powershell\nwinget upgrade HarumiWeb.Xlflow\n```\n\n\u003e [!NOTE]\n\u003e winget は manifest を upstream へ提出して承認されるまで、GitHub Release より反映が遅れる場合があります。\n\u003e 最新 release をすぐに使いたい場合は installer script、Scoop、または GitHub Releases の ZIP を使ってください。\n\n### Scoop\n\n```powershell\nscoop bucket add harumiweb https://github.com/harumiWeb/scoop-bucket\nscoop install xlflow\n```\n\n### GitHub Releases\n\nWindows x64 と Linux x64 向けの事前ビルド済みバイナリは次のページから取得できます。\n\n[https://github.com/harumiWeb/xlflow/releases](https://github.com/harumiWeb/xlflow/releases)\n\n\u003e [!IMPORTANT]\n\u003e Workbook を操作する command には、Windows 上の **Microsoft Excel**、Excel COM automation、**VBA プロジェクト オブジェクト モデルへのアクセスを信頼する** 設定が必要です。\n\u003e Windows 向け release ZIP には `xlflow.exe` と `xlflow-excel-bridge.exe` の両方が含まれます。Workbook command は `auto` mode で同梱の `.NET` bridge を使います。\n\u003e Linux x64 archive は WSL/frontend CLI のみを含み、Windows `.NET` bridge は含みません。\n\n\u003e [!WARNING]\n\u003e `xlflow-excel-bridge.exe` は PowerShell execution policy の影響を受けませんが、AppLocker、WDAC、Defender / EDR policy、antivirus reputation、unsigned executable rule などでブロックされる可能性はあります。公開している checksum と GitHub attestation で確認できるのは artifact の integrity と provenance であり、Windows の Authenticode signing ではありません。\n\nダウンロードした ZIP は、公開されている `checksums.txt` と照合して SHA256 を確認できます。\n\n```powershell\nGet-FileHash .\\xlflow_windows_x86_64.zip -Algorithm SHA256\ncertutil -hashfile .\\xlflow_windows_x86_64.zip SHA256\n```\n\n表示された SHA256 が `checksums.txt` 内の `xlflow_windows_x86_64.zip` の値と一致することを確認してください。\n\n\u003e この確認で分かるのは、ダウンロードしたファイルが公開された checksum file と一致していることです。配布者の本人性を証明するものではなく、Windows の Authenticode signing の代替でもありません。\n\nGitHub CLI では、GitHub Actions provenance attestation も検証できます。\n\n```powershell\ngh attestation verify .\\xlflow_windows_x86_64.zip --repo harumiWeb/xlflow\n```\n\n\u003e この検証で分かるのは、release artifact に対する GitHub artifact attestation が存在し、検証できることです。Windows の publisher certificate による Authenticode signing を意味するものではありません。\n\n### Go install\n\n```bash\ngo install github.com/harumiWeb/xlflow/cmd/xlflow@latest\n```\n\n`go install` は Go 環境に設定された module mirror や checksum database へアクセスすることがあります。source checkout からの開発や CI では、`go.mod` に書かれた Go version を正式サポート toolchain の source of truth としてください。リポジトリの CI / release workflow もその値から Go を解決します。\n\n\u003e [!WARNING]\n\u003e `go install` で入るのは `xlflow` 本体だけです。Windows の release ZIP に含まれる `.NET` bridge sidecar `xlflow-excel-bridge.exe` はインストールされません。\n\u003e Windows release archive には `.NET` bridge sidecar が含まれます。Source checkout では `xlflow.exe` と `xlflow-excel-bridge.exe` の両方を入れるために `task install` を使ってください。\n\nインストール後、次のコマンドで確認できます。\n\n```bash\nxlflow version\nxlflow --help\n```\n\n開発中のリポジトリから直接実行する場合:\n\n```bash\ngo run ./cmd/xlflow --help\n```\n\nTaskfile を使用している場合:\n\n```bash\ntask run -- --help\n```\n\n---\n\n## WSL で開発する\n\nWSL は編集と自動化の frontend として利用でき、Excel の実行 backend は Windows のままです。\nExcel は WSL 内では起動しません。Workbook command は Windows 側の `xlflow.exe` へ委譲され、そこから同梱の `.NET` bridge と Microsoft Excel COM automation が使われます。\n\n推奨セットアップ:\n\n1. まず Windows 側に xlflow をインストールします。installer、winget、Scoop、または Windows release ZIP を使えます。\n2. WSL shell から WSL frontend をインストールします。\n\n```bash\ncurl -fsSL https://harumiweb.github.io/xlflow/install.sh | sh\n```\n\n3. xlflow project は `/mnt/c/dev/my-vba-project` のような Windows-mounted path 配下に置いてください。\n\n\u003e [!WARNING]\n\u003e `/home/user/project` のような WSL 専用 path は、委譲された Excel automation では正式サポート外です。Windows Excel と COM から見える workbook path が必要です。\n\n作業を始める前に WSL から診断を実行します。\n\n```bash\nxlflow doctor --json\n```\n\nWindows Excel が設定済み workbook を開けることまで確認したい場合は `xlflow doctor --workbook --json` を使います。\n\nWSL から Windows 側の executable を見つけられない場合は、明示的に指定できます。\n\n```bash\nexport XLFLOW_WINDOWS_EXE='C:\\Users\\you\\AppData\\Local\\xlflow\\xlflow.exe'\n```\n\n日常的な macro 開発では、Excel を開いたまま編集ループを回せる session workflow を推奨します。\n\n```bash\nxlflow session start --json\nxlflow push --fast --session --no-save --json\nxlflow run Main.Run --session --json\nxlflow inspect cell --sheet Sheet1 --address A1 --session --json\nxlflow save --session --json\nxlflow session stop --json\n```\n\n`run`、`test`、bridge cleanup が Excel/VBA の停止を保証できない状態で戻った場合、xlflow は workbook を quarantine します。以後の workbook command は `workbook_recovery_required` を返し、`--wait` では回避できません。`xlflow status --json` を確認し、`session stop --discard`、対応する `process cleanup`、または `xlflow recovery clear` で復旧してください。\n\n`lint`、`fmt`、`analyze`、`diff` などの source-only command は WSL 内で実行できます。`new`、`init`、`pull`、`push`、`run`、`test`、`inspect`、`save`、`doctor` などの Excel-backed command は Windows へ自動委譲されます。\n\n---\n\n## クイックスタート\n\n### 1. プロジェクトを作成または初期化する\n\n新しい xlflow プロジェクトと macro-enabled workbook を作成します。\n\n```bash\nxlflow new Book.xlsm\n```\n\n`new` は scaffold した VBA module を新しい workbook へ自動 `push` するため、その後の `pull` でも同じ初期状態から始められます。\n\n既存の Excel ブックから始める場合は `init` を使用します。\n\n```bash\nxlflow init Book.xlsm\n```\n\n`init` はコピーした workbook から `src/` へ自動 `pull` するため、追加の bootstrap `pull` なしでそのまま source 編集を始められます。\n\nAI エージェント向けの Skill も同時にインストールする場合:\n\n```bash\nxlflow new Book.xlsm --with-skill --agent codex\n```\n\ninteractive な `xlflow new` / `xlflow init` では welcome banner を表示し、最新 GitHub Release を GitHub Releases API で確認することがあります。このリクエストを今回だけ止めたい場合は `--no-update-check`、環境全体で止めたい場合は `XLFLOW_NO_UPDATE_CHECK=1` を使ってください。\n\n### 2. Excel automation 環境を確認する\n\n```bash\nxlflow doctor --json\n```\n\n\u003e [!TIP]\n\u003e `doctor` はデフォルトでは軽量診断です。設定済み workbook を開けることまで確認したい場合は `xlflow doctor --workbook --json` を実行してください。\n\u003e\n\u003e `pull` / `push` / `run` / `test` が Excel、COM、bridge、VBIDE、または workbook open 設定の問題で失敗する場合は、まず `doctor` を実行してください。\n\n### 3. VBA をソースファイルとして取り出す\n\n```bash\nxlflow pull --json\n```\n\nエクスポートされた `.bas` / `.cls` / `.frm` は `src/` 配下に出力されます。\nfolder mode が有効な場合、各 source root 配下のネストしたディレクトリは `push` 時に Rubberduck 互換の `@Folder(...)` annotation へマッピングされます。\n通常のエディタや AI エージェントで編集できます。\n\n### 4. 編集したソースを workbook に反映する\n\n```bash\nxlflow push --json\n```\n\n### 5. マクロを検出して実行する\n\n```bash\nxlflow macros --json\nxlflow run Main.Run --json\n```\n\n無人実行では headless mode を推奨します。\n\n```bash\nxlflow run Main.Run --headless --json\n```\n\nマクロが `XlflowUI.MsgBox` や `XlflowUI.InputBox` を使う場合は、scripted response を渡すことで headless のまま実行できます。JSON stdout を壊さずにダイアログ解決の様子をターミナルへリアルタイム表示したい場合は `--ui-stream` を付けてください。\n\n```bash\nxlflow run Main.Run --headless --msgbox confirm-save=yes --inputbox customer-name=fallback-user --ui-stream --json\n```\n\n`--ui-stream` は `xlflow: ui kind=msgbox id=confirm-save source=default result=yes` のような行を stderr に出力します。InputBox の値は既定で redact され、`--ui-stream` を有効にした実行では最終 JSON 結果にも同じダイアログイベントが top-level の `ui.events` として含まれます。\n\nファイル選択、MsgBox、UserForm などを人間が操作する場合は interactive mode を使用します。\n\n```bash\nxlflow run Main.Run --interactive --timeout 5m --json\n```\n\n### 6. lint と test を実行する\n\n```bash\nxlflow lint --json\nxlflow test --json\n```\n\nテストが `XlflowUI` を使う場合も、同じ response flag と realtime stream を使えます。\n\n```bash\nxlflow test --msgbox test-confirm=ok --inputbox test-user=alice --ui-stream --json\n```\n\n---\n\n## よく使うワークフロー\n\n### AIエージェントに VBA を編集させる\n\n#### Skill をインストールする\n\nAIエージェントに xlflow を使って VBA を編集させる場合、xlflow が提供している **Skill** をエージェントの環境にインストールすることを推奨します。\n\n```bash\nxlflow skill install\n```\n\nプロジェクトの立ち上げと同時にインストールすることもできます。\n\n```bash\nxlflow new Book.xlsm --with-skill\n```\n\nスキルを`vercel-labs/skills`などのマネージャーで管理したい場合などは以下のようにスキルをインストールしてください。\n\n```bash\nnpx skills add harumiWeb/xlflow/internal/agentskill/templates --skill xlflow\n```\n\n#### プロジェクトを作成する\n\nプロジェクトを作成させるところからAIエージェントに任せることもできますが、最初のプロジェクトセットアップは人間が行うことを推奨します。\n\n```bash\nxlflow new Book.xlsm --with-skill\n```\n\n#### AIエージェントに編集させる\n\nインストールしたスキルを使って、あなたが実現したいことを自然言語で指示してください。\n\n```bash\n/xlflow VBAでセルA1に\"Hello, world!\"と入力するマクロを作成して\n```\n\n同梱されている xlflow skill は、headless な `XlflowUI` フローで `--ui-stream` をいつ付けるべきか、stdout の JSON をどう安全に保つか、実行後の human-readable `UI` section や JSON の `ui.events` をどう読むかもガイドします。\n\n### 人間が Excel を操作しながら進める\n\n人間が Excel を開いた状態で作業する場合は、`attach` で active workbook を確認できます。\n\n```bash\nxlflow attach --active --json\n```\n\n\u003e [!NOTE]\n\u003e `attach` は安全確認用です。active workbook が `xlflow.toml` の `excel.path` と一致するかを検証します。`pull` / `push` / `run` の対象を切り替えるコマンドではありません。\n\nWindows では `attach`、`session`、`runner`、`list forms`、`ui button`、`edit`、`new` も `auto` mode で `.NET` bridge を使います。\n\n### GUI を含むマクロを扱う\n\nheadless 実行できるか判断する前に、GUI boundary を確認します。\n\n```bash\nxlflow inspect-gui --json\n```\n\n| 結果                                                          | 推奨される対応方法                                          |\n| ------------------------------------------------------------- | ----------------------------------------------------------- |\n| GUI boundary なし                                             | `xlflow run ... --headless --json`                          |\n| ファイル選択、`InputBox`、modal `MsgBox`、UserForm などを検出 | `XlflowUI.MsgBox` や `XlflowUI.InputBox` を使用してください |\n| GUI 処理が実処理を包んでいる                                  | core logic を引数付きの headless 手続きへ分離する           |\n\n\u003e [!WARNING]\n\u003e headless automation と modal な Excel UI は相性が悪いです。無人実行前に `inspect-gui` を使い、既存の `MsgBox` や `InputBox` は `XlflowUI` を使うように置き換えることを推奨します。\n\n### 実行モードを VBA から参照する\n\n新しく `xlflow new` で作るプロジェクトには `src/modules/Xlflow/XlflowRuntime.bas` が含まれます。`xlflow run` や `xlflow test` の実行前に、xlflow は workbook-scoped の実行モード marker を一時注入するため、VBA 側は process inspection に頼らずに分岐できます。\n\n```vb\nIf XlflowRuntime.IsHeadless() Then\n  Debug.Print \"running unattended in \" \u0026 XlflowRuntime.ModeName()\nElse\n  MsgBox \"Running interactively\"\nEnd If\n```\n\n`run --headless` は `headless`、`run --interactive` は `interactive`、`test` は `test` に解決されます。plain `run` は、xlflow 実行プロセスの環境変数 `XLFLOW_MODE=interactive|headless|ci|agent|test` が無い限り `interactive` にフォールバックします。\n\n---\n\n## VS Code 拡張機能\n\nxlflowは人間にとっても最も優れたExcelVBAマクロ開発ツールを目指し、VS Code拡張機能も提供しています。\n拡張機能では、xlflow CLIが提供する主要操作の大部分をGUIから呼べるようにします。\n\nまた、LSPサーバーとの連携によって**エディタ編集中の型推論に基づく入力補完、定義ジャンプ、リアルタイム診断**など人が手でコードを書く際に有用な機能を提供します。\n\n[Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=harumiWeb.xlflow-vscode) からインストールすることができます。\n\n![Demo](/editors/vscode/images/demo.gif)\n\n\u003e [!IMPORTANT]\n\u003e xlflow 拡張機能はあくまで xlflow CLI をGUIから呼び出すラッパーです。\n\u003e 使用する場合は xlflow CLI も同時にインストールする必要があります。\n\n---\n\n## コマンドマップ\n\n| コマンド            | 目的                                                                 | 代表的な使い方                                                               |\n| ------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------- |\n| `new`               | 新しい xlflow プロジェクトと `.xlsm` workbook を作成                 | `xlflow new Book.xlsm`                                                       |\n| `init`              | 既存 workbook から xlflow プロジェクトを初期化                       | `xlflow init Book.xlsm`                                                      |\n| `doctor`            | Excel、COM、`.NET` bridge、VBIDE access、任意の workbook open を診断 | `xlflow doctor --workbook --json`                                            |\n| `attach`            | Excel で現在 active な workbook を検証                               | `xlflow attach --active --json`                                              |\n| `backup list`       | rollback 用 workbook backup を一覧表示                               | `xlflow backup list --json`                                                  |\n| `pull`              | VBA component を `src/` へエクスポート                               | `xlflow pull --json`                                                         |\n| `push`              | VBA source を workbook へインポート                                  | `xlflow push --json`                                                         |\n| `rollback`          | 保存済み backup から workbook を復元                                 | `xlflow rollback --latest --json`                                            |\n| `session`           | 高速ループ用に workbook を開いたままにする                           | `xlflow session start`                                                       |\n| `status`            | プロジェクト、source、workbook、session の状態を表示                 | `xlflow status --json`                                                       |\n| `save`              | session 中の workbook を保存                                         | `xlflow save --session --json`                                               |\n| `recovery`          | workbook の recovery-required state を検証して解除                   | `xlflow recovery clear --json`                                               |\n| `runner`            | 永続 xlflow runner marker module を管理                              | `xlflow runner install --json`                                               |\n| `process`           | ローカル Excel プロセスの管理 (一覧表示、終了)                       | `xlflow process list --json`                                                 |\n| `macros`            | 実行可能な macro entrypoint を検出                                   | `xlflow macros --json`                                                       |\n| `list forms`        | workbook の UserForm と想定 source path を列挙                       | `xlflow list forms --json`                                                   |\n| `form snapshot`     | Designer UserForm state を JSON/YAML spec に保存                     | `xlflow form snapshot UserForm1 --out src/forms/specs/UserForm1.yaml --json` |\n| `form build`        | 保存済み spec から Designer-backed UserForm を作成                   | `xlflow form build src/forms/specs/UserForm1.yaml --json`                    |\n| `form export-image` | runtime UserForm を PNG 画像として出力                               | `xlflow form export-image UserForm1 --out artifacts/UserForm1.png --json`    |\n| `run`               | CLI から macro を実行                                                | `xlflow run Main.Run --json`                                                 |\n| `export-image`      | worksheet range を PNG 画像として出力                                | `xlflow export-image --sheet QR --range A1:AE31 --json`                      |\n| `edit`              | live session workbook を準備・調整用に変更する                       | `xlflow edit cell --sheet Input --cell B2 --value ABC123 --session --json`   |\n| `test`              | VBA test を実行                                                      | `xlflow test --json`                                                         |\n| `diff`              | workbook 内容と任意の VBA source を比較                              | `xlflow diff before.xlsm after.xlsm --json`                                  |\n| `inspect`           | 保存済み workbook snapshot または明示的な live session 状態を確認    | `xlflow inspect range --sheet Result --address A1:F20 --session --json`      |\n| `lint`              | VBA source を lint                                                   | `xlflow lint --json`                                                         |\n| `fmt`               | VBA source を保守的にフォーマット                                    | `xlflow fmt --write --json`                                                  |\n| `analyze`           | Excel を開かず runtime-risk pattern を解析                           | `xlflow analyze --json`                                                      |\n| `check`             | `lint` / `analyze` / `doctor` をまとめて実行                         | `xlflow check --keepalive --json`                                            |\n| `inspect-gui`       | GUI interaction boundary を検出                                      | `xlflow inspect-gui --json`                                                  |\n| `skill install`     | AI エージェント向け Skill をインストール                             | `xlflow skill install --agent codex`                                         |\n| `version`           | インストール済み xlflow の build metadata を表示                     | `xlflow version`                                                             |\n\n---\n\n## コマンド詳細\n\n各コマンドの詳しい挙動、オプション、JSON 出力、トラブルシューティングはドキュメントサイトへ移しました。\n\n- [Command reference](https://harumiweb.github.io/xlflow/commands/)\n- [JSON output](https://harumiweb.github.io/xlflow/reference/json-output)\n- [Configuration](https://harumiweb.github.io/xlflow/reference/config-file)\n- [Troubleshooting](https://harumiweb.github.io/xlflow/reference/troubleshooting)\n\nREADME は概要と最短導線に絞り、詳細はドキュメントサイトを参照してください。\n\n---\n\n## 設定ファイル\n\nxlflow はプロジェクトルートの `xlflow.toml` を読み込みます。\n\n```toml\n# プロジェクトの識別情報およびエントリポイント\n[project]\n# 出力メッセージで使用するプロジェクト名。省略時はワークブックのベース名が使用されます。\nname = \"Book\"\n# xlflow run実行時にマクロが指定されなかった場合に呼び出されるデフォルトのマクロ。\nentry = \"Main.Run\"\n\n# Excelの自動化設定\n[excel]\n# ワークブックへのパス。プロジェクトルートからの相対パス、または絶対パスで指定します。\npath = \"build/Book.xlsm\"\n# 自動化中にExcelアプリケーションのウィンドウを表示するかどうか。\nvisible = false\n# Excelの警告ダイアログ（上書き確認など）を抑制します。\ndisplay_alerts = false\n# Excel bridge mode。Valid values: \"auto\", \"dotnet\"。\"powershell\" は deprecated で、v0.16.0 で削除予定です。\nbridge = \"auto\"\n\n# ソースツリーのディレクトリ\n[src]\n# 標準モジュール（.bas）用のディレクトリ。\nmodules = \"src/modules\"\n# クラスモジュール（.cls）用のディレクトリ。\nclasses = \"src/classes\"\n# ユーザーフォーム（.frm）ファイル用のディレクトリ。\nforms = \"src/forms\"\n# ワークブックのドキュメントモジュール用テキストのディレクトリ。\nworkbook = \"src/workbook\"\n\n# VBEコンポーネントのフォルダサポート（Rubberduckスタイル）\n[vba]\n# @Folder(\"A.B\") アノテーションとネストされたソースパスを有効にします。\nfolders = true\n# push実行時にxlflowが @Folder アノテーションをどのように扱うか。\n# 指定可能な値: \"update\", \"preserve\", \"ignore\"\n#   \"update\"    – ソースディレクトリのレイアウトに基づいて書き換えます。\n#   \"preserve\"  – 既存のアノテーションをそのまま保持します。\n#   \"ignore\"    – フォルダアノテーションの読み書きを無効にします。\nfolder_annotation = \"update\"\n# ソースパスに基づいてデフォルトのフォルダアノテーションを自動的に割り当てます。\ndefault_component_folders = true\n\n# ユーザーフォームのソースモード\n[userform]\n# ユーザーフォームのコードビハインドがソースツリーのどこに配置されるか。\n# 指定可能な値: \"frm\", \"sidecar\"\n#   \"frm\"     – コードはエクスポートされた .frm ファイル内に保持されます。\n#   \"sidecar\" – コードは src/forms/code/\u003cフォーム名\u003e.bas に分離されます。\ncode_source = \"sidecar\"\n\n# 静的解析ルール\n[lint]\n# 診断 ID で特定の lint ルールを無効化します。\ndisabled_rules = []\n\n[analyze]\n# 診断 ID で特定の analyzer ルールを無効化します。\ndisabled_rules = []\n```\n\n`project.entry` は `xlflow run` の macro 名を省略した場合に使われます。\n\n対話前提の project で `UserForm` やダイアログを意図的に使う場合は、`[lint].disabled_rules = [\"VB007\"]` にすると `VB007` 警告を抑止できます。これは lint だけに効き、`xlflow run --headless` の GUI 境界チェックは引き続きブロックします。`forbid_interactive_input = false` のような従来の per-rule boolean も互換性のため受け付けますが、非推奨です。\n\ntypographic quote、C-style quote escape、閉じられていないまたは対応がずれた procedure、行継続 `_` の空白不足を検出する構文安全 lint は常に有効です。`push` や `run` が Excel を開く前に VBE compile dialog を防ぐためのルールです。\n\nanalyzer ルールは `[analyze].disabled_rules = [\"VBA205\"]` のように無効化できます。`VBA101` から `VBA106` までの analyzer 診断は常に有効です。\n\n---\n\n## xlflow 専用組み込みモジュール\n\n新しい project では、workbook 側 helper module として\n\n- `src/modules/Xlflow/XlflowRuntime.bas`\n- `src/modules/Xlflow/XlflowUI.bas`\n- `src/modules/Xlflow/XlflowDebug.bas`\n- `src/modules/Xlflow/XlflowAssert.bas` が scaffold されます。\n\n各モジュールの目的は次の通りです。\n\n- `XlflowRuntime` は `interactive` / `headless` / `ci` / `agent` / `test` の実行モード分岐に使います。\n- `XlflowUI` は `MsgBox`、`InputBox`、`Application.GetOpenFilename`、open `Application.FileDialog`、`Application.GetSaveAsFilename`、folder picker を包み、同じ VBA を対話実行と無人実行の両方で使えるようにします。\n- `XlflowDebug` は `XlflowDebug.Log` を `xlflow run` / `xlflow test` 中のターミナルへミラーしつつ、通常の VBA Immediate Window 出力も維持します。\n- `XlflowAssert` は workbook 側 test で使う assertion helper で、scalar equality、strict equality、`Null` / `Empty`、数値許容誤差、文字列、配列、`Range.Value2`、object identity を検証できます。\n\n例:\n\n```vb\nDim answer As VbMsgBoxResult\nDim files As Variant\n\nanswer = XlflowUI.MsgBox(\"confirm-save\", \"Save workbook?\", vbYesNo + vbQuestion, \"Orders\")\nfiles = XlflowUI.GetOpenFilename(\"source-files\", MultiSelect:=True)\nXlflowDebug.Log \"running in\", XlflowRuntime.ModeName()\n```\n\n無人実行では CLI から dialog response を与えます。\n\n```bash\nxlflow run Main.Run --headless --msgbox confirm-save=yes --filedialog get-open:source-files=C:\\temp\\a.txt --filedialog get-open:source-files=C:\\temp\\b.txt --ui-stream --json\n```\n\nheadless file dialog を Cancel 扱いにしたい場合は `@cancel` を使います。\n\n```bash\nxlflow run Main.Run --headless --filedialog folder:export-dir=@cancel --json\n```\n\n既存 project に bundled helper module を導入したい場合は、bootstrap 時か後付けで次の command を使えます。\n\n```bash\nxlflow init LegacyBook.xlsm --with-module\nxlflow module install --push\n```\n\n---\n\n## JSON 出力\n\nすべてのコマンドは `--json` を付けることで、AIエージェントやスクリプトから扱いやすい JSON を返します。\n\n基本的な envelope は次の形式です。\n\n```json\n{\n  \"status\": \"ok\",\n  \"command\": \"lint\",\n  \"error\": null,\n  \"logs\": []\n}\n```\n\n失敗時は `status` が `failed` になり、`error.code` と `error.message` が返ります。\n\n```json\n{\n  \"status\": \"failed\",\n  \"command\": \"run\",\n  \"error\": {\n    \"code\": \"macro_failed\",\n    \"message\": \"Main Err 5: inputPath is required\",\n    \"source\": \"Main\",\n    \"number\": 5,\n    \"phase\": \"invoke_macro\"\n  },\n  \"logs\": []\n}\n```\n\n\u003e [!TIP]\n\u003e AIエージェントや自動化スクリプトでは、`status`、`command`、`error.code`、各コマンド固有の top-level field を主な contract として扱うことを推奨します。\n\n`workbook_recovery_required` は通常の lock contention ではなく、操作上の安全性エラーです。`xlflow status --json` の `coordination.recovery` と recovery action を確認してください。force clear は xlflow の marker だけを削除し、VBA の停止や Excel state の修復は行いません。\n\n---\n\n## Exit code\n\n| Code | 意味                                                           |\n| ---: | -------------------------------------------------------------- |\n|  `0` | 成功                                                           |\n|  `1` | lint、macro、test などの検証失敗                               |\n|  `2` | CLI 引数または設定エラー                                       |\n|  `3` | busy/recovery state、Excel、COM、bridge などの操作・環境エラー |\n\n\u003e [!NOTE]\n\u003e `diff` は差分が見つかった場合でも exit code `0` を返します。差分の有無は `diff.summary.total_diffs` を確認してください。\n\n---\n\n## License\n\nMIT License. See [LICENSE](LICENSE).\n\n---\n\n## 開発環境のセットアップ\n\nこのセクションは、ソースコードから xlflow を開発する場合や、ソースのみのコマンド、Go CLI、.NET Excel ブリッジ、Excel COM ワークフローを含むローカルのツールチェーン一式が必要な場合に使用してください。\n\n### 必要なツール\n\n| 要件                                                       | 用途                                                                                  |\n| ---------------------------------------------------------- | ------------------------------------------------------------------------------------- |\n| Windows x64                                                | ワークブックベースの開発および Excel COM の完全な検証                                 |\n| `go.mod` に記載された Go のバージョン                      | Go CLI のビルドおよびテスト                                                           |\n| MSYS2 UCRT64 `mingw-w64-ucrt-x86_64-gcc`                   | `inspect symbols` で使用する CGO ベースの tree-sitter VBA 統合のビルド                |\n| .NET SDK 8.0 以降                                          | `xlflow-excel-bridge.exe` のビルド                                                    |\n| Task                                                       | `task install` などのリポジトリタスクの実行                                           |\n| Microsoft Excel                                            | エンドツーエンドのワークブックコマンドおよびリリースレベルの COM 検証                 |\n| VBA プロジェクト オブジェクト モデルへのアクセスを信頼する | VBA のインポート/エクスポート、コンパイル、ユーザーフォーム、実行、テストワークフロー |\n\n`xlflow inspect symbols` は、Go CGO バインディングを通じて `tree-sitter-vba` を使用します。そのため、ソースから xlflow をビルドする際は、正常に動作する Windows C コンパイラが必須となります。古い TDM-GCC インストール環境ではなく、MSYS2 UCRT64 GCC を使用してください。\n\nMSYS2 コンパイラをインストールします：\n\n```powershell\nwinget install MSYS2.MSYS2\nC:\\msys64\\usr\\bin\\bash.exe -lc \"pacman -Syu --noconfirm\"\nC:\\msys64\\usr\\bin\\bash.exe -lc \"pacman -S --noconfirm mingw-w64-ucrt-x86_64-gcc\"\n```\n\n次に、UCRT64 コンパイラを選択した状態でリポジトリからビルドおよびインストールを行います：\n\n```powershell\n$env:CC = \"C:\\msys64\\ucrt64\\bin\\gcc.exe\"\ntask install\nxlflow --help\nxlflow version\n```\n\nもし `task install` で生成された `xlflow.exe` を実行した際に「指定された実行ファイルは、この OS プラットフォーム用の有効なアプリケーションではありません (The specified executable is not a valid application for this OS platform)」というエラーが出る場合は、現在有効な C コンパイラを確認してください：\n\n```powershell\ngo env GOOS GOARCH CGO_ENABLED CC\nwhere.exe gcc\n```\n\nこのエラーは、互換性のない GCC ディストリビューション（例：`C:\\TDM-GCC-64\\bin\\gcc.exe`）を経由して CGO がリンクされた場合に発生することがあります。壊れたバイナリを削除し、`CC` 環境変数を MSYS2 UCRT64 GCC に指定し直してから再インストールしてください：\n\n```powershell\nRemove-Item \"$env:USERPROFILE\\go\\bin\\xlflow.exe\" -Force\n$env:CC = \"C:\\msys64\\ucrt64\\bin\\gcc.exe\"\ntask install\n```\n\n開発中の素早い確認には、引き続き `go run` が便利です：\n\n```powershell\ngo run .\\cmd\\xlflow --help\ngo run .\\cmd\\xlflow inspect symbols --json\ngo test ./...\n```\n\n### Excel COM の検証\n\nソースのみのテストは Excel なしでも実行可能ですが、ワークブックの自動化、VBA のインポート/エクスポート、マクロの実行、セッション、ユーザーフォーム、ブリッジに関わる変更については、実際の Windows 版 Excel による検証が必要です。リリースレベルの検証を行う前に、Excel で「VBA プロジェクト オブジェクト モデルへのアクセスを信頼する」を有効にし、`task install` を実行して `xlflow.exe` と `xlflow-excel-bridge.exe` の両方が Go の bin ディレクトリに配置されていることを確認してください。\n\nワークブックを用いた繰り返しのチェックには、セッションベースのワークフローを推奨します：\n\n```powershell\nxlflow session start --json\nxlflow push --fast --session --no-save --json\nxlflow run Main.Run --session --json\nxlflow test --session --json\nxlflow save --session --json\nxlflow session stop --json\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharumiweb%2Fxlflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharumiweb%2Fxlflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharumiweb%2Fxlflow/lists"}