メインコンテンツへ移動
AIチュートリアル

ZCode開発チュートリアル：デスクトップ、Web、ターミナル向けAIコーディング環境の構築

このチュートリアルでは、ZCodeの開発環境を構築し、Electronデスクトップ版、Webワークベンチ、Agent CLIを実行する方法を解説します。さらに、リモートリソース、アクセス認証、配布パッケージの設定方法も紹介します。

約19分で読了
ZCode開発チュートリアル：デスクトップ、Web、ターミナル向けAIコーディング環境の構築

ZCode について

ZCode プロジェクトロゴ

ZCode は AI コーディングワークベンチで、Electron デスクトップアプリ、ブラウザーインターフェース、ターミナル Agent を提供します。リポジトリは workspace 形式で構成され、クライアント、バックエンドサービス、共有 UI、Agent CLI、TUI、ランタイムのソースコードを一元管理しています。

プロジェクトには、主に3つの開発入口があります。

  • Desktop：Electron デスクトップアプリ。pnpm dev:desktop で起動します。
  • Web：ブラウザーワークベンチとローカルバックエンドを同時に起動します。pnpm dev:web を使用します。
  • Agent CLI：ターミナル Agent または TUI を直接開発します。pnpm --filter @zcode/cli dev を使用します。

また、ZCode は統合コマンドライン配布パッケージとしてビルドすることもできます。インストール後に zcode を実行すると TUI が起動し、zcode --web を実行するとローカル Web ワークベンチが起動します。

主な機能

  • デスクトップ、ブラウザー、ターミナルの3通りの利用方法を提供。
  • Web フロントエンド、HTTP/WebSocket バックエンド、Agent をローカルで連携させ、完全な開発フローを構成可能。
  • Desktop と Web で Agent CLI ランタイムを共有。
  • SSH、WSL などのリモートワークスペース開発に対応。
  • React コンポーネント、hooks、Zustand 状態、プロトコル型、RPC フレームワーク、Agent クライアント SDK を共有。
  • デスクトップインストーラーと統合 ZCode コマンドライン配布パッケージを個別にビルド可能。
  • Web を外部公開する際、自動でアクセス トークンを生成でき、認証トークンを明示的に設定することも可能。

開発環境の準備

必要なツールのインストール

開始前に、以下のツールを準備してください。具体的なバージョンはリポジトリルートの mise.toml に従います。

  • Git
  • Node.js 24.14.0
  • pnpm 10.33.2

リポジトリをクローンしてルートディレクトリに移動したら、推奨される初期化コマンドを実行します。

pnpm bootstrap

pnpm bootstrap は workspace の依存関係をインストールし、デスクトップ側のローカル実行リソースを準備して、build:bootstrap を実行します。Agent CLI とランタイムはすでに apps/zcode-cli/ にあるため、Git submodule の追加初期化は不要です。

デフォルトの bootstrap はリモートリソースの準備をスキップするため、ローカルでのデスクトップ開発に適しています。SSH、WSL、またはリモート配布リソースが必要な場合のみ、リモートリソース関連のコマンドを実行してください。

必要に応じた初期化コマンドの選択

  • pnpm install：依存関係のみをインストール。
  • pnpm prepare:desktop-runtime：デスクトップ実行リソースを準備。デフォルトでリモートリソースの準備も含みます。
  • pnpm prepare:remote-assets：リモート実行リソースのみを準備。
  • pnpm bootstrap:with-remote：依存関係、ローカルリソース、リモートリソースを初期化し、関連パッケージを順番にビルドします。ただしデスクトップアプリの bundle はスキップします。
  • pnpm build：各 workspace パッケージのビルドスクリプトを再帰的に実行します。パッケージ内のリソース準備手順も含まれます。

デスクトップ版の実行

初期化が完了したら、リポジトリルートで Electron デスクトップアプリを起動します。

pnpm dev:desktop

pnpm dev:desktop はデフォルトで pnpm dev:desktop:prod と同じ動作をし、本番サービス設定を使用します。起動スクリプトはローカル実行リソースを準備し、デスクトップ Agent をビルドした後、Electron とソース監視を起動します。

テスト環境を使用する場合は、次を実行します。

pnpm dev:desktop:test

開発データの分離

開発データと日常利用のデータが混在しないように、ZCODE_DATA_BASE_DIR で独立したデータベースディレクトリを指定できます。アプリケーションデータは、そのディレクトリ下の .zcode/ に書き込まれます。

ZCODE_DATA_BASE_DIR="$HOME/.zcode-dev-home" pnpm dev:desktop:test

この記法は macOS と Linux に対応しています。

Web ワークベンチの実行

Web フロントエンドまたはバックエンドのソースコードを変更する場合は、連携開発モードの使用を推奨します。

pnpm dev:web

このコマンドは以下を同時に起動します。

  • Web 開発サーバー。デフォルトアドレスは http://localhost:5173。
  • ローカルバックエンド。デフォルトアドレスは http://localhost:3030。

