Fork: 0
dtmoyaji / TelosDB
Transfer to URL with SHA Find file
Newer
Older
TelosDB / journals / 202602-009-2月第4週ジャーナル集約.md
@楽曲作りまくりおじさん 楽曲作りまくりおじさん 14 hours ago 30 KB chore: ジャーナル週次集約・.gitignore・tmp・ローカルDB除外
Raw Blame History

2026年第009週 (2/23) 作業アーカイブ: ディレクトリ整理・Issue運用・v0.3.0・MCPリファクタ

週全体のサマリー

今週（第009週）は、2月23日単日の集中作業として、ディレクトリ整理とビルド修復から始まり、Issue 双方向同期・仕様書現代化・DB正規化・v0.3.0 リリース・UI刷新・MCPモジュール分割まで、23件の案件が実施された。重要な方針・指摘の変遷: (1) GitBucket を Source of Truth とする Issue 運用と手動クローズのルール化、(2) 仕様・運用の分離（docs/specification と .agent/rules）、(3) DB の documents/items 正規化とマイグレーション v0.2.5→v0.3.0、(4) コード品質基準（600行・7階層）に基づく MCP の機能分割。

gantt
    title 第009週 プロジェクト進捗 (2026-02-23)
    dateFormat  YYYY-MM-DD
    section 環境
    ディレクトリ整理とビルド修復     :2026-02-23, 1d
    ソース不要ファイル掃除           :2026-02-23, 1d
    section Issue
    GitBucket双方向同期ツール         :2026-02-23, 1d
    Issue Dir Git除外・手動クローズ   :2026-02-23, 1d
    section ドキュメント
    仕様書現代化・LSA化              :2026-02-23, 1d
    仕様と運用ルールの分離           :2026-02-23, 1d
    section DB
    テーブル正規化・マイグレーション   :2026-02-23, 1d
    スキーマバージョン管理            :2026-02-23, 1d
    section リリース
    v0.3.0 繰り上げ・リリース        :2026-02-23, 1d
    section UI・MCP
    UI刷新・MCP応答標準化・リファクタ :2026-02-23, 1d

2026-02-23: ディレクトリ整理とビルド修復

1. 作業実施の理由と指示

  • 背景: ディレクトリ構造が複雑化し、ルート直下に不要フォルダや散乱したスクリプトが多数存在。Error 1412 でクラッシュする状態に。
  • 意図と指示: ルートを機能ごとに整理し、Tauri ビルド出力をルートに再配置したうえで Error 1412 の解消とビルド通しの確認。

2. 指摘事項とその対応

  • 指摘: 起動時に「Error 1412: Failed to unregister class Chrome_WidgetWin_0」が発生。
    • 対応: 真の原因は vec0.dll 未検出による Rust パニックと特定。build.rs の相対パスを ../../node_modules に修正して解決。
  • 指摘: テストスクリプトもルートに。
    • 対応: scripts/ 内の test_mcp_client.mjs 等をルート直下の tests/ に移動。

3. 作業詳細

AIエージェントは、ビルド出力の最適化（.cargo/config.toml）、不要フォルダ削除、ツール群の tools/ 集約、テストの tests/ 集約、ドキュメントの docs/specification 等への統合、ログの logs/ 隔離を実行した。

4. AI視点での結果

ビルドエラーの根本原因が修正され、ディレクトリが機能・役割ベースで再構築され、保守性が向上した。

2026-02-23: ソースディレクトリの不要ファイル掃除

1. 作業実施の理由と指示

  • 背景: src/ 配下の不要ファイルの調査・整理の指示。
  • 意図: React テンプレートの残骸や一時ファイルを一掃しソースツリーをクリーンに保つこと。

2. 指摘事項とその対応

  • 指摘: src/frontend/ に React 時代の不要アセットが残っている。
    • 対応: App.css、assets/、types/ を削除。
  • 指摘: src/backend/ に一時 DB 等が残っている。
    • 対応: telos.db* および空の logs/ を削除。tests/ は保持。

3. 作業詳細

未使用ファイルのリストアップと実装プラン作成ののち、PowerShell で対象を削除。

4. AI視点での結果

