用途
本技能用于为 Novu 仪表盘中的新聊天渠道添加第一层设置引导(Layer 1 Setup Guide)。第一层指的是连接渠道本身:开发者需要按照编号步骤创建提供方应用或机器人、在 Novu 中保存凭据、安装并验证集成,然后发送第一条消息。引导过程中会显示“监听中…/已连接”的实时指示器。ResolveAgentIntegrationGuide 在集成未连接时渲染 <Channel>SetupGuide 作为设置视图,连接后切换至“已连接/下一步”视图(该部分由另一个技能 add-channel-whats-next-onboarding 负责)。
主要能力
该设置引导组件由多个构建块组成,均来自 setup-guide-primitives.tsx 和 setup-guide-step-utils.ts:
- SetupStepperRail:垂直编号步骤栏,包裹步骤列。
- SetupStep:单个步骤,包含索引、状态、标题、描述、右侧内容、额外内容、全宽内容、头部插槽、变暗、分区标签、内联分区标签等属性。
- SetupButton:次要轮廓操作按钮,href 打开新标签页,否则触发 onClick;支持 leadingIcon 和 disabled。
- SetupModeToggle + SetupMode('quick' | 'manual'):可选的双路径设置(如 Slack)。
- IntegrationCredentialsSidebar:抽屉,通过通用集成表单保存提供方凭据;支持 onSaveSuccess 和 agentOnboarding。
- ListeningStatus:轮询 listAgentIntegrations,当 connectedAt 被设置时触发 onConnected 和彩带效果。
- deriveStepStatus(i, firstIncomplete):返回 'completed' | 'current' | 'upcoming'。
- hasIntegrationCredentials(credentials):任一字符串凭据保存后返回 true。
连接状态是检测出来的,而非断言。只有当后端在集成链接上设置 connectedAt(基于第一条真实入站消息)时,渠道才被视为“已连接”。保存凭据或完成 OAuth/安装并不代表已连接,这些应保持为独立的本地状态。
使用方式
前置条件
- ChatProviderIdEnum.<Channel> 存在于 @novu/shared 中,且提供方存在于 packages/providers(全新提供方需先询问)。
- 集成可被创建/选择(“添加提供方”流程会传入 integrationId)。
文件清单
- 创建 apps/dashboard/src/components/agents/<channel>-setup-guide.tsx — 导出 <Channel>SetupGuide。可复制最接近的同类文件后重命名,完整模板见 reference.md。
- 编辑 agent-integration-guides/resolve-agent-integration-guide.tsx — 在设置 switch 中渲染 <Channel>SetupGuide ... embedded /> 并设置 setupDisplayName(解析器其余部分由 add-channel-whats-next-onboarding 技能覆盖)。
- (可选)仅当渠道需要 webhook 注册/快速设置/订阅者链接等超出普通凭据保存的功能时,在 @/api/agents 或 @/api/integrations 中添加提供方特定的服务器操作。
组件契约
属性:{ agent: AgentResponse; integrationId: string; stepOffset?: number; onStepsCompleted?: () => void; embedded?: boolean }。stepOffset 默认为 1;Overview 以更高基数挂载引导,Integrations 详情页以 1 挂载。
状态机:
- 通过 useFetchIntegrations() 按 _id === integrationId && providerId === ChatProviderIdEnum.<Channel> 解析 selectedIntegration。
- 跟踪进度:hasIntegrationCredentials(...) 或本地 credentialsSavedLocally,加上任何安装/连接标志。在 useEffect([integrationId]) 中重置所有状态。
- 派生 const base = stepOffset → 计算 firstIncompleteStep → 对每个 SetupStep 使用 deriveStepStatus(stepIndex, firstIncompleteStep)。
- 在 SetupStepperRail 中渲染步骤,然后在 pl-8 包装器中渲染 ListeningStatus,最后渲染 IntegrationCredentialsSidebar。
- ListeningStatus.onConnected → 标记为已连接并调用 onStepsCompleted?.()。
- 同时提供嵌入返回(无 Overview 外壳,供解析器使用)和独立返回。
典型三步配方
- 创建应用/机器人 — SetupButton href 指向提供方控制台。可选:清单(CodeBlock,转义注入值)或调用服务器操作的快速设置输入。
- 在 Novu 中保存凭据 — SetupButton onClick={() => setIsCredentialsSidebarOpen(true)};侧边栏的 onSaveSuccess 翻转 credentialsSavedLocally(并可能触发 webhook 注册等提供方操作)。
- 安装/验证并发送第一条消息 — 提供方连接按钮或可复制说明;ListeningStatus 监视 connectedAt。
约定与注意事项
- 保持“已安装/已保存凭据”与“已连接”为不同状态 — 只有 connectedAt 推进最后一步(参见 Slack 引导中的注释)。
- 服务器状态通过 TanStack Query 管理;变更后使 getAgentIntegrationsQueryKey(currentEnvironment?._id, agent.identifier) 失效。
- 转义注入到清单/片段中的任何值(如 Slack YAML 双引号字符串)。
- 当 integrationId 变化时重置本地状态,避免切换集成时进度泄漏。
- Novu/仪表盘约定:前端使用 type(而非 interface),命名导出,每个 return 前空一行,不使用嵌套三元表达式,动画来自 motion/react。不要构建/启动仪表盘(端口 4201)— 通过诊断检查类型。
构建与验证
不要启动仪表盘 — 通过 Cursor 诊断检查类型。从智能体的 Integrations 标签页添加/打开一个 <Channel> 集成:确认保存凭据时步骤推进、凭据抽屉可打开/保存,并且一旦真实消息到达,“监听中…”变为“已连接”并显示彩带。
适用场景
适用于需要为 Novu 新增聊天渠道(如 Slack、Teams、Telegram、WhatsApp 等)开发第一层设置引导的开发者,尤其是在仪表盘前端添加新的渠道设置流程时。
限制
本文档未提及该技能的收费、价格、平台限制或效果数据,这些信息暂未提供。使用前需确保前置条件满足,并遵循 Novu/仪表盘约定。