# snail-ai-chat

**Repository Path**: liaoj/snail-ai-chat

## Basic Information

- **Project Name**: snail-ai-chat
- **Description**: snail ai 内置对话页面
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 18
- **Created**: 2026-07-31
- **Last Updated**: 2026-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Snail AI Chat

`snail-ai-chat` 是 Snail AI 的独立嵌入式聊天前端，默认通过 `/api/snail/chat` 网关访问后端。

## 本地运行

```bash
pnpm install
pnpm dev
```

默认访问地址：

```text
http://localhost:9728/
```

## 构建

```bash
pnpm build
```

`build` 会先执行类型检查和 Vite 构建，然后通过 `scripts/embed.mjs` 将 `dist` 复制到：

```text
../snail-ai/snail-ai-agent/snail-ai-agent-chat/snail-ai-agent-chat-starter/src/main/resources/META-INF/chat
```

如果只需要生成 `dist`，使用：

```bash
pnpm build:only
```

## 配置来源

前端启动时会按下面顺序合并配置，后面的配置覆盖前面的配置：

1. 内置默认配置。
2. 当前站点下的 `config.json`，开发时对应 `public/config.json`。
3. 网关接口 `${gatewayPath}/config` 返回的后端 yml 配置。

生产环境建议把业务配置写在后端 yml 中，前端只保留默认兜底配置。

## 后端 yml 配置

配置路径为 `snail-ai.chat`。

```yaml
snail-ai:
  chat:
    enabled: true
    ui:
      page-title: SnailAIChat
      logo: https://snailjob.opensnail.com/logo.svg
      theme-scheme: auto
      locale: zh-CN
      embed:
        enabled: false
        show-header: false
        show-sidebar-user: false
        show-agent-market: false
        compact-input: true
        lock-agent: false
    session:
      token-ttl-seconds: 3600
```

后端会通过 `/api/snail/chat/config` 返回前端可识别的配置：

```json
{
  "gatewayPath": "/api/snail/chat",
  "pageTitle": "SnailAIChat",
  "logo": "https://snailjob.opensnail.com/logo.svg",
  "themeScheme": "auto",
  "locale": "zh-CN",
  "embed": {
    "enabled": false,
    "showHeader": false,
    "showSidebarUser": false,
    "showAgentMarket": false,
    "compactInput": true,
    "lockAgent": false
  }
}
```

### 配置字段

| yml 字段 | 前端字段 | 说明 | 默认行为 |
| --- | --- | --- | --- |
| `ui.page-title` | `pageTitle` | 浏览器标题和顶部标题。 | `Snail AI Chat` |
| `ui.logo` | `logo` | 顶部 logo 和 favicon 地址。 | 空时使用默认机器人图标 |
| `ui.theme-scheme` | `themeScheme` | 主题模式，支持 `light`、`dark`、`auto`，也兼容 `system`。 | 未配置时使用本地缓存，默认浅色 |
| `ui.locale` | `locale` | 界面语言，支持 `zh-CN`、`en-US`，也兼容 `zh`、`en`、`zh_CN`、`en_US`。 | 未配置时跟随本地缓存或浏览器语言 |
| `ui.embed.enabled` | `embed.enabled` | 是否默认使用嵌入模式。 | `false` |
| `ui.embed.show-header` | `embed.showHeader` | 嵌入模式是否显示顶部栏。 | 嵌入模式默认隐藏 |
| `ui.embed.show-sidebar-user` | `embed.showSidebarUser` | 嵌入模式是否显示侧栏底部用户入口。 | 嵌入模式默认隐藏 |
| `ui.embed.show-agent-market` | `embed.showAgentMarket` | 嵌入模式是否显示智能体市场入口。 | 嵌入模式默认隐藏 |
| `ui.embed.compact-input` | `embed.compactInput` | 嵌入模式是否启用紧凑输入框。 | 嵌入模式默认启用 |
| `ui.embed.lock-agent` | `embed.lockAgent` | 是否默认锁定 `agentId` 指定的智能体。 | `false` |
| `session.token-ttl-seconds` | - | 嵌入式会话 token 有效期，单位秒。 | `3600` |

如果某个 `embed` 字段没有配置，前端会使用内置嵌入默认值。

## 前端静态配置

`public/config.json` 可作为本地开发或纯静态部署的兜底配置：

```json
{
  "gatewayPath": "/api/snail/chat",
  "pageTitle": "Snail AI Chat",
  "logo": ""
}
```

也支持下划线和短横线字段名：

```json
{
  "gateway_path": "/api/snail/chat",
  "page_title": "Snail AI Chat"
}
```

