musubix 1.4.4 → 1.7.0

package/docs/USER-GUIDE.ja.md

@@ -17,10 +17,16 @@
 11. [C4コード生成](#c4コード生成)
 12. [シンボリック推論](#シンボリック推論) *(v1.2.0)*
 13. [正誤性検証](#正誤性検証) *(v1.4.1)*
-14. [MCPサーバー連携](#mcpサーバー連携)
-15. [YATA知識グラフ](#yata知識グラフ)
-15. [ベストプラクティス](#ベストプラクティス)
-16. [トラブルシューティング](#トラブルシューティング)
+14. [高度な推論](#高度な推論) *(v1.4.5)*
+15. [対話的REPLモード](#対話的replモード) *(v1.5.0)*
+16. [YATA Local](#yata-local) *(v1.6.3)*
+17. [YATA Global](#yata-global) *(v1.6.3)*
+18. [KGPR - Knowledge Graph Pull Request](#kgpr---knowledge-graph-pull-request) *(v1.6.4)*
+19. [YATA プラットフォーム拡張](#yata-プラットフォーム拡張) *(v1.7.0)*
+20. [MCPサーバー連携](#mcpサーバー連携)
+21. [YATA知識グラフ](#yata知識グラフ)
+22. [ベストプラクティス](#ベストプラクティス)
+23. [トラブルシューティング](#トラブルシューティング)
 
 ---
 
@@ -840,6 +846,711 @@ const semanticDuplicates = validator.findSemanticDuplicates(allTriples);
 
 ---
 
+## 高度な推論
+
+*(v1.4.5 新機能)*
+
+### 概要
+
+高度な推論は、知識グラフにOWL 2 RL推論とDatalog評価機能を提供します。暗黙的な事実の実体化、ルールベースの推論、人間が理解しやすい説明の生成をサポートします。
+
+### 主要コンポーネント
+
+| コンポーネント | 説明 |
+|--------------|------|
+| `OWL2RLReasoner` | 20以上のビルトインルールを持つOWL 2 RL推論エンジン |
+| `DatalogEngine` | 階層化評価対応のDatalogエンジン |
+| `InferenceExplainer` | 自然言語での説明生成 |
+| `ProgressReporter` | リアルタイム推論進捗追跡 |
+
+### OWL 2 RL 推論
+
+```typescript
+import { OWL2RLReasoner } from '@nahisaho/musubix-ontology-mcp';
+
+const reasoner = new OWL2RLReasoner({
+  maxIterations: 100,
+  enablePropertyChains: true,
+  enableInverseProperties: true
+});
+
+// ストアに対して推論を実行
+const result = await reasoner.reason(store, {
+  onProgress: (progress) => {
+    console.log(`反復 ${progress.iteration}: ${progress.newTriples} 新規トリプル`);
+  }
+});
+
+console.log(`${result.inferredCount} 個の新しい事実を推論`);
+console.log(`適用ルール: ${result.rulesApplied.join(', ')}`);
+```
+
+### OWL 2 RL ルール
+
+| ルールID | 名称 | 説明 |
+|---------|------|------|
+| `prp-dom` | Property Domain | プロパティのドメインから型を推論 |
+| `prp-rng` | Property Range | プロパティのレンジから型を推論 |
+| `prp-inv1/2` | Inverse Properties | 逆関係を推論 |
+| `prp-trp` | Transitive Properties | 推移的プロパティを連鎖 |
+| `prp-symp` | Symmetric Properties | 対称関係を推論 |
+| `cax-sco` | SubClassOf | クラスメンバーシップを伝播 |
+| `scm-spo` | SubPropertyOf | プロパティの包摂関係 |
+| `eq-rep-s/p/o` | SameAs Replacement | 同一個体の置換 |
+
+### Datalog 評価
+
+```typescript
+import { DatalogEngine } from '@nahisaho/musubix-ontology-mcp';
+
+const engine = new DatalogEngine();
+
+// ルールを定義
+const rules = [
+  {
+    head: { predicate: 'ancestor', args: ['?x', '?y'] },
+    body: [
+      { predicate: 'parent', args: ['?x', '?y'] }
+    ]
+  },
+  {
+    head: { predicate: 'ancestor', args: ['?x', '?z'] },
+    body: [
+      { predicate: 'parent', args: ['?x', '?y'] },
+      { predicate: 'ancestor', args: ['?y', '?z'] }
+    ]
+  }
+];
+
+// ルールを評価
+const result = await engine.evaluate(rules, facts, {
+  onProgress: (progress) => {
+    console.log(`階層 ${progress.stratum}: ${progress.rule} を評価中`);
+  }
+});
+
+console.log(`${result.derivedFacts.length} 個の新しい事実を導出`);
+```
+
+### 推論説明
+
+```typescript
+import { InferenceExplainer, ExplanationFormat } from '@nahisaho/musubix-ontology-mcp';
+
+const explainer = new InferenceExplainer(reasoner.getProvenanceLog());
+
+// 特定のトリプルの説明を取得
+const explanation = explainer.explain(
+  'http://example.org/Animal',
+  'rdf:type',
+  'owl:Class',
+  ExplanationFormat.TEXT
+);
+
+console.log(explanation);
+// 出力: "Animal は owl:Class として宣言されているため Class です（ルール cax-sco）"
+
+// HTML形式の説明を生成
+const htmlExplanation = explainer.explain(
+  subject, predicate, object,
+  ExplanationFormat.HTML
+);
+```
+
+### 進捗レポート
+
+```typescript
+import { createProgressReporter } from '@nahisaho/musubix-ontology-mcp';
+
+const reporter = createProgressReporter({
+  onProgress: (info) => {
+    console.log(`フェーズ: ${info.phase}`);
+    console.log(`反復: ${info.iteration}/${info.maxIterations}`);
+    console.log(`トリプル数: ${info.totalTriples}`);
+    console.log(`新規推論: ${info.newInferences}`);
+  },
+  throttleMs: 500  // 500ms間隔でレポート
+});
+
+await reasoner.reason(store, { progressReporter: reporter });
+```
+
+---
+
+## 対話的REPLモード
+
+*(v1.5.0 新規、v1.6.0 強化)*
+
+MUSUBIXは、リアルタイムでコマンドを実行・探索できる対話的REPLシェルを提供します。
+
+### REPLの起動
+
+```bash
+# 対話的REPLを起動
+musubix repl
+
+# カスタム履歴ファイルを指定
+musubix repl --history ~/.musubix-repl-history
+
+# カラー表示なし
+musubix repl --no-color
+```
+
+### REPL機能
+
+| 機能 | 説明 |
+|------|------|
+| コマンド補完 | TABキーでコマンド・オプションを補完 |
+| 履歴ナビゲーション | 上下矢印、履歴検索 |
+| セッション変数 | `$name=value` で設定、`$name` で参照 |
+| 出力フォーマット | JSON、YAML、テーブル自動整形 |
+| CLI統合 | CLIコマンドをそのまま実行可能 |
+
+### 基本的な使い方
+
+```bash
+musubix> help                          # すべてのコマンドを表示
+musubix> help requirements             # コマンド詳細を表示
+musubix> requirements analyze input.md # CLIコマンドを実行
+musubix> $project=my-app               # セッション変数を設定
+musubix> design generate $project      # 変数をコマンドで使用
+musubix> history                       # コマンド履歴を表示
+musubix> exit                          # REPLを終了
+```
+
+### セッション変数
+
+```bash
+# 変数の設定
+musubix> $req=REQ-001
+musubix> $file=./docs/requirements.md
+
+# コマンドで使用
+musubix> requirements validate $file
+musubix> trace impact $req
+
+# 特殊変数: $_ は前回の実行結果を保持
+musubix> requirements analyze input.md
+musubix> $_                           # 前回の結果にアクセス
+```
+
+### 出力フォーマット
+
+```bash
+# 自動検出（デフォルト）
+musubix> learn status
+
+# JSON出力を強制
+musubix> set format json
+musubix> learn patterns
+
+# YAML出力を強制
+musubix> set format yaml
+
+# テーブル出力を強制
+musubix> set format table
+```
+
+### 履歴管理
+
+```bash
+# 最近のコマンドを表示
+musubix> history
+
+# 履歴を検索（Ctrl+Rスタイル）
+musubix> history search requirements
+
+# 履歴をクリア
+musubix> history clear
+```
+
+### REPLコンポーネント
+
+| コンポーネント | 役割 |
+|---------------|------|
+| `ReplEngine` | REPLメインコントローラー |
+| `CommandCompleter` | TAB補完プロバイダー |
+| `HistoryManager` | コマンド履歴の永続化 |
+| `SessionState` | 変数ストレージ |
+| `OutputFormatter` | JSON/YAML/テーブル出力 |
+| `PromptRenderer` | 動的プロンプト表示 |
+
+---
+
+## YATA Local
+
+*(v1.6.3 新規)*
+
+YATA Localは、高性能なSQLiteベースのローカル知識グラフです。推論機能を内蔵し、シングルユーザー・オフライン環境でデータ主権と速度が重要な場合に最適です。
+
+### 機能
+
+| 機能 | 説明 |
+|------|------|
+| **SQLiteストレージ** | WALモードで並行読み取り、シングルライター |
+| **全文検索** | FTS5ベースのトリプル検索 |
+| **グラフ探索** | BFS/DFSアルゴリズム、深度制御 |
+| **推論エンジン** | 4つのOWL-liteルール（推移性、対称性、逆関係、ドメイン/レンジ） |
+| **制約** | 4つの検証ルール（カーディナリティ、排他、一意性、必須） |
+| **ACIDトランザクション** | 完全なトランザクションサポート |
+
+### インストール
+
+```bash
+npm install @nahisaho/yata-local
+```
+
+### クイックスタート
+
+```typescript
+import { YataLocal } from '@nahisaho/yata-local';
+
+// デフォルト設定で初期化
+const yata = new YataLocal('./knowledge.db');
+await yata.initialize();
+
+// トリプルを追加
+await yata.addTriple({
+  subject: 'Person:john',
+  predicate: 'hasParent',
+  object: 'Person:mary'
+});
+
+// トリプルをクエリ
+const results = await yata.query({
+  subject: 'Person:john',
+  predicate: 'hasParent'
+});
+
+// 全文検索
+const searchResults = await yata.search('john parent');
+
+// グラフ探索（BFS）
+const ancestors = await yata.traverse('Person:john', 'hasParent', {
+  direction: 'outgoing',
+  maxDepth: 5,
+  algorithm: 'bfs'
+});
+
+// クリーンアップ
+await yata.close();
+```
+
+### 推論エンジン
+
+YATA Localは4つのOWL-lite推論ルールをサポートします：
+
+| ルール | 説明 | 例 |
+|--------|------|-----|
+| **推移性** | A→BかつB→CならA→C | hasAncestorは推移的 |
+| **対称性** | A→BならB→A | friendOfは対称的 |
+| **逆関係** | A→B（P経由）ならB→A（P⁻¹経由） | hasChild ↔ hasParent |
+| **ドメイン/レンジ** | 述語から型を推論 | hasAgeはPersonを示唆 |
+
+```typescript
+// 推論を実行
+const inferred = await yata.infer();
+console.log(`${inferred.length}個の新しいトリプルを推論`);
+```
+
+### 制約
+
+```typescript
+// 制約を定義
+await yata.addConstraint({
+  type: 'cardinality',
+  predicate: 'hasSpouse',
+  max: 1
+});
+
+// 検証
+const violations = await yata.validate();
+if (violations.length > 0) {
+  console.error('制約違反:', violations);
+}
+```
+
+### 設定オプション
+
+```typescript
+const yata = new YataLocal('./knowledge.db', {
+  // WALモードで並行性向上（デフォルト: true）
+  walMode: true,
+  
+  // FTS5検索を有効化（デフォルト: true）
+  enableSearch: true,
+  
+  // 書き込み時に自動推論（デフォルト: false）
+  autoInfer: false,
+  
+  // ジャーナルモード（デフォルト: 'wal'）
+  journalMode: 'wal'
+});
+```
+
+---
+
+## YATA Global
+
+*(v1.6.3 新規)*
+
+YATA Globalは、チームコラボレーション向けの分散型知識グラフプラットフォームです。共有知識グラフへのREST APIアクセスと、オフラインサポート・インテリジェントな同期機能を提供します。
+
+### 機能
+
+| 機能 | 説明 |
+|------|------|
+| **REST API** | HTTP経由の完全なCRUD操作 |
+| **オフラインキャッシュ** | SQLiteベースのローカルキャッシュ |
+| **同期エンジン** | Push/Pullと競合解決 |
+| **競合解決** | Last-write-winsまたはカスタム戦略 |
+| **認証** | APIキーベースの認証 |
+| **バッチ操作** | 一括トリプル操作 |
+
+### インストール
+
+```bash
+npm install @nahisaho/yata-global
+```
+
+### クイックスタート
+
+```typescript
+import { YataGlobal } from '@nahisaho/yata-global';
+
+// クライアントを初期化
+const yata = new YataGlobal({
+  endpoint: 'https://yata.example.com/api',
+  apiKey: 'your-api-key',
+  graphId: 'project-knowledge'
+});
+
+await yata.initialize();
+
+// トリプルを追加（バッチ）
+await yata.addTriples([
+  { subject: 'Task:001', predicate: 'assignedTo', object: 'User:alice' },
+  { subject: 'Task:001', predicate: 'status', object: 'in-progress' }
+]);
+
+// フィルタ付きクエリ
+const tasks = await yata.query({
+  predicate: 'assignedTo',
+  object: 'User:alice'
+});
+
+// クリーンアップ
+await yata.close();
+```
+
+### オフラインサポート
+
+YATA Globalは自動同期によるオフラインファースト操作をサポートします：
+
+```typescript
+const yata = new YataGlobal({
+  endpoint: 'https://yata.example.com/api',
+  apiKey: 'your-api-key',
+  graphId: 'project-knowledge',
+  
+  // オフライン設定
+  offlineMode: true,
+  cachePath: './yata-cache.db',
+  syncInterval: 60000  // 60秒ごとに自動同期
+});
+
+// オフラインでも動作 - ローカルにキャッシュ
+await yata.addTriple({
+  subject: 'Note:001',
+  predicate: 'content',
+  object: '重要な会議メモ'
+});
+
+// オンライン時に手動同期
+await yata.sync();
+```
+
+### 競合解決
+
+```typescript
+const yata = new YataGlobal({
+  // ... その他のオプション
+  
+  conflictStrategy: 'last-write-wins',  // デフォルト
+  // または: 'server-wins', 'client-wins', 'manual'
+  
+  onConflict: async (local, remote) => {
+    // カスタム解決ロジック
+    console.log('競合を検出:', local, remote);
+    return remote;  // リモート版を優先
+  }
+});
+```
+
+### 同期ステータス
+
+```typescript
+// 同期ステータスを確認
+const status = await yata.getSyncStatus();
+console.log(`保留中の変更: ${status.pendingPush}`);
+console.log(`最終同期: ${status.lastSyncAt}`);
+
+// 完全同期を強制
+await yata.sync({ force: true });
+```
+
+### YATA Local vs YATA Global の選択
+
+| ユースケース | 推奨 |
+|-------------|------|
+| 個人用ナレッジベース | YATA Local |
+| シングルユーザーアプリ | YATA Local |
+| プライバシー重視のデータ | YATA Local |
+| チームコラボレーション | YATA Global |
+| クロスデバイスアクセス | YATA Global |
+| 共有プロジェクト知識 | YATA Global |
+| 同期付きオフラインファースト | YATA Global |
+
+---
+
+## KGPR - Knowledge Graph Pull Request
+
+*(v1.6.4)*
+
+KGPR（Knowledge Graph Pull Request）は、GitHub PRと同様のワークフローで、YATA LocalからYATA Globalへ安全に知識グラフを共有する機能です。
+
+### ワークフロー
+
+```
+┌─────────────┐     ┌──────────────┐     ┌───────────────┐
+│ YATA Local  │ ──► │ KGPR (Draft) │ ──► │ YATA Global   │
+│ (ローカルKG) │     │ (差分抽出)    │     │ (レビュー・マージ) │
+└─────────────┘     └──────────────┘     └───────────────┘
+
+ステータス遷移:
+draft → open → reviewing → approved/changes_requested → merged/closed
+```
+
+### プライバシーレベル
+
+| レベル | フィルタ対象 |
+|-------|------------|
+| `strict` | ファイルパス、URL、認証情報、全メタデータ |
+| `moderate` | ファイルパス、URL、認証情報 |
+| `none` | フィルタなし |
+
+### CLIコマンド
+
+```bash
+# KGPRを作成
+musubix kgpr create -t "認証パターンの追加"
+
+# 作成前に差分をプレビュー
+musubix kgpr diff --namespace myproject --privacy moderate
+
+# KGPR一覧を表示
+musubix kgpr list
+
+# KGPRをレビューに送信
+musubix kgpr submit <id>
+
+# KGPR詳細を表示
+musubix kgpr show <id>
+
+# マージせずにクローズ
+musubix kgpr close <id>
+```
+
+### MCPツール
+
+| ツール | 説明 |
+|-------|------|
+| `kgpr_create` | ローカル知識グラフからKGPRを作成 |
+| `kgpr_diff` | KGPR作成前に差分をプレビュー |
+| `kgpr_list` | 全KGPRを一覧表示 |
+| `kgpr_submit` | KGPRをレビューに送信 |
+| `kgpr_review` | KGPRをレビュー（approve/changes_requested/commented） |
+
+### 使用例
+
+```bash
+# 1. 共有内容をプレビュー
+musubix kgpr diff --privacy strict
+
+# 2. 説明付きでKGPRを作成
+musubix kgpr create -t "Reactパターンの共有" -d "project-xから学習したパターン"
+
+# 3. KGPRを確認
+musubix kgpr show KGPR-001
+
+# 4. レビューに送信
+musubix kgpr submit KGPR-001
+```
+
+---
+
+## YATA プラットフォーム拡張
+
+*(v1.7.0)*
+
+バージョン1.7.0では、YATAプラットフォームに5つの主要機能が追加されました。
+
+### Phase 1: インデックス最適化
+
+YATA Localのクエリパフォーマンスを複合インデックスで最適化。
+
+```typescript
+import { IndexOptimizer } from '@nahisaho/yata-local';
+
+const optimizer = new IndexOptimizer(database);
+
+// クエリパターンを分析して最適なインデックスを作成
+const analysis = await optimizer.analyzeQueryPatterns();
+const created = await optimizer.createOptimalIndexes();
+
+// インデックスの健全性をチェック
+const health = await optimizer.checkIndexHealth();
+```
+
+**主な機能:**
+- 一般的なクエリパターン用の複合インデックス作成
+- 断片化検出によるインデックス健全性監視
+- 自動最適化推奨
+
+### Phase 2: 拡張エクスポートパイプライン
+
+増分エクスポートと複数フォーマット対応の強力なエクスポート機能。
+
+```typescript
+import { ExportPipeline } from '@nahisaho/yata-local';
+
+const pipeline = new ExportPipeline(database);
+
+// フルエクスポート
+const fullData = await pipeline.exportFull({ namespace: 'myproject' });
+
+// 増分エクスポート（前回エクスポート以降の変更）
+const changes = await pipeline.exportIncremental({
+  since: lastExportTimestamp,
+  format: 'json'
+});
+
+// 変換付きエクスポート
+const transformed = await pipeline.exportWithTransform({
+  format: 'rdf',
+  includeMetadata: true
+});
+```
+
+**対応フォーマット:**
+- JSON（デフォルト）
+- RDF/Turtle
+- N-Triples
+- カスタムトランスフォーマー
+
+### Phase 3: Global同期統合
+
+YATA LocalとYATA Global間のシームレスな同期。
+
+```typescript
+import { GlobalSyncClient, SyncEngine } from '@nahisaho/yata-global';
+
+const client = new GlobalSyncClient({
+  endpoint: 'https://yata-global.example.com',
+  offlineMode: true
+});
+
+// 同期を初期化
+await client.initialize();
+
+// ローカル変更をプッシュ
+const syncResult = await client.sync({
+  namespace: 'myproject',
+  direction: 'push'
+});
+
+// グローバルから更新をプル
+await client.sync({
+  namespace: 'shared-patterns',
+  direction: 'pull'
+});
+```
+
+**機能:**
+- オフラインファーストと自動同期
+- 競合解決戦略
+- 選択的な名前空間同期
+- フレームワークパターンリポジトリ
+
+### Phase 4: コードジェネレーター強化
+
+設計ドキュメントからの高度なコード生成。
+
+```typescript
+import { CodeGenerator } from '@nahisaho/yata-local';
+
+const generator = new CodeGenerator({
+  language: 'typescript',
+  outputDir: './src/generated'
+});
+
+// C4設計から生成
+const result = await generator.generateFromC4(designDocument);
+
+// カスタムテンプレートで生成
+await generator.generate({
+  template: 'repository-pattern',
+  context: { entityName: 'User' }
+});
+```
+
+**対応パターン:**
+- Repositoryパターン
+- Serviceレイヤー
+- Factoryパターン
+- ドメインイベント
+- Value Objects
+
+### Phase 5: YATA UI（Web可視化）
+
+知識グラフのWebベース可視化・管理インターフェース。
+
+```typescript
+import { YataUIServer, createYataUIServer } from '@nahisaho/yata-ui';
+
+// サーバーを作成して起動
+const server = createYataUIServer({
+  port: 3000,
+  enableRealtime: true
+});
+
+// データプロバイダーを設定
+server.setDataProvider(async () => ({
+  nodes: await getEntities(),
+  edges: await getRelationships()
+}));
+
+await server.start();
+console.log(`UI: ${server.getUrl()}`);
+```
+
+**UI機能:**
+- インタラクティブなグラフ可視化
+- WebSocketによるリアルタイム更新
+- 名前空間フィルタリング
+- エンティティ/リレーションシップ編集
+- エクスポート/インポート機能
+
+### v1.7.0 パッケージ概要
+
+| パッケージ | 説明 |
+|-----------|------|
+| `@nahisaho/yata-local` | IndexOptimizer, ExportPipeline, CodeGenerator |
+| `@nahisaho/yata-global` | GlobalSyncClient, SyncEngine, CacheManager |
+| `@nahisaho/yata-ui` | YataUIServer, グラフ可視化 |
+
+---
+
 ## MCPサーバー連携
 
 ### MCPサーバーの起動
@@ -1152,6 +1863,6 @@ const client = createYATAClient({
 
 ---
 
-**バージョン**: 1.3.0  
-**最終更新**: 2026-01-05  
+**バージョン**: 1.6.0  
+**最終更新**: 2026-01-06  
 **MUSUBIX Project**