ドメイン仕様書: CLI基盤・アーキテクチャ

[akiojin]

Spec

ドメイン仕様書: CLI基盤・アーキテクチャ

作成日: 2026-04-05
ステータス: active

概要

Rust製 unity-cli の基盤アーキテクチャに関するドメイン仕様書。Node.js+MCPベースの旧実装をRust+TCP直接通信に置換し、ネイティブCLIとして再設計した。CLI本体のサブコマンド体系、TCP通信プロトコル（4byte length + JSON）、設定解決（UNITY_CLI_* 環境変数）、ツールカタログ、ローカルツール（script/index系）のRust移植、UPM/LSP/Cargo配布導線、TDD整備を包含する。さらに、実行効率最適化（daemon化、バッチ実行、バイナリ最適化）およびAgent向けのschema introspection・dry-run・strict validationを含む。

対象コマンド群

• unity-cli raw <tool> --json {...} - 汎用コマンド実行
• unity-cli tool call <tool> / unity-cli tool list / unity-cli tool schema - ツールカタログ操作
• unity-cli system ping - 接続疎通確認
• unity-cli instances list / unity-cli instances set-active - マルチインスタンス管理
• unity-cli unityd start/stop/status/serve - デーモン管理（計画中）
• unity-cli batch - バッチ実行（計画中）
• --dry-run グローバルオプション
• --output text|json 出力形式制御
• ローカルツール: build_index, update_index, find_symbol, find_refs, get_symbols

instances コマンド

複数 Unity インスタンス運用時に、接続先を安全に管理するためのサブコマンド群。

アーキテクチャ: InstanceRegistry

• InstanceRegistry: active 接続先と既知インスタンスを管理するローカル永続状態。
• 保存先: OS標準 config ディレクトリ配下 unity-cli/instances.json。テストでは UNITY_CLI_REGISTRY_PATH で保存先を上書き可能。
• レジストリファイルが欠落・破損していても、再初期化して継続できる。

データモデル

エンティティ	フィールド	型	説明
InstanceRecord	id	String	host:port 形式
	host	String	接続先ホスト
	port	u16	接続先ポート
Registry	active_id	Option<String>	現在アクティブなID
	entries	Vec<InstanceRecord>	既知インスタンス一覧
InstanceStatus (出力)	id	String	host:port
	status	String	up / down
	last_checked_at	String	Unix秒文字列
	active	bool	アクティブ判定
SetActiveResult (出力)	active_id	String	更新後アクティブID
	previous_id	Option<String>	更新前アクティブID

コマンド仕様

instances list

指定ポートの Unity インスタンスの到達性を確認し、一覧表示する。

unity-cli instances list --ports 6400,6401

• 到達可能ポートは status=up、到達不能ポートは status=down と表示。
• --output json でJSON形式の出力が可能。
• ポート重複は自動排除（port deduplication）。

instances set-active

アクティブな接続先インスタンスを切り替える。

unity-cli instances set-active localhost:6401

• 到達不能な host:port を指定した場合、unreachable エラーで失敗する（誤送信防止）。
• 切替成功時は active_id と previous_id を返す。

受け入れシナリオ

1. 前提 指定ポートに Unity が待受中、実行 unity-cli instances list --ports 6400、結果 status=up が返る。
2. 前提 到達不能ポート指定、実行 unity-cli instances set-active host:port、結果 unreachable エラーで失敗する。

TDD対象

• src/instances.rs に parse_id / 到達性判定 / 切替失敗テストを実装済み。

Unity バージョン方針

Unity UPM/Bridge (UnityCliBridge/Packages/unity-cli-bridge) は以下のバージョンポリシーに従う。

対応バージョン

• Unity 2022.3 LTS と Unity 6 の両方でコンパイル可能であること。

条件コンパイル

• 互換分岐は原則 #if UNITY_6000_0_OR_NEWER を用い、API名差分を吸収すること。

破壊的変更の扱い

• 破壊的変更や非対応の追加は Issue 本文 および リリースノート で明示すること。

テスト方針

• 既存テストを Unity 2022.3 / Unity 6 双方で通る形に修正・維持する。

完了済み機能

