项目资源

为项目关联 GitHub 仓库或本地目录，让后续执行获得稳定的工作上下文。

项目资源告诉智能体这组工作会用到哪些代码，以及在哪里执行。资源会持续关联在项目上，不必在每条 issue 中重复粘贴仓库地址或本地路径。

目前支持两种资源：

资源	适用场景	执行位置
GitHub 仓库	团队共享的代码库，希望由运行时管理 checkout	运行时管理的工作目录
本地目录	已经存在的 checkout、很大的仓库，或需要直接查看本地改动	指定电脑上的原目录

资源进入执行的方式

当智能体处理项目内的 issue 时，Multica 会把项目名称、项目描述和资源列表加入执行上下文，并在工作目录中写入 .multica/project/resources.json。

工作区关联的仓库列表始终包含在执行上下文中。项目关联的仓库在此基础上指明这组工作使用的代码和默认 ref。

本地目录只对绑定它的守护进程有效。本次执行所在的守护进程有匹配的本地目录时，智能体直接进入该目录工作；其他电脑仍使用项目中的 GitHub 仓库或工作区仓库。

添加 GitHub 仓库

打开项目，在资源中选择"添加资源"。可以选择已关联到工作区的仓库，也可以粘贴 Git URL。工作区仓库在 设置 → 代码仓库 中维护；连接 GitHub 后，可在同一页面通过 从 GitHub 选择 导入 App 已授权的仓库。

仓库不限于 GitHub：任何运行时能访问的 Git URL 都可以作为仓库资源。自部署的 Multica 还可以在 设置 → 集成 → Git 代码托管 连接自托管的 Forgejo、Gitea 或 GitLab，见自托管 Git 代码托管。

创建项目时，也可以直接在 Repos 中选择仓库。一个项目可以关联多个 GitHub 仓库。

资源中的 ref 可以指定后续 checkout 默认使用的分支、tag 或 commit。default_branch_hint 只向智能体提供默认分支提示，不会强制切换分支。

添加本地目录

添加本地目录的界面只在 Desktop 中提供，因为浏览器不能选择电脑上的文件夹。

这是逃生舱，不是更方便的默认项。 local_directory 是给那些"不得不这么开发"的人准备的 —— 典型是一个 checkout 就几十 GB 的游戏项目，不可能每来一条任务就重新 clone 一份。

如果你的目录只是一个能正常 clone 的普通 git 仓库，请用 github_repo：它默认走 worktree 模式，同一个仓库上的任务可以无限并发。选 local_directory 意味着这个目录上的任务从此只能一条一条串行跑。先看上面的两种资源对照再决定。

确认 Desktop 的本地守护进程在线。
打开项目的资源。
选择"添加本地目录"，再选择要使用的文件夹。

目录必须是绝对路径，已经存在，并且当前守护进程可以读取和写入。以下路径会被拒绝：系统根目录和盘符根（/、C:\）、用户主目录本身及各主目录的上级（如 /Users、/home、/root），以及 /etc、/var、/tmp、/usr、/opt 等系统目录。如果所选路径是符号链接，会先解析为真实路径再按同样的规则校验一次，串行锁也按真实路径生效。

每个项目在同一台守护进程上最多关联一个本地目录。团队中的不同电脑可以分别为同一个项目关联各自的目录。

本地目录不是隔离环境。智能体会直接看到并修改当前分支和未提交的文件；Multica 不会自动切换分支、stash、commit、push 或创建 PR。

本地目录串行执行

两条执行任务使用同一个真实目录时，后到的任务进入 waiting_local_directory，等前一条释放目录后继续。两个路径经不同符号链接指向同一目录时，同样串行。

等待不会修改目录。等待中的任务可以取消，否则会一直等到目录可用。

需要同时处理多项改动时，使用 GitHub 仓库资源，让运行时为不同工作准备各自的工作目录。

执行期间写入的内容

除了智能体产生的代码改动，运行时还可能在目录中写入当前 AI 编程工具所需的说明文件，以及 .multica/project/resources.json。不希望它们进入版本控制时，加入 .gitignore 即可。

Multica 清理执行环境时不会删除关联的本地目录。智能体对该目录的改动，与你在终端中直接运行 AI 编程工具的改动性质相同，需要同样的审查。

使用 CLI 管理资源

# 创建项目时关联仓库
multica project create \
  --title "Agent UX" \
  --repo https://github.com/multica-ai/multica

# 查看和添加资源
multica project resource list <project-id>
multica project resource add <project-id> \
  --type github_repo \
  --url https://github.com/multica-ai/multica \
  --ref main

# 关联指定守护进程上的本地目录
multica project resource add <project-id> \
  --type local_directory \
  --local-path /absolute/path/to/repo \
  --daemon-id <daemon-id>

# 移除资源
multica project resource remove <project-id> <resource-id>

资源变更会影响之后创建的执行任务，不会改写已经结束的执行记录。

接下来

项目 — 了解项目上下文、进度和负责人。
守护进程与运行时 — 了解任务由哪台电脑领取。
执行任务 — 查看 waiting_local_directory 等执行状态。