# @absolutejs/artifacts 中文文档

规范地址：https://npmcn.com/package/%40absolutejs/artifacts/

版本：0\.5\.0
npm 元数据更新时间：2026-11-06T07:31:00.210Z
中文译文更新时间：2026-11-08T11:53:38.808Z
软件包许可：BUSL-1\.1

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

原始 npm 页面：https://www.npmjs.com/package/%40absolutejs/artifacts
原文对照：https://npmcn.com/package/%40absolutejs/artifacts/?lang=original
项目主页：https://github.com/absolutejs/artifacts
源码仓库：https://github.com/absolutejs/artifacts

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

- 包体积（解压后）：258 kB，27 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：drizzle-orm \>=1\.0\.0-rc\.4 \<2，docx-preview ^0\.3\.7，@absolutejs/rag \>=0\.1\.1 \<1
- 首次发布：2026-07-15T02:44:49.874Z
- 最新版本发布：2026-11-06T07:30:59.997Z
- 近 30 天下载量：1784（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

为AI产品打出,版本的文物——计划,生命周期,存储,渲染,出版,修改,以及代理工具而无需规定数据库或主机.

## 安装

```sh
npm install @absolutejs/artifacts
```

也可以使用：`pnpm add @absolutejs/artifacts`、`yarn add @absolutejs/artifacts`、`bun add @absolutejs/artifacts`

## README

# @absolutejs/艺术

人工智能制造的东西的输入生命周期.

AI生成的页面、报告、计划、电子邮件、甲板或图像不应消失 或者变成一个没有验证的blob。 应该有种, 结构化内容、所有权、出处、修订、能力、制作人、, 和明确的出版生命周期.

`@absolutejs/artifacts` 提供合同而不拥有你的数据库, 路线,授权,UI,或托管.

## 它拥有的

-   结构化的文物计划与运行时间验证
-   草案、公布和存档的生命周期状态
-   不可改变的修订历史、恢复和乐观的最新情况
-   结构化内容外加生成或源文件的不透明引用
-   艺术品、资产、渲染器和出版机存储界面
-   用于开发和测试的博物馆内文物和资产储存
-   与 AI 工具地图在结构上兼容的自有生命周期工具
-   模型、工具、跟踪和源实体的验证领域
-   文件、演示文稿、电子表格、, 数据集、代码、图像、音频、视频、电子邮件、档案和通用文件
-   可选桥到 `@absolutejs/rag` 摄入量
-   带有原子多文件包的提供者中性生成登记册
-   分阶段、验证 -- -- 承诺前的多工艺批次,并附有完成收据
-   订正版或明确的实况出版物
-   为交易发包箱设计的持续生命周期事件
-   修订RAG索引状态和索引协调员
-   人工活性/源头分类和了解历史的资产垃圾收集

您的申请保留了授权, 持久的持久性, 公共标志, URL、通知、分析、提交和产品特定渲染.

## 定义类型一次

```ts
import { Type } from "@sinclair/typebox";
import {
  createArtifactService,
  createMemoryArtifactAssetStore,
  createMemoryArtifactStore,
  defineArtifactRegistry,
} from "@absolutejs/artifacts";

const registry = defineArtifactRegistry({
  page: {
    capabilities: ["archive", "edit", "preview", "publish"],
    content: Type.Object({
      blocks: Type.Array(
        Type.Union([
          Type.Object({ heading: Type.String(), type: Type.Literal("hero") }),
          Type.Object({ body: Type.String(), type: Type.Literal("text") }),
        ]),
      ),
      theme: Type.Union([Type.Literal("dark"), Type.Literal("light")]),
    }),
    label: "Page",
    schemaVersion: 1,
  },
});

const artifacts = createArtifactService({
  assetStore: createMemoryArtifactAssetStore(),
  registry,
  store: createMemoryArtifactStore(),
});

const page = await artifacts.create("owner-123", {
  content: {
    blocks: [{ heading: "A real page", type: "hero" }],
    theme: "light",
  },
  createdBy: "agent",
  kind: "page",
  provenance: { model: "your-model", tool: "create_page" },
  title: "Launch page",
});
```

