feat: initial public release (MAESTRO)

2026-06-03 05:08:00 +00:00
commit f5c7666f6b
823 changed files with 184150 additions and 0 deletions
@@ -0,0 +1,124 @@
+---
+id: settings
+title: システム設定
+category: admin
+order: 170
+keywords: [設定, Settings, 管理者, Workers, Tools, Save & Apply]
+---
+
+# システム設定 (admin)
+
+設定画面は MAESTRO の挙動を `config.yaml` に書き込むための UI です。TopBar → **設定** タブで開きます。左にセクションのサイドバー、右に選択中セクションの編集フォームという 2 ペイン構成です。
+
+YAML キーは **スネークケース** (`max_concurrency`)、コード内は **キャメルケース** (`maxConcurrency`) で、`src/config.ts` の `transformKeys` が自動変換します。UI から保存しても YAML はスネークケースのまま保たれます。
+
+## 画面の構成
+
+- **左サイドバー** — セクションをグループ単位で並べる。グループは `User` / `System` / `LLM` / `Agent Runtime` / `Tools` / `MCP & Connections` / `SSH` の 7 つ
+- **右フォーム** — 選択したセクションの設定項目。ほとんどはその場で編集するインラインフォーム
+- `User` グループ以外は **admin 専用**。一般ユーザーには表示されない (`adminOnly`)
+
+## セクション一覧
+
+サイドバーのグループとセクションは以下の通りです。
+
+### User グループ (全ユーザー)
+
+| セクション | 内容 |
+|-----------|------|
+| Preferences | 自分の新規タスクのデフォルト公開範囲などの個人設定 |
+| 🔔 Notifications | ブラウザ通知 / Web Push の購読設定 |
+| 🧠 Memory & Learning | memory エントリの編集と Reflection 履歴の閲覧・revert |
+
+通知の詳細は [ブラウザ通知](#notifications)、memory の詳細は [メモリと学習](#memory) を参照。
+
+### System グループ (admin)
+
+| セクション | 内容 |
+|-----------|------|
+| Branding | アプリ名・ロゴ・アクセント色などの見た目 |
+| Paths & Storage | `storage.*` の作業ディレクトリ・ユーザーフォルダ・アップロード上限 |
+| Execution | `concurrency` (全 worker 合計の並列度)・`max_movements`・`retry.*` |
+
+### LLM グループ (admin)
+
+| セクション | 内容 |
+|-----------|------|
+| Workers | `llm.workers[]` — ジョブ実行時に呼ぶ LLM 接続の定義 |
+| Gateway Server | この MAESTRO 自身を OpenAI 互換 Gateway として公開 + Virtual Keys |
+| Metrics | Prometheus exporter (`llm.metrics` / `gateway.metrics`) |
+
+Gateway の運用は [LLM Gateway 連携](#llm-gateway) を参照。
+
+### Agent Runtime グループ (admin)
+
+| セクション | 内容 |
+|-----------|------|
+| Ask / Subtasks | ASK 上限・サブタスクの制御 |
+| Context | コンテキスト使用率の警告閾値 (warn / prompt / force_transition) |
+| Safety | `max_iterations`・`max_revisits`・history 要約などの自爆防止 |
+| Reflection | タスク完了後の自動学習。詳細は [Reflection の調整](#reflection) |
+
+### Tools グループ (admin)
+
+| セクション | 内容 |
+|-----------|------|
+| Web & Search | WebSearch / WebFetch / search_filter |
+| Browser Runtime | Playwright BrowseWeb のタイムアウト・channel など |
+| Media & Documents | Vision / OCR / 音声 / Office ファイルの上限 |
+| External Services | X / Maps / Amazon などの外部 API キー |
+| Legacy Knowledge | 旧 DKS 設定 (新規 namespace は MCP に移行) |
+
+### MCP & Connections グループ (admin)
+
+| セクション | 内容 |
+|-----------|------|
+| MCP Runtime | MCP のグローバル runtime / quota 設定 |
+
+個々の MCP server は User Folder 側で管理します。詳細は [MCP 連携](#mcp) を参照。
+
+### SSH グループ (admin)
+
+| セクション | 内容 |
+|-----------|------|
+| Admin SSH | グローバル接続・grant・監査ログ・マスターキーローテーション |
+
+詳細は [SSH リモート操作](#ssh) を参照。
+
+## Save & Apply の流れ
+
+フォームの値を変更しても、すぐには反映されません。
+
+1. 値を変更すると、画面下部の **保存バー** が琥珀色に変わり「未保存: N 項目」と表示される
+2. **Save & Apply** ボタンで `/api/config` に PATCH 送信。成功すると「保存しました」トースト
+3. やり直したいときは **Discard Changes** でフェッチ済みの値に戻す
+
+注意点:
+
+- 未保存のまま別タブへ移動しようとすると確認ダイアログが出る (`useUnsavedGuard`)
+- 保存は **ETag ベースの楽観ロック**。他の管理者が先に保存していると「設定が他で変更されました。再読み込みしますか？」と表示される
+- Preferences / Notifications / Memory & Learning の 3 つは個人 API で保存するため、この共通保存バーは出ない (各フォーム内で完結)
+
+## 反映タイミング
+
+ほとんどの設定は `ConfigManager` の変更イベントを各サブシステムが購読しているため **サーバ再起動なしで反映** されます。例外は再起動が必要なもの:
+
+- `auth.providers.*` (認証プロバイダ)
+- `db_path`
+- `port`
+
+## センシティブ値の扱い
+
+`llm.workers[].api_key` や `auth.providers.*.client_secret` などのシークレットは、`/api/config` の GET で実値を返さずマスクされます。UI 上は「変更なし」または「env: ENV_NAME」として表示され、保存時に既存値を保持します。
+
+## 環境変数オーバーライド
+
+一部のキーは環境変数で上書きできます: `OLLAMA_BASE_URL`, `OLLAMA_MODEL`, `WORKTREE_DIR`, `CONCURRENCY`, `DB_PATH`, `PORT`, `LOG_LEVEL`。env で上書きされたフィールドはフォーム上でも「環境変数で上書き中」と示されます。
+
+## TIP
+
+> 開発時は `LOG_LEVEL=debug`、本番は `info` を推奨。
+
+> Workers のモデルドロップダウンが空のときは endpoint が応答していない可能性。network / firewall を確認。
+
+> ユーザー管理・権限・安全性の調整は [ユーザー管理 / 安全性](#admin) を参照。