customware-support-widget

Customware 支持组件

当 Customware React Router 纯客户端 SPA 模板需要添加 Customware 支持聊天入口时，使用此技能。

该组件是第三方浏览器自定义元素。在此模板中，应在 root.tsx 或定义 HTML 文档结构的等效 React Router 根文件/组件中加载组件脚本，并且仅在需要显示支持聊天的路由或布局中渲染 <customware-chat>。该组件负责其 Shadow DOM UI、聊天运行时、服务调用、工具徽章、语音输入和页面操作行为。

有关所有 React 代码示例、脚本加载模式、JSX 类型、气泡/完整模式示例、元数据和样式选项，请参阅 references/component-usage.md。

功能

• 以 <customware-chat> 提供支持聊天 UI。
• chat-bubble 模式可显示浮动启动器/对话框。
• full 模式可用于侧边栏、侧栏、抽屉或分栏聊天区域。
• 可通过 meta DOM 属性提供访客元数据。
• 可通过 styleOptions 或 style-options 自定义尺寸/样式。
• 支持工具的支持功能：读取域/上下文、列出任务、创建任务，以及操作当前页面。
• 可根据用户请求操作页面，例如填写表单、选择选项、点击按钮、替换值或提交可见 UI。

如需确切的 React 实现模式，请使用 references/component-usage.md。

适用场景

• 为 Customware React Router 纯客户端 SPA 模板添加支持聊天。
• 在应用外壳中放置浮动支持启动器。
• 在布局区域中放置完整嵌入式支持聊天面板。
• 允许支持 Agent 帮助操作可见的应用 UI，例如代表用户填写表单。
• 更新现有支持组件的位置或样式。

不适用场景

• 不要将此技能用于服务端渲染。目标模板是纯客户端 React Router SPA 模式。
• 不要使用此技能构建自定义聊天 UI。
• 不要使用此技能通过 iframe 嵌入组件。
• 不要使用此技能直接调用支持聊天端点。
• 除非用户明确要求，否则不要将此技能用于非模板 React 应用或非 React 应用。
• 如果无法确定 orgId 或 projectId，不要使用此技能。请以清晰的原因说明所需的 Customware 组织/项目 ID 缺失，并终止任务。

必须遵守的要求

• 始终渲染真实的自定义元素：<customware-chat>。
• 始终同时传入 org-id 和 project-id。
• 如果缺少任一 ID，请以清晰的缺失 ID 原因终止任务，而不是渲染占位符或提出后续问题。
• 除非现有的应用级加载器已完成此操作，否则应从 root.tsx 或模板中等效的 React Router 根文档外壳加载一次 https://app.customware.ai/support-widget/customware-chat.js。
• 不要将任务 ID、域 ID、用户 ID、API 令牌、会话令牌、身份验证 Cookie 或密钥传入组件。
• meta 仅用于可选访客身份信息：email 和/或 name。
• 使用包装器 CSS、styleOptions 或 style-options 设置尺寸。不要将原生 DOM style 属性用作组件配置。
• 工具调用是精简的状态徽章，不是按钮。
• 页面操作由组件内部处理。不要围绕组件添加自定义点击/填充/页面控制处理程序。
• 不要在宿主应用中硬编码页面操作提示词或值。用户必须在组件中输入请求。

实现工作流

1. 阅读 references/component-usage.md。
2. 确认 React 应用具有 orgId 和 projectId。
3. 选择模式：
   • chat-bubble：用于浮动支持入口／对话框。
   • full：用于嵌入式侧栏、抽屉、分屏面板或固定聊天区域。
4. 除非脚本标签已经存在，否则在 root.tsx 或定义 HTML 文档 <head> 的 React Router 根文件／组件中添加脚本标签。
5. 如果模板尚不认识 <customware-chat>，请在 .d.ts 文件中添加 JSX 自定义元素类型声明。
6. 在需要支持的特定路由或布局中，渲染带有 org-id 和 project-id 的 <customware-chat>。
7. 需要时，通过带类型的 React ref 设置可选的 meta 和 styleOptions。
8. 对于 full 模式，确保包装器／组件具有明确的高度，并由微件负责内部滚动。
9. 对于 bubble 模式，确保包装器不会裁切内容，且具有合适的 z-index。
10. 检查生成的 React 代码语法是否正确，并在可用时运行 npm run check 进行验证。

每种模式的完整代码示例，请参阅 references/component-usage.md。

MITB Agent 约束

• 不要假设可以使用 Playwright、截图、浏览器 DevTools 或视觉测试。
• 不要声称已对微件进行视觉测试。
• 不要在生成的应用中编写面向用户的状态报告。
• 通过代码检查、TypeScript／编译检查，并确保生成的 React Router／Vite 代码符合 references/component-usage.md 中的示例来进行验证。
• 如果生成期间无法获取运行时 ID，请以清晰说明缺少 ID 的原因终止任务。如果预期 ID 会在运行时异步加载，请通过 orgId && projectId 控制组件的渲染，确保组件不会使用占位符渲染。

禁止事项

• 不要创建 iframe 集成。
• 不要在 React 中重建或重新设置微件内部样式。
• 不要访问 Shadow DOM，也不要依赖内部类名。
• 不要将工具调用暴露为可点击的 UI 控件。
• 不要从宿主应用直接调用支持聊天 API 或页面操作 API。
• 不要添加备用嵌入模式。
• 不要在微件属性中存储密钥、访问令牌、私有负载或身份验证／会话数据。
• 不要将任意用户／个人资料对象传入 meta；只传入可选的 email 和 name。
• 不要仅为设想中的内部消息列表设置固定高度。应为整个 full 模式宿主区域设置尺寸。
• 除非这是有意的行为，否则不要将 bubble 模式放入会裁切内容或经过变换的容器中。