# @dougbots/avenor-pi 中文文档

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

版本：0\.26\.0
npm 元数据更新时间：2026-11-12T20:22:42.739Z
中文译文更新时间：2026-11-13T00:18:58.675Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：202 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@earendil-works/pi-tui \*，@earendil-works/pi-coding-agent \>=1\.4\.0
- 首次发布：2026-06-20T03:36:00.917Z
- 最新版本发布：2026-11-12T20:22:42.331Z
- 近 30 天下载量：2719（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：44（近 12 个月 44 个）

## 中文简介

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

## 安装

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

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

## README

# @ dougbots/ avenor-pi (英语)

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

## 先决条件

你需要那个 `avenor` 二进制可用 。 它安装到 `~/.botfiles/bin/avenor` 默认.

```bash
# Check it's on PATH
which avenor

# Or set explicitly
export AVENOR_BIN=~/.botfiles/bin/avenor
```

您还需要 1. 4. 0 或 更新的 Pi (`pi --version`) (中文(简体) ). 繁忙的会议交付取决于 页:1 `agent_before_settle` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你忙着工作的时候收到一个通知 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你需要这个 要联系你 丢失的通知不是丢失.

## 安装

### 从npm起(已公布)

```bash
pi install npm:@dougbots/avenor-pi
```

写给您的全局设置( T)`~/.pi/agent/settings.json`) (中文(简体) ). 使用 `-l` 项目-当地安装`.pi/settings.json`) (中文(简体) ).

### 从git repo

```bash
pi install git:github.com/sdougbrown/avenor@v0.1.0
```

Pi 将复制回波并装入扩展名 `packages/pi`。 。 。 .

### 地方发展

**快速测试** 直接使用扩展名运行 pi :

```bash
cd packages/pi
pi -e ./src/index.ts
```

**自动发现的协同** 链接到您的全局扩展目录 :

```bash
mkdir -p ~/.pi/agent/extensions/avenor
ln -sf $(pwd)/packages/pi/src/index.ts ~/.pi/agent/extensions/avenor/index.ts
```

Pi 自动发现 `~/.pi/agent/extensions/*/index.ts`。修改可以热重装 `/reload`。 。 。 .

**设置中的本地路径** - 直接添加已建 dist:

```bash
# Build first
cd packages/pi && bun run build

# Add to settings
pi install /path/to/avenor/packages/pi
```

### 手动设置.json

如果您喜欢直接编辑设置 :

```json
// ~/.pi/agent/settings.json
{
  "packages": ["npm:@dougbots/avenor-pi"]
}
```

或为地道:

```json
{
  "packages": ["/path/to/avenor/packages/pi"]
}
```

## 软件包结构

```
packages/pi/
├── package.json
├── tsdown.config.ts
├── src/
│   ├── index.ts          # main extension, tool registration, commands, and hooks
│   ├── render.ts         # host-only tool-call and result presentation
│   ├── types.ts          # shared types and status emoji mapping
│   └── watch.ts          # EventFeedOverlay TUI component
└── dist/
    └── index.js          # built output (loaded by pi)
```

这个 `pi` 键入 `package.json` 声明扩展切入点 :

```json
{
  "pi": {
    "extensions": ["./dist/index.js"]
  }
}
```

## 特征

### 中央经纪人的高层同行

两个独立开始的会话需要单独的收件箱来互相传递信息. 设定 `AVENOR_BROKER_URL` 在启动 Pi 之前, 此会话在中央注册 经纪人 民意调查.

```bash
AVENOR_BROKER_URL=https://avenor-broker.home.douggo.com pi --name scout
```

经纪人必须支持租赁同伴登记。 皮拒绝经纪人 不承认这种能力。 离开 `AVENOR_RUN_ID` 财务报告和审定财务报表 `AVENOR_BROKER_TOKEN` 未设定为顶级会话; 这些变量加在一起 选择现有的提供儿童模式。 不完全的对被拒绝.

Pi 发布会话名称以便其他会话可以处理 `scout`没有 皮伊的名字, `AVENOR_SESSION_NAME` 或者说 `AVENOR_LABEL` 提供显示名称。 与 没有,顶级会议需要 `pi-<repo>` 从基特顶级( 寄存器外的目录名称). 机器的短名导致 (单位:千美元)`<hostname>-pi-<repo>`只有经纪人在另一台机器上 6个 当另一个会话已经持有标签时会添加字符 run-id 尾端, 当经纪人的会话列表无法完整读取时, 或者当没有时 仓库。 标签被贴在Pi自己的默认, 所以一个经纪人检查 名称跟随带尾部的取来,而不是拒绝重命名。 一个Pi 会话名称后来被设定替换了默认值。 使用现有的 工具 :

