デュアルライセンス · オープンソース: AGPL-3.0 · クローズドソース: プロプライエタリライセンス（書面による同意が必要）。 商用に関するお問い合わせ: [email protected] / bilibili [柏斯阔落]

更新履歴

目次

1. クイックスタート
2. 機能概要（メインパネル）
3. チャット
4. Mind Sea
5. スキルワークショップ
6. Nagaネットワーク
7. Arkマーケット
8. ターミナル設定
9. MusicBox
10. フローティングボール
11. グローバル機能
12. バックエンドアーキテクチャ
13. オプション設定
14. ポート
15. トラブルシューティング

クイックスタート

必要環境

• Python 3.11（>=3.11, <3.12）
• オプション: uv — より高速な依存関係インストール
• オプション: Neo4j — ローカルナレッジグラフメモリ

インストール

git clone https://github.com/Xxiii8322766509/NagaAgent.git
cd NagaAgent

# フロントエンド
cd frontend
npm install
cd ..

# バックエンド
# 方法1: uv（推奨）
uv sync

# 方法2: 手動
python -m venv .venv
source .venv/bin/activate   # Windows: .\.venv\Scripts\activate
pip install -r requirements.txt

最小設定

config.json.exampleをconfig.jsonにコピーし、LLM APIの認証情報を入力してください：

{
  "api": {
    "api_key": "your-api-key",
    "base_url": "https://api.deepseek.com",
    "model": "deepseek-v3.2",
    "provider": "deepseek",
    "use_gateway": true,
    "api_format": "openai"
  }
}

OpenAI互換の任意のAPI（DeepSeek、Qwen、OpenAI、Ollamaなど）で動作します。Anthropicネイティブフォーマットにも対応（api_formatを"anthropic"に設定）。ログイン後は既定で NagaModel Gateway を使用します。ローカルのプロバイダー認証情報を使う場合は、ターミナル設定で use_gateway を無効化します。

設定はまずプロジェクトルートの config.json から読み込まれます。このファイルがない場合のみ、ユーザーデータディレクトリの設定（Linux/macOS は ~/.naga/config.json、Windows は %APPDATA%/NagaAgent/config.json）にフォールバックします。設定画面で保存すると、現在有効な設定ファイルへ書き戻されます。

起動

cd frontend && npm run dev   # ワンクリック起動（設定済み）

機能概要（メインパネル）

起動後、メインパネル（PanelView） に入ります。マウスの動きに連動した3Dパララックス効果（パースペクティブ回転）があります。 すべての機能はメインパネルの8つのエントリーボタンからアクセスできます：

1. チャット · MessageView

ストリーミングツールコール

チャットエンジンはSSE経由で出力をストリーミングし、フロントエンド表示とTTS文分割に同時送信します。 ツールコールはOpenAIのFunction Calling APIに依存せず、LLMが```tool```コードブロック内にJSONを埋め込むため、**OpenAI互換の任意のプロバイダーでそのまま動作します**。 api_format: "anthropic"でAnthropicネイティブAPIフォーマットにも対応。

シングルラウンドツールコールフロー：

LLMストリーミング出力 ──SSE──▶ フロントエンドリアルタイム表示
       │
       ▼
parse_tool_calls_from_text()
  ├─ フェーズ1: ```tool```コードブロックを抽出
  └─ フェーズ2: 裸のJSON抽出にフォールバック
       │
       ▼
  agentTypeでルーティング
  ├─ "mcp"      → MCPManager.unified_call()
  ├─ "openclaw" → Agent Server /openclaw/send
  └─ "live2d"   → UIアニメーション通知
       │
       ▼
  asyncio.gather() 全ツール並列実行
       │
       ▼
  結果をメッセージに注入、次のLLMラウンドを開始（最大5回）

• テキストパース: json5による寛容なパース、全角文字を自動正規化
• SSEフォーマット: data: {"type":"content"|"reasoning","text":"..."}\n\n（直接JSON、base64なし）
• ループ上限: max_loop_stream = 5（設定可能）

