musubix 1.6.0 → 1.8.0

package/docs/USER-GUIDE.ja.md

@@ -19,10 +19,15 @@
 13. [正誤性検証](#正誤性検証) *(v1.4.1)*
 14. [高度な推論](#高度な推論) *(v1.4.5)*
 15. [対話的REPLモード](#対話的replモード) *(v1.5.0)*
-16. [MCPサーバー連携](#mcpサーバー連携)
-17. [YATA知識グラフ](#yata知識グラフ)
-18. [ベストプラクティス](#ベストプラクティス)
-19. [トラブルシューティング](#トラブルシューティング)
+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. [形式検証](#形式検証) *(v1.7.5)*
+21. [MCPサーバー連携](#mcpサーバー連携)
+21. [YATA知識グラフ](#yata知識グラフ)
+22. [ベストプラクティス](#ベストプラクティス)
+23. [トラブルシューティング](#トラブルシューティング)
 
 ---
 
@@ -1073,6 +1078,593 @@ musubix> history clear
 
 ---
 
+## 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, グラフ可視化 |
+
+---
+
+## 形式検証
+
+*(v1.7.5)*
+
+`@nahisaho/musubix-formal-verify` パッケージは、Z3 SMTソルバーを使用した形式検証機能を提供します。
+
+### インストール
+
+```bash
+npm install @nahisaho/musubix-formal-verify
+# オプション: WebAssemblyサポート用にz3-solverをインストール
+npm install z3-solver
+```
+
+### Z3 SMTソルバー統合
+
+```typescript
+import { Z3Adapter, PreconditionVerifier, PostconditionVerifier } from '@nahisaho/musubix-formal-verify';
+
+// Z3アダプター作成（バックエンド自動選択）
+const z3 = await Z3Adapter.create();
+
+// 事前条件検証
+const preVerifier = new PreconditionVerifier(z3);
+const result = await preVerifier.verify({
+  condition: { expression: 'amount > 0 && balance >= amount', format: 'javascript' },
+  variables: [
+    { name: 'amount', type: 'Int' },
+    { name: 'balance', type: 'Int' },
+  ],
+});
+
+console.log(result.status); // 'valid' | 'invalid' | 'unknown' | 'error'
+```
+
+### Hoareトリプル検証
+
+```typescript
+// {P} C {Q} の検証
+const postVerifier = new PostconditionVerifier(z3);
+const hoareResult = await postVerifier.verify({
+  precondition: { expression: 'balance >= amount', format: 'javascript' },
+  postcondition: { expression: 'balance_new == balance - amount', format: 'javascript' },
+  preVariables: [{ name: 'balance', type: 'Int' }, { name: 'amount', type: 'Int' }],
+  postVariables: [{ name: 'balance_new', type: 'Int' }],
+  transition: 'balance_new == balance - amount',
+});
+```
+
+### EARS→SMT変換
+
+```typescript
+import { EarsToSmtConverter } from '@nahisaho/musubix-formal-verify';
+
+const converter = new EarsToSmtConverter();
+
+// EARS要件をSMT-LIB2に変換
+const results = converter.convertMultiple([
+  'THE system SHALL validate inputs',           // ubiquitous
+  'WHEN error, THE system SHALL notify user',   // event-driven
+  'WHILE busy, THE system SHALL queue requests', // state-driven
+  'THE system SHALL NOT expose secrets',        // unwanted
+  'IF admin, THEN THE system SHALL allow edit', // optional
+]);
+
+results.forEach(r => {
+  console.log(`パターン: ${r.formula?.metadata.earsPattern.type}`);
+  console.log(`SMT: ${r.formula?.smtLib2}`);
+});
+```
+
+### トレーサビリティデータベース
+
+```typescript
+import { TraceabilityDB, ImpactAnalyzer } from '@nahisaho/musubix-formal-verify';
+
+// SQLiteベースのトレーサビリティDB作成
+const db = new TraceabilityDB('./trace.db');
+
+// ノード追加
+await db.addNode({ id: 'REQ-001', type: 'requirement', title: 'ユーザー認証' });
+await db.addNode({ id: 'DES-001', type: 'design', title: 'AuthService' });
+await db.addNode({ id: 'CODE-001', type: 'code', title: 'auth.ts' });
+
+// トレーサビリティリンク追加
+await db.addLink({ source: 'DES-001', target: 'REQ-001', type: 'satisfies' });
+await db.addLink({ source: 'CODE-001', target: 'DES-001', type: 'implements' });
+
+// 影響分析
+const analyzer = new ImpactAnalyzer(db);
+const impact = await analyzer.analyze('REQ-001');
+console.log(`影響ノード数: ${impact.totalImpacted}`);
+```
+
+### v1.7.5 パッケージ概要
+
+| パッケージ | 説明 |
+|-----------|------|
+| `@nahisaho/musubix-formal-verify` | Z3統合、Hoare検証、EARS→SMT、トレーサビリティDB |
+
+### サポートされる変数型
+
+| 型 | 説明 |
+|----|------|
+| `Int` | 整数値 |
+| `Real` | 実数 |
+| `Bool` | 真偽値 |
+| `String` | 文字列 |
+| `Array` | 配列型 |
+| `BitVec` | ビットベクトル |
+
+---
+
 ## MCPサーバー連携
 
 ### MCPサーバーの起動
@@ -1385,6 +1977,6 @@ const client = createYATAClient({
 
 ---
 
-**バージョン**: 1.4.5  
-**最終更新**: 2026-01-05  
+**バージョン**: 1.6.0  
+**最終更新**: 2026-01-06  
 **MUSUBIX Project**