# @dougbots/avenor-core 中文文档

规范地址：https://npmcn.com/package/%40dougbots/avenor-core/

版本：0\.26\.0
npm 元数据更新时间：2026-11-12T20:22:21.554Z
中文译文更新时间：2026-11-12T23:09:52.165Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：466 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-05-17T05:21:09.835Z
- 最新版本发布：2026-11-12T20:22:21.172Z
- 近 30 天下载量：3350（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：49（近 12 个月 49 个）

## 中文简介

控制套接字客户端,主管生命周期,以及针对复仇者代理跑者的工具执行.

## 安装

```sh
npm install @dougbots/avenor-core
```

也可以使用：`pnpm add @dougbots/avenor-core`、`yarn add @dougbots/avenor-core`、`bun add @dougbots/avenor-core`

## README

# @ dougbots/ avenor-core (英语)

控制套接字客户端,主管生命周期,以及针对复仇者代理跑者的工具执行.

Avenor是运行AI代理会话的CLI守护进程. 这个软件包管理守护进程,并围绕它的JSON-RPC控制套接字提供打入的包装器——用于产卵运行,检查状态,跟踪会话,并清理关闭一切的接口.

这是一个 **私营** 工作空间软件包 `@dougbots/avenor-mcp` 财务报告和审定财务报表 `@dougbots/avenor-opencode`。不发布到 npm.

## 二进制发现

复仇者二进制通过三步倒置定位:

1.  `AVENOR_BIN` 环境变量
2.  `avenor` 打开 `PATH` (通过) `which avenor`(中文(简体) )
3.  `~/.botfiles/bin/avenor`

导出助手 `findAvenorBinary()` 运行这个发现。 这个 `Supervisor` 如果没有明确的,则自动调用 `binaryPath` 给出.

## 核心概念

### 客户端

`dial(socketPath)` 连接到向导控制套接字并返回 a `Client`编辑 `Client` 在Unix套接字上讲JSON-RPC 并揭露方法如 `spawn()`, (中文(简体) ), `status()`, (中文(简体) ), `list()`, (中文(简体) ), `shutdown()`, (中文(简体) ), `answerPermission()`, (中文(简体) ), `prompt()`,以及 `cancel()`。它也提供了一个可同步的 `events()` 用于流出运行时的事件.

### 主管

`Supervisor.get()` 单子能保证一个复仇者 `stable` 进程正在运行,绑定到每个 PID 控制套接字。 它从二进制开始 `avenor stable --control-socket <path> --idle-timeout 30m`并登记信号处理器清理出口.

相接跑被跟踪到内存(label ~ runtime ID, sentinel路径,事件日志路径),因此后续和状态检查可以解决正确的跑出时间.

## 工具

包会导出六个自成一体的工具函数. 每个都用于嵌入MCP服务器或CLI处理器.

### `spawnTool`

启动新代理运行 .

```ts
import { spawnTool } from '@dougbots/avenor-core'

const result = await spawnTool({
  agent: 'codex',
  prompt: 'Write a function to reverse a string',
  label: 'reverse-string',
  model: 'claude-sonnet-4',
  backend: 'opencode-http',
  serverUrl: 'http://127.0.0.1:4096',
})
// { run_id: '...', label: 'reverse-string', supervisor_id: '/path/to/socket' }
```

接受 `agent`, (中文(简体) ), `prompt`, (中文(简体) ), `promptFile`, (中文(简体) ), `label`, (中文(简体) ), `dir`, (中文(简体) ), `timeout`, (中文(简体) ), `model`, (中文(简体) ), `thinking`, (中文(简体) ), `backend`, (中文(简体) ), `rosterFile`, (中文(简体) ), `rosterEntry`, (中文(简体) ), `serverUrl`, (中文(简体) ), `sessionId`,以及 `supervisorId` (瞄准特定的套接字).

### 名册选择

`rosterFile` 是高级JSON名册地图的路径 `rosterEntry` 是从中选择的密钥。 每个条目必须包含 `backend` 其中至少一个 `agent` 或者说 `model`数字 :

```json
{
  "planner": {
    "backend": "opencode-acp",
    "model": "provider/planner"
  }
}
```

直接的名册既能产生选择者,也不能提供 `agent`, (中文(简体) ), `model`,或 `backend`。没有名册的直接模式允许独立省略其中的每个身份字段,包括仅后端请求;选定的运行时间供应默认省略值. `thinking` 是运行级别,而不是名册字段,并对照有效的后端检查。 共享选择器验证拒绝缺失选择器对,混合直接/旋转字段,以及未知选择器密钥. 名册文件加载拒绝延迟输入字段,例如 `system`· ; `thinking` 仍然是有效的运行级别选项,但从未从名册条目中读取.

```ts
await spawnTool({
  prompt: 'Analyze the repository',
  dir: '/repo',
  rosterFile: '/repo/roster.json',
  rosterEntry: 'planner',
})
```

名册阶段的选择由Avenor的"去"工作流程跑者解决. 名册条目可以覆盖后端/代理/模型每个阶段。 CLI工作流程回落和嵌入式花名册继承是只使用CLI;稳定的嵌入保持了它现有的行为. 续会必须使用与原届会相同的有效后端.

### `statusTool`

一个或全部运行的报告状态 。 何时 `runId` 省略它列出主管的每行记录.

```ts
import { statusTool } from '@dougbots/avenor-core'

const status = await statusTool({ runId: 'reverse-string', view: 'lifecycle' })
// { run_id: 'reverse-string', label: 'reverse-string', status: 'running', ... }
```

