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

导读

本文以specs/012-weaver-grounding-tools/的设计文档与任务清单为主线，系统介绍 Elsa 工作流引擎中 Weaver/Copilot 的 Grounding Tools（接地工具）体系：如何让 AI 助手基于当前服务器真实安装的活动注册表（Activity Registry）、授权范围内的工作流定义、运行时实例与故障事件（Incidents）来回答问题与起草工作流，而不是依赖模型记忆凭空生成。读完本文，你将掌握该功能的 8 个实施阶段、5 条用户故事对应的 13 个工具（含 7 个 Proposal 类工具）、模型安全 DTO、REST 契约与流式事件、结果脱敏与分页边界机制，以及可复现的测试命令与快速验证路径。

一、功能定位与核心设计决策

1.1 为什么需要 Grounding Tools

在specs/012-weaver-grounding-tools/spec.md中，该特性被描述为“将 Weaver/Copilot 锚定在 Elsa 数据之上”：工作流创作与问题解答的质量，取决于 AI 是否能读到当前服务器上真实安装的活动元数据，而非通用模型记忆里“可能存在的活动”。其核心能力覆盖：

• 查询已安装活动的能力、分类、输入/输出形状；
• 解释、搜索、比较授权范围内的工作流定义；
• 基于真实活动描述与校验，产出“提案”（Proposal）而非直接写库的工作流创建/更新；
• 只读地检查运行时实例与故障事件，并给出带证据的排查结论；
• 向 Studio 暴露供应商无关（provider-neutral）的能力描述，供前端按需启用 UI。

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

specs/012-weaver-grounding-tools/research.md记录了 5 个决定性的技术选型：

架构边界在 plan.md 中进一步明确：Copilot SDK 继续拥有 Agent 循环，Elsa AI Host 提供经过授权、脱敏、限界的工具回调与提案校验；所有数据访问都在服务端完成，Studio 只发送引用与用户意图，绝不把原始工作流/运行时数据发给 AI 提供商。

1.3 数据源与实现位置

从 Elsa.AI.Host 模块文档 可以确认，内置接地工具以IAITool实现注册，读取IActivityRegistry、IWorkflowDefinitionStore、IWorkflowInstanceStore等服务端来源；若某个数据源未注册，工具返回“不可用”结果，同时/ai/capabilities会向 Studio 报告禁用原因。所有工具结果都由AIHostOptions.Grounding限界、脱敏后返回，并经由 AI Host 既有的工具调用路径完成审计。

二、数据模型：模型安全（Model-Safe）DTO 体系

src/modules/Elsa.AI.Abstractions/Models/AIGroundingModels.cs是接地 DTO 的落点，对应>public record ActivityGroundingSummary { public string Type { get; init; } = ""; public int Version { get; init; } public string Namespace { get; init; } = ""; public string Name { get; init; } = ""; public string DisplayName { get; init; } = ""; public string? Description { get; init; } public string Category { get; init; } = ""; public bool IsBrowsable { get; init; } public bool IsTrigger { get; init; } public bool IsContainer { get; init; } public bool IsTerminal { get; init; } public IReadOnlyCollection<ActivityPortSummary> Inputs { get; init; } = []; public IReadOnlyCollection<ActivityPortSummary> Outputs { get; init; } = []; public IReadOnlyCollection<string> Ports { get; init; } = []; public IReadOnlyCollection<string> Constraints { get; init; } = []; }

要点：

• 多版本活动以Version显式表达（对应 spec 的验收场景 2）；
• IsBrowsable用于表达“对租户不可见/不可浏览”的活动，搜索时排除或标记不可用；
• 端口摘要ActivityPortSummary携带Name/DisplayName/Type/Category/IsSensitive/IsRequired/UIHint/DefaultSyntax，其中IsSensitive是脱敏决策的直接依据。

2.2 工作流接地摘要WorkflowGroundingSummary

public record WorkflowGroundingSummary { public string Id { get; init; } = ""; public string DefinitionId { get; init; } = ""; public string? Name { get; init; } public string? Description { get; init; } public int? Version { get; init; } public bool IsLatest { get; init; } public bool IsPublished { get; init; } public bool IsReadonly { get; init; } public string MaterializerName { get; init; } = ""; public string? ProviderName { get; init; } public DateTimeOffset CreatedAt { get; init; } public IReadOnlyCollection<string> ActivityTypes { get; init; } = []; public IReadOnlyCollection<string> Variables { get; init; } = []; public IReadOnlyCollection<string> Inputs { get; init; } = []; public IReadOnlyCollection<string> Outputs { get; init; } = []; }

