Multica Autopilots 实战指南：理解调度化 Agent 自动化的执行模型与 multica CLI 完整操作

Multica Autopilots 实战指南理解调度化 Agent 自动化的执行模型与 multica CLI 完整操作【免费下载链接】multicaMake humans and AI agents work as one team — open-source and self-hostable.项目地址: https://gitcode.com/GitHub_Trending/mu/multicaAutopilot自动飞行器是 Multica 中“让规则代替人来派发 Agent 工作”的核心自动化机制它以定时schedule、Webhook 或手动三种方式被触发把任务可靠地投递给指定 Agent 或 Squad 的 Leader并全程记录运行状态。本文以仓库内为编码 Agent 编写的内置技能文档 SKILL.md 为主线结合其 源码地图 与后端 Go 实现系统讲清 Autopilot 的对象模型、逐条 CLI 命令、Webhook 的持久化准入链路、凭证安全与排障方法让你既能在multicaCLI 上直接上手也能理解其底层为何能保证“不重复、不丢任务”。这份文档是什么给 Agent 的安全操作契约SKILL.md并不只是普通用户手册。它存放在 server/internal/service/builtin_skills/multica-autopilots/与multica-creating-agents、multica-squads、multica-working-on-issues等一同构成 Multica 面向 AI 操作代理的内置技能库。文档头部的 frontmatter 定义了这个技能何时启用--- name: multica-autopilots description: Use when creating, updating, inspecting, triggering, or debugging a Multica autopilot (scheduled, webhook, or manual). user-invocable: false allowed-tools: Bash(multica *) ---user-invocable: false该技能只能由“看懂上下文后自主决定使用”的 Agent 调用而不是用户显式点名启用allowed-tools: Bash(multica *)Agent 只能通过multicaCLI 的子命令来触碰 Autopilot 资源description划定了能力边界创建、更新、检查、触发、调试Autopilot。因此文档内容整体带有一层强烈的“安全护栏”风格哪些命令会产生真实副作用、哪些字段会被脱敏、什么时候必须追加--show-secrets、什么时候绝不允许为了测试而触发真实任务——这些约束既是给人看的也是写给 Agent 看的执行纪律。核心概念Autopilot 不是 Agent而是“派单规则”文档在最前面就划清了一个关键边界An autopilot is not an agent. It is a rule that dispatches work to an agent, or to a squads leader agent.Autopilot 自身不执行任务它是一段可持久化、可审计的“规则”决定何时、把什么样的工作、交给谁。对象模型可概括为Autopilot规则拥有标题、描述、执行模式、被指派的 Agent或 Squad、可选 Project、订阅者等属性Trigger触发器一个 Autopilot 可挂多个触发器类型为schedulecron 表达式 IANA 时区或webhookRun运行实例每次触发落一条autopilot_run记录跟踪从触发到 Agent 任务/Issue 完成的全生命周期DeliveryWebhook 投递Webhook 入口先把请求持久化为一条webhook_delivery再驱动 Run。完整执行链按文档的表述链条为触发器触发schedule | webhook | manual │ ▼ autopilot_run 记录创建 │ ▼ execution_mode 决定产出create_issue | run_only │ ▼ assignee 就绪检查AgentReadiness │ ▼ Issue / Agent 任务执行 │ ▼ 运行状态同步Webhook 路径在链首多了一层“持久准入”durable admissionHTTP 入口先把请求体落库为排队中的webhook_delivery同步地创建或复用幂等的autopilot_run随即返回200响应体含statusaccepted|skipped与run_id此后由“持有数据库租约的 worker”异步接管已接受的 Run负责可恢复的 Issue/任务派发。这条链路在后端源码 server/internal/service/autopilot.go 中对应三个不同入口各有明确分工见 源码地图DispatchAutopilot调度/API/Webhook 通用入口无人肉触发者归因到rule_ownerDispatchAutopilotManual成员点“立即运行”时的入口会把运行归因attribution到actorUserID即操作者同时成为 originator授权主体与 accountable human责任人两个执行模式都成立AdmitAutopilotWebhookDelivery→DispatchAutopilotForWebhookDeliveryWebhook 专用的“先准入、后派发”两段式入口后文专节展开。两种执行模式模式行为可见性 / 备注create_issue先创建一条 Multica Issue再驱动其执行Run 以 Issue 状态的形式可见issue-title-template可用默认run_only外的首选run_only直接创建 Agent 任务不建 Issue无 Issue 态可见持久的“汇报位置”只能依赖任务上下文或指令自行约定关于 Run 的初始状态源码 server/internal/service/autopilot.go 显示Webhook 准入时create_issue模式初始状态为issue_createdrun_only模式初始状态为running之后随 Issue/任务执行而同步。被指派者Agent 或 Squad Leadercreate时用--agent指定执行者。若被指派者其实是一个 Squad则由resolveAutopilotLeaderautopilot.go在派发时解析出该 Squad 的Leader Agent作为实际接收者——这与多 Agent 协作模型中“由 Leader 编排成员”的设计一致。派发前的就绪门禁是AgentReadinessserver/internal/service/agent_ready.go已归档archived或运行时未就绪runtime-unready的 Agent 会在入队前被拦截对应运行会被记录为“跳过”skipped而不是带着错误硬跑。快速开始先读后写文档给出的安全起手式是三连“只读命令”multica autopilot list --output json multica autopilot get autopilot-id --output json multica autopilot runs autopilot-id --output json其中get用于查看单个规则的状态、模式、被指派者与触发器runs用于查看历史执行。文档特别强调一条红线Do not runtrigger,delete,trigger-delete, ortrigger-rotate-urlto test. Those are real side effects.即不要拿trigger真实触发一次运行、delete、trigger-delete、trigger-rotate-url这类命令做“试试看”——它们会造成真实的持久化副作用或真实启动 Agent 工作。这一点与文档末尾“Side effects”一节严格对应。CLI 子命令全参考multica autopilot家族由 server/cmd/multica/cmd_autopilot.go 注册共 12 个子命令list、get、create、update、delete、trigger、runs、trigger-add、trigger-list、trigger-update、trigger-delete、trigger-rotate-url。下表汇总其用途与关键参数以仓库内实际 flag 定义为准子命令用途关键参数list列出工作区全部 Autopilot--status active\|paused、--output table\|json、--full-idget id查看单个规则默认脱敏 Webhook 凭证--output默认 json、--show-secretscreate新建规则--title、--description、--agent、--mode create_issue\|run_only*、--project、--issue-title-template、--subscriber可重复update id更新规则--title/--description/--agent/--project/--status/--mode/--issue-title-template/--subscriber/--clear-subscribersdelete id删除规则含其触发器与协作者授权—trigger id手动立即运行一次--outputruns id查看执行历史--limit默认 20、--offset、--outputtrigger-add id添加 schedule 或 webhook 触发器--kind schedule\|webhook、--cron、--timezone、--labeltrigger-list id列出触发器 id供 update/delete/rotate 定位--output、--full-idtrigger-update id trigger-id修改触发器--enabled、--cron、--timezone、--labeltrigger-delete id trigger-id删除触发器—trigger-rotate-url id trigger-id轮换 Webhook URL--yes/-y带*为创建时必填。源码层面做了三类校验可直接看成 CLI 契约--title、--agent、--mode缺失直接报错--mode仅接受create_issue或run_onlycmd_autopilot.go--kind默认scheduleschedule 必填--cronwebhook 时若同时传--cron/--timezone会被拒绝cmd_autopilot.go--subscriber解析后必须是成员member且自动去重cmd_autopilot.go——订阅者接收该 Autopilot 创建 Issue 的通知。Agent/项目/成员参数支持用 UUID也支持按名称做大小写不敏感的子串解析当名称命中多个结果时命令会列出候选并报“ambiguous”避免误派见 resolveAgent。创建示例与标题模板约束multica autopilot create \ --title 晨会前同步依赖风险 \ --description 扫描本工作区所有进行中 Issue汇总阻塞项并写入任务回复 \ --agent triage-bot \ --mode create_issue \ --issue-title-template 每日同步 {{date}} \ --output jsonissue-title-template是文档特别点名的“陷阱区”只支持{{date}}一个占位符UTC 日期YYYY-MM-DD不要自创{{trigger_id}}、{{branch}}之类的变量。后端对此有双重防线创建/更新时ValidateIssueTitleTemplate会把模板中出现的每个{{...}}token 与支持集比对遇到未知 token 直接报错autopilot.go触发渲染时interpolateTemplate只替换白名单里的date且容忍{{ date }}花括号内带空格写法确保“校验通过即渲染一致”autopilot.go模板留空是合法值此时回退使用 Autopilot 自身的Title作为 Issue 标题。查看与更新runs的表格输出列包含ID / SOURCE / STATUS / ISSUE / TRIGGERED_AT / COMPLETED_ATlist表格则给出ID / TITLE / STATUS / MODE / ASSIGNEE / NEXT_RUN / LAST_RUN。其中NEXT_RUN用相对时间如in 2h、3d ago渲染无后续调度时显示—让你一眼区分“有定时计划的 Autopilot”与“根本没挂触发器”的规则cmd_autopilot.go。暂停/恢复用update改状态即可multica autopilot update autopilot-id --status paused --output json multica autopilot update autopilot-id --status active --output json若想调整执行模式或被指派 Agent同样走update --mode/--agentupdate仅在至少给出一个字段时才有意义全部字段未改会直接报“no fields to update”。前端同款能力对应 packages/views/autopilots/components/autopilot-dialog.tsx创建/编辑弹窗与 autopilot-detail-page.tsx详情页。触发器管理schedule 与 webhook定时触发器multica autopilot trigger-add autopilot-id \ --kind schedule \ --cron 0 9 * * * \ --timezone Asia/Shanghai \ --output json--timezone使用 IANA 时区名默认 UTC。为帮助编辑器/用户在保存前得到权威的“下一次运行时间”服务端暴露了只读计算端点GET /api/autopilots/cron-preview?expr0 9 * * *tzAsia/Shanghai它返回{next_runs: [...]}即接下来 3 次发生的 RFC3339UTC时间表达式非法返回 400 codeinvalid_cron时区不可识别返回 400 codeinvalid_timezone两种错误分开编码是为了让界面能指出“错在哪个输入框”。该端点纯计算、不触碰任何 Autopilot 资源只要求工作区成员身份实现见 server/internal/handler/autopilot_cron_preview.go前端调度编辑器见 packages/views/autopilots/components/schedule-editor/。Webhook 触发器multica autopilot trigger-add autopilot-id --kind webhook --label ci --output json创建成功时 CLI 会在表格之外直接打印可用的 Webhook URLprintWebhookURL。URL 形如https://你的服务地址/api/webhooks/autopilots/token持有该 URL 即等同于可以触发这条 Autopilot因此它属于需要保护的敏感凭证下文“凭证安全”详述。Webhook 为什么“可靠”持久准入 幂等 租约 workerWebhook 触发的核心难点在于上游如 GitHub可能重试、进程可能在任意时刻崩溃。Multica 的答案是先落库、再执行、用数据库做唯一性约束。整条链路落在两个 handler 与一个 service 上HTTP 入口持久化server/internal/handler/autopilot_webhook.go 把公网投递存为排队中的webhook_delivery记录同时同步调用AdmitAutopilotWebhookDelivery若已存在同一次 delivery 对应的 Run 则直接复用否则新建 Runcreate_issue初始issue_createdrun_only初始running并在 Run 上写入webhook_delivery_id最后唤醒 worker。响应保持“快”200statusaccepted|skippedrun_id。幂等键上游用同一X-GitHub-Delivery/Idempotency-Key重试时会命中已存在的 delivery/Run从而复用原投递绝不再创建第二个 Issue 或任务。租约 worker 恢复server/internal/handler/webhook_delivery_worker.go 以带过期时间的数据库租约认领排队中的 delivery按触发器做派发限速并基于autopilot_run.webhook_delivery_id续跑已被准入的 Run。由于 delivery/run 上有部分唯一索引即使 worker 崩溃后重新认领也会复用原 Run 而不是产生重复任务。代码层面对“并发/崩溃竞态”做了兜底recoverConcurrentWebhookAdmission捕获唯一索引冲突PG 错误码23505冲突即表示另一副本已创建该 Run直接查回复用autopilot.goensureWebhookCreateIssueTask则修复“Issue 事务已提交、但任务入队尚未提交”的崩溃窗口autopilot.go。Webhook 端点与令牌的实现细节从 autopilot_webhook.go 还可以读到几个有意思的实现事实请求体上限 256 KiBmaxWebhookBodyBytes足够容纳正常规模的上游事件同时防止攻击者用超大 JSON 撑爆 Agent 上下文令牌格式为awt_ URL-safe base64(32 随机字节)共 47 字符刻意不用 UUID因为 UUID 熵低122 bit vs 256 bit且视觉上与内部 ID 混淆投递状态取值包括queuedworker 尚未完成派发、dispatched、rejected、ignored、failed携带 worker 错误此外还存在“跳过”这一响应态——当shouldSkipDispatch判定应跳过例如运行时离线时入口照常返回skipped但 delivery 记录本身仍会标记为已交递给 Autopilot 机制autopilot_webhook.go路由层中公网 webhook 入口是免鉴权的/api/webhooks/autopilots/{token}与之相对的受管 REST API/api/autopilots*均在 server/cmd/server/router.go 中挂在工作区鉴权组下。前端侧有两个值得了解的辅助函数packages/core/autopilots/webhook.tsbuildAutopilotWebhookUrl按“服务端权威 URL → API 基地址拼接 → 当前 origin 兜底”的顺序组装完整 URLmaskAutopilotWebhookUrl只遮蔽 URL 末段 token固定宽度••••••••••••不泄露长度信息因为唯一带密钥属性的只有最后一段。凭证安全脱敏、查看与轮换Webhook token 就是触发密钥因此autopilot get的默认行为是脱敏JSON 输出中webhook_token、webhook_path、webhook_url三字段会被置空同时补充has_webhook_token是否存在 token与非敏感的webhook_token_hinttoken 末 4 位用于人工比对确认“就是这条”。该脱敏逻辑见 redactAutopilotWebhookCredentials末四位提示取自 webhookTokenHint。只有当你确实需要拿回“活体”凭证时才显式追加multica autopilot get autopilot-id --show-secrets --output json约束有二--show-secrets只对 JSON 输出生效表格模式下直接报错且命令会向 stderr 打印一条警告“会暴露活体 webhook 凭证勿进入日志与共享记录”cmd_autopilot.go。轮换 URL 的命令也遵循同一纪律——它会使旧 URL立即失效multica autopilot trigger-rotate-url autopilot-id trigger-id --yes --output json不带--yes时会弹出y/N交互确认与 UI 端 AlertDialog 确认的风格一致见 cmd_autopilot.go。文档最后给出的铁律是不要把 webhook token 或签名材料粘贴进评论、日志、文档或 PR——trigger-rotate-url应当只在你确认需要更换凭证时使用。权限模型谁可以看、谁可以写Autopilot 层有一套独立的“查看/写入”双层鉴权对应 server/internal/handler/autopilot.go读list/get/runs/deliveries任何工作区成员都可读但GetAutopilot对无写权限的调用者脱敏webhook_token/webhook_path/webhook_url——因为“看得到 token 就等于能触发”写/执行编辑、删除、触发、回放投递、管理触发器与 Webhook 密钥要求是规则的创建者、工作区owner/admin或被显式授予的协作者collaborator。判定函数为autopilotWriteByOwnership创建者/owner/admin见 autopilot.go#L583-L588与memberCanWriteAutopilot叠加协作者查询autopilot.go#L597-L606并在 HTTP 层由requireAutopilotWrite统一强制创建任何成员都可创建创建者即该规则的 owner成为天然写权限持有者。显式写授权存于autopilot_collaborator表迁移 128仅成员可授无外键随删除事务一并清理。协作管理走两个接口POST /api/autopilots/{id}/collaboratorsbody 为{user_id}与DELETE /api/autopilots/{id}/collaborators/{userId}。它们由更窄的requireAutopilotAccessManagement门禁只有创建者或 owner/admin 能授/收权——被授权的协作者只拥有写/执行权不能再转授或收回别人从而避免权限升级。GetAutopilot响应中会内嵌collaborators数组并盖上两个按调用者计算的布尔位can_write是否可编辑/运行/触发与更窄的can_manage_access是否可进入“管理访问”入口。web/desktop 端对应 autopilot-access-manager.tsx。需要注意的是以上是 Autopilot 资源层授权派发时刻还有一道独立的 Agent 调用权限门禁与之做 ANDshouldSkipDispatch会在入队前检查被指派 Agent 的就绪/可调用状态而autopilotAdmitInvoke遵循“手动触发按当前点击者鉴权、定时/Webhook/API 自动化按规则创建者作为主体鉴权”两者都 fail-closed 且不存在 admin 绕过autopilot.go。调试回答“为什么没跑”文档给出了一个面向“why didnt it run”的结构化排障步骤非常值得照单执行multica autopilot get id --output json—— 先确认规则本身的状态active/paused、执行模式、被指派者与触发器是否都在预期内multica autopilot runs id --output json—— 查 Run 的状态与失败原因failure reason若指派给 Squad则multica squad get squad-id --output json检查 Squad——执行会落到它的 Leader 上检查目标 Agent/运行时multica agent get agent-id --output json与multica runtime list --output json—— 对应AgentReadiness门禁Agent 被归档或运行时离线时运行会被跳过而非执行Webhook 场景看投递状态queued表示 worker 尚未完成派发继续等待或检查 workerfailed则带着 worker 的错误信息。同一X-GitHub-Delivery/Idempotency-Key的重试会复用原投递不会叠加新任务create_issue模式下若 Run 记录关联了 Issue再去检查这条 Issue 的实际进展。这套排查顺序在源码中都能找到支撑点步骤 2/5 的“Run 由 delivery 驱动且不重复”由AdmitAutopilotWebhookDelivery的同步幂等准入与DispatchAutopilotForWebhookDelivery的恢复逻辑保证server/internal/service/autopilot.go步骤 3 的 Leader 解析在resolveAutopilotLeader步骤 4 对应AgentReadiness与运行时列表接口。副作用清单与安全注意事项文档明确列举了会“改动持久状态或启动工作”的操作把它们当作“需慎用”集合create/update/delete触发器的新增/更新/删除/轮换trigger add/update/delete/rotatetrigger手动触发一次运行向/api/webhooks/autopilots/{token}发起 Webhook 调用对应纪律重申调试时优先使用只读命令trigger仅在用户明确要求“立即手动运行”时使用trigger-rotate-url仅在确实需要轮换 Webhook URL 时使用——且旧 URL 会立即失效。延伸阅读源码地图想进一步深挖文档自带一份“源码地图” references/autopilots-source-map.md它把上述每个行为都对应到了具体文件CLI 注册与参数定义server/cmd/multica/cmd_autopilot.go配套测试见 server/cmd/multica/cmd_autopilot_test.go派发/准入/幂等/Leader 解析/跳过判定等核心业务逻辑server/internal/service/autopilot.go受鉴权 REST 路由与免鉴权 Webhook 入口的挂载server/cmd/server/router.goWebhook 持久化与 200 准入语义server/internal/handler/autopilot_webhook.go数据库租约 worker 与派发限速server/internal/handler/webhook_delivery_worker.gocron 预览纯计算端点server/internal/handler/autopilot_cron_preview.go前端 Webhook URL 组装/脱敏工具packages/core/autopilots/webhook.ts前端“管理访问”对话框等界面packages/views/autopilots/components/。小结Multica Autopilot 的可靠性建立在三个设计选择上把 Autopilot 定义为“派单规则”而非执行体把 Webhook 做成“先持久准入、后租约派发”的两段式幂等流水线以及把凭证与权限做成“默认脱敏、按需放开、写读分离”。对应到日常使用你只需要记住创建时选对create_issue/run_only、标题模板只用{{date}}、Webhook 凭证走--show-secrets要三思、排查“没跑”时按 get → runs → squad → agent/runtime → delivery 的顺序逐步缩小范围。至此无论你是想用multica autopilot create起一个每日巡检的定时自动化还是想接入 CI 事件让机器人自动建 Issue 并跟进都有了可执行、可验证的完整路径。【免费下载链接】multicaMake humans and AI agents work as one team — open-source and self-hostable.项目地址: https://gitcode.com/GitHub_Trending/mu/multica创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考