# @civitai/agent-runner 中文文档

规范地址：https://npmcn.com/package/%40civitai/agent-runner/

版本：0\.1\.1
npm 元数据更新时间：2026-10-31T17:04:17.501Z
中文译文更新时间：2026-10-31T19:30:09.978Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40civitai/agent-runner
原文对照：https://npmcn.com/package/%40civitai/agent-runner/?lang=original
项目主页：https://github.com/civitai/civitai-app-starters/tree/main/packages/civitai-agent-runner#readme
源码仓库：https://github.com/civitai/civitai-app-starters

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

- 包体积（解压后）：146 kB，45 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：6 个
- peer 依赖：@civitai/components-chat \>=0\.25\.0 \<1\.0\.0
- 首次发布：2026-10-28T00:21:08.137Z
- 最新版本发布：2026-10-31T17:04:17.149Z
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

用于远程模式的持久运行程序：应答作为Postgres上的DBOS工作流运行，通过聊天的运行程序协议（start, events, stop, patch）提供服务。

## 安装

```sh
npm install @civitai/agent-runner
```

也可以使用：`pnpm add @civitai/agent-runner`、`yarn add @civitai/agent-runner`、`bun add @civitai/agent-runner`

## README

# @civitai / agent-runner

的服务器端 [`<civitai-chat>`](https://npmcn.com/package/%40civitai/civitai-components-chat)的远程模式。该页不再在页面中运行辅助回复，而是在运行器上启动运行，通过SSE跟踪其事件，并可以停止运行。如果页面关闭或重新加载，则继续运行。这个包就是那个跑步者：

-   每个回复运行为 [DBOS](https://docs.dbos.dev/) Postgres上的工作流。当进程崩溃时，应答从其最后保存的进度中恢复，无论哪个副本恢复它。
-   它服务于聊天的运行程序协议v1 (`@civitai/components-chat/runner-protocol`)通过HTTP：启动，查找，停止，通过幂等键停止，修补对话，并从任何偏移读取运行的事件。
-   查看器一次只能运行一个活动。

Civitai自己的跑步助手就是基于它开发的。该软件包对Civitai的账户、代币或型号一无所知。部署通过几个接口提供这些功能。

## 安装

```bash
pnpm add @civitai/agent-runner @civitai/components-chat
```

`@civitai/components-chat` 是对等依赖，因为页面和运行程序必须使用相同的协议。您需要Node 22或更高版本，以及DBOS可以使用的Postgres数据库。

## 部署提供了什么

跑步者从外部需要的一切都通过内部接口 `interfaces.ts`：

| 接口 | 它是做什么的 |
| --- | --- |
| `Authenticator` | 将请求的标头转换为它所代表的用户id。 |
| `GrantVerifier` | 检查运行是否允许启动或补丁携带（报头） `x-run-grant`）。 |
| `GrantStore` | 在运行有效期间保持运行的授权，在您自己的表中，而不是在DBOS中。 |
| `ConversationStore` | 加载并自动更新保存的会话，即聊天的v2/v3元数据。 |
| `ModelProvider` | 提供回复使用的语言模型。一个真实的服务器根据每次请求生成它的凭据。 |
| `ToolProvider` | 打开回复工具。跑步者在停止或回复结束时关闭它们。 |

跑步者从不向模型，工具或商店接缝提供凭证。任何传递到DBOS工作流或从步骤返回的内容都将在Postgres中持久化，因此令牌永远不能作为参数或返回值跨越这些接缝。

## Run grants必须说明它们是什么

一、 `RunGrant` 携带必要的 `preview` 国旗:

-   `preview: false` 是跑步补助金。这是一个很好的开始或补丁。
-   `preview: true` 是预演补助金。只有在需要一辆车的路线上才有用 `grantFor(request, conversationId, undefined, true)`.
-   没有布尔值的授权 `preview` 既不。它在任何地方都被拒绝，并且运行API记录拒绝。 `Runner.start` 在保留赠款之前，还会拒绝除运行赠款以外的任何内容。

规则关闭失败，因此忘记标志的验证器不能让其预览授权开始运行。

## 草图

```ts
import { buildRunApp, loggerOptions, Runner } from '@civitai/agent-runner';

const runner = new Runner({
  models, // ModelProvider
  tools, // ToolProvider
  store, // ConversationStore
  grants: grantStore, // GrantStore
  log,
  wallClockMs: 10 * 60 * 1000,
  stopGraceMs: 20_000,
});

const app = buildRunApp({
  service: runner,
  authenticator, // Authenticator
  grants: grantVerifier, // GrantVerifier
  logger: loggerOptions('info'), // never logs request headers
});

runner.register(); // once per process, before launch
await runner.launch({ databaseUrl, executorId: 'replica-1', workerConcurrency: 8 });
await app.listen({ port: 8080, host: '0.0.0.0' });
```

`buildRunApp` 也需要 `routes`，用于在运行API旁边提供部署自己的路由。他们得到的是一样的 `authed`， `grantFor` 和 `refuse` 运行API使用的helper。它还需要 `patchRefusal` 和 `basePath`.

## 持久的名称：不要随意更改

重新启动的进程恢复的运行将根据DBOS为其记录的内容重播。工作流名称(`reply`， `reply-stop-marker`)、排队(`replies`)、应用程式版本(`WORKFLOW_VERSION`， `reply-1`)，日志流(`events`)和回电的顺序因此是合同的一部分。 `test/reply-dbos-calls.pg.test.ts` 从DBOS自己的表中读取它们，并将它们与黄金记录进行比较。该记录与运行程序移动到此包之前验证的记录字节相同。如果你改变了其中任何一个，bump `WORKFLOW_VERSION` 随着变化。

`@dbos-inc/dbos-sdk` 因为同样的原因被固定在一个完全相同的版本上。

## 测试支持

`@civitai/agent-runner/test-support` 导出套件使用的组件：脚本化模型、组件工具、承载身份验证器、文件支持的对话存储、SSE读取器，以及 `freshDatabase` 对于一次性Postgres数据库(它读为 `ASSISTANT_RUNNER_TEST_DATABASE_URL`）。

## 开发

```bash
pnpm --filter @civitai/agent-runner typecheck
pnpm --filter @civitai/agent-runner build
```

套件在CI中运行，在 `agent-runner` job，针对Postgres服务。在CI之外，postgresql支持的套件会跳过unless `ASSISTANT_RUNNER_TEST_DATABASE_URL` 指向可以在其中创建和删除数据库的服务器。在CI中，丢失的URL会使套件失败，而不是跳过它。 `test/core-boundary.test.ts` 失败的时候 `src/` 从外部导入文件，或导入一个包 `package.json` 不申报。

## 许可证

麻省理工学院

## 常见问题

### @civitai/agent-runner 是什么？

用于远程模式的持久运行程序：应答作为Postgres上的DBOS工作流运行，通过聊天的运行程序协议（start, events, stop, patch）提供服务。

### 如何安装 @civitai/agent-runner？

在项目目录运行 npm install @civitai/agent-runner，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@civitai/components-chat（\>=0\.25\.0 \<1\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @civitai/agent-runner 支持 TypeScript 吗？

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

### @civitai/agent-runner 支持 ESM 还是 CommonJS？

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

### @civitai/agent-runner 需要什么版本的 Node\.js？

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

### @civitai/agent-runner 可以商用吗？

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

### @civitai/agent-runner 还在维护吗？

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