# @dougbots/avenor-opencode 中文文档

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

版本：0\.26\.0
npm 元数据更新时间：2026-11-12T20:25:36.821Z
中文译文更新时间：2026-11-13T01:52:27.962Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：737 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@opencode-ai/plugin 1\.15\.3
- 首次发布：2026-05-17T05:23:01.319Z
- 最新版本发布：2026-11-12T20:25:36.464Z
- 近 30 天下载量：2536（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：49（近 12 个月 49 个）

## 中文简介

在您的 OpenCode 会话中, 注册代理服务器的 OpenCode 插件将作为工具运行 。 当您需要子代理来处理一个定义明确的任务时——写出代码,运行测试,搜索一个代码库——在您保持会话焦点的同时,代理者在背景中运行.

## 安装

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

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

## README

# @ dougbots/ avenor- opencode (打开代码)

在您的 OpenCode 会话中, 注册代理服务器的 OpenCode 插件将作为工具运行 。 当您需要子代理来处理一个定义明确的任务时——写出代码,运行测试,搜索一个代码库——在您保持会话焦点的同时,代理者在背景中运行.

## 设置

安装套件并附带对等依赖 :

```bash
bun add @dougbots/avenor-opencode @opencode-ai/plugin@1.15.3
```

OpenCode 2 直接从默认导出加载插件定义形状, 因此运行时不需要 OpenCode 2 包; OpenCode 1 主机 (1. 18.29+) 调用同一切入点 `server()`。 。 。 .

你还需要 `avenor` 二进制. 要么加进你身上 `PATH` 或设置 `AVENOR_BIN` 环境变量到其位置.

```bash
# Option 1 — add to PATH (e.g. via mise, brew, or manual install)
which avenor

# Option 2 — explicit path
export AVENOR_BIN=~/.botfiles/bin/avenor
```

## 注册插件

添加 `@dougbots/avenor-opencode` 到您的 OpenCode 配置 。 如果您使用全局配置 :

```json
// ~/.opencode.json
{
  "plugins": ["@dougbots/avenor-opencode"]
}
```

对于项目级别配置,将同一条目添加到 `.opencode.json` 在你的还原根.

注册后,插件会曝光您 OpenCode 代理可以直接调用的工具——不需要额外的配置 : `avenor_spawn`, (中文(简体) ), `avenor_status`, (中文(简体) ), `avenor_result`, (中文(简体) ), `avenor_inspect`, (中文(简体) ), `avenor_answer_permission`, (中文(简体) ), `avenor_message`, (中文(简体) ), `avenor_peers`, (中文(简体) ), `avenor_events`, (中文(简体) ), `avenor_kill`, (中文(简体) ), `avenor_shutdown`,以及 `avenor_workflow`。 。 。 .

## 行为

当发送运行时 `avenor_spawn`,插件为:

1.  **默认区块** ——工具调用保持开放状态,随着子代理运行更新其标题和元数据,与OpenCode自己的子代理工具调用完全一样. 当运行到达终端状态时工具返回 .
2.  **完成后重新提示** 当 `wait=false` (fire-and-forget)运行完成,插件会自动向管弦乐会场注入一个完成信息,所以LLM在没有人工投票的情况下接取.
3.  **路由权限** 当一个子剂运行在 `opencode-http` 后端请求权限,插件向管弦乐会话注入了再提示. LLM可以打电话 `avenor_answer_permission` ;正常权限对话框也显示为倒置.
4.  **格式化结果** —— OpenCode 返回简洁, 其共享的有约束的道词 `output` 页:1 `avenor_status`, (中文(简体) ), `avenor_result`, (中文(简体) ), `avenor_answer_permission`, (中文(简体) ), `avenor_message`, (中文(简体) ), `avenor_peers`, (中文(简体) ), `avenor_events`, (中文(简体) ), `avenor_inspect`,以及 `avenor_shutdown`结构化元数据留在主机/会场状态.
5.  **发布自己完成的回合** ——每一次对话都公布其已解决的回合,作为自己的约束,通过经纪人的同级最后消息途径,按每个对话顺序进行,所以是同行的 `avenor_peers` `action: "last"` 读一下它的名字.
6.  **接收信件** - 绑定的谈话运行一个 `avenor feed broker` 消费者,被认证为对话本身的跑道,每条饲料记录的到来作为快件标记为另一会话的词句,一次一个记录的到来顺序. 原生标题作为跑步名称发布,所以同龄人可以看到对话的自有名称;没有原生标题,对话使用 `opencode-<repo>` 从其目录中,具有相同的主机名和运行-id-tail规则的 Pi 扩展使用. 见 [邮件](https://npmcn.com/package/docs/messaging.md#opencode-conversations)。 。 。 .

MCP客户给出自己的结果.

## 工具

### `avenor_spawn`

在当前工作目录中发送代理运行 .

**屏蔽模式( 默认 ), `wait=true`:** 工具调用显示实时进度更新,并在运行完成时返回结构化结果.

**火灾和遗忘`wait=false`:** 随即返回 `run_id`. 完成后自动重排会话.

| 参数 | 需求 | 说明 |
| --- | --- | --- |
| `agent` | 没有 | 代理名称; 省略使用提供的模型或运行时间默认值 |
| `prompt` | 没有 | 提示文本 |
| `prompt_file` | 没有 | 快速文件路径 |
| `label` | 没有 | 运行时的可读标签 |
| `timeout` | 没有 | 暂停时间(例如:. `3600s`, (中文(简体) ), `30m`(中文(简体) ) |
| `model` | 没有 | 模型覆盖 |
| `thinking` | 没有 | 运行级推理控制; 不支持的有效后端拒绝显式值 |
| `backend` | 没有 | 后端覆盖; 直接模式默认为 Avenor `opencode-acp` 删除后端 |
| `roster_file` | 没有 | 高级名册地图路径 |
| `roster_entry` | 没有 | 内键 `roster_file` |
| `wait` | 没有 | 屏蔽到完成( 默认) `true`(中文(简体) ) |
| `supervisor_id` | 没有 | 通过 socket 路径重新使用已有导师 |

产卵母道是对话本身的束缚跑道,所以通过 只有在产卵经过控制运行的主管——默认情况下 单子,或明确命名的同一套接字。 一只卵子指着另一个 主管仍然在那里运行,没有母路线.

工作目录( E)`dir`)是从您的 OpenCode 会话上下文自动被注入的——它不是一个面向用户的参数.

#### 直接模式和名册模式

使用 `roster_file` 加号 `roster_entry` 以选择完整的身份。 每个名册条目都要求 `backend` 其中至少一个 `agent` 或者说 `model`; 名册模式拒绝直接 `agent`, (中文(简体) ), `model`,以及 `backend` 超载 直接模式允许所有三个身份字段独立省略,包括后端只选择. 名册模式不应用直接 `opencode-acp` 默认.

```json
{
  "prompt": "Review the repository",
  "roster_file": "/repo/roster.json",
  "roster_entry": "reviewer",
  "wait": true
}
```

列入名册的条目 `backend`, (中文(简体) ), `agent`, (中文(简体) ), `model`,可选 `thinking` 默认; `system` 被拒绝。 明确的运行级别 `thinking` 胜过条目, 并被验证对有效的后端。 续会不能改变后端。 插件通过 `roster_file` 因此,当OpenCode进程目录与项目目录不同时,绝对路径可以避免模糊.

### `avenor_status`

获取特定运行状态或所有活动运行状态 。 使用紧凑 `lifecycle` 查看进度和等待检查的许可; `full` 仍然是兼容默认值.

| 参数 | 需求 | 说明 |
| --- | --- | --- |
| `run_id` | 没有 | 用于查询的特定运行 ID( 所有运行的密件) |
| `view` | 没有 | 详细反应: `lifecycle` 或者说 `full` (默认) |
| `supervisor_id` | 没有 | 通过 socket 路径重新使用已有导师 |

### `avenor_result`

等待运行完成并返回其完整的最终输出,没有记录或事件细节. 这是输出检索工具; `avenor_status` 仍然是一次生命周期检查.

| 参数 | 需求 | 说明 |
| --- | --- | --- |
| `run_id` | 对 | 运行ID等待 |
| `wait` | 没有 | 等待终端结果( 默认) `true`(中文(简体) ) |
| `timeout` | 没有 | 最多等待时间( 例如 `30s` 或者说 `5m`(中文(简体) ) |
| `supervisor_id` | 没有 | 通过 socket 路径重新使用已有导师 |

被封锁的运行返回其等待的许可, 而不是永远等待 。 如果此工具本身的超时过期, 它返回最新的状态 `ready: false` 财务报告和审定财务报表 `timed_out: true`。 。 。 .

### `avenor_inspect`

使用 `avenor_inspect` 以审查一个有界限的快照。 简况包括文字记录、完成的工具和活的工具、权限和最后产出。 使用 `avenor_events` 当需要原始事件记录时.

| 参数 | 需求 | 说明 |
| --- | --- | --- |
| `run_id` | 对 | 运行ID检查 |
| `limit` | 没有 | 要缩小到快照的最大事件 |
| `after_seq` | 没有 | 只包含在此序列号后的事件 |
| `supervisor_id` | 没有 | 通过 socket 路径重新使用已有导师 |

### `avenor_answer_permission`

回答一个待批准的许可请求。 这个 `option_id` 从 `pending_permission.options` 数组返回 `avenor_status`。 。 。 .

| 参数 | 需求 | 说明 |
| --- | --- | --- |
| `run_id` | 对 | 以待决权限运行 ID |
| `option_id` | 对 | 选项编号从 `pending_permission.options` |
| `request_id` | 没有 | 请求ID( 如果省略, 自动发现) |
| `supervisor_id` | 没有 | 通过 socket 路径重新使用已有导师 |

### `avenor_message`

向另一个运行发送消息,撤回一个待决请求,恢复一个已完成的运行,或者发送控制回复. 每个行动都是明确的,每个结果都表明一个失败的要求是否仍然可以撤回.

| `action` | 所需字段 | 它会做什么 |
| --- | --- | --- |
| `tell` | `target`, (中文(简体) ), `message` | 在不创建询问边缘的情况下发送消息 |
| `ask` | `target`, (中文(简体) ), `message`选项 `timeout_ms` | 传递信息等待回复 |
| `reply` | `reply_to`, (中文(简体) ), `message` | 答一入道传. 从其索赔中答复了这一表面的询问;经纪人将这一消息传送回寄件人。 没有路由报告的信件 ID `edge-absent` |
| `resume` | `target`, (中文(简体) ), `message`选项 `label`, (中文(简体) ), `idempotency_key` | 恢复其持续届会的完成运行 |
| `withdraw` | `message_id` | 撤回待决请求 |
| `control_reply` | `target`选项 `payload` | 在供应商支持的情况下发送控制回复 |

`target` 是一个运行的id,一个对等标签,或者 `"self"`。 。 。 . `timeout_ms` 必须是不超过共享询问盖的整数。 此工具不使用 `supervisor_id`;它与默认的主管有关.

谈话是自言自语 而不是主管: `tell`, (中文(简体) ), `ask`, (中文(简体) ), `reply` 财务报告和审定财务报表 `withdraw` 作为对话, `resume` 仅保留所有者,以及 `control_reply` 这里没有支持的表面 。 答复通过feed的声称库回答——询问这次谈话的反馈是回答,第二次答复报告 `edge-absent`。 。 。 .

该工具的结构化元数据是"蛇"中共享的合同对象(`action`, (中文(简体) ), `outcome`, (中文(简体) ), `text`,以及 `message_id`, (中文(简体) ), `run_id`, (中文(简体) ), `label`, (中文(简体) ), `reply`, (中文(简体) ), `sentinel_file`, (中文(简体) ), `on_event` 当结果带回来时, MCP 主机返回的字段相同.

### `avenor_peers`

列出可见代理会话,重命名运行,或读取运行中最后一个代理消息.

| `action` | 字段 | 它会做什么 |
| --- | --- | --- |
| `list` (默认) | —— 说 | 列出可见的对等点 |
| `rename` | `name`选项 `session_id` | 默认更改显示名称 |
| `last` | `target` | 读取目标最后一个代理消息及其停止原因 |

`last` 在目标尚未完成转弯时返回共享的空结果. `target` 接受运行的id、标签或 `"self"`。结构化元数据是 `{peers}`, (中文(简体) ), `{renamed}` 或者说 `{last}` 在 snake case中,与 MCP 主机返回的对象相同.

### `avenor_events`

从运行读取事件,可选择按类型过滤. 返回最后的 N 事件 .

| 参数 | 需求 | 说明 |
| --- | --- | --- |
| `run_id` | 对 | 运行ID以读取事件 |
| `types` | 没有 | 按事件类型过滤( 字符串阵列) |
| `limit` | 没有 | 返回最大事件( 默认为 50) |
| `supervisor_id` | 没有 | 通过 socket 路径重新使用已有导师 |

### `avenor_kill`

停止运行而不关闭主管。 其他运行和主管自己持续运行.

| 参数 | 需求 | 说明 |
| --- | --- | --- |
| `run_id` | 对 | 运行运行的ID或标签以终止 |
| `supervisor_id` | 没有 | 多监督模式的主管ID |

### `avenor_workflow`

驱动一个持久的工作流程实例 。 一个 `action` 选择动词; 每个动作都有一个可选 `supervisor_id` 用于多监督模式。 只读动作不需要允许; `gate`, (中文(简体) ), `complete` 财务报告和审定财务报表 `cancel` 保持他们的权力检查.

| 行动 | 参数 | 目的 |
| --- | --- | --- |
| `status` | `workflow_id` | 轻量级实例状态 |
| `inspect` | `workflow_id` | 完整实例细节 |
| `events` | `workflow_id`, (中文(简体) ), `after_seq`, (中文(简体) ), `limit` | 这个案例的日志事件 |
| `wait` | `workflow_id`, (中文(简体) ), `timeout` | 等待终端状态或超时 |
| `ready` | `controller_id`, (中文(简体) ), `limit` | 申请自动派送的候选人;不给予租约 |
| `controller_status` | `controller_id` | 一个控制员的状态 一个咨询候选人的计数, 或者一个汇总清单没有它 |
| `gate` | `workflow_id`, (中文(简体) ), `node_id`, (中文(简体) ), `gate_id`, (中文(简体) ), `activation_id`, (中文(简体) ), `operation`字段 | 记录停放的门的决定 `awaiting_gate` 激活 |
| `complete` | `workflow_id`, (中文(简体) ), `node_id`, (中文(简体) ), `activation_id`, (中文(简体) ), `attempt_id`, (中文(简体) ), `lease_id`, (中文(简体) ), `owner_token`, (中文(简体) ), `outcome`, (中文(简体) ), `outputs`, (中文(简体) ), `artifacts` | 完成一台机器/外部交接激活 |
| `cancel` | `workflow_id`, (中文(简体) ), `actor`, (中文(简体) ), `reason` | 取消整个实例( 最终) `canceled`(中文(简体) ) |

基本控制方法为 [`docs/control-protocol.md`](https://npmcn.com/package/docs/control-protocol.md)。 。 。 .

### `avenor_shutdown`

关闭报务监督程序,清理临时档案. 工作完成或主管失事时请打电话.

| 参数 | 需求 | 说明 |
| --- | --- | --- |
| `supervisor_id` | 没有 | 监事会关闭( 默认为单通) |
| `force` | 没有 | 强制关闭而不是优雅 |

关机时有个主管 命名另一个 离开此插件的束缚 对话、他们的素材和他们的证书 主管 谈话一定会放弃的.

## 典型工作流程

**屏蔽( 默认) :**

```
1. avenor_spawn            →  tool call shows live progress, blocks until done
2. (avenor_answer_permission  →  if a permission is routed to this session mid-run)
3. tool call returns       →  completion preview with status + session_id
4. avenor_result           →  retrieve the complete final output when needed
5. avenor_message          →  optionally iterate with action "resume"
6. avenor_shutdown         →  clean up when finished
```

**平行/火灾和遗忘(`wait=false`:**

```
1. avenor_spawn × N        →  each returns run_id immediately
2. plugin starts monitoring each run immediately
3. (sub-agent finishes)    →  plugin re-prompts this session automatically
4. avenor_answer_permission  →  if a permission was routed here mid-run
5. avenor_result           →  wait for and retrieve the final output
6. avenor_events           →  inspect raw event history when needed
```

## 依赖关系

-   **端点 :** `@opencode-ai/plugin` v1.15.3( 主机代理机用于挂载插件的运行时间)
-   **构建时间 :** `@opencode/plugin` (OpenCode 2 加载器的类型定义;已建成的入站点没有运行时间引用,因此一代都不安装)
-   **二进制 :** `avenor` 必须在 `PATH` 或时 `AVENOR_BIN` (在第一个工具引用时选中, 而非插件加载时间)

## 常见问题

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

在您的 OpenCode 会话中, 注册代理服务器的 OpenCode 插件将作为工具运行 。 当您需要子代理来处理一个定义明确的任务时——写出代码,运行测试,搜索一个代码库——在您保持会话焦点的同时,代理者在背景中运行\.

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

在项目目录运行 npm install @dougbots/avenor-opencode，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@opencode-ai/plugin（1\.15\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

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

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

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

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

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

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

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