ソース: apiserver/agentic_tool_loop.py

コンテキスト圧縮

セッショントークンが10万を超えると自動的にトリガーされ、コンテキストのオーバーフローを防止します：

サマリー構造（6セクション）：重要な事実 / ユーザーの好み / 重要な決定 / TODO / 背景情報 / 最近の状態。 <compress>タグはセッションファイルに永続化されますが、LLMトークン統計にはカウントされません。

DeepSeek推論チェーン表示

DeepSeek使用時、reasoningフィールドがSSE経由でリアルタイムにプッシュされ、フロントエンドで独自のスタイルで表示されます。

2. Mind Sea · MindView

GRAGナレッジグラフメモリ

GRAG（Graph-RAG）は会話から五つ組を自動抽出し、Neo4jに保存して、関連するメモリをLLMコンテキストとして取得します。

五つ組構造： (主語, 主語タイプ, 述語, 目的語, 目的語タイプ)

抽出パイプライン：

1. 構造化抽出（推奨）: beta.chat.completions.parse() + Pydantic QuintupleResponse、temperature=0.3、最大3回リトライ
2. JSONフォールバック: パース失敗時、最初の[から最後の]までのコンテンツを抽出
3. フィルタリング: 事実（行動、関係、状態、好み）のみを保持；比喩、仮定、感情をフィルタリング

エンティティタイプ： person / location / organization / item / concept / time / event / activity

タスクマネージャー：

• 3つのasyncioワーカーがasyncio.Queue(maxsize=100)を消費
• SHA-256重複排除：同一の保留/実行中タスクはスキップ
• 1時間ごとに24時間以上経過したタスクをクリーンアップ

デュアルストレージ：

• ローカル: logs/knowledge_graph/quintuples.json
• クラウド: Neo4jグラフデータベース、graph.merge() upsert

RAG検索： キーワード抽出 → Cypherクエリ → 主語(タイプ) —[述語]→ 目的語(タイプ) 形式でコンテキストに注入

リモートメモリ： ログインユーザーはNagaMemoryクラウドを優先利用；未ログイン時はローカルGRAGが利用可能。パフォーマンスコストを避けるため、クラウドパスはローカルNeo4jへの自動フォールバックを行わなくなりました。

ソース: summer_memory/

Mind Sea 3D可視化

Canvas 2D + 手動3D投影（WebGLではない）、球面座標カメラ、透視除算 700 / depth。

7層レンダリング順序： 背景グラデーション → 床グリッド → 水面 → ボリュメトリックライト（3本のゴッドレイ）→ パーティクルシステム（3層、125パーティクル）→ 生物発光プランクトン（10個、軌跡付き）→ ナレッジグラフノード & エッジ（深度ソート）

グラフマッピング： subject/object → ノード、predicate → 有向エッジ、次数中心性 → ノード高さの重み、100ノード制限

インタラクション： ドラッグで軌道回転、中クリックでパン、スクロールでズーム、ノードクリック/ドラッグ、キーワード検索フィルター

3. スキルワークショップ · SkillView

内蔵MCPエージェント

Model Context Protocolに基づくプラグイン可能なツールアーキテクチャで、各ツールが独立したエージェントとして動作します：

登録 & ディスカバリ： mcp_registry.pyが**/agent-manifest.jsonをglobスキャンし、importlib.import_moduleで動的にインスタンス化。

MCP管理UI

フロントエンドのMcpAddDialog.vueがグラフィカルなMCPツール管理インターフェースを提供 — 再起動不要でツールの追加・削除が可能。

コミュニティスキルインストール

スキルワークショップはコミュニティ公開スキルのワンクリックインストールに対応（Agent Browser、Brainstorming、Context7、Firecrawl Searchなど）。 バックエンドエンドポイント: GET /openclaw/market/items、POST /openclaw/market/items/{id}/install

ソース: mcpserver/

4. Nagaネットワーク · コミュニティフォーラム

コミュニティフォーラム

メインパネルの「Nagaネットワーク」ブロックからアクセス可能な、完全埋め込み型コミュニティ：

