[RFC] 收敛 workflow 执行双轨：skill inline YAML 与 scope service / NyxID downstream

[eanzhao]

[RFC] 收敛 workflow 执行双轨：skill inline YAML 与 scope service / NyxID downstream

基于 feature/integrate（300441ca0 附近）的代码调查；所有 文件:行 引用以该版本为准。

1. 现状：同一个 workflow 有两条互不知晓的执行链

链路 A — Lark/chat 默认路径：Ornn skill → inline YAML 临时执行

Lark 入站 (ChannelConversationTurnRunner.RunInboundAsync, agents/Aevatar.GAgents.NyxidChat/ChannelConversationTurnRunner.cs:125)
  → LLM 调 use_skill (src/Aevatar.AI.ToolProviders.Skills/UseSkillTool.cs)
  → OrnnRemoteSkillFetcher 每次实时拉取 skill（无缓存）(src/Aevatar.AI.ToolProviders.Ornn/OrnnRemoteSkillFetcher.cs:20-76)
  → SkillWorkflowExtractor 提取 workflows/ 或 assets/ 下的 YAML (src/Aevatar.AI.ToolProviders.Skills/SkillWorkflowExtractor.cs:26-239)
  → use_skill 返回 "## aevatar_start_workflow Handoff"，附 {workflow_id, workflow_yamls} JSON (UseSkillTool.cs:386-409)
  → LLM 调 aevatar_start_workflow(workflow_id, workflow_yamls=inline)
  → WorkflowChatSource.InlineYamlBundle → 临时 run，不进 scope catalog (AevatarInvocationDispatcher.cs:286-290)

关键事实：

• Handoff prompt 原文明确指示 inline 执行："Call aevatar_start_workflow with this inline workflow bundle before treating workflow YAMLs as ordinary reference files."
• mount_workflows 参数存在（mount 进 scope catalog，走 IScopeWorkflowCommandPort.UpsertAsync，有 RevisionId），但默认 false 且 opt-in（UseSkillTool.cs schema："Default false"），mount 还触发 approval（RequiresApproval => MountWorkflows）。
• SkillRunnerGAgent 的 cron 场景同样走 inline（agents/Aevatar.GAgents.Scheduled/SkillRunnerGAgent.cs:673-731）。

事实源 = Ornn skill assets 里的 YAML，在拉取瞬间冻结的快照。

链路 B — 生产暴露面：scope catalog → service binding → NyxID downstream

scope workflow catalog（注册 workflow，含 revision）
  → service binding（ScopeBindingImplementationKind.Workflow，
     src/platform/Aevatar.GAgentService.Abstractions/ScopeBindings/ScopeBindingModels.cs:3-9；
     ServiceBindingSpec proto：src/platform/Aevatar.GAgentService.Governance.Abstractions/Protos/service_binding.proto:30-42）
  → invoke 端点 POST /{scopeId}/services/{serviceId}/invoke/{endpointId}[:stream]
     (src/platform/Aevatar.GAgentService.Hosting/Endpoints/ScopeServiceEndpoints.cs:81-95，带 scope access guard)
  → （out-of-band 人工/控制台）注册为 NyxID downstream service，得到 slug
  → 任意 agent 经 nyxid_proxy 发现（省略 slug → 列服务）与调用（凭证注入 + approval 透传）
     (src/Aevatar.AI.ToolProviders.NyxId/Tools/NyxIdProxyTool.cs:20-26, 93-96, 112-117)

事实源 = scope catalog 里的注册 workflow（committed actor state + revision），并有完整治理面（scope guard、NyxID 凭证注入、approval）。

脱轨点

