Elsa Weaver AI Copilot 平台快速上手：服务端托管式 AI 工作流助手的 MVP 验证指南

• 后端
• 工作流自动化
• 流程编排
• 低代码

Weaver 是 Elsa 工作流引擎中的 AI Copilot 平台：Studio 通过聊天界面与服务器托管的 AI 助手交互，由 Elsa Server 负责上下文解析、受治理的工具执行、审计与提案落地，而 GitHub Copilot SDK 负责会话编排与工具续跑。本文基于 specs/008-weaver-ai-copilot 目录下的 quickstart.md，完整梳理 MVP 的验证目标、开发环境隔离、服务端配置、手工验证清单、自动化测试命令与架构边界检查，读完即可照单复现 Weaver 的端到端验证流程。

一、MVP 验证目标：不依赖 Studio 直连 Provider

Weaver 的核心前提是：Studio 永远不直接调用 AI 提供商，一切 AI 能力都由 Elsa Server 代为执行。Quickstart 定义了 6 个必须被验证的 MVP 路径：

1. 启用 AI 抽象、Host 与 Copilot 适配器三个模块；
2. 启动由服务器托管的 Weaver 聊天；
3. 在服务端解析工作流上下文；
4. 流式输出助手与工具事件；
5. 创建工作流提案；
6. 对提案进行校验、审批、应用并留下持久化审计。

其中最关键的一条边界是：Copilot 适配器以GitHub.Copilot.SDK作为 Agent 运行时，而 Elsa Server 只负责提供上下文、工具回调、脱敏、审计与提案强制，不应去模仿 Copilot 的工具续跑循环。这背后是 research.md 中的明确决策：Copilot SDK 拥有会话创建/恢复、模型选择、工具调用与续跑、自定义 Agent、MCP 与 hooks；Elsa Host 只负责租户安全的上下文附件解析、基于 RBAC 过滤的工具元数据、服务端工具执行、提案专属变更强制、审计、脱敏与 Studio 流契约。

二、开发环境：用独立 git worktree 隔离实现

实现应运行在专用的 git worktree 中，而不是主检出目录，目的是让功能开发、生成产物与测试输出彼此隔离。Core 与配套的 Studio 模块分别创建独立 worktree：

git -C /Users/sipke/Projects/Elsa/elsa-core worktree add -b codex/008-weaver-ai-copilot-core ../elsa-core-weaver codex/008-weaver-ai-copilot git -C /Users/sipke/Projects/Elsa/elsa-studio worktree add -b codex/008-weaver-ai-copilot-studio ../elsa-studio-weaver main

此后，Core 任务在/Users/sipke/Projects/Elsa/elsa-core-weaver下执行，Studio 任务在/Users/sipke/Projects/Elsa/elsa-studio-weaver下执行。如果目标分支已存在，则直接挂载到该分支而不是重复创建。

三、服务端启用 Weaver：UseAI / UseHost / UseCopilot

在 Elsa Server 的Program.cs中启用 Weaver 的最小配置如下：

services .AddElsa(elsa => { elsa.UseAI(ai => { ai.UseHost(); ai.UseCopilot(copilot => { copilot.RuntimePath = "copilot"; copilot.Model = "configured-model"; }); }); });

UseHost()启用服务端的上下文解析、工具注册、提案与审计能力；UseCopilot()注册 Copilot 适配器。RuntimePath指向 Copilot CLI 运行时，Model指定模型名称（示例值configured-model需替换为实际部署中配置的模型）。

从源码看，CopilotOptions提供的可配置项远不止这两个。查看 CopilotOptions.cs 可见完整字段：

这些选项在 CopilotAIFeature.cs 中通过ConfigureOptions逐项写入CopilotOptions，并以IShellFeature形式注册到模块系统（该特性标注为[ManifestFeatureCategory("AI")]、DisplayName = "Copilot AI Provider"）。

仓库中 AI 相关模块的物理位置与 plan.md 中的规划一致：Elsa.AI.Abstractions（csproj）持有 provider 无关的模型与契约；Elsa.AI.Host（csproj）提供 REST/流式端点、内置工具、上下文、提案与审计；Elsa.AI.Copilot（csproj）封装 Copilot SDK；持久化侧有Elsa.AI.Persistence.EFCore及 MySql / Oracle / PostgreSql / SqlServer / Sqlite 各数据库实现（csproj 列表见 src/modules）。

