loom-plan-execution

/loom-plan-execution

以指南为先的计划执行技能。

使命

此技能不会用自己的模板隐藏软件包设置步骤。它会先引导用户访问与当前由 CI/CD 管理的技能软件包版本块相匹配的软件包和指南页面，然后通过适用的 Loom Agent Plan-Execution Orchestrator 运行时页面执行。

选定与技能绑定的版本后，检测一个受支持的主机 RID，获取并验证对应的已发布 AO 自包含软件包，安全地解压，然后在 Windows 上直接运行 ao.exe --guide，或在 Unix 上直接运行 ao --guide。在规划或开展后续工作前，验证 JSON 版本和可读的内含 guide_path。软件包包含英文文档；应用主机中不嵌入指南页面。

如果调用方明确表示正在当前仓库中调试此技能，并要求使用当前源代码树，此技能可以构建并使用本地 Loom Agent Plan-Execution Orchestrator 仓库输出，而不是下载软件包资源。此本地源代码覆盖方式仅用于仓库调试，不会形成第二个官方执行权威。

此技能将 Loom Agent Plan-Execution Orchestrator 作为官方执行权威。只有在 Windows 上直接运行 ao.exe run/ao.exe resume，或在 Unix 上直接运行 ao run/ao resume，才算作官方技能运行。其他路径均不属于官方执行。

业务结果优先规则：如果调用方的请求或计划内容（例如 testplan.md）明确以业务执行产出为目标，此技能必须将该业务结果视为首要完成目标，不得偏离目标而只开展 AO 元执行活动。

请先阅读

• 共享术语权威来源：../../../docs/en/architecture/workflow-terminology.md（双语、人类易读的状态映射；在向用户展示任何内容前阅读）。

• 运行时绑定权威来源：此技能仅记录精确绑定的 AO 软件包版本。主机根据当前机器确定操作系统、架构、Linux libc、RID 和应用主机；不要将这些临时详情保存在已签入的技能状态中。

已发布运行时传输规则

已发布的 AO 执行使用其直接自包含的应用主机，且不需要 MCP。可选的 SO/MCP 支持属于后续的独立工作流事项；不得以此阻止 AO 软件包获取或指南捕获。已分发的 MCP 应用发生故障仍应视为失败。

命名 Agent 解析

此技能指定的每个 .agent.md 都是该角色的精确行为契约；宿主注册仅用于分发，不是能力门槛。

• 根据文件 frontmatter 中精确的 name 识别角色，而不是根据文件名。对于工作流设计师，该名称为 loom-plan-execution Workflow Designer。从此技能的 assets/agents/ 文件夹解析该文件；在独立安装中，则在当前技能根目录下解析相同的相对路径，例如 ~/.agents/skills/<skill-folder>/ 或 ~/.claude/skills/<skill-folder>/。优先使用当前仓库／工作区副本，其次使用匹配的全局已安装技能副本。
• 分发前预检：将该精确名称与宿主为子 Agent 调用提供的 Agent 列表进行比对。技能本地的 assets/agents/ 文件通常不会注册（VS Code 不会注册它们），因此若缺少该名称，应直接采用下方的驱动 Agent 路由；不要发起预计会失败的直接调用。
• 若该名称已注册，直接调用。遇到以下任一结果，都应视为未注册，并在同一步切换到驱动 Agent 路由：agent not found、未知 Agent 或无效 Agent 名称、子 Agent 工具没有 agentName（或等效）参数，或调用被默认 Agent 静默处理且该 Agent 未确认所声明的角色。
• 驱动 Agent 路由：调用一个可用且已注册的通用 Agent，该 Agent 必须能够编辑、运行命令并验证（在 VS Code 中，即省略 agentName 的默认 Agent）。当契约要求设计、编辑或验证时，切勿使用只读 Agent（例如 Explore），也不要用名称相似的角色替代。在分发请求中，注明精确的 frontmatter 名称，并提供指向精确 .agent.md 文件的可点击 Markdown 链接，然后通过以下两种方式之一交付契约：
  • 内联：包含完整文件内容。
  • 仅路径：提供已解析的文件路径，不带哈希，并指示驱动 Agent 在采取行动前自行阅读整个文件。驱动 Agent 必须先回显其读取到的 frontmatter name，若无法读取文件则必须停止。
