# @ai-matrx/alchemy 中文文档

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

版本：0\.23\.96
npm 元数据更新时间：2026-10-30T12:13:18.968Z
中文译文更新时间：2026-11-05T18:14:35.861Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ai-matrx/alchemy
原文对照：https://npmcn.com/package/%40ai-matrx/alchemy/?lang=original
项目主页：https://github.com/AI-Matrix-Engine/aidream/tree/main/apps/shared/alchemy#readme
源码仓库：https://github.com/AI-Matrix-Engine/aidream

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

- 包体积（解压后）：9.2 MB，187 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：6 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0
- 首次发布：2026-09-12T21:36:07.961Z
- 最新版本发布：2026-10-30T12:13:18.763Z
- 近 30 天下载量：92568（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：238（近 12 个月 238 个）

## 中文简介

Matrx Alchemy: 完整的 Matrx 副本, 准备- AI, 和导出经验, 有框架中立的核心, React 菜单, glyph 和样式; 宣告( 屏幕所持有的: 类型、 注册、 验证、 JSON schema) 和一个表面同步; 动作( 单 ac)

## 安装

```sh
npm install @ai-matrx/alchemy
```

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

## README

# @ai- matrx/ 盐类

Alchemy是Matrx的内容到AI的工具包. **炼金术菜单** 是其小的、可重复使用的副本、准备和出口管制。 这种分配方式将共享核心、反应控制、CSS和SVG传送;它不包含平行执行。 它坐着 `@ai-matrx/agents` 永远不要依赖它.

## 一个菜单,准备使用

```tsx
import { AlchemyMenu } from "@ai-matrx/alchemy/react";
import "@ai-matrx/alchemy/styles.css";

export function TaskActions({ task }: { task: { id: string; title: string; description: string } }) {
  return <AlchemyMenu
    sourceId={`task:${task.id}`}
    label={task.title}
    human={() => task.description}
    json={() => task}
    agent={() => ({
      kind: "task",
      location: "Task detail",
      description: "Current task, including unsaved changes",
      data: task,
    })}
  />;
}
```

透明图标打开了普通拷贝,Markdown,格式化的HTML带有纯文本倒回,JSON,直接AI上下文,准备,下载. 不需要chevron,图标库或Tailwind建设. 语义 HSL 令牌继承了主机的 Matrx 主题; 中性默认工作不包含一个. 设定 `sourceId` 当挂载控制器可以切换记录时,从记录身份。 懒惰取出器在内容被捕获后运行.

准备支持可编辑的草稿,细节预设,结构减小,遗漏和撤销. 提供表格行会增加相关的电子表格格式;已注册的导出者和页面动作会保留相同的捕获源边界. 一个缺席的AI提供者离开手动准备,而不显示已死AI控制.

## 门户和磁带目标

Portal是每个Matrx主机的默认标记. 默认的玻璃/透明控件在32px桌面目标中使用实际的Tap目标原始,并带有侧边-平面 18px 艺术,1.75中风和外壳图标颜色;粗指针保留了44px. 使用 `triggerVariant="glass"` 标题和 `triggerVariant="transparent"` 用于内容动作. `triggerVariant="outline"` 对密集工具栏(28px目标和16px艺术品,匹配Data工具栏)使用条形按钮. `AlchemyMenu` 大小 `xs` 财务报告和审定财务报表 `toolbar` 选择带有 14px 艺术品的压缩 28px 目标进行玻璃/透明控制. `icon="copy-transform"` 是一个可选的包件变体;两个标记船都作为SVG资产. 未来的主机标记会扩展这个被打入的图标集,而不是替换触发器或添加页面CSS.

```tsx
import { ContentTransferMenu } from "@ai-matrx/alchemy/react";

<ContentTransferMenu source={{ kind: "markdown", text: content }} />
<ContentTransferMenu source={{ kind: "text", text: title }} triggerVariant="glass" />
// Inside a mounted ContentTransferSurfaceProvider, no source prop is needed:
<ContentTransferMenu />
```

