loom-skill-enhancement

/loom-skill-enhancement

通过已发布的 Loom Skill Orchestrator（so）工作流，升级或创建正在增强的技能。交付增强后的技能是业务成果；运行时检查则是辅助证据。

必读内容

• 执行契约：运行时获取、文件和载荷规则、工作流标识、编译／运行／恢复、版本语义探测以及运行时模式。

• 运行时语义迁移：已验证的 0.3.282 发射器矩阵、生成方规则、gov4 可达性、迁移流程、恢复格式以及 Windows 工具限制。 仅阅读当前阶段所需的参考文档：

• 执行契约：运行时获取、文件和载荷规则、工作流标识、编译／运行／恢复、版本语义探测以及运行时模式。

• 审查与证据契约：指南资源、工作流设计、批量审查／修复、必需输出、审计交付以及完成证据。

• 通俗反馈：面向用户的必需措辞、术语映射和示例。

• SO 技能参考：精确运行时指南／架构／演示参考包及软件包行为。

• Mermaid 工件交付：已验证的四种工件输出处理方式，以及仅追加的单次执行进度日志。

• 共享术语规范：../../../docs/en/architecture/workflow-terminology.md。

运行时绑定

已发布的 AO 和 SO 运行时仅使用自包含的 product+RID 包。宿主 Agent 会确定当前操作系统、架构和 Linux libc，并选择且仅选择一个受支持的 RID。无需解析器可执行文件、启动描述符或已安装的 dotnet 主机。

MCP 为可选项，绝不会阻止包启动、获取指南或执行官方 CLI。完成全新的指南步骤之前，不要注册或检查 MCP。后续工作流步骤可以在 MCP 可用时使用它；其绑定来自正在运行的自包含 apphost 标识，而非描述符文件。调度后发生的 MCP 应用程序/工具故障仍属于故障，不得通过重试其他传输方式来掩盖。

• 当前已发布的 SO 包运行时版本：0.4.5。

• 每当 SO 包版本发生变化时，发布工作流都会刷新此区块，以确保技能约定与最新的稳定包集合保持一致。

• assets/so-workflow/so-package-lock.json 是精确版本的权威依据，也是已纳入版本控制的锁定参考目标。根据该版本推导发布渠道；不要让用户选择。

• 对绑定版本和检测到的 RID，仅使用 Techne.Loom.SkillOrchestrator.Runtime.<rid>。不要探测或选择 DLL/FDD 模式，也不要在技能已纳入版本控制的状态中持久化机器 RID 或 apphost 路径。

• 已发布版和测试版的包索引分别为 reference/packages.released.md 和 reference/packages.beta.md。

• 迁移脚本操作手册：路径安全的迁移入口、生产者边界、试运行行为和可重复的测试样例检查。

每轮增强都遵循以下引导流程：

1. 创建全新的外部工作流副本，并保留同一条 caseId/runId 链路。
2. 从锁定文件读取精确的包版本，推导其发布渠道，并检测宿主 RID。
3. 如果共享的当前用户操作系统临时目录缓存中存在完整验证且不可变的 AO/SO 代次，并且精确包 ID/版本/RID 及完整 .nupkg SHA-512 均匹配，则复用该代次。若未命中，先检查标准 NuGet 缓存，然后获取精确版本的包，并将其 SHA-512 与精确注册元数据进行比对；同版本 GitHub 回退方案必须具备 .sha512 旁车文件。
4. 在安全提取 apphost 和文档前，验证包 ID、版本、nuspec、RID、清单、入口点、归档大小和路径。暂存并验证新建或修复的代次后，再以原子方式发布；绝不覆盖其他有效或正在使用的代次。不要添加缓存锁、固定且已纳入版本控制的引导脚本、第二个解析器或描述符文件。如果宿主无法执行所需检查，则以具体的能力错误终止。
5. 在 Windows 上直接运行 so.exe --guide，在 Unix 上直接运行 so --guide。验证 JSON 版本、文档和指南的绝对路径、路径包含关系及可读性。使用这份全新指南，通过同一个 apphost 继续进行规划、编写、验证、编译、运行或恢复。

每轮增强都必须证明，精确锁定的已发布 SO 包 apphost 可运行，然后才能开展后续工作。

工作流流程

