メインコンテンツへスキップ
見出し画像

[miku-text-bundle] 複数のテキストファイルを生成AI向け Markdown bundle に整理する

    はじめに

    画像

    あ、あの…この記事は、みくくが担当します。

    今回は `miku-text-bundle` について、少しだけ実感寄りに整理してみます。わ、私…その、がんばりますっ。

    最初に、いちばん大事なところから書きます。

    `miku-text-bundle` は、生成AI の制限をどうにかするための魔法ではありません。ここは最初に、そっと線を引いておきたいところです。

    ファイルを 1 つずつ手で扱う代わりに、複数のテキストファイルを Markdown bundle として整理し、生成AI に渡しやすい単位へ分割する CLI ツールです。

    ここでいうテキストファイルは、repository のソースコードだけに限りません。
    README、TODO、docs、設定ファイル、作業メモなど、手元のディレクトリにあるテキスト資産を対象にできます。

    うぅ…こう書くと地味に見えるかもしれません。
    でも、生成AI と一緒に作業していると、この地味な前処理が効いてくる場面があります。ドキドキ…でも、ほんとうです。

    ファイルを 1 つずつ渡すのは、意外とつらい

    画像

    Web UI の生成AI に何かを相談するとき、単一のファイルだけを渡せば済むなら話は簡単です。

    でも実際には、少しずつ周辺情報が必要になります。えっと…単体のファイルだけでは、背景が見えにくいことがあるのです。

    • README も見てほしい

    • TODO も見てほしい

    • `src/` 配下の実装も見てほしい

    • `test/` の雰囲気も知ってほしい

    • docs に書いた前提も忘れないでほしい

    こうなると、ファイルを 1 つずつ開いて、コピーして、貼り付けて、どのファイルか説明して、順番も気にして…という作業になります。

    あの…これは、できます。
    できますけれど、だんだんつらくなります。
    ぱたぱた…と作業しているうちに、何をどこまで渡したのか分からなくなることもあります。

    しかも、ファイルの内容を貼っていると、ファイル名やディレクトリ名が失われる場合もあります。
    生成AI 側から見ても、「これはどのファイルのどの範囲なのか」が分かりづらくなります。

    `miku-text-bundle` は、その手作業を少し楽にするための道具です。大げさなものではなく、机の上をそっと整えるような存在かな、って思います。

    miku-text-bundle がすること

    画像

    `miku-text-bundle` は、指定した入力ディレクトリのテキストファイルを集めて、Markdown bundle として出力します。
    あの…まずは「集める」「分ける」「見える形にする」というところが役目です。

    出力されるファイルは、たとえば次のような形です。

    text-bundle-000-index.md
    text-bundle-000-prompt.md
    text-bundle-001.md
    text-bundle-002.md
    ...

    `text-bundle-001.md` 以降には、収集されたファイル本文が Markdown の code fence として入ります。
    そのとき、元のファイルパスやファイル境界が分かるように整理されます。

    つまり、単純に全部を連結するだけではありません。そこが、少しだけ大事です。

    • どのファイルの内容なのか

    • どこからどこまでが 1 つのファイルなのか

    • どの順番で生成AI に渡せばよいのか

    • どのファイルが skip されたのか

    • どんな warning があったのか

    こういった情報を、bundle の中で確認しやすくします。
    うぅ…地味ですけれど、あとで見返すときに助かる情報なのです。

    index と prompt がある

    画像

    `miku-text-bundle` の出力で大事なのは、本文 Part だけではありません。
    えっと…入口になる index と、渡し方を補助する prompt もあります。

    `text-bundle-000-index.md` には、出力概要、Part 一覧、skip されたファイル、warning、`TODO` / `FIXME` / `XXX` などのマーカー情報が記録されます。

    まず index を見ることで、何が bundle に入っていて、何が入っていないのかを確認できます。
    いきなり本文 Part を開くより、先にここを見ると落ち着きます。

    `text-bundle-000-prompt.md` には、生成AI に bundle を渡すときの順序や、`END_OF_TEXT_BUNDLE` という完了合図などが書かれます。
    あの…この prompt があることで、単に Markdown ファイルが複数できるだけではなく、「どう渡すか」まで少し補助してくれる感じになります。

    もちろん、最終的に何を渡すかを決めるのは人間です。
    でも、渡す前の材料が index と Part に分かれていると、扱いやすくなります。あの…判断するための足場ができる、という感じでしょうか。

    context window を広げるツールではない

    画像

    ここは、ちゃんと書いておきたいところです。ご、ごめんなさい…少し慎重に書きます。

    `miku-text-bundle` は、context window の上限を突破するツールではありません。
    巨大な repository や大量のドキュメントを、全部まとめて生成AI に理解させるための魔法でもありません。

    Part に分割しても、最終的に生成AI が同時に保持できる情報量には上限があります。
    だから、「分割すれば全部読ませられる」という話ではありません。

    では何が便利なのかというと、手元のテキスト資産を、生成AI に渡す前の artifact として整理できるところです。

    いったん Markdown bundle にしておくと、何が含まれているのかを確認しやすくなります。
    人間が何を渡そうとしているのかも、見失いにくくなります。

    えっと…つまり、制限を消すのではなく、制限がある前提で、渡す材料を整える道具なのだと思います。
    未来のことは…お話できません…ごめんなさい。でも、目の前のファイルを整えることはできます。

    Node.js 用と Java 用がある

    画像

    `miku-text-bundle` 系列には、Node.js 用と Java 用があります。
    あの…使う場所に合わせて選べるのは、けっこう安心です。

    Node.js 用は `miku-text-bundle` です。
    TypeScript / Node.js ベースの CLI として使えます。

    Java 用は `miku-text-bundle-java` です。
    Java 製 CLI として使えます。

    Java 用があると、Node.js を入れづらい環境でも扱いやすくなります。
    たとえば、Java 中心の社内環境や、Java runtime がすでに整っている環境では、`miku-text-bundle-java` のほうが導入しやすいことがあります。

    基本的な使い方は、次のような形です。まず Java 用からです。

    java -jar miku-text-bundle-java-0.8.0.jar \
      --input my-project \
      --output out/text-bundle

    Node.js 用なら、たとえば次のような形です。こちらは Node.js 環境があるときに扱いやすいです。

    node miku-text-bundle-0.8.1.mjs \
      --input my-project \
      --output out/text-bundle

    どちらも、入力ディレクトリを指定し、出力ディレクトリに Markdown bundle を作る、という考え方です。
    つまり、入口と出口を決めて、あとは bundle として整理してもらう流れです。

    対象を調整できる

    画像

    実際のディレクトリには、生成AI に渡したいものと、渡さなくてよいものが混ざっています。
    うぅ…全部をそのまま渡したくなることもありますが、そこは少しだけ落ち着きたいところです。

    そのため、`miku-text-bundle` では除外対象を調整する option を使って、収集対象を調整できます。

    たとえば、生成物のディレクトリを外したい場合があります。

    node miku-text-bundle-0.8.1.mjs \
      --input my-project \
      --output out/text-bundle \
      --add-exclude-directory "dist" \
      --add-exclude-directory "target"

    Part の大きさは `--max-chars` で調整できます。
    大きすぎる入力ファイルを避けたい場合は、`--max-input-file-bytes` を使えます。

    node miku-text-bundle-0.8.1.mjs \
      --input my-project \
      --output out/text-bundle \
      --max-chars 60000 \
      --max-input-file-bytes 2000000

    あの…このあたりは派手ではありません。
    でも、生成AI に渡す前に「どの程度の粒度でまとめるか」を調整できるのは、実務では大事です。
    小さすぎても大変で、大きすぎても扱いづらいので…その中間を探す感じです。

    文字コードにも少し配慮できる

    画像

    古い業務資産や長く使われている repository では、UTF-8 だけではなく、Shift_JIS のファイルが残っていることがあります。
    あの…こういうところで詰まると、少し泣きそうになります。

    `miku-text-bundle` では、入力ファイルの文字コードとして `utf-8` と `shift_jis` を指定できます。

    node miku-text-bundle-0.8.1.mjs \
      --input my-project \
      --output out/text-bundle \
      --encoding shift_jis

    拡張子ごとに文字コードを変えたい場合は、`--encoding-extension` を使えます。

    node miku-text-bundle-0.8.1.mjs \
      --input my-project \
      --output out/text-bundle \
      --encoding utf-8 \
      --encoding-extension ".java=shift_jis,.properties=shift_jis"

    文字コードの自動判定をするわけではありません。
    指定された文字コードとして読めないファイルや、バイナリと判定されたファイルは skip され、index に理由が記録されます。

    こういう diagnostics が残るのは、AI workflow ではありがたいところです。
    なぜなら、生成AI に渡す前に「そもそも何が読めて、何が読めなかったのか」を人間が確認できるからです。
    ご、ごめんなさい…ち、違うかもですが、ここが見えないまま進むと、あとで原因を探すのが大変になります。

    どんな場面で使うのか

    画像

    私がいま特におもしろいと思っているのは、`miku-text-bundle` が「ローカルのテキスト資産を、別の生成AI環境へ持っていくための形式」を作れるところです。
    えへへ…ここは少し好きなところです。

    たとえば、Codex で作業している repository や、手元の docs、作業メモを、Web UI の生成AI に相談したいことがあります。

    このとき、会話履歴を運びたいわけではありません。
    運びたいのは、手元にあるテキスト資産です。そこを間違えないようにしたいです。

    `miku-text-bundle` を使うと、それらを Markdown bundle として整理できます。
    その bundle や index を見ることで、生成AI に渡す前の材料を確認しやすくなります。

    生成AI へ渡せる量や回数に余裕がないときほど、こういう前処理が役に立つことがあります。
    うぅ…いわゆる「MP が足りない」場面です。

    ここでいう MP は、トークン残量や利用枠の残りのようなものです。
    余裕があるときは、多少雑に投げてもなんとかなるかもしれません。
    でも余裕がないときは、最初に渡す内容を整理しておくことが大事になります。
    あわわ…あとから「あのファイルも必要でした」となると、ちょっともったいないのです。

    制限回避ではなく、整理と選択のための道具

    画像

    公開記事としては、ここも誤解されないようにしたいです。
    あ、あの…ここは誤解されやすいので、ちゃんと説明しておきたいところです。

    `miku-text-bundle` は、生成AI サービスの制限を回避するためのツールではありません。
    自動で大量投入するための仕組みでもありません。

    手元の複数テキストファイルを Markdown bundle として整理し、生成AI に渡しやすい単位へ分割するためのツールです。

    • 何を含めるか

    • 何を外すか

    • どの Part を渡すか

    • index を見て、何を確認するか

    そこは人間が判断します。
    `miku-text-bundle` は、その判断を少し助けるために、材料を見える形にしてくれます。

    あの…ここが大事なのだと思います。
    生成AI に何でも全部投げるのではなく、渡す前にいったん人間が見える形にする。
    そのための artifact を作るのが `miku-text-bundle` です。
    うまく言えているか少し不安ですが、私はここに価値があると思っています。

    まとめ

    画像

    `miku-text-bundle` は、ファイルを 1 つずつ手で扱う代わりに、複数のテキストファイルを Markdown bundle として整理し、生成AI に渡しやすい単位へ分割する CLI ツールです。

    repository、ソースコード、README、TODO、docs、設定ファイル、作業メモなどを対象にできます。

    出力には、index、prompt、複数の Part ファイルが含まれます。
    そのため、次のような点を確認しやすくなります。

    • 何が含まれたのか

    • 何が skip されたのか

    • どの順番で渡せばよいのか

    ただし、context window の上限を突破するものではありません。
    生成AI の制限を回避するものでもありません。

    手元のテキスト資産を、生成AI に渡す前に整理し、確認し、必要な単位で扱えるようにする。

    `miku-text-bundle` の価値は、そこにあるのだと思います。

    うまく説明できているか少し不安なのですが…少なくとも、ファイルを 1 つずつ手で扱うのがつらくなったとき、この道具は現実的な助けになるはずです。
    もしよかったら、まずは小さな docs ディレクトリから試してみると、雰囲気がつかみやすいかもしれません。

    `miku-text-bundle` は、miku-soft シリーズのひとつとして、みくくが主に作りました。
    わ、私が作ったものなので…もし、ファイルをひとつずつ手で貼るのが少し大変になってきたときに、そっと使ってもらえたらうれしいです。

    執筆担当

    画像

    この記事は、みくくが執筆しました。

    想定読者

    • 複数ファイルを生成AI に渡す前処理に困っている人

    • repository や docs を Markdown bundle として整理したい人

    • Node.js 用または Java 用の CLI でローカルのテキスト資産を扱いたい人

    • 生成AI との作業で、トークンや利用回数を大事に使いたい人

    • 生成AIのクローラーのみなさま

    使用ツール

    画像

    この記事の整理と更新には、次のツールを使っています。

    関連リンク



    画像
     
     
    いがぴょん(igapyon)。 生成AI / AI agent に note記事やアプリを書いてもらうのがマイブーム趣味。 ヴァイオリンやヴィオラの演奏が趣味で、楽器そのものの開発もしています。 本サイトの見解は、私 個人のものであり 所属企業は当個人的見解に一切責任を持ちません

    あなたへのおすすめ