```json
{"action":"ask","target":"scout","message":"Ready?","timeout_ms":30000}
```

入境请求包括: `avenor_message` 动作 `reply`。 。 。 . 告诉作为信息到达 没有回复指示。 这个 [克劳德同行 层](https://npmcn.com/package/marketplace/plugins/avenor/README.md) 可以加入同一个经纪人.

当地主管仍然可以从事产卵、状况、成果和地方工作 儿童信息。 单靠中央对等工具并不能启动。 一旦它存在, `avenor_peers` 结合其同龄人和中央同龄人. `avenor_message` 更喜欢精确的ID,然后是一个独特的标签. 复制标签返回 `ambiguous_name`;跨独立经纪人的重复ID也模棱两可. 仅匹配ID并不能确定两个记录是同一对等的. 不完整的上市或运输故障拒绝解决 结合的视角,包括本地的匹配, 因为一个看不见的纪录会掩盖它. 答复和撤回保留拥有其信息的提供者.

#### 身份和交货寿命

Pi为一个会话保留了生成的ID和证书. 登记 复试用同一对. 注册后,临时运输失败 重新投票而不登记其他身份。 成功延长投票 经纪人的60秒租约 会话关闭中止民意调查,等待询问, 然后要求退休;如果不能确认退休,租约将到期.

一个已过期或已退休的同龄人从列表中消失,无法收到消息. 认证、同时投放或过期身份拒绝停止参与; 开始一个新的会话以获得新的身份。 经纪人重启还需要 新会话。 Pi 不默默地替换可能持有信件的收件箱. 经纪人保留已过期和已退休的身份记录,直到关闭围栏 延迟了注册重试,所以这些记录会消耗其一生的记忆.

Polling 在 Pi 注射前从经纪人队列中删除信件 。 Pi 重试 其内膜批量的注入失败,但过程崩溃或中断 民意调查的反应可能会失去交付。 这不是一次交货的保证. 经纪人不包括对租赁同行的重叠民意测验;无记名证书者确实 并没有确定只有一种物理过程持有它们.

注册路线仍对能够到达经纪人的客户开放. 限制 访问预定的尾网或等同的可信任网络,并在 网络不加密传输。 在提出请求的机构或 信头,永远不要在经纪人 URL 中。 不要把它们放入日志、命令参数或 承诺配置。 租赁适用于选择进入的 Pi 同行;现有 Claude 自我登记者保留其现有的终生行为.

见 [高层对等核查 地图](https://npmcn.com/package/skills/verify-avenor/features/top-level-peers.md) 联合国 课程证明 。 这个 Pi- Claude 集成涵盖 # 434 的部分内容; 其他工具 而简单的MCP客户身份仍然是单独的工作.

### 工具

LLM 子代理管理的现有工具 :

| 工具 | 说明 |
| --- | --- |
| `avenor_spawn` | 派出特工逃跑(封锁或放火和遗忘). 使用 `pi` 默认直接模式后端; 接受可选 `agent`, (中文(简体) ), `model`, (中文(简体) ), `prompt`, (中文(简体) ), `dir`, (中文(简体) ), `roster_file`,以及 `roster_entry`在主机模式中,产卵到此过程的单通导师(默认)会收到一个父代理符,用于 `avenor_message`非本地产卵和巢产卵需在简要说明中提供地址;其请求不转交父母. |
| `avenor_status` | 获取运行状态或全部运行状态; 使用 `view="lifecycle"` 用于压缩进度和许可检查 |
| `avenor_result` | 等待运行,并返回其完整的最终产出,没有记录细节 |
| `avenor_inspect` | 审查有界限的记录、工具活动、权限和最后产出 |
| `avenor_answer_permission` | 答复待批准的许可请求 |
| `avenor_message` | 一个明确的信息工具 `action`数字 : `tell`, (中文(简体) ), `ask`, (中文(简体) ), `reply`, (中文(简体) ), `resume`, (中文(简体) ), `withdraw` 或者说 `control_reply`。每个结果都说明结果,如果一个失败的询问,是否仍然可以撤回. |
| `avenor_peers` | 一个有明确内容的同伴工具 `action`数字 : `list` (默认), `rename` 或者说 `last`。 。 。 . `last` 返回目标最后一个代理消息及其停止原因,或者当目标尚未完成转弯时返回空结果. |
| `avenor_events` | 从运行中读取事件 |
| `avenor_kill` | 杀一跑 |
| `avenor_workflow` | 一个明确的工作流程工具 `action`数字 : `status`, (中文(简体) ), `inspect`, (中文(简体) ), `events`, (中文(简体) ), `wait`, (中文(简体) ), `ready`, (中文(简体) ), `controller_status`, (中文(简体) ), `gate`, (中文(简体) ), `complete` 或者说 `cancel`。只读动作不需要允许; `gate`, (中文(简体) ), `complete` 财务报告和审定财务报表 `cancel` 保持他们的权力检查. |
| `avenor_shutdown` | 关掉报仇主管 |

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

直接模式许可证 `agent`, (中文(简体) ), `model`,以及 `backend` 要独立省略,包括仅后端请求;省略值使用运行时默认值。 派用品 `backend: "pi"` 在未给出后端时直接模式。 名册模式同时使用 `roster_file` 财务报告和审定财务报表 `roster_entry`,并将后端选择留给名册条目,而不是应用 Pi 的直接默认:

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

每个名册条目必须包含 `backend` 其中至少一个 `agent` 或者说 `model`。不将名册模式与直接模式合并 `agent`, (中文(简体) ), `model`,或 `backend` 超载 拒绝列入名册 `system`; 条目 `thinking` 仅仅是默认,所以运行级别 `thinking` 仍然胜出,并被验证与有效的后端。 续会必须保留在原来的后端。 使用绝对 `roster_file` 当 Pi 进程和目标项目有不同的工作目录时.

### Pi 特性

在工具之外,扩展与Pi的TUI和事件系统集成:

-   **状态部件** —— 显示所有运行状态、相位和权限状态的持久部件
-   **页脚状态** - 那个 `avenor` 状态密钥包含活动运行,活代理-树总计,未读通知计数,以及当前民意调查失败计数(参见 [完成通知](https://npmcn.com/package/%40dougbots/avenor-pi/#readme-completion-notices)(中文(简体) )
-   **完成通知** – 每跑完成一次通知,当您的会话闲置时立即发送,在繁忙时分批分出一次续作
-   **投票诊断** - 显示有限制的投票错误 `avenor:poll:error` 用于相伴的扩展; 完成通知的发送, 将耗尽其重复, 将分开发射 `avenor:delivery:error`; 失败的上个回合记录 (`session_last_set`)在每一次故障时发射 `avenor:last-turn:error`
-   **中同诊断** - 在高层会议上,每个中央经纪人的失败(会议名称、民意调查、登记、转会出版物、退休)都出现 `avenor:peer:error` 与操作,经纪人拒绝代码,以及身份是否为终端. 每次行动第一次失败,都会引起一次警告;儿童会不断向Stderr报告,这是其主管的记录
-   **现场进展** - 封锁 `avenor_spawn` 调用流进度更新 `onUpdate`
-   **丰富环境** 活性子剂在系统中自动浮出水面,通过 `before_agent_start`
-   **自定义渲染** ——"Pi"扩展将所有Avenor工具调用和结果作为主题,范围摘要. 结果崩溃并扩大了观点.
-   **图标** 运行管理交互式命令:
    -   `/avenor-status` ——所有运行的显示状态
    -   `/avenor-errors` - 显示和清除最近的投票错误
    -   `/avenor-watch <run_id>` ——打开实时事件信息覆盖
    -   `/avenor-cancel <run_id>` ——取消运行中的子代理

### 完成通知

火灾和遗忘的产卵`wait: false`)承诺一件事: 你听说过 当它结束时运行。 每次完成运行都会产生一个通知——标签,终端 状态、 边框输出预览—— 以及它在哪里降落取决于您在 那一刻.

-   **闲.** 通知是作为用户信息发送的,并开始自转。 这个 计数为未读,直到 Pi 确认信件落地, 而收缩则 运行发送等待它完成 。 接受但从未接受的发送 最多发送三次确认;一旦预算用完通知 保存未读的下一个和解, 失败在 `avenor:delivery:error`。 。 。 .
-   **忙着.** 通知已排队,页脚显示 `unread:N`下一个 通常将每个队列通知附加为 `avenor-completion` 在单个续行下自定义消息, 所以有三次运行 工作时完成 意味着三个消息和一个醒来。 解决 以中止或出错结束,则不提供任何结果;通知等待.

每个终端状态排队通知—— `done`, (中文(简体) ), `failed`, (中文(简体) ), `timeout`, (中文(简体) ), `killed`。 。 。 .

`avenor_result` 和阻断 `avenor_spawn` (单位:千美元)`wait: true`自行交付时 他们跑; `avenor_result` 取出你的标签,所以你不需要保留 身份证 A 类 `ready` 结果消耗了运行: 队列通知被丢弃, `unread:N` 摔倒在地上 以后再也没有结果了 结果不是 `ready` - 被兄弟会的停站点、超时或报告中断 等待许可——不消费,其通知是正常的 时间表。 达到完成的阻断产卵返回结果内含和 删除通知; 页脚可以显示瞬态 `unread:N` 运行时 等待在飞行中.

#### 页脚状态

状态密钥下的一个字符串 `avenor`,按此顺序:

| 脚本 | 含义 |
| --- | --- |
| `🟢 label — running [phase] 🔒 +2` | 每个非终端运行一次:状态emoji,标签,状态,相位标签, `🔒` 等待许可, `+N` 为那跑步的活生生的后代 |
| `total:N` | 直接活跑+发现活跑后后代;只有在活跑后后代存在时才出现 |
| `unread:N` | 尚未发送通知: 已排队解决, 或在空闲会话中飞行 |
| `errors:N` | 最近的民意调查失败;通过一个没有增加新错误的周期清除 |

失踪 `unread:N` 或者说 `errors:N` 表示为零. 无 `total:N`键入活动运行行. `unread:N` 计数通知, 不运行, 也可以在上次运行退出后继续设置 —— 否则会话闲置 还可以做广告 `unread:1` 直到你消费或收到通知. `total:N` 轨迹与它们一起活跑并消失. `errors:N` 超过他们 也:当以后的民意调查周期没有增加新的错误时 失败而不是连续不断。 背后的界限历史 `/avenor-errors` 长于 `errors:N`;运行此命令可以清除两者.

### 工具结果通道

Pi 返回 JSON 模型内容 `content[0].text` 和结构化 `details` 页:1 全部工具除外 `avenor_spawn`。渲染器创建了主题、界限摘要 用于显示。 它不修改基本的模型内容或 `details` 对象.

Pi做了总结 将输出、事件和快照捆绑起来 他们展示。 使用 `avenor_result`, (中文(简体) ), `avenor_inspect`,或 `avenor_events` 联 合 国 对应数据.

MCP客户给出自己的结果.

### 代理简介

这个 `avenor_spawn` 工具接受可选 `agent` 参数将映射到 pi 中的已命名配置文件 `agents.json`数字 :

```json
{
  "jockey": {
    "model": "anthropic/claude-sonnet-4",
    "systemPrompt": "You are a PR reviewer..."
  }
}
```

何时 `agent` 设定, 报仇者通行证 `PI_AGENT=<name>` 到 pi 子进程。 这个 `@dougbots/pi-agents` 扩展读取此以载入相应的配置文件( 模式、 系统提示、 工具、 权限) `agents.json` (地点: `PI_CODING_AGENT_DIR` 或者说 `~/.pi/agent/`) (中文(简体) ).

如果你不需要一个名字的档案, `model` 单靠自己就足够了——不需要代理配置或扩展设置.

何时 `pi-agents` 选择了会话范围d `/agent-profile`,此扩展名 也自动将可选会话元数据转发到 Pi 。 复仇者会 不依赖 `pi-agents`; 缺失或错误的元数据被忽略. 环境 不是一个 `avenor_spawn` 参数并仅适用于 Pi-backed child 运行.

## 典型工作流程

**屏蔽( 默认) :**

```
1. avenor_spawn            →  tool call shows live progress, blocks until done
2. tool call returns       →  completion preview with status + session_id
3. avenor_result           →  retrieve the complete final output when needed
4. avenor_inspect          →  inspect transcript and tool details when needed
5. avenor_message           →  action "resume" to optionally iterate
6. avenor_shutdown         →  clean up when finished
```

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

```
1. avenor_spawn × N        →  each returns run_id immediately
2. (status widget updates) →  persistent widget shows all active runs
3. avenor_status           →  optional compact lifecycle/permission check
4. avenor_result           →  wait for and retrieve each final output
5. /avenor-watch <id>      →  open live diagnostics for a specific run
```

## 依赖关系

-   **端点 :** `@earendil-works/pi-coding-agent` (Pi运行时间,由Pi提供)
-   **端点 :** `@earendil-works/pi-tui` (TUI组件,由pi提供)
-   **依赖性 :** `@dougbots/avenor-core` (监督员、客户端、工具原始人)
-   **二进制 :** `avenor` 必须在 `PATH` 或时 `AVENOR_BIN`

## 常见问题

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

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

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

在项目目录运行 npm install @dougbots/avenor-pi，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@earendil-works/pi-tui（\*）、@earendil-works/pi-coding-agent（\>=1\.4\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

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

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

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

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

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

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

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