# @corbits/artifacts 中文文档

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

版本：0\.4\.0
npm 元数据更新时间：2026-11-01T03:27:05.618Z
中文译文更新时间：2026-11-10T18:54:48.026Z
软件包许可：LGPL-2\.1-only

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

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

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

- 包体积（解压后）：271 kB，42 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：2 个
- peer 依赖：hono ^4\.12\.32，@intx/db ^0\.5\.0，postgres ^3\.4\.9，@intx/agent ^0\.5\.0，@intx/types ^0\.5\.0，drizzle-orm ^0\.45\.2，hono-openapi ^1\.2\.0，@intx/hub-api ^0\.5\.0，@intx/hub-common 0\.5\.0
- 首次发布：2026-09-25T05:03:11.308Z
- 最新版本发布：2026-11-01T03:27:05.235Z
- 近 30 天下载量：3965（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

艺术、版本和上传,带有可插件内容Store,可挂载到任何互换主机。 需要@intx0.4.0或更新 .

## 安装

```sh
npm install @corbits/artifacts
```

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

## README

# @c轨道/艺术

为交换代理商及其用户提供版本文件和文件:在Hono路由上架的轨道中心模块 `@intx/hub-api`,在可插件中保留 Postgres 和字节中的版本 `ContentStore`以及辅助车的船舶代理工具.

## 为什么?

1.  **每个版本都保留.** 文件或上传文件的每个版本都是新版本,其内容,字节和SHA-256摘要. `expectedVersion` 将修改变为比较和设定.
2.  **就像任何枢纽路线一样.** `createArtifactRoutes` 返回 a `Hono<TenantEnv>` 子应用程序。 读者只能是来电的房客 书写在中心 `requireGrant`。 。 。 .
3.  **探员通过同一家商店写作.** 一个运行扫描的路由集和一个侧车工具包让一个工作流程运行来创建,读取和修改其用户所看到的文物.
4.  **移民安全回放.** 每个SQL文件都具有"一能"性,在一个咨询锁下运行在每个靴子上,因此可以同时从几个复制品开始.

它没有UI,也没有物品商店: 宿主制造出文物,带来自己的 `ContentStore` 用于大型文件.

## 安装

```bash
bun add @corbits/artifacts \
  @intx/agent @intx/authz @intx/db @intx/hub-api @intx/types \
  drizzle-orm hono hono-openapi postgres
```

添加 `@intx/agent` 只有代理人使用侧车工具。 运行于节点QQ24.

## 快速启动