• 两种交付方式都必须传递所有必需输入和参考上下文；大型输入应通过路径传递。不得只传递摘要来代替契约。
• 当 Agent 文件和输入较大时，优先采用仅路径交付。请求大小错误、HTTP 408 或超时属于传输故障，并非 Agent 未注册：以仅路径模式重试一次，并通过路径传递输入；若再次失败，则报告传输阻碍。
• 驱动 Agent 回退无需用户批准；这是正常操作。不要仅因专用名称未注册就暂停并询问用户。
• 仅当精确文件缺失或存在歧义，或没有具备相应能力的非只读驱动 Agent 时才停止。此时应保留失败证据，报告具体阻碍，不得声称已完成或继续依赖该工作的检查。若未通过任何子 Agent 驱动、而是在主对话中直接执行该角色的工作，则必须获得用户明确批准。
• 记录每次分发：精确的 frontmatter 名称、.agent.md 链接、路由（direct 或 driver-fallback）、交付方式（inline 或 path-only）、回退触发证据，以及驱动 Agent 回显的名称。

工作流文件语言

工作流定义文件是 Loom Skill Orchestrator 治理下 AO、SO 及正在增强的技能所共用的规范性英文信息载体。工作流自身拥有的架构键、节点和转换名称／描述、工作流阶段、表达式、提示、失败指引、证据引用及控制元数据均须保留为英文。用户／业务负载值及面向用户的本地化输出应使用其源语言或指定语言；本地化属于呈现层，不得更改工作流键或控制语义。

调用方文件准备约定

在调用 CLI 之前，调用方必须在磁盘上准备好完整的输入集，并关闭所有输入文件。对于 --script-file、--input-file、--base-workflow-file、--verify-script、--reference-workflow-file、--patch-content-file、--patch-target、--workflow-file、--objective-file、--context-file、--instance-file 和 --result-file，只能传入路径。

不要以内联方式传入脚本源码、JSON、补丁替换文本或参考内容。不要要求 CLI 或后续步骤创建缺失的输入文件，也不要修复之前未完整写入的文件。CLI 会在读取或写入前预检所有必需的输入文件。CLI 可以创建候选、验证和审计等目标文件。

选择性读取 JSON

对于大于 16 KiB（16,384 个 UTF-8 字节）的 JSON，默认采用选择性检查：仅使用搜索或正则表达式定位目标键或路径，然后读取有界的行窗口，并根据需要扩大范围。对于压缩格式的 JSON 或不安全的行切片，使用 JSON Pointer 或结构化解析器提取所需的子树。仅当用户明确要求，或整份文档验证需要时，才读取完整 JSON。此规则适用于 JSON 数据；.agent.md 角色约定仍须完整读取。

指南中心结构

权威 AO 指南页面位于 ../../../docs/en/guides/ 下，并会递归打包到运行时文档包中。提取后的包使用 guides/ao-guide.md 作为 --guide 入口，并包含相邻的 ao-guide-flow.md、ao-guide-reference.md 和 ao-guide-reference-<chapter>.md 页面。此技能不会发布任何 AO 指南文件；运行时获取请使用 reference/ao-skill-reference.md，版本特定的权威依据请使用新鲜提取的指南。

• 当前已发布 AO 包运行时版本：0.4.5。
• 每当 AO 包版本变更时，发布工作流都会刷新此区块，以使技能约定与最新发布的稳定包保持一致。

首先遵循当前技能包版本区块，然后据此确定相应的包内容：

• 包索引仍是技能本地参考。权威 AO 指南源为 ../../../docs/en/guides/ao-guide.md；提取后的运行时入口为 guides/ao-guide.md。目标本地 AO 副本是从精确绑定的运行时包中提取的完整包指南页面，可供本地检查，但绝不能取代新鲜发布的运行时 guide_path。

• 不要在此技能下添加或发布任何 AO 指南文件；请使用从精确锁定的包直接通过 ao.exe --guide 或 ao --guide 返回的新鲜指南。

• 工作流设计子 Agent：assets/agents/loom-plan-execution-workflow-designer.agent.md

• 用于增强 AO 的 Loom Skill Orchestrator 治理基准资产：

  • 每次运行的计划输出：<execution-output-root>/plan/skill-plan.md（由运行时管理；不是稳定的技能资产）
  • assets/so-workflow/so-template.json
  • assets/so-workflow/so-package-lock.json
  • assets/so-workflow/node-to-file-map.md

• assets/so-workflow/reference/ao/runtime-contracts.md

• assets/so-workflow/reference/ao/runtime-behavior.md

• assets/so-workflow/reference/document-copy-manifest.json

以通俗语言提供各种语言的反馈

此技能发出的所有面向用户的进度、阻塞、错误和完成情况更新，都必须使用用户指定的语言，让没有工作流背景的高中生也能看懂。英语不会自动变得通俗易懂，这条规则同样适用于所有受支持的语言。

