multica-projects-and-resources

Multica 项目与资源

快速开始

项目是持久化上下文容器。附加到项目的资源会影响未来的 Agent 任务。

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（或快速创建任务）绑定到项目时，项目描述会被注入到 Agent 的简报中 ## Project Context 下，并作为 project_description 写入 .multica/project/resources.json。请用它承载应适用于项目中每个任务的项目级规则/上下文。

常见资源类型：

• github_repo — 持久化的 GitHub 仓库上下文，包含 resource_ref.url、可选的检出 ref，以及可选的仅用于提示词的 default_branch_hint；
• local_directory — daemon 本地路径上下文，包含 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（默认）在用户的 目录中运行 Agent，一次一个任务；第二个任务会在 waiting_local_directory 中等待。worktree 为每个任务提供该仓库各自的 git worktree，因此任务可以并发运行，并且每个任务都以用户仓库中一个分支的形式交付工作， 而不是编辑工作副本。同一对话的每个任务共享该分支 —— issue 对应 agent/<agent>/<issue>， chat 对应 agent/<agent>/chat-<session> —— 并且每一轮的 worktree 都从上一轮的工作开始， 而不是从 HEAD 开始；没有对话支撑的任务会得到 agent/<agent>/<task>。是否继续由 所有权记录（refs/multica/local-state/<branch>，其中保存着所属对话、该分支已携带的用户目录快照，以及记录时的分支顶端） 决定，绝不依据分支名。用户创建的、同名的分支 —— 或者不再包含所记录 commit 的分支，即被删除后重建或 被强制移动 —— 会被保持不变，任务则回退到 agent/<agent>/<issue>-<id>。一轮只会重放用户自该快照以来所做的更改；当这些 编辑与分支自身的工作发生冲突时，worktree 会以合并中的状态交给 Agent，并且该次运行不会交付任何内容， 直到 Agent 解决冲突。worktree 要求该路径是一个 git 仓库且至少 有一个 commit；否则任务会以显式错误失败。该门槛是 daemon 所声明的 local-worktree-v1 能力 —— 而不是其版本字符串 —— 并且会检查两次：保存时一次，以及针对认领每个任务的 daemon 再检查一次， 因此运行时无法执行 worktree 的机器，其任务会被取消，而不是就地运行。 当该机器上的 daemon 未声明该能力时，保存 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：

[Roadmap](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。