# @djangocfg/widget-assistant 中文文档

规范地址：https://npmcn.com/package/%40djangocfg/widget-assistant/

版本：0\.3\.24
npm 元数据更新时间：2026-11-09T14:46:14.838Z
中文译文更新时间：2026-11-12T12:14:14.958Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40djangocfg/widget-assistant
原文对照：https://npmcn.com/package/%40djangocfg/widget-assistant/?lang=original
项目主页：https://djangocfg.com/
源码仓库：https://github.com/markolofsen/django-cfg

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

- 包体积（解压后）：247 kB，81 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react ^19\.0\.0，lucide-react ^1\.68\.0，@djangocfg/api ^2\.1\.644，@djangocfg/i18n ^2\.1\.644，@djangocfg/ui-core ^2\.1\.644
- 首次发布：2026-10-25T06:30:03.247Z
- 最新版本发布：2026-11-09T14:46:14.633Z
- 近 30 天下载量：5568（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：29（近 12 个月 29 个）

## 中文简介

@djangocfg/widget-chat上方的站点助手:SSE线和会话层,持续主机,对接列,浮动按钮和工作表,拼写,帮助和17个内置地块

## 安装

```sh
npm install @djangocfg/widget-assistant
```

也可以使用：`pnpm add @djangocfg/widget-assistant`、`yarn add @djangocfg/widget-assistant`、`bun add @djangocfg/widget-assistant`

## README

# @djangocfg/widget-assistant(英语:

一个站点的助理聊天:SSE线和会话,恒定主机,对接列,浮动按钮和电话表,上方 `@djangocfg/widget-chat`。 。 。 . 它对一个网站一无所知`src/boundary.test.ts` 执行它,所以一个宿主的通行证是很少的 **a 一种语言(来自框架的地语提供者)、适配器、建议及其自己的部件渲染器.** 仅源:主机转接 (`DEFAULT_TRANSPILE_PACKAGES`)和进口 `@djangocfg/widget-assistant/styles` 一次 一次吗.

```tsx
<AssistantChat adapter={adapter} suggestions={suggestions} dataRenderers={renderers} />
```

## 文档

