fullseye

Fullseye を AI アシスタントの RAG にする手順(Claude Code 向け)

Fullseye の推奨運用は「AI コーディングアシスタントの知識ベース(RAG)として使う」こと。 全 op が機械可読な Markdown ノート(docs/ops、単一真実源)を持つため、追加のベクタ DB や 埋め込みサービスは不要です。grep できる環境ならそれがそのまま RAG になります。

3 段階の導入方法を用意しています。Tier 0/1 は外部依存ゼロ(Fullseye リポジトリだけで完結)。

PyPI からの利用: pip install fullseye した環境では console script fullseye-rag が 使えます。checkout(clone / pip install -e .)なら docs/ops のフルコーパスを、wheel のみ なら同梱の OP_CATALOG.md(AI 向け全 op カタログ)をスキルにピン留めします(フルの per-op ノートが欲しくなったら repo を clone して再実行するだけ)。更新は py -3.11 tools/update_fullseye.py(dirty ツリー拒否・–ff-only・スキルはバックアップの上 更新・Studio 設定には触れない=環境をつぶさない設計)。

入口は 1 つではない(最初に読む)

文書だけを渡した Codex / Copilot は、どちらも 1 回目に用途から引く索引を見つけられなかった(2026-09-15)。このガイドに導線が無かったからです。入口は 5 つあります:

  1. 用途から → docs/CAPABILITIES.md。課題 → 推奨パイプライン(順序つき op)/ 代替 / 限界 / 実寸校正 を 1 課題 1 ファイル(docs/capabilities/)で持ち、op 名の実在と型(in → out)が前段から後段へ繋がることを tests/test_capabilities.py が検査します。
  2. やりたいことの言葉で → fullseye-rag search / fullseye.search_ops(次の節)。
  3. op 名・概念から → docs/ops/INDEX.md → 族の目次 → op ノート。
  4. 機械で引く → fs.op_find(query)(自由語・語幹)/ fs.op_assist(op)(仕様・プリセット・次に繋げる先)/ fs.op_path(from_sort, to_sort)(型 A → 型 B を繋ぐ op 列)/ fs.op_producers(sort)(その型を産む op)/ fs.op_accepts(op)(実測の受理型)、CLI は fullseye has <op>(HALCON 名でも引ける)。
  5. 索引ファイル → docs/OP_INDEX.json(全 op の型契約)、wheel 同梱の OP_CATALOG.md。

Windows のシェルから読むときは UTF-8 を明示する —— ノートは BOM 無しの UTF-8 で、既定のコードページで開くと日本語が文字化けし、AI が「読めていない」のに「無い」と判断します(Codex で実際に起きた)。PowerShell は Get-Content -Encoding utf8、Python は PYTHONUTF8=1。

まず探す: やりたいことの言葉で op を引く(どの Tier でも使える)

fullseye-rag search "ノイズ除去"            # コマンド(pip install fullseye だけで動く)
fullseye-rag search "edge detection" -k 5 --lang en

import fullseye
fullseye.search_ops("边缘检测", k=5)          # Python。MCP なら fullseye_find_ops

op の要約は 7 言語(日本語の原文 + 英語・中文 簡体 / 繁体・한국어・Deutsch・हिन्दी の訳。ヒンディー語は術語を英語のまま書いているので、術語は英語で引く)で索引にしてあり、 名前・HALCON 名・入出力の型と一緒に照合して、順位つきで「要約(問い合わせの言語)+ ノートの場所」を返します。 ノートの本文は日本語なので grep では「Rauschen」「降噪」「잡음」が 0 件ですが、この検索なら母語で引けます。 埋め込みや外部サービスは使いません(BM25、標準ライブラリだけ)。同義語は拾わないので、当たりが薄いときは 別の言い方か英語で引き直してください。名前が分かっているなら MCP の fullseye_search_ops(部分一致)が速いです。 実行できる例: py -3.11 examples/find_ops_by_meaning.py。

Tier 0: リポジトリを開くだけ(手順ゼロ)

Fullseye リポジトリのチェックアウトを Claude Code で開けば、docs/ops/INDEX.md と per-op ノートをそのまま検索・参照できます。コーパスはリポジトリ内容(wheel には同梱しない) なので、pip インストールのみの場合はリポジトリも clone してください。

docs/ops/2d/<category>/<op>.md   # 呼び出し形・型契約・HALCON 別名・文献・関連 op
docs/ops/3d/<category>/<op>.md
docs/ops/INDEX.md                # フォルダ階層 walk で自動生成の全体目次
docs/ops/<family>/guides/<name>.md   # 族ごとの使い方ガイド(数式・図・正典引用)
docs/OP_INDEX.json               # レジストリの機械可読インデックス

Tier 1: スキルとして常駐させる(推奨・同梱インストーラー)

自分のプロジェクト側で作業しながら Fullseye を引きたい場合は、同梱のセットアップ スクリプトを 1 回実行します:

py -3.11 tools/setup_claude_rag.py              # インストール(再実行=更新)
py -3.11 tools/setup_claude_rag.py --uninstall  # 削除

同梱スキル skills/fullseye-ops が ~/.claude/skills/fullseye-ops へコピーされ、 SKILL.md の FULLSEYE_REPO = 行がこの checkout の絶対パスに自動で固定されます (AI がどのプロジェクトで作業していてもコーパスの場所が分かる)。コーパス (docs/ops)が見つからない checkout ではインストールを拒否します(fail-closed)。

