项目资源

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

目前支持两种资源：

资源进入执行的方式

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

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

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

添加 GitHub 仓库

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

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

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

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

添加本地目录

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

1. 确认 Desktop 的本地守护进程在线。
2. 打开项目的 资源，或者创建项目对话框里的 本地目录 标签页 —— 项目还没建出来时也能做同样的选择。
3. 选择"添加本地目录"，再选择要使用的文件夹。
4. 选择任务如何使用它 —— 原地 还是 并行，两者的区别见"任务如何共享这个目录"。如果这个文件夹是 git 仓库、并且那台机器上的运行时能做隔离，Desktop 会预选 并行，否则预选 原地。当场可以改，之后也可以在 资源 里点目录旁边的铅笔图标改。

预选只作用于你此刻正在关联的目录。之前关联好的目录仍然保持保存时的模式 —— 已有的配置不会在你不知情的情况下被切换。

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

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

任务如何共享这个目录

本地目录有两种执行模式，按资源逐个设置。在资源面板里可以直接切换，CLI 用 --execution-mode。Desktop 里这两种模式显示为 原地 和 并行；API、CLI 和本页其余部分都使用标识符。

in_place（默认）—— “原地”

智能体直接在你的目录里工作，任务一次只跑一条。两条执行任务使用同一个真实目录时，后到的任务进入 waiting_local_directory，等前一条释放目录后继续。两个路径经不同符号链接指向同一目录时，同样串行。

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

worktree —— “并行”

每条任务拿到你仓库的一个独立 git worktree，建在运行时自己的工作区目录里。同一目录上的任务并发执行，谁都不用排队，并且都不会写你的工作副本。

要求这个目录是一个至少有一次提交的 git 仓库。如果不是，任务会明确报错，而不是悄悄退回串行。那台机器上的运行时也必须实现了该模式。运行时在连接时会声明这项能力，Melso 判断的是这个声明而不是版本号 —— 一个开发构建完全可能带着看起来足够新的版本号，却根本没有对应的实现。这个声明会被检查两次：只要那台机器的运行时没有声明该能力，保存资源就会被拒绝，并提示去升级那台机器上的 App；每条任务在被真正领取时还会再按领取它的运行时检查一次 —— 所以资源保存之后才降级的机器，其任务会被带原因取消，而不是悄悄原地跑掉。选择 worktree 就是在要求隔离，把它换成“直接改你的工作副本”永远不是兜底方案。

智能体看到什么、你拿回什么：

• 智能体从你眼前的状态开始，而不是从 HEAD 开始。 你未提交的改动和未跟踪的文件会被回放进 worktree，所以它不会去 review 一份你已经不用的代码。你自己的工作副本、暂存区和 stash 列表都不会被动到。如果这个状态无法忠实还原 —— 包括未跟踪内容超出回放上限（2000 个文件 / 200 MiB）—— 任务会直接失败，而不是从一棵你认不出来的树开始。通常的解决办法是把还没被忽略的构建产物加进 gitignore 或清理掉。
• 结果是你仓库里的一个分支，命名为 agent/<agent>/<task>。执行记录的运行详情面板里会显示分支名（可直接复制），也可以用 git branch 找到它。用 git log / git diff review，然后自己决定 merge 还是 cherry-pick。Melso 不会替你合并。中途失败的任务同样会报告它的分支，因为它已经把智能体做出来的部分提交进去了。
• 不会静默丢东西。 智能体留下的未提交改动，会在 worktree 被移除前提交到那个分支上，任务中途失败时同样如此。极少数情况下连这次提交都做不了 —— 例如仓库开了 commit.gpgSign 而运行时拿不到签名密钥 —— worktree 会被刻意保留而不是删除，任务标记为失败，并且在你仓库里执行 git worktree list 就能看到存放这些改动的目录。
• 没有产生改动的任务不留下任何东西。 它的分支会被删除，而不是作为一个空条目留在 git branch 里。

由于 worktree 位于运行时的工作区目录内，它会按正常的清理周期回收；只有分支会留在你的仓库里。

执行期间写入的内容

除了智能体产生的代码改动，运行时还可能在目录中写入当前 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 仓库，并让任务在各自的 worktree 中并发执行
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 等执行状态。