@ferris1225/pi-subagents 0.6.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +177 -174
- package/package.json +1 -2
- package/src/index.ts +12 -10
- package/src/prompt.ts +5 -5
- package/README-zh.md +0 -158
package/README.md
CHANGED
|
@@ -1,174 +1,177 @@
|
|
|
1
|
-
# pi-subagents
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/@ferris1225/pi-subagents)
|
|
4
|
-
[](https://www.npmjs.com/package/@ferris1225/pi-subagents)
|
|
5
|
-
[](./LICENSE)
|
|
6
|
-
|
|
7
|
-
](https://www.npmjs.com/package/@ferris1225/pi-subagents)
|
|
4
|
+
[](https://www.npmjs.com/package/@ferris1225/pi-subagents)
|
|
5
|
+
[](./LICENSE)
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
Focused background delegation for [pi](https://pi.dev). `pi-subagents` adds a small set of
|
|
10
|
+
specialized agents that run in isolated child processes, report results back to the main
|
|
11
|
+
agent, and keep the workflow moving without manual polling.
|
|
12
|
+
|
|
13
|
+
## Highlights
|
|
14
|
+
|
|
15
|
+
- **Automatic delegation guidance** — injects the enabled agent catalog and routing rules into
|
|
16
|
+
the main agent's system prompt.
|
|
17
|
+
- **Isolated execution** — every sub-agent runs in its own `pi` process with `--no-session`.
|
|
18
|
+
- **Automatic continuation** — a completed result is sent to the main session as a custom
|
|
19
|
+
message and automatically starts a follow-up turn. If the main agent is busy, the result
|
|
20
|
+
waits in the follow-up queue.
|
|
21
|
+
- **Parallel fan-out** — run independent tasks together, with a bounded background queue.
|
|
22
|
+
- **Live progress** — a TUI widget shows each agent's status, activity, model, usage, and
|
|
23
|
+
elapsed time; completion also produces a concise notification.
|
|
24
|
+
- **Per-agent configuration** — enable agents, select models, set thinking strength, and
|
|
25
|
+
choose discovery scope from `/subagents-setup`.
|
|
26
|
+
- **Leaf processes** — child agents cannot access the `subagent` tool, so delegation cannot
|
|
27
|
+
recurse.
|
|
28
|
+
|
|
29
|
+
## Install
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
pi install npm:@ferris1225/pi-subagents
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Requires pi **>= 0.80.6**.
|
|
36
|
+
|
|
37
|
+
After installation, open the setup wizard in an interactive TUI session:
|
|
38
|
+
|
|
39
|
+
```text
|
|
40
|
+
/subagents-setup
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
The default configuration enables `explore`, `worker`, and `reviewer`. `plan` is available
|
|
44
|
+
but opt-in.
|
|
45
|
+
|
|
46
|
+
## Included agents
|
|
47
|
+
|
|
48
|
+
| Agent | Default | Access | Purpose |
|
|
49
|
+
| --- | :---: | --- | --- |
|
|
50
|
+
| `explore` | Yes | Read-only | Fast codebase reconnaissance and structured findings. |
|
|
51
|
+
| `worker` | Yes | Full | Implements, fixes, refactors, and tests a self-contained task. |
|
|
52
|
+
| `reviewer` | Yes | Read-only | Independent adversarial review of a diff before completion. |
|
|
53
|
+
| `plan` | No | Read-only | Produces a separate implementation plan when one is useful. |
|
|
54
|
+
|
|
55
|
+
Agents are Markdown files in `agents/`. Each file contains YAML frontmatter and a system
|
|
56
|
+
prompt. User and project scopes can override a built-in agent with the same name.
|
|
57
|
+
|
|
58
|
+
## Workflow
|
|
59
|
+
|
|
60
|
+
A typical flow is:
|
|
61
|
+
|
|
62
|
+
```text
|
|
63
|
+
main agent
|
|
64
|
+
│
|
|
65
|
+
├─ subagent(explore / worker / reviewer)
|
|
66
|
+
│ └─ isolated pi child process
|
|
67
|
+
│ └─ result message
|
|
68
|
+
│
|
|
69
|
+
└─ automatic follow-up turn with the result
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
1. The main agent calls `subagent` with a self-contained brief.
|
|
73
|
+
2. The tool returns immediately and ends that foreground tool turn, leaving the editor ready
|
|
74
|
+
for input.
|
|
75
|
+
3. The child process works independently. Up to four queued runs execute at once; a single
|
|
76
|
+
parallel request may contain up to eight tasks.
|
|
77
|
+
4. On completion or failure, the extension sends a durable result message to the main
|
|
78
|
+
session. That message automatically wakes the main agent, or waits until its current turn
|
|
79
|
+
finishes.
|
|
80
|
+
5. The main agent uses the result to verify the work and continue dependent steps. No later
|
|
81
|
+
user prompt is required to collect a result.
|
|
82
|
+
|
|
83
|
+
Switching sessions, reloading, or shutting down cancels remaining background runs.
|
|
84
|
+
|
|
85
|
+
## Usage
|
|
86
|
+
|
|
87
|
+
The main agent is encouraged to delegate automatically, but you can also ask directly:
|
|
88
|
+
|
|
89
|
+
```text
|
|
90
|
+
Use explore to map how authentication is wired up.
|
|
91
|
+
Ask worker to implement the API change after the exploration is complete.
|
|
92
|
+
Run reviewer on the final diff before reporting completion.
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Single task
|
|
96
|
+
|
|
97
|
+
```json
|
|
98
|
+
{
|
|
99
|
+
"agent": "worker",
|
|
100
|
+
"task": "Implement the requested change. Inspect the existing conventions, update tests, and report the files changed and checks run."
|
|
101
|
+
}
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Optional `cwd` selects the working directory for that child.
|
|
105
|
+
|
|
106
|
+
### Parallel tasks
|
|
107
|
+
|
|
108
|
+
Use parallel mode only for independent work:
|
|
109
|
+
|
|
110
|
+
```json
|
|
111
|
+
{
|
|
112
|
+
"tasks": [
|
|
113
|
+
{ "agent": "explore", "task": "Map the API layer and its tests." },
|
|
114
|
+
{ "agent": "explore", "task": "Map the database layer and its tests." }
|
|
115
|
+
]
|
|
116
|
+
}
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Start dependent work after the relevant result has been delivered to the main agent.
|
|
120
|
+
|
|
121
|
+
## Configuration
|
|
122
|
+
|
|
123
|
+
Configuration is stored at `~/.pi/agent/pi-subagents.json`. The location follows
|
|
124
|
+
`PI_CODING_AGENT_DIR` when set.
|
|
125
|
+
|
|
126
|
+
```json
|
|
127
|
+
{
|
|
128
|
+
"enabledAgents": ["explore", "worker", "reviewer"],
|
|
129
|
+
"agentModels": {
|
|
130
|
+
"explore": "anthropic/claude-haiku-4-5"
|
|
131
|
+
},
|
|
132
|
+
"thinkingLevel": "max",
|
|
133
|
+
"proactiveInjection": true,
|
|
134
|
+
"agentScope": "user"
|
|
135
|
+
}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
| Field | Description |
|
|
139
|
+
| --- | --- |
|
|
140
|
+
| `enabledAgents` | Agent names exposed to discovery and prompt injection. An empty array disables all agents. |
|
|
141
|
+
| `agentModels` | Optional `provider/model-id` override per agent. |
|
|
142
|
+
| `thinkingLevel` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. |
|
|
143
|
+
| `proactiveInjection` | Whether to add the delegation directive to the main system prompt. |
|
|
144
|
+
| `agentScope` | `user`, `project`, or `both`; controls which user/project agent directories are discovered. |
|
|
145
|
+
|
|
146
|
+
Model selection uses this precedence:
|
|
147
|
+
|
|
148
|
+
```text
|
|
149
|
+
configured agent model → current main-session model → agent frontmatter model
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Unavailable configured models are replaced with a usable current-session model when possible
|
|
153
|
+
and the repaired configuration is saved.
|
|
154
|
+
|
|
155
|
+
## Agent discovery and overrides
|
|
156
|
+
|
|
157
|
+
- Built-in agents are shipped with the package.
|
|
158
|
+
- User agents live in `~/.pi/agent/agents/`.
|
|
159
|
+
- Project agents live in the nearest `.pi/agents/` directory.
|
|
160
|
+
- For duplicate names, project overrides user and user overrides built-in.
|
|
161
|
+
|
|
162
|
+
Use a matching Markdown filename and `name` field to replace a built-in agent. Keep the task
|
|
163
|
+
brief explicit: include the goal, relevant paths, constraints, and expected handoff.
|
|
164
|
+
|
|
165
|
+
## Development
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
npm install
|
|
169
|
+
npm run check
|
|
170
|
+
npm test
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
The package has no runtime dependencies beyond pi peer dependencies.
|
|
174
|
+
|
|
175
|
+
## License
|
|
176
|
+
|
|
177
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ferris1225/pi-subagents",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0",
|
|
4
4
|
"description": "Focused sub-agent delegation for pi: explore / plan / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -18,7 +18,6 @@
|
|
|
18
18
|
"src",
|
|
19
19
|
"agents",
|
|
20
20
|
"README.md",
|
|
21
|
-
"README-zh.md",
|
|
22
21
|
"LICENSE"
|
|
23
22
|
],
|
|
24
23
|
"pi": {
|
package/src/index.ts
CHANGED
|
@@ -146,18 +146,18 @@ export default function (pi: ExtensionAPI): void {
|
|
|
146
146
|
"Delegate a discrete, self-contained task to a specialized sub-agent running in an ISOLATED context window.",
|
|
147
147
|
"Agents: explore (read-only codebase recon), plan (implementation plan, opt-in), worker (implement/fix/refactor/test, full tools), reviewer (adversarial pre-commit review, read-only).",
|
|
148
148
|
"Modes: single ({agent, task}) or parallel ({tasks: [{agent, task}, ...]}).",
|
|
149
|
-
"It starts agents in the background and immediately returns control to the main window;
|
|
149
|
+
"It starts agents in the background and immediately returns control to the main window; completion messages automatically wake the main agent to continue.",
|
|
150
150
|
"Each agent has no memory of this conversation — brief it fully (goal, exact paths, constraints, expected output)."
|
|
151
151
|
].join(" "),
|
|
152
152
|
promptSnippet:
|
|
153
|
-
"Start background subagents: explore (read-only search), worker (implement), reviewer (adversarial review);
|
|
153
|
+
"Start background subagents: explore (read-only search), worker (implement), reviewer (adversarial review); completion automatically resumes the main agent.",
|
|
154
154
|
promptGuidelines: [
|
|
155
155
|
"Use subagent to delegate discrete, self-contained tasks so the main context stays clean; do orchestration and verification yourself.",
|
|
156
156
|
"Use subagent with agent 'explore' for broad or open-ended code search before large changes.",
|
|
157
157
|
"Use subagent with agent 'worker' to implement a well-scoped task; it plans internally.",
|
|
158
158
|
"Use subagent with agent 'reviewer' for a fresh read-only review before reporting work done or committing.",
|
|
159
|
-
"subagent launches work in the background and ends the current turn;
|
|
160
|
-
"Run independent tasks in parallel by passing a tasks array to subagent; start dependent work
|
|
159
|
+
"subagent launches work in the background and ends the current turn; when a result arrives, the main agent is automatically resumed with it.",
|
|
160
|
+
"Run independent tasks in parallel by passing a tasks array to subagent; let the automatically resumed main agent start dependent work after results arrive.",
|
|
161
161
|
],
|
|
162
162
|
parameters: SubagentParams,
|
|
163
163
|
|
|
@@ -183,8 +183,8 @@ export default function (pi: ExtensionAPI): void {
|
|
|
183
183
|
}
|
|
184
184
|
}
|
|
185
185
|
|
|
186
|
-
// Finished runs leave the widget immediately. Their final findings
|
|
187
|
-
// as a custom message
|
|
186
|
+
// Finished runs leave the widget immediately. Their final findings are sent
|
|
187
|
+
// back as a custom message that automatically starts a follow-up turn.
|
|
188
188
|
const finishRun = (runId: number, status: "done" | "failed"): void => {
|
|
189
189
|
monitor.setStatus(runId, status); // stamps endedAt for the elapsed time
|
|
190
190
|
const run = monitor.removeRun(runId);
|
|
@@ -297,7 +297,9 @@ export default function (pi: ExtensionAPI): void {
|
|
|
297
297
|
content: `### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}\n\n${getResultOutput(result)}`,
|
|
298
298
|
display: true,
|
|
299
299
|
},
|
|
300
|
-
|
|
300
|
+
// The result is both durable context and a wake-up signal. If the
|
|
301
|
+
// main agent is busy, followUp queues it until the current turn ends.
|
|
302
|
+
{ deliverAs: "followUp", triggerTurn: true },
|
|
301
303
|
);
|
|
302
304
|
},
|
|
303
305
|
() => finishRun(runId, "failed"),
|
|
@@ -307,7 +309,7 @@ export default function (pi: ExtensionAPI): void {
|
|
|
307
309
|
};
|
|
308
310
|
|
|
309
311
|
// Sub-agents intentionally detach from the foreground turn. This makes the
|
|
310
|
-
// editor available immediately;
|
|
312
|
+
// editor available immediately; completion messages later wake the main agent.
|
|
311
313
|
if (params.tasks && params.tasks.length > 0) {
|
|
312
314
|
if (params.tasks.length > MAX_PARALLEL_TASKS) {
|
|
313
315
|
return {
|
|
@@ -327,7 +329,7 @@ export default function (pi: ExtensionAPI): void {
|
|
|
327
329
|
type: "text",
|
|
328
330
|
text:
|
|
329
331
|
started > 0
|
|
330
|
-
? `Started ${started} background subagent${started === 1 ? "" : "s"}.
|
|
332
|
+
? `Started ${started} background subagent${started === 1 ? "" : "s"}. Results will automatically resume the main agent when ready.`
|
|
331
333
|
: failures.map((result) => getResultOutput(result)).join("\n"),
|
|
332
334
|
},
|
|
333
335
|
],
|
|
@@ -346,7 +348,7 @@ export default function (pi: ExtensionAPI): void {
|
|
|
346
348
|
};
|
|
347
349
|
}
|
|
348
350
|
return {
|
|
349
|
-
content: [{ type: "text", text: `Started ${result.agent} in the background. Its
|
|
351
|
+
content: [{ type: "text", text: `Started ${result.agent} in the background. Its result will automatically resume the main agent when ready.` }],
|
|
350
352
|
details: makeDetails("single", true)([result]),
|
|
351
353
|
terminate: true,
|
|
352
354
|
};
|
package/src/prompt.ts
CHANGED
|
@@ -38,18 +38,18 @@ export function buildDelegationDirective(agents: AgentConfig[]): string {
|
|
|
38
38
|
## Sub-agent delegation (pi-subagents)
|
|
39
39
|
|
|
40
40
|
You have a \`subagent\` tool that starts specialized agents in ISOLATED background processes.
|
|
41
|
-
It immediately ends the current main-agent turn so the user can keep working.
|
|
42
|
-
|
|
43
|
-
|
|
41
|
+
It immediately ends the current main-agent turn so the user can keep working. When a child
|
|
42
|
+
finishes, its result is sent back as a message that automatically resumes the main agent;
|
|
43
|
+
if the main agent is busy, the result waits as a follow-up.
|
|
44
44
|
|
|
45
45
|
Available agents:
|
|
46
46
|
${catalog}
|
|
47
47
|
|
|
48
48
|
${routing ? `Routing:\n${routing}\n` : ""}Dispatch discipline:
|
|
49
|
-
- Default to delegating every discrete task to a sub-agent; use
|
|
49
|
+
- Default to delegating every discrete task to a sub-agent; use the automatically delivered findings for orchestration and verification.
|
|
50
50
|
- Only handle inline: pure Q&A, a single trivial edit/lookup, or when the user explicitly says to do it directly. When in doubt, delegate.
|
|
51
51
|
- For an already-known or trivial target, use a direct search/read tool (e.g. grep/find/read) — do not over-delegate a one-line lookup.
|
|
52
|
-
${hasMultiple ? "- Run INDEPENDENT tasks in parallel: one subagent call with a `tasks` array, and track them with your todo list.
|
|
52
|
+
${hasMultiple ? "- Run INDEPENDENT tasks in parallel: one subagent call with a `tasks` array, and track them with your todo list. Let the automatically resumed main agent launch dependent work only after its prerequisite result arrives (e.g. explore, then worker, then reviewer).\n" : ""}- Brief each sub-agent as self-contained: goal, exact paths, constraints, expected output. It has NO memory of this conversation.
|
|
53
53
|
- Treat delegated agents as leaf workers: do not ask a sub-agent to dispatch another sub-agent; child processes do not have this tool.
|
|
54
54
|
- Trust but verify: a sub-agent's summary describes intent, not outcome. Check the actual changes/results before reporting work done.
|
|
55
55
|
|
package/README-zh.md
DELETED
|
@@ -1,158 +0,0 @@
|
|
|
1
|
-
# pi-subagents
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/@ferris1225/pi-subagents)
|
|
4
|
-
[](https://www.npmjs.com/package/@ferris1225/pi-subagents)
|
|
5
|
-
[](./LICENSE)
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
[English](./README.md) | 中文
|
|
10
|
-
|
|
11
|
-
一个聚焦的 [pi](https://pi.dev) 扩展，给主模型提供**它真的会去用**的 sub-agent：
|
|
12
|
-
`explore`、`worker`、`reviewer`（外加可选的 `plan`），每个都跑在独立的 `pi` 进程里。
|
|
13
|
-
真正的差异点不是 agent 本身，而是**主动派发注入**——让模型自己主动去委派任务，
|
|
14
|
-
于是你可以把全局 `AGENTS.md` 里那两段派发/审查规则删掉。
|
|
15
|
-
|
|
16
|
-
## 为什么选 pi-subagents？
|
|
17
|
-
|
|
18
|
-
pi 故意不内置 sub-agent。社区的补位方案分两种，但都没踩中：
|
|
19
|
-
|
|
20
|
-
- **太重** —— 9 个 agent、链式流水线、worktree 集群、到处都是 slash 命令。强大，但机器太多。
|
|
21
|
-
- **太安静** —— 只给一个 `subagent` 工具，模型**很少主动调用**，因为 pi 只把工具本身展示给主模型，
|
|
22
|
-
从不展示每个 agent 的描述。于是除非你在全局提示词里强制，否则这些 agent 一直吃灰。
|
|
23
|
-
|
|
24
|
-
`pi-subagents` 走中间路线：
|
|
25
|
-
|
|
26
|
-
| 优势 | 对你意味着什么 |
|
|
27
|
-
|------|----------------|
|
|
28
|
-
| **真的会被用** | `before_agent_start` hook 每轮把 agent 清单 + 派发/审查指令注入系统提示词，再由 tool `promptGuidelines` 和 `Use PROACTIVELY when …` 描述加强。这正是重型框架依赖的那根杠杆——我们只是把它变成默认行为。 |
|
|
29
|
-
| **体量合适** | 3 个聚焦的 agent（+1 可选），不是 9 个。没有链式/worktree/集群机器。只有 single 和 parallel 两种模式。 |
|
|
30
|
-
| **替代你的 AGENTS.md 规则** | 注入的指令是 "Sub-agent Dispatch" 和 "Review, Verification & Commit" 两段的自包含替代。装上它，然后把那两段删掉。 |
|
|
31
|
-
| **真隔离** | 每个 agent 都是独立 `pi` 进程（`--no-session`），委派出去的活绝不污染主上下文。 |
|
|
32
|
-
| **该只读就只读** | `explore`、`plan`、`reviewer` 都是只读。`reviewer` 跑在**独立**上下文，避免自我确认偏差。 |
|
|
33
|
-
| **纯选择式配置** | 不用手敲值：勾选式模块选择器 + 模糊过滤、可翻页的模型选择器。 |
|
|
34
|
-
| **合理的模型默认** | 每 agent 可单独覆盖模型；不选就**用主窗口当前 session 的模型**。配置中的不可用模型会自动修复并写回。 |
|
|
35
|
-
| **子代理是叶节点** | 子进程不会获得 `subagent` 工具，因此不会递归派发或无限运行。 |
|
|
36
|
-
| **零运行时依赖** | 纯 pi 扩展，仅 peer 依赖，无需构建步骤。 |
|
|
37
|
-
|
|
38
|
-
## 安装
|
|
39
|
-
|
|
40
|
-
```bash
|
|
41
|
-
pi install npm:@ferris1225/pi-subagents
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
要求 pi **≥ 0.80.6**——子代理思考强度使用该版本引入的 `--thinking` 参数值。
|
|
45
|
-
|
|
46
|
-
然后运行配置向导（纯选择）：
|
|
47
|
-
|
|
48
|
-
```text
|
|
49
|
-
/subagents-setup
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
## Agent 一览
|
|
53
|
-
|
|
54
|
-
| Agent | 默认启用 | 工具 | 职责 |
|
|
55
|
-
|-------|:--------:|------|------|
|
|
56
|
-
| `explore` | ✅ | 只读 | 快速代码侦察；返回压缩后的发现以便交接。 |
|
|
57
|
-
| `worker` | ✅ | 全部 | 实现/修复/重构/测试一个自包含任务。**内部先规划后动手。** |
|
|
58
|
-
| `reviewer` | ✅ | 只读 | 在独立上下文做对抗式提交前审查。 |
|
|
59
|
-
| `plan` | 可选 | 只读 | 产出可人工审阅的独立实现计划。worker 本就会内部规划，所以只在你需要把计划作为独立产物时才用它。 |
|
|
60
|
-
|
|
61
|
-
每个 agent 都是一个 Markdown 文件（`agents/*.md`：YAML frontmatter + 正文作为 system prompt）。
|
|
62
|
-
想覆盖任意一个，只需把同名 `name` 的文件放进 `~/.pi/agent/agents/`（用户级）或 `.pi/agents/`（项目级）。
|
|
63
|
-
|
|
64
|
-
## 主动派发是怎么工作的
|
|
65
|
-
|
|
66
|
-
pi 从不把每个 agent 的描述展示给主模型——它只看到 `subagent` 这个工具。三根杠杆解决这一点：
|
|
67
|
-
|
|
68
|
-
1. **`before_agent_start` 注入** —— 每一轮，把启用的 agent 加上一段派发/审查指令追加进父模型系统提示词。
|
|
69
|
-
2. **tool `promptSnippet` / `promptGuidelines`** —— 在工具激活时持续强化「何时该委派」。
|
|
70
|
-
3. **`Use PROACTIVELY when …` 描述** —— 在 Claude Code agent 生态被验证过的触发措辞。
|
|
71
|
-
|
|
72
|
-
这段指令会引导出一条干净的流程：**`explore` → `worker` → `reviewer`**，独立任务并行扇出，
|
|
73
|
-
以及「信任但需验证」的交接。由于子代理在后台运行，依赖前序结果的步骤必须等结果送达后再启动。
|
|
74
|
-
|
|
75
|
-
## 配置
|
|
76
|
-
|
|
77
|
-
存放在 `~/.pi/agent/pi-subagents.json`（尊重 `PI_CODING_AGENT_DIR`）：
|
|
78
|
-
|
|
79
|
-
```json
|
|
80
|
-
{
|
|
81
|
-
"enabledAgents": ["explore", "worker", "reviewer"],
|
|
82
|
-
"agentModels": { "explore": "anthropic/claude-haiku-4-5" },
|
|
83
|
-
"thinkingLevel": "max",
|
|
84
|
-
"proactiveInjection": true,
|
|
85
|
-
"agentScope": "user"
|
|
86
|
-
}
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
- `enabledAgents` —— 哪些 agent 可被发现并注入。
|
|
90
|
-
- `agentModels` —— 每 agent 的模型覆盖（`"provider/model-id"`）。如果已保存的模型不可用，会切换到主窗口当前模型并写回此文件。
|
|
91
|
-
- `thinkingLevel` —— 子代理思考强度：`off`、`minimal`、`low`、`medium`、`high`、`xhigh` 或 `max`（默认）。
|
|
92
|
-
- `proactiveInjection` —— 开关系统提示词注入。
|
|
93
|
-
- `agentScope` —— `"user"`（默认）、`"project"` 或 `"both"`。
|
|
94
|
-
|
|
95
|
-
**每个 agent 的模型优先级**：
|
|
96
|
-
|
|
97
|
-
```
|
|
98
|
-
可用的 agentModels[name] → 当前 session 模型 → agent frontmatter 里的默认
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
如果配置的模型不再可用，会切换到主窗口当前模型，并在下一次运行前写回配置文件。
|
|
102
|
-
|
|
103
|
-
## 使用
|
|
104
|
-
|
|
105
|
-
主模型会自己调用 `subagent`，你也可以直接要求：
|
|
106
|
-
|
|
107
|
-
```text
|
|
108
|
-
# 单个
|
|
109
|
-
用 explore sub-agent 梳理一下认证是怎么接起来的。
|
|
110
|
-
|
|
111
|
-
# 并行（独立任务）
|
|
112
|
-
用并行 sub-agent 跑这两件：探索 API 层，以及探索 DB 层。
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
工具参数形态：
|
|
116
|
-
|
|
117
|
-
```jsonc
|
|
118
|
-
// 单个
|
|
119
|
-
{ "agent": "worker", "task": "<自包含的任务简报>" }
|
|
120
|
-
// 并行
|
|
121
|
-
{ "tasks": [ { "agent": "explore", "task": "..." }, { "agent": "explore", "task": "..." } ] }
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
所有子代理默认在后台启动。工具会立即结束当前主代理回合，编辑器可直接继续输入，
|
|
125
|
-
无需按 Escape；完成输出会显示出来，并在后续用户请求前加入上下文。启动完成后，
|
|
126
|
-
Escape 只中止前台工作；切换会话、`/reload` 或退出才会清理仍在运行的后台进程。
|
|
127
|
-
|
|
128
|
-
## 实时状态与通知
|
|
129
|
-
|
|
130
|
-
子代理运行期间，编辑器上方的挂件为每个运行显示一行状态（图标、agent、模型、
|
|
131
|
-
token 用量、耗时），其下缩进一行显示它正在做什么：`thinking`、`responding`、
|
|
132
|
-
`read src/index.ts`、`bash npm test`……（不会是一坨 JSON 参数）。
|
|
133
|
-
`responding` 表示模型正在流式输出普通文本，**不**表示向文件系统写入。
|
|
134
|
-
|
|
135
|
-
运行结束（成功**或**失败）时，该行立即从挂件消失，主窗口收到一条通知，
|
|
136
|
-
给出最终摘要（`✓ worker · openai/gpt-5 · ↑12.4k ↓3.1k · 47s`）。完成结果消息
|
|
137
|
-
才是对话中持久保留、并会供后续请求使用的记录。
|
|
138
|
-
|
|
139
|
-
子代理使用配置的思考强度（默认 `--thinking max`）；pi 会按目标模型实际支持
|
|
140
|
-
的级别自适应降级（`max → xhigh → high → … → off`），弱模型也能平稳运行。
|
|
141
|
-
任务内容通过 stdin 传递，只有 agent system prompt 使用短生命周期临时文件。
|
|
142
|
-
子进程输出在内存中流式处理；默认不设运行时限，只有显式中止时才清理整个进程树。
|
|
143
|
-
|
|
144
|
-
## 开发
|
|
145
|
-
|
|
146
|
-
```bash
|
|
147
|
-
npm install
|
|
148
|
-
npm run check # tsc --noEmit
|
|
149
|
-
npm test # vitest
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
## 相关项目
|
|
153
|
-
|
|
154
|
-
- [pi-querit-search](https://www.npmjs.com/package/pi-querit-search) —— 为 pi 提供实时网络搜索与网页抓取，同一作者。
|
|
155
|
-
|
|
156
|
-
## 许可证
|
|
157
|
-
|
|
158
|
-
MIT
|