OpenSquilla 元技能迁移缺口（精简版）

本文档仅保留“未完成迁移缺口”与“验收口径”，用于 P1/P2 跟踪。

当前结论（2026-06-14）#

• 元技能基础能力已可用：DAG 编排、llm_classify、user_input pause/resume、final_text_mode、结构化结果。
• P1 中 meta-runs operator 基线已完成并升级：在保留 session 维度入口（meta-runs <session-id> ...）兼容性的同时，新增了全局视图 meta-runs list/show/failures。
• proposal lifecycle/provenance 已完成域层闭环（durable LearningProposal + snapshot/history additive 输出）。
• skill_exec 已具备 stdin 执行、evidence 持久化与 replay/reconstruct machine-readable 契约。
• P2-1 并行 step 调度已完成：当前并发语义为独立 ready tool_call steps 的波次并发（子集并行），且 Agent/MAF 双实现已回归通过。
• 本次补齐了最关键的 meta 语义收口：MetaSkill 不能 compose MetaSkill、skip_if clarify 语义落点、以及 meta 专属 risk/capabilities 门禁。

逐项验收表#

说明：本表用于把 OpenSquilla 的用户/作者文档要求，与 OpenClaw 当前实现逐项对齐。

严格版迁移结论#

• 口径说明（上游要求 vs 本地增强）：本表中的“已完成”表示已满足 OpenSquilla 文档的能力目标；若上游未强制实现形态（例如是否采用独立 durable workflow 对象、是否提供 structured final text mode），则按 OpenClaw 的增强实现计入，不将其表述为上游硬规范。
• 运行时主链路已完成迁移：DAG、路由、失败替代、pause/resume、skill_exec、risk/capabilities 门禁与审计证据主路径均可用。
• 运维/产品命令面已完成当前同构目标：在保留 session 维度 meta-runs 入口的前提下，已补齐全局 runs 视图命令（list/show/steps/failures）与稳定 meta catalog 产品入口，并支持失败窗口过滤。
• 治理门禁已完成 profile 对齐：proposal 接受前统一质量门禁已在 accept/change --to accept 落地 opensquilla-authoring-v1 结构化 profile，覆盖 structure/trigger/runtime/safety 分组检查，且 machine-readable 失败契约已携带 gate profile 与失败检查列表。
• 治理 review workflow object 缺口已关闭：已引入独立 durable 对象 meta_run_review_workflow（LearningModels.cs），采用 durable id meta-run-workflow:<session>:<proposal>（SkillCommands.cs, SkillCommands.cs），在 lifecycle mutation 进行 upsert 且在 show/mutation 输出中 hydration additive workflow section（SkillCommands.cs, SkillCommands.cs, Session.cs）。拒绝/冲突路径不推进 transition_count 的 non-drift 回归已覆盖（SkillCommandsTests.cs, SkillCommandsTests.cs）。

最关键的 3 个收口#

• MetaSkill 不能 compose MetaSkill 的硬禁已经收口。

  运行时预检会拒绝 meta->meta composition，Agent/MAF 双路径都已覆盖回归，错误信息也已明确指出 meta->meta nesting 被拒绝。

• skip_if 这类 clarify 语义已经收口。

  skip_if 已进入 clarify schema，并在运行时用于跳过用户提示；Agent/MAF 两条路径都能在 skip 条件命中时继续执行而不落 checkpoint。

• risk / capabilities 的 meta 专属门禁已经收口。

  meta skill 加载阶段会按配置门禁筛掉不满足风险/能力要求的技能，SkillLoader.LoadAll 会保留普通技能，同时过滤掉不满足 meta policy 的 meta skill。

已完成范围（简表）#

剩余迁移缺口（按优先级）#

P2（能力增强，不阻塞基础迁移）#

• proposal 接受门禁 profile 对齐项已完成，剩余工作转向覆盖率扩展

  现状：accept/change --to accept 已使用 opensquilla-authoring-v1 结构化 profile 执行分组检查，并在 JSON 失败契约输出 gate profile 与 failed checks；成功路径会持久化门禁快照元数据。

  剩余：继续扩展失败/越权/冲突组合链路的 E2E 覆盖密度，提升长期治理置信度。

• creator 质量门禁深度基本补齐

  现状：已具备 proposalDraft.quality、分级建议字段与阻断型阈值；skills create --proposal-draft 在低质量草稿上会返回 machine-readable proposal_draft_quality_gate_failed。

  仍可继续增强：如果后续要引入更细的门禁策略，可以再细分阻断项/警告项层级与 creator 分类规则。

• 产品层 E2E 验收口径继续扩展中

  现状：已完成 create -> proposal -> lifecycle -> audit 验收切片，并补入权限失败分支、双向冲突分支（dismiss 后 accept 冲突、accept 后 dismiss 冲突）与 invalid_lifecycle_transition 分支；失败分支已校验 JSON 错误契约（status/command/errorCode/message），并覆盖失败后 lifecycle/audit/provenance 不漂移；仍可继续覆盖更多失败/越权/冲突场景，提升长期治理信心。

  建议：在现有切片基础上继续补充失败与授权边界链路的端到端回归。

