# @electric-ax/agents-runtime 中文文档

规范地址：https://npmcn.com/package/%40electric-ax/agents-runtime/

版本：0\.6\.3
npm 元数据更新时间：2026-06-25T19:28:29.042Z
中文译文更新时间：2026-11-13T11:08:17.219Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：1.6 MB，73 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：21 个
- peer 依赖：@tanstack/react-db \>=0\.1\.78，dockerode \>=5\.0\.0，e2b \>=2\.0\.0，react \>=18
- 首次发布：2026-04-23T14:34:36.720Z
- 最新版本发布：2026-06-25T19:28:28.758Z
- 近 30 天下载量：11318（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：29（近 12 个月 29 个）

## 中文简介

电子代理运行时间——代理实体在耐用流上的行为堆栈

## 安装

```sh
npm install @electric-ax/agents-runtime
```

也可以使用：`pnpm add @electric-ax/agents-runtime`、`yarn add @electric-ax/agents-runtime`、`bun add @electric-ax/agents-runtime`

## README

# @ 电动轴/ 代理运行时

耐用实体操作员运行时间 [持久流](https://npmcn.com/package/README.md)。 。 。 .

每个实体都拥有一个只有附件的流. 每一刻,跑步时间都会实现 以输入 TanStack DB 收藏,构建一个 `HandlerContext`,以及 运行您的实体的单 `handler(ctx, wake)` 进入点.

没有分开的 `setup()` 或者说 `loader()` 状态.

## 安装

```bash
pnpm add @electric-ax/agents-runtime
```

同伴依赖 : `@tanstack/db >= 0.5.33`

## 快速启动

```ts
import http from 'node:http'
import { z } from 'zod'
import { createRuntimeHandler, defineEntity } from '@electric-ax/agents-runtime'

defineEntity(`assistant`, {
  description: `Simple durable chat assistant`,

  state: {
    status: {
      schema: z.object({
        key: z.string(),
        value: z.enum([`idle`, `working`]),
      }),
      type: `status`,
      primaryKey: `key`,
    },
  },

  async handler(ctx) {
    if (!ctx.db.collections.status.get(`current`)) {
      ctx.db.actions.status_insert({
        row: { key: `current`, value: `idle` },
      })
    }

    ctx.useAgent({
      systemPrompt: `You are a helpful assistant.`,
      model: `claude-sonnet-4-5-20250929`,
      tools: [...ctx.electricTools],
    })

    await ctx.agent.run()
  },
})

const runtime = createRuntimeHandler({
  baseUrl: `http://127.0.0.1:4437`,
  serveEndpoint: `http://127.0.0.1:3000/webhook`,
})

await runtime.registerTypes()

const server = http.createServer(async (req, res) => {
  if (req.url === `/webhook` && req.method === `POST`) {
    await runtime.onEnter(req, res)
    return
  }

  res.writeHead(404)
  res.end()
})

server.listen(3000, `127.0.0.1`)
```

## 实体模式

实体申报 `defineEntity(name, definition)`数字 :

```ts
import { z } from 'zod'
import { defineEntity } from '@electric-ax/agents-runtime'

defineEntity(`pr-reviewer`, {
  description: `Code review agent`,

  creationSchema: z.object({
    repo: z.string(),
    prNumber: z.number().int(),
  }),

  inboxSchemas: {
    'pr-opened': z.object({
      diff: z.string(),
      baseBranch: z.string().optional(),
    }),
  },

  state: {
    reviewStatus: {
      schema: z.object({
        key: z.string(),
        status: z.enum([`pending`, `reviewing`, `done`]),
      }),
      type: `review_status`,
      primaryKey: `key`,
    },
  },

  async handler(ctx, wake) {
    if (ctx.firstWake && !ctx.db.collections.reviewStatus.get(`current`)) {
      ctx.db.actions.reviewStatus_insert({
        row: { key: `current`, status: `reviewing` },
      })
    }

    if (wake.type === `inbox`) {
      ctx.useAgent({
        systemPrompt: `Review pull requests carefully and concisely.`,
        model: `claude-sonnet-4-5-20250929`,
        tools: [...ctx.electricTools],
      })
      await ctx.agent.run()
      ctx.db.actions.reviewStatus_update({
        key: `current`,
        updater: (draft) => {
          draft.status = `done`
        },
      })
    }
  },
})
```

## 处理器连接

`handler(ctx, wake)` 接收 :

-   `ctx.firstWake` —— 说 `true` 只有第一次醒来,实体
-   `ctx.entityUrl` 编号 : `ctx.entityType` ——身份元数据
-   `ctx.args` - 不可改变的有效产卵群
-   `ctx.db` ——实体已实现的StreatDB被打出 `ctx.db.collections.<name>` (TanStack DB 收藏)用于读取和 自动生成的写入动作 `ctx.db.actions.<name>_{insert,update,delete}`
-   `ctx.electricTools` ——内置运行时间工具通过代理

### 状态

每一件被宣布为 `definition.state` 自动生成 `<name>_insert`, (中文(简体) ), `<name>_update`,以及 `<name>_delete` 行动 `ctx.db.actions`读取 `ctx.db.collections.<name>`数字 :

```ts
ctx.db.actions.counts_insert({ row: { key: `main`, value: 0 } })
ctx.db.actions.counts_update({
  key: `main`,
  updater: (draft) => {
    draft.value++
  },
})
ctx.db.actions.counts_delete({ key: `main` })

