cometchat

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CometChat Integration

CometChat 集成

You are the entry point for all CometChat integrations. Follow every step in order.

Trigger phrases:
/cometchat
,
/cometchat 1
,
/cometchat 2
,
/cometchat 3
, "integrate CometChat", "add CometChat", "add chat to my app"

你是所有CometChat集成操作的统一入口，请严格按顺序执行每一步。

触发短语:
/cometchat
,
/cometchat 1
,
/cometchat 2
,
/cometchat 3
, "integrate CometChat", "add CometChat", "add chat to my app"

AUTONOMOUS MODE

自主模式

If ALL of the following are true, proceed without asking for confirmation:

Framework is unambiguously detected (only one framework matches)
Credentials already exist in .env / .env.local (APP_ID, REGION, AUTH_KEY present)
Experience was passed as an argument (e.g. /cometchat 1 or /cometchat conversation-list)

If ANY of the following require clarification, ask once and proceed:

Multiple frameworks detected (e.g. Next.js + Astro in a monorepo)
No .env file and no existing CometChat init in source
No experience specified and cannot be inferred from existing code

DO NOT ask for confirmation on:

Framework version detection (read package.json and decide)
Whether to patch vs create (follow FILE OPERATION RULES from core)
Whether to skip install (read package.json and decide)
Whether CSS is already imported (read the file and decide)

如果以下所有条件都满足，可无需用户确认直接执行：

框架检测结果明确（仅匹配到一个框架）
凭据已存在于.env / .env.local文件中（已包含APP_ID、REGION、AUTH_KEY）
体验类型已作为参数传入（例如/cometchat 1 或 /cometchat conversation-list）

如果以下任意项需要 clarification，询问用户一次后继续执行：

检测到多个框架（例如monorepo中同时存在Next.js + Astro）
不存在.env文件，且源码中没有已有的CometChat初始化代码
未指定体验类型，且无法从现有代码推断

以下情况无需向用户确认：

框架版本检测（直接读取package.json判断即可）
选择修改文件还是新建文件（遵循核心规则中的文件操作规范）
是否跳过依赖安装（读取package.json判断即可）
CSS是否已经导入（读取对应文件判断即可）

Step 1 — Detect Platform

步骤1 — 检测平台

Read the following files (whichever exist) to identify the platform:

File to read	Signal
`package.json`	Web / React Native
`pubspec.yaml`	Flutter
`app/build.gradle` or `build.gradle.kts`	Android
`*.xcodeproj/` (glob) or `Package.swift`	iOS

Detection rules (check in this order):

```
package.json
```
exists → read
```
dependencies
```
and
```
devDependencies
```
:
- ```
"next"
```
  present → Next.js
- ```
"@react-router/dev"
```
  present → React Router v7
- ```
"react-router-dom"
```
  present (no
```
@react-router/dev
```
  ) → React Router v6
- ```
"astro"
```
  present → Astro
- ```
"react-native"
```
  present → React Native (coming soon)
- ```
"expo"
```
  present → Expo (coming soon)
- ```
"react"
```
  present (none of the above) → React.js / Vite
- None of the above → Unknown web project
```
pubspec.yaml
```
exists → Flutter (coming soon)
```
app/build.gradle
```
or
```
build.gradle.kts
```
exists → Android (coming soon)
```
*.xcodeproj
```
or
```
Package.swift
```
exists → iOS (coming soon)
Nothing matched → ask the user: "What platform are you building on?"

读取以下存在的文件来识别平台：

要读取的文件	对应平台
`package.json`	Web / React Native
`pubspec.yaml`	Flutter
`app/build.gradle` 或 `build.gradle.kts`	Android
`*.xcodeproj/` (全局匹配) 或 `Package.swift`	iOS

检测规则（按此顺序检查）：

存在
```
package.json
```
→ 读取
```
dependencies
```
和
```
devDependencies
```
：
- 包含
```
"next"
```
  → Next.js
- 包含
```
"@react-router/dev"
```
  → React Router v7
- 包含
```
"react-router-dom"
```
  （无
```
@react-router/dev
```
  ） → React Router v6
- 包含
```
"astro"
```
  → Astro
- 包含
```
"react-native"
```
  → React Native (即将推出)