状态值 : `running`, (中文(简体) ), `waiting`, (中文(简体) ), `done`, (中文(简体) ), `failed`, (中文(简体) ), `timeout`, (中文(简体) ), `killed`,以及 `unknown` 当主管不报告任何状况或本套件不承认时. `done`, (中文(简体) ), `failed`, (中文(简体) ), `timeout` 财务报告和审定财务报表 `killed` 终端; `unknown` 没有。 如果等待许可申请,结果包括: `pending_permission` 附有可供选择的选项。 这个 `lifecycle` 视图省去最后输出和诊断元数据; `full` 仍然是兼容性的默认值.

### `resultTool`

等待一跑完成并返回其完整的最终输出而无需记录或事件细节.

```ts
import { resultTool } from '@dougbots/avenor-core'

const result = await resultTool({ runId: 'reverse-string', timeout: '5m' })
// { run_id: 'reverse-string', status: 'done', ready: true, output: '...' }
```

设定 `wait: false` 进行无阻断可用性检查。 立即返回等待许可; 过期结果等待返回 `ready: false` 财务报告和审定财务报表 `timed_out: true` 没有停止运行.

### `answerPermissionTool`

回答待决的运行许可请求。 若为 `requestId` 中,它自动查找当前待决请求.

```ts
import { answerPermissionTool } from '@dougbots/avenor-core'

await answerPermissionTool({ runId: 'my-run', optionId: 'allow-once' })
// { ok: true }
```

### `messageTool`

运行间每个消息的一个工具 : `tell`, (中文(简体) ), `ask`, (中文(简体) ), `reply`, (中文(简体) ), `resume`, (中文(简体) ), `withdraw` 财务报告和审定财务报表 `control_reply`它需要约束 `MessageProvider`,它提供谁的呼叫 说,一个目标如何解决, 并且只有表面可以执行的行动.

```ts
import { messageTool } from '@dougbots/avenor-core'

await messageTool({ action: 'resume', target: 'reverse-string', message: 'Now optimize it for speed' }, provider)
// { action: 'resume', outcome: 'resumed', text: '...', runId: '...', label: '...' }
```

### `peersTool`

列表已连接运行, 重命名运行的显示标签, 或读取对等方最后一个代理消息 。 喜欢 `messageTool`,它通过绑定的提供者读取.

```ts
import { peersTool } from '@dougbots/avenor-core'

const result = await peersTool({ action: 'list' }, provider)
console.log(result.text)
```

### `eventsTool`

从一跑的上盘事件日志读取最近的事件. 按事件类型选择过滤并限制计数(默认为50,最大为1000).

```ts
import { eventsTool } from '@dougbots/avenor-core'

const events = await eventsTool({ runId: 'my-run', types: ['tool_use', 'error'], limit: 20 })
```

QQ 只通过单通支持 `Supervisor` - 通过一项明确的 `supervisorId` 会投出.

### `shutdownTool`

关闭了复仇者守护进程。 过 `force: true` 以立即杀死而不是优雅的终止。 清除用于跟踪运行的监控文件和事件日志 .

```ts
import { shutdownTool } from '@dougbots/avenor-core'

const result = await shutdownTool({ force: false })
// { ok: true, cleaned_up: ['/path/to/sentinel.done', ...] }
```

## 快开始

```ts
import { Supervisor, resultTool, spawnTool, shutdownTool } from '@dougbots/avenor-core'

// 1. The supervisor auto-starts avenor. Call get() early — it's a singleton.
const sup = await Supervisor.get()

// 2. Spawn a run
const { run_id } = await spawnTool({
  agent: 'codex',
  prompt: 'Review src/app.ts for security issues',
  label: 'security-review',
})

// 3. Wait for the complete final output
const result = await resultTool({ runId: run_id })
console.log(result) // { run_id, label, status: 'done', ready: true, output: '...' }

// 4. Clean up
await shutdownTool()
```

## 出口

| 导出 | 仁爱 | 说明 |
| --- | --- | --- |
| `dial` | 函数 | 连接到控制套接字,返回 a `Client` |
| `Client` | 类 | JSON- RPC 守护进程客户端 |
| `Supervisor` | 类 | Singleton检测器处理周期管理器 |
| `findAvenorBinary` | 函数 | 发现二进制路径 |
| `spawnTool` | 函数 | 启动新代理运行 |
| `statusTool` | 函数 | 查询运行的生命周期状态( 单一或全部) |
| `resultTool` | 函数 | 等待并获取一个运行的完整最终输出 |
| `answerPermissionTool` | 函数 | 答复待批准的许可请求 |
| `peersTool` | 函数 | 列表运行, 重命名运行的显示标签, 或读取对等端最后一个消息 |
| `messageTool` | 函数 | 告诉、询问、回复、恢复、撤回或回答控制信息 |
| `eventsTool` | 函数 | 从运行事件日志读取最近的事件 |
| `shutdownTool` | 函数 | 停止复仇者守护进程,清理干净 |

## 常见问题

### @dougbots/avenor-core 是什么？

控制套接字客户端,主管生命周期,以及针对复仇者代理跑者的工具执行\.

### 如何安装 @dougbots/avenor-core？

在项目目录运行 npm install @dougbots/avenor-core，或使用 pnpm add / yarn add / bun add。

### @dougbots/avenor-core 支持 TypeScript 吗？

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

### @dougbots/avenor-core 支持 ESM 还是 CommonJS？

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

### @dougbots/avenor-core 可以商用吗？

@dougbots/avenor-core 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @dougbots/avenor-core 的下载量有多少？

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

### @dougbots/avenor-core 还在维护吗？

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