使用简短的句子、常见的词语和直接的动词。按顺序说明四件事：发生了什么；用户的工作或数据是否仍然安全，或者哪些结果仍然有效；为什么会这样；接下来具体会做什么。

不要让读者去猜状态值、步骤类型、节点 ID、关卡名称、交接术语、运行时细节或审计术语的含义。必须使用某个技术词时，先用日常语言解释，再展示其准确名称。只有在有助于用户操作或验证结果时，才将命令、路径、ID 和负载字段放在单独的 Technical details 行中。面向用户的说明中绝不能使用 FPx、xxx_preflight_xxx、节点 ID、关卡 ID 或内部字段名等仅供工作流使用的标签；准确标识符只能放在技术细节或证据中。同样的规则以及下方的术语示例，适用于通过 AO 报告增强反馈的任何技能；对于正在增强的技能，说明中应包含这些规则的精简版本。

产物地址的可用性

每个产物地址都必须使用完整的本地文件 URL：Windows 使用 file://C:/...；Linux/macOS 使用 file:///...。请验证该 URL 能在当前主机上打开现有且可读的文件。如果文件 URL 无法打开，请在当前工作区中创建并验证一个副本，然后使用该副本的 URL。URL 中的每个空格都必须编码为 %20；可点击的 Markdown 链接和后续文本代码围栏中必须使用完全相同的编码 URL。绝不能返回含有字面空格的 URL、裸路径、截断或过期的 URL，也不能只提供代码围栏而不附链接。如果没有任何 URL 能打开，请报告交付受阻。

每次执行的进度日志

对于每条 AO 执行后进度报告，都要将完整的 Markdown 条目写入单独的外部文件。条目中必须包含 ISO 8601 格式的 UTC 时间戳和本地时间戳，以及数字形式的 UTC 偏移量和操作系统时区 ID。从仓库根目录调用平台辅助脚本，并使用绝对路径：Windows 使用 powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/AppendProgressReport.ps1 -TargetFile <execution-output-root>/progress-report.md -EntryFile <entry-file>；Linux/macOS 使用 bash scripts/AppendProgressReport.sh --target-file <execution-output-root>/progress-report.md --entry-file <entry-file>。辅助脚本只读取条目文件，并将其追加到目标文件。它会返回目标文件的完整 URL；如果要报告日志位置，请复用该 URL，不要更改。绝不能读取、打开或检查现有的 progress-report.md，也不能手动追加或以读取后再写入的方式修改文件。如果辅助脚本失败，请报告失败，并暂停后续业务步骤，不要更改工作流状态。

通俗语言术语示例

左栏用于机器记录。右栏说明了面向用户时应表达的含义。这些英文句子仅作示例，不是固定输出：请用用户指定的语言表达相同含义。在其他地区使用英语，并不等于使用了通俗易懂的语言。

内部措辞	用用户的语言这样表达
Done	“请求的工作已完成。”
WaitResume	“我需要您提供信息或确认，才能继续。”
SubagentCall	“有专人正在检查这部分内容。”
gate	“有一项必要检查尚未通过。”
transition	“下一步将……”
seam 或 boundary	“工作正等待交接。”
frontier	“有几个可选的后续操作。”
runtime	“正在运行任务的程序”
render unchanged	“先前的示意图仍然有效；无需绘制新图。”

示例：输出文件夹中已有记录

内部备注：step-0008-compiled 已存在；渲染结果未变。

面向用户的更新：“任务本身没有问题。输出文件夹中已有之前的记录，因此本次运行没有覆盖它。之前的图表和报告仍然有效。我会使用一个新的输出文件夹，并继续执行同一已保存的运行。”

示例：审核发现尚未解决的问题

内部备注：审核返回了四项问题，但在分类和修复之前，就声称已通过审核检查。

面向用户的更新：“审核发现了四个问题。流程过早停止，因为它把审核当作已完成，而没有检查这些问题是否已修复。我会对这四个问题进行分类并修复，然后再次检查。”

示例：等待用户决定

内部备注：任务正停在等待用户输入的步骤。

面向用户的更新：“继续之前，我需要你做出一项决定：[用一句简短的话说明需要做出的决定]。”

不要将内部备注复制到面向用户的更新中。如需采取操作或进行验证，请将准确的命令、路径、ID 和证据字段放在单独的 Technical details 部分中。

输入约定

• 首选输入：至少包含 10 行非空内容的详细计划
• 备用输入：详细计划文档的文件路径
• 运行时版本依据：当前由 CI/CD 管理的技能包版本块；需要时，根据该绑定版本判断 released 或 beta
• 指南输入：在 Windows 上直接运行 ao.exe --guide，在 Unix 上直接运行 ao --guide；指南仅提供英文，并以 JSON 格式返回 version、docs_root 和 guide_path。
• 可选输入：运行时源模式（默认为 package-channel；调试当前仓库中的此技能并有意使用当前源代码输出时，可显式指定 repo-src-debug）
• 可选输入：显式指定审核输出根目录