每一个成功的创建或生命周期突变都附加了不可改变的快照. 恢复历史创造了新的私人草案,而不是改写或 重写旧版本:

```ts
const history = await artifacts.listRevisions("owner-123", page.id);
const restored = await artifacts.restore("owner-123", page.id, 1);
```

## 生产持久性

在PostgreSQL上使用包拥有的Drizzle schema,包括Neon. 店铺 在解剖学上写下现在的文物,不可改变的修改和生命周期 发件箱事件。 它还坚持按修订指数编制州和栅栏 文物由所有者读取并变异.

```ts
import {
  artifactDrizzleSchema,
  createDrizzleArtifactStore,
} from "@absolutejs/artifacts/drizzle";

const store = createDrizzleArtifactStore({ db });
```

导出 `artifactDrizzleSchema` 你申请的Drizzle计划 普通迁移工作流程拥有四个表格。 插入并选择类型框 从这些表格直接生成的,从同一切入点出口; 主机应该重新使用它们,而不是重新定义数据库行计划.

当永久删除主机主机时, 请打电话 `artifacts.purgeOwner(ownerId)`。 。 。 . 制作店删除其目前的记录,修订,索引状态, 和一次交易中的发件箱事件; 孤儿资产字节仍受 包裹的历史感 垃圾收集.

## 文件备份的文物种类

直接使用捆绑的定义或用特定应用程序来组成定义 类型 :

```ts
import {
  defineArtifactRegistry,
  standardArtifactDefinitions,
} from "@absolutejs/artifacts";

const registry = defineArtifactRegistry({
  ...standardArtifactDefinitions,
  page: myPageDefinition,
});
```

文件字节留在主机存储中 。 人工记录保留不透明的引用 名称、媒体类型、大小、校验和、角色和存储 URI。 URI没有治疗 作为公共 URL, 软件包只读取配置的资产 存储。 删除文件不会删除其字节, 因为旧的不可更改 订正案仍可参考.

```ts
const report = await artifacts.create("owner-123", {
  content: { summary: "Quarterly results" },
  createdBy: "agent",
  kind: "document",
  title: "Q3 report",
});

await artifacts.attach("owner-123", report.id, {
  data: pdfBytes,
  mediaType: "application/pdf",
  name: "q3-report.pdf",
  role: "primary",
});
```

多个生成的文件应使用一个分阶段交易,从而使用一个 文物修订:

```ts
const report = await artifacts.createBundle("owner-123", {
  assets: [pdfOutput, docxOutput, thumbnailOutput],
  content: { summary: "Quarterly results" },
  createdBy: "agent",
  kind: "document",
  provenance: {
    lineage: [{ relation: "generated_from", sourceId: "rag-document-123" }],
    tool: "quarterly_report_generator",
  },
  title: "Q3 report",
});
```

当一件工作必须一起生产出几件文物时, 完成整批工作, 在永久存在前运行域验证器,并通过存储执行 执行 `createBatch` (Drizzle和内存商店的包装)

```ts
const staged = await artifacts.stageBatch(
  "owner-123",
  {
    evidence: [{ sourceId: "research-run-123", sourceUrl: sourceUrl }],
    items: [
      { artifact: worksheetInput, key: "worksheet" },
      { artifact: reportInput, key: "report" },
    ],
    provenance: { tool: "prospecting_mission", traceId: mission.id },
  },
  {
    validators: [
      ({ items }) =>
        validateDomainEvidence(items).map((message) => ({
          code: "evidence_invalid",
          message,
        })),
    ],
  },
);

const receipt = await staged.commit();
if (receipt.status !== "committed") throw new Error(receipt.error);
```

