# @xian0x5a/pi-durable-subagents 中文文档

规范地址：https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/

版本：0\.4\.6
npm 元数据更新时间：2026-11-02T21:48:37.298Z
中文译文更新时间：2026-11-02T22:44:42.407Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.9 MB，185 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.19\.0
- 运行依赖：4 个
- peer 依赖：typebox \*，@earendil-works/pi-ai \>=0\.99\.0，@earendil-works/pi-tui \>=0\.99\.0，@earendil-works/pi-agent-core \>=0\.99\.0，@earendil-works/pi-coding-agent \>=0\.99\.0
- 首次发布：2026-10-06T10:22:27.011Z
- 最新版本发布：2026-11-02T21:48:36.934Z
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

在显式所有者和产卵者监督下异步协作的持久Pi代理。

## 安装

```sh
npm install @xian0x5a/pi-durable-subagents
```

也可以使用：`pnpm add @xian0x5a/pi-durable-subagents`、`yarn add @xian0x5a/pi-durable-subagents`、`bun add @xian0x5a/pi-durable-subagents`

## README

# pi-durable-subagents

在显式所有者和产卵者监督下异步协作的持久Pi代理。

## 功能

### 交互代理切换

运行 `/agents` 从业主或任何代理打开代理切换器。使用 `/agents owner` 在不打开切换器的情况下直接返回到确切安装的Workflow Owner演示：

![The Agent switcher overlay with an Attention Inbox Human Request above the Live Agent tree](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/images/agent-switcher.png)

选择一个子代理以进入其完整的Pi会话并直接与之交互——读取其记录、在其编辑器中输入或使用其命令和工具。在全屏模式下，单击编辑器上方的活动dock会打开相同的切换器。

### 协调与监督