如果请求过于简短，请引导用户进入计划模式，或要求用户在继续之前提供详细的计划文件。

默认假设

在基于 Loom Agent Plan-Execution Orchestrator 的计划执行过程中应用以下默认值：

• Loom Agent Plan-Execution Orchestrator 是此技能唯一的官方执行授权；官方运行在 Windows 上使用直接 ao.exe run/ao.exe resume，在 Unix 上使用 ao run/ao resume。
• 当计划内容明显面向业务交付物时，必须优先考虑业务成果；仅运行时/元数据模式需要用户明确提出。
• 官方 AO 运行时使用此技能提供的确切版本，以及主机选定的单个产品+RID 包。不支持探测主机、DLL 闭包、第二种运行时模式或跨模式回退。
• 在 Windows PowerShell 5.1 的包通道模式中，将 .nupkg 视为 ZIP 内容，不要直接对 .nupkg 使用 Expand-Archive；请使用 ZIP API 或等效的基于 ZIP 的提取方式。
• 在 Windows PowerShell 5.1 中，对使用 Invoke-WebRequest 或 Invoke-RestMethod 的包通道 HTTP 探测添加 -UseBasicParsing，避免运行时获取过程卡在旧版浏览器引擎提示上。
• 如果包验证、提取、apphost 启动或指南执行失败，请停止并保留失败证据。绝不要根据 stderr 记录成功；仅保留成功的 JSON 结果，以及直接 apphost 返回的可读 guide_path。
• 在 repo-src-debug 模式下，仅将当前仓库的 Loom Agent Plan-Execution Orchestrator 构建输出用作明确的调试覆盖。
• 保持已签入的源计划/快照不可变，并将可变运行时状态保存在同一个外部工作流文件或明确的执行输出根目录中。
• 将有效的工作流、模板、架构、演示、运行时副本、审计备份和编译反馈 JSON 输出写为缩进的多行 JSON。仅在 JSONL、MCP/CLI 线载荷和明确的规范哈希投影中使用紧凑 JSON。
• 输出目标可以位于 Git 工作树之外，也可以被 Git 忽略。返回规范化后的真实路径，验证每个输出都存在且可读；当 --workspace-root 可用时，使用经过验证的工作区相对镜像以便直接在编辑器中打开；Git 跟踪绝不是交付条件。
• 每次 AO apphost 调用或生成审计的步骤之后（包括 ao.exe 和 ao 调用），都遵循 Mermaid 工件交付：验证实际返回的审计路径及其可读性，然后开始边思考边说明的更新，按顺序提供经过验证的 Mermaid、HTML、Analysis 和 Dataflow Markdown 链接与 text 代码围栏配对。每个标题都必须链接到完整的绝对已验证运行时文件地址（Windows 驱动器路径或 Unix 绝对路径），并规范化为 /；标题后须立即跟随一个 text 代码围栏，其正文只能包含完全相同的完整地址。绝不能使用工作区相对地址、缩短、截断、省略或在代码围栏内添加标签/说明。保持此配对格式和工件顺序不变。如果文件未生成或未验证，则遵循交付失败/连续性规则，不得编造其地址。代码围栏之后，按顺序使用本地化的 ## 标题说明执行信心和预计总体进度，每项附上一条简短理由。信心用于估计所请求的工作成功完成的可能性；预计总体进度用于衡量整个请求的大致完成程度。两者都必须依据已验证的证据；不要求固定公式或阈值，且百分比不能替代必需的完成检查。仅使用当前或最近一次已验证的路径；遇到 not_emitted 时，说明渲染未改变；遇到 delivery_failed 时，报告失败和下一步操作，不要提供链接或重复使用路径。面向用户的文本须保持纯文本，并使用当前交互语言。
• 对于 runtime_path_only，在固定工件报告中包含完整的已验证绝对地址。仅当 link_resolvable=true 时，才在单独的主机/编辑器打开操作中使用已验证的工作区镜像；不要替换或省略报告中的地址。 AO 仅支持 CLI。直接执行提取出的 AO apphost；指南、编译、运行或恢复均不需要动态 MCP 注册、运行时描述符或 MCP 预检。
• 对此技能本身的每次完整交付执行而言，直接编译 apphost 仅用于验证，并非最终状态。
• 完成指南交接和编译验证后，使用一个全新的外部运行时工作流副本。对该副本运行同一个 apphost，然后在直至终止完成的每次恢复中，都使用该 apphost 和持久化状态。
• 如果运行时返回阻塞状态，保留其证据并恢复同一个工作流副本。继续执行，直至终止完成或记录明确的不可恢复故障；仅有阻塞载荷绝不算完成。
• 切勿将本地编排、直接脚本、仓库调试输出、指南成功、提示词规划、编译成功或未恢复的阻塞状态宣称为受治理的完成。
• 如果已发布的 apphost 无法启动，保留失败的打包和启动证据并停止。不得替换为本地或辅助执行路径。