ctx.db.collections.counts.get(`main`)
ctx.db.collections.counts.toArray
```

### 探员

```ts
ctx.useAgent({
  systemPrompt: `You are a helpful assistant.`,
  model: `claude-sonnet-4-5-20250929`,
  tools: [...ctx.electricTools, myTool],
})

await ctx.agent.run()
```

`agent.run()` 从实现的时间表组装实体的背景 处理提醒触发消息。 如果你不打电话 `useAgent()`, (中文(简体) ), 运行时间不会运行 LLM 为那个钟.

### 闪烁、观察和发送

```ts
const child = await ctx.spawn(
  `researcher`,
  `r-1`,
  { topic: `durability` },
  { wake: { on: `runFinished`, includeResponse: true } }
)

// Return from this wake. Continue when the child completion wake arrives.

const observed = await ctx.observe(entity(`/researcher/r-2`), {
  wake: { on: `runFinished`, includeResponse: true },
})
const status = observed.status()

ctx.send(`/other-entity/id`, { text: `hello` }, { type: `message` })
```

### 共享状态

```ts
const boardSchema = {
  findings: {
    schema: z.object({
      key: z.string(),
      domain: z.string(),
      finding: z.string(),
    }),
    type: `finding`,
    primaryKey: `key`,
  },
}

if (ctx.firstWake) {
  ctx.mkdb(`board-1`, boardSchema)
}

const board = await ctx.observe(db(`board-1`, boardSchema))

board.findings.insert({
  key: `f-1`,
  domain: `security`,
  finding: `XSS found`,
})
```

`mkdb` 创建后置流( 如果已存在的话 ) . `observe(db(...))` 返回任意提示读取和写入的控点.

## 运行时处理器

`createRuntimeHandler()` 创建电子代理在 实体被唤醒.

```ts
const runtime = createRuntimeHandler({
  baseUrl: `http://127.0.0.1:4437`,
  serveEndpoint: `http://127.0.0.1:3000/webhook`,
})

await runtime.registerTypes()
```

主要方法:

-   `runtime.registerTypes()` ——在服务器中注册所有实体类型
-   `runtime.onEnter(req, res)` ——用于webhook发送的节点HTTP适配器
-   `runtime.handleRequest(request)` 取自处理器
-   `runtime.drainWakes()` 等待在飞机上醒来后安顿下来

## 实体信号

可以通过服务器生命周期终点控制代理:

```http
POST /_electric/entities/:type/:instanceId/signal
```

JSON的尸体是 `{ "signal": "SIGINT", "reason": "...", "payload": ... }`。 。 。 . 同名API被CLI曝光:

```bash
electric agents signal /horton/onboarding SIGINT --reason "stop current run"
electric agents kill /horton/onboarding
```

信号行为 :

-   `SIGINT` 中止活动处理器引用并保持实体状态不变.
-   非代理处理者可以通过 `ctx.signal` 并传递给可以工作,例如 `fetch` 或子进程.
-   `SIGSTOP` 暂停实体。 新信件再次唤醒它,但已经待办的工作在被暂停时不被处理.
-   `SIGCONT` 恢复已暂停的实体.
-   `SIGHUP`, (中文(简体) ), `SIGTERM`,以及 `SIGUSR` 交付给 `ctx.onSignal(...)` 当当前唤醒活动时 .
-   `SIGTERM` 向闲置或暂停的实体过渡 `stopped`; 运行的实体移动到 `stopping` 直到清理结束.
-   `SIGKILL` 立即将实体移动到 `killed`,未注册者醒来,关闭实体流.

## 内设特工

前一个 `registerChatAgent` 编号 : `registerResearcherAgent` 编号 : `registerCoderAgent` 编号 : `registerOracleAgent` 帮助者已被移除 。 内地特工现在住在 `@electric-ax/agents` (霍顿+工人). 在您的运行时间注册, 使用 `createBuiltinAgentHandler` 从 `@electric-ax/agents`。 。 。 .

## 时间线助手

运行时间也会导出 UI 层所用的时长帮助 :

-   `createEntityIncludesQuery(db)`
-   `getEntityState(runs, inbox)`
-   `buildSections(runs, inbox)`
-   `timelineToMessages(db)`

`useChat(db)` 使用基于查询的 `IncludesRun` 编号 : `IncludesInboxMessage` 阵列,以及 `timelineToMessages(db)` 从相同的形状建立 LLM 消息 数据.

## 测试

老公众 `createTestAdapter` API 已被删除 .

关于该repo内部的集成测试,参见:

-   [运行时间dsl.ts](https://npmcn.com/package/%40electric-ax/agents-runtime/test/runtime-dsl.ts)
-   [运行时间- dsl. test.ts](https://npmcn.com/package/%40electric-ax/agents-runtime/test/runtime-dsl.test.ts)
-   [设置- context.ts](https://npmcn.com/package/%40electric-ax/agents-runtime/test/setup-context.test.ts)

## 许可证

阿帕奇 - 2.0

## 常见问题

### @electric-ax/agents-runtime 是什么？

电子代理运行时间——代理实体在耐用流上的行为堆栈

### 如何安装 @electric-ax/agents-runtime？

在项目目录运行 npm install @electric-ax/agents-runtime，或使用 pnpm add / yarn add / bun add。

### @electric-ax/agents-runtime 支持 TypeScript 吗？

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

### @electric-ax/agents-runtime 支持 ESM 还是 CommonJS？

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

### @electric-ax/agents-runtime 可以商用吗？

@electric-ax/agents-runtime 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @electric-ax/agents-runtime 的下载量有多少？

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

### @electric-ax/agents-runtime 还在维护吗？

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