四、手工验证：17 步端到端清单

启动启用了 Weaver 的 Elsa Server 后，按以下顺序逐项验证：

4.1 能力发现与工具列举（步骤 1–4）

1. 请求GET /ai/capabilities，确认流式输出（streaming）、提案审查（proposal review）、附件类型（attachment kinds）与 Agent 列表都被通告；
2. 确认/ai/capabilities会通告针对活动（activities）、工作流（workflows）、提案（proposals）与运行时（runtime）的 grounding families，并且当相应 store 未注册时会附带 disabled 原因；
3. 以授权用户请求GET /ai/tools，确认返回 Activity Registry、工作流定义、提案、实例与事故（incident）相关工具。

GET /ai/capabilities的响应结构在 rest-api.md 中有完整示例：

{ "streaming": true, "conversationPersistence": true, "proposalReview": true, "supportedAttachmentKinds": [ "WorkflowDefinition", "WorkflowInstance" ], "agents": [ { "name": "workflow-author", "displayName": "Workflow author", "description": "Creates safe workflow proposals" } ] }

GET /ai/tools返回当前用户、租户与可选 Agent 作用域下可用的工具，每个工具携带治理元数据：

[ { "name": "workflow.getDefinition", "displayName": "Get workflow definition", "mutability": "ReadOnly", "dangerLevel": "Low", "permissions": ["read:workflows"], "tenantBehavior": "TenantScoped", "auditBehavior": "RecordInvocation", "schema": {} } ]

该接口支持agent查询参数以限定 Agent 作用域。

4.2 聊天与流式事件（步骤 5–8）

4. 向 Weaver 提问"哪个已安装活动可以接收 HTTP 请求"，验证回答基于activities.search或activities.getDescriptor工具，而不是凭空猜测；
5. 以携带WorkflowDefinition附件引用的请求启动POST /ai/chat，让 Weaver 解释该工作流；
6. 验证流事件包含助手增量（assistant deltas）与工具生命周期事件；
7. 验证 Elsa 日志/审计记录了服务端工具执行，且驱动 Agent 循环的是 Copilot SDK 的会话事件，而非 Host 管理的续跑轮次。

POST /ai/chat的请求示例（附件只传引用，不传原始数据）：

{ "conversationId": "optional-existing-conversation-id", "message": "Explain why this workflow failed", "attachments": [ { "kind": "WorkflowInstance", "referenceId": "instance-123", "timeRange": { "from": "2026-05-20T08:00:00Z", "to": "2026-05-20T10:00:00Z" } } ], "agent": "instance-diagnostics" }

响应以 SSE 或等价的服务端自有流式传输逐条下发AIStreamEvent记录：

{ "type": "assistant.delta", "conversationId": "conversation-123", "sequence": 12, "timestamp": "2026-05-20T10:15:00Z", "data": { "messageId": "message-456", "content": "The failure happened in..." } }

契约中定义的流事件类型包括：conversation.started、assistant.delta、assistant.completed、tool.started、tool.progress、tool.result、proposal.created、proposal.updated、conversation.completed、conversation.error。Studio 端的渲染期望在 studio-contract.md 中定义：assistant.delta追加文本、tool.started显示工具名与安全参数摘要、tool.progress更新进度行、proposal.created弹出提案通知等。

4.3 提案生命周期（步骤 9–13）

8. 让 Weaver 生成一个简单工作流；
9. 验证提案已创建，且GET /ai/proposals/{id}返回 payload、rationale（理由）、warnings、diagnostics 与 graph preview；
10. 在未审批时尝试 apply，验证服务器拒绝该状态迁移；
11. 以授权用户审批并应用提案；
12. 验证工作流已持久化、校验通过，且 prompt、工具调用、审批、应用均有持久化审计记录。

提案是AI 写工作流的唯一路径。POST /ai/proposals/{id}/approve只标记审批而不应用；POST /ai/proposals/{id}/reject拒绝并记录原因；POST /ai/proposals/{id}/apply才会真正校验并应用。apply 规则（见 rest-api.md）为：