规则：仅在授权检查通过后返回；大图做摘要并支持按需取详情；缺失的活动描述符以警告形式提示。

2.3 运行时实例与故障摘要

RuntimeInstanceGroundingSummary包含Id/TenantId/DefinitionId/DefinitionVersionId/Version/Status/SubStatus/CorrelationId/Name/IncidentCount/CreatedAt/UpdatedAt/FinishedAt；IncidentGroundingSummary包含WorkflowInstanceId/ActivityId/ActivityNodeId/ActivityType/Message/ExceptionType/ExceptionMessage/Timestamp。两者都是“有界 + 脱敏”视图，变量与输入/输出载荷在进入模型上下文、流式输出与审计存储之前必须脱敏。

2.4 通用结果与能力描述

public record AIGroundingToolResult { public string Summary { get; init; } = ""; public IReadOnlyCollection<JsonObject> Items { get; init; } = []; public int Total { get; init; } public int Returned { get; init; } public bool Truncated { get; init; } public string? Cursor { get; init; } public IReadOnlyCollection<string> Evidence { get; init; } = []; public IReadOnlyCollection<string> Warnings { get; init; } = []; } public record AIGroundingCapabilityDescriptor { public string Family { get; init; } = ""; public string DisplayName { get; init; } = ""; public bool Available { get; init; } public IReadOnlyCollection<string> ToolNames { get; init; } = []; public IReadOnlyCollection<string> AttachmentKinds { get; init; } = []; public IReadOnlyCollection<string> DisabledReasons { get; init; } = []; }

这对应契约中的GroundingToolResult（Summary/Items/TotalCount/HasMore/Cursor/Warnings/EvidenceReferences）与GroundingCapabilityDescriptor（Name/DisplayName/Description/ToolNames/SupportedAttachmentKinds/Enabled/DisabledReason）：大结果集返回摘要 + 游标/过滤，结果同时适用于 Copilot 工具回调和 Studio 工具活动渲染，且不包含任何供应商 SDK 类型。

三、任务蓝图：8 个阶段与 5 条用户故事

tasks.md 将整个落地过程按“共享基础设施 → 用户故事 → 打磨”组织，每阶段都带可独立验证的 Checkpoint。

3.1 Phase 1：Setup（共享基础设施）

• T001在src/modules/Elsa.AI.Abstractions/Models/AIGroundingModels.cs增加接地 DTO 记录（即上文 DTO）；
• T002在src/modules/Elsa.AI.Host/Options/AIHostOptions.cs增加接地结果大小与分页选项；
• T003 [P]在src/modules/Elsa.AI.Host/Features/AIFeature.cs增加接地工具注册扩展帮助器；
• T004 [P]在src/modules/Elsa.AI.Host/Endpoints/AI/Capabilities/Endpoint.cs更新 AI 能力响应模型。

3.2 Phase 2：Foundational（阻塞性前置）

• T005Services/AIGroundingResultFormatter.cs：负载脱敏与尺寸钳制；
• T006Services/ActivityGroundingMapper.cs：活动描述符 → 模型安全摘要；
• T007Services/WorkflowGroundingMapper.cs：工作流图 → 模型安全图摘要；
• T008Services/RuntimeGroundingMapper.cs：运行时实例 → 模型安全摘要；
• T009在Extensions/ServiceCollectionExtensions.cs注册接地服务与内置工具（源码可见TryAddSingleton<AIGroundingResultFormatter>()等注册语句）；
• T010 [P]test/unit/Elsa.AI.Host.UnitTests/Grounding/AIGroundingResultFormatterTests.cs：格式化与脱敏单测；
• T011 [P]test/unit/Elsa.AI.Host.UnitTests/Grounding/AIGroundingCapabilityTests.cs：能力描述符组装单测。

Checkpoint：共享接地服务可用且有测试覆盖。

3.3 用户故事 1（P1，MVP）：发现可用活动

目标：让 Weaver 搜索并检查已安装的 Activity Registry 元数据。独立测试：不借助工作流/运行时工具，仅按能力搜索已安装活动并取回一条描述符。

• 测试：T012 活动描述符映射单测、T013activities.search/activities.getDescriptor集成测试（test/integration/Elsa.AI.IntegrationTests/AIActivityGroundingToolTests.cs）；
• 实现：T014Tools/Activities/ActivitiesSearchTool.cs、T015Tools/Activities/ActivityDescriptorTool.cs、T016Services/ActivityGroundingSearchService.cs（支持按 query、category、type、version、input、output、触发行为过滤）、T017 能力端点暴露活动接地元数据、T018 在AIToolsEndpointTests.cs验证GET /ai/tools能列出活动工具。

