noxitro/context-foundation
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 の「確かめたこと」)
更新のあとにすること
- setup のやり直しと、索引の作り直しは要りません。 依存の一覧も、 索引の形式も変わっていません
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 の「確かめたこと」)
更新のあとにすること
- setup のやり直しと、索引の作り直しは要りません。 依存の一覧も、 索引の形式も変わっていません
/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 でもテストを流しました)。
更新のあとにすること
- 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を流してください - Copilot の新しいセッションを始める。 動いているセッションには、 setup の後も検索の道具は出ません(控えの skill は動きます)
- 設定を確かめる。
.cf\config.tomlに[search] rerankerかrerank_candidatesがあると、止まります。消してください。[index] pathは、.cfの中のファイル名だけにできます - 索引は、作り直さなくても使えます。 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を流すと消え ます
- 流すと、ソースを変えていなくても、索引に入るファイルが両方の向きに
変わります。0.3.1 が生成物として除いていた手書きのファイルの多くが
入り、0.3.1 が見逃していた生成物の一部が抜けます。逆向きもあります。
頭のコメントのかたまりのどこかの行が「generated from / with /
using」「auto-generated」などで始まる手書きのファイルは、0.3.1 では
入っていても、除かれます(入れるには
安全
- 作業フォルダの設定から、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.)
- バナーの形(「This file was generated」「File automatically
generated by」「Generated by」「autogenerated」「このファイルは
自動生成」「自動生成ファイル」など)は、頭の 2,000 文字のどの
コメントの行でも、書き出しにあれば印にする。前に飾りの記号や、
短い前置き(
- 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