更长的页面居住 [`@docs/`](https://npmcn.com/package/%40djangocfg/widget-assistant/@docs/README.md) (仅存储,不在npm包中):架构,有线合约,Python服务器半个,连接了一个新项目,定制,故障排除. 服务器半个不在 django-cfg 的配置中: 每个产品在代理平面上自己写(`@docs/server.md`) (中文(简体) ).

## 文件夹( 每个任务一个)

| 文件夹 | 任务 |
| --- | --- |
| `wire/` | hTTP 和 SSE 合同:框架、 解析器、 运输、 存储的对话 |
| `stream/` | 一次谈话:适配器、会话钩、失传后调和、故事的脚本传输 |
| `composer/` | 部件的作曲所缺少的,装入其中(`ComposerBehaviour`:口音键,护身符,高度,帮助列表 |
| `messages/` | 信件周围的行: 复制页脚, 重接/ 已安装行 |
| `shell/` | 聊天所在位置: 列框、 码头/ 工作表、 有提示的浮动按钮、 锁定视图、 打开/ 宽度状态 |
| `i18n/` | 17种语言捆绑在一起`locales/`, (中文(简体) ), `useAssistantCopy()`;语言来自 `@djangocfg/i18n`提供商, 部件的复制件也接踵而至 |
| `styles/` | 部件样式表条目、布局、编曲和按钮运动 |

`Host.tsx` (以 `./host`为许多表面保留一个挂载聊天; `AssistantChat.tsx` 组成部件.

## 值得了解的行为

-   **口语密钥.** `⌘D` 编号 : `Ctrl+D` 开始和停止( e)`formatHotkey` 为系统绘制正确的一个). 在发音时, Enter 停止并发送, Escape 停止并保存文本, 从任何地方。 每站会用麦克风打开等场停止变化(450 mss of quiet,最多2.5 s):引擎会报告出词迟到,部件会收起并放下. 引擎是我们的`composer/wholeTranscript.ts`:它重建了浏览器在每个事件结果中的全部记录稿,并在浏览器结束运行时重新启动自己,因为部件对单独结果的缝合只保留了后一字.
-   **战地.** 虽然它只长出高度, 按下作曲家周围的空条会将字段聚焦(仅键盘设备).
-   **盖.** 在键盘设备上打开面板将焦点放入字段;在发送到字段返回后,或者当发送结束一个口令(Enter后开始下一个口令)时,向麦克风返回. 从不打电话.
-   **浮动按钮.** 跳入,在一瞬间后显示一个消息风格的提示(`hint` 道具;文本默认为被捆绑了的一环),然后每隔如此多的时间会有一个环. 没有严密的控制;由主机决定显示的频率.
-   **帮助.** 一发 `?` 在面板头(`AssistantHelp`,由框架和码头显示)打开弹出式中键列表;隐藏在触摸设备上.
-   **时间.** UTC在线上,阅读区和屏幕上的地方. 消息下的时间和复制行出现于徘徊;最新消息保持其视线,但当其答案仍在流出而从未为一空行.

## 电线( 0.2)

一个词汇, `data: {json with type}\n\n`,仅在 `wire/frames.ts`数字 :

| 框架 | 字段 |
| --- | --- |
| `run` | `version`, (中文(简体) ), `thread_id`, (中文(简体) ), `message_id`, (中文(简体) ), `client_id`, (中文(简体) ), `seq` |
| `status` | `phase`数字 : `thinking` | `searching` | `answering` |
| `text_delta` | `delta` |
| `reasoning_delta` | `delta` (可选图层:模型的思维,由部件本身的理性块所绘制) |
| `reasoning_end` | `elapsed_ms?`, (中文(简体) ), `tokens?` (可选:封存思想;否则下个文本、有效载荷或 `done` 已经) |
| `ui_payload` | `kind`, (中文(简体) ), `data`: 主机通过 `dataRenderers[kind]`; 列出在 `payloadKinds` 并报告给 `onUnknownPayload` |
| `done` | `tokens_in`, (中文(简体) ), `tokens_out`, (中文(简体) ), `cost_usd`, (中文(简体) ), `finish_reason`, (中文(简体) ), `replayed?` |
| `error` | `code` (单位:千美元)`unavailable` | `timeout` | `failed`, (中文(简体) ), `message`, (中文(简体) ), `retryable` |

一个未知 `type` 被忽略. `wire/fixtures/events.json` 每个帧中有一个并被安装在服务器侧: 漂移在任一侧都失败测试 。 公众聊天不能前进 `tool_call` 编号 : `tool_result`。 。 。 .

`createTransport` 带 `streamUrl` (路径,或发送的函数,对于路径中的线性id), `buildBody`, (中文(简体) ), `headers`, (中文(简体) ), `streamFetch`, (中文(简体) ), `getToken` (签署)或 `visitorToken` (匿名,以 `x-visitor-token`) (中文(简体) ). 奥米 `api` 从 `useSession` 对于匿名主机:没有获取到任何东西,房间开始为空. `context` 是主机定义的纯记录;软件包从未读取过. `examples/KbAssistant.tsx` 是一个知识库主机,带有 `citations` 有效载荷 测试舱的参考文献.

## 会议(0.3)

会话是服务器上的一条线程 . `useSession({ transport, api, storage, getContext })` 一次显示一个并给主机 `startNew()`, (中文(简体) ), `switchTo(id)`, (中文(简体) ), `sessions` 编号 : `refreshSessions()` 财务报告和审定财务报表 `busy` (一转是流:起动或切换等,停止结束).

-   `api: ThreadApi` 是三次调用主机地图到它的终点: `list(signal)` (首先是最新活动), `create()` (单位:千美元)`POST threads/`,总是一行)和 `load(id, signal)` (掷出) `ThreadNotFoundError` 在404年: 陌生人的或清洗的会话.
-   装入已记住的会话( E)`storage: { read, write }`,主机会选择密钥;读写不能扔出)显示,否则是最新的,否则是空白页. **在第一次发送时创建会话, 绝不装入**;记录稿当时没有被重播,所以现场信息存活.
-   `createTransport({ streamUrl: ({ threadId }) => … })` 在路径中为会话设置位置; `SendInput.threadId` 这是什么 `threadFor` 已经返回.
-   历史是 **屏幕本身**,从对话(Messages, Notes)上画出,而不是随列表而增长的下拉:今天/昨天/每月一个标题,从七个聊天中取出搜索字段,打开聊天标记,点击打开后返回. 挂载 `<AssistantHistory session={session} />` 旁边 `AssistantPortal` (内部) `AssistantHostProvider`打开它从任何控制 `useAssistantHistory().setOpen(true)`· ; `<SessionsMenu session={session} />` 是现成的对头按钮(新聊天、历史 / 回聊天) 。 一个拥有自己的"..."菜单(UI Core)的主机 `MenuBuilder`,作为 `SessionsMenu`是因为 `children` 或进入 `actions`)将"新聊天"保留在那里,并将聊天列表替换为"历史"一行调用 `setOpen(true)`。聊天会挂在屏幕下,所以运行会不停地流出。 语出: `newChat`, (中文(简体) ), `sessions`, (中文(简体) ), `sessionsEmpty`, (中文(简体) ), `sessionsSearch`, (中文(简体) ), `sessionsNoMatch`, (中文(简体) ), `sessionsBack`;标题来自 `Intl`。 。 。 .
-   `<AssistantChat draftRoom={session.thread.session ?? 'new'} />` 将每期未同意的草稿保存在自己的身份证下.
-   没有删除和没有 `clear()`:"清"是"新谈". 保留是服务器的工作.
-   无 `api` (匿名东道主); `startNew()` 只是空出房间.