即使是平版源也有格式的复制/下載,由源标签的AI上下文信封,手动编辑,细节/特征限制,并撤销. 经认证的主机增加了6个人工智能准备食谱和可用的Matrx目的地. 表格来源会添加选择,过滤,排序,列选择,行限制,CSV/TSV和Excel. 手动编辑的草稿是发送给目的地的内容;与其新形状相容的行动消失.

## 扩展共享菜单

Copy/Download 选择器使用一个格式调色板. 其他格式使用相同的平面;快速复制,准备,替代上下文,页面操作使用共享组. 供应能力和说明,而不是提供另一个菜单.

-   使用 `human`, (中文(简体) ), `json`,以及 `agent` 获取相同内容的不同表达方式.
-   使用 `export.sheetRows` 财务报告和审定财务报表 `export.sheetColumns` 表格;电子表格格式自动可用.
-   使用 `export.items[].build` 用于自定义文件的字节、 MIME 类型、 扩展名和可选文件名。 它出现在"下载"中. 一个 `onSelect` 回调优先 `build` 并仍然是一页动作.
-   使用 `aiVariants` 用于其他来源, `aiCustom` 用于源设置,以及 `groomer` 每节的细节。 他们进入同样的准备工作空间.
-   使用下层 `ContentTransferMenu` 及其格式适配器和预测页面动作的能力提供者. `sourceFormats={false}` 在一个文件/ 只操作控件中压制源格式; 一个动作 `placement: "download"` 在调色板中放置一个真正的下载.

标签和提示在共享几何内被包裹. 保存稳定的ID,资格检查,捕捉边界,以及诚实的结果. 不添加每页 Copy/ Download 列表, 绕过共享的传输, 或为特定集成重排菜单 .

## 表出口和现场参考文献

登记册 `tableDataFormat` 用显示标签键入的平面 JSON `tableSchemaFormat` 用于源身份、预测的图和行。 普通的JSON保留了机器密钥;重复的显示标签被分解而未降值. 两个适配器都读取了目前的预测草稿,包括过滤,分拣和可见的列. 可读格式也选择了Email JSON在该表示中.

供应 `table.availableScopes`, (中文(简体) ), `table.initialScope` 和可选 `table.scopeLabels` 装填器 诚实地捕捉每个范围。 编制工作空间保留每个范围的草稿。 提供 `references` 具有明确注册实体身份和提供者 `reference` 用于验证和构建 Canonic 信封的端口。 这些是现场保存的参考文献,独立于内容过滤器和草稿编辑. `referenceActions` 能够打开现有的高级拾取器。 永远不要从标题中推断一个实体.

一个提供者 `email` 端口启用 CSV, JSON 和 Markdown 电子邮件操作 。 软件包在明确发送前显示精确被封存的文件和调整;主机向认证账户发送相同的文件名, MIME和字节. 股份/存取控制保持分离。 标准表格复制配置也接受 `references`, (中文(简体) ), `rowReferences` 财务报告和审定财务报表 `triggerVariant`。 。 。 .

## 一次整合 Matrx 服务

Matrx服务适配器住在 `@ai-matrx/agents`它坐落在Alchemy上方 导入 `MatrxContentTransferProvider` 从 `@ai-matrx/agents/content-transfer/react`,以及 `createMatrxTransferPorts(bindings)` 编号 : `createMatrxTransferActions(ports)` 从 `@ai-matrx/agents/content-transfer`. 提供者接受Cononical Transport,认证数据库读取端口,当前组织获取器和源应用程序,并向后代Alchemy菜单提供所宣称的持久AI准备工作. 在身份边界上挂载, 更改用户或组织无法重用另一个身份准备的运行 。 将已有的笔记、文档、工作簿、任务、附件、代码和聊天打开器捆绑一次,并通过提供者登记返回的动作 `capabilities.actions`;菜单继承到 Matrx 保存并用 AI 组继续 .

Openers 报告一个编辑器被打开,而不是项目被保存. 如果取景者失败, Save-and-attach 保留所创建的音符. New-chat/window 交接器附加了被捕获的内容作为文本资源,让人类作曲家空出并永不自动运行. 连接工具通过现有的助手Chat 选项拾取器选择; 这不是一个自动的 MCP 引用 .