详细假设、启动契约、输出矩阵和防漂移规则见参考文档：

• 本地技能参考：reference/ao-skill-reference.md

此技能的工作流生成或修订必须使用本地工作流设计器子 Agent，并提供上下文丰富的相对链接，不得使用自由形式的通用 Agent 调用：

• assets/agents/loom-plan-execution-workflow-designer.agent.md

使用该工作流设计器路径时，必须遵循确定性的工作流编写契约，而非仅具描述性的文本：

• 每个转换都必须声明结构化、可执行的 guardExpression 和规范的 passExpression 谓词，明确的证据输出以及明确的接缝归属；succeedExpression 是需要迁移的旧版输入，不应作为字段编写
• 每条上下文路径都必须在所属契约的 context_fields 目录中声明；每个 context.Get<T>(path) 类型以及每个生产者／输出投影都必须与声明的 JSON 类型一致；仅检查是否存在时使用 context.Has(path)
• 首先将要增强技能的 SKILL.md 映射为 assets/so-workflow/node-to-file-map.md 中的优先级 1 项；在支持文件之前，纳入其精确的目标相对路径、所属节点、请求的更改和验证证据。
• 对于每个新增或更改的 context_fields 条目，都必须将声明类型与独立的实际 AO 生产者输出或权威生产者架构进行比较。在 static-contract-review.json 中记录 contextFieldTypeComparisons；类型证据未知时，必须在大规模测试前阻止就绪判定。
• 每个关卡都必须声明可由机器检查的通过谓词、必需的证据引用和路由覆盖映射
• 编织退出提示必须保留恢复连续性契约字段以及预期的载荷／证据形状
• 最终工作流提案必须包含转换、关卡和归属预检清单，之后才能接受 JSON 输出
• 失败时默认关闭：拒绝缺少具体谓词或证据路径的含糊转换／关卡表述

该 .agent.md 文件是工作流设计器子 Agent 的权威行为来源。使用前，不得要求将其镜像到 .github/agents/、用户配置文件的 Agent 文件夹或任何其他可发现的 Agent 根目录。仅通过 具名 Agent 解析 分派该文件：先预检宿主 Agent 列表；若已注册，则调用精确的 frontmatter 名称；否则使用驱动程序路径，并以内联或仅路径方式交付。驱动程序回退无需用户批准。不得将此路径替换为自由形式的近似 Agent 角色。

工作流设计器参考包

在调度 assets/agents/loom-plan-execution-workflow-designer.agent.md 之前，调用方必须提供范围明确的 referencePackManifest，以及来自同一 AO 运行时的最新 schemaDemoInput。参考包必须包含成功的指南 JSON 和返回的指南文件、来自同一运行时的 schema/demo/demo 编译审计、当前目标合同和需求、当前工作流源文件、适用的 AGENTS.md，以及修订时的最新编译反馈。每个条目都必须包含规范化路径、SHA-256、确切的运行时版本、权威角色、读取状态和验证结果。较旧的工作流仅作为 previous_runnable_reference，并且需要注明版本、哈希、差异及拒绝项的处理方式。

在调度上下文中包含以下完整且可点击的文档参考，并将其视为执行和恢复行为的适用权威依据：执行模型（英文）、执行模型（简体中文）、JSON 合同（英文）、JSON 合同（简体中文）、AO 行为（英文）、AO 行为（简体中文）、SO 行为（英文）和 SO 行为（简体中文）。

设计器必须在运行时拥有的 <execution-output-root>/workflow-design/ 下返回 reference-manifest.json、static-contract-review.json 和 semantic-probe-report.json，其 schema 版本分别为 workflow-designer.reference-manifest.v1、workflow-designer.static-contract-review.v1 和 workflow-designer.semantic-probe-report.v1。保留包含路径、SHA-256、schemaVersion、verdict 和确切运行时版本的描述符。必需的语义探测若失败或状态未知，则无法判定为就绪；仅编译成功不能作为语义证据。

分阶段工作流设计