フロント・バックエンドとも本番に必要なコードとリソースのみが残る洗練された構造となった。

2026-02-23: GitBucket Issue 双方向同期ツールの作成

1. 作業実施の理由と指示

  • 背景: GitBucket の Issue をローカル docs/issues/ に Markdown で同期（プル・プッシュ）したい要望。
  • 意図: 双方向同期スクリプトを構築し、GitBucket をシームレスなローカル Issue トラッカーとして利用可能にする。

2. 指摘事項とその対応

  • 指摘: 全 Issue 取得と更新の仕組みが必要。
    • 対応: GitHub API 互換エンドポイントに対し fetch を用いた tools/scripts/sync_issues.mjs を作成。
  • 指摘: 双方向の整合性。
    • 対応: Frontmatter（id, state, title, updated_at）でメタデータを保持し、updated_at 比較で Pull/Push。id: new は POST で新規発番からリネームまで自動処理。

3. 作業詳細

実装計画とタスク定義ののち、sync_issues.mjs を実装。既存 Issue 2件の Pull に成功。

4. AI視点での結果

IDE 上で Markdown として Issue の閲覧・追記・クローズが可能になり、開発フローが効率化された。※ リモート Push には .env の GITBUCKET_TOKEN が必要。

2026-02-23: IssueディレクトリのGit管理除外

1. 作業実施の理由と指示

  • 背景: リモートが正のため、docs/issues/ を Git で二重管理しないようにしたいとの指摘。
  • 意図: .gitignore に docs/issues/ を登録し、追跡から除外する。

2. 指摘事項とその対応

  • 指摘: docs/issues/ が Git 管理下になっている。
    • 対応: .gitignore に追記し、git rm -r --cached docs/issues/ で追跡のみ解除。

3. 作業詳細

.gitignore 追記、キャッシュからの除外、ジャーナル作成とコミット・プッシュを実施。

4. AI視点での結果

同期スクリプトと Git の責務が分離され、リポジトリが不要な Markdown 履歴で汚れない運用が確立した。

2026-02-23: Issue-1のテストとリリース

1. 作業実施の理由と指示

  • 背景: ディレクトリ改修・脱LLM化に伴い、最新 main で全機能のコンパイル・テスト通過とリリースバイナリ構築が必要。
  • 意図: バックエンド API の正常性を検証したうえで Tauri 本番インストーラーを生成し、Issue-1 をクローズする。

2. 指摘事項とその対応

  • 指摘: API テストが別プロセス起動を前提にしている。
    • 対応: テスト前に cargo run で API サーバーを起動し、cargo test で疎通確認。
  • 指摘: GitBucket へのクローズ反映がスキップされた。
    • 対応: GITBUCKET_TOKEN 未設定のため Push はスキップ。ローカル Issue-1.md は state: closed に更新済み。

3. 作業詳細

テスト・リリース計画の立案、API サーバー起動下での cargo test 成功、npm run tauri build でインストーラー生成、Issue-1 のクローズと同期スクリプト実行。

4. AI視点での結果

大再編後の TelosDB が完全に機能し、本番バイナリとしてリリース可能であることが証明された。

2026-02-23: Issue手動管理ルールの策定と同期ツールの改良

1. 作業実施の理由と指示

  • 背景: GitBucket API の制限（PATCH で 404）により、スクリプトによる自動クローズが不可能と判明。
  • 意図: 「クローズのみ手動」という運用ルールを策定し、ツールで URL 通知等の支援を行う。開発ガイドに追記。

2. 指摘事項とその対応

  • 指摘: 同期スクリプトがエラーで停止する。
    • 対応: 404 を個別にキャッチし、例外を投げず「手動操作が必要」と対象 URL を表示するよう変更。
  • 指摘: ルールの明文化。
    • 対応: 06_development_guide.md に「Issue管理ルール」を新設。

3. 作業詳細

sync_issues.mjs の PATCH 失敗時のリマインド機能実装、開発ガイドの更新、Issue #2 での URL リマインド表示を検証。

4. AI視点での結果

API の制限をルールと補助機能でカバーする運用体制を構築した。

2026-02-23: 仕様書の現代化とLSA化の反映

