Elsa Weaver Grounding Tools 实战指南：基于 Elsa 数据的能力发现、工具目录与受控提案式工作流编排

后端工作流自动化流程编排低代码【免费下载链接】elsa-coreThe Workflow Engine for .NET项目地址https://gitcode.com/gh_mirrors/el/elsa-core点击查看免费下载导读本文以specs/012-weaver-grounding-tools/quickstart.md为骨架系统讲解 Elsa 中 WeaverAI 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 提供方发送原始工作流或运行时数据而是通过kindreferenceId的附件形式传递上下文引用写操作必须可审查AI 生成的工作流变更一律以提案proposal形式落地由用户明确批准并应用后才真正持久化。1.2 四个关键设计决策来自 research.mdresearch.md 记录了几个对理解整个功能至关重要的取舍决策取舍理由被否决的替代方案用确定性 Elsa 工具而非 Embedding 向量检索活动描述符、工作流定义、实例、事故都是结构化 Elsa 数据确定性检索准确、可测、权限可控全量提示词注入昂贵易泄漏、优先上向量库MVP 场景不需要、让 Copilot 直连数据库破坏租户/RBAC/脱敏边界以 Activity Registry 为创作地基活动版本、输入输出、触发行为、约束决定了草稿能否被验证在提示词里硬编码常见活动知识用户会装自定义活动、直接暴露原始ActivityDescriptor模型侧 DTO 必须稳定、有界、脱敏写操作保持 proposal-onlyAI 生成的工作流变更是高影响操作必须可审计、可回滚、经过基线校验让 Copilot 直接调工作流持久化绕过审查与基线检查、MVP 里加带确认提示的直接操作工具确认 UX 与审计语义未成熟运行时巡检与操作动作分离实例/事故巡检是只读且有即时价值重试、取消、重启、批量操作具有破坏性留待后续显式动作/提案语义把操作工具纳入 MVP扩大风险面、完全不做运行时工具用户确实需要询问实例与失败原因此外能力面必须提供方中立provider-neutralStudio 依据 Elsa 自己发布的能力描述符决定启用哪些控件而不是依赖 GitHub Copilot SDK 的特性开关——这也保证了部分部署如未注册运行时存储时 UI 能给出可理解的禁用状态。二、环境搭建Setup按 quickstart.md 的 Setup 章节验证环境需要四步2.1 启动启用了 AI Host 与 Copilot 的 Elsa ServerElsa Server 需启用 AI 相关特性AI HostElsa.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 RegistryIActivityRegistry/活动描述符、工作流管理/运行时抽象、身份/租户服务端点沿用 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.searchReadOnly按能力、类型、类别、输入/输出、触发行为或文本查询查找已安装活动activities.getDescriptorReadOnly返回单个已安装活动的详细模型安全元数据activities.search的参数字段query、category、canStartWorkflow、inputName、outputName、skip、take结果为GroundingToolResultActivityGroundingSummary。实现位于 Tools/Activities/ActivitiesSearchTool.cs 与 Tools/Activities/ActivityDescriptorTool.cs底层检索服务为 Services/ActivityGroundingSearchService.cs。工作流定义工具族Workflow Definition Tools工具可变性用途workflows.searchReadOnly按名称、状态、活动使用、标签或文本查找已授权的工作流定义workflows.getDefinitionReadOnly返回已授权工作流定义摘要与选定图细节workflows.getDefinitionGraphReadOnly返回面向图的节点/连接数据用于解释、比较或作为提案基线workflows.findUsagesReadOnly查找使用某活动类型、变量名、输入、输出或表达式语法的工作流提案工具族Proposal Tools工具可变性用途workflows.validateDraftProposal验证草稿工作流载荷而不持久化workflows.proposeCreateProposal为新建工作流创建可持久化的可审查提案workflows.proposeUpdateProposal为更新既有工作流版本创建可持久化的可审查提案对应实现为 Tools/Workflows/WorkflowValidateDraftTool.cs、WorkflowProposeCreateTool.cs、WorkflowProposeUpdateTool.cs校验与差异能力由 Services/WorkflowDraftValidationService.cs 与 Services/WorkflowProposalDiffService.cs 提供。运行时工具族Runtime Tools工具可变性用途instances.searchReadOnly按工作流、状态、日期范围、是否含事故或文本查找已授权实例instances.getReadOnly返回模型安全的实例摘要instances.getExecutionHistoryReadOnly返回有界的活动时间线instances.getActivityStateReadOnly返回实例中选定活动的有界状态incidents.searchReadOnly按工作流、实例、活动、时间范围或错误文本查找事故incidents.getReadOnly返回单个事故摘要及证据引用实现位于 Tools/Runtime 目录含InstancesSearchTool、WorkflowInstanceTool、WorkflowInstanceExecutionHistoryTool、WorkflowInstanceActivityStateTool、IncidentsSearchTool、IncidentTool公共基类为RuntimeToolBase。实例/事故到模型安全摘要的映射见 Services/RuntimeGroundingMapper.cs。推迟工具Deferred ToolsMVP 明确不做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.LowProposalDefinition(...)Mutability AIToolMutability.Proposal、DangerLevel AIToolDangerLevel.Medium。这正好呼应 spec.md 的FR-017文档必须说明哪些工具只读、哪些仅提案、哪些是未来管理动作。同一个基类还提供了GetString/GetInt/GetBool/GetObject参数解析辅助方法所有工具执行均为async返回ValueTaskAIToolResult符合 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、TimeRangereferenceId是 Elsa 侧引用而非原始数据——这正是Studio 只传引用与意图的体现。上下文提供者的抽象见 Contracts/IAIContextProvider.cs 与 Context 目录如WorkflowDefinitionContextProvider、WorkflowInstanceContextProvider。4.2 流事件与工具生命周期既有流事件形状保留grounding 工具映射到当前工具生命周期事件tool.startedtool.resultproposal.createdconversation.errorconversation.completed工具结果数据应包含toolName、toolCallId、status、summary以及可选的脱敏结果数据使其既适合 Copilot SDK 工具回调也适合 Studio 的工具活动渲染对应FR-016。事件映射实现位于 Streaming/AIStreamEventMapper.cs。4.3 错误行为状态码含义400非法搜索过滤器、不支持的附件类型、非法草稿载荷403缺少权限、租户不匹配、工具访问被拒绝404活动、工作流、实例、事故或提案不存在409工作流基线过期stale baseline422草稿验证失败503提供方运行时不可用能力端点仍可工作五、手动验证清单Manual Validation以下步骤完整继承自 quickstart.md并补充了每一步的验收要点与对应的工具/契约出处。5.1 能力面与工具面验证步骤 1-4请求GET /ai/capabilities验证 grounding 能力面广告了activities、workflows、proposals、runtime四个工具族对应 Endpoints/AI/Capabilities/Endpoint.cs 中的四个CreateCapability调用请求GET /ai/tools验证在已授权的工作流作者上下文中可用以下工具完整工具清单见 contracts/tool-catalog.mdactivities.searchactivities.getDescriptorworkflows.searchworkflows.getDefinitionworkflows.validateDraftworkflows.proposeCreateworkflows.proposeUpdateinstances.searchinstances.getincidents.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-001Weaver 能基于已安装 Activity Registry 数据回答活动发现问题不出现幻觉活动名。建议同时用canStartWorkflow: truecategory过滤条件复核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-002Weaver 只用已安装活动创建简单工作流提案请求不可用活动时收到阻塞性诊断。提案包含基线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三者的分工如下单元测试test/unit/Elsa.AI.Host.UnitTests含Grounding/、Tools/、AIToolRegistryTests.cs、AIRegistrationTests.cs覆盖工具注册、grounding 摘要映射、脱敏与有界性——对应FR-013/FR-014/FR-016与SC-005在超大元数据或运行时数据测试中所有 grounding 响应均已脱敏且不超配置尺寸集成测试test/integration/Elsa.AI.IntegrationTests验证端到端行为——活动发现不出现幻觉活动名SC-001、提案创建与阻塞诊断SC-002、工作流解释SC-003、失败实例巡检SC-004、Studio 能力发现SC-006构建验证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/ToolsActivities/、Workflows/、Runtime/三个子目录 基类GroundingToolBase.cs与 schema 定义GroundingToolSchemas.cs能力/聊天/工具端点src/modules/Elsa.AI.Host/Endpoints/AICapabilities/、Chat/、Tools/服务层src/modules/Elsa.AI.Host/Services工具注册、活动搜索、草稿验证、提案差异、三类 grounding 映射、审计、流事件映射、编排器AIOrchestrator抽象与模型src/modules/Elsa.AI.AbstractionsContracts/IAITool.cs、IAIContextProvider.cs、IAIProposalStore.csModels/AIToolDefinition.cs、AIGroundingModels.cs、AIProposal.cs、AIContextAttachment.cs配置项src/modules/Elsa.AI.Host/Options/AIHostOptions.csGrounding.ActivityGroundingEnabled、WorkflowGroundingEnabled、ProposalGroundingEnabled、RuntimeGroundingEnabled、SupportedAttachmentKinds、ProposalReviewEnabled等开关都从这里读取特性注册src/modules/Elsa.AI.Host/Features/AIFeature.cs。十、总结Quickstart 验证矩阵验证对象Quickstart 步骤对应契约/需求关键验收点能力面1-2FR-013 / SC-006广告四个 grounding 族工具面3-4FR-016 / FR-01710 个最小工具可用且可变性标注正确活动发现5-6FR-001~003 / SC-001答案只引用已安装活动提案式创作7-8FR-006~008 / SC-002搜索→验证→提案不直接保存工作流解释9-10FR-004 / SC-003引用真实触发器、活动与图结构失败实例巡检11-12FR-009~011 / SC-004引用失败活动、事故消息、时间线与脱敏状态自动化回归目标测试命令plan.md 测试策略单元 集成 单节点构建全部通过至此你已经掌握 Weaver Grounding Tools 从搭建、契约到手动与自动化验证的完整闭环。核心心法只有一句话读走 Elsa 真实数据脱敏、有界、按权限写走可审查提案proposal-only能力面保持提供方中立——这套模式既保证了 AI 回答的准确性也守住了租户、权限与审计的红线。赞分享后端工作流自动化流程编排低代码【免费下载链接】elsa-coreThe Workflow Engine for .NET项目地址https://gitcode.com/gh_mirrors/el/elsa-core点击查看免费下载相关推荐Elsa Weaver Grounding Tools 工具目录契约为 AI Copilot 提供可治理的 Elsa 数据落地工具Elsa Weaver Grounding Tools 工具目录契约为 AI Copilot 提供可治理的 Elsa 数据落地工具 本指南以 specs/01后端工作流自动化流程编排低代码Gods Eye View AISStream WebSocket管道服务端船舶数据摄取全链路详解Gods Eye View AISStream WebSocket管道服务端船舶数据摄取全链路详解 Gods Eye View 是一款运行在浏览器里的间后端工作流自动化流程编排低代码Elsa Weaver Grounding Tools基于活动注册表、工作流定义与运行时实例的受治理 AI 工具族实现指南Elsa Weaver Grounding Tools基于活动注册表、工作流定义与运行时实例的受治理 AI 工具族实现指南 导读 本文以 specs/012后端工作流自动化流程编排低代码上一篇Ant Design 颜色工具包常见问题解答下一篇终极Laravel权限管理数据清理指南高效清理过期权限数据的5个实用方法创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考