仅统计编写的状态节点；不包括转换和合成的测试框架节点。编写的状态节点少于 40 个的工作流采用整体工作流路线。工作流有 40 个或更多编写的状态节点时，先创建独立的 loom.workflow-skeleton.v1 设计视图，冻结类型化接口和跨阶段路由，然后再编写隔离的阶段片段。每个阶段最多保留 25 个编写的状态节点作为软上限，并记录例外。新工作流使用 phaseSliced；迁移可明确混用 phaseSliced 和 legacy，但必须声明并类型化每个跨阶段读写。

对 skeleton-check、phase-compile、impact、merge 和最终的 compile，使用同一个选定的直接 AO apphost。阶段编译仅执行静态检查。在中央汇总接口变更请求，修订骨架，运行 impact，然后仅重做受影响阶段及已证实的依赖阶段；影响未知时必须进行完整重新验证。将每个阶段恰好一个通过的结果合并到新的候选文件中，然后要求对该确切文件执行完整 AO 编译及其审计。绝不修改活动运行时工作流副本。

每个阶段最多允许三次修复尝试，合并后最多允许两轮完整编译修复。达到任一上限时，保留证据并请求明确决策，不得默默重试。返回与现有 static-contract-review.json 中 phaseDesignEvidence 关联的 phase_design_evidence；不要创建第四份报告。可选支持哈希不是新鲜度门槛。包完整性和必需的业务输出哈希检查保持不变。

skeleton-check --workflow-file <path> --skeleton-file <path>
phase-compile --workflow-file <path> --skeleton-file <path> --fragment-file <path> --phase-id <id> --output-file <path>
impact --previous-workflow-file <path> --previous-skeleton-file <path> --candidate-workflow-file <path> --candidate-skeleton-file <path> --output-file <path>
merge --workflow-file <path> --skeleton-file <path> --result-file <path>... --output-file <path>

独立运行时契约

软件包渠道只有一条运行时路径：适用于当前主机的准确 AO 产品 + RID 软件包。

• 根据操作系统、架构和 Linux libc 精确检测一个受支持的 RID。使用技能绑定的准确 AO 版本。
• 仅当共享的当前用户操作系统临时 AO/SO 缓存中存在不可变代，并且其准确软件包 ID、版本、RID 与完整验证过的 .nupkg SHA-512 均匹配时，才可复用。未命中时，先检查标准 NuGet 全局软件包缓存，再获取准确的软件包，并根据 catalogEntry.packageHash 验证其字节；同版本 GitHub Release 回退方案必须带有有效的 .sha512 旁文件。
• 解压前，验证软件包 ID、准确版本、RID、SHA-512、nuspec、runtime.json、归档路径与大小、apphost 和英文指南文件。只有所有检查都通过后才解压。
• 解压后立即在 Windows 上运行 ao.exe --guide，或在 Unix 上运行 ao --guide。在后续工作前验证其版本和可读取的包含路径。
• schema/demo、编译、运行和恢复均使用同一个已解压的 apphost。软件包、解压、启动或指南检查失败时，必须安全失败。
• 不要求已安装的 .NET 主机、DLL 模式、运行时解析器、启动描述符或固定引导脚本。允许使用共享的 AO/SO 缓存；不要添加缓存锁。

运行时流程

0. 首先对意图进行分类：业务执行还是明确的运行时验证。如果目标明确要求交付业务成果，则锁定为业务优先模式。
1. 确认当前技能绑定的包版本；必要时根据版本格式推导发布通道，并确认运行时来源（package-channel 或显式的 repo-src-debug）。
2. 准备运行时：
   • repo-src-debug：从 src/dotnet/Techne.Loom.AgentOrchestrator 构建 Loom Agent Plan-Execution Orchestrator。
   • package-channel：获取并验证精确的 AO 产品 + RID 包，在技能文件夹之外安全解压，然后运行其直接 apphost 的 --guide。不使用 DLL、Roslyn 包、生成的 .deps.json 或框架启动约定。