ソース: frontend/src/forum/

クレジット & 好感度システム

ログインユーザー限定のゲーミフィケーションインタラクションシステム：

関連API（APIサーバー経由でNagaポータルにプロキシ）: /api/checkin、/api/affinity、/api/credits

5. Arkマーケット · MarketView

Arkマーケットはすべてのリソース取得と管理を集約し、7つのタブに整理されています：

6. ターミナル設定 · ConfigView

設定ページは3つのタブを持つ単一ページにリデザインされました（3-in-1統一）：

キャラクターカードシステム

characters/ディレクトリが切り替え可能なAIキャラクターを管理し、各キャラクターはJSON設定ファイルで記述されます：

{
  "ai_name": "Najezhda",
  "user_name": "User",
  "live2d_model": "NagaTest2/NagaTest2.model3.json",
  "prompt_file": "conversation_style_prompt.txt",
  "portrait": "Naga.png",
  "bio": "開発者 柏斯阔落 が作成したAIアシスタント、愛称Naga。"
}

• 各キャラクターディレクトリには独立した会話スタイルプロンプト、Live2Dモデルアセット、ポートレート画像が含まれます
• キャラクターが有効化されると、AI名とLive2Dモデルはキャラクター JSONにより完全に管理され、UIで手動上書きはできません
• デフォルトキャラクター: Najezhda

ソース: characters/

7. MusicBox · MusicView

メインインターフェースのBGMと同じ再生インスタンスを共有するスタンドアロン音楽プレーヤー（統一BGMアーキテクチャ）：

• プレイリストエディター（MusicEditView）: トラックリストを管理；保存時にグローバルプレーヤーに即座に同期
• 再生状態同期: 再生/一時停止アイコンがオーディオイベントとリアルタイムに更新
• ループ: 現在のトラック終了時に自動的に次のトラックへ進行
• Live2Dリップシンク: TTS再生中、AdvancedLipSyncEngineV2が60FPSでLive2Dの口形状を駆動

8. フローティングボール · FloatingView

メインパネルの「フロート」ボタンをクリックすると、軽量フローティングボールウィンドウに入り、4つの状態を循環します：

ball（100×100の円）→ compact（420×100の折りたたみバー）→ full（420×Nの展開）→ classic（通常ウィンドウ）

外観 & アニメーション：

• スプライトフレーム瞬きアニメーション: 5フレーム（開 → 半閉 → 閉 → 半閉 → 開）、70ms/フレーム、ランダム間隔トリガー
• 返信生成中: 光るハロパルスエフェクト
• ホバー時: 明度リフトエフェクト
• 透明フレームレスウィンドウ、自由にドラッグ可能

機能：

• フローティング状態で直接チャット入力可能；compact / full状態でメッセージ履歴を閲覧
• スクリーンショットキャプチャパネル: 画面ウィンドウを画像添付として選択
• ファイルアップロード対応
• 右クリックメニューはElectronネイティブメニューで実装（小窓でのクリッピングを防止）

グローバル機能

音声インタラクション

TTS（テキスト読み上げ）

• エンジン: Edge-TTS、OpenAI互換エンドポイント /v1/audio/speech
• アーキテクチャ: 3スレッドパイプライン — 文キュー → TTS呼び出し（Semaphore(2)並行）→ pygame再生
• Live2Dリップシンク: 60FPSで5パラメータを抽出（mouth_open / mouth_form / mouth_smile / eye_brow_up / eye_wide）
• ポートクリーンアップ: 起動時に占有ポートを自動検出・解放

ASR（音声認識）

• ローカルエンジン: FunASR、VADエンドポイント検出とWebSocketリアルタイムストリーミング
• 3モード自動切替: LOCAL（FunASR）→ END_TO_END（Qwen Omni）→ HYBRID

リアルタイム音声チャット（DashScope APIキーが必要）

• Qwen Omni経由の全二重WebSocket音声インタラクション
• エコー抑制、VAD検出、オーディオチャンキング（200ms）、セッションクールダウン制御

