multica-projects-and-resources

Multica のプロジェクトとリソース

クイックスタート

プロジェクトは永続的なコンテキストのコンテナです。プロジェクトに添付されたリソースは、将来のエージェントタスクに影響を与える可能性があります。

multica project list --output json
multica project get <project-id> --output json
multica project resource list <project-id> --output json

プロジェクトリソースは、プロジェクトリソースのコマンド/エンドポイントを通じて変更されます。Issue の コメントは永続的なプロジェクトリソースを作成しません。

コアモデル

プロジェクトは作業をグループ化し、永続的なリソースを保持します。リソースは単なる表示用メタデータではなく、後にタスクのブリーフや .multica/project/resources.json に注入されるコンテキストです。

プロジェクトの description も永続的なコンテキストです。Issue（またはクイック作成タスク）がプロジェクトに紐付けられると、プロジェクトの説明が ## Project Context の下でエージェントのブリーフに注入され、project_description として .multica/project/resources.json に書き込まれます。プロジェクト内のすべてのタスクに適用すべきプロジェクト全体のルール/コンテキストに使用してください。

一般的なリソースタイプ:

• github_repo — 永続的な GitHub リポジトリのコンテキスト。resource_ref.url、オプションのチェックアウト ref、およびオプションのプロンプト専用 default_branch_hint を持ちます。
• local_directory — デーモンローカルのパスコンテキスト。resource_ref.local_path、daemon_id、オプションのラベル、および オプションの execution_mode（in_place（デフォルト）または worktree）を持ちます。

CLI

multica project list --output json
multica project get <project-id> --output json
multica project create --title "<title>" --repo <github-url> --output json
multica project create --title "<title>" --start-date 2026-03-01 --due-date 2026-03-31 --output json
multica project update <project-id> --title "<title>" --output json
multica project update <project-id> --due-date 2026-04-15 --output json
multica project update <project-id> --start-date "" --output json   # clear the start date
multica project status <project-id> in_progress --output json
multica project resource list <project-id> --output json
multica project resource add <project-id> --type github_repo --url <github-url> --output json
multica project resource add <project-id> --type github_repo --url <github-url> --ref <branch-or-sha> --output json
multica project resource add <project-id> --type local_directory --local-path <abs-path> --daemon-id <daemon-id> --output json
multica project resource add <project-id> --type local_directory --local-path <abs-path> --daemon-id <daemon-id> --execution-mode worktree --output json
multica project resource update <project-id> <resource-id> --execution-mode in_place --output json
multica project resource update <project-id> <resource-id> --url <new-github-url> --output json
multica project resource update <project-id> <resource-id> --ref <branch-or-sha> --output json
multica project resource remove <project-id> <resource-id> --output json

--execution-mode は、タスクが local_directory をどのように共有するかを決定します。in_place（デフォルト）はユーザーの ディレクトリでエージェントを一度に 1 つのタスクで実行します。2 つ目のタスクは waiting_local_directory で待機します。worktree は各タスクにそのリポジトリの 専用の git worktree を与えるため、タスクは並行して実行され、各タスクはワーキングコピーを編集するのではなく、ユーザーのリポジトリ内のブランチとして作業を 提供します。1 つの会話のすべてのタスクはそのブランチを共有します — Issue の場合は agent/<agent>/<issue>、チャットの場合は agent/<agent>/chat-<session> — そして各ターンの worktree は HEAD からではなく前のターンの作業から 開始します。背後に会話がないタスクには agent/<agent>/<task> が与えられます。継続は、ブランチ名ではなく所有権レコード（refs/multica/local-state/<branch>。これは所有する会話、そのブランチがすでに保持しているユーザーディレクトリのスナップショット、およびそれが記録されたときのブランチチップを保持します）によって 決定されます。ユーザーが作成した同名のブランチ — または記録されたコミットをもはや含まないブランチ（つまり削除して再作成されたか強制的に移動されたもの）— はそのままにされ、タスクは agent/<agent>/<issue>-<id> にフォールバックします。1 つのターンは、そのスナップショット以降にユーザーが変更したものだけを再生します。それらの 編集がブランチ自身の作業と競合する場合、worktree はマージの途中でエージェントに引き渡され、エージェントがそれを解決するまで実行は何も 提供しません。worktree はパスが少なくとも 1 つのコミットを持つ git リポジトリであることを要求します。そうでない場合、タスクは明示的なエラーで失敗します。ゲートは、デーモンがアドバタイズする local-worktree-v1 ケイパビリティです — そのバージョン文字列ではありません — そしてそれは 2 回チェックされます。保存時、および各タスクを請け負うデーモンに対して再度。したがって、そのランタイムが worktree を実行できないマシンでは、タスクは in_place で実行されるのではなくキャンセルされます。 worktree の保存も、そのマシン上のデーモンがそのケイパビリティをアドバタイズしていない間は拒否されます（HTTP 422、コード daemon_version_unsupported）。修正方法は、そのマシンで Multica アプリを更新してから再試行することです。空の値を渡すと、デフォルトに戻すためにクリアされます。

