experience-ui-bundle-agentforce-client-generate

管理 Agentforce Conversation 客户端

此技能与框架无关：同时支持 React 和 Angular UI Bundle 应用。Agentforce 客户端提供两个功能包，它们封装了相同的 Lightning Out glue——请选择与应用框架匹配的包（在步骤 0 中检测）：

框架	功能包	元素	组件符号
React	@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client	<AgentforceConversationClient />	AgentforceConversationClient
Angular	@salesforce/ui-bundle-template-feature-angular-agentforce-conversation-client	<app-agentforce-conversation-client>	AgentforceConversationClientComponent

**硬性约束：**绝 NEVER 创建自定义 Agent、聊天机器人或聊天小组件。所有此类请求都必须通过从相应的功能包导入并渲染现有的、与框架匹配的组件（React <AgentforceConversationClient /> 或 Angular <app-agentforce-conversation-client>）来完成，具体如下文所述。如果组件的 props/inputs 不支持某项需求，请说明这一限制——不要自行设计替代方案。

先决条件

要使组件正常工作，用户必须先配置以下 Salesforce 设置。成功嵌入 Agent 后，务必指出这些先决条件。

受信任的域（仅本地开发时需要）：

• Setup → Session Settings → Trusted Domains for Inline Frames → Add your domain
  • 本地开发：localhost:<dev-server-port> — React（Vite）的默认值为 localhost:5173；Angular 模板可能使用不同的端口（检查应用的开发服务器配置，例如 localhost:5174）。添加应用实际运行所用的端口。
  • **警告：**部署到生产环境前，请移除此受信任域条目。

说明

步骤 0：检测应用框架

在执行任何其他操作之前，先确定目标 UI Bundle 应用使用 React 还是 Angular——这将决定以下每个步骤中的发现、导入、元素语法和属性绑定方式。

针对应用（或 uiBundle）根目录运行随附的检测器。它会以确定性的方式执行检测，并且只打印一个标记——react、angular、ambiguous 或 unknown：

bash "<skill_dir>/scripts/detect-framework.sh" "<app-or-uiBundle-root>"

检测器综合以下信息：根目录及其上级目录中的 angular.json；任何非 node_modules 目录下 package.json 中的 @angular/core / react；以及源文件特征（Angular：*.component.ts、app.routes.ts 或使用 @Component 装饰的类；React：*.tsx / *.jsx）。

根据结果采取行动：

• react 或 angular → 使用对应框架。不要询问用户——检测结果是确定的。
• ambiguous（检测到两个框架）或 unknown（两者都未检测到）→ 继续操作前，询问用户应用使用哪种框架。

在后续步骤中始终使用已确定的框架。

第 1 步：检查组件是否已存在

在所有应用文件（非实现文件）中搜索现有用法。使用与检测到的框架对应的 grep 命令：

React：

grep -r "AgentforceConversationClient" --include="*.tsx" --include="*.jsx" --exclude-dir=node_modules

Angular：

grep -rn "app-agentforce-conversation-client" --include="*.html" --exclude-dir=node_modules
grep -rn "AgentforceConversationClientComponent" --include="*.ts" --exclude-dir=node_modules

**重要：**查找使用该元素的文件（例如，共享 shell/布局、路由组件或功能页面）。对于 Angular，<app-agentforce-conversation-client> 标签位于 *.html 模板中，组件则注册在宿主的 imports: [...] 中。请勿打开组件的实现文件：

• React：AgentforceConversationClient.tsx / AgentforceConversationClient.jsx
• Angular：conversation.ts、conversation.html、__inherit__conversation.ts、agentforce-embed.service.ts

**如果找到多个文件：**询问用户指的是哪个组件文件。在问题澄清前不要继续。

**如果找到：**读取该文件并检查当前的 agentId 值。

Agent ID 验证规则（确定性）：

• 仅当匹配 ^0Xx[a-zA-Z0-9]{15}$ 时才有效
• 含义：以 0Xx 开头，总长度为 18 个字符

判断：

• 如果 agentId 匹配 ^0Xx[a-zA-Z0-9]{15}$，且用户想更新其他 props → 前往第 4 步（更新 props）
• 如果 agentId 匹配 ^0Xx[a-zA-Z0-9]{15}$，且用户要求“嵌入”或“添加”聊天客户端 → 告知用户：“Agentforce Conversation Client 已嵌入 <file>，其 Agent ID 为 <agentId>。您想更换 Agent，还是更新其他 props？”
  • 更换 Agent → 第 2 步
  • 更新 props → 第 4b 步