## 语音(0.3.3)

麦克风菜单总是提供一种口语化语言:访客可以说出任何语言,无论主机UI怎么说. 没有 `speech` 由助理负责 `useSpeechLanguage` 从 `@djangocfg/ui-core/lib/speech-language` (上一次选中, 由此设备上的每一个聊天和标签共享 ) `cfg.chat.speech_language`; 否则浏览器语言拼写中的第一个支持, 页面语言只打破平局; 其它的英语)并 feed `createWholeTranscriptSpeech`。东道主 `speech={{ value, onChange }}` 仍然可以覆盖它(控制模式). 采取器列出基础部件的"Web Speech"目录(61种语言,有方言,可搜索),该目录覆盖了全部17个捆绑的地块(英语:`zh` 是普通话, `no` bokmål);没有免费的"其他BCP-47"字段. 触摸装置会隐藏取取器和麦克风(它们有自己的键盘口令). 一个显示没有采取器的主机运行一个更老版本:升级到0.3.3或更晚.

信件声音( 发送、 回答开始、 回答完成、 错误) 来源 `widget-chat` 且默认的; `messageSounds={false}` 让他们安静, `messageSounds={{ volume, urls }}` 调谐它们.

Dictation start/stop tones被捆绑(Web Audio,没有文件). `sounds={false}` 让他们安静下来; `sounds={{ play(kind) }}` 替换它们.

## 附录

`<AssistantChat attachments={{ upload, kinds, maxFileSize, maxFiles }} />` 添加纸张剪贴,放放和图像粘贴( 默认: 图像/ audio/ text/ document, 10 MB, 5 文件) 。 这些类型是聊天的,从此包再导出. `upload` 是主机的; 默认线体增益 `attachments` 仅当文件被附上时。 细节 : `@djangocfg/widget-chat` `@docs/attachments.md`。 。 。 .

## 从外面问,码头和锁上的房间