1. 作業実施の理由と指示

  • 背景: システムが LLM から LSA へ転換したが、docs/specification/ が旧来の src-tauri 依存・LLM 前提のまま。
  • 意図: 現状のディレクトリ（src/frontend, src/backend）および LSA ベース検索エンジンに即して仕様書をすべて更新する。

2. 指摘事項とその対応

  • 指摘: 仕様書がレガシーのまま。
    • 対応: 01_system_overview.md〜04_mcp_api_specification.md、07_ui_design_spec.md、mcp.json を LSA・50次元・サイドカー排除に合わせて全面更新。

3. 作業詳細

全ファイルの走査と「脱LLM・LSA特化」に合わせた論理的な書き換え。Mermaid 図もシングルプロセス構成に修正。

4. AI視点での結果

仕様書がソースコードと完全に一致する唯一の正（Single Source of Truth）の状態になった。

2026-02-23: READMEの現代化

1. 作業実施の理由と指示

  • 背景: 仕様書と同様、トップの README.md も LLM 基盤や古いディレクトリ構成の記述が残っていた。
  • 意図: LSA 特化型エンジンと整理後のディレクトリに合わせて README を最新化する。

2. 指摘事項とその対応

  • 指摘: README もレガシー。
    • 対応: コンセプトを LSA/50d に変更、システム構成図からサイドカーを排除、ディレクトリ構成を src/frontend, src/backend 等に修正、環境要件から重いモデル不要を反映。デザインをミニマル・ハイコントラストに修正。

3. 作業詳細

古いパスの置換、LSA による「GPU不要」「モデル配置不要」の強調、デザイン文言の修正。

4. AI視点での結果

初見の開発者・エージェントが現在のアーキテクチャを正しく把握できる環境が整った。

2026-02-23: Issueの日英併記ルールの策定

1. 作業実施の理由と指示

  • 背景: 透明性とグローバル対応のため、Issue を日本語・英語の両方で管理する方針に。
  • 意図: 全 Issue でタイトル・本文を日英併記とし、既存分の翻訳を補完。片方のみの場合はもう一方を追記する運用とする。

2. 指摘事項とその対応

  • 指摘: 既存 Issue が日本語のみ。
    • 対応: Issue-1.md および Issue-2.md に英語を追記。
  • 指摘: ルールの明文化。
    • 対応: 開発ガイドの「Issue管理ルール」に日英併記の義務化を追加。

3. 作業詳細

開発ガイドの更新、Issue-1/Issue-2 の翻訳・更新、同期スクリプト実行と手動更新用 URL リマインドの確認。

4. AI視点での結果

ローカル docs/issues/ はすべて日英併記となり、新規 Issue でも自動で翻訳提案・補完する流れが確立した。

2026-02-23: Issueトラッカー仕様の抽象化

1. 作業実施の理由と指示

  • 背景: 「GitBucket」という固有名詞のため、他トラッカー（GitHub, GitLab, Gitea）へのポータビリティが損なわれていた。
  • 意図: 「上流 Issue トラッカー」「GitHub 互換 API」等の抽象表現に置き換え、汎用性を高める。

2. 指摘事項とその対応

  • 指摘: GitBucket 連携を仕様に書くとポータビリティが失われる。
    • 対応: README と 06_development_guide.md で製品名依存を排除し、「上流トラッカー」「GitHub v3 互換 API」に抽象化。

3. 作業詳細

該当ドキュメントの走査と意味を維持したままの呼称変更。同期スクリプトの実装詳細ではなく「外部トラッカーとの同期」という運用定義に修正。

4. AI視点での結果

制約が「特定ソフト」から「プロトコル（GitHub API v3）」に昇華し、将来のトラッカー切り替え時も仕様の大幅書き換えが不要な記述になった。

2026-02-23: 仕様書とプロジェクト運用ルールの分離

1. 作業実施の理由と指示

  • 背景: docs/specification/ にプロジェクト運用ルール（GitBucket 連携・Issue の書き方等）が混在し、設計書のポータビリティを損なっていた。
  • 意図: システムの「仕様」とリポジトリの「作法・運用」をフォルダ単位で明確に分離する。