• 如果 agentId 缺失、为空或不匹配 ^0Xx[a-zA-Z0-9]{15}$ → 继续第 2 步（需要真实 ID）
• 如果未找到 → 继续第 2 步（添加新组件）

如果用户报告错误：

如果用户说组件“无法正常工作”“显示错误”或类似内容，请询问具体的错误消息。然后继续第 2 步，将配置的 agentId 与组织进行交叉核对。

第 2 步：解析并验证 Agent ID

前置条件

1. 验证 sf CLI 是否可用：

   sf --version
   

   如果失败：

   • 告知用户：“未安装 Salesforce CLI（sf）。需要使用它查询您组织中可用的 Agent。”
   • 询问：“您想让我安装它吗？”
     • 是 → 通过 npm install -g @salesforce/cli 安装，然后继续。
     • 否 → “您可以在 Setup → Agentforce Agents 中手动查找 Agent ID：点击 Agent 名称，然后从 URL 中复制 ID。您想现在提供 ID，还是跳过此步骤？”
       • 用户提供 ID → 验证格式（^0Xx[a-zA-Z0-9]{15}$），保存该 ID，然后继续第 3 步。
       • 跳过 → 使用占位符 <YOUR_AGENT_ID>，继续第 4 步。

2. 验证组织连接状态：

   sf org display --json
   

   如果失败：

   • 告知用户：“未找到已通过身份验证的组织。”
   • 询问：“您现在想连接到组织吗？运行 sf org login web 进行身份验证。”
     • 用户完成身份验证 → 重试查询，然后继续。
     • 用户拒绝 → “您可以在 Setup → Agentforce Agents 中手动查找 Agent ID：点击 Agent 名称，然后从 URL 中复制 ID。您想现在提供 ID，还是跳过此步骤？”
       • 用户提供 ID → 验证格式、保存该 ID，然后继续第 3 步。
       • 跳过 → 使用占位符 <YOUR_AGENT_ID>，继续第 4 步。

**注意：**即使用户提供了自己的 agentId，要让 Agent 在运行时正常工作，也必须连接组织。未连接组织的 agentId 将无法使用。

查询所有 Employee Agent

运行 references/agent-id-resolution.md 中定义的 SOQL 查询。

处理结果

完全没有记录：

“此组织中未找到 Employee Agent。请在 Setup → Agentforce Agents 中创建一个。”

询问用户是要手动提供 Agent ID，还是跳过。如果跳过，使用占位符 <YOUR_AGENT_ID> 继续执行第 4 步。

所有 Agent 均未激活：

找到了 Employee Agent，但均未激活：

• Agentforce Sales Agent (0Xxxx000000001dCAA)
• HR Assistant (0Xxxx0000000002BBB)

激活方法：Setup → Agentforce Agents → 点击 Agent 名称 → 在 Agent Builder 中打开 → 点击 Activate。 然后重新运行此步骤。

询问用户是要手动提供 Agent ID，还是跳过。如果跳过，使用占位符 <YOUR_AGENT_ID> 继续执行第 4 步。

存在已激活的 Agent — 路径 A（全新安装／没有现有 agentId）：

仅列出已激活的 Agent 供选择：

聊天组件应使用哪个 Agent？

1. Property Manager Agent (0Xxxx0000000001CAA)
2. HR Assistant (0Xxxx0000000002BBB)

• 只有一个 Agent 时，仍需向用户确认，不要自动选择。
• 如果用户选择了一个 → 保存所选的 Id，供第 4 步使用。
• 如果用户拒绝选择（“skip”、“no”或“I don't want to set one”）→ 接受并进入后续步骤。不要再次询问。对于全新安装，在第 4 步中使用占位符 <YOUR_AGENT_ID>。对于现有项目，保持组件原样。

存在已激活的 Agent — 路径 B（第 1 步中的现有 agentId 已通过格式检查）：

将现有 agentId 与查询结果交叉核对：

• 找到 ID，且 Agent 已激活 → “该 Agent ID 对应 ‘Property Manager Agent’ — 在此组织中处于已激活状态。”继续。
• 找到 ID，但 Agent 未激活 → “已配置的 Agent ‘Sales Agent’ 存在，但未激活。激活方法：Setup → Agentforce Agents → 点击 Agent 名称 → 在 Agent Builder 中打开 → 点击 Activate。或者选择其他已激活的 Agent：” → 显示已激活的 Agent 列表。
• 完全找不到 ID → “已配置的 Agent (0Xxxx...) 在此组织中不存在 — 可能已被删除，或属于其他组织。请选择替代项：” → 显示已激活的 Agent 列表。如果没有可用的已激活 Agent，则显示未激活的 Agent 列表及激活说明。