- 包含
```
"expo"
```
  → Expo (即将推出)
- 包含
```
"react"
```
  且不满足以上所有条件 → React.js / Vite
- 不满足以上所有条件 → 未知Web项目
存在
```
pubspec.yaml
```
→ Flutter (即将推出)
存在
```
app/build.gradle
```
或
```
build.gradle.kts
```
→ Android (即将推出)
存在
```
*.xcodeproj
```
或
```
Package.swift
```
→ iOS (即将推出)
无匹配项 → 询问用户："你正在基于哪个平台开发？"

Edge Cases

边界情况

Handle these before proceeding to Step 2:

Monorepo with multiple
package.json
files:

Read the
```
package.json
```
nearest to the current working directory first
If the nearest one has no recognizable framework, check one level up
If still ambiguous (e.g., Next.js in
```
apps/web/
```
and Astro in
```
apps/docs/
```
), ask: "I found multiple apps — which one should I add chat to?"

No
package.json
at all:

Ask: "What platform are you building on?" — do not attempt detection
If the user names a supported framework, proceed with that skill

package.json
exists but no recognizable framework (
"react"
not present, no
"next"
, no
"astro"
, etc.):

Say: "I couldn't detect a supported framework in your
```
package.json
```
. CometChat skills currently support React.js, Next.js, React Router, and Astro. Are you using one of these?"
If yes, proceed with the named skill. If no, point to the CometChat docs.

Framework detected but marked "coming soon":

See Step 3 — stop and point to docs. Do not attempt integration.

在进入步骤2之前先处理这些情况：

包含多个
package.json
文件的Monorepo：

优先读取距离当前工作目录最近的
```
package.json
```
如果最近的文件中没有可识别的框架，向上检查一级目录
如果仍然不明确（例如
```
apps/web/
```
是Next.js，
```
apps/docs/
```
是Astro），询问："我检测到多个应用，请问要给哪个应用添加聊天功能？"

完全没有
package.json
文件：

询问："你正在基于哪个平台开发？"——不要尝试自动检测
如果用户说出支持的框架，使用对应技能继续操作

存在
package.json
但没有可识别的框架（无
"react"
、无
"next"
、无
"astro"
等）：

回复："我无法在你的
```
package.json
```
中检测到支持的框架。CometChat技能目前支持React.js、Next.js、React Router和Astro，你是否在使用其中之一？"
如果是，使用用户指定的技能继续操作。如果否，引导用户访问CometChat文档。

检测到的框架标记为"即将推出"：

参考步骤3——停止操作并引导用户访问文档，不要尝试集成。

Example — Full Invocation Flow

示例 — 完整调用流程

This shows what a complete

/cometchat

run looks like from trigger to delegation.

User: /cometchat 1

→ Step 1: Read package.json
  Found: "next": "^15.0.0"
  Detected: Next.js (App Router — src/app/ present)

→ Step 2: Confirm
  "Detected Next.js 15 (App Router) — continuing."

→ Step 3: Support check
  Next.js → supported ✓

→ Step 4: Route placement
  "Where would you like to embed the chat?"
  User: "A dedicated /chat route"

→ Step 4b: Experience
  Experience 1 passed as argument — skip asking

→ Step 5: Credentials
  Read .env.local → NEXT_PUBLIC_COMETCHAT_APP_ID found
  Read .env.local → NEXT_PUBLIC_COMETCHAT_REGION found
  Read .env.local → NEXT_PUBLIC_COMETCHAT_AUTH_KEY found
  No /api/cometchat-token endpoint found
  All credentials inferred — no questions needed

→ Step 6: Delegate to cometchat-react-nextjs
  Passing: experience=1, placement=dedicated-route, credentials=from-.env.local

→ Step 6b: Theming
  "Would you like the chat UI to match your app's visual theme?"
  User: "No"
  → Skip theming

→ Step 7: Post-integration prompt
  "Your chat integration is working with test users. When you're ready
   to connect your real app users, run /cometchat production."

以下展示了

/cometchat

从触发到分配任务的完整运行流程：

User: /cometchat 1

→ Step 1: Read package.json
  Found: "next": "^15.0.0"
  Detected: Next.js (App Router — src/app/ present)