2. 指摘事項とその対応

  • 指摘: GitBucket 連携を仕様に書くのは筋が違う。
    • 対応: 06_development_guide.md から Issue 管理記述を削除し、新設の docs/workflow/issue_management.md に移行。README のディレクトリ案を仕様とワークフロー区別で更新。

3. 作業詳細

docs/workflow/issue_management.md の作成、既存ルールの集約、06_development_guide.md を純粋な技術ガイドに再定義、README の修正。

4. AI視点での結果

設計書は「システムの作り」、ワークフローは「開発の進め方」を独立して記述する健全な構成となった。

2026-02-23: テーブル構造の正規化とドキュメント・チャンクの分離

1. 作業実施の理由

Issue-2 に基づく DB 正規化。従来は items にチャンクごとに同一 path が冗長に保持されていた。

2. 指示（背景・観点・意図）

  • 背景: チャンク分割によりメタデータとデータが混在。
  • 観点: 1 ドキュメント対 N チャンクを DB 上で明示的に管理。
  • 意図: 削除のドキュメント単位一括操作と、検索結果での正しいソース表示を可能にする。

3. 指示事項とその対応

  • documents テーブル: 新設し path を一意に管理。
  • items テーブル: document_id と chunk_index を追加、冗長な path を削除。
  • MCP ツール: add_item_text・search_text を新スキーマに合わせてリファクタ。型不整合は JsonRpcResponse で解決。

4. 作業詳細

db.rs のスキーマ更新、mcp.rs の各ツールリファクタ（特に add_item_text でドキュメント存在確認と既存チャンク削除）、仕様書 ER 図の更新。

5. AI視点での結果

DB 構造がクリーンになり、ドキュメント単位の管理が容易になった。Axum ハンドラと MCP の境界も明確化した。

2026-02-23: 運用ルールの.agent_rulesへの移行と日英併記化

1. 作業実施の理由

ユーザー指示に基づき、運用ルールを .agent/rules に集約し、日英併記を適用するため。

2. 指示（背景・観点・意図）

  • 背景: docs/ に仕様と運用が混在。
  • 観点: AI が読むルールを .agent/rules に置き、セッション開始時にコンテキスト化する。
  • 意図: ルールを日英併記にし、グローバル開発・AI 協調を円滑にする。

3. 指摘事項とその対応

  • ルール配置: issue_management.md を .agent/rules へ移動。技術仕様は docs/specification で継続。
  • 番号調整: 06_development_guide.md → 05_、07_ui_design_spec.md → 06_ にリネーム。
  • 日英併記: 両ファイルに英語翻訳を追加。移動元を削除。

4. 作業詳細

issue_management.md の抽出・英訳と .agent/rules への配置、開発ガイド・UI 仕様のリネームと日英併記、技術仕様と AI 向けルールの境界を明確化。

5. AI視点での結果

運用ルールが .agent/rules に集約され、AI の自己規律が高まる。日英併記で一貫したポリシーとなった。

2026-02-23: MIMEタイプ対応の追加

1. 作業実施の理由

documents に MIME を保持し、将来の PDF・画像・コード等の拡張に対応しやすくするため。

2. 指示（背景・観点・意図）

  • 背景: 現状はテキストチャンクのみだが、ソース形式をメタデータとして保持したい。
  • 観点: スキーマを維持しつつ、自動検知と明示指定の両方をサポート。
  • 意図: フロント表示切り替えやバックエンドのパース処理の布石とする。

3. 指示事項とその対応

  • スキーマ: documents に mime TEXT を追加。
  • 自動検知: mcp 内で path 拡張子から主要 MIME を判別。
  • ツール: add_item_text に mime 引数追加、検索結果に mime を返す。DB 仕様書を更新。

4. 作業詳細

db.rs のテーブル定義修正、mcp.rs の add_item_text と検索・get の MIME 対応、cargo check で整合性確認。

5. AI視点での結果

TelosDB が「型（MIME）を持ったドキュメント集合」としての性質を強め、将来の UI・マルチモーダル対応の基盤となった。

2026-02-23: バージョン0.3.0への繰り上げとブランチ作成

1. 作業実施の理由