Checkpoint：Weaver 能以已安装活动为据进行创作。

3.4 用户故事 2（P2）：理解工作流定义

目标：搜索、取回、解释、比较已授权的工作流定义。独立测试：附加或搜索一个工作流定义并请求图摘要，期间不产生提案。

• 测试：T019 图映射单测、T020 工作流搜索/详情工具集成测试（AIWorkflowGroundingToolTests.cs）；
• 实现：T021Tools/Workflows/WorkflowsSearchTool.cs、T022WorkflowDefinitionTool.cs、T023WorkflowDefinitionGraphTool.cs、T024WorkflowUsageSearchTool.cs（findUsages）、T025 扩展Context/WorkflowDefinitionContextProvider.cs使用模型安全图摘要。

3.5 用户故事 3（P3）：安全工作流创建与更新

目标：基于已安装活动元数据与校验，产出可审阅的提案。独立测试：要求 Weaver 创建/更新工作流，验证输出仅为提案 + 诊断信息。

• 测试：T026WorkflowDraftValidationTests.cs（草稿对活动描述符的校验）、T027AIWorkflowProposalToolTests.cs；
• 实现：T028Services/WorkflowDraftValidationService.cs、T029Tools/Workflows/WorkflowValidateDraftTool.cs、T030WorkflowProposeCreateTool.cs、T031WorkflowProposeUpdateTool.cs、T032Services/WorkflowProposalDiffService.cs（提案图差异）、T033 在草稿校验服务中加入更新提案的陈旧基线检查（stale baseline）。

3.6 用户故事 4（P4）：检查运行时实例与故障

目标：以脱敏的运行时证据检查实例与故障。独立测试：询问一个失败种子实例失败原因，验证输出有证据支撑。

• 测试：T034 运行时映射单测、T035AIRuntimeGroundingToolTests.cs；
• 实现：T036instances.search、T037instances.get、T038instances.getExecutionHistory、T039instances.getActivityState、T040incidents.search、T041incidents.get（均在Tools/Runtime/下，统一继承RuntimeToolBase，其构造注入AIGroundingResultFormatter以保证统一脱敏/限界）、T042 扩展Context/WorkflowInstanceContextProvider.cs纳入有界的故障与活动状态摘要。

3.7 用户故事 5（P5）：向 Studio 暴露能力

目标：让 Studio 在不假设具体供应商的前提下发现并渲染可用的接地功能。独立测试：调用 capabilities 与 tools 端点，验证接地族、附件种类与不可用状态。

• 测试：T043 扩展AICapabilitiesEndpointTests.cs、T044 扩展AIChatEndpointTests.cs覆盖接地工具结果事件；
• 实现：T045 能力端点增加接地能力响应字段、T046 在src/modules/Elsa.AI.Abstractions/Models/AIContextAttachment.cs增加 activity/workflow/runtime/diagnostics/time range 支持附件种类、T047 能力端点增加禁用接地能力的原因说明。

3.8 Phase 8：打磨与横切关注点

• T048 在src/modules/Elsa.AI.Host/README.md增加接地工具文档（已存在，见上文模块文档）；
• T049 更新specs/008-weaver-ai-copilot/quickstart.md的 Weaver 快速开始引用；
• T050~T052 依次运行单元测试、集成测试与dotnet build Elsa.sln -m:1全量验证。

3.9 阶段依赖与并行机会

• Phase 1无依赖；Phase 2依赖 Setup 并阻塞所有用户故事；
• US1是 Foundation 之后的第一个 MVP 故事；US2可紧随 Foundation 启动并受益于 US1 的缺失活动警告；US3依赖 US1 + US2；US4与 US3 相互独立；US5在各类工具具备能力元数据后即可启动；Polish依赖目标故事落地；
• 可并行：T003 与 T004、T010 与 T011、各用户故事内部的测试任务、Foundation 之后的 US2 与 US4。

3.10 实施策略：MVP 优先 + 增量交付

1. 完成 Setup 与 Foundation；
2. 完成 US1 活动发现，验证 Weaver 能搜索已安装活动并回答问题；
3. 在活动/工作流接地可靠后再加入 US3 提案创建/更新；
4. 依次交付：活动接地 → 工作流解释/搜索 → 提案校验与提案创建/更新 → 运行时检查 → 面向所有启用工具族的 Studio 能力元数据。

