# @aphrody/m3-ai 中文文档

规范地址：https://npmcn.com/package/%40aphrody/m3-ai/

版本：1\.4\.7
npm 元数据更新时间：2026-10-23T03:51:42.469Z
中文译文更新时间：2026-11-08T07:21:42.368Z
软件包许可：Apache-2\.0 AND MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40aphrody/m3-ai
原文对照：https://npmcn.com/package/%40aphrody/m3-ai/?lang=original
项目主页：https://github.com/aphrody-labs/bun-distribution/tree/os/packages/m3-ai#readme
源码仓库：https://github.com/aphrody-labs/bun-distribution

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

- 包体积（解压后）：889 kB，70 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：13 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0，tailwindcss \>=4\.1\.0
- 首次发布：2026-09-25T02:04:01.929Z
- 最新版本发布：2026-10-23T03:51:41.172Z
- 近 30 天下载量：1875（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

材质设计3代理交互组件(工具调用,平分,聊天作曲,工人,任务): SpaceUI (@spacedrive/ai) 在@aphody/m3-primitives上重建.

## 安装

```sh
npm install @aphrody/m3-ai
```

也可以使用：`pnpm add @aphrody/m3-ai`、`yarn add @aphrody/m3-ai`、`bun add @aphrody/m3-ai`

## README

# @aphrody/m3-ai (英语)

材质设计 3 代理界面的回放组件(工具调用卡,打出标记,聊天泡和作曲,模型选择器,任务板)和OpenAI兼容聊天服务器的流媒体客户端,由SpaceUI重建 `@spacedrive/ai`。 。 。 .

```sh
bun add @aphrody/m3-ai @aphrody/m3-primitives @aphrody/m3-motion react react-dom tailwindcss
```

```tsx
import { useState } from "react";
import { ChatComposer, MessageBubble } from "@aphrody/m3-ai";

export function Chat() {
  const [draft, setDraft] = useState("");
  return (
    <>
      <MessageBubble content="Hello" isUser />
      <ChatComposer
        draft={draft}
        onDraftChange={setDraft}
        onSend={() => setDraft("")}
      />
    </>
  );
}
```