{
  "voice_realtime": {
    "enabled": true,
    "provider": "qwen",
    "api_key": "your-dashscope-key",
    "model": "qwen3-omni-flash-realtime"
  }
}

ソース: voice/

Live2Dアバター

pixi-live2d-display + PixiJS WebGLを使用してCubism Live2Dモデルをレンダリング。 SSAAスーパーサンプリング: Canvasをwidth × ssaaでレンダリングし、CSS transform: scale(1/ssaa)。

4チャンネル直交アニメーションシステム（live2dController.ts）：

マージ順序: ボディステート → 口 → アクション → 手動オーバーライド → 感情ブレンド → トラッキングブレンド

OpenClawコンピュータ制御

OpenClaw Gateway（ポート20789）と連携し、自然言語でAIコーディングアシスタントにローカルタスクを委託します。

• 3層フォールバック起動： パッケージバイナリ → グローバルopenclawコマンド → 自動npm install -g openclaw
• sessionKeyフック（2026.2.17+）対応、カスタムフックパスの設定可能
• POST /openclaw/sendで命令を送信、最大120秒待機

タスクスケジューラ（TaskScheduler）：

• タスクステップの記録（目的/内容/出力/分析/成功状態）
• 「重要な発見」マーカーの自動抽出
• メモリ圧縮: ステップがしきい値を超えると、LLMがCompressedMemoryを生成（key_findings / failed_attempts / current_status / next_steps）
• schedule_parallel_execution()がasyncio.gather()でタスクリストを並列実行

ソース: agentserver/

スプラッシュアニメーション

バックエンドアーキテクチャ

NagaAgentは5つの独立したマイクロサービスで構成され、すべてmain.pyによってオーケストレーションされます：

┌─────────────────────────────────────────────────────────┐
│                   Electron / PyQt5 フロントエンド          │
│  Vue 3 + Vite + UnoCSS + PrimeVue + pixi-live2d-display │
│                                                         │
│  PanelView · MessageView · MindView · SkillView         │
│  MarketView · ConfigView · MusicView · FloatingView     │
│  ForumListView · ForumPostView · ForumQuotaView …       │
└──────────┬─────────────┬──────────────┬─────────────────┘
           │             │              │
   ┌───────▼──────┐ ┌────▼────┐  ┌─────▼──────┐
   │  API Server  │ │  Agent  │  │   Voice    │
   │   :8000      │ │  Server │  │  Service   │
   │              │ │  :8001  │  │   :5048    │
   │ チャット/SSE │ │         │  │            │
   │ ツールコール │ │ タスク  │  │ TTS / ASR  │
   │ 圧縮        │ │ スケジュ│  │ リアルタイム│
   │ ドキュメント │ │ ール    │  │ 音声       │
   │ 認証プロキシ │ │ OpenClaw│  │            │
   │ メモリAPI   │ └────┬────┘  └────────────┘
   │ スキルマーケ │      │
   │ ット        │  ┌───▼──────────┐
   │ 設定管理    │  │  OpenClaw    │
   └──────┬───────┘  │  Gateway     │
          │          │  :20789      │
   ┌──────▼──────┐   └─────────────┘
   │ MCP Server  │
   │   :8003     │
   │ ツール登録  │
   │ エージェント│
   │ ディスカバリ│
   │ 並列実行    │
   └──────┬──────┘
          │
  ┌───────┴───────────────────────┐
  │      MCPエージェント（プラグイン） │
  │ Weather | Search | Crawl      │
  │ Launcher | Guide | Doc | MQTT │
  └───────────────────────────────┘
          │
   ┌──────▼──────┐
   │    Neo4j    │
   │   :7687     │
   │  ナレッジ    │
   │   グラフ     │
   └─────────────┘

ディレクトリ構造

