[RFC] Scripts-as-tools + workflow 自迭代 —— AI 加 feature 不用编译发版

[eanzhao]

相关：#424（LLM provider catalog —— scripting 已经在做发现层），#400（NyxID 边界）

背景

aevatar 已经有三块独立但互不知道彼此存在的能力：

1. Workflow YAML 完全 hot-swap：/api/chat 接受 inline YAML，WorkflowGAgent 第一次用时编译，每次 run 是独立 actor（src/workflow/Aevatar.Workflow.Core/Primitives/WorkflowParser.cs）。30 个 step kind 覆盖编排层（llm_call / tool_call / connector_call / conditional / switch / while / foreach / parallel / race / map_reduce / vote / workflow_call / dynamic_workflow / human_input / assign / transform / cache / checkpoint / wait_signal / emit / delay 等）。
2. Scripting 子系统完整：Roslyn 运行时编译、ScriptDefinitionGAgent 持久化、ScriptBehaviorGAgent 沙箱执行、ScriptCatalogGAgent 管 revision，支持 promote / rollback。关键：编译走 Roslyn，不要发版。
3. LLM tool framework 成熟：IAgentTool + ToolManager + ToolCallLoop + IAgentToolSource + approval / hooks / middleware；MCP 已接通；Aevatar.AI.ToolProviders.Scripting 已经把 7 个meta-tool（script_compile / script_execute / script_promote / script_rollback / script_list / script_source / script_status）暴露给 LLM。

把三块连起来，逻辑上 AI 已经能：列出脚本 → 写一个新脚本 → 编译 → 沙箱执行 → 看结果 → promote → 在 workflow 里 tool_call 调用。但实际不行，缝隙就一处：每个 script 还没作为独立 tool 出现在 LLM 面前。LLM 看到的只有统一的 script_execute(scriptId, payloadJson)，不知道 catalog 里有 calculate_discount(order_id, customer_tier) 这种语义化 tool 可调。

目标

把现有三块缝合到位，让"AI 写一个 script 当工具用 + 写一份 YAML 把它编排进新功能 → 立即上线"成为最短闭环。不引入第二条系统，所有补丁都是在已有抽象内部加 adapter。

提议：补 5 块小东西

1. ScriptToolSource : IAgentToolSource（最具杠杆）

新建 source（住在 Aevatar.AI.ToolProviders.Scripting），在 agent 激活时（或定时）扫 ScriptCatalogGAgent 里 promoted 状态的 script，把每条映射成独立 IAgentTool，注册进 ToolManager。LLM 选 tool 时看到的是 calculate_discount，背后路由到 ScriptExecuteTool。

2. Script Definition 加 tool 元数据

ScriptDefinition proto 增加：

字段	用途
tool_name	LLM 看到的名字（snake_case，全 catalog 唯一）
tool_description	自然语言描述，LLM 选 tool 的依据
when_to_use	触发条件描述（可选，给 LLM 的提示）
examples	可选示例参数（给 LLM 的 few-shot）

没有这些字段时，script 默认不进入 ScriptToolSource，依然只对 meta-tool 可见。这样不破坏现有脚本。

3. Proto → JSON Schema 自动转换

IAgentTool.ParametersSchema 要 JSON Schema，但 script 输入是 protobuf。需要从 proto descriptor 自动生成 JSON Schema（住在 Aevatar.AI.Abstractions/ToolProviders 的 helper 里）。否则每个脚本作者得手维护两份 schema，AI 自己玩不起来。

4. Tool 输出契约 + await readmodel

Script 产出是 events + readmodel，tool result 是字符串。需要明确：

• option A：Script Definition 声明一个 tool_response 强类型 message，runtime 等到对应 readmodel StateVersion ≥ 写入版本后，序列化这个字段返回；
• option B：默认返回 readmodel snapshot 的 stable subset。

这块有 CLAUDE.md 强约束：禁止 query-time replay/priming。所以正确做法是 await committed + projection observed，不是同步从 actor state 读。倾向 A，强类型契约更清晰。

5. Per-script approval policy

ScriptExecuteTool 现在统一 AlwaysRequire，AI 自迭代场景里太重。Script Definition 加 tool_approval_mode 字段，沙箱阶段 / promoted 阶段可以分别策略。配合现有 ToolApprovalMiddleware。

---

这 5 块加上去，链路全通。1+2+3 是必须，4 是正确性，5 是体验。

AI 自迭代的真正边界（硬约束，不是工程缺口）

写之前要把范围讲清楚，避免 "AI 能做任何 feature" 误区：

