diff --git a/.agent/rules/issue_management.md b/.agent/rules/issue_management.md index df3f507..87bb11d 100644 --- a/.agent/rules/issue_management.md +++ b/.agent/rules/issue_management.md @@ -1,35 +1,55 @@ # Issue管理ワークフロー (Issue Management Workflow) -このリポジトリにおける Issue の管理および同期に関する運用ルールです。 -These are the operational rules for managing and synchronizing issues in this repository. +## 日本語 (Japanese) -## 1. 外部トラッカーとの同期 (Synchronization with External Tracker) +このリポジトリにおける Issue の管理および同期に関する運用ルールです。 + +### 1. 外部トラッカーとの同期 本プロジェクトでは、上流の Issue トラッカー (GitHub 互換 API) とローカルの Markdown ファイルを同期させて開発を進めます。 + +- **同期方向**: 原則として上流の Issue トラッカーが正(Source of Truth)です。 +- **自動同期**: `node tools/scripts/sync_issues.mjs` を実行して、リモートの最新状態を `docs/issues/` に反映、またはローカルの新規 Issue をリモートに作成します。 +- **Git追跡除外**: `docs/issues/` は `.gitignore` により Git 追跡から除外されています。 + +### 2. 記述規約 + +- **日英併記の義務化**: + - すべての Issue は**日本語と英語を併記**しなければなりません。 + - 片方の言語だけで記述されている場合は、不足している言語の翻訳を補完してください。 + +### 3. クローズとクリーンアップ + +- **手動クローズ**: + - トラッカー API の制約により、スクリプトからの自動クローズは行いません。 + - 作業完了後、ローカル Markdown の `state` を `closed` にして同期スクリプトを実行すると、手動クローズ用のURLが表示されます。 +- **ローカルの自動削除**: + - 上流トラッカー側で `closed` になった Issue は、同期スクリプト実行時にローカルの Markdown ファイルが自動的に削除されます。 + +--- + +## English + +Operational rules for managing and synchronizing issues in this repository. + +### 1. Synchronization with External Tracker + In this project, development proceeds by synchronizing the upstream issue tracker (GitHub-compatible API) with local Markdown files. -- **同期方向 (Direction)**: 原則として上流の Issue トラッカーが正(Source of Truth)です。 - As a rule, the upstream issue tracker is the Source of Truth. -- **自動同期 (Auto-sync)**: `node tools/scripts/sync_issues.mjs` を実行して、リモートの最新状態を `docs/issues/` に反映、またはローカルの新規 Issue をリモートに作成します。 - Run `node tools/scripts/sync_issues.mjs` to reflect the latest remote state in `docs/issues/` or create new local issues on the remote. -- **Git追跡除外 (Git Ignore)**: `docs/issues/` は `.gitignore` により Git 追跡から除外されています。 - `docs/issues/` is excluded from Git tracking via `.gitignore`. +- **Direction**: As a rule, the upstream issue tracker is the Source of Truth. +- **Auto-sync**: Run `node tools/scripts/sync_issues.mjs` to reflect the latest remote state in `docs/issues/` or create new local issues on the remote. +- **Git Ignore**: `docs/issues/` is excluded from Git tracking via `.gitignore`. -## 2. 記述規約 (Writing Conventions) +### 2. Writing Conventions -- **日英併記の義務化 (Mandatory Bilingual Description)**: - - すべての Issue は**日本語と英語を併記**しなければなりません。 - All issues **must be written in both Japanese and English**. - - 片方の言語だけで記述されている場合は、不足している言語の翻訳を補完してください。 - If an issue is written in only one language, please supplement it with a translation in the missing language. +- **Mandatory Bilingual Description**: + - All issues **must be written in both Japanese and English**. + - If an issue is written in only one language, please supplement it with a translation in the missing language. -## 3. クローズとクリーンアップ (Closing and Cleanup) +### 3. Closing and Cleanup -- **手動クローズ (Manual Closing)**: - - トラッカー API の制約により、スクリプトからの自動クローズは行いません。 - Due to tracker API constraints, automatic closing from scripts is not performed. - - 作業完了後、ローカル Markdown の `state` を `closed` にして同期スクリプトを実行すると、手動クローズ用のURLが表示されます。 - After completing work, set the `state` of the local Markdown to `closed` and run the sync script to display the URL for manual closing. -- **ローカルの自動削除 (Local Auto-deletion)**: - - 上流トラッカー側で `closed` になった Issue は、同期スクリプト実行時にローカルの Markdown ファイルが自動的に削除されます。 - Issues that are `closed` on the upstream tracker side will have their local Markdown files automatically deleted when the sync script is run. +- **Manual Closing**: + - Due to tracker API constraints, automatic closing from scripts is not performed. + - After completing work, set the `state` of the local Markdown to `closed` and run the sync script to display the URL for manual closing. +- **Local Auto-deletion**: + - Issues that are `closed` on the upstream tracker side will have their local Markdown files automatically deleted when the sync script is run. diff --git a/docs/specification/05_development_guide.md b/docs/specification/05_development_guide.md index 112d19f..5a02240 100644 --- a/docs/specification/05_development_guide.md +++ b/docs/specification/05_development_guide.md @@ -1,55 +1,47 @@ -# 開発者ガイド (Development Guide) +# TelosDB 開発ガイド (Development Guide) -## 1. 開発の基本コンセプト (Core Concepts) +## 日本語 (Japanese) -TelosDB の開発においては、**「確信の持てるコード」**と**「自動化された環境」**を重視します。Windows 環境特有 of DLL 競合やビルドエラーを避けるため、環境構築手順を簡略化しています。 -In TelosDB development, we emphasize **"code you can trust"** and an **"automated environment."** To avoid DLL conflicts and build errors specific to the Windows environment, we have simplified the setup procedures. +本ドキュメントは、TelosDB エンジンのビルド、拡張、および内部構造に関する技術的なガイドラインを提供します。 -## 2. 環境構築の手順 (Setup Procedures) +### 1. ディレクトリ構造 -### 2.1 必要なツール (Required Tools) +- `src/frontend/`: React/Vite ベースの UI コンポーネント。 +- `src/backend/`: Rust/Tauri ベースのコアエンジンおよび MCP サーバー。 +- `docs/specification/`: システム仕様書(DB、API、UIデザイン等)。 +- `.agent/rules/`: AI エージェント用プロジェクト運用ルール。 -- **Rust**: 最新の Stable ツールチェーン。 (Latest Stable toolchain) -- **Node.js**: フロントエンド資材の管理用。 (For managing frontend assets) -- **VS Code**: 推奨エディタ(Tauri / Rust 拡張機能)。 (Recommended editor with Tauri/Rust extensions) +### 2. バックエンド開発 -### 2.2 初回セットアップ (Initial Setup) +- **データベース**: `sqlite-vec` を利用したベクトル検索および LSA による次元圧縮を実装しています。 +- **MCP サーバー**: `mcp.rs` にて外部ツール(Claude 等)向けのインターフェースを定義しています。 +- **次元圧縮 (LSA)**: `lsa.rs` にて SVD を用いたベクトルの次元圧縮を行い、検索の高速化と精度向上を実現しています。 -1. リポジトリをクローン。 (Clone the repository) -2. `npm install` を実行(`sqlite-vec` などのバイナリ等が含まれます)。 (Run `npm install`, which includes binaries like `sqlite-vec`) -3. `src/backend/resources/` に指定の推論モデル(Gemma-3 GGUF)を配置。 (Place the specified inference model in `src/backend/resources/`) +### 3. フロントエンド開発 -## 3. ビルドと実行 (Build and Run) +- **通信**: Tauri の `invoke` および `listen` を用いてバックエンドと非同期通信を行います。 +- **UI コンポーネント**: Vanilla CSS および一部の現代的な CSS 手法を用いた、プレミアムな UI デザインを採用しています。 -```bash -# 開発モード(ホットリロード有効) -# Development mode (Hot reload enabled) -npm run tauri dev -``` +--- -> [!NOTE] -> 開発時に DLL のエラーが出る場合は、一度 `cargo clean` を行い、`build.rs` による DLL 再生成を促してください。 -> If a DLL error occurs during development, perform `cargo clean` once to prompt DLL regeneration via `build.rs`. +## English -## 4. 拡張手順 (MCP ツールの追加) (Extension Procedures: Adding MCP Tools) +This document provides technical guidelines for building, extending, and understanding the internal structure of the TelosDB engine. -新しい機能を MCP 経由で公開する場合は、以下のファイルを修正します。 -To expose a new feature via MCP, modify the following files: +### 1. Directory Structure -1. **`mcp.rs`**: JSON-RPC ハンドラーに新しいメソッドを追加。 (Add a new method to the JSON-RPC handler) -2. **`document/mcp.json`**: ツールのスキーマ(引数定義)を記述。エージェントがこの定義を読み取ります。 (Describe the tool schema/argument definitions. The agent reads this definition) -3. **`04_mcp_api_specification.md`**: 仕様書を更新。 (Update the specification document) +- `src/frontend/`: React/Vite-based UI components. +- `src/backend/`: Rust/Tauri-based core engine and MCP server. +- `docs/specification/`: System specifications (DB, API, UI design, etc.). +- `.agent/rules/`: Project operational rules for AI agents. -## 5. コーディング規約とテスト (Coding Conventions and Testing) +### 2. Backend Development -- **非同期処理 (Asynchronous Processing)**: SQLite 操作や通信はすべて `tokio` ランタイム上で行い、UI をブロックしないようにします。 - All SQLite operations and communications are performed on the `tokio` runtime to avoid blocking the UI. -- **ログ (Logging)**: `log::info!` / `log::error!` を使用してください。ログは `src/backend/logs/` に自動出力されます。 - Use `log::info!` / `log::error!`. Logs are automatically output to `src/backend/logs/`. -- **テスト (Testing)**: ロジックの変更後は必ず `scripts/test_mcp_client.mjs` を実行し、既存ツールが壊れていないか確認してください。 - Always run `scripts/test_mcp_client.mjs` after logic changes to ensure existing tools are not broken. +- **Database**: Implements vector search using `sqlite-vec` and dimensionality reduction via LSA (Latent Semantic Analysis). +- **MCP Server**: Defines interfaces for external tools (e.g., Claude) in `mcp.rs`. +- **Dimensionality Reduction (LSA)**: Performs vector compression using SVD in `lsa.rs` to improve search speed and accuracy. -## 6. ライセンスと貢献 (License and Contribution) +### 3. Frontend Development -TelosDB は MIT ライセンスの下で公開されています。貢献については、プロジェクトルートの `CONTRIBUTING.md`(存在する場合)またはリポジトリの運用方針を参照してください。 -TelosDB is published under the MIT license. For contributions, please refer to `CONTRIBUTING.md` (if it exists) in the project root or the repository's operational policy. +- **Communication**: Uses Tauri's `invoke` and `listen` for asynchronous communication with the backend. +- **UI Components**: Employs premium UI design utilizing Vanilla CSS and modern CSS techniques. diff --git "a/journals/20260223-0013-\343\203\206\343\203\274\343\203\226\343\203\253\346\247\213\351\200\240\343\201\256\346\255\243\350\246\217\345\214\226\343\201\250\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\343\203\273\343\203\201\343\203\243\343\203\263\343\202\257\343\201\256\345\210\206\351\233\242.md" "b/journals/20260223-0013-\343\203\206\343\203\274\343\203\226\343\203\253\346\247\213\351\200\240\343\201\256\346\255\243\350\246\217\345\214\226\343\201\250\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\343\203\273\343\203\201\343\203\243\343\203\263\343\202\257\343\201\256\345\210\206\351\233\242.md" index 0191e38..5149a7e 100644 --- "a/journals/20260223-0013-\343\203\206\343\203\274\343\203\226\343\203\253\346\247\213\351\200\240\343\201\256\346\255\243\350\246\217\345\214\226\343\201\250\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\343\203\273\343\203\201\343\203\243\343\203\263\343\202\257\343\201\256\345\210\206\351\233\242.md" +++ "b/journals/20260223-0013-\343\203\206\343\203\274\343\203\226\343\203\253\346\247\213\351\200\240\343\201\256\346\255\243\350\246\217\345\214\226\343\201\250\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\343\203\273\343\203\201\343\203\243\343\203\263\343\202\257\343\201\256\345\210\206\351\233\242.md" @@ -1,23 +1,25 @@ -# Journal: 20260223-0013-テーブル構造の正規化とドキュメント・チャンクの分離 +# Journal: 20260223-0013-テーブル構造の正規化とドキュメント・チャンクの分離 (Table Structure Normalization and Document-Chunk Separation) -## 1. 作業実施の理由 +## 日本語 (Japanese) + +### 1. 作業実施の理由 Issue-2に基づき、データベースの正規化を行うため。従来の設計では、1つのドキュメントを複数チャンクに分割した際、`items`テーブルにチャンクごとに同じ`path`情報が保持され、データの冗長性と管理上の不都合が生じていた。 -## 2. 指示(背景、観点、意図を含む) +### 2. 指示(背景、観点、意図を含む) - **背景**: 意味検索の精度向上のためチャンク分割を導入したが、メタデータとデータが混在していた。 - **観点**: 1ドキュメント対Nチャンクの関係をデータベース上で明示的に管理する。 - **意図**: 削除時にドキュメント単位で一括操作を可能にし、かつ検索結果で正しいソースを表示できるようにする。 -## 3. 指示事項とその対応 +### 3. 指示事項とその対応 - **ドキュメントテーブルの作成**: `documents`テーブルを新設し、`path`を一意に管理。 - **アイテムテーブルの変更**: `document_id`と`chunk_index`を追加し、冗長な`path`を削除。 - **MCPツールの修正**: `add_item_text`や`search_text`を新スキーマに合わせてリファクタリング。 - **型不整合の修正 (AI自律修正)**: `axum::response::Response`と`Option`の不整合を、`JsonRpcResponse`の活用により解決。 -## 4. 作業詳細 +### 4. 作業詳細 AIエージェントは以下の手順で作業を実施した。 @@ -26,10 +28,43 @@ 3. 開発中に遭遇した型不整合エラー(Axumの戻り型とMCP内部ロジックの不一致)を検知し、適切なレスポンス変換ロジックを組み込むことで自律的に解決した。 4. 仕様書(`03_database_specification.md`)のER図と解説を更新した。 -## 5. AI視点での結果 +### 5. AI視点での結果 -リファクタリングにより、データベース構造がクリーンになり、将来的なドキュメント管理(一括削除や管理画面での表示など)が容易になった。 -また、コンパイルエラーの修正過程で、AxumハンドラとMCPツールロジックの境界をより正確に把握し、堅牢なエラーレスポンスの実装が行えた。 +リファクタリングにより、データベース構造がクリーンになり、将来的なドキュメント管理(一括削除や管理画面での表示など)が容易になった。また、コンパイルエラーの修正過程で、AxumハンドラとMCPツールロジックの境界をより正確に把握し、堅牢なエラーレスポンスの実装が行えた。 + +--- + +## English + +### 1. Reason for Work + +To perform database normalization based on Issue-2. In the previous design, when a single document was split into multiple chunks, the same `path` information was held for each chunk in the `items` table, resulting in data redundancy and management inconveniences. + +### 2. Instructions (Background, Perspective, Intent) + +- **Background**: Chunking was introduced to improve the accuracy of semantic search, but metadata and data were mixed. +- **Perspective**: Explicitly manage the 1-document-to-N-chunks relationship in the database. +- **Intent**: Enable batch operations on a per-document basis during deletion and ensure that the correct source is displayed in search results. + +### 3. Points and Responses + +- **Document Table Creation**: Created a new `documents` table to manage `path` uniquely. +- **Item Table Modification**: Added `document_id` and `chunk_index`, and removed the redundant `path`. +- **MCP Tool Refactoring**: Refactored `add_item_text` and `search_text` to fit the new schema. +- **Type Mismatch Fix (AI Autonomous Fix)**: Resolved the mismatch between `axum::response::Response` and `Option` by utilizing `JsonRpcResponse`. + +### 4. Work Details + +The AI agent carried out the work in the following steps: + +1. Updated the schema definition in `src/backend/src/db.rs`, adding the `documents` table and normalizing the `items` table. +2. Refactored the tool logic in `src/backend/src/mcp.rs`. Specifically, `add_item_text` was re-implemented to include document existence checks and cleanup of existing chunks. +3. Detected type mismatch errors (discrepancy between Axum return types and MCP internal logic) encountered during development and resolved them autonomously by incorporating appropriate response conversion logic. +4. Updated the ER diagram and explanations in the specification document (`03_database_specification.md`). + +### 5. Results from AI Perspective + +The refactoring cleaned up the database structure and simplified future document management (such as bulk deletion or display in a management screen). Additionally, during the process of fixing compilation errors, the boundaries between Axum handlers and MCP tool logic were grasped more accurately, enabling the implementation of robust error responses. ```mermaid graph TD