P2 实施任务单（可直接开工）#

Task C：并行 step 调度（P2-1）#

状态：已完成（2026-06-14）

目标：在不破坏 DAG 语义和现有 pause/resume 行为的前提下，让独立 ready steps 并发执行。

建议改动文件：

• src/OpenClaw.Agent/AgentRuntime.cs
• src/OpenClaw.MicrosoftAgentFrameworkAdapter/MafAgentRuntime.cs
• src/OpenClaw.Tests/AgentRuntimeTests.cs
• src/OpenClaw.Tests/MafAdapterTests.cs

实施要点（TDD）：

1. RED：新增并发红测，验证两个互不依赖 tool_call steps 能并行（MaxConcurrent >= 2）。
2. GREEN：在 meta 执行循环中加入 ready-set 波次调度，对“无路由副作用、无失败分支依赖”的独立 steps 并发执行。
3. REFACTOR：统一 Agent/MAF 两条实现路径的并行判定与结果归并规则，保持错误码与 structured 输出兼容。

验收测试（建议最小切片）：

• dotnet test src/OpenClaw.Tests/OpenClaw.Tests.csproj --filter "FullyQualifiedName~ExecuteMetaSkillAsync_IndependentToolSteps_RunConcurrently|FullyQualifiedName~MafAgentRuntime_ExecuteMetaSkillAsync_IndependentToolSteps_RunConcurrently"
• dotnet test src/OpenClaw.Tests/OpenClaw.Tests.csproj --filter "FullyQualifiedName~ExecuteMetaSkillAsync_|FullyQualifiedName~MafAgentRuntime_ExecuteMetaSkillAsync_"

DoD：

• 独立 steps 在运行证据上可观测到并发执行。
• depends_on、route、on_failure、user_input 语义与现有契约保持兼容。
• replay/reconstruct/proposals 相关回归不退化。

完成证据：

• 新增回归：ExecuteMetaSkillAsync_IndependentToolSteps_RunConcurrently
• 新增回归：MafAgentRuntime_ExecuteMetaSkillAsync_IndependentToolSteps_RunConcurrently
• 切片回归：FullyQualifiedName~ExecuteMetaSkillAsync_|FullyQualifiedName~MafAgentRuntime_ExecuteMetaSkillAsync_（通过）

风险控制：

• 并发只覆盖可证明独立的 ready steps，避免扩大到有路由副作用分支。
• 失败传播策略保持现有错误码与文本契约，避免 CLI/operator 侧回归。

Task D：产品级 MetaSkill catalog / creator / proposal flow（P2-2）#

目标：补齐产品层工作流能力（catalog 发现、creator 生成、proposal 评审入口），与 runtime 核心解耦。

建议改动文件（第一阶段）：