精确挂载的表层申报,使用 `createSurfaceTransferHandle` 从 `/core` 财务报告和审定财务报表 `ContentTransferSurfaceProvider` 从 `/react`把它的范围固定在前端 永远不要向全球寻找同名的地表。 标准 Matrx 表格包括默认共享行和工具栏控制; `copy={false}` 选择退出。 自定义表格可以使用下级 `ContentTransferMenu` 来源/表格合同.

## 框架中立使用

```ts
import { capture, createDraft, serialize } from "@ai-matrx/alchemy/core";

const { snapshot } = await capture(
  { kind: "text", text: "Hello" },
  new AbortController().signal,
);
const artifact = serialize(createDraft(snapshot), "plain");
```

| 条目 | 出口 |
| --- | --- |
| `/core` (亦为包根) | 捕捉,投影,制备,序列器,文物和运输. |
| `/react` | `AlchemyMenu`低级 `ContentTransferMenu`,表面/提供者绑定和反应甘油. |
| `/operate` 写入门 | `createWriteDoor({ ports, declarations })`: 给一个已宣布的目标(人、菜单、目的地、代理、小程序、自动化)的每封信返回 a `Receipt` ——应用(可能包括: `warning`),排队或拒绝,有判决和补救. 把它捆起来 `door` 主机端口并注册每个目的地的无头处理器. |
| `/ports` | 仅主机端口类型( O)`AlchemyHostPorts`, (中文(简体) ), `KindValidatorPort`, (中文(简体) ), `DiagnosticsPort`, (中文(简体) ), `IdentityPort`, (中文(简体) ), `PersistencePort`) (中文(简体) ). 一个宿主在边界上绑住它们一次;一个不受约束的可选端口意味着能力是不存在的,从没有被绊住. |
| `/actions` | 一个行动登记册(菜单行动) `runAction`; 以 id 表示的方案 `invokeAction` + 键 `invocableAction`,加上表面动作: `ActionDeclaration`编号 :`ActionInfo`,从写入目标、客户工具以及 `ui.ui_surface_action` 排队, `resolveActionChain` (孩子获胜的名字) 和一个跑者 `runSurfaceAction` (服务器、任务、导航、页面). |
| `/surface` | 一个 SurfacePort 运行时间 : `readSurfaceChain(client, surfaceName, { maxDepth?, organizationIds? })` 读取表面的动作 `ui.ui_surface*` 通过取景者的客户端(组织扩展仅适用于其成员),以及 `createSurfacePort(opts)` 挂载、保存其值并运行其动作(页面动作在 `"actions"` 溪流并用 `completeAction`) (中文(简体) ). |
| `/checks` | 一个表面同步。 只写 `declared_by: "code"` 并且从来没有报告一个数据库宣布的行是 stale 或孤儿. |
| `/styles.css` | 自成一体的菜单和工作空间样式. |
| `/alchemy.svg`, (中文(简体) ), `/portal.svg`, (中文(简体) ), `/copy-transform.svg` | 被包装的图标资产; Portal 是默认的. |

登记器安装金丝雀需要先放出手足包和设计系统,安装Alchemy拉入时失败 `@ai-matrx/agents`样式表导入 Canonical 设计- system 样式; SVG 资产在构建时从它们的一个来源复制 .

## 常见问题

### @ai-matrx/alchemy 是什么？

Matrx Alchemy: 完整的 Matrx 副本, 准备- AI, 和导出经验, 有框架中立的核心, React 菜单, glyph 和样式; 宣告\( 屏幕所持有的: 类型、 注册、 验证、 JSON schema\) 和一个表面同步; 动作\( 单 ac\)

### 如何安装 @ai-matrx/alchemy？

在项目目录运行 npm install @ai-matrx/alchemy，或使用 pnpm add / yarn add / bun add。

### @ai-matrx/alchemy 支持 TypeScript 吗？

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

### @ai-matrx/alchemy 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @ai-matrx/alchemy 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ai-matrx/alchemy 可以商用吗？

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

### @ai-matrx/alchemy 的下载量有多少？

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

### @ai-matrx/alchemy 还在维护吗？

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