如果用户报告了错误，即使 Agent 已激活，也要显示其名称，以便用户确认是否为所需的 Agent。

查询错误处理

如果 SOQL 查询失败，直接向用户显示响应中的错误消息。不要猜测解决方法 — 只报告返回的内容。例如：

“查询失败，错误为：[error message from response]。请检查组织权限，或 API 版本是否支持此对象。”

此步骤不会执行的操作

• 不会回退到 GraphQL 或 Tooling API — 仅使用 SOQL
• 不会自动选择（始终向用户确认）
• 不会通过程序激活（只能通过 Setup UI）
• 不会写入文件（这是第 4 步的操作）

第 3 步：标准导入策略

根据检测到的框架使用对应的导入方式。

React — 默认在应用代码中导入组件：

import { AgentforceConversationClient } from "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client";

如果尚未安装该包，请安装：

npm install @salesforce/ui-bundle-template-feature-react-agentforce-conversation-client

Angular — 导入独立组件，并在宿主组件的 imports 数组中注册它（若未注册，Angular 不会渲染任何内容 — React 中没有对应的步骤）：

import { AgentforceConversationClientComponent } from "@salesforce/ui-bundle-template-feature-angular-agentforce-conversation-client";

@Component({
  selector: "app-layout",
  imports: [/* existing imports */, AgentforceConversationClientComponent],
  templateUrl: "./app-layout.html",
})
export class AppLayoutComponent {}

如果尚未安装该包，请安装：

npm install @salesforce/ui-bundle-template-feature-angular-agentforce-conversation-client

本地／组合式导入： 仅在用户明确要求使用经过修改的本地组件，或应用是组合式 UI Bundle 且已在本地继承该功能文件时，才使用本地相对路径导入 — React 组合式应用从 ./components/AgentforceConversationClient 导入；Angular 组合式应用从继承的功能文件（例如 ../../../features/agentforce/__inherit__conversation）导入 AgentforceConversationClientComponent。如果宿主已有此类导入，则沿用现有导入方式，不要改用该包。

不要仅凭文件发现结果推断导入路径。优先在整个代码库中使用一致的导入方式。

第 4 步：添加或更新组件

确定适用哪个子步骤：

• 第 1 步中未找到组件 → 转到 4a（新安装）
• 第 1 步中找到组件 → 转到 4b（更新现有组件）

4a — 新安装