1. 将目标分类为新目标，或已纳入 Loom Skill Orchestrator 治理的目标；锁定要增强的技能所需的交付物。
2. 编辑要增强的技能交付物之前，先进入计划模式。首先将该技能的 SKILL.md 作为优先级 1 映射到 assets/so-workflow/node-to-file-map.md，其中包括其准确路径、所属节点、所需变更和验证证据；之后再映射支持文档。在 <execution-output-root>/plan/ 下构建范围受限的参考资料包和每次运行的计划。
3. 分析输入、输出、节点、分支、循环、所有权边界、门禁和具体证据生成方；将每个上下文路径与所属契约的 context_fields 目录核对，并确保类型化读取和输出投影与其 JSON 类型一致。对于每个新增或变更的字段，将其声明类型与独立的实际 SO 生成方输出或权威生成方架构进行比较，然后在现有静态审查中记录 contextFieldTypeComparisons。类型证据未知时，不得判定为就绪；停止，不得臆测后继续进行大范围测试。
4. 通过 assets/agents/loom-skill-enhancement-workflow-designer.agent.md 生成或修订工作流 JSON；JSON 是权威来源，Mermaid 仅用于展示。 在设计器调度上下文中加入指向英文和中文执行模型、JSON 契约、SO 行为、SO 工具和 CLI 用法页面的完整可点击链接。
5. 对于独立检查，构建一个共享的受限上下文，运行完整的外部 whenAllPass 批次，只聚合一次，只修复一次，并按审查契约中的说明重新验证。
6. 运行精确运行时编译。编译仅作为结构性证据。
7. 通过公开的 run 运行精确的外部工作流副本，并执行每个必需的 resume，直至最终状态为 Done。不得依据编译、受阻载荷、本地编排或其他工作流副本宣称已完成。
8. 验证目标交付物变更、事件／审计记录、输出系列值、Mermaid／HTML 路径以及完成清单。

选择性读取 JSON

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

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

对于增强运行的验证脚本和验证工作流步骤，执行以下默认要求：

• 设计时确保每次验证运行不超过 5 分钟。如果某项检查可能超过 5 分钟，则将其拆分为较小的独立验证。
• 验证步骤之间的内部延迟不得超过 5 秒。不得插入长时间休眠或手动间隔。
• 在不影响正确性的情况下，并行运行独立验证检查；仅在存在硬依赖时才串行运行。
• 每个并行验证批次结束后，只聚合一次，并且仅执行最低限度的串行最终检查。
• 如果平台限制导致无法满足这些要求，则安全失败，提供明确的阻塞证据，并给出具体的拆分／并行补救计划。

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

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

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

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

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

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

按阶段切分工作流的设计

仅统计编写的状态节点；不包括转换和合成的测试框架节点。编写的状态节点少于 40 个的工作流，继续使用完整工作流路径。工作流达到 40 个或更多编写的状态节点时，先创建独立的 loom.workflow-skeleton.v1 设计视图，冻结类型化导入／导出、入口／出口、依赖项、门控／终止节点归属、路由和回边，然后再编写隔离的各个阶段。每个阶段的编写状态节点以不超过 25 个为软性上限，并记录例外情况。新工作流使用 phaseSliced；迁移可明确混用 phaseSliced 和 legacy，但每个跨阶段读写仍须声明类型。

对 skeleton-check、phase-compile、impact、merge 和最终 compile 使用同一个选定的直接 SO apphost。阶段编译仅限静态分析，不得运行业务命令、HTTP、AskUser 或子 Agent。在中心统一汇总接口变更请求，更新骨架，运行 impact，并仅重新处理受影响的阶段及已证实的依赖阶段。归属或依赖关系不明确时，必须重新完整验证。每个阶段只合并一个通过的结果到新的候选文件中，并使用同一文件运行完整 SO 编译；绝不要修改活动工作流副本。

每个阶段最多进行 3 次修复尝试，合并后最多进行 2 轮完整编译修复。达到任一上限时，保留失败证据并请求明确决策。返回 phase_design_evidence，并将其关联到现有 static-contract-review.json 中的 phaseDesignEvidence；不要创建第四份报告。可选的支持性哈希不是新鲜度门槛。确切的软件包、语义探测、业务输出和发布检查仍然适用。

语义漂移门禁

运行时版本变更既是契约变更，也是执行语义变更。

• 在编辑目标或执行批处理之前，使用精确选定的运行时，运行最小三节点测试样例的继承版本和替换版本。替换版本必须到达最终状态 Done，且预期上下文值非空。
• 已发布的 0.3.282 矩阵针对特定发射器：普通 ToolCall/noop 上的字面量 updates 不生效；StateUpdate/MemoryWrite 会写入已声明的更新；真实的 echo/write-file 结果和经验证的外部恢复投影可以在探测后使用 $result。不得将已声明的 outputPath 或同一转换中的 $context 绑定当作自身有效性的证明。
• 对于生产者先于分支／循环消费者的情况，运行 gov4 探测。首次遍历时忽略 DFS 回边；拒绝仅在一个分支上存在生产者的汇合；将受治理和未受治理的数据流规则分开处理。记录未知行为，不要猜测。
• 对重复出现的目标模式，在迁移前运行幂等的试扫描。仅自动转换无歧义的 ToolCall/noop 字面量写入模式为 StateUpdate/state.update；报告含糊的绑定和未知发射器，不要凭空编造 $context 生产者。
• 每次规范恢复前，检查被阻塞转换的 requiredInputs。必需的同级字段必须保留在载荷顶层；只有声明的 resumeOutputKey 才会从载荷中投影出来。
• 最终验证必须返回非空的 runtime_semantic_probe_evidence、batch_migration_evidence 和 decision_evidence_manifest。

