@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;工具名称冲突。
安装
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/）. 项目文件通过名称获胜。编辑适用于下一个刷出。
---
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钩子和工具定义。
开发
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可信发布发布。
已知的限制
- 只在运行时由父模块注册的模型提供程序不会复制到子模块中；子进程自己加载扩展并获取它们所注册的内容。
- 子代理扩展工具来自子代理自己的扩展负载，因此必须为子代理安装允许列表中的扩展工具。