Skip to content

noxitro/context-foundation

v0.4.2MIT

Local search over a large codebase and its design docs by meaning and keywords. Adds a read-only MCP search tool for finding where something is implemented or documented (from another engine's term, or a plain-language or Japanese description), a hook that tells the agent to use it before grep only in workspaces with an index, a fallback skill, and /context-index to build the index. Retrieval only; the code never leaves the PC.

変更履歴

版ごとに、変わったことと、更新のあとにすること(setup のやり直し・索引の 作り直し・新しいセッション)を書きます。新しい版が上です。

  • プラグインの版は、plugin.json・.github/plugin/marketplace.json・ pyproject.toml・src/context_foundation/__init__.py の 4 か所でそろえ ます(テストで確かめています)
  • 索引の形式の版(INDEX_SCHEMA_VERSION)を上げる版では、「更新のあとに すること」に索引の作り直しを書きます。これまでの版は、どれも形式の版 1 です
  • Python の依存の一覧(pyproject.toml の dependencies)を変えた版では、 setup のやり直しが要ります。プラグインの置き場では、道具も、やり直す まで「set up for an older version (its dependencies changed)」と知らせ ます(リポジトリを取得した人の .venv は、依存の一覧を確かめません)
  • git のタグは、まだ打っていません。前の版に戻すときは、コミットの sha で 固定します(docs/copilot.md の「チームの Marketplace に載せる」)

0.4.2(2026-11-18)

Copilot CLI 1.0.113 で、/context-index が読み込まれなかったのを直し ました。検索の順位の付け方、索引の形式、エージェント向けの検索の出力、 MCP の道具は変えていません。

  • 1.0.113 から、CLI が拡張に渡す SDK の名前が @microsoft/copilot-sdk に 変わり、前の名前(@github/copilot-sdk)を読み込めなくなった。コマンドの 置き場も、commands から interaction.commands に変わった。拡張は、 新しい名前から順に SDK を読み込み、コマンドを両方の置き場に渡すように した。1.0.112 までの CLI と、アプリのランタイム(前の名前)でも動く
  • 拡張の単体テストに、SDK の読み込みの順とコマンドの置き場のテストを 足した。プラグインの通しの確かめ(.github/scripts/plugin_smoke.py)は、 偽の SDK を 2 つの名前で 1 回ずつ置いて動かす
  • Copilot CLI 1.0.113 と 1.0.112 の対話の画面で、一覧に出ること・使い方・ 索引づくり・作り直し・full・同じセッションでの検索を確かめた。索引 づくりの間、モデルの呼び出しは 0 回だった【実測】。アプリでは、まだ 試していない【未確認】(docs/copilot.md の「確かめたこと」)

更新のあとにすること

  1. setup のやり直しと、索引の作り直しは要りません。 依存の一覧も、 索引の形式も変わっていません
  2. copilot plugin update context-foundation で更新し、Copilot CLI の 新しいセッションを始めます。/context と打って、一覧に /context-index が出れば読み込まれています

0.4.1(2026-11-18)

Copilot CLI 1.0.113 では、/context-index が読み込まれません(0.4.2 で 直しました)。 1.0.112 までの CLI では動きます。

索引を作るスラッシュコマンド /context-index を足しました。同じ作者の cxxref の /cxxref-index と同じ形(Copilot CLI の拡張)です。検索の順位の 付け方、索引の形式、エージェント向けの検索の出力、MCP の道具は変えて いません。

  • /context-index: Copilot CLI のセッションで打つと、モデルを呼ばずに、 ctxf.py init と ctxf.py index を裏で動かす。初めては、検索したい フォルダを並べる(/context-index "<エンジンのソース>" "<設計文書>")。 2 回目からは、何も付けずに打つと、今の設定で作り直す。full で、すべて 埋め込み直す。進み具合をときどき出し、終わったらそう出す。出力は .cf\context-index.log に書く。用意(setup)が済んでいなければ、何も 作らずに、やり直すコマンドを出す(setup は動かさない)
  • 拡張は Copilot CLI の実験的機能で、機能フラグ EXTENSIONS が有効な ときだけ読み込まれる。設定のしかたは docs/copilot.md の「/context-index」
  • MCP サーバーは読み取り専用のまま。エージェントからは索引を作れない
  • skill context-search の「When it is not ready」は、索引が無いとき、 利用者に /context-index を勧めるように変えた(拡張が使えないときの CLI の手順も残した)
  • 偽の SDK で、Linux で動かして確かめた。そのあと Windows の Copilot CLI で動かすと、1.0.113 では読み込まれず(拡張が「failed」)、1.0.112 では 動いた【実測】(docs/copilot.md の「確かめたこと」)

更新のあとにすること

  1. setup のやり直しと、索引の作り直しは要りません。 依存の一覧も、 索引の形式も変わっていません
  2. /context-index を使うなら、機能フラグ EXTENSIONS を有効にしてから、 Copilot CLI の新しいセッションを始めます

0.4.0(2026-11-17)

本番で使うための直しです。監査で見つかった不具合を直し、文書を今の動きに 合わせました。検索の順位の付け方と、索引の形式は変えていません。索引が 新しく、source のルートが作業フォルダそのものなら、エージェント向けの検索の 出力は 0.3.1 と同じです(エージェントでの計測をした形を、変えないため)。 違うのは、0.3.1 の出力が上限のバイト数を超えていたときと、400 バイト 以上の 1 行で本文が止まっていたときだけです(下の「検索と出力」)。 0.3.1 の出力が上限を超えるのは、モデルが top_k を 8 より大きくした 呼び出しや、パスが深く passage の大きいコードの結果です。そのときは、 多くの場合、後ろの場所だけの行からシグネチャが消えます(まれに、本文の 切れ目も変わります)。既定の top_k の 8 では、まれです。

0.4.0 の直しを手元で動かして確かめたのは、Windows と Python 3.13 です。 Linux と、Python 3.11・3.12・3.14 は、CI のテストで確かめます(CI の テストは 3.11・3.12・3.13・3.14 で回します。Linux と 3.12 は、WSL の Ubuntu でもテストを流しました)。

更新のあとにすること

  1. setup をやり直す。 依存の一覧が変わりました(版の上限を足し、 huggingface_hub の下限を 0.36 に上げた)。プラグインとして入れた人は python -I "<プラグインのフォルダ>\ctxf.py" setup、リポジトリを取得した 人は setup.bat です。プラグインの置き場では、やり直すまで、MCP サーバーは道具を出さず、入口は「set up for an older version (its dependencies changed)」と知らせます。定期に流している index も、 やり直すまで終了コード 4 で止まります。リポジトリを取得した人には、 この知らせは出ません(.venv の依存は自動では確かめません)。自分で setup.bat を流してください
  2. Copilot の新しいセッションを始める。 動いているセッションには、 setup の後も検索の道具は出ません(控えの skill は動きます)
  3. 設定を確かめる。 .cf\config.toml に [search] reranker か rerank_candidates があると、止まります。消してください。[index] path は、.cf の中のファイル名だけにできます
  4. 索引は、作り直さなくても使えます。 0.3.1 で作った索引は、そのまま 検索できます。ただし、取り込みの規則が変わったので(秘密を持ちやすい 名前のファイルを除く、生成物の判定、長いパス、ファイルとフォルダの リンク)、一度 index を流すことを勧めます。変わっていない passage の 埋め込みは使い回すので、時間は変わったファイルの分だけです。それまでの 索引に .env などが入っていたら、流すまで残ります
    • 流すと、ソースを変えていなくても、索引に入るファイルが両方の向きに 変わります。0.3.1 が生成物として除いていた手書きのファイルの多くが 入り、0.3.1 が見逃していた生成物の一部が抜けます。逆向きもあります。 頭のコメントのかたまりのどこかの行が「generated from / with / using」「auto-generated」などで始まる手書きのファイルは、0.3.1 では 入っていても、除かれます(入れるには [index] skip_generated = false)。0.3.1 が除いていた生成物でも、文書の拡張子のものと、印が コメントの行の書き出しに無いものは入ります。入れたくないファイルは、 source の exclude に足します
    • フォルダのリンクとジャンクションは、たどらなくなりました。その先の ソースを索引に入れていたなら、流すと抜けます。入れるには、その フォルダを root にした [[source]] を足します
    • 流す前の status --check は、取り込みの規則の違いの分も、増えた・ 消えたに数えます(ファイルは変わっていません)。そのときは、索引を 作った道具の版が違うことも知らせます。一度 index を流すと消え ます

安全

  • 作業フォルダの設定から、Python のコードを読み込めないようにした。 [search] reranker と rerank_candidates は無くなり、書いてあると 「設定 [search] の reranker は 0.4.0 で無くなりました…」で止まる。reranker は、Python から Searcher(..., reranker=関数, rerank_candidates=N) で 渡したときだけ使う(評価とテストのため)。評価の記録の reranker には、 渡した関数の モジュール:名前 が入る(渡していなければ null)
  • [index] path は、.cf の中のファイル名だけにした。絶対パス、ドライブ つきのパス、..、空、.、リンクで .cf の外に出るフォルダは、設定の 誤りとして止まる
  • 秘密を持ちやすい名前のファイルを、既定で除く(理由 secret_name)。 .env・.env.*・*.pem・*.key・*.pfx・*.p12・id_rsa*・ id_dsa*・id_ecdsa*・id_ed25519*・.npmrc・.pypirc・.netrc・ _netrc・.git-credentials・.p4config・.p4tickets・*.tfvars と、 名前に secret か credential を含む yaml・yml・toml・ini・cfg・json。 include を書いても除く。名前だけで見るので、ほかの設定ファイルの中の 秘密は、そのまま索引に入る
  • init が、Perforce なら .cf を .p4ignore に足すよう知らせる(索引には、 ソースの本文の写しが入る)
  • 索引に書かれたパスが、絶対パス・ドライブつき・UNC・/ か \ で始まる・ .. を含むときは、ファイルに触れずに [changed since index] にする (ふつうの索引のパスは、どれも source のルートからの相対パス)
  • .cf の中に置かれたリンク(index.db.partial と作っている途中の索引の 名前)は、たどらずに消してから書く。.cf\.gitignore は、その名前で 何か(リンクも)があれば書かない
  • 入口の where と copilot register は、PATH の python と copilot を、 PATH の絶対パスのフォルダからだけ探す(Windows でも、今のフォルダは 見ない)。見つけた python は -I で起動する
  • CF_ENTRY が無いとき(pip で入れた ctxf、python -m context_foundation)、文面が案内するコマンドは "<python>" -P -m context_foundation <コマンド> になった(今のフォルダのモジュールを 読まない)
  • 取ってきたリポジトリに .cf が入っていたら、使わずに消して、自分で 作り直す。設定は、作業フォルダの外のフォルダ(source のルート・モデルの フォルダ・用語の対応表)も指せるため(下の「まだ直していないこと」)

取り込み

  • 既定の名前で除くフォルダ(build・target・packages など)は、前と 同じく除く。ただし、中に索引に入りうるファイルがいくつあったかを数えて、 index の終わりと status に出す(例も 5 つまで)。エージェント向けの status(MCP の道具も)には、「not indexed: N folders excluded by default folder names … Search those with grep」の 1 行が出る。入れる には、そのフォルダを root にした [[source]] を足すか、source に default_excludes = false を書く
  • 生成物の判定を、先頭 2,000 文字の、コメントの行だけで行うようにした。 文書(.md・.markdown・.mdx・.txt・.rst・.adoc)は、生成物と みなさない。印は 3 つに分ける
    • バナーの形(「This file was generated」「File automatically generated by」「Generated by」「autogenerated」「このファイルは 自動生成」「自動生成ファイル」など)は、頭の 2,000 文字のどの コメントの行でも、書き出しにあれば印にする。前に飾りの記号や、 短い前置き(NOTE:・WARNING:・注意: など)があってもよい。 「Generated by:」(後ろにコロン。表の出どころなど)は、0.3.1 と同じく 印にしない
    • 説明にもよく出る形(「auto-generated」だけ、「generated from」 「generated with」「code generated」「parser generated by」 「自動生成され」など)は、ファイルの頭のコメントのかたまり(最初の コードの行より前。docstring の中の行も含む)のどこかの行の書き出しに あるときだけ印にする
    • @generated・<auto-generated・大文字の DO NOT EDIT は、 コメントの行のどこにあっても印にする。小文字の「do not edit」は、 同じ行に「generated」があるときだけ
    • 頭で開いたブロックコメント(/* */、docstring の """)の中の行は、 行の頭に記号が無くてもコメントの行として見る。' は VB の拡張子 (.vb など)、<!-- はマークアップの拡張子(.xml・.html・ .csproj など)のときだけ、コメントの始まりとみなす
    • # で始まる行は、ふつうはコメントの行として見る。ただし # の後ろが include・import・if・else・define・pragma・warning・ using などの語の行は、プリプロセッサの行としてコードの行とみなし、 印を見ない(頭のかたまりもそこで終わる)。# がコメントの始まりの ファイル(拡張子が .py・.sh・.cmake・.yaml・.yml・.toml・ .ini・.cfg・.rb・.ps1 のものと、名前が Makefile・ Dockerfile のもの)では、その語の行もコメントの行として見る (「# WARNING: This file is auto-generated by …」を見落とさない)
    • 0.3.1 では除かれていた手書きのファイルの多くが、索引に入るようになる。 0.3.1 が見逃していた生成物の一部は、除かれるようになる。逆向きに 変わるものもある(上の「更新のあとにすること」4.)
  • UTF-8 でも CP932 でも読めないファイルは、行ごとに読む(文字コードの記録は mixed)。読めない部分が多いものは、理由 undecodable で除く(前は binary と数えていた)
  • Windows で、260 文字を超えるパスのファイルも取り込む
  • フォルダのリンク(シンボリックリンク、Windows のジャンクション)は たどらない。数は link_dir として status に出る。前は、ジャンクション をたどり、輪になっていると同じファイルを何度も入れていた。リンクの 先を入れるには、そのフォルダ(リンクそのものでもよい)を root にした [[source]] を足す。status の人が読む形とエージェント向けの形も、 そう案内する
  • 一覧できないフォルダは、unreadable_dir として数える(前は黙って 消えていた)
  • ファイルのリンクは、取り込まない。指す先が source のルートの中なら理由 symlink_inside(指す先は、もとの場所で、その名前の決まりのとおりに 取り込まれる)、外なら symlink_outside で除く。前は、どこを指す リンクも、リンクの名前で読んでいた(.env を指すリンクが、秘密の 名前の除外をすり抜けた)
  • UTF-8 で表せない名前のファイルは、理由 bad_name で除く(前は 索引づくりが止まっていた)
  • ほかの source のルートになっているフォルダは、その source の側だけで 取り込む(同じファイルを 2 回入れない)。フォルダのリンクのパスが、 ほかの source のルートと同じときも、その source の側で取り込み、 link_dir には数えない
  • 構文で分ける途中で落ちたファイル(深い else-if の連なりなど)は、行で 分けて続ける。数は status に出る。とても長い else-if の連なりでも、 落ちないようにした

索引づくり

  • 止められた索引づくりは、続きから計算する。計算した埋め込みを、途中で .cf\index.db.partial に書いておき、次の index が使い回す(埋め込みの 設定が同じときだけ)。--full は、これも使わずに消し、すべて埋め込み 直す。形の合わない行は使わず、ファイルを読めなければ、消して続ける
  • index.db.partial は、埋め込みつきの索引ができあがったら消す。 --no-embed(とモデルを読めずに keyword だけで作ったとき)は残し、次に 埋め込みつきで作るときに使う。設定で埋め込みを切った([embedding] enabled = false)索引ができあがったときは消す
  • 止められたときの途中のファイル(index.db.tmp-<番号>)は、その番号の プロセスがもう無ければ、次の索引づくりが消す。番号の形でない名前の ファイルには触れない
  • index --download でモデルの取得に失敗したときは、1 行で知らせて、 終了コード 2 で止まる
  • できあがった索引で index.db を置き換えられないとき(Windows で、 ほかのプログラムが開いている)は、index.db.new に残して、終了コード 1 で止まる。次の index は、そこから埋め込みを使い回す
  • 埋め込みのある索引を、モデルが読めないまま keyword だけの索引に置き 換えない。終了コード 2 で止まり、model download か --no-embed を案内 する。index.bat は、置き換えるかを尋ねる(既定は「いいえ」)
  • source のルートが無いときは、何も書かずに、無いルートをすべて挙げて 止まる(終了コード 2)。入るファイルが 1 つも無いときも、1 行で知らせて 止まる(終了コード 2)
  • 壊れた index.db(SQLite でない、途中で切れた、0 バイト)を、Windows でも置き換えられるようにした
  • 形式の版の違う索引からも、埋め込みの設定が同じなら、埋め込みを使い 回す
  • 索引に、作るたびに変わる build_id と、質問の前置き(query_prefix)を 残す。どちらも無くてよい項目で、0.3.1 の索引はそのまま使える

検索と出力

  • 質問の語は、異なる語の最初の 256 個だけを使う(keyword の側)。とても 長い質問で、誤りになったり、何分も止まったりしなくなった。256 個まで なら、順位は前と同じ。256 個を超えたときは、その旨の note を出す。 用語の対応表で足した語は、質問の後ろの語より先に残す
  • 索引を作り直している最中の検索が、古い索引の番号で新しい索引の passage を返さないようにした
  • 埋め込みの設定(pooling・前置き・ONNX のファイルなど)が索引と違うとき は、semantic と hybrid をやめて keyword にし、その旨を note で知らせる
  • エージェント向けの形では、索引の後に消えたファイルの passage は、本文を 見せず、場所だけを [file no longer exists] の印つきで出す。人が読む 形は、「※索引の後に消えたファイル」の印を付けて、索引のときの本文を 出す。JSON は、本文に missing: true を付ける。本文は、索引を作り直す まで index.db に残る
  • 場所だけの行にも、[changed since index] と [file no longer exists] の印を付ける。古い passage があるときは、頭に stale: … の 1 行、 終わりに引用の前に今の行を確かめるよう求める段落が足される
  • source のルートが作業フォルダそのものでないときは、終わりの手前に roots: <id> = <ルート>, … の 1 行を出す(source:path をどこで開けば よいか)。作業フォルダの外のルートは、設定の絶対パスのまま出るので、 検索のたびにモデルに送られる
  • エージェント向けの出力は、上限(既定 12,000 バイト)に収まる。収まら ないときは、場所だけの行のシグネチャから落とし、最後は (+N more matches, not shown) にする。消えたファイルの場所の行は、ほかの場所の 行より先に場所を取っておく(消えたファイルを含む出力は、0.3.1 と並べ方が 違うことがある)。場所の行だけで上限を超えるとき(上限を小さくしたとき など)は、消えたファイルの行も後ろから落として (+N more matches, not shown) に数える。上限を超えるのは、頭・note・古い passage の段落・ roots: の行など、決まって出す部分に、More matches の見出しと件数の 行(合わせて 60 バイトほど)を足した大きさが上限を超えるときだけ(上限を 最小の 1,000 バイト近くにして、ルートの行がとても長いときに起きうる)。 とても長い 1 行で、後ろの passage の本文が出なくなっていたのも直した
  • ルートが見つからない source の passage には、変わったかを確かめられない 旨の note が出る
  • 作業フォルダの名前を変えたり、動かしたりしても、[changed since index] の確かめが働く(今の設定のルートを見る)
  • パスに %・?・# がある作業フォルダと、UNC のパスで、索引を開ける ようにした
  • Windows の 260 文字を超えるパスのファイルが、変わっていないのに [changed since index] になっていたのを直した
  • 人が読む形で、0 件のときに「索引(<日時>)の後に増えたファイルは、作り 直すまで検索に出ません」と出す。消えたファイルには 「※索引の後に消えたファイル」と出す

status

  • status --check を足した。フォルダを歩いて、索引の後に変わった・増えた・ 消えたファイルを数える(ファイルを読むので、大きいコーパスでは数十秒 かかる)。既定の status と検索では行わない。数えるのは、今の版の取り 込みの規則で作り直すと変わるファイルなので、ほかの版の道具で作った 索引では、規則の違いの分も入る。そのときは(増えた・消えたが 1 つでも あれば)、索引を作った道具の版と、そのことを知らせる
  • source ごとに、今の設定のルートを出す。エージェント向けの形は sources: engine = corpus/engine (7 files, 17 passages), …。索引を 作ったときとルートが違えば、人が読む形にそれも出す。JSON の root は、 今の設定のルートになった(新しく folder と、違うときの indexed_root)

MCP サーバー

  • .cf か索引の無い作業フォルダでは、起動の挨拶の指示を「No context-foundation index in this workspace; search with grep.」にする。 索引のある作業フォルダの指示、道具の名前・説明・引数は、前と同じ
  • 8,192 バイトを超える質問は、誤りとして断る
  • 形の崩れた要求(params が object でない、深すぎる JSON、NaN や Infinity を含むもの、id が有限の数でないものなど)で落ちなくなった。 JSON-RPC の誤りで答える。答えを JSON にできないときも、決まった Internal error の 1 行で答え、詳しいことは標準誤差に書く
  • 設定ファイルを読めないとき(UTF-8 でない、開けない、TOML の誤り、 [search] などが表でない)も、起動の挨拶には、ふだんの指示で答える。 理由は、道具を呼んだときの誤りの文で返す。コマンドは、その理由を 1 行で出して、終了コード 2 で止まる(UTF-8 でない設定と、表でない 項目では、前は traceback だった)
  • 用意ができていないときのサーバーは、理由と setup のコマンドを標準誤差に 書き(コマンドの後ろは改行で、句点を付けない)、道具を呼ばれたときも 同じ文で答える。このサーバーも、標準出力には JSON の行だけを書く。 NaN・Infinity を含む行、深すぎる JSON の行、形の崩れた行は読み 飛ばし(答えない)、答えを JSON にできない要求(id が 1e999 など) にも答えない。前は、id が NaN の要求に JSON でない行を返し、深い 入れ子の行で落ちていた

入口と用意(setup)

  • 対応する Python を 3.11 から 3.14 にした。範囲の外の Python では、setup は何もせずに止まり、使う版の起動のしかた(py -3.14 -I "<…>\ctxf.py" setup など)を示す。setup.bat は、py -3.14・-3.13・-3.12・-3.11、 python の順に探す
  • setup.bat は、壊れた .venv や、範囲の外の Python で作った .venv を 作り直す。入れた後に、要るパッケージ(numpy・onnxruntime・tokenizers・ tree_sitter・jsonschema)を読み込めるかを確かめ、読めなければ .venv を 1 回だけ作り直して入れ直す。それでも読めなければ、その旨を出して終了 コード 1 で終わる。最初の用意の段(モデルを取得するかを尋ねるところ)が 失敗したときも、終了コード 1 で終わる(前は 0。モデルの取得を断るのは 失敗ではない)
  • ctxf.py setup も、pip が入れ終えたのに要るパッケージを読めないとき (仮想環境の Python が、同じフォルダのまま別の版に置き換わった、 パッケージの一部が壊れたなど)は、読めない理由を出して、仮想環境を venv --clear で 1 回だけ作り直して入れ直す。それでも読めなければ、 「pip installed the Python packages, but they cannot be loaded (…). Delete the folder <仮想環境> …」と出して終了コード 1 で終わる(pip は 入れたものの記録だけを見るので、入れ直さない)
  • .bat は、ctxf.py --run を通して動く。フォルダを動かしても写しても 動く
  • pip が失敗したときの最後の 1 行が、原因を選んで示す(パスが長すぎる、 PyPI に届かない、この Python 向けの配布物が無い)。Windows で長いパスが 切ってあり、置き場のパスが長いときは、pip の前に知らせる
  • setup --gpu と --cpu の切り替えは、入れ替える先を入れられると 確かめてから、今のものを外す。入れられなければ、何も変えずに止まる
  • モデルの取得の失敗は、1 行で知らせる(長いパスか、ネットワークと プロキシ)
  • 仮想環境のもとの Python が消えていたら、「set up with a Python that is no longer installed」と知らせる。隣の .venv(リポジトリを取得した人) でも同じに見て、利用者ごとの置き場には切り替えず、直すコマンドとして setup.bat を示す(Windows 以外では、.venv を作り直す python3 -m venv --clear .venv からの 1 行)。Windows 以外では、bin/python の 指す先の版(python3.12 など)が pyvenv.cfg の版と違うときも、同じに 扱う。隣の .venv が壊れているときは、セッションの始めの 1 文も、 grep で探すことと、setup.bat を利用者に頼むことを伝える(控えの skill も同じ python で動くので、勧めない)
  • 仮想環境の python が、要るパッケージを読めないとき(もとの Python が 別の版に替わったなど)、子は終了コード 104 で、標準入力を読む前に 終わる。入口はそれを受けて、「set up in a virtual environment whose packages can no longer be loaded」と知らせる(serve は道具を出さない サーバーになる。ほかのコマンドは終了コード 4)。pip で入れた ctxf serve も、同じときは終了コード 104 で、標準出力に何も書かずに終わる。 道具そのもの(context_foundation のモジュール)の import の誤りは、 これに読み替えず、traceback を出して終了コード 1 で終わる。この知らせは、 検索などのコマンドの文面と MCP のログに出る。where の python: の行と 始めの 1 文には出ない(where では model: unknown (ImportError: …) などになる)
  • 入口(python -I ctxf.py <コマンド>)を Ctrl+C で止めたときは、道具の 後始末を待って、道具の終了コード(130)を返す。traceback は出ない (前は traceback を出し、Windows では終了コード 0xC000013A だった)。 もう一度 Ctrl+C を押すと、道具も止めて、すぐに止まる(Windows でも同じ。 前の入口は、Windows では道具が終わるまで Ctrl+C を受け取れなかった)。 Windows 以外で、 入口のプロセスだけに SIGINT を送った(kill -INT <pid> など)ときは、 道具には届かないので、道具はそのまま最後まで動く。無人で打ち切るときは、 プロセスグループに送る(kill -INT -<pgid>)
  • 壊れた仮想環境を setup が作り直すときも、前の setup で選んだ --gpu を 引き継ぐ。作り直しの途中で pip が失敗したり止められたりしても、次の setup が引き継ぐ(前は CPU 用の onnxruntime に黙って戻っていた)
  • where が、診断に要るものを 1 回で出す(入口の Python、PATH の python、置き場、モデルの有無、今のフォルダと COPILOT_SESSION_CWD から見える索引)。setup: の行は、隣の .venv を使っているときは setup.bat を示す
  • ctxf.py --help が、入口だけのコマンド(setup・where・ session-hint)を先に出す
  • setup の完了の文と、用意ができていないときの文が、新しいセッションが 要ることを知らせる
  • copilot register は、PATH の python が無いか起動しないとき、知らせる (止めはしない)。pip で入れたパッケージからは登録できないと、はっきり 知らせる

文面のコマンド

  • 道具の文面が案内するコマンドは、そのまま動く形にした。入口から動いて いるときは python -I "<…>\ctxf.py" <コマンド>、.bat から動いている ときは .venv の python で ctxf.py --run <コマンド>。入口は、子の プロセスに環境変数 CF_ENTRY で自分の呼び方を渡す
  • エージェント向けの「索引が無い」文は、MCP サーバーのものとそろえた (index.bat に触れない)
  • skill の取り次ぎは、--format が無ければ --format agent を足す

パッケージと CI

  • requires-python は >=3.11,<3.15。依存に上限を足した(numpy <3、 onnxruntime <2、huggingface_hub <3、jsonschema <5)。版を固定した 一覧(lock)は持たない。0.x の版の依存(tree-sitter と文法、tokenizers) には上限が無い
  • sdist に、テスト・評価の例・skill・入口・.bat などを入れた (MANIFEST.in)。docs・bench・examples・skills などはファイルの名前で 挙げ、.cf・*.db・*.pdf などは外すので、git で無視している手元の ファイル(第三者の資料、公開しない計測、.cf の索引)は入らない。 tests・.github・直下の .bat・src は、拡張子とパッケージの探索で入れる ので、そこに置いた追跡していないファイルは入る。配る sdist は、まっさら な checkout から作る(手元で作ったら python .github/scripts/check_sdist.py <sdist> で確かめる。CI は、中身が git ls-files と同じかを確かめる)。 wheel は変わらない
  • CI: テストを Python 3.11・3.12・3.13・3.14(Windows と Ubuntu)で回す。 依存を宣言した下限の版で回す job と、wheel と sdist を作って使う job を 足した。sdist の中身は、git ls-files と同じかを確かめる(足りない・ 余計なファイルがあれば落ちる)。CI とまっさらな機械での確認は、週に 1 回も回す。公開リポジトリでは、60 日間動きが無いと、GitHub が週 1 回の 実行を止める(Actions の画面で有効に戻す)。GitHub Actions の更新は Dependabot が知らせる
  • 実物の埋め込みモデルを使うテスト(tests/test_model.py)を足した。 モデルが手元に無ければ飛ばす

まだ直していないこと

  • 検索は、上位の passage だけを返し、ほかにも当たるものがあるか、当たった ものが的外れかを知らせない。識別子が分かっていて、使われている場所を すべて挙げたいときは、grep を使う。エージェントへの始めの 1 文と道具の 説明は「検索を grep より先に」のままにしてある(計測した形なので、 変えるには測り直しが要る)
  • エージェントへの指示は、検索の語を英語で書くよう求めている。日本語の 設計文書は、日本語の語が検索に入らないと、順位が下がりやすい(skill の 文は、利用者の言葉を残すよう書いている)。同じ理由で、まだ変えていない
  • setup の後も、動いているセッションには検索の道具が出ない(新しい セッションが要る)
  • MCP の status の道具には、--check に当たる引数が無い(道具の引数を 変えないため)
  • index.db.new が残っていても、status と検索は知らせない
  • 作業フォルダの設定は、作業フォルダの外も指せる。[[source]] root (~ も)、[embedding] model_dir と onnx_file(索引に埋め込みが あれば、MCP サーバーは起動の挨拶のときに、そのモデルを読み込む)、 用語の対応表。[embedding] model = "hash-256-test-only" で、テスト用の埋め込みも選べる。どれも 意図した機能なので閉じていない。MCP サーバーで外を読まないようにするかは、 まだ決めていない。それまでは、取ってきたリポジトリに入っていた .cf は 使わない
  • 生成物の判定の限界: 頭のコメントのかたまり(docstring も)のどの行 でも、書き出しが説明にもよく出る形の手書きのファイル(// Auto-generated ids …、"""Schema compiler. の後の Generated from the schema: … など)は、除かれる(0.3.1 では入っていたものもある。入れるには [index] skip_generated = false)。文の途中の「X is generated by Y」は、印に しない

0.3.1(2026-11-16)

  • 索引づくりの埋め込みを、GPU でも計算できるようにした(設定の [embedding] device。既定は auto)。入口の setup に --gpu・--cpu を足した(Windows。onnxruntime を onnxruntime-directml に入れ替える)

更新のあとにすること: 何も要らない。GPU を使うときだけ setup --gpu。

0.3.0(2026-11-16)

  • 既定の出し方を、MCP サーバーと「検索を grep より先に」の始めの 1 文に 変えた。skill は、MCP の道具が使えないときの控えになった
  • MCP サーバーは、起動の挨拶のときに、埋め込みモデルとベクトルを裏で先に 読み込む([search] preload = false で止められる)
  • MCP サーバーは、COPILOT_SESSION_CWD の場所から .cf を探す
  • 用意が済んでいない PC では、道具を出さないサーバーとして答える
  • copilot register --mcp は、何もしない指定になった

更新のあとにすること: 新しいセッションを始める(MCP サーバーは、プラグイン の更新のあとのセッションから動く)。

0.2.2(2026-11-16)

  • skill が、skill のフォルダの直下の取り次ぎ(skills/context-search/ctxf.py) を呼ぶようにした(エージェントが入口のパスを組み立て間違えていた)

更新のあとにすること: 何も要らない。

0.2.1(2026-11-16)

  • 中身の無い passage(include の並び、名前空間の開き閉じ、前方宣言だけの もの)を埋め込まず、意味検索の順位から外す

更新のあとにすること: 効かせるには index をもう一度流す(中身のある passage の埋め込みは使い回す)。

0.2.0(2026-11-16)

  • Copilot のプラグインと Marketplace の形にした(plugin.json・ .github/plugin/marketplace.json)。Python の依存は、プラグインの外の 利用者ごとの置き場に、ctxf.py setup で 1 回だけ置く
  • init を足した(作業フォルダに設定を作る)
  • 日本語だけの質問に、用語の対応表で英語の語を足す
  • register-copilot.bat は、このフォルダを手元の Marketplace として足し、 プラグインを入れる

更新のあとにすること: プラグインとして入れ直す。0.1 の登録の形(copilot skill add と hook のファイル)は、register-copilot.bat が確認のうえで 外す。プラグインとして入れた人は、最初に 1 回 setup。

0.1.0(2026-11-16)

最初の版です。

  • 取り込み、構文の単位の分割(C・C++・C#)と見出しの単位の分割 (Markdown)、keyword・semantic・hybrid の検索(SQLite の 1 ファイル)
  • 評価データの形式と検査、検索だけの手法の評価、エージェントを使う手法を Copilot CLI で回す道具(bench)
  • skill・読み取り専用の MCP サーバー・始めの 1 文の hook の登録と、.bat
  • 差分更新(変わっていない passage の埋め込みを使い回す)、 index --revision