#	问题	后果
1	定义双源：skill YAML 快照 vs catalog 注册 revision	改一边另一边无感知，Lark 实际跑的版本与 service 上激活的 revision 静默分叉
2	默认路径绕开注册：Handoff 指示 inline，mount 是 opt-in	每次 Lark 调用都是临时 run，catalog/binding/NyxID 三层全部旁路
3	治理面不一致	service invoke 有 scope guard + 凭证注入 + approval；inline 只有 chat 侧 tool approval，同一 workflow 两套安全语义
4	aevatar_start_workflow 双重语义：workflow_id（名称查找）+ workflow_yamls（inline 内容）	正是 CLAUDE.md「API 字段单一语义，禁止双重语义（名称查找 + inline 内容）」点名的反例
5	workflow ↔ scope service ↔ NyxID slug 无 typed 关联	"这个 workflow 的生产部署是哪个 service/slug" 不可查询，drift 不可审计

2. 设计目标（从仓库不变量直接推导）

1. 事实源唯一：workflow 定义的权威 = scope catalog（committed state + revision）；skill assets YAML 降级为"分发种子"。
2. 单一主干，禁止双轨：chat 执行、cron 执行、service 调用最终解析到同一个 catalog 对象。
3. 强类型解析，禁止字符串路由：workflow → service → slug 的关联必须是 typed 字段，不是 display_name 模糊匹配。
4. ACK 诚实：本地 run（{run_id, status, stream_topic}，见 ADR-0026 D3）与跨边界代理调用（任意 HTTP 响应 + approval pending）契约不同，不得混在一个结果壳里假装一样。
5. 外部仓库零改动：Ornn 的 skill 格式（assets YAML）、NyxID 的注册/发现/代理面全部按现状用。

3. 候选方案对比

方案 1：aevatar_start_workflow 内嵌 NyxID downstream 解析（最初提议）

workflow_id 本地 catalog 未命中时，工具内部去 NyxID 发现 downstream service 并经 proxy 调用。

• ✅ 单一工具入口，LLM 心智不变；跨 scope 可达。
• ❌ 在已有三种 source 语义（InlineYamlBundle / CatalogWorkflow / DefinitionActor，AevatarInvocationDispatcher.cs:286-290）上叠第 4 种，加深脱轨点 4 的双重语义违规。
• ❌ workflow_id → slug 今天没有任何 typed 来源（脱轨点 5），只能靠 slug/display_name 字符串匹配——CLAUDE.md 禁止的字符串路由。
• ❌ 结果契约撕裂：本地 run 与代理调用的返回形态、一致性承诺、approval 语义完全不同，塞进一个工具违反 ACK 诚实。
• ❌ 静默跨边界：调用方以为在本 scope 起 run，实际打到别处的服务（凭证、审批、计费面都变了），不应隐式发生。
• 📌 注意：这个方案不是被否定，而是缺前置——等方案 3 的 Phase 3 落地 typed slug 关联后，它的"typed 变体"可以作为可选 Phase 4 重新评估（见 §5）。

方案 2：纯 prompt 收敛

只改 Handoff / 系统提示，让 LLM "先查 catalog，再用 nyxid_proxy 发现"。

• ✅ 零结构改动。
• ❌ 不解决定义双源（脱轨点 1/2/4/5 原样保留）。
• ❌ 依赖 LLM 服从指令，持久会话中指令衰减是已踩过的坑（active-playbook 经验）；非确定性。

方案 3（推荐）：分层收敛 —— mount-first + reference-only + typed exposure

把两条链路收敛成一条主干上的四个生命周期阶段：