每个文物都携带其批号、物品钥匙、证据和出处. `commit()` 返回持久对账收据:, 修订,原子性,验证结果,以及任何存档赔偿. 这个 默认模式需要原子 `ArtifactStore.createBatch`失败的主机 提供交易可以明确选择 `archive_on_failure`; 已完成 先前的写作随后被存档并报告为 `rolled_back` 或者说 `partial_failure`调用 `rollback()` 承诺释放前的所有阶段 资产交易.

## 生成

发电机是中立的。 他们返回经过验证的结构化内容和 零或更多文件写入; 注册通过相同方式实现这些输出 文物捆绑生命周期:

```ts
const generators = createArtifactGeneratorRegistry([
  {
    kind: "presentation",
    name: "company-deck",
    generate: async ({ prompt }) => buildPresentation(prompt),
  },
]);

const deck = await generators.generate(artifacts, {
  createdBy: "agent",
  kind: "presentation",
  ownerId: member.id,
  prompt: "Build the partner launch deck",
});
```

发电机可能暴露于 `validate` 函数。 捆绑起来 `validateGeneratedArtifactFormats` 验证器检查 CSV 行结构, RFC 822 头,ZIP可读性,以及PPTX包/XML完整性在持久性之前. 生成数件独立的文物,通过同样的原子接收 登记:

```ts
const receipt = await generators.generateBatch(artifacts, {
  ownerId: member.id,
  items: [
    { createdBy: "agent", key: "deck", kind: "presentation", title: "Deck" },
    { createdBy: "agent", key: "email", kind: "email", title: "Email" },
  ],
  provenance: { tool: "campaign_generator" },
});
```

生成验证器运行于每个输出完成后, 在任何输出完成之前 承诺 验证失败返回一个按键回滚的完成收件到 无效输出.

## RAG 摄入量

可选 `@absolutejs/artifacts/rag` 入口解决一个当前或 上传合同中的历史文物记录 `@absolutejs/rag`结构化内容列为JSON和每个附件 包含文件而不披露其存储 URI :

```ts
import { artifactToRAGUploads } from "@absolutejs/artifacts/rag";
import { buildRAGUpsertInputFromUploads } from "@absolutejs/rag";

const revision = await artifacts.getRevision("owner-123", report.id, 2);
const uploads = await artifactToRAGUploads(revision, assetStore);
const upsert = await buildRAGUpsertInputFromUploads({ uploads });
```

`createArtifactRAGIndexCoordinator` 将转换用耐用 `pending`, (中文(简体) ), `indexed`,以及 `failed` 状态。 它从文档中去除标识 替换成功后以前的索引修订。 设定 `failureMode` 改为 `"isolate_uploads"` 以独立索引结构化内容和资产。 一个坏 资产在保存成功时生成打入的部分收据 文档 id; 过期的 id 仅在修订完全成功后才删除.

## 事件和保留

每一个生命周期的变异都把活动 提供给同样的文物商店 调用它来写当前记录和不可更改的修改。 持久性适配器 应该把这些行 在一个数据库交易, 然后工人可以消费 未处理的RAG索引、预览、通知、扫描或 转换.

资产收集将存储候选软件与每个软件的参考文献进行比较 保留修订版. `collectAssetGarbage({ dryRun: true })` 预览删除; 符合条件的只有比所配置的最低年龄长的未引用对象.

## 编写出版和制作

出版是一个适配器,因为公众访问是一个主机政策:

```ts
const artifacts = createArtifactService({
  publisher: {
    publish: async (artifact, { idempotencyKey }) =>
      mintPublicTokenAndUrl(artifact, idempotencyKey),
    unpublish: async (artifact, { idempotencyKey }) =>
      revokePublicAccess(artifact, idempotencyKey),
  },
  registry,
  store: postgresArtifactStore,
});
```

发布默认值为 `pinned`: 公共记录名称 确切的不可更改 修订. `mode: "live"` 是一个明确的备选方案,其修订工作取得了进展 ,然后编辑.