• src/OpenClaw.Core/Skills/*（catalog/creator 抽象）
• src/OpenClaw.Cli/SkillCommands.cs（catalog/creator/proposal 入口命令）
• src/OpenClaw.Tests/SkillCommandsTests.cs
• docs/opensquilla-meta-skill-migration.md
• docs/zh-CN/opensquilla-meta-skill-migration.md

实施要点（分期）：

1. Phase 1：只落“目录发现 + 只读提案查看”最小闭环，确保不影响现有 meta-runs 运维面。（已完成，2026-06-14）
2. Phase 2：增加 creator 脚手架与提案草稿生成（含验证与失败路径）。
3. Phase 3：接入 proposal pipeline（状态流、审计字段、权限边界）。

Phase 2 当前进展（2026-06-14）：

• openclaw skills create 最小脚手架入口（standard|meta）
• 支持 --json 合同输出（name/slug/kind/path/created/overwrote）
• 支持冲突保护与 --force 覆盖 SKILL.md
• proposal 草稿输出契约（--proposal-draft，text/json 双输出）
• proposal 草稿失败路径（standard + --proposal-draft 返回 usage 错误）
• proposal 草稿质量摘要（JSON proposalDraft.quality + 文本质量行）
• proposal 草稿质量明细（proposalDraft.quality.checks[] + warnings[]）
• --json 失败路径 machine-readable 错误码（示例：invalid_proposal_draft_kind）
• creator 质量检查分级（pass|warn|fail）与建议字段（checks[].recommendation）
• creator 质量门禁阈值（skills create --proposal-draft 在低质量草稿上返回 proposal_draft_quality_gate_failed）
• create 失败 JSON 统一 schema（status/command/errorCode/message）
• 错误码体系已扩展到 skills proposals 与 skills meta-runs proposals show 的参数校验失败路径
• 错误码体系已扩展到 replay/reconstruct/proposals change/rollback 的参数校验失败路径
• 错误码体系已扩展到 catalog/inspect/install 的参数校验失败路径
• 错误码体系已扩展到 meta-runs 运行时失败分支（例如 session/run/proposal not found 与 lifecycle transition 拒绝），--json 下统一输出 machine-readable 错误 schema
• 错误码体系已扩展到 inspect/install 的运行时检查失败分支（如 source inspect 失败与 install 执行异常），--json 下统一输出 machine-readable 错误 schema
• 错误码体系已扩展到 skills 顶层 unknown subcommand 分支，--json 下输出统一 machine-readable 错误 schema（unknown_subcommand）
• Phase 3 权限边界第一步：proposals accept|dismiss|rollback|change 需要 OPENCLAW_OPERATOR_ID，缺失时在 --json 下返回 permission_denied
• Phase 3 审计字段第一步：proposals show 与 mutation 响应新增 additive audit 字段（schemaVersion/actorId/changedAtUtc/transitionAction），来源于 durable transition metadata
• Phase 3 产品级 E2E 验收切片已落地：create --proposal-draft --json -> dismiss -> rollback -> change -> show，并新增权限失败分支回归，对应 RunAsync_Phase3_E2E_CreateToLifecycleToAudit_ReachesConsistentState 通过
• Phase 3 产品级 E2E 冲突分支回归：dismiss -> accept(conflict) -> show，对应 RunAsync_Phase3_E2E_DismissThenAcceptConflict_PreservesDismissedState 通过
• Phase 3 产品级 E2E 反向冲突分支回归：accept -> dismiss(conflict) -> show，对应 RunAsync_Phase3_E2E_AcceptThenDismissConflict_PreservesApprovedState 通过
• 错误码体系已覆盖当前 skills 命令面主要失败路径（参数校验、运行时 not-found、inspect/install 运行时失败、unknown subcommand）

Phase 1 完成证据（additive，兼容旧调用方）：

• openclaw skills catalog（含 --kind meta 与 --json）
• openclaw skills proposals 只读 alias（list/show；拒绝 lifecycle 写操作）
• proposals list/detail JSON 增加入口标识：entrypoint、readOnlyAlias
• 顶层与 skills 帮助文本更新，并有对应回归测试

验收测试（建议最小切片）：

• dotnet test src/OpenClaw.Tests/OpenClaw.Tests.csproj --filter "FullyQualifiedName~RunAsync_Skills_|FullyQualifiedName~RunAsync_MetaRuns_Proposals_"

DoD：

• catalog/creator/proposal 命令具备稳定帮助文本与 JSON 契约。
• 运行时编排与产品流程分层清晰，避免 runtime 路径耦合产品策略。

风险控制：

• 先做只读与脚手架能力，再推进写路径和状态流。
• 所有新增合同字段保持 additive，避免破坏现有调用方。

P1 验收口径（更新）#

P1-1 Meta-runs 运维面#

• meta-runs inspection（摘要/过滤/verbose/json）
• replay preview-only + reconstruct audit-only
• proposals / proposals show 证据视图
• proposals accept/dismiss/rollback/change durable lifecycle（meta_run_proposal）
• 幂等/冲突/JSON 失败路径契约
• proposal provenance 的域层闭环（snapshot + 回滚/变更）

P1-2 skill_exec 运维面#

• stdin-heavy 执行路径
• evidence 持久化与 reconstruct notes
• replay 缺口 machine-readable 合约（含 skill_exec_inputs_not_persisted）
• 更高层 operator UX（聚合与导诊）

建议下一步（执行顺序）#

1. 继续扩展产品级 E2E 验收切片（增加更多失败/越权/冲突路径）。 优先建议：按 failure matrix 维度补齐更多组合链路，并保持 JSON 错误契约 + non-drift 双断言。
2. 如未来需要更细 creator 分类，再拆分阻断项/警告项门禁策略。
3. 将扩展后的产品级 E2E 切片纳入常规回归基线。

2026-06-15 增量闭环：meta-skill-creator 运行时同构#

• Gateway 内置 meta-skill-creator 已具备 fill_slots/assemble/lint/smoke/runtime_e2e/persist 语义实现与可执行链路。
• FULL_GATED 等价测试已在 Agent 与 MAF 两侧显式断言 lint/smoke/runtime_e2e/persist 均完成。
• creator 工具契约测试已覆盖持久化 gates.json 结构（proposal_id、creator_mode、lint、smoke、runtime_e2e）与响应 envelope。

验证切片：

• dotnet test src/OpenClaw.Tests/OpenClaw.Tests.csproj --filter "FullyQualifiedName~MafAgentRuntime_ExecuteMetaSkillAsync_MetaSkillCreator_FullGated_Completes|FullyQualifiedName~ExecuteMetaSkillAsync_MetaSkillCreator_FullGated_ProducesPersistencePayload"
• dotnet test src/OpenClaw.Tests/OpenClaw.Tests.csproj --filter "FullyQualifiedName~MetaSkillCreator"

Phase 3 验收清单（DoD 草案）#

• proposal pipeline 状态机定义并文档化（含允许/禁止迁移、幂等与冲突语义）。
• 写操作入口完成权限边界定义（操作者身份、只读入口限制、越权失败契约）。
• 审计字段在 list/show/mutation 输出中保持 additive 且前后兼容。
• --json 失败路径继续使用统一 schema（status/command/errorCode/message）。
• 完成端到端验收切片并通过（产品链路 + 回放/重建链路）。

P1 执行任务单（归档）#

P1-1 与 P1-2 已完成并通过回归验证。该节仅保留历史记录，后续工作聚焦 P2。