MIME 対応等の新機能が完了し、バージョンを 0.3.0 に繰り上げ、リリース用ブランチを作成するため。

2. 指示（背景・意図）

  • 背景: 0.2.x の開発が一区切り。
  • 意図: セマンティックバージョニングに基づきマイナーバージョンを上げ、大きな機能追加を明示する。

3. 指示事項とその対応

  • ブランチ: release/v0.3.0 を新規作成。
  • バージョン: 全関連ファイルのバージョンを 0.3.0 に統一。

4. 作業詳細

release/v0.3.0 の作成とチェックアウト、Cargo.toml・mcp の initialize レスポンス・tauri.conf.json・package.json のバージョン更新、cargo check と Cargo.lock の検証。

5. AI視点での結果

TelosDB が正式に 0.3.0 開発サイクルへ移行し、複数設定ファイルのバージョンが同期された。

2026-02-23: リリースv0.3.0の作成

1. 作業実施の理由

0.3.0 繰り上げに伴い、リリースノートの作成と Git タグ付与でマイルストーンを確定するため。

2. 指示（背景・意図）

  • 指示: 「0.3.0でリリース作って」
  • 背景: リファクタリング・MIME・日本語解析改善等の成果を一つのパッケージとして定義する。

3. 指示事項とその対応

  • リリースノート: RELEASE_v0.3.0.md を作成。MIME、DB 正規化、検索精度向上、Vibrato 移行を網羅。
  • タグ: 現在のコミットに v0.3.0 を付与。

4. 作業詳細

リリースノート作成、release/v0.3.0 へのコミット、git tag -a v0.3.0 -m "Release v0.3.0" の実行。追記としてリポジトリ整理コミット（.githooks、.protected-files、CONTRIBUTING、ジャーナル名正規化等）の要約を記録。

5. AI視点での結果

v0.3.0 が正式にリリース定義され、内部構造の健全化と解析精度向上が両立したマイルストーンとなった。

2026-02-23: データベースのマイグレーション対応（v0.2.5→v0.3.0）

1. 作業実施の理由

v0.3.0 のテーブル正規化により v0.2.5 との互換性が失われたため、既存ユーザーがデータを失わず移行できる自動マイグレーションを実装する。

2. 指示（背景・観点・意図）

  • 指示: 「マイグレーション作れる？」→「ごー」
  • 背景: 手動の DB 削除・再構築はバリアが高いため、起動時にスキーマを自動変換したい。
  • 意図: 既存 items からメタデータを抽出し、documents との 1:N 構造に再編。ベクトル整合のため id を維持する。

3. 指示事項とその対応

  • 自動検知: PRAGMA table_info(items) で古い path の有無を確認し、要否を判断。
  • データ移行: documents 新規作成、ユニークな path を移行。items を新スキーマで再作成（document_id・chunk_index 付与）。全工程を 1 トランザクションで実行。

4. 作業詳細

db.rs に migrate_025_to_030 を実装、init_schema 冒頭で呼び出し、cargo check で確認。ウォークスルーで移行ロジックを整理。

5. AI視点での結果

ユーザーは特別な操作なく v0.3.0 へアップデート可能になった。ベクトル ID を引き継ぐ設計で再インデックスも最小限に抑えられた。

2026-02-23: スキーマバージョン管理テーブルの追加

1. 作業実施の理由

今後のマイグレーションを確実かつ自動的に管理するため、DB 自体に現在のスキーマバージョンを保持する。

2. 指示（背景・観点・意図）

  • 指示: 「dbに今のテーブル構成がどのバージョンであるか格納するテーブルを1つ作ったらどうか」
  • 背景: これまではカラムの有無等で推測していたが、複雑化に備え明示管理が必要。
  • 意図: 「internal_metadata が存在しない ＝ 0.3.0 未満」という判断基準を導入し、既存マイグレーションを整理する。

3. 指示事項とその対応

  • 管理テーブル: key と value を持つ internal_metadata を追加。version: 0.3.0 を保存。
  • マイグレーション: migrate_025_to_030 でまず internal_metadata の有無を確認するステップを追加。DB 仕様書を更新。

4. 作業詳細