制作人按文物种类和输出格式独立登记:

```ts
const renderers = createArtifactRendererRegistry([
  {
    format: "html",
    kind: "page",
    render: async (artifact) => ({
      body: renderSafePage(artifact.content),
      mediaType: "text/html; charset=utf-8",
    }),
  },
]);
```

软件包从未将生成的 HTML 或 JavaScript 视为可信任可执行文件 内容。 应用程序应界定结构化内容计划,并加以制作 通过控制适配器.

## AI 工具

`createArtifactTools` 绑定创建、列表、获取、更新、发布和取消 操作到一个所有者。 返回的定义使用 TypeBox 输入和 不变 `{ description, input, handler }` 使用的形状 `@absolutejs/ai`。 。 。 .

```ts
const tools = createArtifactTools({
  createdBy: "agent",
  ownerId: member.id,
  service: artifacts,
});
```

只披露用户明确控制公众的出版工具 访问.

## 许可证

1.1商业来源许可证——免费发放给自己的产品、应用程序和 内部用途;你可能不会把它作为 互相竞争的人工智能的工艺品, 编辑、制作、出版或文物管理服务。 转换为 Apache 2.0于2030年7月14日发布. 见 [自由主义](https://npmcn.com/package/%40absolutejs/artifacts/LICENSE)。 。 。 .

## 浏览器文档预览

安装可选选项 `docx-preview` 端点和导入 `renderDocxPreview` 从 `@absolutejs/artifacts/browser`。通过 DOCX 矩阵和显示 返回的 HTML 为 `srcDoc` 在iframe 中输入 `sandbox=""`保留沙盒: 渲染器会禁用活动内容、外部资源、 HTML 块和链接. 通过您的应用程序认证的所有者扫描文件端点获取字节 . 浏览器预览大致为Word布局;总是保留原始文件.

过 `{ allowLinks: true }` 以保存已验证的 HTTPS 和普通电子邮件链接. 使用 `sandbox="allow-popups allow-popups-to-escape-sandbox"` 对于此模式: 链接 在新标签中打开文档沙盒,没有打开者或参考者. 文档脚本和父页导航仍然禁用. 链接依然存在 默认禁用。 HTTP, 可执行的 URL, 证书和电子邮件参数 不接受.

### 格式化 Word 导出

`renderFormattedDocx({ blocks, filename, pageSize: 'letter' })` 返回一个 `ArtifactRenderResult` 包含可编辑的 DOCX 字节。 块是段落, 标题,或项目符号;运行支持粗体、斜体和HTTPS/mailto超链接. 没有获取资源 。 默认体型为11.5分. 文件为: 限于2,000个块和1 MB的结构化输入.

对于简单的生成的草稿, `documentBlocksFromText(text)` 确认空白行 段落, `#`编号 :`##` 标题, `-`编号 :`*`编号 :`•` 子弹, `**bold**`,标记下链接和 赤色 HTTPS URL 。 这是一个有限的文本格式,不是一个完整的Markdown渲染器; HTML 仍然为文字文本。 在Word相容的应用程序中,布局可以有所不同.

## 常见问题

### @absolutejs/artifacts 是什么？

为AI产品打出,版本的文物——计划,生命周期,存储,渲染,出版,修改,以及代理工具而无需规定数据库或主机\.

### 如何安装 @absolutejs/artifacts？

在项目目录运行 npm install @absolutejs/artifacts，或使用 pnpm add / yarn add / bun add。

### @absolutejs/artifacts 支持 TypeScript 吗？

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

### @absolutejs/artifacts 支持 ESM 还是 CommonJS？

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

### @absolutejs/artifacts 可以商用吗？

@absolutejs/artifacts 使用 BUSL-1\.1 许可。声明的许可为 BUSL-1\.1，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @absolutejs/artifacts 的下载量有多少？

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

### @absolutejs/artifacts 还在维护吗？

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