四、工具目录：13 个命名空间化工具与权限语义

tool-catalog.md 定义了全部工具，统一使用 Elsa 自有的AIToolDefinition元数据并在服务端执行。每个工具标注Mutability：ReadOnly或Proposal。

4.1 活动工具

activities.search（ReadOnly）——按能力、类型、分类、输入/输出、触发行为或文本查询查找已安装活动：

{ "query": "http request", "category": "HTTP", "canStartWorkflow": true, "inputName": "Path", "outputName": "Body", "skip": 0, "take": 20 }

返回GroundingToolResult<ActivityGroundingSummary>。源码实现位于Tools/Activities/ActivitiesSearchTool.cs，依赖ActivityGroundingSearchService执行过滤，AIGroundingResultFormatter负责输出限界。

activities.getDescriptor（ReadOnly）——返回单个已安装活动的详细模型安全元数据：

{ "typeName": "Elsa.Http.Endpoint", "version": 1 }

返回ActivityGroundingSummary，实现见Tools/Activities/ActivityDescriptorTool.cs。

4.2 工作流定义工具（均 ReadOnly）

• workflows.search：按名称、状态、活动使用、标签或文本查询查找已授权的工作流定义；
• workflows.getDefinition：返回已授权定义摘要与选定图细节；
• workflows.getDefinitionGraph：返回面向图的活动与连接数据，供解释、比较或提案基线使用；
• workflows.findUsages：查找使用某活动类型、变量名、输入、输出或表达式语法的工作流。

4.3 提案工具（Mutability: Proposal）

• workflows.validateDraft：不持久化地校验一个草稿工作流负载；
• workflows.proposeCreate：为新工作流创建持久化、可审阅的提案；
• workflows.proposeUpdate：为更新既有工作流版本创建持久化、可审阅的提案。

4.4 运行时工具（均 ReadOnly）

• instances.search：按工作流、状态、日期范围、是否含故障或文本查询查找已授权实例；
• instances.get：返回模型安全的实例摘要；
• instances.getExecutionHistory：返回有界的活动时间线；
• instances.getActivityState：返回选定活动的有界状态；
• incidents.search：按工作流、实例、活动、时间范围或错误文本查找故障；
• incidents.get：返回单条带证据引用的故障摘要。

4.5 明确延期的工具

以下破坏性/操作类工具刻意不在 MVP内，需等待未来的显式审批语义：instances.proposeRetry、instances.proposeCancel、instances.proposeRestart、workflows.proposeDelete、workflows.proposePublish、workflows.proposeUnpublish。

五、REST 契约与流式事件

rest-api.md 在既有 Weaver API 之上扩展，不暴露供应商 SDK 类型。

5.1GET /ai/capabilities

在既有响应中加入接地能力描述符：

{ "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" ] } ] }

grounding[]中每个族都对应一个AIGroundingCapabilityDescriptor，DisabledReasons让 Studio 能解释为什么某个族不可用（例如运行时数据源未注册）。

5.2GET /ai/tools

返回当前 actor、租户与可选 agent 作用域下可用的接地工具，沿用既有AIToolDefinition形状。

5.3POST /ai/chat

请求形状不变，通过附件（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" } ] }

5.4 流式事件

沿用既有事件形状，接地工具映射到工具生命周期事件：tool.started、tool.result、proposal.created、conversation.error、conversation.completed。工具结果数据应包含toolName、toolCallId、status、summary以及可选的已脱敏结果数据——这正是AIGroundingToolResult的设计意图，保证 Copilot 工具回调与 Studio 工具活动渲染都能消费同一份结果。

5.5 错误语义

六、安全与治理边界

6.1 功能需求（FR）中的核心红线

• 权限：工作流定义工具必须在校验tenant、ownership与工作流读权限后才返回数据（FR-005）；运行时工具要求显式的工作流/实例/诊断作用域或时间范围，除非用户有管理分析权限（FR-010）。
• 只写提案：AI 发起的工作流创建/更新在用户显式批准并应用前必须保持“仅提案”（FR-007）；提案应用前草稿必须按已安装活动描述符、图规则、必填输入、表达式兼容性与基线版本进行校验（FR-008）。
• 脱敏：敏感值在进入 Copilot、流向 Studio 流或写入审计记录之前一律脱敏（FR-011）；每次工具调用都要以 actor、租户、会话、工具名、状态与脱敏摘要被审计（FR-015）。
• 限界：工具结果必须可被截断与汇总，使大目录、大图、日志或故障集不超过配置的上下文上限（FR-012）。
• 边界：Studio 契约不得暴露 GitHub Copilot SDK 类型或数据库实体（FR-014）；工具输出需确定化以适配 SDK 回调与 Studio 渲染（FR-016）；MVP 排除删除工作流、取消实例、重启实例、批量重试等直接破坏性动作（FR-018）。