1. 如果用户已指定目标文件，请使用该文件。否则，询问用户："我应该将 Agentforce Conversation Client 添加到哪个文件？" 在确认目标文件之前，请勿继续。（React：一个 *.tsx/*.jsx 组件。Angular：宿主组件的 *.html 模板 — 以及用于导入和 imports: [] 注册的 *.ts 文件。）
2. 阅读目标文件，了解现有导入和模板结构。
3. 添加第 3 步中的导入。Angular 还需要在宿主 @Component({ imports: [...] }) 数组中注册该组件 — 否则该元素不会渲染任何内容。
4. 将该元素作为现有内容的同级元素插入 — 请勿包装或重构现有标记。使用第 2 步中的真实 agentId，或者在用户跳过第 2 步时使用占位符 <YOUR_AGENT_ID>。

React（JSX）：

<AgentforceConversationClient agentId="0Xx8X00000001AbCDE" />

Angular（模板）：

<app-agentforce-conversation-client agentId="0Xx8X00000001AbCDE" />

5. 除非用户明确提出要求，否则不要添加任何其他代码（包装器、布局组件、新函数）。

Angular 属性绑定规则（关键）： 输入名称与 React 相同，但绑定语法不同。裸属性是字符串，因此布尔值、数字和对象必须使用 [prop] 绑定：

• 字符串 → agentId="0Xx..."、width="420px"（普通属性即可）
• 布尔值 → [inline]="true"、[headerEnabled]="false"（不要使用裸属性 inline，它会产生字符串 ""）
• 数字 → [width]="420"
• 对象 → [styleTokens]="{ headerBlockBackground: '#0176d3' }"

完成前验证（Angular）：

• 每个非字符串输入（布尔值/数字/对象）都使用 [prop] 绑定 — 不要使用裸属性 inline/headerEnabled。
• AgentforceConversationClientComponent 已在宿主组件的 @Component({ imports: [...] }) 数组中注册（否则该元素不会渲染任何内容）。

4b — 更新现有组件

1. 阅读第 1 步中确定的文件。
2. 找出现有元素（React 中的 <AgentforceConversationClient ... />，Angular 中的 <app-agentforce-conversation-client ...>）。
3. 仅应用用户要求的更改。规则：
   • 添加用户要求的新属性。
   • 更改用户要求更新的属性值。
   • 保留用户未提及的所有属性和值 — 不要删除、重新排序或重新格式化。
   • 绝不删除组件后再重新创建。
4. 如果触发了第 2 步（交叉核对或重新选择），并解析出新的 Agent ID，请将现有的 agentId 值替换为新值。
5. 如果当前的 agentId 已有效、用户未要求更改，并且第 2 步确认它处于激活状态，则保持不变。

第 4 步后的错误处理

如果用户在组件设置完成后报告错误（例如“无法正常工作”“我看到一条错误”），请转到第 2 步，根据组织验证已配置的 agentId。交叉核对该 Agent 是否处于激活状态、是否存在，以及是否属于已连接的组织。

步骤 5：配置 props

可用 props/输入项（两个框架中的名称完全相同，只有绑定语法不同——参见步骤 4a 中的 Angular 规则）：

• agentId（字符串，必填）- Salesforce Agent ID
• inline（布尔值）- 内嵌模式设为 true，浮动模式则省略
• width（数字 | 字符串）- 例如，420 或 "100%"
• height（数字 | 字符串）- 例如，600 或 "80vh"
• headerEnabled（布尔值）- 显示/隐藏标题栏
• styleTokens（对象）- 用于所有样式（颜色、字体、间距）
• salesforceOrigin（字符串）- 自动解析
• frontdoorUrl（字符串）- 自动解析
• agentLabel（字符串）- Agent 的标题栏标题

示例：

浮动模式（默认）：

// React
<AgentforceConversationClient agentId="0Xx..." />

<app-agentforce-conversation-client agentId="0Xx..." />

带尺寸的内嵌模式：

// React
<AgentforceConversationClient agentId="0Xx..." inline width="420px" height="600px" />

<app-agentforce-conversation-client agentId="0Xx..." [inline]="true" width="420px" height="600px" />

添加或更新 Agent 标签：

// React
<AgentforceConversationClient agentId="0Xx..." agentLabel="<dummy-agent-label>" />

<app-agentforce-conversation-client agentId="0Xx..." agentLabel="<dummy-agent-label>" />

样式规则（强制）：

• 所有视觉自定义（颜色、字体、间距、边框、圆角、阴影）都必须通过 styleTokens prop/输入项完成，无一例外。
• 只能使用下表列出的 token 名称。不得自行创建自定义 token 名称。
• 不得通过 CSS 文件、style 属性、className/class 或包装元素应用样式。这些方式不起作用，组件会忽略它们。
• Angular：使用 [styleTokens]="{ ... }" 绑定（对象）传递 token，而不是使用裸属性。
• 如果用户要求的视觉更改无法映射到下方的 token，请告知他们当前的 token 集不支持此更改。

完整的可用样式 token 列表，请参阅 references/style-tokens.md。

复杂模式请参阅 references/examples.md，了解：

• 侧边栏容器和响应式尺寸
• 深色主题和高级主题组合
• 无标题栏的内嵌模式、计算尺寸
• 完整的宿主组件示例

应避免的常见错误： 请参阅 references/constraints.md，了解：

• 无效的 props（containerStyle、style、className）
• 无效的样式设置方式（CSS 文件、style 标签）
• 不应编辑的文件（实现文件）

常见问题

如果组件未显示或身份验证失败，请参阅 references/troubleshooting.md，了解：

• Agent 激活和部署
• localhost 可信域
• Cookie 限制设置

参考文件索引

文件	何时阅读
references/agent-id-resolution.md	步骤 2 — SOQL 查询结构、响应格式、激活路径、手动查找
references/style-tokens.md	步骤 5 — 所有 UI 区域的完整样式 token 参考
references/examples.md	步骤 5 — 布局模式、尺寸、主题组合、宿主组件示例
references/constraints.md	步骤 4 — 无效的 props、无效的样式设置方式、不应编辑的文件
references/troubleshooting.md	设置后 — Agent 激活、可信域、Cookie 设置