Ornn skill（分发种子, assets/*.yaml）
   │ use_skill 默认幂等 mount（content 不变→no-op；变→新 revision）
   ▼
scope workflow catalog ◄────────────── 单一事实源（revision 化）
   │ bind（激活某 revision）                ▲
   ▼                                       │ chat/cron 执行：aevatar_start_workflow(workflow_id [+revision])
scope service（invoke 端点 + 治理面）       │
   │ NyxID 注册（slug 写回 binding 的 typed 字段）
   ▼
NyxID downstream（slug）◄── 跨 scope 调用走 nyxid_proxy（既有 approval/凭证语义）

4. 推荐方案落地（三阶段）

Phase 1 — 止血：mount-first + reference-only Handoff（最小 diff）

• use_skill 对含 workflow 的 skill 默认 mount（幂等：content-hash 相同 → 复用现 revision；不同 → UpsertAsync 新 revision，ScopeWorkflowUpsertRequest 已支持 RevisionId，src/platform/Aevatar.GAgentService.Abstractions/ScopeWorkflows/ScopeWorkflowModels.cs:5-12）。
• Handoff 文本从"传 inline bundle"改为只交 workflow_id（+ 本次 mount 得到的 revision），LLM 走 CatalogWorkflow 分支。
• aevatar_start_workflow 的 not-found 错误 actionable 化："workflow '' 不在本 scope catalog；若它已发布为服务，用 nyxid_proxy（不带 slug）发现 downstream service 后调用"。错误时刻的引导比系统提示更确定（这是对方案 1 诉求的承接：LLM 确实会去 NyxID 找，但通过既有工具、在明确失败的时机）。
• 效果：Lark 上每次执行都落在 catalog revision 上，脱轨点 1/2 关闭。

Phase 2 — 收窄契约：撤掉 LLM-facing 的 inline 语义

• 从 aevatar_start_workflow 的 LLM-facing schema 移除 workflow_yamls（aevatar_invocation_tools.proto:54-60 中 field 5），消除脱轨点 4 的双重语义；draft/dev 场景与 SkillRunner cron 内部路径改走"先 mount 后引用"或保留独立的内部契约（不暴露给 LLM）。
• SkillRunnerGAgent（cron）同步改为 mount+catalog 执行，使 cron 与 chat 跑同一 revision。
• 补 guard：禁止 LLM-facing tool schema 同时含名称查找与 inline 内容字段。

Phase 3 — typed exposure：让"生产部署"成为可查询事实

• ServiceBindingSpec（或 service definition）增加 typed 字段记录 NyxID 注册信息（slug、注册时间）；ops 在 NyxID 注册后通过 binding API 写回。NyxID 侧零改动，纯 aevatar 侧状态。
• 由此 workflow → binding（激活 revision）→ NyxID slug 全链 typed 可查，drift（skill 快照 vs 激活 revision）可审计、可在 mount 结果里直接报告。

（可选）Phase 4 — 重新评估方案 1 的 typed 变体

Phase 3 之后，同 cluster 内 dispatcher 可以 typed 解析 workflow_id → binding → slug，不再需要模糊匹配。若届时确有"单工具入口"需求，可给 aevatar_start_workflow 加显式的跨边界结果壳（明确区分 local_run vs proxied_invocation，各自诚实的 ACK 语义）。在那之前不做。

5. 兼容性

• Ornn 零改动：assets/workflows 下的 YAML 继续作为 skill 的分发格式，只是语义从"执行体"降为"安装种子"。
• NyxID 零改动：注册仍 out-of-band，发现/调用用既有 nyxid_proxy 面。
• 存量 skill 零改动：mount-first 对 skill 内容无要求；19 个已迁移 skill 不用动。
• 不硬编码 skill 名：所有行为由 skill 是否携带 workflow YAML 这一结构事实驱动。

6. Open Questions

1. mount 的 approval 语义：目前 mount_workflows=true 触发 approval。mount-first 后建议：首次 mount / revision 变更需 approval，同 revision 幂等重放免审批——是否接受？
2. 同名 workflow 内容漂移时跑哪个：建议 chat 执行跑本次 mount 出的 revision，service 调用跑 binding 激活的 revision，两边结果都显式带 revision（可观察、不静默）。
3. SkillRunner cron 收敛的 scope 归属：cron 用 NyxApiKey 执行，mount 进哪个 scope（owner scope？）需要定一个归属规则。
4. 跨 scope 发现要不要做 cluster 内聚合：是统一全走 NyxID 发现，还是为同 cluster 服务建一个跨 scope service catalog readmodel（聚合 actor）？倾向先统一走 NyxID，避免第二套发现面。

---

欢迎拍砖，尤其是 Phase 1 的 mount-first 默认值变更（行为面最大）和 Open Question 2 的 revision 选择规则。

[eanzhao]

补档：关于"保留现有 inline 路径作为 availability fallback、NyxID downstream 作为另一来源"的评估

线下讨论了一个变体：保留现在 Lark bot 的 inline YAML 调用方式作为 fallback，让 NyxID downstream 作为另一个 workflow 来源。结论补档如下。

结论：「NyxID downstream 作为另一个 workflow 来源」成立（本 RFC 即此定位）；「现有 inline 路径作为可用性 fallback」不建议——那不是稳健，是把脱轨制度化成运行时行为。可取形式 = 双来源、显式选择。

两个来源不是同一事实的两个副本，而是不同版本 + 不同治理面。fallback 只有在副本等价时才带来稳健（如读多副本）；版本可能不同时，fallback 带来的是不确定性：

1. 版本漂移变成运行时抽奖。NyxID 一抖，本次调用就无感知地跑了 skill 快照里的旧版 YAML，下次又跑回 service 上的新版。结果不可复现，排查难度高于直接失败。
2. fail-open 治理降级。service 路径有 scope guard + 凭证注入 + approval（ScopeServiceEndpoints.cs:81-95、NyxIdProxyTool.cs:112-117）；inline 路径只有 chat 侧 tool approval。"approval 被拒/凭证不足 → 降级到 inline 本地跑"等于失败时绕过了拦住它的那道控制。fallback 触发条件的错误分类学（not-registered / NyxID 不可用 / approval denied / timeout）必须各自处理，混进统一的"主路径失败→降级"就是 silent-fallback bug class（仓库已有先例教训）。
3. 身份与凭证错位。别人 scope 发布的 service，其 YAML 快照在调用者 scope 里用调用者的凭证和 connectors inline 跑——要么缺 secret/connector 失败得莫名其妙，要么用错身份执行了本该在服务方身份下跑的动作，违反 credential isolation。

另外两点支撑：

• mount-first（Phase 1）落地后，fallback 想覆盖的可用性窗口本不存在：同 scope 执行的来源解析走本地 catalog（actor 持久态），对 NyxID 零依赖。"NyxID 挂了跑不了"只剩跨 scope service 场景——而该场景没有合法的本地替代品（本地跑别人服务的快照正是上面 1/3 两条危险），诚实失败 + actionable error 是唯一正确行为。
• 仓库既有口径一致：现有的 WorkflowDirectFallbackPolicy 就是窄 fallback 的样板——typed source 驱动、白名单 gate、inline bundle 直接排除（src/workflow/Aevatar.Workflow.Application/Runs/WorkflowDirectFallbackPolicy.cs），而不是广义的可用性降级。

方向性原则一句话：not-found → 发现引导（去 NyxID 找）✅；失败 → 换版本跑（降级）❌。 两者方向相反，不可互换。

最小落地切片（已开 issue，进 milestone "Workflow Week of 2026-06-08"）

Issue	内容	对应 RFC
#1981	E2E 最小闭环验证：bind → NyxID 注册 → nyxid_proxy 发现/调用（既有 surface，零新代码预期，产出 runbook + 缺口清单）	链路 B 事实地基
#1982	aevatar_start_workflow catalog 未命中返回 actionable 错误，引导 nyxid_proxy 发现	Phase 1（引导部分）
#1983	ServiceBindingSpec 增加 NyxID 暴露 typed 记录（slug 写回 + 读模型透出）	Phase 3 最小片 / P4 前置

这组就是"双来源显式选择"的最小骨架：来源由声明与目录事实决定，失败诚实失败，不做静默降级。