github_repo の場合、非 JSON の --ref は resource_ref.ref を設定します。これはそのプロジェクト内の将来のタスクのデフォルトのチェックアウトブランチ/タグ/SHA です。JSON の --ref '<json>' は、ショートカットでカバーされない完全なペイロードやリソースタイプのためのエスケープハッチとして残ります。

--start-date / --due-date はオプションのカレンダー日付です（YYYY-MM-DD、Issue の日付と同様）。project update では、空の文字列（--start-date ""）を渡すと日付をクリアします。フラグを設定しない場合は変更されません。

コメント内でプロジェクトを参照する

プロジェクトには MUL-123 形式の識別子がないため、そのタイトルを文章として書くと死んだテキストになります。読者のクライアントが自動リンク化できるものが何もないからです。代わりにメンションリンク形式を使用し、multica project list --output json から取得したプロジェクト UUID を指定してください。

[ロードマップ](mention://project/<project-id>)

どのクライアントでもナビゲート可能ですが、表示は異なります。web とデスクトップではプロジェクトのアイコンと現在のタイトルを含むチップとしてレンダリングされ、モバイルではタップするとプロジェクトが開く通常のリンクとしてレンダリングされます。@agent / @squad とは異なり、これは純粋なリンクです。util.MentionRe には project すら含まれていないため、何もエンキューせず、誰にも通知しません。これは issue メンションと同じ無副作用の契約です。

プロジェクトの URL を貼り付けるよりも、この形式を優先してください。web とデスクトップでは、アプリ内の裸のプロジェクト URL を同じチップに展開しますが、モバイルでは展開されません。モバイルでは貼り付けられた URL がシステムブラウザに渡され、読者はアプリから離れてしまいます。

リソースを追加するタイミング

ユーザーが永続的なプロジェクトコンテキストを求めた場合に、プロジェクトリソースを追加または更新します。「把这个 GitHub repo 绑到项目上」、「以后都用这个 repo」、「agent 总是拿不到这个项目的仓库」、または「这个项目要在我的本地目录里跑」などです。

プロジェクトリソースは永続的で、将来のタスクに影響します。multica repo checkout はタスクローカルなチェックアウト状態です。

誤ったコンテキストのデバッグ

1. multica project get <project-id> --output json。
2. multica project resource list <project-id> --output json。
3. github_repo.resource_ref.url、任意の ref、default_branch_hint、および local_directory.resource_ref.daemon_id を確認します。
4. リソースの更新は永続的な変更です。更新後は、リソースを一覧表示することが検証パスです。
5. リソースが期待されるタスクコンテキストと一致する場合は、次にランタイム/リポジトリのチェックアウトパスを確認します。

副作用

プロジェクトの作成/更新/削除/ステータス、およびプロジェクトリソースの追加/更新/削除は、永続的なワークスペース状態を変更し、将来のタスクに影響します。ユーザーがその正確なローカルパスを明示的に要求していない限り、local_directory を変更する前に確認してください。

ソースに基づく詳細: references/projects-and-resources-source-map.md。