在起草、修订或回复之前,请阅读撰写指南和集合约定;该集合的检出内容位于 shared/ 目录下。
视频迭代编排
技能类型:刚性 — 保持工单范围、中断工作、依赖谱系和证据门控。普通故障进入恢复流程;它们不会结束一次实现尝试。
目的与所有权
将Jira史诗、GitHub问题队列或明确的需求列表(可选择缩小到指定工单)转变为持久的交付队列。每个选定的工单或修正都会获得一个独占的实现代理和工作树。在分派之前,编排器选择仅后端、仅前端或跨层范围,并提供完整的执行合约。每个实现代理使用 video-iterative-development 来执行该合约并生成其经过验证的提交。
编排器委托执行,而非决策权。它独占拥有源解释、工单范围、产品行为、仓库和层选择、依赖顺序、分支和PR拓扑、偏差、阻塞器处置、生命周期状态、最终验收和工单报告。它调用而非重复其配套组件:
resume-and-reconcile.md拥有中断工作发现和映射源变更检测。extract-figma-visuals拥有Figma层次结构选择、导出和捆绑验证。feature-conformance拥有源权威、决策记录、可追溯性和交付声明验证。video-iterative-development拥有分配的实现、恢复机制、证据和提交。它返回观察结果和结构化决策请求;它不会更改执行合约或分配交付状态。agent-implementation-reviewer拥有独立的只读计划与差异报告。编排器应用特性合约适配器而不更改该共享审阅者。- 工程指导审查 检查最终差异是否符合适用的仓库约定。它记录具体后果和合理的例外,而不会将偏好转化为新的工单需求。
决策权
重大决策是指任何改变源解释、范围、产品或设计行为、参与的仓库或层、依赖顺序、分支或PR拓扑、所需证据、已批准的偏差、阻塞器处置或最终工单状态的决策。编排器在每个分派之前或响应工作请求时,做出并记录每一个重大决策。本技能授权的自动源解析也是编排器的决策。
实现代理只能选择可逆的、符合仓库惯例的机制,这些机制不改变执行合约,例如本地代码组织、命令排序、确定性的选择器细节,或者如何诊断和重试范围内的故障。当指令不完整、冲突或需要重大选择时,工作代理不得猜测、扩大范围、联系提示者或自行分配终端状态。它向编排器返回结构化的 decision_request,并继续所有未受影响的分配工作。
输入
- 一个Jira史诗键/链接、GitHub问题队列或明确的优先级需求列表。从请求中解析所选队列;对于GitHub或跟踪器无关的运行,不要要求提供Jira。
- 对于修正模式,一个只读的发现Markdown文档。
- 当无法从工作区发现仓库根目录时提供的仓库根目录。
- 可选的只读设计文档或链接。架构是文档的子类型,而不是单独的输入类别。
- 对于适用的UI工单,可选的只读Figma根框架链接(包含
node-id)。 - 可选的通过Slack协调运行的请求,包括一个明确命名的频道或明确请求直接消息运行。如果没有指定目标,
slack-coordinator使用仓库默认值。 - 任何明确的外部权威或截止日期。
不要请求功能ID、合约文件、批准标志、Figma修订版或层分类。缺少可选的Figma或设计文档上下文不是阻塞器。
当请求Slack协调时,直接调用 slack-coordinator 作为编排的一部分;不要生成单独的Slack代理或窗格。为编排使用一个Slack运行和线程。编排器是唯一的Slack联络人,也是其 run_id 的唯一消费者;实现代理向编排器报告,从不自行调用协调器或消费所有者输入。
在只读处理解析史诗和选定的工单后,检查现有的账本以查找活动的协调器 run_id。如果存在,则恢复该运行。否则,确认可执行文件可用,并在第一个改变状态的操作之前调用 run start,将史诗作为工作,请求的结果作为目标,选定的工单作为范围。仅当当前指令中明确命名了单个频道时传递 --channel,仅当提示者明确请求直接消息运行时传递 --dm,否则让协调器使用仓库默认值。在账本第一次允许写入时,记录返回的 run_id、频道、线程时间戳和永久链接。不要仅仅因为工单启动、恢复、重试或更改所有者而启动第二个协调器运行。
在每个编排器改变状态的操作之前,以及在每个授权实现工作的分派或后续操作之前,立即运行 run check。退出码 0 允许该操作。退出码 10 时,使用 run resolve 应用、回答或拒绝所有者输入,然后再次检查。退出码 11 时,暂停,短暂等待后重试,并报告原因;在协调不可用时,绝不改变状态、分派工作或回退到其他Slack路径。退出码 12 是操作员的明确紧急制动决策,允许运行在没有进一步Slack调用的情况下继续。
使用 run event 记录编排阶段变更、工单生命周期变更以及阻塞器开始或清除;守护进程拥有静默间隔状态重新发布。一旦编排达到其最终的完成、失败或取消结果,调用 run finish 一次。遵循独立技能的命令、频道选择、消息和失败合约,而不是在此重复或弱化它们。当未请求Slack协调时,不要启动运行,也不要添加Slack门控。
选择运行模式
使用交付模式而不附加发现结果:对于Jira,阅读Jira交付工作流;对于GitHub和跟踪器无关的队列,阅读交付模式。当所选队列包含发现结果文档时,使用修正模式。阅读修正工作流。
无论哪种模式,在创建工作树之前,运行恢复与源协调。对于Jira,状态起决定性作用:In Progress 和 Code Review 状态为 resume_required,必须采用现有工作,而不是从头开始。
工单范围与设计权限
所选工单的需求和验收标准定义了工作的边界。史诗提供成员资格、顺序和依赖上下文;它决不被假定包含Figma或设计文档中表示的每一个行为。仅映射那些澄清所选工单的Figma节点和文档章节。未映射的设计内容是上下文,而不是缺失、延期或超出范围的工作。
在工单边界内:
- 映射的Figma是视觉和交互行为的默认权威,包括模糊或冲突的工单细节;
- 映射的Figma自动覆盖冲突的设计文档;
- 在没有适用Figma的情况下,映射的设计文档解决模糊的工单细节;
- 仓库和API约定解决剩余的实现细节。
在 .agent-evidence/orchestration/<run-id>/decision-log.md 中记录每个自动解决。仅当罕见的未解决问题会实质性地改变产品范围或用户行为时,才暂停受影响的工单。明确批准偏离权威来源的行为是 approved_deviation;普通的实现决策和Figma解决不是偏差。
在 .agent-evidence/orchestration/<run-id>/design-documents/manifest.json 创建一个运行级别的设计文档清单。它记录源身份、整个文档的SHA-256值,以及仅映射到所选工单的章节的稳定ID、标题和SHA-256值。feature-conformance 引用此清单;它不会创建另一个。
对于每个提供的UI根节点,在分派之前调用 extract-figma-visuals,并将其验证后的捆绑包传递给适用的工作代理。一个提供的Jira、Figma或设计文档源,如果在访问检查和实质性重试后仍不可读,则仅阻塞受影响的工单。绝不替换过时的内容、重新创建的模拟或猜测的需求。
建立运行状态
在分派之前:
- 为选定的史诗工作创建或继续一个目标。只要任何工单有可恢复或独立的工作,就保持其活动状态。
- 检查仓库指导、当前状态、工作树、工单分支、开放的PR、生成的代码规则和文档化的验证命令。对于现有的PR,识别其源工作树以及该工作树不可用的原因。对于跨层工作,将参与仓库的文档化复合启动配置解析为其完整的进程拓扑:每个命令、参数、工作目录、环境源、依赖顺序、端口、健康/功能探测、迁移/夹具步骤、客户端生成步骤、运行时定义和Android Patrol命令。将选定的工作树、验证命令和解析后的拓扑传递给实现代理。仓库文档化的IDE复合配置是拓扑定义,而不是调用IDE的指令。
- 通过所选跟踪器的认证接口解析工单和依赖关系,然后运行恢复/源协调。Jira使用Jira MCP;GitHub或明确列表运行保留其自身的范围和状态权威。
- 提取并验证适用的Figma捆绑包。在提供时创建单个设计文档清单。
- 在预检模式下调用
feature-conformance。修复代理生成的模式或映射错误并重新运行;不要将其呈现为工单阻塞器。 - 解析显式任务目录或配置的任务根目录。使用如下所述的不可变索引收据。创建一个被忽略的账本、
decision-log.md,以及可重建的resume-state.json和source-index.json缓存。当缓存不存在或过时时,Jira、Git、PR、当前清单和当前源读取保持权威性。 - 构建依赖关系表,并记录所有者、所选范围和未更改的层、采用或新的写入面、PR目标、源映射、合约行、编排器决策、证据门控、规范运行时租赁状态、恢复状态和最终状态。当启用Slack协调时,也在运行级别记录其
run_id、频道、线程时间戳、永久链接和当前协调状态。
使用规范的 snake_case 机器状态:ready、waiting、resume_required、resume_needs_lineage、resume_source_missing、active、source_update_detected、reconciliation_active、correction_active、needs_product_decision、locally_verified、submitted、submitted_verified 和 blocked。
保留索引记录和证据
index.json 对任务工件具有权威性。将合约收据记录为 feature-contract (design.contract),符合性记录为 feature-conformance (review.conformance),建议的阻塞器记录为 delivery-disposition (delivery.disposition),以及验证后的提交收据记录为 submission-closure (delivery.closure)。为每个持久的修订版本分配一个新的不可变迭代,绑定其确切的JSON快照路径/哈希、工单、源头部和相关的合约/审查记录。在使用当前记录之前,选择并验证摘要;无效的索引绝不回退到扫描。使用相邻的可选任务工件助手或确切的手动约定。只有真正未索引的传统任务才使用编号记录。
运行账本、恢复清单和源索引是可重建的操作缓存,而不是不可变的验收或审查收据的替代品。原始的视觉捆绑包和捕获内容仍然是排除在外的本地证据。GitHub PR正文、不同的证据注释、直接托管的捕获内容和当前头部回读仍然是发布权威;绝不削弱已安装的发布钩子或基线/当前证据要求。
隔离和堆叠工单工作
为每个活动的实现代理在其修改的每个仓库中提供一个独占的工作树和分支。绝不共享可变的检出或丢弃中断的更改。
- 采用
In Progress和Code Review状态工单的选定源,包括属于该工单的脏工作树。 - 仅为没有采用工作的合格工单创建新工作。
- 从其前置条件的已验证提交的远程头部创建依赖分支。
- 将依赖PR的目标设置为该前置条件分支,以便PR仅包含其工单的增量。记录堆叠的谱系。
- 重用现有的修正PR源分支和PR。仅在其旧工作树不可用时重新创建该确切分支的检出。
- 绝不重置、清理、暂存、强制推送或重写中断的工作,仅仅是为了简化设置。
- 对重叠的写入面进行排序,或创建专门的集成工单分支。
一个已提交的前置条件分支足以用于下游实现、本地验证和提交。
…
[为翻译截断]