• ✅ Rust CLI本体の実装・サブコマンド体系・TCP transport・設定解決・TDD整備 (旧 機能仕様書: Rust版 unity-cli 置換・UPM統合・TDD整備 #82)
• ✅ UPM統合 (com.akiojin.unity-cli-bridge)・LSP同梱 (lsp/)・Cargo配布導線 (旧 機能仕様書: Rust版 unity-cli 置換・UPM統合・TDD整備 #82)
• ✅ 108ツールカタログ・ローカルツールRust移植・スキル導線 (旧 機能仕様書: Rust版 unity-cli 置換・UPM統合・TDD整備 #82)
• ✅ tool schema コマンド・--dry-run オプション・strict validation (旧 機能仕様書: Agent向け CLI schema/dry-run/strict validation #100)
• ✅ Unity 2022.3 LTS / Unity 6 両対応・条件コンパイル分岐 (旧 機能仕様書: Unity対応バージョン方針（2022.3 LTS / Unity 6） #144)

Plan

Phase 1: unityd デーモン（最優先）

TCP接続を永続化するデーモンプロセスを導入し、コマンドごとの接続確立コストを排除する。既存 lspd.rs をモデルに unityd.rs を実装。ConnectionPool で (host, port) ごとに接続を再利用。常に auto モード（接続試行→失敗時フォールバック）で動作。

Phase 2: バッチコマンド（Phase 1完了後）

複数コマンドを1回のCLI呼び出しで実行し、IPC往復回数を削減。DaemonRequest::Batch バリアント追加。セミコロン区切り・JSON配列入力をサポート。

Phase 3: Unity側キュードレイン（独立）

Unity Editorが1フレーム内で複数コマンドを処理。フレーム予算（16ms）超過時は次フレームへ繰り越し。

Phase 4: バイナリ最適化（独立・低リスク）

[profile.release] にLTO・codegen-units=1・strip・opt-level="s"・panic="abort"を設定。

Tasks

Phase 1: unityd デーモン

• src/unityd.rs を新規作成（lspd.rs をモデルにスキャフォールド）
• cli.rs に Unityd サブコマンド追加
• DaemonRequest / DaemonResponse 定義
• serve_forever() 実装（Unix Socket / TCP リスナー、アイドルタイムアウト600s）
• start_background() / stop() / status() / ping() / call_tool() 実装
• ConnectionPool 実装（HashMap<(String, u16), UnityClient>）
• 自動モード（デーモン接続試行→失敗時フォールバック）を固定
• TDD: start/stop/status、デーモン経由call_tool、フォールバック、アイドルタイムアウト、接続再利用テスト

Phase 2: バッチコマンド

• セミコロン区切り・JSON配列バッチパーサー実装
• DaemonRequest::Batch バリアント追加
• ワンショットモードでのバッチ実行
• TDD: パーサー、バッチ結果配列、部分失敗継続テスト

Phase 3: Unity側キュードレイン

• UnityCliBridge TCPサーバーでキュードレインループ実装
• フレーム予算チェック・繰り越し実装
• TDD: 同時コマンド処理、フレーム予算超過テスト

Phase 4: バイナリ最適化

• [profile.release] セクション追加（LTO, codegen-units=1, strip, opt-level="s", panic="abort"）
• 最適化前後のバイナリサイズ計測・比較
• 全テスト通過確認

ドキュメント

• docs/development.md にデーモン運用・バッチコマンド使い方を追加
• スキル定義の更新（デーモン関連）

TDD

• RED: unityd start/stop/status、デーモン経由call_tool、フォールバック、アイドルタイムアウト、ConnectionPool再利用のテストを先に追加
• GREEN: 最小実装で通過
• REFACTOR: lspd.rs との共通部分抽出

旧Issue参照

• 機能仕様書: Rust版 unity-cli 置換・UPM統合・TDD整備 #82 機能仕様書: Rust版 unity-cli 置換・UPM統合・TDD整備 (実装完了)
• 機能仕様書: CLI実行効率の最適化 #88 機能仕様書: CLI実行効率の最適化 (実装中)
• 機能仕様書: Agent向け CLI schema/dry-run/strict validation #100 機能仕様書: Agent向け CLI schema/dry-run/strict validation (実装完了)
• 機能仕様書: Unity対応バージョン方針（2022.3 LTS / Unity 6） #144 ドメイン仕様書: Unity バージョン互換方針 (実装完了)

[akiojin]

Skill 契約・Linter・デュアルプラグイン配布の専用 SPEC を立てました: #160

本 Issue (#145) の「✅ 108ツールカタログ・ローカルツールRust移植・スキル導線」で言及している skill 導線部分のうち、以下を #160 へ分離して扱います:

• Claude Code / Codex Skill 契約 v1 (frontmatter / description / SKILL.md 本文の機械検証ルール)
• unity-cli skills lint Rust サブコマンドによる静的検証
• .codex-plugin/plugin.json / .agents/skills/ / .agents/plugins/marketplace.json を新設した Codex プラグイン正式対応
• 既存 14 skill の新契約一括移行
• 開発専用 gh-skills-sync の dev-skills/ 退避