许可证:Apache-2.0和麻省理工学院`LICENSE`, (中文(简体) ), `LICENSE.spaceui`) (中文(简体) ). 安装指南 : [文件/材料/立方米/INSTALL.md](https://github.com/aphrody-labs/bun-distribution/blob/os/docs/material/m3/INSTALL.md)。 。 。 .

建造在 `@aphrody/m3-primitives`,M3颜色角色,打字尺,形状和运动,以及材料符号图标。 端点 : `react` 财务报告和审定财务报表 `react-dom` 18或19岁, `tailwindcss` 4.1+ (英语). `@aphrody/m3-ai/ag-ui` 持有AG-UI协议约束.

## CSS 设置

使用 M3 公用事业的 Tailwind 级名称 `@aphrody/m3-theme`导入 然后让Tailwind扫描软件包的输出。 这个 全食谱在 [空间-M3-未来.md](https://github.com/aphrody-labs/bun-distribution/blob/os/docs/material/m3/architecture/design/SPACEUI-M3-FUSION.md), (中文(简体) ), 节"集成":

```css
@import "tailwindcss";
@import "@aphrody/m3-tokens/m3-tokens.css";
@import "@aphrody/m3-theme/spaceui.css";
@import "@aphrody/m3-theme/tailwind.css";

@source "../node_modules/@aphrody/m3-primitives/dist";
@source "../node_modules/@aphrody/m3-ai/dist";
```

装入 材料符号字体一次: 导入 `@aphrody/m3-fonts/fonts-symbols.css`,或打电话 `ensureMaterialSymbols()` 从 `@aphrody/material-web/icon/material-symbols.js`。 。 。 .

## 使用量

```tsx
import { ChatComposer, MessageBubble, ToolCall } from "@aphrody/m3-ai";
import type { ToolCallPair } from "@aphrody/m3-ai";

const pair: ToolCallPair = {
  id: "1",
  name: "file_read",
  argsRaw: '{"path":"README.md"}',
  args: { path: "README.md" },
  resultRaw: '{"text":"# Aphrody"}',
  result: { text: "# Aphrody" },
  status: "completed",
};

export function Conversation({ draft, setDraft, send }: Props) {
  return (
    <>
      <MessageBubble content="List the files" isUser />
      <ToolCall pair={pair} />
      <MessageBubble content="There is one file: `README.md`." isUser={false} />
      <ChatComposer draft={draft} onDraftChange={setDraft} onSend={send} />
    </>
  );
}
```

## 构成部分

| 构成部分 | M3 解剖学 |
| --- | --- |
| `ToolCall` | 外观卡`surface-container-low`中形状):状态图标或圆形指示器, `text-label-large` 工具名、可扩展参数和结果块 `font-code` 打开 `surface-container-highest`错误结果 `error-container`。 。 。 . |
| `Markdown` | M3型号(标题/标题/正文)上的Prose, `font-code` 代码块, `primary` 链接, `outline-variant` 引用和表. `size` 选择体积; `allowHtml` 为可信任的内容启用原始 HTML . |
| `MessageBubble` | 用户转身为 `secondary-container` 气泡 (大形状),助手在表面以标准复制图标按钮为标记下转. |
| `ChatComposer` | 搜索栏解剖学 : `surface-container-high`超大的形状, `text-body-large` 输入,项目避孕药,模型芯片,标准mic图标按钮,填充后发送/停止图标按钮. |
| `ModelSelector` | 药丸触发器打开 M3 菜单(`surface-container`, 外小形状, 第 2 级 : 搜索字段, 提供者区域标题, 48 dp 项, 选择在 `secondary-container`,能力芯片. `ModelOptionList` 财务报告和审定财务报表 `groupModelsByProvider` 单挑名单. |
| `InlineWorkerCard` | 已填入的卡片( E)`surface-container`,中等形状), `text-title-small` 标题、状态芯片、在运行时循环指示器、可扩展记录 `ToolCall`s和马克下. |
| `InlineBranchCard` | 一个思维分支的填充卡:指标或分支图标,状态芯片,可扩展结论. |
| `TaskStatusIcon` | 每个状态的符号:已完成 `success`,正在进行并准备就绪 `primary`,待核准 `warning`积压 `outline`。 。 。 . |
| `TaskPriorityIcon` | 按优先事项分列的编号: `error`高级 `warning`中间 `primary`低调 `outline`。 。 。 . |
| `TaskRow` | Ense M3列表项目(48 dp): `text-body-large` 头条, `text-body-small` 支撑柱,8%悬浮状态层, `secondary-container` 选择、 超时菜单. |
| `TaskList` | 按状态分组的任务:相撞 `text-title-small` 区域标题, `outline-variant` 分裂者. |
| `TaskDetail` | M3 表面任务 : `text-headline-small` 标题、属性网格、子任务作为复选框列表、下标描述、填充和文本按钮. |
| `TaskCreateForm` | 标题和描述文本字段, 优先级选择, 填充 `Create` 文本 `Cancel` 按钮. |

来自 `types.ts`数字 : `pairTranscriptSteps`, (中文(简体) ), `tryParseJson`, (中文(简体) ), `isErrorResult`, (中文(简体) ), `TASK_STATUS_ORDER`, (中文(简体) ), `TASK_STATUS_LABEL`, (中文(简体) ), `TASK_PRIORITY_LABEL`,以及记录、任务和 模型类型.

## 本地聊天

在 OpenAI 兼容服务器( lama- server, vLLM, Apprody 网关) 上聊天 ,没有可见的字符串硬码:

| 导出 | 作用 |
| --- | --- |
| `ChatLabels`, (中文(简体) ), `chatLabelsFr` 编号 : `chatLabelsEn` 编号 : `chatLabelsJa`, (中文(简体) ), `resolveChatLabels`, (中文(简体) ), `formatLabel` | 每个可见的字符串和 aria- label 都有一个词典 。 每个聊天组件都使用 `labels?: Partial<ChatLabels>`; 缺少的密钥会回到英语上. |
| `streamChatCompletion`, (中文(简体) ), `createSseParser`, (中文(简体) ), `parseChatCompletionChunk`, (中文(简体) ), `chatReducer`, (中文(简体) ), `ChatStreamError` | 纯流客户端 `POST <baseUrl>/chat/completions` (单位:千美元)`stream: true`:SSE 框架、内容 / `reasoning_content` /工具召唤三角洲, `finish_reason`顶级 `citations` 财务报告和审定财务报表 `refusal`网络故障和404/502/503/504 `unavailable`。 。 。 . |
| `useOpenAIChat({ baseUrl, model, fetch?, headers?, initialMessages?, preamble?, body? })` | 反应钩子 : `{ messages, send, stop, status, error, reset, setMessages }`, (中文(简体) ), `status` 实值 `idle`, (中文(简体) ), `streaming`, (中文(简体) ), `error` 或者说 `unavailable`。 。 。 . |
| `ConversationList` | 导航-绘图列表:新对话,可选搜索,重命名/删除回调,空状态,本地化日期. |
| `ModelUnavailable` | 下载 / 装入 / 不可用状态 . |
| `CitedMarkdown`, (中文(简体) ), `CitationChip`, (中文(简体) ), `CitationList`, (中文(简体) ), `RefusalNotice` | 基础答案 : `[n]` 标记为芯片,编号来源,"来源中未建立的"通知. `MessageBubble` 带 `citations` 财务报告和审定财务报表 `refusal` 直接说. |
| `MemoryPanel` | 通过逐项删除和确认的"清除所有"来保存记忆(`confirmClear` 输入您自己的对话框 . |
| `ChatIcon` | 聊天图标作为内置材料符号SVG:聊天组件不需要图标字体. |

`Markdown` (和 `MessageBubble`, (中文(简体) ), `CitedMarkdown`开放外部链接 `target="_blank" rel="noopener noreferrer"` 并带 `onLinkClick(href, event)` (电话) `event.preventDefault()` 从 Tauri 网页视图打开系统浏览器) 或 `renderLink`。 。 。 . `ChatComposer` 带 `disabled` (该模型没有可用性:输入、发送、语音和选择器为 相对于 `isSending`。 。 。 .

## 测试

```sh
bun test
```

`test/preload.ts` 决定 `@aphrody/m3-primitives` 因此,测试不需要一个 已建成 `dist`。 。 。 .

## 贷项

衍生自 SpaceUI [`@spacedrive/ai`](https://github.com/spacedriveapp/spaceui) (麻省理工学院,见 `LICENSE.spaceui`),在材料设计3上重建. 新代码为Apache-2.0.

## 常见问题

### @aphrody/m3-ai 是什么？

材质设计3代理交互组件\(工具调用,平分,聊天作曲,工人,任务\): SpaceUI \(@spacedrive/ai\) 在@aphody/m3-primitives上重建\.

### 如何安装 @aphrody/m3-ai？

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

### @aphrody/m3-ai 支持 TypeScript 吗？

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

### @aphrody/m3-ai 支持 ESM 还是 CommonJS？

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

### @aphrody/m3-ai 可以商用吗？

@aphrody/m3-ai 使用 Apache-2\.0 AND MIT 许可。声明的许可为 Apache-2\.0 AND MIT，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @aphrody/m3-ai 的下载量有多少？

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

### @aphrody/m3-ai 还在维护吗？

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