Benben Kingdom Helper（奔奔王国攻略助手）
ローカルのマークダウン形式で書かれた奔奔王国の攻略ノートを、## 見出しでセクションに分割し、JSON インデックスファイルに保存します。すべてのクエリは BM25 キーワード検索で処理されます。
コア機能
- インデックスの構築/再構築 — 設定ディレクトリ内のすべての md ファイルを
##見出しでセクションに分割し、JSON インデックスファイルに書き込みます。 - 意味検索 — プレイヤーの質問に対して BM25 キーワード検索を実行し、最も関連性の高い断片を返します。Claude がゲーム用語を使って文脈に沿った回答を構成します。
- インクリメンタル更新 — ローカルの md ファイル、Web ページ記事、微信公衆号の記事を知識ベースに新規追加/更新できます。
トリガー条件
ユーザーメッセージに 「奔奔」 または 「奔奔王国」 が含まれている場合にトリガーされます。
以下の状況に応じて、それぞれのフローを実行します：
- 攻略/質問を尋ねる → 【クエリフロー】
- md のパスや URL を提供して追加を依頼 → 【インクリメンタル更新フロー】
- 初回利用 / インデックス再構築の要求 / インデックスが空 → 【初期化フロー】
クエリフロー（すべての質問はここを通る）
純粋なキーワード/BM25 検索。embedding モデルやベクターデータベースは不要です。
- 実行：
python -m scripts.query --question "<ユーザーの質問>" --top-k 8 - 返された JSON（構造は
references/schemas.mdを参照）を解析し、その中の_footerフィールドを取得して後で使用します：chunks：最も関連性の高い原文の断片（ソースファイル、タイトル、見出し、内容、タグ、スコアを含む）concepts：空の配列（概念抽出は削除済み）sources：ヒットしたファイルのリスト（重複排除済み）max_score：最高 BM25 スコア_footer：固定のフッターテキスト
- 検索結果を使用して回答を構成し、末尾に手順2で取得した
_footerの値を追加します：- 奔奔王国独自の用語（「伝説」「集结」「駐防」「ハムる」「無課金」「体力」「号角」「試練」「秘境」「四代」「三代」……など）を使用し、汎用的な言葉に翻訳しないこと。
- このゲームをやり込んだベテランプレイヤーのように、結論と理由を直接述べ、テンプレート的な表現は避けてください。
- 検索結果に「ここは注意」（「絶対にダメ」「注意」など）というヒントがあれば、必ず含めてください。
max_scoreが 0 の場合、または結果が空の場合は、捏造しないでください。正直に「ノートデータベースに関連する内容が見つかりませんでした。新しい攻略を追加しますか？」と伝えてください。
初期化フロー（初回利用時）
ステップ 1 — 知識ベースのパスを設定
python -m scripts.setup --set-vault /path/to/your/vault
/path/to/your/vault は、あなたが奔奔王国の攻略マークダウンファイルを保存しているディレクトリです。
ステップ 2 — インデックスを構築
python -m scripts.index_vault
vault ディレクトリ内のすべての .md ファイルをスキャンし、## 見出しでセクションに分割して ~/.benben-kingdom/index.json を生成します。
以降は質問するだけでOK — インデックスは事前に構築されています。
インクリメンタル更新フロー
A. ローカルのマークダウンファイル
python -m scripts.add_source --path <絶対パス>
B. Web ページ / 微信公衆号 URL
wechat-article-pdfスキル（または他のツール）を使って URL をマークダウンに変換し、一時ファイルに保存します。- 実行：
python -m scripts.add_source --path /tmp/benben-xxx.md \
--origin-url <元のURL> --title "<記事タイトル>"
C. 直接貼り付けられたテキスト
一時的な md ファイルに書き込んだ後、A のパスを通して実行します。--title でタイトルを指定してください。
インクリメンタル更新のたびにインデックスが自動的に再構築されるため、追加の操作は不要です。
スクリプト早見表
すべてのスクリプトはスキルディレクトリから python -m scripts.<名前> で実行します：
| スクリプト | 用途 | 主要パラメータ |
|---|---|---|
setup.py | 依存関係のチェック、初期化 | --check, --reset |
index_vault.py | JSON インデックスの構築 | --vault <パス> |
add_source.py | 単一 md の追加/更新とインデックス再構築 | --path, --origin-url, --title |
query.py | キーワード/BM25 検索、JSON を返す | --question, --top-k |
設計原則
- キーワード検索が唯一のエントリポイント：すべての質問は必ず
query.pyを通さなければならず、md ファイルを直接読んで回答してはいけません。 - 決定論的な操作はスクリプトに、言語理解はモデルに：インデックス構築や検索ロジックは明確で信頼性が高く、回答の構成方法は Claude が判断します。
- 捏造しない：検索結果がない場合は、ないと伝えます。ゲームのバージョン更新は速いため、間違った回答をするよりも、答えない方がマシです。
- プレイヤー用語を使う：プレイヤーは「ハムる」「無課金」「カンニング」「号角を吹く」「部隊に入る」などと言います。そのまま使うことで、古参プレイヤーがアドバイスしているような雰囲気を出します。
参考ドキュメント
references/schemas.md— スクリプトの JSON スキーマ / データベーステーブル構造references/configuration.md— 設定項目の説明references/troubleshooting.md— よくあるエラー（インデックスファイルの欠落、Vault パスの誤りなど）