关于 orchestration-envelope
为 Agent 工作流的无头驱动和审查技能定义机器结果契约。它将交互式文本报告与严格校验的 JSON 结果区分开，并规定解析失败时的有限重试流程。
主要功能
- 01定义 Envelope v2 与 SkillOutcome v1
- 02规定驱动结果解析和校验
- 03无效结果仅重试一次
- 04保留仓库状态来源与矛盾
适用场景
- 01为无头工作流驱动解析技能结果
- 02校验技能输出并记录诊断
- 03将仓库状态矛盾交由专门流程处理
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/orchestration-envelope确认已加载。
附带文件references/TURN_CONTRACT.md
详细介绍
机器结果契约（内部）
交互式技能仍以文本为先。无头驱动程序会在边界处获取精简且经过验证的结果；它不会在每项面向用户的技能中重复添加 JSON 部分。
规范的 Turn contract 仍保留在此处，供加载该契约的执行器和审查技能使用。
可执行的事实来源是
@gtrabanco/agentic-workflow-schema：
类型、JSON Schemas、renderOutputInstruction(skill)、parseTurn(input) 和
compileWorkflowSnapshot(input)。本文档仅说明策略；请勿在此处复制第二份 Schema。
输出配置
WORKFLOW_SKILL_PROFILES 是权威清单。
workflow-status始终返回严格的 Envelope v2 传感器结果。 其信封在detail下包含详细的项目视图。- 其他由驱动程序调用的技能仅在驱动程序将
renderOutputInstruction(skill)附加到该次调用时返回 SkillOutcome v1。它包含由模型负责填写的少量字段：结果、下一步意图／目标、阻碍因素、问题、发现和证据引用。 advance（配套的 pi 包命令）是协调器，而非工作技能配置：它以确定性代码的形式处理传感器信封，绝不会输出工作技能的 SkillOutcome。- 交互式调用会输出常规的易读报告；无需驱动程序结果。
两种结果都采用一个最终的 fenced json 代码块。该包会在路由边界拒绝未知键。仓库事实绝不会根据模型文本重新构建：驱动程序会根据选定的版本化文档和调用方提供的仓库事实，编译 WorkflowSnapshot v1。
驱动程序协议
- 读取配置，并且仅在由驱动程序调用时附加
renderOutputInstruction(skill)。 - 将最终响应传递给
parseTurn({skill, text, context})。将返回的来源和诊断信息与运行日志一同保存。 - 如果机器结果缺失、格式错误或无效，则在同一会话中重新调用一次，并发送：
Emit only the machine result for the turn above. - 解析修复后的回复。第二次失败即视为驱动程序级别的
FAILED；绝不无限重试，也绝不将任意文本转化为工作流事实。
兼容性刻意限制在较窄范围内：仅当缺失值可通过机械方式确定时，才会修复文档记载的旧版 v2 格式。非零的问题计数却没有对应的问题标识、未匹配的数字单元 ID，或无关文本，仍然无效，并会报告给驱动程序。
契约演进
- 新驱动程序必须严格遵循 Envelope v2。必须包含
detail（通常为null），特定技能的扩展项应放在其中；例如，design_candidates应为detail.design_candidates，而非根级键。 workflow-status为现有传感器使用方保留 Envelope v2。parseEnvelope()仍是兼容旧版的包 API；新使用方应使用parseEnvelopeV2Strict()或parseTurn()。SkillOutcome v1和WorkflowSnapshot v1是独立且经过版本管理的 JSON Schemas。对任何已发布契约进行破坏性更改，都必须升级包的主版本。
规范化仓库状态
驱动程序在规划前会调用 discover-repository-state，并保留冻结的
docs/workflow/REPOSITORY_STATE.md 引用。WorkflowSnapshot v1 会保留未知项、来源和已声明的矛盾；驱动程序会将矛盾交由 resolve-repository-state 处理，而不是默默替换矛盾内容。