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

导读

本文以specs/012-weaver-grounding-tools/quickstart.md为骨架，系统讲解 Elsa 中 Weaver（AI Copilot）如何通过"接地工具（Grounding Tools）"访问服务器端真实数据——已安装活动元数据、工作流定义、工作流实例与事故记录——从而在无数据库直接暴露的前提下回答问题、创建提案。读完本文，你将掌握：如何搭建具备 grounding 能力的 Elsa Server、如何验证/ai/capabilities与/ai/tools能力面、四大工具族（activities / workflows / proposals / runtime）的完整目录与调用契约，以及"读只读、写仅提案（proposal-only）"的受控编排模式下如何用手动验证与自动化测试完成端到端验收。

该能力定位在 specs/012-weaver-grounding-tools/spec.md，配套契约见 contracts/rest-api.md 与 contracts/tool-catalog.md，实现源码位于 src/modules/Elsa.AI.Host 与 src/modules/Elsa.AI.Abstractions。

一、Grounding Tools 的目标与设计原则

1.1 目标

Quickstart 开篇即点明目标（Goal）：

验证 Weaver 能够回答基于已安装 Elsa 数据的提问并创建提案，且不暴露数据库或提供方 SDK 的直接访问。

翻译成工程语言就是三条边界：

• 数据只经服务器：Elsa Server 是唯一允许访问工作流存储、运行时存储、Activity Registry、诊断与审计持久化的组件（见 spec.md 的 Assumptions 一节）；
• Studio 只传引用与意图：Studio 不向 AI 提供方发送原始工作流或运行时数据，而是通过kind+referenceId的附件形式传递上下文引用；
• 写操作必须可审查：AI 生成的工作流变更一律以"提案（proposal）"形式落地，由用户明确批准并应用后才真正持久化。

1.2 四个关键设计决策（来自 research.md）

research.md 记录了几个对理解整个功能至关重要的取舍：

此外，能力面必须提供方中立（provider-neutral）：Studio 依据 Elsa 自己发布的能力描述符决定启用哪些控件，而不是依赖 GitHub Copilot SDK 的特性开关——这也保证了部分部署（如未注册运行时存储）时 UI 能给出可理解的禁用状态。

二、环境搭建（Setup）

按 quickstart.md 的 Setup 章节，验证环境需要四步：

2.1 启动启用了 AI Host 与 Copilot 的 Elsa Server

• Elsa Server 需启用 AI 相关特性：AI Host（Elsa.AI.Host）负责工具注册、能力面、提案存储与会话编排；Elsa.AI.Copilot封装 GitHub Copilot SDK 并独占代理循环（agent loop）；
• 依赖关系在 plan.md 的 Technical Context 中列明：核心依赖为 Elsa AI abstractions/host 模块、GitHub.Copilot.SDK（仅限Elsa.AI.Copilot内部）、Activity Registry（IActivityRegistry/活动描述符）、工作流管理/运行时抽象、身份/租户服务，端点沿用 FastEndpoints 模式。

2.2 安装若干活动，至少包含一个触发活动与一个动作活动

这是 grounding 正确性的基础：Weaver 的答案必须只引用当前服务器真实安装的活动。例如 HTTP 相关的Elsa.Http.Endpoint属于触发活动，Email 发送活动属于动作活动。若仓库中有 samples/extensions/workbench 之类的示例宿主，可参照其活动注册方式验证自定义活动场景。

2.3 创建或播种三类种子数据

• 一个已发布的工作流定义（用于验证workflows.search/workflows.getDefinition/ 解释能力）；
• 一个使用了自定义或带版本活动的工作流（用于验证多版本活动描述符的识别，以及"引用了已卸载活动"这类告警场景，见 spec.md Edge Cases）；
• 一个带事故（incident）的失败工作流实例（用于验证运行时巡检：失败活动、事故消息、时间线、脱敏状态）。

2.4 配置持久化的提案与审计存储（仅在验证提案生命周期时需要）

• 提案存储实现IAIProposalStore（契约见 Contracts/IAIProposalStore.cs）；
• 是否具备持久会话与提案能力，会直接影响/ai/capabilities返回的conversationPersistence与proposalReview布尔值——见下方源码证据。

三、能力发现与工具目录契约

3.1GET /ai/capabilities：能力面描述

该端点返回 stream 能力、会话持久化、提案审查、支持的附件种类以及各 grounding 族（family）的可用状态。完整的响应契约见 contracts/rest-api.md，摘要如下：

{ "streaming": true, "conversationPersistence": true, "proposalReview": true, "supportedAttachmentKinds": [ "WorkflowDefinition", "WorkflowInstance", "ActivitySelection", "DiagnosticsScope", "TimeRange" ], "grounding": [ { "name": "activities", "displayName": "Activity catalog", "enabled": true, "toolNames": ["activities.search", "activities.getDescriptor"], "supportedAttachmentKinds": ["ActivitySelection"] } ] }

从源码实现看，Endpoints/AI/Capabilities/Endpoint.cs 会为四个族分别构建能力描述符：

