@ dougbots/ avenor-pi (英语)

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

先决条件

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

# 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起(已公布)

pi install npm:@dougbots/avenor-pi

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

从git repo

pi install git:github.com/sdougbrown/[email protected]

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

地方发展

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

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

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

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:

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

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

手动设置.json

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

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

或为地道:

{
  "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 声明扩展切入点 :

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

特征

中央经纪人的高层同行

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

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 会话名称后来被设定替换了默认值。 使用现有的 工具 :

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

入境请求包括: avenor_message 动作 reply。 。 。 . 告诉作为信息到达 没有回复指示。 这个 克劳德同行 层 可以加入同一个经纪人.

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

身份和交货寿命

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

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

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

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

见 高层对等核查 地图 联合国 课程证明 。 这个 Pi- Claude 集成涵盖 # 434 的部分内容; 其他工具 而简单的MCP客户身份仍然是单独的工作.

工具

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

直接模式和名册模式

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

{
  "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 状态密钥包含活动运行,活代理-树总计,未读通知计数,以及当前民意调查失败计数(参见 完成通知(中文(简体) )
• 完成通知 – 每跑完成一次通知,当您的会话闲置时立即发送,在繁忙时分批分出一次续作
• 投票诊断 - 显示有限制的投票错误 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,按此顺序:

失踪 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数字 :

{
  "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