1. 新 step kind 仍要 C# 编译重启：IWorkflowModulePack 是静态 pack，加新 module 要 DI 注册。但实际不是问题——tool_call + connector_call + script 三件套覆盖业务编排层；真正需要新 step kind 的场景（新传输协议、新存储后端）本来不该让 AI 改。
2. 沙箱 capability 是天花板：IScriptBehaviorRuntimeCapabilities 暴露的（AskAI / Publish / SendTo / CreateAgent / UpsertScriptDefinition / ScheduleSelfDurableSignal / ProposeScriptEvolution）就是上限。AI 想要新能力（GPU、原生代码、新存储）依然要在内核加。这是对的，沙箱不该由 AI 自己撑开。
3. AI 必须能看到 readmodel 目录：CLAUDE.md 强制读写分离、禁止 actor 间侧读。AI 写 script 想"读其他 actor 的状态"必须走 readmodel——但 readmodel 是 projection 主链产出的，AI 不能凭空造。所以要给 AI 一个可读 readmodel 目录 + proto schema 可见，否则会凭直觉写出违反读写分离的脚本被门禁拦下。这块可能是最容易被忽视的缺口。
4. Promotion 治理缺位：promote / rollback 已有，但缺 canary、gradual rollout、自动 rollback on error rate spike。AI 自己 promote 到生产是危险的，需要分级 staging。
5. Evals 闭环缺位：AI 自迭代关键不是"能写"，是"能验证"。需要：
   • script + workflow 的 dry-run / shadow-run 模式；
   • 失败诊断回灌给 AI 的标准化错误格式（stack + step context + 输入快照 + readmodel 当时态）；
   • golden test / 回归套件，AI promote 前必须跑通。
6. 成本和失控边界：AI 写 100 个 script、跑 10000 次 workflow 的资源和成本要有 quota / kill-switch。ScriptCatalogGAgent 没看到资源配额维度。

待决问题

1. ScriptToolSource 的发现时机：agent 激活时一次性拉？订阅 ScriptCatalogGAgent 的 promoted 事件流增量更新？还是定时拉？倾向后两者组合（事件流为主，定时兜底）。
2. per-agent vs global tool catalog：所有 agent 共享一个全局脚本目录？还是 per scope（org / user / team）？跟 [RFC] Scope 与 AI Team 边界 —— 新增 AI Team 支持 scope 多团队 #464（scope 与 AI Team）相关。
3. script 输出契约二选一：option A（强类型 tool_response）还是 option B（readmodel snapshot subset）？
4. AI 看到的 readmodel 目录怎么暴露：新做一个 ReadModelCatalogGAgent？还是 workflow 已有的 actor_inspect / event_query 扩展为 readmodel browser？
5. proto → JSON Schema 转换层：自己写还是用现成（grpc-gateway style）？aevatar 自己生成的 proto types 用 protobuf-net，需要确认能不能拿到 descriptor。
6. dry-run / shadow-run 形态：ScriptBehaviorGAgent 已有 ephemeral execute mode，是否复用作为 dry-run？workflow 这边要不要也加一个 plan-only 模式？
7. Evals 在哪一层做：script 的单元测试 + workflow 的端到端 golden case 要不要统一进 ScriptCatalogGAgent / WorkflowGAgent 作为 promote 前置门禁？
8. AI 写完后谁来 review：自动 promote 还是必须 human approval？跟 [RFC] Member 与 Service 边界 —— 新增 Agent 作为 AI Team 产品身份，Service 作为发布运行面 #465（Member 与 Service 边界）有交集——AI Team 自己改自己 service。

落地顺序（建议，从最具杠杆开始）

1. Script Definition proto 加 tool_name / description / when_to_use / examples / tool_approval_mode + 默认隐藏行为
2. proto → JSON Schema converter + 单元测试
3. ScriptToolSource : IAgentToolSource，事件流订阅 + 启动时全量
4. Tool 输出契约（option A 倾向）+ await stable readmodel version 的等待 helper
5. CLI / UI：aevatar script tool list / preview {tool_name}，方便人工审阅 AI 写的脚本
6. Workflow 侧：tool_call 步骤验证脚本 tool 可被引用（理论上现成的）
7. Readmodel catalog（待决 4 决定形态后）
8. dry-run / evals 层（最大块，可以独立 RFC）
9. Promotion 治理：canary + auto-rollback（独立 RFC）

1-6 是 MVP，做完 "AI 写 script + 写 YAML + 上线" 闭环就成立。7-9 是把"能跑"变成"敢跑"。

---

评论区想听：

• option A vs B 的输出契约选型（待决 3）
• readmodel catalog 形态（待决 4）
• evals / dry-run 是否拆独立 RFC
• 跟 [RFC] Scope 与 AI Team 边界 —— 新增 AI Team 支持 scope 多团队 #464 / [RFC] Member 与 Service 边界 —— 新增 Agent 作为 AI Team 产品身份，Service 作为发布运行面 #465 的 scope 边界要不要先对齐