• activities：取决于ActivityGroundingEnabled配置与IActivityRegistry是否注册；
• workflows：取决于WorkflowGroundingEnabled与IWorkflowDefinitionStore是否注册；
• proposals：取决于ProposalGroundingEnabled与是否存在非瞬态提案存储；
• runtime：取决于RuntimeGroundingEnabled与IWorkflowInstanceStore是否注册。

当对应存储未注册时，端点会给出DisabledReasons（如 "Workflow instance store is not registered."），供 Studio 渲染禁用态。注意端点要求Capabilities查看权限（RequirePermission(..., CoreVerbs.View)，见 Permissions/AIResourcePermissions.cs）。

3.2GET /ai/tools：可用工具清单

按 contracts/tool-catalog.md，所有工具都使用 Elsa 自有的AIToolDefinition元数据（见 Models/AIToolDefinition.cs），在服务端执行，名称稳定且带命名空间。工具注册与检索由 Services/AIToolRegistry.cs 承载，工具的公共抽象为IAITool（见 Contracts/IAITool.cs）。

活动工具族（Activity Tools）

activities.search的参数字段：query、category、canStartWorkflow、inputName、outputName、skip、take；结果为GroundingToolResult<ActivityGroundingSummary>。实现位于 Tools/Activities/ActivitiesSearchTool.cs 与 Tools/Activities/ActivityDescriptorTool.cs，底层检索服务为 Services/ActivityGroundingSearchService.cs。

工作流定义工具族（Workflow Definition Tools）

提案工具族（Proposal Tools）

对应实现为 Tools/Workflows/WorkflowValidateDraftTool.cs、WorkflowProposeCreateTool.cs、WorkflowProposeUpdateTool.cs；校验与差异能力由 Services/WorkflowDraftValidationService.cs 与 Services/WorkflowProposalDiffService.cs 提供。

运行时工具族（Runtime Tools）

实现位于 Tools/Runtime 目录（含InstancesSearchTool、WorkflowInstanceTool、WorkflowInstanceExecutionHistoryTool、WorkflowInstanceActivityStateTool、IncidentsSearchTool、IncidentTool，公共基类为RuntimeToolBase）。实例/事故到模型安全摘要的映射见 Services/RuntimeGroundingMapper.cs。

推迟工具（Deferred Tools，MVP 明确不做）

instances.proposeRetry、instances.proposeCancel、instances.proposeRestart、workflows.proposeDelete、workflows.proposePublish、workflows.proposeUnpublish——这些需要未来显式的批准语义（对应功能需求FR-018：初始实现必须排除直接破坏性动作）。

3.3 可变性与危险等级在源码中的体现

从源码结构看，Tools/GroundingToolBase.cs 提供了两个定义辅助方法：

• ReadOnlyDefinition(...)：Mutability = AIToolMutability.ReadOnly、DangerLevel = AIToolDangerLevel.Low；
• ProposalDefinition(...)：Mutability = AIToolMutability.Proposal、DangerLevel = AIToolDangerLevel.Medium。

这正好呼应 spec.md 的FR-017（文档必须说明哪些工具只读、哪些仅提案、哪些是未来管理动作）。同一个基类还提供了GetString/GetInt/GetBool/GetObject参数解析辅助方法，所有工具执行均为async（返回ValueTask<AIToolResult>），符合 plan.md 的异步约束。

四、REST API 契约与流事件

4.1POST /ai/chat：附件驱动的 grounding 请求

聊天请求沿用既有形状，grounding 通过"附件（attachments）+ 可用工具"生效：

{ "conversationId": "conversation-123", "message": "Create a workflow that starts on HTTP POST and sends an email", "agent": "workflow-author", "attachments": [ { "kind": "ActivitySelection", "referenceId": "activities:http,email" } ] }

kind对应契约中的附件类型（WorkflowDefinition、WorkflowInstance、ActivitySelection、DiagnosticsScope、TimeRange），referenceId是 Elsa 侧引用而非原始数据——这正是"Studio 只传引用与意图"的体现。上下文提供者的抽象见 Contracts/IAIContextProvider.cs 与 Context 目录（如WorkflowDefinitionContextProvider、WorkflowInstanceContextProvider）。

4.2 流事件与工具生命周期

既有流事件形状保留，grounding 工具映射到当前工具生命周期事件：

• tool.started
• tool.result
• proposal.created
• conversation.error
• conversation.completed

工具结果数据应包含toolName、toolCallId、status、summary以及可选的脱敏结果数据，使其既适合 Copilot SDK 工具回调，也适合 Studio 的工具活动渲染（对应FR-016）。事件映射实现位于 Streaming/AIStreamEventMapper.cs。

4.3 错误行为

五、手动验证清单（Manual Validation）

以下步骤完整继承自 quickstart.md，并补充了每一步的验收要点与对应的工具/契约出处。

5.1 能力面与工具面验证（步骤 1-4）

1. 请求GET /ai/capabilities；

2. 验证 grounding 能力面广告了activities、workflows、proposals、runtime四个工具族（对应 Endpoints/AI/Capabilities/Endpoint.cs 中的四个CreateCapability调用）；

