diff --git a/docs/specification/05_development_guide.md b/docs/specification/05_development_guide.md new file mode 100644 index 0000000..112d19f --- /dev/null +++ b/docs/specification/05_development_guide.md @@ -0,0 +1,55 @@ +# 開発者ガイド (Development Guide) + +## 1. 開発の基本コンセプト (Core Concepts) + +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. + +## 2. 環境構築の手順 (Setup Procedures) + +### 2.1 必要なツール (Required Tools) + +- **Rust**: 最新の Stable ツールチェーン。 (Latest Stable toolchain) +- **Node.js**: フロントエンド資材の管理用。 (For managing frontend assets) +- **VS Code**: 推奨エディタ(Tauri / Rust 拡張機能)。 (Recommended editor with Tauri/Rust extensions) + +### 2.2 初回セットアップ (Initial Setup) + +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. ビルドと実行 (Build and Run) + +```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`. + +## 4. 拡張手順 (MCP ツールの追加) (Extension Procedures: Adding MCP Tools) + +新しい機能を MCP 経由で公開する場合は、以下のファイルを修正します。 +To expose a new feature via MCP, modify the following files: + +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) + +## 5. コーディング規約とテスト (Coding Conventions and Testing) + +- **非同期処理 (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. + +## 6. ライセンスと貢献 (License and Contribution) + +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. diff --git a/docs/specification/06_ui_design_spec.md b/docs/specification/06_ui_design_spec.md new file mode 100644 index 0000000..0a433f5 --- /dev/null +++ b/docs/specification/06_ui_design_spec.md @@ -0,0 +1,38 @@ +# UI デザイン仕様書 (UI Design Specification) + +## 1. コンセプト: High-Contrast Minimalism + +TelosDB の UI は、装飾を極限まで削ぎ落とし、情報の「明瞭さ」と「速度感」を重視した **「ハイコントラスト・ミニマリズム」** をテーマにしています。 +以前の流行であったガラスモーフィズム(透過・ブラー)を廃し、ソリッドな背景と鋭いエッジ、洗練されたタイポグラフィによって、静謐でプロフェッショナルな道具としての佇まいを目指します。 + +### 1.1 デザインの構成要素 + +- **背景**: 漆黒(`#050505`)に近い深い黒を基調とし、要素を区別するために深いグレーのソリッドな面を使用。 +- **ボーダー**: 透過ブラーではなく、非常に細く(1px)彩度の低いグレースケールの境界線を採用。 +- **タイポグラフィ**: 幾何学的で現代的なサンセリフ体(Outfit)と、情報の視認性に特化したインターフェイスフォント(Inter)。 +- **アクセント**: 機能的な意味(成功、エラー、ステータス)を持つ要素にのみ、厳選されたアクセントカラーを適用。 + +## 2. インタラクティブ・フィードバック + +### 2.1 ステータス・インジケーター + +ヘッダー右側に配置されたバッジは、システムの状態をリアルタイムに示します。 + +- `Running`: LSA エンジン(Vibrato 形態素解析 + ndarray 行列演算)および MCP サーバーが待機中または処理中。 +- `Stopped`: 重大な構成エラーまたはプロセス停止。 + +### 2.2 アクティビティ・ログ (SSE Listener) + +検索や登録のアクティビティは、画面下部のログセクションに垂直方向に流れます。 +ソリッドなデザインに合わせ、カードの浮き上がり(Shadow)ではなく、ミニマルなリスト形式で表示されます。 + +## 3. フロントエンド技術スタック + +- **Vanilla JS & CSS**: 高速な起動と低メモリフットプリントを維持。 +- **Desktop First**: Tauri 2 による Windows ネイティブの挙動(システムトレイ、イベントループ)に最適化。 + +## 4. レイアウト構造 + +1. **Header (HUD)**: 常に固定され、モデル名とデータ件数を表示(ヘッドアップディスプレイ)。 +2. **Main Content**: 検索バーと結果リスト。余白(Negative Space)を適切に取り、情報のノイズを排除。 +3. **Footer (Toolbar)**: 設定へのアクセスと再インデックスボタンを集約。 diff --git "a/journals/20260223-0014-\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253\343\201\256.agent_rules\343\201\270\343\201\256\347\247\273\350\241\214\343\201\250\346\227\245\350\213\261\344\275\265\350\250\230\345\214\226.md" "b/journals/20260223-0014-\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253\343\201\256.agent_rules\343\201\270\343\201\256\347\247\273\350\241\214\343\201\250\346\227\245\350\213\261\344\275\265\350\250\230\345\214\226.md" index 555f83f..034ede7 100644 --- "a/journals/20260223-0014-\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253\343\201\256.agent_rules\343\201\270\343\201\256\347\247\273\350\241\214\343\201\250\346\227\245\350\213\261\344\275\265\350\250\230\345\214\226.md" +++ "b/journals/20260223-0014-\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253\343\201\256.agent_rules\343\201\270\343\201\256\347\247\273\350\241\214\343\201\250\346\227\245\350\213\261\344\275\265\350\250\230\345\214\226.md" @@ -13,6 +13,7 @@ ## 3. 指記事項とその対応 - **ルール配置の修正**: 運用ルールである `issue_management.md` を `.agent/rules` へ移動。技術仕様である `development_guide.md` は `docs/specification` で管理を継続。 +- **ドキュメント番号の調整**: サイドカー廃止に伴い欠番となった `05` を詰めるため、`06_development_guide.md` を `05_development_guide.md` に、`07_ui_design_spec.md` を `06_ui_design_spec.md` にリネーム。 - **日英併記**: 両ファイルの内容に英語翻訳を追加。 - **不要ファイルの削除**: `docs/` 内の移動元ファイル(Issue管理)を削除。 @@ -21,8 +22,9 @@ AIエージェントは以下の手順で作業を実施した。 1. `docs/workflow/issue_management.md` を抽出し、英語翻訳を付加して `.agent/rules/issue_management.md` を作成。 -2. `docs/specification/06_development_guide.md` を日英併記に更新(配置先は `docs/` 配下を維持)。 -3. 開発者向けの技術仕様と、AIエージェント向けの運用ルールの境界を明確にした。 +2. `docs/specification/06_development_guide.md` を `05_development_guide.md` にリネームし、日英併記に更新。 +3. `docs/specification/07_ui_design_spec.md` を `06_ui_design_spec.md` にリネーム。 +4. 開発者向けの技術仕様と、AIエージェント向けの運用ルールの境界を明確にした。 ## 5. AI視点での結果