db.rs で internal_metadata の作成とバージョン書き込みを init_schema に追加。migrate_025_to_030 のリファクタ、仕様書の ER 図・説明の更新、cargo check で確認。

5. AI視点での結果

明示的なバージョン管理により、今後のマイグレーションが安全かつ論理的に行えるようになった。v0.2.5 以前にも「テーブル有無で判断」が有効な移行パスとなった。

2026-02-23: ヘッダ/フッタ再設計

目的

ヘッダ・フッタの見た目と配置を安定させ、「画面左端基準でのヘッダ」「フッタも左端基準」にすること。

指示

  • ヘッダは画面左端基準。フッタも左端基準。必要ならフッタも再配置。

作業要約（AI視点）

site-header.js と styles.css を編集し、ロゴを左端に安定配置。フッタの内側コンテナを左寄せに変更。ユーザーのスクリーンショットとフィードバックで微調整。

変更履歴（主要）

  • site-header.js: header-content ラッパーを導入し、ロゴをラッパー内に配置。
  • main-panel.js: 検索パネル内のブランドを削除、model-name-display を stats 内へ移動。
  • styles.css: --page-vertical-padding を 0 に。ヘッダを左端基準に。フッタの .footer-inner を左端基準に。パネルボーダーを削除してフラット化。

AIエージェントの所感

初期の「サイドバーに被らないようメインと揃える」方針がユーザー意図と食い違い混乱を招いた。次回からはレイアウト基準（左端基準 or サイドバー基準）を先に確認する運用に改善する。

2026-02-23: UIデザインの刷新とミニマリズムの徹底

1. 作業実施の理由

06_ui_design_spec.md の「High-Contrast Minimalism」を完全に反映し、グラスモーフィズムからプロフェッショナルなソリッドデザインへ進化させるため。

2. 指示（背景・観点・意図）

  • 背景: 「軽量・高速なローカル検索エンジン」へシフトし、UI も速度感と明瞭さを体現する必要があった。
  • 観点: 透明度・ブラーを排除し、漆黒基調のハイコントラスト、1px ボーダー、Outfit/Inter の使い分け。
  • 意図: ノイズを極限まで減らした HUD 的な使い心地を実現する。

3. 指摘事項とその対応

  • 指摘: main-panel.js で構文エラー。
    • 対応: ファイルを整理して上書きし、冗長・構文ミスを排除。
  • 指摘: 「宝くじ」が検索に引っかからない。
    • 対応: FTS5 (BM25) を導入し、キーワード一致を優先するハイブリッド検索に変更。
  • 指摘: MCP Activity ログが描画されない。
    • 対応: カスタムエレメントの生成タイミングを考慮し、SSE 受信ごとに描画ターゲットを動的に探索するよう修正。
  • 指摘: コピーボタンはダイアログに。
    • 対応: MCP 設定ダイアログ内にコピー機能を移設。
  • 指摘: フッタのバージョン表記は不要、コピーライトは DtmOjaji に。
    • 対応: フッタからバージョン削除、サイドバー INFO（TelosDB アコーディオン）にバージョンとコピーライトを集約。権利表記を DtmOjaji に統一。

4. 作業詳細

UI は High-Contrast Minimalism でレイアウト・コンポーネント・UX を刷新。バックエンドは FTS5/Trigram と BM25 を導入し、Vector と BM25 の Max を取るハイブリッド検索を search_text に実装。フッタ・メタ情報を整理し、バージョンとコピーライトをサイドバーに集約。

5. AI視点での結果

ビジュアルに留まらず検索アルゴリズムを強化し、BM25 により Elasticsearch 級のキーワード検索をローカルで実現。UI は「道具としての美しさ」と操作性が融合した。

2026-02-23: MCPツール応答形式の標準化と検索エラーの修正

1. 作業実施の理由

Qwen 等の LLM から MCP で search_text を実行した際に Tool call failed が発生する問題に対応するため。

2. 指示（背景・観点・意図）

  • 背景: 従来は検索結果の JSON 配列をそのまま content に返しており、MCP 仕様（{type: "text", text: "..."} 形式）に準拠していなかった。
  • 観点: 仕様不合だと LLM が「引数が間違っている」等の誤解をしやすい。
  • 意図: 全 MCP ツールの応答を標準化し、空クエリによる FTS5 エラーも防止する。

