customware-support-widget

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Customware Support Widget

Customware 支持聊天组件

Use this skill when the Customware React Router client-only SPA template needs a Customware support chat entry point.

The widget is a third-party browser custom element. In this template, load the widget script in

root.tsx

or the equivalent React Router root file/component where the HTML document structure is defined, and render

<customware-chat>

only in the route or layout where support should appear. The widget owns its Shadow DOM UI, chat runtime, service calls, tool badges, speech input, and page-operation behavior.

For all React code examples, script loading patterns, JSX typing, bubble/full mode examples, metadata, and style options, read references/component-usage.md.

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

该组件是一个第三方浏览器自定义元素。在本模板中，需在定义HTML文档结构的

root.tsx

或等效的React Router根文件/组件中加载组件脚本，且仅在需要显示支持功能的路由或布局中渲染

<customware-chat>

。该组件拥有自身的Shadow DOM UI、聊天运行时、服务调用、工具徽章、语音输入以及页面操作行为。

如需查看所有React代码示例、脚本加载模式、JSX类型定义、气泡/全屏模式示例、元数据及样式选项，请阅读references/component-usage.md。

What It Offers

功能特性

A support chat UI as
```
<customware-chat>
```
.
```
chat-bubble
```
mode for a floating launcher/dialog.
```
full
```
mode for a sidebar, rail, drawer, or split-pane chat region.
Optional visitor metadata through the
```
meta
```
DOM property.
Optional sizing/customization through
```
styleOptions
```
or
```
style-options
```
.
Tool-backed support behavior: read domain/context, list tasks, create tasks, and operate the visible page.
Page operation for user requests like filling forms, selecting options, clicking buttons, replacing values, or submitting visible UI.

以
```
<customware-chat>
```
形式提供支持聊天UI。
```
chat-bubble
```
模式：提供浮动启动器/对话框。
```
full
```
模式：可作为侧边栏、侧边栏轨道、抽屉或分栏聊天区域。
通过
```
meta
```
DOM属性传递可选访客元数据。
通过
```
styleOptions
```
或
```
style-options
```
进行可选尺寸调整/自定义。
工具支持的交互行为：读取域名/上下文、列出任务、创建任务以及操作当前可见页面。
响应用户请求的页面操作：如填写表单、选择选项、点击按钮、替换值或提交可见UI。

When To Use

适用场景

Add support chat to the Customware React Router client-only SPA template.
Place a floating support launcher in an app shell.
Place support chat as a full embedded panel in a layout region.
Allow the support agent to help with visible app UI, such as filling a form on behalf of the user.
Update an existing support widget placement or styling.

For the exact React implementation patterns, use references/component-usage.md.

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

如需查看具体的React实现模式，请使用references/component-usage.md。

When Not To Use

不适用场景

Do not use this skill for server-side rendering work. The target template is client-only React Router SPA mode.
Do not use this skill to build a custom chat UI.
Do not use this skill to iframe the widget.
Do not use this skill to call support chat endpoints directly.
Do not use this skill for non-template React apps or non-React apps unless explicitly asked.
Do not use this skill if
```
orgId
```
or
```
projectId
```
cannot be determined. Fail the task with a clear reason that the required Customware org/project id is missing.

请勿将本技能用于服务端渲染工作。目标模板为纯客户端React Router SPA模式。
请勿使用本技能构建自定义聊天UI。
请勿使用本技能通过iframe嵌入该组件。
请勿使用本技能直接调用支持聊天端点。
除非明确要求，否则请勿将本技能用于非模板React应用或非React应用。
若无法确定
```
orgId
```
或
```
projectId
```
，请勿使用本技能。需明确说明缺少必填的Customware组织/项目ID，终止任务。

Non-Negotiables

硬性要求

Always render the real custom element:
```
<customware-chat>
```
.
Always pass both
```
org-id
```
and
```
project-id
```
.
If either id is unavailable, fail the task with a clear missing-id reason instead of rendering placeholders or asking follow-up questions.
Load
```
https://app.customware.ai/support-widget/customware-chat.js
```
once from
```
root.tsx
```
or the template's equivalent React Router root document shell unless an existing app-level loader already does this.
Do not pass task ids, domain ids, user ids, API tokens, session tokens, auth cookies, or secrets into the component.
Use
```
meta
```
only for optional visitor identity:
```
email
```
and/or
```
name
```
.
Use wrapper CSS,
```
styleOptions
```
, or
```
style-options
```
for sizing. Do not use the native DOM
```
style
```
property as widget configuration.
Tool calls are compact status badges, not buttons.
Page operation is handled inside the widget. Do not add custom click/fill/page-control handlers around it.
Do not hardcode page-operation prompts or values into the host app. The user must type the request into the widget.

始终渲染真实的自定义元素：
```
<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
```
属性用作组件配置。
工具调用为紧凑状态徽章，而非按钮。
页面操作由组件内部处理。请勿在其周围添加自定义点击/填充/页面控制处理程序。
请勿在宿主应用中硬编码页面操作提示或值。用户必须在组件中输入请求。

