プロジェクトリソース

プロジェクトのリソースは、この一連の作業がどのコードを使い、どこで実行するかをエージェントに伝えます。リソースはプロジェクトに紐づいたまま保たれるため、リポジトリの URL やローカルパスをイシューごとに貼り直す必要はありません。

現在サポートされているリソースは 2 種類です。

リソースが実行に入る仕組み

エージェントがプロジェクト内のイシューを処理するとき、Melso はプロジェクト名、プロジェクトの説明、リソース一覧を実行コンテキストに追加し、作業ディレクトリに .multica/project/resources.json を書き込みます。

ワークスペースに紐づくリポジトリ一覧は、常に実行コンテキストに含まれます。プロジェクトに紐づくリポジトリは、それに加えて、この一連の作業で使うコードとデフォルトの ref を指定します。

ローカルディレクトリは、それを紐づけたデーモンに対してのみ有効です。実行を担当するデーモンに一致するローカルディレクトリがある場合、エージェントはそのディレクトリに直接入って作業します。ほかのコンピュータは引き続き、プロジェクトの GitHub リポジトリまたはワークスペースのリポジトリを使います。

GitHub リポジトリの追加

プロジェクトを開き、リソース で「リソースを追加」を選択します。ワークスペースに紐づけ済みのリポジトリを選ぶことも、Git URL を貼り付けることもできます。ワークスペースのリポジトリは 設定 → リポジトリ で管理します。GitHub を接続すると、同じページの GitHub から選択 で、App が認可済みのリポジトリをインポートできます。

リポジトリは GitHub に限定されません。ランタイムがアクセスできる Git URL であれば、どれでもリポジトリリソースとして使えます。セルフホストの Melso では、設定 → 連携 → Git ホスティング でセルフホストの Forgejo、Gitea、GitLab も接続できます。詳細はセルフホスト Git ホスティングを参照してください。

プロジェクトの作成時に、リポジトリ で直接リポジトリを選ぶこともできます。1 つのプロジェクトには複数の GitHub リポジトリを紐づけられます。

リソースの ref には、以後の checkout がデフォルトで使うブランチ、タグ、またはコミットを指定できます。default_branch_hint はエージェントにデフォルトブランチのヒントを与えるだけで、ブランチの切り替えを強制しません。

ローカルディレクトリの追加

ローカルディレクトリを追加する UI は Desktop でのみ提供されます。ブラウザからはコンピュータ上のフォルダを選択できないためです。

1. Desktop のローカルデーモンがオンラインであることを確認します。
2. プロジェクトの リソース を開きます。プロジェクト作成ダイアログの ローカルディレクトリ タブでも、プロジェクトができる前に同じ選択ができます。
3. 「ローカルディレクトリを追加」を選び、使用するフォルダを選択します。
4. タスクがそれをどう使うかを選びます — 直接 か 並行 で、違いは「タスクがディレクトリを共有する方法」を参照してください。フォルダが git リポジトリで、そのマシンのランタイムが隔離を実行できる場合、Desktop は 並行 を、そうでなければ 直接 を初期選択します。その場で変更できますし、あとから リソース でディレクトリ横の鉛筆アイコンからも変更できます。

初期選択は、いま紐づけようとしているディレクトリにだけ適用されます。以前に紐づけたディレクトリは保存時のモードのままです — 既存の設定が知らないうちに切り替わることはありません。

ディレクトリは絶対パスで、すでに存在し、現在のデーモンが読み書きできる必要があります。次のパスは拒否されます: システムのルートとドライブのルート（/、C:\）、ホームディレクトリ自体と各ホームディレクトリの親（/Users、/home、/root など）、および /etc、/var、/tmp、/usr、/opt などのシステムディレクトリ。選択したパスがシンボリックリンクの場合は、まず実体のパスに解決してから同じルールでもう一度検証されます。直列ロックも実体のパスに対して働きます。

同じデーモンに紐づけられるローカルディレクトリは、プロジェクトごとに最大 1 つです。チーム内の別々のコンピュータは、同じプロジェクトにそれぞれ自分のディレクトリを紐づけられます。

タスクがディレクトリを共有する方法

ローカルディレクトリには 2 つの実行モードがあり、リソースごとに設定します。リソースパネルから切り替えられるほか、CLI では --execution-mode を使います。Desktop での表示は 直接 と 並行 で、API・CLI とこのページの以降では識別子を使います。

in_place（既定）— 「直接」

エージェントはあなたのディレクトリで直接作業し、タスクは一度に1つずつ実行されます。2 つのタスクが同じ実体のディレクトリを使う場合、後から来たタスクは waiting_local_directory に入り、先のタスクがディレクトリを解放してから続行します。異なるシンボリックリンク経由で同じディレクトリに到達する 2 つのパスも、同じように直列化されます。

待機中にディレクトリが変更されることはありません。待機中のタスクはキャンセルできます。キャンセルしなければ、ディレクトリが使えるようになるまで待ち続けます。

worktree — 「並行」