-   `askAssistant(text)` 在页面上放出其它处打出的一个快键(一个英雄搜索,一个"讨论这个"按钮)入作曲家,并在作曲家被挂起并允许发送后发送. 一个插槽:在作曲家存在前两次询问保留了最后一个.
-   `<AssistantHeaderActions><ChatMenu session={session} /></AssistantHeaderActions>`,在旁边 `AssistantPortal`,发布头控件; `AssistantFrame` 财务报告和审定财务报表 `ChatDock` 在文件之间没有线条显示( 明确) `actions` (原始内容存档于2018-03-25). prop wins. `AssistantFrame` 财务报告和审定财务报表 `ChatDock` 带 `actions` (标题控制,如“...”菜单):它们坐在一个面板标题的相近处(`ChatPanelHeader` 从 `widget-chat`,由宽柱,平板侧面板和电话平板等同绘制),由薄分取出;每个按钮有ui-core工具提示. `ChatDock` 是平板电脑上的侧面板,基件包的 `ChatSheet` 在电话。 密钥列表( E)`AssistantHelp`)被隐藏在触摸设备上.
-   **一条放置规则,在框架.** `<AssistantFrame docked={open} />`: 从 1280 px 开始,聊天是页面旁边的一列; 范围更窄, 框架本身作为右下方的浮动窗口( tablet; 没有背景, 不是模式)或全屏幕平面( 电话) 打开. 一个主机不能 `ChatDock`,没有媒体查询,也没有第二个表面.
-   **拥有自己的外壳或运输工具的宿主** (呼唤投票自己的路线): `AssistantFrame` `heading`, (中文(简体) ), `help`, (中文(简体) ), `tablet`, (中文(简体) ), `windowBottom`, (中文(简体) ), `stageMin`, (中文(简体) ), `className`, (中文(简体) ), `fill`· ; `AssistantChat` `store`, (中文(简体) ), `capabilities`, (中文(简体) ), `renderers`, (中文(简体) ), `footer`, (中文(简体) ), `composer`, (中文(简体) ), `readOnly`; 条目 `@djangocfg/widget-assistant/shell` 离开图中的SSE层。 全部可选;见 [`@docs/interface.md`](https://npmcn.com/package/%40djangocfg/widget-assistant/@docs/interface.md#a-host-with-its-own-shell-and-transport)。 。 。 .
-   **一个签名的视图,在框架.** `<AssistantFrame requireAuth lock={...} />` (另见 `ChatDock`:一个签名的读者得到聊天,一个读者客户端仍在识别中得到一个空的躯体,其他人得到一个大图标,一个理由和一个 **签名** 按钮,以列全高(无惰性作曲)为中心。 签名以保存当前页面并前往 django-cfg 认证路由(`useAuth` 从 `@djangocfg/api/auth`(a) 同伴依赖; `lock` (单位:千美元)`AssistantLockOptions`数字 : `title`, (中文(简体) ), `body`, (中文(简体) ), `signInLabel`, (中文(简体) ), `icon`, (中文(简体) ), `onSignIn`, (中文(简体) ), `content`)修改单词或替换块. 又导出 : `AssistantAuthGate`, (中文(简体) ), `useAssistantAccess`, (中文(简体) ), `useSignIn`。主机没有锁定的包装.
-   `AssistantLocked` (光景;它的) `composerLabel` 财务报告和审定财务报表 `onComposerClick` )是大门所画出的东西;它只在表面直接使用,没有django-cfg auth.

## 测试

`pnpm --filter @djangocfg/widget-assistant check test`:电线、电流和边界测试,以及 `tsc --noEmit`。 。 。 .

## 从0.1(讲电影框的主持人)

0.2 断线. 在主机服务器中: `run` 携带 `thread_id` 财务报告和审定财务报表 `message_id` (无) `run_id`, (中文(简体) ), `user_message_id`, (中文(简体) ), `assistant_message_id`(三); `status.phase` 实值 `thinking|searching|answering` (单位:千美元)`reading` 财务报告和审定财务报表 `choosing` - 失踪; `done` 没有信件 id; 卡片有效载荷是 `ui_payload {kind: 'film_cards', data}` 和以前一样,但软件包不再验证它,所以注册它: `dataRenderers={{ film_cards: … }}` 财务报告和审定财务报表 `payloadKinds={['film_cards']}`。存储的信息有 `parts: [{kind, data}]` 替换 `widgets: [{kind, ids, caption}]`。 。 。 . `ChatContext` 确是明白的记录 `title` 财务报告和审定财务报表 `browse` 类型是主机定义. `createTransport` 仍然打开 `/apix/chat/v1/stream` 否时 `streamUrl` ; 仅为匿名主机保留默认值; 带有会话集的登录主机 `streamUrl`。字典丢失 `statusReading` 财务报告和审定财务报表 `statusChoosing` 和收益 `statusAnswering`; 捆绑 `lockedBody` 财务报告和审定财务报表 `hint` 不再谈论电影.

## 从0.2(一线, `clear()`(中文(简体) )

0.3 替换单行径 `ThreadApi { load, clear }` 与 `ThreadApi { list, create, load(id, signal) }` (单位:千美元)`useSession` 选择 `storage`),删除 `Session.clear` (使用时 `startNew`),交换词典密钥 `clear`, (中文(简体) ), `clearConfirm`, (中文(简体) ), `clearYes` 页:1 `newChat`, (中文(简体) ), `sessions`, (中文(简体) ), `sessionsEmpty`添加 `ThreadNotFoundError`,则 `not_found` 拒绝代码, `SendInput.threadId`, (中文(简体) ), `AdapterDeps.threadFor` 编号 : `onActive`, (中文(简体) ), `AssistantChat.draftRoom`, (中文(简体) ), `SessionsMenu`, (中文(简体) ), `useAssistantLocale` 财务报告和审定财务报表 `relativeTime`。保留手写会话栏的主机可以删除.

## 常见问题

### @djangocfg/widget-assistant 是什么？

@djangocfg/widget-chat上方的站点助手:SSE线和会话层,持续主机,对接列,浮动按钮和工作表,拼写,帮助和17个内置地块

### 如何安装 @djangocfg/widget-assistant？

在项目目录运行 npm install @djangocfg/widget-assistant，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）、lucide-react（^1\.68\.0）、@djangocfg/api（^2\.1\.644）、@djangocfg/i18n（^2\.1\.644）、@djangocfg/ui-core（^2\.1\.644）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @djangocfg/widget-assistant 支持 TypeScript 吗？

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

### @djangocfg/widget-assistant 支持 ESM 还是 CommonJS？

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

### @djangocfg/widget-assistant 可以商用吗？

@djangocfg/widget-assistant 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @djangocfg/widget-assistant 的下载量有多少？

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

### @djangocfg/widget-assistant 还在维护吗？

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