以後、画像処理・幾何ビジョンの話題で Claude Code が自動的にこのスキルを起動し、 docs/ops を検索(retrieve)→ 型(sort)が繋がる op を選んで実装 → 同梱の worked example で 検証、という流れで動きます。スキル本文がそのまま「AI への使い方指示書」です。 手動で入れたい場合は skills/fullseye-ops を ~/.claude/skills/ へコピーするだけでも 動きます(パス固定が無い分、AI がリポジトリ位置を都度探します)。

Tier 2(任意): クラスタ化コーパス — 外部ツールでの発展形

ノート 3,629 枚をトピッククラスタに階層化し、各クラスタに LLM 要約を付けた 「ナビゲーション付きコーパス」も作れます。私たちは内部で RAPTOR フォークの corpus2skill (TF-IDF + k-means + LLM 要約)を使っていますが、これは任意の最適化であって 必須ではありません。要件は「docs/ops を入力に、クラスタごとの SKILL.md 階層を 出力する」ことだけなので、同等のツールなら何でも代替できます。

再取込(ノート更新後)の例 — 内部運用そのままの honest な記録として:

$env:RAPTOR_DIR="<path-to-raptor-checkout>"
py -3.11 raptor_corpus2skill.py --source <fullseye>/docs/ops --name fullseye_ops_corpus_v2 `
  --overwrite --max-depth 2 --max-clusters 6 --min-cluster-size 8   # 要 ANTHROPIC_API_KEY

注意: クラスタ化コーパスは取込時点のスナップショットです。docs/ops を更新したら 再取込しないと陳腐化します(Tier 0/1 は常に生ノートを読むため陳腐化しません)。

Tier 3(同梱): 文献層 —— 製造と運転の知識を「使う op」に落とす

op ノートは「この op が何をするか」を答えますが、「この工程・この部品では何を測ればよいか」は答えません。 その隙間を埋めるのが docs/literature/ です。外部の文献コーパス(メカ設計・メカトロ部品・ 製造工程、運転のシミュレーションと評価・センサーの模擬、OpenAlex のメタデータ約 8,900 本。テーマ → op の表は分野ごと)をクラスタごとに要約し、 光学計測と外観検査の信頼性(POD・スペックル・偏光からの形状復元・大域光輸送・受入試験と不確かさ・合成データの 6 軸)は人が論文を厳選して軸ごとに概観を書いた層(目録 docs/literature/curated/)として持ち、各クラスタで使う op(人が書いたテーマ → op の 対応表、op 名は生成時に出荷ノートと突き合わせて実在を保証)と、代表論文の題名・年・DOI を来歴として付けてあります。 読む順は「工程・部品・運転の評価の話題 → 文献層のクラスタ → 使う op → op ノート(型の契約・実行できる例)→ 実装」。抄録は写さず、 語の一致で op を引くことはしません(一般語で無関係の op が並ぶのを実測して捨てました)。コーパス本体は repo に無いので、 この層だけは tools/gen_literature_notes.py --rad-root <RAD> で作り直し、tests/test_literature_notes.py が形を守ります。 引ける経路の正直な範囲: この層はリポジトリのファイルとして読む(Claude Code のスキル fullseye-ops、checkout モード)ときに引けます。 MCP サーバーの検索(fullseye_search_ops / fullseye_find_ops)と fullseye-rag search は文献層のクラスタや論文を返しません。ただしテーマ → op の表で人が書いた文脈(「テーマ: なぜ使うか」、日本語と英訳)は意味で引く検索の索引語に入っていて、現場の言い方(「溶接ビードの高さ」「研磨の除去量」)で op を引け、結果の contexts 欄に出ます。 wheel(pip install)にも docs/literature は入っていません。

なぜこれが機能するか(設計上の根拠)

  1. md=単一真実源: ノートはレジストリから決定的に自動生成され、CI の drift テストで 「commit 済みノート == 現在のコードから生成したノート」を強制。AI が読む文書と 実際のコードが常に同じ版です(frontmatter の version + fingerprint)。
  2. 型(sort)契約: 各ノートが in:/out: と「型が繋がる関連 op」を持つので、AI は パイプラインを型検査しながら組めます。
  3. 検証可能: 全 op に ground-truth 付き worked example(examples/ / examples_3d/)があり、AI が自分の提案を実行して確かめられます。
  4. 表示まで一気通貫: Studio(py -3.11 studio.py)を開けば、AI が組んだ結果を 画像ウィンドウ・3D 表示として人間が同じ画面で検査できます(dev_open_window 等で スクリプトから複数窓の配置も可能)。

    op グラフを使う手順

入出力の型が分かる場合は plan(have, want, goal, direction=...) を最初に使う。既定ではMCP pipelineから 実行できる辺だけをDAGとして計画する。台帳だけにある研究用opを調べる場合に限り、Python APIの constraints={"executable_only": false}を使う。これはMCPのAI向けschemaには出さない。 describe は1件だけを返し、全型一覧を無制限に返さない。choose は比較できる実測がない候補を順位付けしない。 つまみ範囲は docs/op_knob.json の実測と入力文脈に基づき、効かなかったつまみを探索から除く。

This site is open source. Improve this page.