详细的测试样例、载荷、清单和证据要求见执行契约和运行时语义迁移参考。

命名 Agent 的解析

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

• 根据文件 frontmatter 中精确的 name 识别角色，而不是根据文件名识别。在本技能的 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）。若契约要求设计、编辑或验证，切勿使用 Explore 等只读 Agent；也不要用名称相似的角色替代。通过以下两种方式之一交付契约：
  • 内联：包含完整文件内容。
  • 仅路径：提供解析后的文件路径，不带哈希，并指示驱动 Agent 在行动前自行读取整个文件。驱动 Agent 必须先复述其读取到的 frontmatter name；如果无法读取文件，则必须停止。
• 每次子 Agent 调用（包括直接命名 Agent 调用）都必须包含文件声明的精确 name、指向同一 .agent.md 的可点击 Markdown 链接，以及所有必需输入和参考上下文；大型输入通过路径传递。仅提供名称或用摘要代替契约均不充分。
• 若 Agent 文件及输入内容较大，优先采用仅路径交付。请求大小错误、HTTP 408 或超时属于传输失败，而非 Agent 未注册：改用仅路径模式重试一次，并通过路径传递输入；若再次失败，则报告传输阻塞。
• 驱动 Agent 回退无需用户批准；这是正常操作。不要仅仅因为专用名称未注册就停下来询问用户。
• 仅当精确文件缺失或存在歧义，或不存在有能力的非只读驱动 Agent 时才停止。此时保留失败证据，报告具体阻塞原因，不要继续执行依赖检查。未经用户明确批准，不得在主对话中直接完成该角色的工作而不使用任何子 Agent 驱动。
• 记录每次分派：frontmatter 中的精确名称、.agent.md 链接、路径（direct 或 driver-fallback）、交付模式（inline 或 path-only）、触发回退的证据，以及驱动 Agent 复述的名称。

核心治理

• 工作流设计人员应以所选运行时的最新英文指南／架构／演示、同一 AppHost 的成功编译结果，以及版本匹配的英文技术文档为准；已翻译的公开文档仅用于本地化检查。工作流自有的架构和控制元数据使用英文；用户／业务负载和本地化呈现则保留其源语言／请求语言。
• 每个正在增强的技能都必须在其 SKILL.md 中包含上文定义的选择性 JSON 读取规则。要求现有的 Markdown 缺口审查器在修复前后均输出结构化的 selective_json_policy 判定，以及精确的 1 起始行号／引文证据；修复后的聚合仅接受判定通过且证据完整的结果。适用时，更新会直接检查大型 JSON 的目标本地 Agent 提示词或文档，并复用现有的审查、修复、验证和聚合节点，不得添加工作流节点。将 evidenceQuoteVerified 视为可信聚合器的证明，而非独立于运行时的证据：该路由假定指定的聚合结果可信，且不会阻止伪造的恢复负载。如果该信任边界不足以满足要求，必须进行独立验证；绝不可声称具备防伪能力。
• 面向用户的 SO 和每个正在增强的技能的进度、阻塞、错误和完成消息，必须使用当前交互语言中的通俗措辞。不得使用 FPx、xxx_preflight_xxx、节点 ID、关卡 ID 或内部字段名等仅供工作流内部使用的标签来解释；精确标识符仅可出现在技术细节或证据中。每个正在增强的技能还必须要求每次执行后的更新按顺序包含本地化的执行置信度和预计总体进度百分比标题，每项各附一条简短原因。置信度用于估计请求的工作成功完成的可能性；预计总体进度用于衡量整个请求的大致完成情况。两者都必须基于已验证的证据；这两个百分比均不能替代必需的交付物、证据关卡或最终的 Done。
• 每个正在增强的技能都必须保留既定的 AO/SO 报告格式：按 Mermaid、HTML、Analysis、Dataflow 的顺序提供四个 Markdown 链接，每个链接后紧接一个 text 代码围栏，其中包含完全相同且已验证的绝对文件 URL。使用规范化的 / 路径分隔符，并将空格编码为 %20；绝不可输出字面空格、原始 HTML 锚点、裸路径或以代码围栏替代链接。保留标签、字段、顺序和周边报告格式。如果文件不可用，应遵循交付失败指南，不得猜测。
• 将 /loom-skill-enhancement 及其创建或更新的每个技能的完整进度报告，按顺序逐份追加到 <execution-output-root>/progress-report.md；包含 ISO 8601 UTC 时间戳，以及带数字偏移量和 OS 时区 ID 的本地时间戳。追加失败时，保留先前日志，报告失败，并暂停后续业务步骤的推进，但不得更改运行时执行状态。遵循 Per-Execution Progress Log。
• 所有 CLI 文件输入都必须是完整、已关闭、仅含路径的文件。将可变计划、运行时副本、事件、审计输出和决策证据保存在技能包之外。
• 将增强运行的 plan/skill-plan.md 视为仅位于 <execution-output-root> 下的临时、限定于本次运行的文件。绝不可将其复制、移动、迁移或将其内容纳入正在增强的技能的 assets/、包、发行版或交付物中。运行时自有的上下文和完成证据只能保留其路径和哈希，不得保留其内容。
• AskUser 仅用于请求用户自有的决策或值。运行时自有的事实和工件路径应使用运行时自有的继续流程。
• 每个后续步骤都必须在同一外部副本上通过边界检查；跨所有者边界的步骤还必须获得明确批准或结构化继续授权。
• 对正在运行的工作流副本直接编辑，仅限于阻塞状态下、经明确批准且最小化的紧急变通操作，并且必须立即随后执行正常的 SO 编译／运行／恢复流程。
• 对每次子 Agent 调用，均应用 Named Agent Resolution 中的精确文件分派和完整内容回退流程：注明准确的 Agent 名称，并包含指向适用 .agent.md 的 Markdown 链接。要求每个正在增强的技能在其 SKILL.md 中发布此规则，并将其应用于每次调用；绝不可用近似匹配的角色替代。
• 将假设、更正、决策、探测结果、events.jsonl 和审计引用写入 <execution-output-root>/evidence/；对话文本不属于执行证据。