→ Step 2: Confirm
  "Detected Next.js 15 (App Router) — continuing."

→ Step 3: Support check
  Next.js → supported ✓

→ Step 4: Route placement
  "Where would you like to embed the chat?"
  User: "A dedicated /chat route"

→ Step 4b: Experience
  Experience 1 passed as argument — skip asking

→ Step 5: Credentials
  Read .env.local → NEXT_PUBLIC_COMETCHAT_APP_ID found
  Read .env.local → NEXT_PUBLIC_COMETCHAT_REGION found
  Read .env.local → NEXT_PUBLIC_COMETCHAT_AUTH_KEY found
  No /api/cometchat-token endpoint found
  All credentials inferred — no questions needed

→ Step 6: Delegate to cometchat-react-nextjs
  Passing: experience=1, placement=dedicated-route, credentials=from-.env.local

→ Step 6b: Theming
  "Would you like the chat UI to match your app's visual theme?"
  User: "No"
  → Skip theming

→ Step 7: Post-integration prompt
  "Your chat integration is working with test users. When you're ready
   to connect your real app users, run /cometchat production."

Step 2 — Confirm Detection

步骤2 — 确认检测结果

If detection is unambiguous, state what was detected and continue. Only pause for confirmation if ambiguous.

Example (unambiguous): "Detected Next.js (App Router) — continuing." Example (ambiguous): "Detected both Next.js and Astro in this monorepo. Which should I target?"

If the user corrects you, use their answer.

如果检测结果明确，告知用户检测到的内容后继续操作。仅当结果不明确时暂停等待用户确认。

示例（结果明确）："检测到 Next.js (App Router) — 继续操作。" 示例（结果不明确）："我在这个monorepo中同时检测到了Next.js和Astro，请问要针对哪个平台操作？"

如果用户纠正你的检测结果，使用用户提供的答案。

Step 3 — Check UI Kit Support

步骤3 — 检查UI Kit支持情况

Supported now:

React.js / Vite / CRA →
```
cometchat-react-reactjs
```
Next.js →
```
cometchat-react-nextjs
```
React Router v6 / v7 →
```
cometchat-react-react-router
```
Astro →
```
cometchat-react-astro
```

Coming soon (not yet available):

React Native, Expo, Flutter, Android, iOS

If the detected platform is coming soon, say:

"CometChat skills for [platform] are not available yet. You can integrate manually using the CometChat docs. Want me to open the docs for your platform?"

Then stop — do not attempt an integration without a skill file.

当前已支持：

React.js / Vite / CRA →
```
cometchat-react-reactjs
```
Next.js →
```
cometchat-react-nextjs
```
React Router v6 / v7 →
```
cometchat-react-react-router
```
Astro →
```
cometchat-react-astro
```

即将推出（暂不可用）：

React Native, Expo, Flutter, Android, iOS

如果检测到的平台属于即将推出的类别，回复：

"针对 [platform] 的CometChat技能暂未上线。你可以参考CometChat文档手动集成。需要我为你打开对应平台的文档吗？"

随后停止操作——没有对应技能文件时不要尝试集成。

Step 4 — Ask Where to Place the Chat

步骤4 — 询问聊天功能放置位置

Ask the user where they want the chat UI to live:

"Where would you like to embed the chat?"
[A] Dedicated
/chat
route — creates a new page/route at
/chat
. Best for apps where chat is a top-level destination.
[B] Embed in an existing page — adds the chat component directly into a page you already have (e.g.,
/dashboard
,
/support
). Best when chat is a secondary feature alongside other content.

Wait for the user to choose [A] or [B].

If [A]: proceed normally — the framework skill will create a
```
/chat
```
route.
If [B]: ask "Which page/route should I add chat to?" then pass that path to the framework skill. The framework skill will patch that page instead of creating a new
```
/chat
```
route.

Autonomous fallback: If running in non-interactive / automated mode, default to [A] (dedicated

/chat

route) and proceed without asking.

询问用户希望将聊天UI放在哪里：

"你希望将聊天功能嵌入到哪个位置？"
[A] 独立的
/chat
路由 — 在
/chat
路径创建一个新的页面/路由。适合聊天作为顶层功能入口的应用。
[B] 嵌入到现有页面 — 直接将聊天组件添加到你已有的页面中（例如
/dashboard
、
/support
）。适合聊天作为次要功能和其他内容共存的场景。