Implementation Workflow

实现流程

Read references/component-usage.md.
Confirm the React app has
```
orgId
```
and
```
projectId
```
.
Choose the mode:
- ```
chat-bubble
```
  for a floating support launcher/dialog.
- ```
full
```
  for an embedded rail, drawer, split pane, or fixed chat region.
Add the script tag in
```
root.tsx
```
or the React Router root file/component that defines the HTML document
```
<head>
```
, unless it already exists.
Add JSX custom element typings in a
```
.d.ts
```
file when the template does not already know
```
<customware-chat>
```
.
Render
```
<customware-chat>
```
with
```
org-id
```
and
```
project-id
```
in the specific route or layout that needs support.
Set optional
```
meta
```
and
```
styleOptions
```
through a typed React ref when needed.
For full mode, ensure the wrapper/component has a concrete height and internal scrolling belongs to the widget.
For bubble mode, ensure the wrapper is not clipped and has an appropriate
```
z-index
```
.
Validate the resulting React code syntactically and with
```
npm run check
```
when available.

Use references/component-usage.md for complete code examples for each mode.

阅读references/component-usage.md。
确认React应用已获取
```
orgId
```
和
```
projectId
```
。
选择模式：
- ```
chat-bubble
```
  ：浮动支持启动器/对话框。
- ```
full
```
  ：嵌入式侧边栏轨道、抽屉、分栏或固定聊天区域。
在定义HTML文档
```
<head>
```
的
```
root.tsx
```
或React Router根文件/组件中添加脚本标签（若尚未存在）。
若模板未识别
```
<customware-chat>
```
，需在
```
.d.ts
```
文件中添加JSX自定义元素类型定义。
在需要支持功能的特定路由或布局中渲染带有
```
org-id
```
和
```
project-id
```
的
```
<customware-chat>
```
。
必要时，通过类型化React ref设置可选的
```
meta
```
和
```
styleOptions
```
。
对于全屏模式，确保包裹层/组件具有明确高度，且内部滚动由组件自身处理。
对于气泡模式，确保包裹层不会被裁剪，且设置合适的
```
z-index
```
。
对生成的React代码进行语法验证，若有可用的
```
npm run check
```
命令，也需执行该命令进行验证。

如需查看各模式的完整代码示例，请使用references/component-usage.md。

MITB Agent Constraints

MITB Agent约束条件

Do not assume access to Playwright, screenshots, browser DevTools, or visual testing.
Do not claim that the widget was visually tested.
Do not write user-facing status reports inside the generated app.
Validate by code inspection, TypeScript/compile checks, and ensuring the generated React Router/Vite code follows the examples in references/component-usage.md.
If runtime ids are unavailable during generation, fail the task with a clear missing-id reason. If ids are expected to load asynchronously at runtime, gate the component behind
```
orgId && projectId
```
so it never renders with placeholders.

请勿假设可访问Playwright、截图工具、浏览器DevTools或视觉测试工具。
请勿声称已对该组件进行视觉测试。
请勿在生成的应用中编写面向用户的状态报告。
通过代码检查、TypeScript/编译检查进行验证，并确保生成的React Router/Vite代码遵循references/component-usage.md中的示例。
若生成过程中无法获取运行时ID，需明确说明缺少ID的原因并终止任务。若ID需在运行时异步加载，则需通过
```
orgId && projectId
```
控制组件渲染，确保不会渲染占位符。

Do Not Do

禁止操作

Do not create an iframe integration.
Do not rebuild or restyle the widget internals in React.
Do not reach into Shadow DOM or depend on internal class names.
Do not expose tool calls as clickable UI controls.
Do not call the support chat API or page-operation API directly from the host app.
Do not add fallback embed modes.
Do not store secrets, access tokens, private payloads, or auth/session data in widget attributes.
Do not pass arbitrary user/profile objects into
```
meta
```
; pass only optional
```
email
```
and
```
name
```
.
Do not set a fixed height only on an imagined internal message list. Size the whole full-mode host region.
Do not place bubble mode inside clipped or transformed containers unless that behavior is intentional.

请勿创建iframe集成。
请勿在React中重构或重新设置组件内部样式。
请勿访问Shadow DOM或依赖内部类名。
请勿将工具调用暴露为可点击UI控件。
请勿从宿主应用直接调用支持聊天API或页面操作API。
请勿添加备用嵌入模式。
请勿在组件属性中存储机密信息、访问令牌、私有负载或认证/会话数据。
请勿将任意用户/配置文件对象传入
```
meta
```
；仅可传递可选的
```
email
```
和
```
name
```
。
请勿仅为假想的内部消息列表设置固定高度。需为整个全屏模式宿主区域设置尺寸。
请勿将气泡模式放置在被裁剪或变形的容器中，除非该行为是有意为之。