`pageTitle`、`logo`、`embed` 也可以放在 `ui` 节点中：

```json
{
  "gatewayPath": "/api/snail/chat",
  "ui": {
    "pageTitle": "Snail AI Chat",
    "logo": "/favicon.svg",
    "theme": "auto",
    "lang": "zh-CN",
    "embed": {
      "enabled": true,
      "showHeader": false
    }
  }
}
```

当 `gatewayPath` 以 `/` 开头时，前端会根据 `VITE_APP_BASE_API` 或当前路径中的 `/snail-chat` 前缀自动补齐部署前缀。

## 环境变量

开发环境使用 `.env.test`：

```ini
VITE_HTTP_PROXY=Y
VITE_CHAT_CLIENT_BASE_URL=http://localhost:8081
VITE_CHAT_BASE_URL=/
VITE_APP_BASE_API=
```

生产构建使用 `.env.prod`：

```ini
VITE_HTTP_PROXY=N
VITE_CHAT_BASE_URL=./
VITE_APP_BASE_API=
```

| 变量 | 说明 |
| --- | --- |
| `VITE_HTTP_PROXY` | 是否启用 Vite 本地代理。`Y` 时代理 `/api/snail/chat`。 |
| `VITE_CHAT_CLIENT_BASE_URL` | 本地代理目标后端地址。 |
| `VITE_CHAT_BASE_URL` | Vite `base`，控制静态资源基础路径。 |
| `VITE_APP_BASE_API` | 部署在后端 context path 下时使用的 API 前缀。 |

## URL 参数

URL 参数主要用于传递用户态信息，或者临时覆盖 yml 默认配置。

### 会话参数

| 参数 | 说明 |
| --- | --- |
| `openId` | 宿主系统传入的平台用户标识，用于创建嵌入式会话。 |
| `trustedCredential` | 可选的可信凭据，后端如配置校验器会使用它校验会话创建请求。 |
| `agentId` | 指定默认选中的智能体。 |
| `theme` / `themeScheme` | 指定主题模式，支持 `light`、`dark`、`auto`、`system`。 |
| `lang` / `locale` | 指定界面语言，支持 `zh-CN`、`en-US` 及 `zh`、`en` 别名。 |

示例：

```text
http://localhost:9728/?openId=user-001&agentId=1&theme=dark&lang=en-US
```

### 临时覆盖参数

布尔参数支持 `1/0`、`true/false`、`yes/no`、`on/off`。这些参数优先级高于后端 yml。

| 参数 | 说明 |
| --- | --- |
| `embed` | 覆盖 `snail-ai.chat.ui.embed.enabled`。 |
| `showHeader` | 覆盖 `snail-ai.chat.ui.embed.show-header`。 |
| `showSidebarUser` | 覆盖 `snail-ai.chat.ui.embed.show-sidebar-user`。 |
| `showAgentMarket` | 覆盖 `snail-ai.chat.ui.embed.show-agent-market`。 |
| `compactInput` | 覆盖 `snail-ai.chat.ui.embed.compact-input`。 |
| `lockAgent` | 覆盖 `snail-ai.chat.ui.embed.lock-agent`。 |

如果后端 yml 已经配置了嵌入模式，iframe 地址可以只保留用户和智能体信息：

```text
http://localhost:9728/?openId=user-001&agentId=1
```

临时覆盖示例：

```text
http://localhost:9728/?openId=user-001&agentId=1&showHeader=1&compactInput=0
```

## 宿主动态切换主题和语言

嵌入到 iframe 后，宿主系统可以通过 `postMessage` 动态同步主题和语言：

```js
iframe.contentWindow?.postMessage(
  {
    type: 'snail-ai-chat:ui',
    payload: {
      theme: 'dark',
      locale: 'en-US'
    }
  },
  'https://your-domain'
);
```

也支持命名空间写法：

```js
iframe.contentWindow?.postMessage(
  {
    snailAiChat: {
      themeScheme: 'auto',
      lang: 'zh-CN'
    }
  },
  'https://your-domain'
);
```

## 宿主页面 iframe 示例

```html
<iframe
  src="https://your-domain/snail-chat/?openId=user-001&agentId=1&theme=auto&lang=zh-CN"
  style="width: 100%; height: 720px; border: 0;"
  allow="clipboard-read; clipboard-write"
></iframe>
```

## 认证说明

页面会先调用 `${gatewayPath}/session` 获取嵌入式 token，后续请求通过后端返回的认证头发送 token。默认认证头为：

```text
Snail-Ai-Auth
```

不要把 token 拼到 URL query 中。