等待用户选择[A]或[B]。

如果选择**[A]**：正常继续操作，对应框架技能会创建
```
/chat
```
路由。
如果选择**[B]**：询问"我应该将聊天功能添加到哪个页面/路由？"，然后将路径传给对应框架技能，框架技能会修改该页面而不是新建
```
/chat
```
路由。

自主模式 fallback： 如果运行在非交互/自动化模式下，默认选择[A]（独立

/chat

路由），无需询问直接继续。

Step 4b — Present Experience Options

步骤4b — 展示体验选项

If experience was passed as argument (e.g.

/cometchat 1

/cometchat conversation-list

), skip this step and use the specified experience.

Otherwise, ask:

"Which chat experience would you like to integrate?"

Show all three options with descriptions:

[1] Conversation List + Messages A full chat UI. The left panel shows all conversations (users and groups). Clicking one opens the message thread on the right — header, message list, and composer. Best for apps where users need to browse and switch between multiple conversations.

[2] One-to-One Chat Embeds a direct message window with a single hardcoded user or group. No conversation list — just the message header, list, and composer filling the screen. Best for apps where the chat partner is known in advance (e.g., customer support, matched pairs).

[3] Tab-Based Chat The left panel has a bottom tab bar with four tabs: Chats, Calls, Users, Groups. Each tab shows the corresponding CometChat list component. Clicking a conversation or user opens messages on the right. Best for full-featured messenger-style apps.

Wait for the user to choose [1], [2], or [3].

Autonomous fallback: If running in non-interactive / automated mode and no experience was specified:

Default to Experience 1 (Conversation List + Messages)
DO NOT ask the user — proceed immediately
Log the assumption in output: "No experience specified — defaulting to Experience 1 (Conversation List + Messages)"

如果体验类型已经作为参数传入（例如

/cometchat 1

、

/cometchat conversation-list

），跳过此步骤使用指定的体验类型即可。

否则，询问用户：

"你想要集成哪种聊天体验？"

展示全部三个选项及说明：

[1] 会话列表+消息页 完整的聊天UI，左侧面板展示所有会话（用户和群组），点击某个会话后右侧打开消息线程，包含头部、消息列表和输入框。适合用户需要浏览切换多个会话的应用。

[2] 一对一聊天 嵌入和单个指定用户或群组的直接聊天窗口，没有会话列表，仅展示消息头部、列表和输入框占满屏幕。适合聊天对象提前确定的场景（例如客服支持、配对用户聊天）。

[3] 标签页式聊天 左侧面板底部有四个标签：聊天、通话、用户、群组，每个标签展示对应的CometChat列表组件，点击会话或用户后右侧打开消息页。适合功能完整的 messenger 风格应用。

等待用户选择[1]、[2]或[3]。

自主模式 fallback： 如果运行在非交互/自动化模式下且未指定体验类型：

默认选择体验1（会话列表+消息页）
不要询问用户，直接继续操作
在输出中记录假设："未指定体验类型，默认使用体验1（会话列表+消息页）"

Step 5 — Collect Credentials

步骤5 — 收集凭据

Inference order — execute all before asking:

Check

.env

.env.local

.env.development

for

APP_ID

REGION

AUTH_KEY

Grep source files for
```
CometChatUIKit.init
```
— extract credentials from existing call if found
Check for server-side auth token endpoint (
```
/api/auth
```
,
```
/api/cometchat-token
```
) → if found, use
```
loginWithAuthToken()
```
and skip Auth Key entirely
Default
```
LOGIN_UID
```
to
```
cometchat-uid-1
```
if not found (pre-created in every CometChat app)

Only ask the user for values still missing after the steps above.

⚠ Auth Key is for development only. In production use server-generated Auth Tokens.

推断优先级 — 询问用户前先执行全部检查：

检查

.env

.env.local

.env.development

中是否存在

APP_ID

、

REGION

、

AUTH_KEY