ブラウザーではフロントエンドのアドレスにアクセスしてください。開発サーバーは /ws と通常の /api リクエストをローカルバックエンドへプロキシします。/api/v1/oauth/token は、現在設定されているプロダクトサービスへ個別にプロキシされます。

バックエンドのワークスペースを指定

macOS または Linux では、環境変数で Web バックエンドが使用するプロジェクトディレクトリを指定できます。

ZCODE_SERVER_WORKSPACE=/path/to/project pnpm dev:web

Agent のソースコードを変更した場合は、CLI とその workspace 依存関係を再ビルドしてからサービスを再起動します。

pnpm --filter @zcode/cli... build

Agent CLI と TUI の開発

ターミナルインターフェースまたは Agent を主に開発する場合は、ソースコードの入口を直接実行できます。

pnpm --filter @zcode/cli dev --help
pnpm --filter @zcode/cli dev

CLI とその依存関係をビルドした後は、生成された CommonJS ファイルを直接実行することもできます。

pnpm --filter @zcode/cli... build
node apps/zcode-cli/packages/cli/dist/zcode.cjs --help

このソースコード入口は Agent CLI を直接実行し、統合配布コマンドにおける --web の振り分けは実行しません。Web を開発する場合は pnpm dev:web を使用してください。統合された zcode コマンドをテストする場合は、コマンドライン配布パッケージをビルドして解凍する必要があります。

ZCode コマンドライン版の使用

コマンドライン配布パッケージは TUI、Web、バックエンド、Agent をまとめ、zcode で統一して起動します。Electron には依存しませんが、実行時には mise.toml の要件を満たす Node.js が必要です。

基本コマンド

# ターミナルの対話インターフェースに入る
zcode

# Web ワークベンチを起動
zcode --web

# プロジェクトとポートを指定し、ブラウザーの自動起動を無効化
zcode --web --workspace /path/to/project --port 3030 --no-open

# ヘルプを表示
zcode --help
zcode --web --help

Web モードはデフォルトで現在のディレクトリを作業ディレクトリとして使用し、127.0.0.1 をリッスンして空きポートを自動選択し、ブラウザーを開きます。デフォルトではアクセス トークンを有効にしません。使用後は、ターミナルで Ctrl+C を押してサービスを停止できます。

ローカルネットワークからのアクセス

ほかのデバイスからアクセスする場合は、リッスンアドレスを 0.0.0.0 に変更します。

zcode --web --host 0.0.0.0

ローカルホスト以外のアドレスをリッスンする場合、ZCode はデフォルトでアクセス トークンを生成します。ターミナルに出力されたトークン付きリンクを使用してサービスにアクセスしてください。--token でトークンを指定することも、--no-token でトークン認証を無効にすることもできます。

汎用 Web サービスの HTTP 入口を直接起動する場合は、ZCODE_SERVER_AUTH_TOKEN で API と WebSocket の認証を設定できます。プログラムインターフェースでサービスを作成する場合は、authToken オプションを使用します。

環境変数の設定

リポジトリルートの .env.example には、サービスアドレスとビルド設定の例が用意されています。必要に応じて .env にコピーし、ローカル専用の上書き項目を .env.local に配置できます。

  • ZCODE_DATA_BASE_DIR：アプリケーションデータのベースディレクトリ。データはその下の .zcode/ に書き込まれます。
  • ZCODE_SERVER_WORKSPACE：Web バックエンドのワークスペースパスを指定。
  • ZCODE_BUILTIN_PROVIDER_CONFIG_FILE：ローカル Provider 設定ファイルを指定。未設定の場合は組み込み設定を使用。
  • ZCODE_DIST_BASE_URL：コマンドラインインストールスクリプトが使用するダウンロードベース URL。

これらのランタイム変数は、起動コマンドの環境に直接設定することもできます。Desktop の開発サービス設定は、dev:desktop:test と dev:desktop:prod で選択します。

SSH と WSL のリモート機能開発

リモートワークスペース機能を開発する前に、リモートリソースを準備します。

pnpm bootstrap:with-remote
pnpm dev:desktop

リモートプロジェクトに接続する際は、リソースとして「ローカルにダウンロードしてからアップロード」を選択します。開発環境はローカルの packages/desktop/mock-cdn とローカルビルド成果物からリソースを取得し、SFTP でリモートホストへアップロードします。CDN にはアクセスしません。

デスクトップインストーラーのビルド

デスクトップ版をビルドするには、次のコマンドを実行します。

pnpm bundle:desktop

デフォルトの対象は macOS arm64 で、出力ディレクトリは packages/desktop/dist/ です。OS と CPU アーキテクチャを指定することもできます。

pnpm bundle:desktop -- --os win --arch x64
pnpm bundle:desktop -- --help

--os は mac、win、linux に対応し、--arch は x64 と arm64 に対応します。実際のパッケージ化と署名には、対象プラットフォームに対応するツールと設定が必要です。

macOS では、生成された DMG を開き、ZCode を「アプリケーション」へドラッグします。ローカルで署名していないビルドの初回起動がシステムによってブロックされた場合は、次を実行できます。

sudo xattr -rd com.apple.quarantine /Applications/ZCode.app