3. 指摘事項とその対応

  • 指摘: Qwen で「content パラメータは文字列である必要がある」等のエラー。
    • 対応: 検索結果を JSON 文字列として 1 つのテキストブロックにまとめ、MCP 準拠形式で返却。エラー時は isError: true を含む標準形式に統一。空 content の事前チェックを追加。

4. 作業詳細

mcp 内の全ツールの応答を MCP 仕様に適合させ、search_text は to_string_pretty でデコードし { type: "text", text: "..." } の配列で返却。旧 UI 用 lsa_search を search_text に統合・整理。

5. AI視点での結果

配列の直接返却がプロトコルレベルで拒絶されていた原因を解消し、多様な LLM から一貫して TelosDB 検索を利用可能にした。エラーハンドリングの標準化で不測時も LLM が状況を正しく伝えられるようになった。

2026-02-23: MCPモジュールのリファクタリングと機能分割

作業実施の理由

src/backend/src/mcp.rs が 1100 行超・ネスト 13 階層となり、コード品質基準（600 行以内・7 階層以内）を大幅に超過していたため。

指示内容

  • 背景: 保守性向上のため、巨大ファイルを機能単位で分割する。
  • 観点: MCP の責務を通信（axum）、データ型、バックグラウンド処理、個別ツールに分ける。
  • 意図: 各ファイルの役割を明確にし、機能追加・デバッグを容易にする。

構成案と実行

mcp.rs を src/backend/src/mcp/ 配下の複数モジュールに分割した。

  • types.rs: AppState、JSON-RPC 構造体。
  • handlers.rs: SSE・ステータス・doc_count・model_name 等の axum ハンドラ。
  • system.rs: LSA トレーニング・HNSW 同期等の基盤ロジック。
  • tools/mod.rs: ツールディスパッチャ。
  • tools/items.rs: add, update, delete, get。
  • tools/search.rs: search_text のハイブリッド検索。
  • tools/system.rs: lsa_retrain。
  • mod.rs: メッセージハンドラとサーバー起動。

指摘事項とその対応

  • 不一致: JapaneseTokenizer::new() の Result 処理漏れでビルドエラー → unwrap() を追加。
  • ハンドラ復旧: 誤削除した initialize ハンドラを mod.rs に復旧。
  • 通信ロジック: バインドを 127.0.0.1 に戻し、SSE セッション時は SSE ストリーム経由でレスポンスを返すよう復元。
  • CPU ブロッキング: LSA 学習・HNSW 同期を spawn_blocking に移譲し、起動時のレスポンス低下と初期化タイムアウトを防止。
  • フロント: 検索結果で similarity 未定義時に toFixed で落ちる問題を修正。MCP 準拠の JSON 文字列レスポンスのパースを改善。
  • プロトコル: JsonRpcResponse で null をシリアライズしないよう修正。session_id と sessionId のエイリアスをサポート。
  • 診断: デシリアライズ前に生のリクエストボディをログ出力。各サブモジュールのインポートを補完。

作業詳細

mcp/ ディレクトリ作成、機能ごとのファイル分割、mcp.rs 削除と lib.rs の参照を mcp/mod.rs に変更。cargo check、count_loc.cjs・nesting_depth.cjs で品質基準を確認。

AI視点での結果

  • 行数: 最大 348 行（items.rs）で 600 行基準をクリア。
  • ネスト: 複雑な match・ネストを解消し、各関数の複雑度が低下。
  • 保守性: 機能追加時に編集対象ファイルが明確になり、開発効率の向上が期待できる。
graph TD
    A[lib.rs] --> B[mcp/mod.rs]
    B --> C[mcp/handlers.rs]
    B --> D[mcp/tools/mod.rs]
    B --> E[mcp/system.rs]
    D --> F[mcp/tools/items.rs]
    D --> G[mcp/tools/search.rs]
    D --> H[mcp/tools/system.rs]
    F -.-> I[AppState / types.rs]
    G -.-> I
    H -.-> I