3. 请求GET /ai/tools；

4. 验证在已授权的工作流作者上下文中可用以下工具（完整工具清单见 contracts/tool-catalog.md）：

   • activities.search
   • activities.getDescriptor
   • workflows.search
   • workflows.getDefinition
   • workflows.validateDraft
   • workflows.proposeCreate
   • workflows.proposeUpdate
   • instances.search
   • instances.get
   • incidents.search

注意：quickstart 只列出这 10 个最小集；完整契约还包含workflows.getDefinitionGraph、workflows.findUsages、instances.getExecutionHistory、instances.getActivityState、incidents.get。可用工具的集合由当前 actor、租户与可选的 agent 作用域决定（contracts/rest-api.md 对GET /ai/tools的说明）。

5.2 活动发现问答（步骤 5-6）

提问："What activities can start a workflow from an HTTP request?"

验收：答案只引用已安装的活动。这条验证对应功能需求FR-001/FR-002/FR-003与成功标准SC-001（"Weaver 能基于已安装 Activity Registry 数据回答活动发现问题，不出现幻觉活动名"）。建议同时用canStartWorkflow: true+category过滤条件复核activities.search的触发能力筛选（参数示例见 contracts/tool-catalog.md）。

5.3 提案式创建工作流（步骤 7-8）

提问："Create a workflow that starts on HTTP POST and sends an email."

验收：Weaver 依次搜索活动 → 验证草稿 → 创建提案，而不是直接保存工作流。这条验证FR-006/FR-007/FR-008与SC-002（"Weaver 只用已安装活动创建简单工作流提案；请求不可用活动时收到阻塞性诊断"）。提案包含：基线（baseline）、草稿载荷、差异（graph diff）、理由（rationale）、警告与验证诊断（见>dotnet test test/unit/Elsa.AI.Host.UnitTests/Elsa.AI.Host.UnitTests.csproj dotnet test test/integration/Elsa.AI.IntegrationTests/Elsa.AI.IntegrationTests.csproj dotnet build Elsa.sln -m:1

三者的分工如下：

1. 单元测试（test/unit/Elsa.AI.Host.UnitTests，含Grounding/、Tools/、AIToolRegistryTests.cs、AIRegistrationTests.cs）：覆盖工具注册、grounding 摘要映射、脱敏与有界性——对应FR-013/FR-014/FR-016与SC-005（"在超大元数据或运行时数据测试中，所有 grounding 响应均已脱敏且不超配置尺寸"）；
2. 集成测试（test/integration/Elsa.AI.IntegrationTests）：验证端到端行为——活动发现不出现幻觉活动名（SC-001）、提案创建与阻塞诊断（SC-002）、工作流解释（SC-003）、失败实例巡检（SC-004）、Studio 能力发现（SC-006）；
3. 构建验证（dotnet build Elsa.sln -m:1）：-m:1强制单进程 MSBuild 节点，便于在受限环境或需要确定性构建顺序时使用。

按 plan.md 的测试策略：xUnit 单元测试在test/unit/Elsa.AI.Host.UnitTests，集成测试在test/integration/Elsa.AI.IntegrationTests；仅当需要播种事故的工作流运行时夹具时才引入组件测试（对应 test/component 目录的能力）。

九、源码地图：去哪里继续深入

如果你要基于本 quickstart 继续开发或审查实现，以下路径是核心入口：

• 工具实现：src/modules/Elsa.AI.Host/Tools（Activities/、Workflows/、Runtime/三个子目录 + 基类GroundingToolBase.cs与 schema 定义GroundingToolSchemas.cs）；
• 能力/聊天/工具端点：src/modules/Elsa.AI.Host/Endpoints/AI（Capabilities/、Chat/、Tools/）；
• 服务层：src/modules/Elsa.AI.Host/Services（工具注册、活动搜索、草稿验证、提案差异、三类 grounding 映射、审计、流事件映射、编排器AIOrchestrator）；
• 抽象与模型：src/modules/Elsa.AI.Abstractions（Contracts/IAITool.cs、IAIContextProvider.cs、IAIProposalStore.cs；Models/AIToolDefinition.cs、AIGroundingModels.cs、AIProposal.cs、AIContextAttachment.cs）；
• 配置项：src/modules/Elsa.AI.Host/Options/AIHostOptions.cs（Grounding.ActivityGroundingEnabled、WorkflowGroundingEnabled、ProposalGroundingEnabled、RuntimeGroundingEnabled、SupportedAttachmentKinds、ProposalReviewEnabled等开关都从这里读取）；
• 特性注册：src/modules/Elsa.AI.Host/Features/AIFeature.cs。

十、总结：Quickstart 验证矩阵

至此，你已经掌握 Weaver Grounding Tools 从搭建、契约到手动与自动化验证的完整闭环。核心心法只有一句话：读走 Elsa 真实数据（脱敏、有界、按权限），写走可审查提案（proposal-only），能力面保持提供方中立——这套模式既保证了 AI 回答的准确性，也守住了租户、权限与审计的红线。

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