• 用户必须拥有 apply 权限；
• 提案必须处于 approved 状态；
• 提案 baseline 必须与当前工作流版本匹配（存在版本概念时）；
• 校验必须通过；
• apply 会发出审计记录并返回创建或更新的工作流引用。

提案的数据模型在>

这一行为对应契约 runtime-contract.md 与需求FR-026：进行中的聊天回合会在可配置的断线宽限期内继续执行，期间产生的持久化输出允许授权客户端重连恢复。MVP 的持久化要求是：提案与审计必须持久化（durable），会话历史保留策略可配置（开发与测试允许内存存储），见IAIProposalStore与IAIAuditSink的说明。

4.5 运行时趋势与事故分析（步骤 16–17）

15. 携带附件引用并选择时间范围与诊断作用域（diagnostics scope），请求运行时趋势，验证结果不包含该作用域之外的数据；
16. 询问 Weaver 某个失败的工作流实例为何失败，验证它使用instances.getExecutionHistory、instances.getActivityState、incidents.search或incidents.get，且不会暴露敏感状态。

运行时趋势分析默认被限制为"附件引用 + 显式用户选择的时间范围与诊断作用域"（对应FR-027），租户级全量分析需要未来的显式作用域扩展。

4.6 错误语义

API 契约统一了错误码语义（rest-api.md）：400无效请求/不支持的附件类型/非法提案迁移，401未认证，403权限不足/租户不匹配/工具或提案被拒，404上下文引用/会话/提案不存在，409提案 baseline 过期或状态非法，422提案校验失败，503Provider 运行时不可用。

五、架构边界：Provider 隔离与运行时契约

Quickstart 提供了两个 grep 命令用于执行边界检查：

rg "Copilot" src/modules/Elsa.AI.Abstractions src/modules/Elsa.AI.Host rg "GitHub" src/modules/Elsa.AI.Abstractions src/modules/Elsa.AI.Host

预期结果：Abstractions、Host 契约、工作流模型与 Studio 契约中不得出现任何 Provider SDK 类型或 Provider 自有事件名。这一边界对应需求FR-020与成功标准SC-008，其实现结构为：

• Elsa.AI.Abstractions拥有AIProviderEvent、AIStreamEvent、会话、工具、上下文、提案与审计模型；
• Elsa.AI.Host解析上下文与授权工具集，但不运行模型/工具续跑循环；
• Elsa.AI.Copilot直接使用GitHub.Copilot.SDK会话，将 Elsa 工具注册为受治理的 SDK 回调，并把 SDK 事件映射为 Elsa 自有模型。

research.md 记录了该决策的理由：GitHub 将 Copilot SDK 标为 public preview、功能可能变动，适配器边界能保护 Elsa 抽象与 Studio 契约免受 Provider SDK 迭代冲击。

运行时契约定义了核心抽象接口：IAIProvider（创建会话 + 执行回合）、IAIOrchestrator（执行聊天并产出流事件）、IAITool/IAIToolRegistry（工具定义与查找）、IAIProviderToolInvoker（Provider 侧工具调用回拨）、IAIContextProvider（附件上下文解析）、IAIProposalStore（提案存取）与IAIAuditSink（审计落盘）。

内置 MVP 工具清单（Mutability 标注了工具性质）：

工具执行规则（runtime-contract.md）强调：执行前校验租户、RBAC、所有权、危险等级、全局启用与 Agent 作用域；只通过 Elsa 服务抽象访问持久化；参数与结果在进入流与审计前脱敏；结果进入模型上下文前做大小裁剪；成功、失败与拒绝都通过IAIAuditSink记录。

六、工具治理：元数据、注册 API 与启用策略

每个工具必须声明治理元数据（tool-governance.md）：Name（稳定命名空间标识）、Description、Schema（结构化输入）、Mutability（ReadOnly/Proposal/Administrative）、DangerLevel（Low/Medium/High/Critical）、Permissions（所需 Elsa 权限）、TenantBehavior（TenantScoped/HostScoped/CrossTenantDenied）、AuditBehavior（None/RecordInvocation/RecordInvocationAndResult）与可选的AgentScopes。