6.2 边缘用例清单

活动元数据缺失/超大/本地化/重复/多版本；工作流引用已卸载的自定义活动；用户未选允许作用域却要求租户级分析；上下文选择与工具执行之间定义/实例被删除；提案基线在应用前过期；运行时变量/输入输出/日志/故障/活动元数据含密钥或敏感配置；工具返回结果过多需分页或汇总；提供商不可用时接地工具与能力端点保持可用。

6.3 提案安全机制（源码确认）

Elsa.AI.Host 模块文档 明确：workflows.proposeCreate与workflows.proposeUpdate只写入IAIProposalStore，不持久化工作流定义；批准与应用是独立的受治理动作。这与 FR-007 完全一致，也是“提案生命周期可审计、无隐藏写库”的实现保证。

七、快速验证：Quickstart 与测试命令

7.1 环境准备

1. 启动启用 AI Host 与 Copilot 的 Elsa Server；
2. 安装若干活动，至少包含一个触发活动与一个动作活动；
3. 创建或种子化：一个已发布的工作流定义、一个使用自定义/多版本活动的工作流、一个带故障的失败实例；
4. 若验证提案生命周期，配置持久化提案与审计存储。

7.2 手动验证步骤

1. 请求GET /ai/capabilities，确认能力广告覆盖活动、工作流、提案与运行时四个工具族；
2. 请求GET /ai/tools，确认授权工作流作者可见：activities.search、activities.getDescriptor、workflows.search、workflows.getDefinition、workflows.validateDraft、workflows.proposeCreate、workflows.proposeUpdate、instances.search、instances.get、incidents.search；
3. 问 Weaver：“What activities can start a workflow from an HTTP request?”，确认回答只引用已安装活动；
4. 问 Weaver：“Create a workflow that starts on HTTP POST and sends an email”，确认 Weaver 依次执行活动搜索、草稿校验，并创建提案而非直接保存工作流；
5. 让 Weaver 解释一个种子工作流定义，确认回答包含真实触发器、活动、输入输出与图结构；
6. 问 Weaver 种子失败实例的失败原因，确认回答引用失败活动、故障消息、时间线与脱敏状态。

7.3 目标测试命令

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

单元测试目录集中在test/unit/Elsa.AI.Host.UnitTests/Grounding/（结果格式化、能力组装、活动/工作流/运行时映射、草稿校验），集成测试位于test/integration/Elsa.AI.IntegrationTests/（活动、工作流、提案、运行时、能力端点、聊天流、工具端点）。性能目标（来自 plan.md，供实测参考）：典型目录下工具元数据/能力响应 p95 低于 250ms，正常负载下首个接地聊天工具结果 3 秒内返回。

八、实施与演进建议

• 按任务清单推进：tasks.md的全部 T001~T052 均标记为已完成，说明当前仓库已具备完整的接地工具实现、契约与测试，可作为二次开发与扩展的直接参照；
• 遵循 MVP 顺序：先验证 US1（活动发现），再叠加 US2（工作流理解）与 US3（提案），US4 与 US5 可并行推进；
• 守住三条边界：读工具默认启用、提案工具需显式启用、破坏性操作留待未来审批语义（参见Elsa.AI.Host/README.md的“proposal tools must be enabled explicitly”）；
• 延续测试纪律：任何新工具族都必须同时具备Grounding/单元测试与Elsa.AI.IntegrationTests集成测试，并在合入前跑通 T050~T052 三组命令。

参考路径速查

• 规格与规划：spec.md、plan.md、research.md、data-model.md、tasks.md、quickstart.md
• 契约：rest-api.md、tool-catalog.md
• DTO 源码：AIGroundingModels.cs
• 宿主实现：Elsa.AI.Host/README.md、ServiceCollectionExtensions.cs、AIGroundingResultFormatter.cs、Tools/Activities/ActivitiesSearchTool.cs、Tools/Workflows/WorkflowDefinitionGraphTool.cs、Tools/Runtime/RuntimeToolBase.cs
• 测试：test/unit/Elsa.AI.Host.UnitTests/Grounding/与test/integration/Elsa.AI.IntegrationTests/

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