工件地址可用性

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

每次执行的进度日志

在收到来自 /loom-skill-enhancement 或其创建或更新的技能的每份执行后进度报告后，将完整的 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，也绝不手动追加或执行读取-修改-写入操作。要求此技能创建或更新的每个技能都调用同一个助手脚本。如果失败，请报告失败情况，并暂停后续业务步骤，不要更改运行时工作流状态。

稳定资产

• assets/so-workflow/so-template.json
• assets/so-workflow/so-package-lock.json
• assets/so-workflow/node-to-file-map.md
• assets/so-workflow/governance-notes.md
• assets/so-workflow/reference/document-copy-manifest.json
• 工作流设计器子 Agent：assets/agents/loom-skill-enhancement-workflow-designer.agent.md
• 获取指南后可选的 MCP 支持：assets/agents/loom-skill-enhancement-mcp-startup.agent.md
• 可复用的 weave-out 和审查子 Agent：
  • assets/agents/loom-skill-enhancement-skill-markdown-gap-review.agent.md
  • assets/agents/loom-skill-enhancement-package-lock-gap-review.agent.md
  • assets/agents/loom-skill-enhancement-workflow-governance-gap-review.agent.md
  • 重新增强策略审查器：assets/agents/loom-skill-enhancement-reenhancement-conflict-judgment.agent.md
  • assets/agents/loom-skill-enhancement-weave-out-subagent-fit-review.agent.md
  • assets/agents/loom-skill-enhancement-review-fix-loop.agent.md
  • assets/agents/loom-skill-enhancement-review-findings-aggregator.agent.md
  • assets/agents/loom-skill-enhancement-scope-input-output-analysis.agent.md
  • assets/agents/loom-skill-enhancement-route-gate-analysis.agent.md
  • assets/agents/loom-skill-enhancement-evidence-node-map-analysis.agent.md

完成

完成需满足以下所有条件：

• 已创建或修改所请求增强的技能文件；
• 精确锁定的 RID 软件包身份、哈希和归档检查、安全解压、直接启动 apphost，以及全新且可读的指南证据均已通过；MCP 为可选项，不是引导门槛；
• 精确运行时语义探测和批量迁移证据（如适用）均已通过；
• 一个工作流副本谱系已通过公开的 run/resume 到达最终的 Done；
• 审查、修复、修复后验证、边界检查、事件日志、审计产物和持久化决策证据均可读取；
• 运行时拥有的完成清单引用的是现有证据，而非对缺失证明进行自我认证。

软件包锁定元数据分为已检入的锁定引用目标、已解析的精确软件包版本／通道证据，以及运行时拥有的完成清单对已检入锁定资源的引用。已检入的技能 Markdown 治理结果同样包含运行时拥有的完成清单对该已检入源资源的引用。

完整的输出检查清单请参阅审查与证据契约，面向用户的完成或失败文本请参阅通俗语言契约。