在源码中搜索
```
CometChatUIKit.init
```
，如果找到现有调用则从中提取凭据
检查是否存在服务端鉴权token接口（
```
/api/auth
```
、
```
/api/cometchat-token
```
）→ 如果存在，使用
```
loginWithAuthToken()
```
，完全跳过Auth Key
如果未找到
```
LOGIN_UID
```
，默认设为
```
cometchat-uid-1
```
（每个CometChat应用默认预创建的测试用户）

仅向用户询问执行以上步骤后仍然缺失的值。

⚠ Auth Key仅用于开发环境，生产环境请使用服务端生成的Auth Tokens。

Step 6 — Delegate to Platform Skill

步骤6 — 分配给平台对应技能

Based on the detected platform, follow the corresponding skill in full, passing through the chosen experience and credentials:

Platform	Skill to follow
React.js / Vite / CRA	`cometchat-react-reactjs`
Next.js	`cometchat-react-nextjs`
React Router v6 / v7	`cometchat-react-react-router`
Astro	`cometchat-react-astro`

Start from Step 0 of the target skill (idempotency check). Skip steps the target skill says to skip. Apply the experience the user chose in Step 4 (maps to Step 7A / 7B / 7C in the target skill).

Do not ask the user for credentials again — carry them through from Step 5.

基于检测到的平台，完整执行对应技能的流程，传入用户选择的体验类型和凭据：

平台	对应执行的技能
React.js / Vite / CRA	`cometchat-react-reactjs`
Next.js	`cometchat-react-nextjs`
React Router v6 / v7	`cometchat-react-react-router`
Astro	`cometchat-react-astro`

从目标技能的步骤0（幂等性检查）开始执行，跳过目标技能说明要跳过的步骤，应用用户在步骤4选择的体验类型（对应目标技能中的步骤7A / 7B / 7C）。

不要再次向用户询问凭据，直接使用步骤5收集到的内容。

Step 6b — Ask About Theming

步骤6b — 询问主题配置

After the framework skill completes the integration, ask:

"Would you like the chat UI to match your app's visual theme (colors, fonts, border radius)?"

If yes: follow the Theming section in
```
cometchat-react-core
```
— it covers the key CSS variables to override and where to place them.
If no: skip and proceed to Step 7.

Autonomous fallback: Skip theming in non-interactive / automated mode.

框架技能完成集成后，询问用户：

"你希望聊天UI匹配你应用的视觉主题（颜色、字体、圆角）吗？"

如果选择是：执行
```
cometchat-react-core
```
中的主题配置章节，其中说明了需要覆盖的关键CSS变量以及放置位置。
如果选择否：跳过此步骤，进入步骤7。

自主模式 fallback： 非交互/自动化模式下跳过主题配置。

Step 7 — Post-Integration: Go to Production

步骤7 — 集成后：生产环境配置

After the basic integration is complete, offer this follow-up:

"Your chat integration is working with test users. When you're ready to connect your real app users, run
/cometchat production
."

Trigger phrases for production setup:

/cometchat production

, "go to production", "connect real users", "replace cometchat-uid-1", "set up auth tokens", "remove Auth Key"

When triggered:

Detect framework (same as Step 1)
Follow Step 8 of the corresponding framework skill — it covers:
- UID strategy (map your app's user ID → CometChat UID)
- Creating CometChat users at sign-up (REST API)
- Server-side auth token endpoint (framework-specific)
- Updating the client to use
```
loginWithAuthToken()
```
- Removing Auth Key from
```
.env
```
- Testing with two real users in separate windows

基础集成完成后，向用户提供以下后续操作指引：

"你的聊天集成已经可以和测试用户正常运行，当你准备好对接真实应用用户时，运行
/cometchat production
即可。"

生产环境配置触发短语：

/cometchat production

, "go to production", "connect real users", "replace cometchat-uid-1", "set up auth tokens", "remove Auth Key"

当触发生产环境配置时：

检测框架（和步骤1逻辑一致）
执行对应框架技能的步骤8，其中包含：
- UID映射策略（将你应用的用户ID映射为CometChat UID）
- 注册时创建CometChat用户（REST API）
- 服务端鉴权token接口（框架特定实现）
- 更新客户端使用
```
loginWithAuthToken()
```
- 从
```
.env
```
  中移除Auth Key
- 使用两个真实用户在不同窗口测试