# @jangmanj/pi-bgtasks 中文文档

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

版本：0\.1\.1
npm 元数据更新时间：2026-11-01T05:40:38.768Z
中文译文更新时间：2026-11-01T13:20:36.486Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：78.5 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.19\.0
- 运行依赖：0 个
- peer 依赖：@earendil-works/pi-coding-agent \>=1\.4\.0
- 首次发布：2026-10-28T12:21:31.951Z
- 最新版本发布：2026-11-01T05:40:38.458Z
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

后台shell任务和Pi的进程内子代理：bg\_run， bg\_logs, bg\_kill, subagent。

## 安装

```sh
npm install @jangmanj/pi-bgtasks
```

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

## README

# @jangmanj / pi-bgtasks

后台shell任务和Pi声明的进程内子代理。四个工具，没有命令，没有设置。

| 工具 | 做 | 模型被告知 |
| --- | --- | --- |
| `bg_run` | 在后台启动shell命令。返回id和日志路径。 | 在阻塞工作前启动长命令；完成会唤醒你，所以不要睡觉，不要拖延；仅在每个任务退出并检查后报告完成情况。 |
| `subagent` | 运行一个 **宣布** 代理、前台或 `background: true`. | 交出独立的相邻工作（绘图、长读、研究、复习、独立切片），一次完成几个工作再阻塞；提示是整个简短的；报告是证据，而不是完成。 |
| `bg_logs` | 列出任务和子代理，或按id读取一个（shell tail或子代理报告）。 | 为阅读多做一个唤醒预览，或作一个决定的新鲜状态；不是一种等待的方式。 |
| `bg_kill` | 按id逐个停止。 | 为了不再需要的工作或逃跑；从不唤醒一个回合。 |

工具描述携带这些指令，因此它们与工具一起进入任何会话。三个短 `promptGuidelines` 再加上一个将军 `AGENTS.md` 通常不会：开始边工作前，阻塞工作，写一个完整的摘要，永远不要投票。

不要装 `pi-bg-tasks` 或者 `@gotgenes/pi-subagents`;工具名称冲突。

## 安装

```sh
pi install npm:@jangmanj/pi-bgtasks
```

需要Pi 1.4.0及以上版本，Node 22.19及以上版本。

## 声明子代理