各タスクが、あなたのリポジトリの独立した git ワークツリー を受け取ります。ワークツリーはランタイム自身のワークスペースディレクトリ内に作成されます。同じディレクトリに対するタスクは並行して実行され、待機は発生しません。どのタスクもあなたの作業コピーには書き込みません。

このモードには、コミットが 1 つ以上ある git リポジトリであることが必要です。そうでない場合、タスクは黙って直列実行に戻るのではなく、明示的なエラーで失敗します。そのマシンのランタイムも、このモードを実装している必要があります。ランタイムは接続時にその能力を宣言し、Melso はバージョン番号ではなくこの宣言で判定します — 開発ビルドは、実装がまったくないまま十分に新しく見えるバージョン文字列を持ちうるからです。この宣言は 2 回検証されます。そのマシンのランタイムが能力を宣言していない間、リソースの保存は拒否され、そのマシンのアプリを更新するよう促されます。さらに各タスクは実際にそれを受け取ったランタイムに対して再度検証されます — つまりリソース保存後にダウングレードされたマシンでは、タスクが黙ってその場で実行されるのではなく、理由付きでキャンセルされます。worktree を選ぶことは隔離を求めることであり、代わりに作業コピーを書き換えることがフォールバックになることはありません。

エージェントが見るもの、あなたが受け取るもの:

• エージェントは HEAD ではなく、あなたが今見ている状態から開始します。 未コミットの変更と未追跡ファイルがワークツリーに再現されるため、すでに手元にないコードをレビューすることはありません。あなた自身の作業コピー、インデックス、stash リストが変更されることはありません。その状態を忠実に再現できない場合 — 再現の上限（2000 ファイル / 200 MiB）を超える未追跡コンテンツがある場合を含む — タスクは、見覚えのないツリーから開始する代わりに失敗します。通常の対処法は、まだ無視されていないビルド成果物を gitignore に加えるか削除することです。
• 成果物はあなたのリポジトリ内のブランチで、agent/<agent>/<task> という名前が付きます。実行の「実行詳細」パネルにブランチ名が表示され（コピーも可能）、git branch でも見つけられます。git log / git diff でレビューし、マージするか cherry-pick するかは自分で決めます。Melso が代わりにマージすることはありません。途中で失敗した実行もブランチを報告します。エージェントが作った分はすでにコミットされているからです。
• 黙って失われるものはありません。 エージェントが未コミットのまま残した変更は、ワークツリーが削除される前にそのブランチへコミットされます。タスクが途中で失敗した場合も同様です。 ごくまれにそのコミット自体が実行できない場合 — 例えば commit.gpgSign が有効で、ランタイムが署名鍵を利用できないリポジトリ — ワークツリーは削除されずに意図的に保持され、タスクは失敗として報告されます。あなたのリポジトリで git worktree list を実行すると、その変更を保持しているディレクトリが表示されます。
• 何も変更しなかったタスクは、何も残しません。 そのブランチは git branch に空の項目として残らず、削除されます。

ワークツリーはランタイムのワークスペースディレクトリ内にあるため、通常のクリーンアップ周期で回収されます。あなたのリポジトリに残るのはブランチだけです。

実行中に書き込まれるもの

エージェントによるコードの変更のほかに、ランタイムは、現在の AI コーディングツールが必要とする指示ファイルと .multica/project/resources.json をディレクトリに書き込むことがあります。バージョン管理に含めたくない場合は .gitignore に追加してください。

Melso が実行環境をクリーンアップするとき、紐づけたローカルディレクトリを削除することはありません。エージェントによるこのディレクトリへの変更は、あなたがターミナルで AI コーディングツールを直接実行したときの変更と同じ性質のものであり、同じようにレビューが必要です。

CLI でリソースを管理する

# プロジェクト作成時にリポジトリを紐づける
melso project create \
  --title "Agent UX" \
  --repo https://github.com/albertsalgueda/melso

# リソースの一覧表示と追加
melso project resource list <project-id>
melso project resource add <project-id> \
  --type github_repo \
  --url https://github.com/albertsalgueda/melso \
  --ref main

# 特定のデーモン上のローカルディレクトリを紐づける
melso project resource add <project-id> \
  --type local_directory \
  --local-path /absolute/path/to/repo \
  --daemon-id <daemon-id>

# ローカル git リポジトリを紐づけ、タスクを各自のワークツリーで並行実行させる
melso project resource add <project-id> \
  --type local_directory \
  --local-path /absolute/path/to/repo \
  --daemon-id <daemon-id> \
  --execution-mode worktree

# 既存のローカルディレクトリのモードを切り替える
melso project resource update <project-id> <resource-id> --execution-mode worktree
melso project resource update <project-id> <resource-id> --execution-mode in_place


# リソースを削除する
melso project resource remove <project-id> <resource-id>

リソースの変更は、その後に作成されるタスクに反映されます。すでに終了した実行の記録が書き換えられることはありません。

次のステップ

• プロジェクト — プロジェクトのコンテキスト、進捗、リードを理解します。
• デーモンとランタイム — タスクをどのコンピュータが受け取るかを理解します。
• タスク — waiting_local_directory などの実行ステートを確認します。