コマンドライン配布パッケージのビルド

コマンドライン配布パッケージのビルド入口は pnpm build:zcode です。ビルド前にダウンロードベース URL ZCODE_DIST_BASE_URL を設定する必要があります。--base-url で直接指定することもできます。

pnpm build:zcode --base-url https://downloads.example.com/zcode/

# ZCODE_DIST_BASE_URL が設定済みの場合
pnpm build:zcode

# 既存のビルド成果物を再利用して再パッケージのみ実行
pnpm build:zcode --skip-build

# 使用可能なオプションを表示
pnpm build:zcode --help

ここでのダウンロード先はプレースホルダーの例にすぎないため、正式リリース時には実際のホスティング先に置き換える必要があります。ビルドスクリプトは CLI/TUI、バックエンド、Web を順に処理し、ネイティブライブラリ、worker、ランタイム依存関係を収集してから、配布パッケージを組み立てます。

デフォルトのバージョンはルートディレクトリの package.json から取得され、出力先は dist/zcode/ です。次のファイルが含まれます。

  • releases/<version>/zcode-<version>.tar.gz：実行パッケージ。
  • releases/<version>/sha256.txt：チェックサム。
  • latest.json：バージョンインデックス。
  • install.sh：インストールスクリプト。

インストールスクリプトは、デフォルトでランタイムを ~/.zcode/runtime にインストールし、~/.local/bin に zcode コマンドを作成します。これらの場所は、それぞれ ZCODE_DIST_HOME と ZCODE_DIST_BIN_DIR で変更できます。

配布パッケージをローカルで検証する

ファイルをアップロードしたりインストールスクリプトを実行したりせずに、ビルド結果を直接展開して実行できます。

zcode_version=$(node -p "require('./dist/zcode/latest.json').version")
mkdir -p dist/zcode/debug
tar -xzf "dist/zcode/releases/$zcode_version/zcode-$zcode_version.tar.gz" \
  -C dist/zcode/debug

# TUI を起動
node dist/zcode/debug/zcode/bin/zcode.mjs

# Web を起動
node dist/zcode/debug/zcode/bin/zcode.mjs --web \
  --workspace "$PWD" --port 3030 --no-open

その後 http://127.0.0.1:3030 にアクセスすると、同じバックエンドがホストする Web ページと Agent の完全な連携フローを検証できます。ポートは空いている必要があります。pnpm dev:web がそのポートを使用中の場合は、--port で別のポートを指定してください。

高度な開発のヒント

  1. 対応するエントリーポイントを優先して使用する：デスクトップ機能には dev:desktop、フロントエンドとバックエンドの連携には dev:web、Agent と TUI には CLI workspace の dev コマンドを使用します。
  2. Agent の変更後は再ビルドする：Web サービスはすべての Agent のビルド結果を自動的に取得するわけではありません。変更後は pnpm --filter @zcode/cli... build を実行してサービスを再起動してください。
  3. テストデータを分離する：ZCODE_DATA_BASE_DIR を使用して、開発シナリオごとに独立したデータディレクトリを作成します。
  4. 外部から接続可能にする場合も認証を維持する：--host 0.0.0.0 を使用した後は、自動生成されたトークンを維持するか、--token を明示的に設定してください。
  5. コマンドの参照元を確認する：pnpm build:zcode は配布パッケージを生成するだけで、システムの PATH にある既存の zcode は置き換えません。macOS と Linux では command -v zcode、Windows では where.exe zcode を実行できます。
  6. 開発時の検証と配布時の検証を区別する：pnpm dev:web はソースコードの反復開発に適しています。展開後の bin/zcode.mjs は、最終的な統合コマンドと配布フロー全体の検証に適しています。

リポジトリ構成の概要

  • packages/desktop：Electron Main、Host、Renderer、およびデスクトップ向けパッケージング。
  • packages/web：Web クライアント。
  • packages/server：HTTP、WebSocket サービス、およびリモート接続。
  • packages/zcode-server-cli：独立した Server の起動とプロセス管理。
  • packages/ui：共有 React コンポーネント、hooks、および Zustand の状態管理。
  • packages/services：業務サービスと永続化。
  • packages/shared、packages/rpc、packages/client：共有プロトコルと型、RPC フレームワーク、および Agent クライアント SDK。
  • packages/provider、packages/provider-node：Provider の共通機能と Node.js 実装。
  • apps/zcode-cli：Agent CLI、TUI、ランタイム、およびツール。
  • scripts、config、third-party：ビルド保守スクリプト、組み込み設定、およびサードパーティ関連資料。

まとめ

ZCode はデスクトップ、Web、バックエンド、Agent CLI を同じ workspace に統合しています。初めて開発する場合は pnpm bootstrap から始め、目的に応じて pnpm dev:desktop、pnpm dev:web、または CLI のソースコード用エントリーポイントを選択してください。リモートワークスペースをテストする場合や正式リリースを行う場合は、必要なリモートリソースを準備してから、対応するデスクトップまたはコマンドライン向けインストールパッケージをビルドします。