子代理只有在文件声明了它的全部内容时才存在。文件: `<cwd>/.pi/agents/<name>.md` 在 `$PI_CODING_AGENT_DIR/agents/<name>.md` (默认 `~/.pi/agent/agents/`）. 项目文件通过名称获胜。编辑适用于下一个刷出。

```markdown
---
description: Reads code and reports findings
tools: read, grep, find, ls
model: provider/model-id
thinking: high
max_turns: 20
---
You read code and report what you find. Do not edit files.
```

| 关键 | 要求 | 规则 |
| --- | --- | --- |
| `description` | 是 | 一行，显示给父模型。 |
| `tools` | 是 | 确切的允许列表：名称或 `*` 模式，逗号列表或 `[a, b]`. `none` 意味着没有工具。 |
| `model` | 是 | `provider/id` （精确），或者一个裸模型id，解析如下。从来没有继承; `inherit` 是无效的。 |
| `thinking` | 否 | `off minimal low medium high xhigh max`. |
| `max_turns` | 否 | 1-500，默认30。到达它将使运行失败并保留部分结果。 |
| 身体 | 是 | 整个系统提示。没有继承父提示、上下文文件、技能或对话。 |

### 未申报的名称

调用 `subagent` 使用没有文件的名称创建安全默认值，而不是失败：tools `read, grep, find, ls` (只读) `max_turns` 30，以及要求批处理工作的提示，观察和引用的权利要求，以及以结尾的最终消息 `done` 或者 `partial` 打开的项目。它被保存为 `~/.pi/agent/agents/<name>.md` 所以它变成了一个你可以编辑的普通声明；现有文件永远不会被覆盖。这个 `model` 参数，并选择其模型；如果没有它，调用将失败并列出可用的模型。在保存任何内容之前检查模型，结果告诉调用者创建了什么以及在哪里创建了什么。 `model` 已经声明的代理被拒绝：声明的模型是权威的。文件存在但无效的名称是错误，而不是创建的触发器。

解析是严格的。未知的键、缺失的字段或错误的值使该文件无效；它是不可生成的，并且当模型要求它时显示错误。无效的项目文件不会退回到它所隐藏的全局文件。

孩子永远不会收到这个扩展的工具(`subagent`， `bg_*`)，即使通过 `*` 模式。命名它们的声明是无效的。

## 选择供应商

`provider/id` 完全按照书面使用；它永远不会与另一条路由交换。一个裸模型id（没有提供者）在每个有凭证的提供者中查找，并使用Pi自己的验证数据(`isUsingSubscription`当运行时不公开OAuth时，回退到OAuth)。在最佳层绑定的两个提供者是列出它们的错误；Pi从不猜测它们之间的关系。解析后的 `provider/id` 显示在每个报表标题中。

## 打电话的人得到了什么

每个结果（前景或唤醒中的结果）都是一个报告：一个标题（id、代理、状态、模型、回合、工具调用、持续时间），然后是直接声明的结果。

| 状态 | 身体 |
| --- | --- |
| `RUNNING` | 包含文本的最新助手消息，标记为 `Latest progress (not the final report)`。在第一个这样的信息出现之前，报告说还没有可用的辅助进展。 |
| `COMPLETED` | 孩子最后一条包含文字的信息。空洞的回答永远不会无声地返回； `NO RESULT: the subagent finished without writing a final answer…` |
| `FAILED` | `FAILED: <reason>` (提供者错误, `max_turns` 到达，启动失败)，然后任何部分输出，标记为部分。 |
| `KILLED` | `KILLED before finishing.` 加上部分输出。 |

失败和击杀被放在前台，所以它们作为工具错误出现。超过32 KB的输出被截断 `[truncated: showing N of M characters]`;4 KB的唤醒预览指向 `bg_logs` 其余的。 `bg_logs` 标记未被读取的已完成作业 `[completed, unread]`.

## 行为

-   前台子代理返回结果，或者在失败时抛出部分结果。Pi的中止阻止了他们。
-   后台作业一旦完成就会触发后续回合，除非开始时是这样 `notifyOnCompletion: false` (包括 `bg_run` 和 `subagent`);然后等待结果 `bg_logs`，失败将页脚变为红色，直到它被读取。如果代理忙，则在下一个回合边界注入结果。阅读它 `bg_logs` 首先抑制尾流。 `bg_kill` 永远不会醒来。
-   唤醒 `display: false`：模特领报告，成绩单无卡。页脚携带用户可见的状态。
-   限制：16个运行shell任务，4个运行子代理，每种保存32条完成记录。
-   Shell任务在自己的进程组中运行(`bash -lc`): SIGTERM， 1.5 s后SIGKILL。日志 `0600` 在每个用户中 `0700` 目录(`PI_BG_LOG_DIR` 覆盖)。如果pi在没有shutdown钩子的情况下退出，则运行组被sigkill。
-   工作生存 `/reload`;回调函数到达当前扩展实例。它们在任何其他关闭时停止。
-   放在唤醒消息中的输出是xml转义和有界的。

## 代理并发

一次最多运行四个子代理，计算会话构建和拆除。进一步的请求排队(`Queued subagent <id>`)，并在空闲槽位时以FIFO顺序开始；队列最多容纳64个请求，满队列拒绝新请求。前台调用通过队列等待；后台调用立即返回一个id，并保持通常的完成唤醒。读取队列工作不会将其未来结果标记为已读。 `bg_kill` 取消排队工作而不启动它或唤醒一个回合；Shutdown在停止运行子进程之前取消排队的工作。启动失败的会话将保留为失败报告，并遵循正常的唤醒规则。页脚计算正在运行的工作，而不是排队的工作。

## 页脚

一个状态键， `bgtasks`,通过 `ctx.ui.setStatus`，通道每个页脚扩展读取（Pi自己的，zentui，电力线，状态线，星舰风格）。一个键意味着选择一个位置。与pi-webtasks相同的配方：书呆子字体图标，256色，紧凑计数，盲文旋转器，同时运行任何东西。从会话开始时呈现为模糊的零，因此页脚在工作开始时保持其形状；会话结束时删除。仅在更改时设置。旋转器间隔仅在某些东西正在运行时存在。

其中有两个通道，shell任务和子代理。数字是有多少人在跑步；字形和颜色的变化，以显示车道的状态：

| 文本 | 意味着 |
| --- | --- |
| `0 0` (暗) | 闲置 |
| `2⠋ 1⠋` (蓝色、紫色) | 两个shell任务和一个子代理正在运行 |
| `0 1⠋` (红色、紫色) | shell任务失败了，没有人读过它，也没有人被它唤醒 |

一旦读取失败，红色清除 `bg_logs`、终止或作为唤醒传递给模型。文字记录中没有添加任何内容。Zentui的颜色模式 `Original` 保持这些颜色， `Zentui` 取代他们。任务中的名称和标签永远不会到达页脚。

`setStatus` 是唯一的通道，如pi-webtasks；没有任何内容作为zentui自定义变量发布，因此它不会显示两次。

## 集成协议

不变的 `pi-bg-tasks` V1，所以现有的读者（西蒙说桥）继续工作： `globalThis[Symbol.for("jang.pi.bg.tasks.v1")]` （`Map<id, task>`)， `globalThis[Symbol.for("jang.pi.bg.service.v1")]` （`{version, store, list, get}`), `pi.events` `bg-tasks:changed` / `bg-tasks:terminal`.

