Multica 项目与资源体系深度解析：让 github_repo 与 local_directory 成为 Agent 任务的持久上下文

Multica 项目与资源体系深度解析让 github_repo 与 local_directory 成为 Agent 任务的持久上下文【免费下载链接】multicaMake humans and AI agents work as one team — open-source and self-hostable.项目地址: https://gitcode.com/GitHub_Trending/mu/multicaMultica 的 Project 不仅是看板上的分组对象更是“持久上下文容器”绑定到项目上的资源github_repo、local_directory会在每次任务派发时被注入 Agent 的工作简报并落盘为工作目录中的.multica/project/resources.json。本文基于 Multica 仓库内置技能文档 SKILL.md 及其源码映射完整覆盖multica projectCLI 的全部命令、两类资源的数据结构与校验规则、in_place/worktree两种本地目录执行模式的双层能力门控、任务上下文注入链路以及项目提及链接mention://project/uuid的渲染机制读完后可独立完成项目资源的创建、排查与调优。一、核心模型项目是持久的上下文容器技能文档开篇给出了一个关键定性Projects are durable context containers项目是持久上下文容器。这句话决定了整个资源体系的语义边界资源不是展示元数据而是会被消费的运行上下文。绑定到项目上的资源后续会被注入每个任务的 brief任务简报并写入 Agent 工作目录下的.multica/project/resources.json供本地运行的 Agent 直接读取。Issue 评论不会创建持久项目资源。资源的增删改只有一条正路项目资源命令/API 端点。在评论里粘贴一个仓库 URL 不会留下任何持久状态。项目的description同样是持久上下文。当一个 issue或 quick-create 任务绑定到项目时项目描述会被注入 Agent 简报的## Project Context小节并以project_description字段写入.multica/project/resources.json。因此description是承载“项目级规则/全局约定”适用于该项目内所有任务的最佳位置。从源码结构看这条注入链路是完整闭环的claim任务领取处理器读取proj.Description并放进 claim 响应ProjectDescription字段见 handler/daemon.godaemon 侧经Task类型与TaskContextForEnv透传最终由简报生成逻辑写入## Project Context小节execenv/runtime_config.go并由 execenv/context.go 中的writeProjectResources写出.multica/project/resources.json该文件由 Multica 拥有并维护project_description即对应其中的 JSON 字段。二、Quick start先掌握三条读命令multica project list --output json multica project get project-id --output json multica project resource list project-id --output jsonproject list默认输出表格列ID / TITLE / STATUS / LEAD / CREATED支持--status过滤与--full-id显示完整 UUIDproject get默认输出 JSON若项目挂有资源还会向 stderr 打印一行面包屑提示N resource(s) attached — run multica project resource list ...JSON 走 stdout保持可解析project resource list默认表格列ID / TYPE / REF / LABEL其中github_repo的 REF 列会显示为url ref形式一眼看出默认 checkout ref。这三条命令是后续一切诊断与变更的起点先读现状再动手改。三、CLI 参考项目 CRUD 与状态项目命令注册于 cmd/multica/cmd_project.go全部经 HTTP API 落到服务端路由定义在 cmd/server/router.go 的/api/projects之下。项目状态是固定枚举planned、in_progress、paused、completed、cancelledCLI 会在本地先行校验拼写错误会直接给出合法值清单而非等到服务端 400。3.1 创建项目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完整可选 flag--description、--status、--iconemoji、--lead成员或 Agent 名字CLI 会解析成lead_type/lead_id、--start-date、--due-date、--repo可重复。一个值得注意的实现细节--repo传入的每个仓库会被打包进 create 请求体的resources数组resource_type: github_repo由服务端在同一事务中随项目一起挂载资源避免失败时留下“半挂载”的项目——这是 CLI 源码中明确的注释意图。3.2 更新项目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 # 清空开始日期update只把“显式传入”的 flag 放进请求体未传的 flag 不影响原值若一个字段都没传会直接报错提示可用的 flag 清单。日期字段的清空语义依赖Changed()判断见下文 3.4。3.3 变更状态与删除multica project status project-id in_progress --output json multica project delete project-id --output jsonproject status是project update --status的语法糖二者共用同一套状态校验。3.4 日期参数--start-date / --due-date取值为可选日历日YYYY-MM-DD与 issue 的日期字段同构迁移 166_project_dates.up.sql 为project表添加了可空的start_date DATE与due_date DATE两列——存的是纯日历日不含时分与时区保证“3 月 1 日”对任何本地时区的查看者都是 3 月 1 日在project update中传空字符串--start-date 表示清空该日期不传该 flag 则保持原值不动。CLI 源码用cmd.Flags().Changed(start-date)而非空串判断来区分这两种情况与 issue 的日期 flag 行为一致。四、项目资源完整命令集资源子命令与项目命令注册在同一文件中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 json4.1 add 的 flag 与类型约束--type默认github_repo。按类型划分的快捷 flagflag适用类型语义--urlgithub_repo仓库 URL该类型必填除非走 JSON--ref--default-branch-hintgithub_repo可选的默认分支提示仅提示性质--local-pathlocal_directory绝对路径该类型必填--daemon-idlocal_directory拥有该本地路径的 daemon id该类型必填--ref-labellocal_directory内嵌在 resource_ref 中的人类可读标签--execution-modelocal_directoryin_place默认或worktree--ref通用JSON 形态的完整 resource_ref 兜底通道对 github_repo非 JSON 值则视为 checkout ref 并与--url合并--label通用行级人类可读标签与 ref 内 label 不同列对未内置快捷方式的类型CLI 会明确要求--ref json传完整载荷——这意味着新增资源类型时无需改动 CLI通用 JSON 通道天然向前兼容。4.2 update 的合并语义为什么部分编辑不会丢字段服务端的UpdateProjectResource对resource_ref是整体替换见 pkg/db/queries/project_resource.sql 的UPDATE ... SET resource_ref $2。因此 CLI 的resource update在构造请求前会先拉取资源列表找到既有行把url/default_branch_hint/ref或local_path/daemon_id/label/execution_mode作为种子预填入待提交的 payload再覆盖被显式修改的字段cmd_project.go 中buildResourceRefFromFlags的 existingRef 合并逻辑。这套设计带来几个可预期的行为只传--default-branch-hint不会把url弄丢对--default-branch-hint、--ref-label、--execution-mode、--refgithub_repo 的非 JSON 值传空字符串表示删除对应字段execution_mode 清空即回到in_place默认resource_type创建后不可变——要换类型只能 remove 后重新 add--label 或--clear-label清空行级标签--position调整展示顺序。五、两类资源的数据结构与校验资源行结构为project_resource表resource_type JSONB 的resource_ref 行级label/position/created_by。服务端在 API 边界对每种类型做严格校验handler/project_resource.go未知类型直接拒绝防止拼写错误产出 daemon/UI 都无法理解的资源行新类型则可以在不迁移表结构的情况下加入校验分支。5.1 github_repo{ url: https://github.com/org/repo, // 必填http(s) 或 ssh git URL ref: release/1.2, // 可选未来任务的默认 checkout 分支/标签/SHA default_branch_hint: main // 可选提示性字段 }url必填且必须通过isValidGitRepoURL校验ref被提升到 daemon 的RepoData.Ref由 daemon 按任务保存并在 checkout 请求未显式指定 ref 时作为/repo/checkout的默认 refdaemon/health.godefault_branch_hint是提示性质的字段不驱动 checkout 行为。5.2 local_directory{ local_path: /Users/dev/code/multica, // 必填绝对路径 daemon_id: d-xxxx, // 必填把路径锁定到某台机器 label: My Mac main checkout, // 可选UI 展示用 execution_mode: worktree // 可选缺省即 in_place }校验规则validateLocalDirectoryReflocal_path必须非空且看起来是绝对路径——由于服务端不知道 daemon 跑在什么 OS 上接受 POSIX 前导/、UNC 前缀\\、Windows 盘符C:\或C:/三者的并集。这是“拼写防护”而非文件系统检查目录真实存在性由 daemon 在运行时再验证daemon_id必填且把路径限定到单一 daemon 注册同一路径字符串在另一台机器上是另一个资源execution_mode只允许空即in_place、in_place、worktree三种值零值字段缺失意味着in_place——这样在 worktree 模式出现之前创建的资源无需数据迁移就保持原行为。六、execution_mode共享同一个本地目录的两种方式--execution-mode决定了项目任务如何共享local_directory资源这是本技能文档中最复杂、也最容易踩坑的部分。6.1 in_place默认串行直接改用户工作区Agent 直接在用户的目录里运行同一目录同一时间只跑一个任务第二个任务进入waiting_local_directory状态排队等待。daemon 侧由LocalPathLocker按规范化后的真实路径加锁实现daemon/local_directory.go 中的NewLocalPathLocker/Acquire锁的等待回调会把任务置为服务端的waiting_local_directory状态编辑直接落在用户的工作树中风险直观并发的任务可能互相踩踏。6.2 worktree每任务独立 git worktree可并发每个任务在该仓库上获得自己的 git worktree由 execenv/local_worktree.go 中的PrepareLocalWorktree在 daemon 的 env 根目录下创建同一目录上的任务因此可以并发运行每个任务的交付物是用户仓库中的一个agent/agent/task分支源码中分支名为agent/sanitized-agent-name/short-task-id由taskKey生成短任务键而不是直接编辑工作副本前提路径必须是一个至少含一次提交的 git 仓库否则任务会以明确错误失败。注意这个校验发生在任务执行期由 daemon 完成——服务端看不到文件系统无法提前保证任务结束时走Finalize提交并保留分支或Discard清理 worktree 与分支路径。6.3 local-worktree-v1 能力门控为什么检查两次worktree模式受 daemon 声明的local-worktree-v1能力protocol.DaemonCapabilityLocalWorktreeV1门控——注意门控依据是能力声明而非版本字符串并且同一门控被执行两次第一道保存时save-time gate。handler/project_resource.go 中的requireWorktreeCapableDaemon在写入execution_modeworktree时检查该 daemon最近一次注册看到的 runtime 行是否声明了该能力。判定逻辑是“newest-wins”取last_seen_at最新的一行而非“any-row”注销 runtime 只是把行置为 offline、metadata 仍在若某台机器曾运行过具备能力的旧版本、之后又降级any-match 会永远误报“支持”而 newest-wins 读的是该机器当前的二进制。若判定不支持保存被拒绝返回 HTTP 422响应体带code: daemon_version_unsupported、current_version、min_version与daemon_id字段——修复方式就是升级该机器的 Multica 应用后重试。min_versionMinLocalWorktreeCLIVersion只是展示给用户的版本号没有任何门控逻辑依赖它开发构建的 git-describe 版本串会被版本下限刻意豁免版本比较不可靠能力声明才是权威信号。第二道领取时claim-time gate权威门控。保存时的检查只覆盖“写入那一刻”的版本若机器在资源保存之后降级保存门控就失效了。因此 handler/daemon.go 在任务领取claim时再做一次worktreeClaimBlockReason检查它读取的是本次 claim 请求头中 daemon 实际声明的能力X-Client-Capabilities。命中拦截时服务端不是简单返回 4xx而是带着持久化的原因取消任务CancelTaskWithReason类别local_directory_error并返回 422——因为资源被钉在该 daemon 上若只是留空或重新投递任务会无限次回到同一台太旧的机器。源码注释解释了为何必须取消而非降级为 in_place旧版 daemon 遇到不认识的execution_mode字段会直接 JSON 跳过等于把用户明确要求隔离的任务“就地”跑在用户工作区里——这正是 worktree 模式要防止的后果所以宁可失败也不降级。传空值--execution-mode 可把字段清回默认的in_place。相关行为可查的验证代码还包括能力门控的专项测试 handler/worktree_claim_gate_test.go覆盖“旧行残留”“降级后 newest-wins 判否”“升级后判是”等场景。七、--ref 的双重角色--ref在resource add/update中承担两种语义区分规则在 cmd_project.go 的buildResourceRefFromRefFlag值以{或 开头 → 一律按 JSON 载荷解析是完整 payload 或未覆盖类型的逃生通道对github_repo非 JSON 的--ref值就是 checkout ref分支/标签/SHA与--url合并。这个细节很关键像2024数字标签或1234567短 SHA这类全数字值不能走 JSON 解析否则json.Unmarshal会把它当数字静默吞掉一个合法的 checkout ref——所以判定“像 JSON”只用{/[前缀不做宽松解析。非 JSON--ref设置的是resource_ref.ref即该项目未来任务的默认 checkout 分支/标签/SHA更新时只改 ref 不影响url等既有字段见 4.2 的合并语义。八、在评论中引用项目mention://project 链接项目没有MUL-123这类人类可读标识符把项目标题当普通文字写在评论里就是“死文字”——读者的客户端没有东西可以自动链接。正确写法是使用提及链接形式项目 UUID 从multica project list --output json获取[Roadmap这是一个纯渲染链接render-onlyutil/mention.go 中的util.MentionRe正则只匹配member|agent|squad|issue|all五种类型不包含project——因此后端从不解析它不排入通知队列、不通知任何人与issue提及相同的“无副作用契约”刻意比agent/squad更弱各端呈现不同web 与桌面端渲染为带项目图标和当前标题的 chipviews/rich-content 的RichLink与编辑器 mention-view.tsx移动端渲染为普通链接、点击打开项目mobile/markdown 仅路由点击、保留默认富链接样式优先使用提及链接而非粘贴项目 URLweb 与桌面端会把裸的站内项目 URL unfurl 成同样的 chiplink-handler.ts 的parseWorkspaceEntityLink要求同源、无 query/fragment、当前 workspace slug 且 id 指向单一实体但移动端不会——移动端粘贴的 URL 会被交给系统浏览器把读者带出应用Agent 侧的对应说明位于运行时简报的 Mentions 小节execenv/runtime_config_sections.go。九、何时添加资源持久上下文 vs 任务级状态技能文档给出的触发场景用户语言示例“把这个 GitHub repo 绑到项目上”“以后都用这个 repo”“agent 总是拿不到这个项目的仓库”“这个项目要在我的本地目录里跑”。判据是持久性项目资源是持久的影响该项目未来的所有任务而multica repo checkout只是任务本地的 checkout 状态只在当前任务生命周期内有效。用户表达“以后/总是/这个项目就用 X”时应当落到project resource add而不是期待某次 checkout 或某条评论能留下状态。十、调试“错误上下文”的检查清单当 Agent 拿到的仓库、分支或本地目录不对时按顺序排查multica project get project-id --output json—— 确认绑定的是这个项目description是否符合预期multica project resource list project-id --output json—— 列出全部资源逐字段核对github_repo的resource_ref.url、可选ref、default_branch_hintlocal_directory的resource_ref.daemon_id是否指向当前机器更新资源是持久变更更新后以再次 list 作为验证路径update 的响应只回显被改的行list 才是完整状态;若资源与期望的任务上下文一致问题就不在资源层——下一步检查运行时runtime/仓库 checkout 路径daemon 侧的RepoData.Ref、worktree 准备日志等。十一、副作用与操作纪律技能文档对副作用的界定非常明确project create/update/delete/status与project resource add/update/remove全部是对持久 workspace 状态的变更会实实在在影响未来任务除非用户明确要求过那条具体的本地路径修改local_directory之前必须先询问——它指向的是用户机器上真实存在的工作目录错误配置会让 Agent 在错误的目录里串行占用锁甚至worktree 配置错误时产生预期外的分支交付。十二、源码地图继续深入的路径以下文件构成本主题的完整实现面摘要自仓库内置的 projects-and-resources-source-map.md关注点位置CLIproject list/get/create/update/delete/status与project resource ...的注册与实现server/cmd/multica/cmd_project.goAPI 边界校验、execution_mode 常量与 422 保存门控server/internal/handler/project_resource.goclaim 路径的权威 worktree 门控与带因取消server/internal/handler/daemon.go本地目录路径校验、黑名单、LocalPathLocker串行锁server/internal/daemon/local_directory.go每任务 worktree 的创建/提交/清理与分支命名server/internal/daemon/execenv/local_worktree.go.multica/project/resources.json写出与project_descriptionserver/internal/daemon/execenv/context.go## Project Context简报小节server/internal/daemon/execenv/runtime_config.goproject_resource表 CRUD 查询server/pkg/db/queries/project_resource.sqlstart_date/due_date列迁移server/migrations/166_project_dates.up.sql/api/projects与/api/projects/{projectId}/resources路由server/cmd/server/router.go提及正则不含 projectserver/internal/util/mention.go能力门控专项测试server/internal/handler/worktree_claim_gate_test.go掌握这些路径后你可以把“资源为什么没生效”从命令行现象一路追到 claim 响应、daemon 侧 worktree 准备与.multica目录写入的每一环完成从使用到排障的完整闭环。【免费下载链接】multicaMake humans and AI agents work as one team — open-source and self-hostable.项目地址: https://gitcode.com/GitHub_Trending/mu/multica创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考