3. 证明选定的运行时能够运行不带参数的 --guide 命令，解析其 JSON 结果，并在继续之前读取返回的 guide_path 和 docs_root。
4. 仅在获得该指南结果后，才运行规划入口（prompt-plan）并捕获所需的提示词块。
5. 创建或修订工作流时，调用本地 workflow-designer 子 Agent，并通过相对链接向其提供相关技能文件、指南文件、计划文件和审计产物。
6. 在技能路径之外生成一份外部 WorkflowInstance 副本，记录其不可变的实例标识和持久化运行时状态 / 会话路径，然后针对该副本运行 compile。
7. 使用同一份外部 WorkflowInstance 副本运行 Loom Agent Plan-Execution Orchestrator；之后的每次 resume 都必须复用其持久化运行时状态。
8. 遇到阻塞状态时，根据负载信号并使用 prompt-replan 更新衔接节点，然后通过结构化信封负载执行 resume。
9. 确认当前路径受阻时，在请求 AO 规划器重新规划之前，持久化当前工作流状态、阻塞报告、所有已尝试补救措施及其结果，以及相关事件 / 审计引用。
10. 根据保留的历史记录重新规划，并选择明确的策略：从当前状态继续、回退到未经确认的设计节点、从当前状态重新设计、替换整个计划，或采用影响最小且可逆的变通方案。
11. 恢复执行前，要求规划器提供通往最终业务结果的可行路径；如果选择了回滚或变通方案，路径中也必须包含相应方案。
12. 重复重新规划 / 恢复执行，直到 Loom Agent Plan-Execution Orchestrator 达到已完成状态。
13. 仅当 Loom Agent Plan-Execution Orchestrator 已完成，且所请求的业务交付成果可验证时，才报告完成。

对于 AO 工作流设计和 AO weave-out 规划，如果现有的合适子 Agent 已能完成 weave-out 目标，则优先使用它们，而不是生成通用 Agent 占位符。

提示词块、负载约定和阻塞状态处理的操作细节见参考文档。

验证运行时效率约定（必需）

对于规划器编写的验证工作流脚本和验证步骤，以下限值必须作为硬性默认要求执行：

• 每次验证运行都应保持精简且能收敛；目标是在 5 分钟内完成。如果某项验证预计会超过 5 分钟，则将其拆分为更小的独立验证。
• 步骤之间的内部空闲延迟不得超过 5 秒。不要在验证步骤之间加入人为等待、长时间休眠或手动设置的间隔。
• 在不影响正确性的前提下，并行运行相互独立的验证工作，仅将有依赖关系的检查按顺序执行。
• 每批并行验证结果汇总一次，然后继续执行所需的最少串行检查。
• 如果主机限制导致无法满足这些限值，则应安全失败，明确提供阻塞证据，并返回具体的拆分或并行化修复计划。

自动轮询计时规则（必需）

对于自动就绪状态轮询，在支持立即检查时，应立即检查，并从最短的有效间隔开始。只有在记录到 pending 或 not-ready 结果，表明当前等待时间不足以完成验证后，才增加下一次等待时间；每次重试恰好增加 1 秒。不要使用指数退避，也不要在没有观察到证据时增加等待时间。

验证步骤之间的每次空闲等待不得超过 5 秒，并保留现有操作和会话的截止时间。如果在 5 秒上限时检查结果仍未就绪，只能继续使用现有运行时截止时间，或报告阻碍因素；不要延长运行时截止时间。此轮询规则不会缩短等待人工响应的时间。

AO/SO AskUser 测试隔离（必需）

当验证工作流通过 AO 或 SO 测试 AskUser 行为时：

• 对于 apphost 集成测试或端到端测试，直接通过本次运行所选运行时的规范化绝对 apphost 路径调用该运行时。记录其准确版本、可执行文件路径和工作目录。在 package-channel 模式下使用准确的包 apphost；仅在明确进行仓库调试时使用当前源代码的输出，并将该证据标记为仅供开发使用。不要仅通过 PATH 查找可执行文件，也不要静默替换为 DLL／项目输出。
• 为每个测试通道的契约文件、AskUser 存储／会话数据、工作流副本、事件／日志记录和审计输出指定唯一的外部根目录。仅使用有文档说明或受测试支持的存储根目录控制项，并验证解析后的路径。如果无法隔离存储，则串行执行受影响的测试，不要共享可变状态。
• 为每个同时运行的工作线程／测试通道分配一个由操作系统分配的临时环回端口。仅使用 AO/SO 返回的端点，并断言同时运行的并行通道使用不同端口。绝不要硬编码或重复使用固定端口，也不要臆造端口选择 CLI 标志。
• 保密配对令牌和完整路由 URL；仅将运行时返回的已批准端点传递给浏览器功能。

必需输出

