# @asteby/metacore-ai-chat 中文文档

规范地址：https://npmcn.com/package/%40asteby/metacore-ai-chat/

版本：7\.0\.0
npm 元数据更新时间：2026-10-17T20:14:28.296Z
中文译文更新时间：2026-11-08T08:32:59.619Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40asteby/metacore-ai-chat
原文对照：https://npmcn.com/package/%40asteby/metacore-ai-chat/?lang=original
源码仓库：https://github.com/asteby/metacore-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：218 kB，99 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react \>=18，react-dom \>=18，lucide-react \>=0\.460，@asteby/metacore-app-providers ^153\.0\.0
- 首次发布：2026-10-12T05:08:38.031Z
- 最新版本发布：2026-10-17T20:14:28.128Z
- 近 30 天下载量：1854（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

Metacore 副驾驶聊天——浮动部件,聊天面板,可拖动的 FAB 和一个可注入的聊天客户端(HTTP,权限,品牌,建议)

## 安装

```sh
npm install @asteby/metacore-ai-chat
```

也可以使用：`pnpm add @asteby/metacore-ai-chat`、`yarn add @asteby/metacore-ai-chat`、`bun add @asteby/metacore-ai-chat`

## README

# @asteby/metacore-ai-chat (英语)

Metacore apps 的副驾驶聊天:浮动部件(可移动 FAB),聊天面板, 启动提示,提议(同意/拒绝)和一个可注入的聊天客户端. 所有特定应用都被注入; 包导入没有商店, API 客户或路线.

## 安装

```bash
pnpm add @asteby/metacore-ai-chat @asteby/metacore-app-providers lucide-react
```

尾风必须扫描软件包(与其他元核UI软件包相同):

```css
@source "../node_modules/@asteby/metacore-ai-chat/dist/**/*.{js,mjs}";
```

## 你注射的东西

| 关切 | 怎么样 |
| --- | --- |
| HTTP 客户端 | `createHttpChatClient(api, { basePath: '/chat' })` 或属于自己的 `ChatClient` |
| 权限 | `permissions={{ canChat, canDecideProposals }}` (单位:千美元)`canChat: false` 隐藏部件并显示拒绝的通知 `CopilotChat`(中文(简体) ) |
| 标记 | `branding={{ name, mascotSkin, avatar }}`;吉祥物是: `Mascot` 从 `@asteby/metacore-app-providers` |
| 建议 | `suggestions={[...]}`,或省略使用 `useAgentSuggestions()` (租户) `agent_suggestions`中性默认值) |
| 复制 | `labels={{ ... }}` 部分覆盖( 西班牙默认值) |

REST默认合同`createHttpChatClient`:

-   `POST {base}/send` `{message, session_id, attachments}` - > (中文) `{success, session_id, reply|response, proposals?}`
-   `GET {base}/sessions`, (中文(简体) ), `GET {base}/history/:id`
-   `POST {base}/proposals/:id/decide` `{approve}`

不同的后端吗? 执行 `ChatClient` (单位:千美元)`send` 需要; `listSessions`, (中文(简体) ), `loadHistory`, (中文(简体) ), `decideProposal` (可选).

## 建议格式

答复可能包含 `proposals`两种形状都得到接受并正常化(`normalizeProposal`(中文(简体) ) 打开 `ChatClient.send`, (中文(简体) ), `loadHistory` 和 HTTP 客户端 :

```jsonc
// A) display shape
{ "id": "p1", "title": "Archivar hallazgo", "summary": "Motivo…", "status": "pending" }
// B) action shape: title = "action · model", summary = compact JSON of payload
{ "id": "p2", "action": "archive", "model": "finding", "payload": { "id": 7 }, "status": "pending" }
```

`id` 需要(字符串或数字,被强迫字符串); `status` 实值 `pending` (默认) `approved` | `rejected`。 。 。 . 明确 `title`编号 :`summary` 胜过所得者。 无行 `id` 或无所显示 被放弃. `action`, (中文(简体) ), `model` 财务报告和审定财务报表 `payload` 保留在规范化的提案上 `decideProposal` 主机可以使用它们.

## 标记回复

AI的答复是安全的 Markdown + GFM(`Markdown`表格(横向卷轴), blockquotes,内置/封装代码,并带有副本按钮,链接和图像. Raw HTML 从未被渲染过, 危险的 URL 放弃方案,打开外部链接 `noopener noreferrer`,图像仅限于http(s)/同源. 未终止的代码栅栏在输入回复时被关闭 。 只使用主题符号样式( 没有打字插件) . 过 `onLinkClick` 改为 `CopilotProvider` 以通过您的路由器( 返回) 路径内应用链接 `true` 处理时).

## 通道:机器人+代理+团队

给部件一个适配器,它就成为一个统一的收件箱。 软件包没有端点或套接字;您绘制了您的后端:

```tsx
const channels: ChannelAdapter = {
  listChannels: () => api.get('/internal-chat/channels').then(toChannels),   // kind: 'bot' | 'agent' | 'team'
  loadMessages: (id) => api.get(`/internal-chat/channels/${id}/messages`).then(toMessages),
  send: (id, body) => api.post(`/internal-chat/channels/${id}/messages`, { body }).then(toMessage),
  markRead: (id) => api.post(`/internal-chat/channels/${id}/read`),
  subscribe: (on) => ws.subscribe('INTERNAL_CHAT_MESSAGE', (e) => on({ type: 'message', message: toMessage(e.payload) })),
}
<CopilotWidget channels={channels} fullscreenHref="/agent" />
```

-   机器人频道(你的) `ChatClient`)首先注入(`includeBot={false}` (删除)。 一个 `agent` 带有自己的频道 `client: ChatClient` 获得完整的 AI 聊天( 提议, 历史); 没有一个, 它由适配器像团队线程一样服务 .
-   未读计数驱动一个 FAB 徽章(即使面板关闭时仍然有效);最后打开的频道被记住.
-   `subscribe` 事件: `message`, (中文(简体) ), `unread`, (中文(简体) ), `presence`, (中文(简体) ), `channels` (etch.

## 全屏幕

页眉的扩展按钮将部件变成一个取景口填充表面(列表+线程相并从 `md` 上升; 电话总是得到它. `Escape` 步骤后退: 扩大 / 浮动 / 关闭. `fullscreenHref` 编号 : `onOpenFullscreen` 添加一个 "开通全景"链接应用与自己的工作空间路线. `hidden` 删除已显示的路由中的部件 .

## 演示徽章

警徽显示何时 `CopilotProvider demo` 编号 : `CopilotWidget demo` 设置,或当后端显示回复时 `demo: true` (单位:千美元)`createHttpChatClient` 读取 `demo` 编号 : `is_demo`) (中文(简体) ). 永远不要把它永远留在 真实的数据.

## 无障碍性和状态

-   `CopilotWidget` 面板为 `role="dialog"` (单位:千美元)`aria-label` =品牌名称, `aria-modal="false"`: 页面仍然可用). 重点转到作曲家的开场,然后回到FAB的关闭; `Escape` 关闭( 任意) `CopilotChat` 与 `onClose`) (中文(简体) ).
-   控件至少是44x44px 有明显的焦点环; 动画荣誉 `prefers-reduced-motion`。 。 。 .
-   离线( E)`navigator.onLine`) 显示状态横幅并禁用发送. 转弯失败时显示提示 `labels.retry`· ; `loadHistory` 财务报告和审定财务报表 `decideProposal` 失败显示警告( 历史带有重试) , 而不是沉默地失败 .
-   `demo` 打开 `CopilotProvider` (或 `CopilotChat`使 `labels.demo` 徽章("Datos destrativos").
-   可选会话选择器 : `<CopilotChat sessions={list} sessionId={id} onSelectSession={setId} />` (获得) `list` 从 `client.listSessions()`) (中文(简体) ).