-   **Owner-directed工作流:** 当前Pi会话，在TUI或无头模式下，成为持久的工作流所有者。分叉或克隆到一个新的，独立的工作流。看到 [老板工作流程](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/owner-workflow.md).
-   **持久子代理：** 代理创建可配置的、上下文独立的子节点 `agent_spawn`． 看到 [代理产卵](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/agent-spawning.md).
-   **消息传递和请求：** `agent_message` 发送消息和标题请求； `agent_wait` 加入他们的答案。看到 [代理信息](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/agent-messaging.md).
-   **可见的义务:** `agent_observe` 列出并检索未完成的请求。
-   **人类的决策:** 在TUI中，生成的Agent可以阻塞一个自由形式的Human Answer `ask_user`． 看到 [人类的请求](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/human-requests.md).
-   **运行监督:** 所有者和直接产卵者检查，中断，恢复，或中止精确运行 `agent_observe` 和 `agent_control`． 看到 [运行监督](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/run-supervision.md).
-   **事件处理:** 运行时提醒恢复被遗忘的答案；隔离的版主在策略范围内处理持久的停滞、死锁和失败。看到 [操作事件缓和](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/operational-incident-moderation.md).
-   **持久的复苏:** 一个新的主机重建权威和来自Pi转录的待处理请求。看到 [主机冷恢复](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/cold-host-recovery.md).
-   **模型的政策:** `/agents models` 维护一个持久的拒绝列表，列出孩子不能使用的模型。看到 [工作流策略](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/workflow-policy.md).
-   **虚拟模型:** 一次命名一个有序的模型后备列表并使用 `virtual/<name>` 在模板和刷出；修复列表更新每个Agent。在 `/agents` 配置选项卡(`c`）. 看到 [虚拟模型](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/workflow-policy.md#virtual-models).

协调不会覆盖Pi的压缩、重试或传输设置。

### 持久的义务

![A Request becomes an Answer obligation delivered to the Responder; only an Answer or the requester's Cancellation closes it. A Host watcher reminds a stalled Responder, then starts a Moderator that can intervene or escalate to the Workflow Owner.](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/images/request-obligation.svg)

请求创建一个应答义务，在提交应答或收到请求者的取消请求之前，应答者需要承担该义务。停止、恢复或失败Run，或者人为地在子进程中输入，都会使它保持打开状态，而普通的Message则不会创建任何状态。当有义务的代理停止时，主机会发送一个提醒（如果在人工输入时停止，则会发送一个免费提醒），然后启动一个Moderator，该Moderator可以进行干预或升级到Workflow Owner。看到 [代理信息](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/agent-messaging.md) 和 [操作事件缓和](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/operational-incident-moderation.md).

## 安装

从npm安装：

```bash
pi install npm:@xian0x5a/pi-durable-subagents
```

或者直接跟踪Git存储库：

```bash
pi install git:github.com/xian0x5a/pi-durable-subagents
```

附加终端支持使用 `node-pty` 本地插件。它为x64和arm64上的Linux、macOS和Windows提供了预构建的二进制文件，因此这些平台不需要在安装时构建。其他平台从源代码编译它，它需要一个c++工具链和npm权限来运行它的安装脚本。

## 使用

启动交互式Pi TUI：

```bash
pi
```

包采用当前会话作为工作流所有者；不需要单独的激活命令。

无头模式也承载所有者，没有人在循环中：

```bash
pi -p "Delegate the review to two agents and summarize their answers"
pi --mode json "..."
pi --mode rpc
```

在无头工作流中，代理不能使用 `ask_user`； 相反，他们会通过上级向上级投诉。当一个孩子的Run暂停时，它的主管会得到通知。代理选择器、代理视图和活动dock需要TUI。报表存储在会话中，因此以交互方式重新打开它(`pi --session <file>`)来阅读它们。看到 [无头的工作流](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/owner-workflow.md#headless-workflows).

## 建议的代理模板

模板是创建预设：编辑只适用于未来的刷出。看到 [代理模板](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/agent-spawning.md#agent-templates) 查看配置细节。

下面两个模板都使用了一个 [虚拟模型](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/workflow-policy.md#virtual-models)因此，退役或禁用的模型被固定在一个地方。 `thinking: preset` 在自己的级别上运行每个条目。把它加入 `/agents` 配置选项卡(`c`)，或 `~/.pi/agent/config/pi-durable-subagents.json`：

```json
{
  "virtualModels": {
    "cheap": [
      { "id": "openai-codex/gpt-6-luna", "thinking": "high" },
      { "id": "deepseek/deepseek-v4-flash", "thinking": "high" }
    ]
  }
}
```

### `cheap-delegate`

对于有界实现、例程执行和有针对性的事实查找，这是一个经济高效的默认值。

另存为 `~/.agents/agents/cheap-delegate.md`：

```markdown
---
name: cheap-delegate
useWhen: >-
  Use as a cost-efficient default delegate for tasks with clear goals and
  verifiable outcomes, such as implementation with explicit requirements or
  instructions and bounded scope, routine execution, or targeted fact-finding.
  Do not use for thorough review, open-ended investigation, high-stakes security
  or architecture work, or tasks requiring substantial ambiguity resolution.
  If its results remain inadequate after several iterations and show no obvious
  improvement, stop assigning that task to this template.
models:
  - id: virtual/cheap
    thinking: preset
---
```

### `moderator`

自动用于事件处理；把它指向更便宜的型号。

另存为 `~/.agents/agents/moderator.md`：

```markdown
---
name: moderator
useWhen: Use for moderation and incident response.
models:
  - id: virtual/cheap
    thinking: preset
---
```

## 兼容性

Pi提供了包的Pi对等模块；根据正在运行的主机在结构上检查兼容性。需要Pi 0.99.0或更新版本，这是第一个带有本地虚拟模型的版本。看到 [开发](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/development.md) 负责一致性检验和监督测试运行。

## 信任与坚持

协调是基于信任的协议，而不是安全边界。所有者、刷出者、普通代理和版主是可信任的参与者，通过角色作用域工具进行操作。

Pi抄本是标识、消息、请求、交付和提交结果的持久权威。调度队列、保持、实时运行状态、UI关注和打开的代理视图附件是不稳定的：有序关闭会关闭它们，而突然的进程丢失可能会丢弃它们，而不会声明持久完成。

## 文档

-   [老板工作流程](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/owner-workflow.md) -激活，无头工作流和兼容性行为
-   [业主堵塞诊断](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/owner-blockage-diagnostics.md) -持久的准入失败状态和 `/agents diagnostics`
-   [转录修复设计](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/workflow-transcript-repair-design.md) -建议的工作流程自有修理慢化剂和已验证的更换；没有实现
-   [操作事件缓和](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/operational-incident-moderation.md) —触发检测、有界处理、Moderator权限、Resolution和恢复
-   [主机冷恢复](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/cold-host-recovery.md) -记录发现、隔离、休眠名册和剩余请求
-   [工作流策略](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/workflow-policy.md) -可重新加载执行，交付，审查限制 `/agents models` 排除列表和虚拟模型
-   [代理产卵](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/agent-spawning.md) -子创建和接收语义
-   [代理信息](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/agent-messaging.md) —交付方式和Agent Requests
-   [人类的请求](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/human-requests.md) -转录原生问题，回答模式和承诺
-   [代理选择器](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/agent-selector.md) —活动层次、休眠近因、关注和键盘导航
-   [交互式代理视图接受](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/agent-view-acceptance.md) -完整模式渲染、输入、转换、隔离和生命周期证据
-   [运行监督](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/run-supervision.md) —观察、中断、恢复、中止和代理视图保留
-   [开发](https://npmcn.com/package/%40xian0x5a/pi-durable-subagents/docs/development.md) -兼容性门，有监督的测试运行和截止日期

## 常见问题

### @xian0x5a/pi-durable-subagents 是什么？

在显式所有者和产卵者监督下异步协作的持久Pi代理。

### 如何安装 @xian0x5a/pi-durable-subagents？

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

### @xian0x5a/pi-durable-subagents 支持 TypeScript 吗？

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

### @xian0x5a/pi-durable-subagents 支持 ESM 还是 CommonJS？

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

### @xian0x5a/pi-durable-subagents 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @xian0x5a/pi-durable-subagents 可以商用吗？

@xian0x5a/pi-durable-subagents 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @xian0x5a/pi-durable-subagents 还在维护吗？

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