子代理添加 `globalThis[Symbol.for("jang.pi.bg.agents.v1")]` （`Map<id, run>`), `bg-agents:changed` / `bg-agents:terminal`,有效载荷 `{version: 1, run}`.

## 代码映射

-   `src/jobs.ts`：工作分类账。两个通道的一个生命周期：v1存储和事件、id、结算、杀死、读/未读、修剪、页脚计数。
-   `src/shell.ts`， `src/agents.ts`两条车道。每一个都提供了它的工作是如何开始、停止和显示的； `agents.ts` 还拥有声明和模型选择。
-   `src/scheduler.ts`： FIFO在并发限制下运行调度程序；子代理队列。
-   `src/notifier.ts`：唤醒交付。空闲：现在发送；忙：追加到下一回合边界；结算：送剩下的；读取退出。
-   `src/footer.ts`：页脚行及其旋转项。
-   `src/port.ts`：通知器和页脚使用的到Pi的接缝；真正的适配器。测试使用带有手动时钟的记录仪。
-   `src/host.ts`这是世界上唯一一份经久不衰的纪录 `/reload` （绑定会话、挂起唤醒、页脚状态），以及在其上构建的通知器和页脚。
-   `src/index.ts`钩子和工具定义。

## 开发

```sh
npm run check        # type checker and tests
npm run smoke:pack   # pack, install the tarball, and load it in Pi
```

释放是 `npm version patch` (或 `minor`， `major`), `git push --follow-tags`;CI通过带有出处的npm可信发布发布。

## 已知的限制

-   只在运行时由父模块注册的模型提供程序不会复制到子模块中；子进程自己加载扩展并获取它们所注册的内容。
-   子代理扩展工具来自子代理自己的扩展负载，因此必须为子代理安装允许列表中的扩展工具。

## 常见问题

### @jangmanj/pi-bgtasks 是什么？

后台shell任务和Pi的进程内子代理：bg\_run， bg\_logs, bg\_kill, subagent。

### 如何安装 @jangmanj/pi-bgtasks？

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

### @jangmanj/pi-bgtasks 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/jangmanj\_\_pi-bgtasks 是否存在。

### @jangmanj/pi-bgtasks 支持 ESM 还是 CommonJS？

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

### @jangmanj/pi-bgtasks 需要什么版本的 Node\.js？

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

### @jangmanj/pi-bgtasks 可以商用吗？

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

### @jangmanj/pi-bgtasks 还在维护吗？

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