• 已确认绑定的运行时版本，并提供推导出的正式版／Beta 版证据及对应的规范链接
• 运行时源选择，以及由版本推导的渠道解析元数据
• 软件包渠道的运行时证据：准确的软件包 ID／版本／RID、源、已验证的 SHA-512、nuspec／清单／存档检查、提取结果、apphost 路径，以及最新的指南结果
• 涉及 Windows PowerShell 5.1 时的软件包渠道运行时获取事实：基于 ZIP 的 .nupkg 提取路径、HTTP 探测模式，以及提取或指南生成失败时的快速失败证据
• 工作流／会话／事件路径及审计产物链接
• 每次子 Agent 调用的命名 Agent 调度记录：准确的 frontmatter 名称、.agent.md 链接、路由（direct 或 driver-fallback）、交付模式（inline 或 path-only）、回退触发证据，以及驱动程序回显的名称
• workflow.compile-feedback.json 和共享的 workflow.compile-feedback.v1 结果，包括解析／验证状态、计数、阶段阻塞项、候选路径／哈希，以及 AO 运行时身份／版本
• 所有输出产物的已验证实际路径，包括 Git 工作树之外或位于被忽略的工作区镜像中的工作流、反馈、审计、Mermaid 和 HTML 文件
• 指南中心、流程和参考路径，并将固定的 guide_path 指南中心保持在 200 行以内
• 运行时和审计更新所需的思维过程字段
• 每次调用 AO apphost 或执行会生成审计记录的步骤后（包括 ao.exe 和 ao 调用），均须遵循 Mermaid 产物交付：验证实际返回的审计路径及其可读性，然后开始思维过程更新，并按顺序提供 Mermaid、HTML、Analysis 和 Dataflow 的 Markdown 链接加 text 代码围栏。每个标题都必须链接到已验证运行时文件的完整绝对地址（Windows 驱动器路径或 Unix 绝对路径），并规范化为使用 /；其后立即跟随一个 text 代码围栏，正文只能包含完全相同的完整地址。必须保留此精确配对格式和产物顺序。不得使用工作区相对地址，不得缩短、截断、省略地址，也不得在围栏中添加标签或说明。如果文件未生成或未验证，则应用交付失败／连续性规则，不得编造地址。之后按顺序提供本地化的 ## 标题“执行信心”和“预计整体进度”，每个标题下给出一句简短理由。信心用于估计请求工作成功完成的可能性；预计整体进度用于估算整个请求的大致完成程度。两者均须基于已验证证据；没有固定公式或阈值，且任何百分比都不能替代必需的完成检查。面向用户的文字须保持纯文本，并使用当前交互语言。仅使用当前或最新的已验证路径；若为 not_emitted，说明渲染内容未变；若为 delivery_failed，报告失败及后续操作，不得提供链接或重复使用旧链接。
• 适用业务优先模式时，提供业务交付物验证摘要
• 对于 runtime_path_only，在固定产物报告中包含完整的已验证绝对地址。仅当 link_resolvable=true 时，才可将已验证的工作区镜像用于单独的主机／编辑器打开操作；不得用其替代或省略报告中的地址。

完整的输出矩阵和字段级约定请参阅参考文档。

禁止的结果

拒绝或标记以下任何执行结果为无效，如果该结果声称或暗示：

• AO 并非官方技能执行的必需项
• AO 和另一条路径是此技能并行的官方执行模式
• 调用方明确要求业务输出时，仅凭 AO 运行时产物就可以视为最终完成
• 未经用户明确批准，业务输出请求被悄然降级为仅运行时／元数据执行
• compile、--guide 或辅助 shell 步骤是常规技能运行模式
• compile、--guide、prompt-plan、prompt-replan 或辅助 shell 步骤是常规技能运行模式
• 非 AO 输出可计为官方技能执行历史
• 非 AO 测试可计为官方技能执行证据
• 仅凭说明文字的流程或示例就具有官方执行权威性

完成标准

只有满足以下所有条件，才能认定执行受到妥善管控：

• 只有在 Windows 上直接运行 ao.exe run／ao.exe resume，或在 Unix 上直接运行 ao run／ao resume，才算官方技能运行
• 直接 apphost compile、--guide、prompt-plan 和 prompt-replan 仅用于准备或验证
• 技能级历史只能来自 AO 工作流状态、会话状态、事件日志或审计产物
• 阻塞历史必须保留被阻塞的节点、阻塞原因、尝试过的操作、结果、证据引用，以及选定的重新规划锚点／策略
• 规划器必须将保留的历史作为输入，且不得悄然丢弃失败的尝试或先前的路径决策
• 重新规划若未声明从所选锚点到最终业务结果的路径，并为任何变通方案保留一步回滚计划，则无效
• 技能级检查清单只能来自 AO 工作流节点、前沿、转换、阻塞状态和恢复点
• 技能级运行映射只能来自 AO 运行时的 workflow_file、next_frontier、阻塞状态和审计产物
• 技能级证据只能来自 AO 所有的运行时状态和审计产物
• 非 AO 测试不计为官方技能执行证据
• 说明文字中的流程和辅助命令示例仅用于解释，不具有执行权威性
• 当调用方的目标明确要求业务输出时，仅有 AO 完成状态并不足够，还必须提供相应的业务交付物

详细的禁止／验收示例请参阅参考文档。