NagaAgent/
├── main.py                   # 統一エントリーポイント、全サービスをオーケストレーション
├── build.py                  # クロスプラットフォームビルドスクリプト
├── config.json               # ランタイム設定（config.json.exampleからコピー）
├── pyproject.toml            # バージョン5.1.5、プロジェクトメタデータ & 依存関係
│
├── apiserver/                # API Server (:8000)
│   ├── api_server.py         #   FastAPIメインアプリ
│   ├── agentic_tool_loop.py  #   マルチラウンドツールコールループ
│   ├── llm_service.py        #   LiteLLM統一LLMインターフェース
│   └── streaming_tool_extractor.py  # ストリーミング文分割 + TTSディスパッチ
│
├── agentserver/              # Agent Server (:8001)
│   ├── agent_server.py
│   └── task_scheduler.py     #   タスクオーケストレーション + 圧縮メモリ
│
├── mcpserver/                # MCP Server (:8003)
│   ├── mcp_server.py
│   ├── mcp_registry.py       #   マニフェストスキャン + 動的登録
│   ├── mcp_manager.py        #   unified_call() ルーティング
│   ├── agent_weather_time/
│   ├── agent_open_launcher/
│   ├── agent_game_guide/
│   ├── agent_online_search/
│   ├── agent_crawl4ai/
│   ├── agent_playwright_master/
│   ├── agent_vision/
│   ├── agent_mqtt_tool/
│   └── agent_office_doc/
│
├── summer_memory/            # GRAGナレッジグラフメモリ
│   ├── quintuple_extractor.py  #   OpenAI / Anthropicフォーマット対応
│   ├── quintuple_graph.py
│   ├── quintuple_rag_query.py
│   ├── task_manager.py
│   ├── memory_manager.py
│   └── memory_client.py      #   NagaMemoryリモートクライアント
│
├── voice/                    # 音声サービス (:5048 / :5060)
│   ├── output/               #   TTS + リップシンク
│   └── input/                #   ASR + リアルタイム音声
│
├── characters/               # キャラクター設定ディレクトリ
│   └── Najezhda/             #   プロンプト / Live2Dモデル / ポートレート
│
├── frontend/                 # Electron + Vue 3 フロントエンド
│   ├── electron/             #   メインプロセス
│   │   └── modules/          #   backend / hotkeys / menu / tray / updater / window
│   └── src/
│       ├── views/            #   全ページビュー
│       ├── forum/            #   フォーラムモジュール
│       ├── components/       #   共通コンポーネント
│       ├── composables/      #   useAuth / useBackground / useAudio …
│       └── utils/            #   live2dController / session / config
│
├── system/                   # 設定ローダー、環境チェッカー、システムプロンプト
├── guide_engine/             # ゲームガイドエンジン
└── logs/                     # ランタイムログ、ナレッジグラフファイル

オプション設定

{
  "grag": {
    "enabled": true,
    "neo4j_uri": "neo4j://127.0.0.1:7687",
    "neo4j_user": "neo4j",
    "neo4j_password": "your-password"
  }
}

{
  "system": { "voice_enabled": true },
  "tts": {
    "port": 5048,
    "default_voice": "zh-CN-XiaoxiaoNeural"
  }
}

{
  "voice_realtime": {
    "enabled": true,
    "provider": "qwen",
    "api_key": "your-dashscope-key",
    "model": "qwen3-omni-flash-realtime"
  }
}

{
  "web_live2d": {
    "ssaa": 2,
    "model": {
      "source": "GUI またはキャラクターシステムが自動注入",
      "x": 0.5,
      "y": 1.3,
      "size": 6800
    },
    "custom_model_id": "アップロード後に生成されるモデルID",
    "face_y_ratio": 0.13,
    "tracking_hold_delay_ms": 100
  }
}

{
  "mqtt": {
    "enabled": true,
    "broker": "mqtt-broker-address",
    "port": 1883,
    "topic": "naga/agent/topic",
    "client_id": "naga-agent-client"
  }
}

ポート

トラブルシューティング

python main.py --check-env --force-check  # フル環境診断
python main.py --quick-check              # クイックチェック

コントリビューション

IssueやPull Requestを歓迎します。ご質問はQQチャンネル nagaagent1 にご参加ください。

Star履歴