Remotion 仓库中的 AI 提交工作流解析/commit扩展与 worker-prompt.md 的实现与协议【免费下载链接】remotion Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion导读本文以 Remotion 仓库内的.pi/extensions/commit/worker-prompt.md为骨架剖析这套内嵌在 Pi Coding Agent 里的「提交工作进程commit worker」机制——当你对维护者会话执行/commit时扩展如何在临时会话分支上启动一个独立 worker、五步完成识别改动 → 提交 → 创建/更新 GitHub PR的全流程并最终以严格的五行结果契约回传状态。读完本文你将掌握该 worker 的任务边界、完整工作流与既有 PR 处理规则、输出协议的设计动机以及它在 扩展入口 与 行为测试 中的源码级落地方式。一、worker-prompt.md 在仓库中的定位.pi/是仓库内嵌的 Pi Coding Agent 扩展目录包含三个扩展commit、pullfrog-monitor、vercel-deployment。其中commit扩展由三个文件组成文件作用worker-prompt.mdworker 的系统提示词模板定义任务边界、工作流与结果契约index.ts扩展的 TypeScript 实现注册/commit命令并驱动整个 worker 生命周期index.test.ts基于bun:test的行为测试验证消息排队与结果回传语义从源码结构可以推断出清晰的职责分工worker-prompt.md是写给另一个 AI 进程看的规范文本而index.ts是围绕这份规范建立的运行时骨架——两者通过运行期模板渲染 严格文本解析耦合在一起构成了一套机器可验证的 Agent 间通信协议。这正是本机制最有价值的设计点worker 的输出不是自由文本而是必须能被parseWorkerResult精确解析的固定格式详见第五节。worker 运行在用户当前 Pi 会话树的**临时兄弟分支temporary sibling branch**上拥有理解工作所需的完整对话上下文但其推理过程与工具调用在任务结束后会从用户活跃会话分支中被移除它操作的是与用户会话相同的 Git checkout 与工作区。换言之这是一次可隔离、可追踪、用完即弃的委托式提交执行。二、worker 的任务边界worker 的职责被严格限定为一句话提交当前任务产生的改动并创建或更新其 GitHub Pull Request。同时用户通过/commit附带的可选上下文{{userContext}}占位符只作为背景信息辅助理解意图文档明确要求不得将其直接照抄为 commit message 或 PR 标题措辞必须从实际改动、完整分支与对话上下文中推导保证准确。一个值得注意的边界约束写在「Workflow」末尾不要为了制造一次提交而修改源文件。由仓库必需的 hooks 或prskill 产生的改动是被允许的但在提交前必须检查这些改动。这从机制层面杜绝了为提交而提交的污染行为。三、五步工作流原文档把 worker 的推进过程定义为五个步骤本文原样继承并逐一注解步骤动作说明1勘察现场检查当前分支、Git status、已暂存/未暂存改动、未跟踪文件、分支提交记录、可能的 base 分支以及当前分支是否已存在 PR2区分改动归属区分属于当前任务的改动与明显无关或模糊的改动若无法安全判定应提交什么绝不盲目暂存或提交直接返回status: failed并附简要说明3无既有 PR 时创建若尚无 PR 且有内容要发布则通过 Pi 的 skill 机制走prskill以该 skill 为准创建首个 PR4已有 PR 时更新若 PR 已存在按下一节的既有 PR 规则执行5无改动时收尾若没有任何可提交、可推送或值得更新的内容返回status: no_changes这五步呈现的是一种先勘察、后判权、再执行的安全顺序第 2 步是所有后续动作的闸门无法归因的改动不会被强行纳入提交范围。四、既有 Pull Request 的处理规则当当前分支已经存在 PR 时worker 必须先读取该 PR 的编号、URL、标题、完整 body、base 分支与 head 分支再决定要更新什么。规则的核心精神可以概括为授权明确、绝不重写历史、尊重人工内容授权语义调用/commit即视为用户授权暂存、提交并推送明确属于当前任务的改动无需再次请求授权提交信息基于当前实际改动给出简洁的 commit message评估 PR 标题与 body 时要通览整个分支推送纪律正常 push绝不 force-push、绕过 hooks、改写已发布历史或更改 PR base元数据更新仅在标题需要变更时才走pr-nameskill仅当 PR 标题/body 已过时或不完整时才更新不得为了换个说法而重写元数据人工内容保护保留有用的手工撰写内容描述、issue 链接、reviewer 备注、checklist、截图/视频、验证细节等只有分支证伪时才删除或重写更新通道更新的 PR body 必须以 Markdown 文件形式放在临时目录中不得通过 shell 参数内联传递 Markdown不使用gh pr edit而是通过gh api以安全 JSON 编码的标题/body 更新 PR 元数据并保持命令输出精简失败降级若普通 push 或 GitHub 更新被拒绝立即停止并上报失败而不是采取破坏性的恢复手段。上述约束在 扩展入口 的实现中体现为worker 会话结束后扩展会等待 agent 空闲再从源叶子节点会话树导航回去把结果以自定义消息投递给用户若过程中出现 assistant 错误、未产出结果或结果格式错误都会走formatFailure失败路径并以 error 通知提示。五、结果契约严格的五行输出协议worker 结束时必须只返回恰好五行、且值均为真实值的结果禁止代码块、标题、多余行、占位符或格式说明。字段定义如下行字段取值1status:四选一committed/updated_pr/no_changes/failed2commit:实际的短 SHA 与 commit message或none3pr:实际的 PR 编号、标题与 URL或none4verification:执行过的验证命令或Not run5notes:重要注意事项或none四个状态值的语义区分同样关键committed本次运行创建并推送了 commit即便同时创建或更新了 PR也以此为准updated_pr没有产生新 commit但推送了既有 commit 或更新了 PR 元数据no_changes无内容可提交/推送/更新failed无法安全完成提交。测试文件 index.test.ts 中给出了一个符合该契约的典型样例status: no_changes commit: none pr: none verification: Not run notes: none六、源码级实现剖析6.1 命令注册与一次调用的完整时序扩展通过pi.registerCommand(commit, {...})注册斜杠命令其描述为Commit changes and create or update a PR. Usage: /commit [optional context]。命令处理器的执行时序可概括为若已有 worker 在运行则直接警告返回防止重入等待当前 turn 空闲后记录sourceLeafId源会话叶子用buildWorkerPrompt(userContext)渲染提示词以自定义消息remotion-commit-worker-promptdisplay: false、triggerTurn: true、deliverAs: followUp触发 worker 会话等待agent_end事件收集 worker 分支产生的消息从消息中定位最后一条 prompt 消息提取其后的最后一段 assistant 文本与可能的错误对文本做严格解析再把结果投递回源叶子节点最终以remotion-commit-result类型消息展示给用户。6.2 模板渲染{{userContext}}的运行期替换提示词模板并非直接发送而是由 buildWorkerPrompt 读取与扩展同目录的worker-prompt.md并执行return template.replaceAll({{userContext}}, () userContext || (none provided));也就是说模板是数据注入后才是完整提示词——这正是文档以{{userContext}}占位符保留可替换插槽这一写法的实现基础。6.3 严格的文本解析器worker 返回的自由文本能否被接受取决于 parseWorkerResult 的三重校验按换行切分后必须恰好等于 5 行RESULT_FIELDS长度每一行必须以字段名:前缀开头且值非空第一行的 status 必须在WORKER_STATUSES [committed, updated_pr, no_changes, failed]中。解析成功后displayStatus会把failed映射为失败、其余映射为成功解析失败或内容缺失时统一通过formatFailure生成五行status: failed的标准失败结果。这套设计保证了无论 worker 行为多不可控主会话收到的永远是规范结果。6.4 worker 运行期间的用户输入保护输入事件处理 有一段重要逻辑当commitWorkerRunning为真且事件不是来自扩展本身时用户的交互消息会被排队挂起并通知用户消息将在 commit worker 退出后释放当前排队 N 条返回action: handled从而避免用户在 worker 执行中途把主会话拐走。worker 结束后若成功回到源叶子节点排队的消息会按顺序释放第一条以普通方式发送开启模板展开其余以followUp方式递送见 releaseQueuedUserMessages若无法退出 worker 分支则消息继续滞留并给出警告。6.5 上下文隔离扩展在pi.on(context)中过滤历史消息remotion-commit-result类型永远不进上下文remotion-commit-worker-prompt仅在 worker 运行时保留。这意味着提交过程的中间产物不会污染用户后续会话的上下文窗口与worker 的推理与工具调用将移出活跃分支的文档声明互为印证。6.6 行为测试佐证index.test.ts 用 mock 的ExtensionAPI与ExtensionCommandContext验证了关键语义worker 运行期间交互消息无论steer还是followUp都会被handled且暂不投递、会话停留在 worker 叶子当agent_end携带五行no_changes结果到达后会话返回源叶子并发送remotion-commit-result随后在agent_start时排队消息才被依次释放。这为「消息排队 — worker 隔离 — 结果回传 — 消息释放」的整条链路提供了可执行的行为基准。七、设计要点总结纵观整套机制可以提炼出四条贯穿始终的设计原则契约先行的 Agent 间通信worker 的行为规范写在文档中而文档的格式约定五行协议又被实现方用代码强制校验文档与代码互为规范与守护安全优先于完成度改动归属存疑即失败、禁止 force-push、禁止破坏性恢复、push 被拒即停手人工内容与历史不可侵犯保留手工 PR body、只改确实过时的元数据、用gh api而非gh pr edit主会话体验零污染消息排队 上下文过滤 临时分支保证一次 AI 提交流程对用户而言是旁路执行、结果送达。八、适用前提与如何观察它工作需要说明的是这套机制不是 Remotion 对外发布的产品功能而是维护者在仓库中内嵌的 Agent 开发基础设施它依赖 index.ts 顶部导入的earendil-works/pi-coding-agent扩展框架并由 Pi 会话的 skill 机制pr、pr-name配合完成 PR 的创建与命名。若要体验需要在安装了该扩展的 Pi Coding Agent 会话中、处于一个带有任务改动的临时分支上执行/commit [可选上下文说明]随后即可在会话中观察到worker 运行中、用户消息被暂时排队、结果以五行状态返回的完整过程对实现细节感兴趣的读者可以对照 worker-prompt.md规范、index.ts实现与 index.test.ts测试三者逐行交叉阅读这套提示词文档 严格解析实现 行为测试的组合本身就是一份很好的 Agent 工作流工程化样例。【免费下载链接】remotion Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考