## 通过

### 业务(ERP)

```tsx
import { CopilotProvider, CopilotWidget, createHttpChatClient } from '@asteby/metacore-ai-chat'
import { api } from '@/lib/api'
import { useAuthStore } from '@/stores/auth-store'

const client = createHttpChatClient(api) // ops exposes /chat/send, /chat/sessions, /chat/history/:id

export function Copilot() {
  const canChat = useAuthStore((s) => s.can('chat.use')) // adapt to your permission check
  return (
    <CopilotProvider client={client} permissions={{ canChat }}>
      <CopilotWidget />
    </CopilotProvider>
  )
}
```

挂载 `<Copilot />` 在认证的布局中替换 `AIChatWidget`。 。 。 . 这个软件包尚未覆盖( 在操作中停留直到后续): 语音/ 活模式, 文件上传、导游、团队对话嵌入、图表/舞蹈嵌入、火花丸. 使用 `CopilotChat` 直接面板( e)`/agent` 页 次) `className="h-full"`。 。 。 .

### 恶作剧

```tsx
<CopilotProvider
  client={createHttpChatClient(api, { basePath: '/api/v1/chat' })}
  branding={{ name: 'Gobi', mascotSkin: 'gobi-navy' }}
  permissions={{ canChat: hasPermission('copilot:use') }}
  suggestions={['Resumen del tablero', 'Hallazgos pendientes de revisión']}
>
  <CopilotWidget defaultPosition={{ bottom: 24, right: 24 }} />
</CopilotProvider>
```

如果gobiernos的后端使用不同的合同,通过习惯 `ChatClient`。 。 。 . 使用 `suggestions` (c) 省去它来继承租户的品牌.

## 还出口

`useChat` (状态机器), `chatReducer`, (中文(简体) ), `useDraggableFab` 编号 : `computePanelLayout`, (中文(简体) ), `useRevealText`,则 `AGENT_*` 地表类常数( 使用主题符号) `--surface-*`, (中文(简体) ), `--elevation-*`) (中文(简体) ).

## 常见问题

### @asteby/metacore-ai-chat 是什么？

Metacore 副驾驶聊天——浮动部件,聊天面板,可拖动的 FAB 和一个可注入的聊天客户端\(HTTP,权限,品牌,建议\)

### 如何安装 @asteby/metacore-ai-chat？

在项目目录运行 npm install @asteby/metacore-ai-chat，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18）、react-dom（\>=18）、lucide-react（\>=0\.460）、@asteby/metacore-app-providers（^153\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @asteby/metacore-ai-chat 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @asteby/metacore-ai-chat 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @asteby/metacore-ai-chat 可以商用吗？

@asteby/metacore-ai-chat 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @asteby/metacore-ai-chat 的下载量有多少？

根据 npm 官方下载统计，@asteby/metacore-ai-chat 在 2026/10/07 – 2026/11/05 这 30 天内被下载 1,854 次，日均约 62 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @asteby/metacore-ai-chat 还在维护吗？

最新版本 7\.0\.0 发布于 2026/10/18（21 天前）；至今共发布 13 个版本，其中过去 12 个月发布了 13 个；首次发布于 2026/10/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。