第三方模块通过扩展 API 注册能力：

public static class AIFeatureExtensions { public static AIFeature AddAITool<TTool>(this AIFeature feature) where TTool : class, IAITool; public static AIFeature AddAIContextProvider<TProvider>(this AIFeature feature) where TProvider : class, IAIContextProvider; public static AIFeature AddAIAgent<TAgent>(this AIFeature feature) where TAgent : class, IAIAgentDefinitionProvider; public static AIFeature AddMcpServer(this AIFeature feature, Action<AIMcpServerOptions> configure); }

工具执行的强制顺序是：解析当前 actor 与租户 → 解析 Agent 作用域 → 查找工具定义 → 校验全局与 Agent 级启用 → 校验租户行为 → 校验权限与所有权 → 校验 mutability 与危险策略 → 脱敏参数 → 执行工具 → 脱敏结果 → 发出流与审计事件。

启用策略（对应FR-025）：启用模块注册的只读工具可默认启用；提案工具需要显式管理员启用；管理类工具在 MVP 中即使注册也被禁用；MCP 后端工具需要显式管理员启用且仅暴露 allowlist 中的工具名，且必须按 Agent 作用域隔离。

七、自动化测试命令

Quickstart 给出的定向测试命令，覆盖抽象层、Host、Copilot 适配器与集成测试四个层级：

dotnet test test/unit/Elsa.AI.Abstractions.UnitTests/Elsa.AI.Abstractions.UnitTests.csproj dotnet test test/unit/Elsa.AI.Host.UnitTests/Elsa.AI.Host.UnitTests.csproj dotnet test test/unit/Elsa.AI.Copilot.UnitTests/Elsa.AI.Copilot.UnitTests.csproj dotnet test test/integration/Elsa.AI.IntegrationTests/Elsa.AI.IntegrationTests.csproj

以上四个测试工程均存在于仓库中（test/unit 与 test/integration/Elsa.AI.IntegrationTests）。按 plan.md 的规划，单元测试覆盖抽象、工具元数据、授权门控、上下文脱敏、提案生命周期、持久化状态迁移、显式工具启用、重连处理与适配器映射；集成测试覆盖聊天流式输出、工具调用、能力发现、提案应用、租户隔离、持久化审计记录、持久化提案与作用域化趋势分析。

八、Studio 原型参考与落地注意

实现配套的 Studio 模块（Elsa.Studio.AI）之前，先检查原型分支：

git -C ../elsa-extensions-investigation fetch origin feat/ai:refs/remotes/origin/feat/ai git -C ../elsa-extensions-investigation show --stat 93f0e09d71e57f5daff1e2d593f0a51faaa80417 git -C ../elsa-extensions-investigation diff --name-status main..origin/feat/ai -- src/modules/agents/Elsa.Studio.Agents

参考其中的路由、菜单、表格、对话框、校验与 Agent 编辑器约定，但Weaver 的首要 UI 是聊天与提案审查。按 studio-contract.md 的约束，Studio 只负责渲染聊天面板、发送消息与上下文引用、渲染流式事件与提案详情、通过服务端 API 发起 approve/reject/apply；不得调用模型 Provider、托管 AI 运行时、发送 Provider 凭证、在可传引用时发送原始工作流/运行时数据集，也不得在客户端直接应用工作流变更。

九、相关文档导航

本文是 Weaver 平台设计文档集的一部分，按需深入阅读：

• 功能规格与用户故事：spec.md
• 架构决策与备选方案分析：research.md
• 实施计划与模块结构：plan.md
• REST 与流式 API 契约：rest-api.md
• 运行时抽象与工具边界：runtime-contract.md
• Studio 职责与渲染期望：studio-contract.md
• 工具治理元数据与启用策略：tool-governance.md
• 数据模型与实体规则：data-model.md

按上述清单完成 17 步手工验证、四个测试工程跑通、两条 grep 边界检查为空，即意味着 Weaver 的 MVP 路径（服务端托管、引用式上下文、流式事件、提案审查、持久化审计）全部验证通过。

• 后端
• 工作流自动化
• 流程编排
• 低代码