与 `DATABASE_URL` 指向运行过的中枢数据库 `runArtifactMigrations` (见 [使用互换](https://npmcn.com/package/%40corbits/artifacts/#readme-using-with-interchange):

```ts
import {
  createArtifact,
  createArtifactDb,
  getArtifact,
} from "@corbits/artifacts";

const { db, close } = createArtifactDb(process.env.DATABASE_URL!);

const created = await db.transaction((tx) =>
  createArtifact(tx, {
    scope: { tenantId: "acme", principalId: "alice" },
    ownerPrincipalId: "alice",
    kind: "document",
    title: "Notes",
    content: "Hello",
    source: { origin: "manual" },
  }),
);
console.log(await getArtifact(db, created.id));
await close();
```

`acme` 财务报告和审定财务报表 `alice` 必须是中心的租户和校长。 它在第一版打印文物.

## 合适的话

[互换](https://github.com/faremeter/interchange) 由AI代理作为委托人:拥有自己身份、权限和证书的账户。 其枢纽是多租户控制平面,它持有租户、本金和赠款(允许在资源上持有本金);其侧车是代理运行时间.

-   **运行于 :** 中心,作为其Hono应用的路线及其Postgres的桌子`artifacts` 计划.
-   **插入到 :** [`@intx/hub-api`](https://github.com/faremeter/interchange/tree/main/packages/hub-api) 路线和赠款, [`@intx/db`](https://github.com/faremeter/interchange/tree/main/packages/db) (数量) `DBConfig`,以及 `tenant` 财务报告和审定财务报表 `principal` 作为FK目标的表格),以及 [`@intx/agent`](https://github.com/faremeter/interchange/tree/main/packages/agent) 工具在侧车.
-   **与 :** [`@corbits/mailbox`](https://github.com/corbitsdev/corbits-mailbox) 财务报告和审定财务报表 [`@corbits/memory`](https://github.com/corbitsdev/corbits-memory),其他轨道中心模块,以及 [`@corbits/agent-token`](https://github.com/corbitsdev/corbits-agent-token) 为代理无记名标志.

## 参考文献

### `createArtifactRoutes(deps)`

| `deps` | 类型 | 主机提供的东西 |
| --- | --- | --- |
| `db` | `ArtifactDb` | 例如,枢纽的细雨柄 `createDB`。 。 。 . |
| `contentStore` | `ContentStore` | 文件字节去的地方 . `InlineContentStore` 将其保存在 Postgres; 执行端口以保存对象. |
| `requireGrant` | `RequireGrant` | 从 `@intx/hub-api`是因为 `createRequireGrant`。 。 。 . |
| `onArtifactCreated` | `(tx, row, scope) => Promise<void>` | 可选的 在创建交易中运行以获取其他创建副效果 。 创造者 `write` 财务报告和审定财务报表 `archive` 补助金是给你的. |
| `decorate` | `(tenantId, rows) => Promise<void>` | 可选的 在序列行中添加只显示字段。 它不能改变返回的行. |
| `uploadPolicy` | `UploadPolicy` | 可选的 MIME 类型 `POST /artifacts/upload` 接受这个建议。 默认为 `ARTIFACT_UPLOAD_POLICY`。 。 。 . |
| `countSegments` | `ArtifactCountSegments` | 可选的 名为上游 `GET /artifacts/counts`。 。 。 . |

| 路线 | 赠款 | 对 |
| --- | --- | --- |
| `GET /artifacts` | 无(租户范围) | 列出文物,被活化. 空 `200` 没有校长. |
| `GET /artifacts/counts` | 无(租户范围) | 每起计数 `countSegments` 桶,还有 `all`。 。 。 . |
| `POST /artifacts` | `create` 打开 `artifact:*` | 在 1 版本创建文本或 URL 文物 . |
| `POST /artifacts/upload` | `create` 打开 `artifact:*` | 上传一个或多个文件( E)`multipart/form-data`),各有一件文物. |
| `GET /artifacts/:id` | 无(租户范围) | 最新版本. |
| `GET /artifacts/:id/versions` | 无(租户范围) | 版本历史. |
| `GET /artifacts/:id/versions/:version` | 无(租户范围) | 一个版本,有其内容. |
| `POST /artifacts/:id/versions` | `write` 打开 `artifact:<id>` | 添加 JSON 或新版本 `file` 用于上传文件. |
| `POST /artifacts/:id/archive`, (中文(简体) ), `unarchive` | `archive` 打开 `artifact:<id>` | 存档或恢复. |
| `GET /artifacts/:id/download?version=N` | 无(租户范围) | 一个版本的字节,默认最新. |
| `GET /artifacts/:id/preview` | 无(租户范围) | A 类 `text/html` 沙盒式CSP下工艺品; `415` 否则. |

没有主, 除了列表和数答之外, 每一个路线 `403`另一个租户的文物,或者一个身份不明的,回答 `404`。在主机上设置一个上传和重审路径的请求-机构限制;在检查前缓冲机构 `MAX_UPLOAD_BYTES`。 。 。 .

每次写报告 `contentSha256`,与新版本存储的hex sha256:在UTF-8文本上,或者在文件的字节上传. `POST /artifacts` 财务报告和审定财务报表 `POST /artifacts/upload` 每件文物都带着它 `POST /artifacts/:id/versions` 返回旁边 `artifactId` 财务报告和审定财务报表 `version`这是 `null` 仅针对摘要存在前所写的版本.

### `createWorkflowArtifactRoutes(deps)`

用于工作流程运行的运行范围路由,该路由以无记名符号和 `x-workflow-run-address` 标题而不是会话 .

| `deps` | 类型 | 主机提供的东西 |
| --- | --- | --- |
| `db` | `ArtifactDb` | 与上同为相. |
| `contentStore` | `ContentStore` | 与上同为相. |
| `resolveRunScope` | `WorkflowRunResolver` | `(bearerToken, runAddress) => ResolvedWorkflowRunScope | null`。 。 。 . `null` 答题 `401`。 。 。 . |
| `agentToken` | `AgentTokenAuth` | 可选的 接受经纪人自己的中枢标志作为第二条入站方式. |
| `uploadPolicy` | `UploadPolicy` | 可选的 MIME 类型 `POST /artifacts/binary` 接受这个建议。 默认为 `ARTIFACT_UPLOAD_POLICY`。 。 。 . |
| `maxBinaryBytes` | `number` | 可选的 字节上限 `POST /artifacts/binary`默认为 `MAX_UPLOAD_BYTES`。 。 。 . |
| `maxContentChars` | `number` | 可选的 由此产生的内容的字符上限——全文或经编辑的文本,用于 `POST /artifacts` 财务报告和审定财务报表 `PATCH /artifacts/:id/versions`默认为64 000. |
| `beforeWrite` | `WorkflowBeforeWrite` | 可选的 检查每个文本创建( N)`POST /artifacts`)和修订(`PATCH /artifacts/:id`)作文前. 所有的写法都有效. |

`beforeWrite({ scope, kind, write, content })` 得到运行范围, 文物种类, `write` 作为 `{ op: "create" }` 或者说 `{ op: "revise", artifactId }`,且该版本在任何编辑后将保留内容。 它返回一个:

-   `{ action: "allow" }` 照常写作.
-   `{ action: "refuse", code, message }` 答题 `422` 与 `{ code, message }`,而代理工具错误是 `message`。 。 。 . `code` 必须匹配 `/^[a-z0-9_]+$/`· ; `message` 必须是 1 到 1 000 个字符.
-   `{ action: "redirect", artifactId, expectedVersion? }` 将创作变成对文物的修改 必须是同类的 在跑的房客,回答 `200` 联合国 `{ id, version }`。该修订取了创建的名称。 丢失、存档或其他租户的文物答案 `404`和一个 stale `expectedVersion` 答题 `409` 告诉经纪人读读现有文物并修改.

任何其它决定, 重定向返回修改, 或重定向到另一类解答 `500` 写什么? 未检查二进制上传和链接文件 .

一个创造的检查不是连环化的:两个并发的创造都可以同时允许,因此,像"每个租户一个计划"这样的政策在跑步时仍然可以用两个计划来结束. 修改后的检查在持有文物行锁的交易内部进行,所以应当迅速,不得写出文物.

每笔笔写作`POST /artifacts`, (中文(简体) ), `POST /artifacts/binary`, (中文(简体) ), `POST /artifacts/link-file`, (中文(简体) ), `PATCH /artifacts/:id`回答问题 `{ data: { id, version, contentSha256 } }`,同一份摘要 租户路线报告。 对于 `link-file` 文摘覆盖存储 `preview` 文本( 当没有给出时为空),而不是工作空间文件 `path`。 。 。 .

### `runArtifactMigrations(config, { schema })`

取同样的 `DBConfig` 财务报告和审定财务报表 `schema` 作为交换 `runMigrations`。 。 。 . `schema` 持有主机 `tenant` 财务报告和审定财务报表 `principal` 表格; 此软件包的表格总是输入 `artifacts`。 。 。 .

### `@corbits/artifacts/sidecar-bundle`

`artifacts` 是一个 `@intx/agent` 3个工具的工具包。 他们把扫描过的路线叫做特工的 `hub` 证书.

-   `artifact_write` 在未给出标识时, 从内容或工作空间文件路径创建 。 用一个ID来修改,或者用全文,或者用 `edits`:准确的段落,每个段落必须出现一次,否则没有文字. `expectedVersion` 如果新版本存在,则拒绝写入。 它回来了 `{ id, version, contentSha256 }`。 。 。 .
-   `artifact_read` 返回内容,一个过去版本 `version`区域 `offset` 财务报告和审定财务报表 `limit`。 。 。 .
-   `artifact_search` 列出最新的文物,由 `kind` 由a `query` 与标题和内容相匹配.

## 使用互换

在互换后运行迁移, 挂载两套路由, 赠款 `create` 打开 `artifact:*` 给创造文物的负责人 给特工们工具包.

```ts
import { timeWindowEvaluator } from "@intx/authz";
import { createDB, createGrantStore, runMigrations } from "@intx/db";
import { createRequireGrant } from "@intx/hub-api";
import {
  createArtifactRoutes,
  InlineContentStore,
  runArtifactMigrations,
} from "@corbits/artifacts";

const dbConfig = {
  host: "localhost",
  port: 5432,
  user: "postgres",
  password: "postgres",
  database: "interchange",
};

await runMigrations(dbConfig, { schema: "public" });
await runArtifactMigrations(dbConfig, { schema: "public" });

const { db } = createDB(dbConfig);
const requireGrant = createRequireGrant({
  grantStore: createGrantStore(db),
  conditionRegistry: { time_window: timeWindowEvaluator },
});

export const artifactRoutes = createArtifactRoutes({
  db,
  contentStore: InlineContentStore,
  requireGrant,
});
```

挂载 `artifactRoutes` 在中枢应用程序 `/api`在枢纽的认证 和租户中间的软件.

对于特工,挂载 `createWorkflowArtifactRoutes({ db, contentStore: InlineContentStore, resolveRunScope })` 时间 `/api/workflow-artifacts`。 。 。 . `resolveRunScope` 这是主机的 `(bearerToken, runAddress)` 从中心的工作流程中返回租户和校长的查询,或者 `null`。侧车工具呼叫 `/api/workflow-artifacts`添加到代理中并绑定其 `hub` 在您部署时, 证书为代理的中枢符 :

```ts
import { defineAgent, type InferencePreference } from "@intx/agent";
import { artifacts } from "@corbits/artifacts/sidecar-bundle";

export function buildAssistant(sources: readonly InferencePreference[]) {
  return defineAgent({
    id: "assistant",
    systemPrompt: "You help the team read and write shared artifacts.",
    capabilities: [],
    inference: { sources },
    tools: [artifacts],
  });
}
```

## 从0.1升级

-   `mountArtifacts(app, opts)` 现在 `createArtifactRoutes(deps)`,以及 `mountWorkflowArtifacts(app, opts)` 现在 `createWorkflowArtifactRoutes(deps)`双向挂载 `app.route`。 。 。 .
-   `POST /artifacts` 财务报告和审定财务报表 `POST /artifacts/upload` 需求 `create` 打开 `artifact:*`升级将它授予每个已经在其租户中创造出文物的校长;将它授予新的校长.
-   `runArtifactMigrations(db)` 现在 `runArtifactMigrations(dbConfig, { schema })`. 现有0.1.0数据升级在第一个靴子上.
-   那靴子掉了0.1.0的迁移分类账. 你不能回滚到0.1.0,0.1.0和0.2.0复制品不得共享数据库.
-   细细的桌子 `web_site` 援助者, `SKILL_DRAFT_KIND`, (中文(简体) ), `windowContent` 并拆除邮递路线和助手。 这个 `mail_attachment_ref` 表格已删除.
-   需要24号节点或更新.

## 从0.2升级

由地表分隔:AGENTS(侧车工具包)和HOSTS(路线和出口)的变化.

### 代理工具

侧车工具包倒塌了 5个更精细的涂装工具变成了3个. `artifact_write` 现在涵盖创建和链接(通过 `edits`编号 :`content` 其定义如下: `{ artifactId, version }` 结果是一样的.

| 0.2 工具 | 0.3 (韩语) | 怎么样 |
| --- | --- | --- |
| `artifact_create` | `artifact_write` | 没有就叫吧 `artifactId`,通过 `title`, (中文(简体) ), `kind`, (中文(简体) ), `content`。 。 。 . |
| `artifact_link_file` | `artifact_write` | 没有就叫吧 `artifactId`,通过工作空间 `path`。 。 。 . |
| `artifact_read_chunk` | `artifact_read` | 传送范围为 `offset`编号 :`limit` 改为 `start`编号 :`end`。 。 。 . |
| `artifact_list` | `artifact_search` | 首先命令对结果进行最新更新. |
| `artifact_find_by_title` | `artifact_search` | 没有一滴一滴——见下文的告诫. |

**`artifact_find_by_title` 这不是一个滴入.** 在0.2中它和标题相符 **没错**,只匹配标题,最多返回一个 `{ artifactId, version }` (或作无. 在 0.3 时 `artifact_search` 对大小写不敏感的子字符串(ILKE)匹配 **标题和内容**,然后返回匹配的列表。 需要旧的准确标题、单结果语义的调用者必须在过滤结果后进行(比较) `title` 案件不敏感,并进行第一次精确的匹配.

搜索结果上限为每次呼叫50件文物. `artifact_search` 接受一个 `cursor` 财产(加) `limit`,上限为50),通过所有匹配的页面;回转先前的呼叫 `nextCursor` (保持相同的查询和类型)直到不返回.

### 主机

角色不变,但去掉了两条路线和一条出口:

-   `GET /artifacts/find` → `GET /artifacts?query=…`时 `query` 是标题和内容上相同的对大小写不敏感的子字符串.
-   `GET /artifacts/:id/chunk` → `GET /artifacts/:id/read?offset&limit`。 。 。 .
-   `readArtifactChunk` 删除. `findArtifactByTitle` 财务报告和审定财务报表 `linkFileArtifact` 继续出口. `README.md`是因为 `Reference` 一节描述当前的路线和工具.

现在从软件包条目导出两个错误类别: `VersionConflictError` 答题 `409` 当 `expectedVersion` 已经僵化 `ArtifactEditError` 答题 `400` 当修改被拒绝时。 把它们找出来 准确的失败给用户.

## 许可证

[LGPL - 2.1- 仅限](https://github.com/corbitsdev/corbits-artifacts/blob/main/LICENSE)

## 常见问题

### @corbits/artifacts 是什么？

艺术、版本和上传,带有可插件内容Store,可挂载到任何互换主机。 需要@intx0\.4\.0或更新 \.

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

在项目目录运行 npm install @corbits/artifacts，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：hono（^4\.12\.32）、@intx/db（^0\.5\.0）、postgres（^3\.4\.9）、@intx/types（^0\.5\.0）、drizzle-orm（^0\.45\.2）、hono-openapi（^1\.2\.0）、@intx/hub-api（^0\.5\.0）、@intx/hub-common（0\.5\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

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

### @corbits/artifacts 需要什么版本的 Node\.js？

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

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

@corbits/artifacts 使用 LGPL-2\.1-only 许可。弱 Copyleft：作为库被调用时通常不要求开源你自己的代码，但修改库本身需以 LGPL 开源；前端打包合并后的适用边界存在不同理解。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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