1.1.1 创建自定义 subagent 示例#

以创建一个只读安全审查员为例。

创建文件：

1
~/.pi/agent/agents/security-reviewer.md

内容如下：

1
---
2
name: security-reviewer
3
description: 只读安全审查员，检查认证、授权、输入校验及敏感信息泄漏
4
aliases: security-auditor
5
advertise: true
6
model: inherit
7
thinking: high
8
tools: read, grep, find, ls, contact_supervisor
9
systemPromptMode: replace
10
inheritProjectContext: true
11
inheritGlobalContext: false
12
inheritSkills: false
13
defaultContext: fresh
14
acceptanceRole: read-only
15
async: true
16
timeoutMs: 900000
17
---
18

19
你是一个只读安全审查员。
20

21
任务：
22
- 审查指定文件或主 agent 提供的 diff。
23
- 重点检查认证绕过、权限校验缺失、输入校验和敏感信息泄漏。
24
- 从实际代码中验证问题，不凭猜测报告漏洞。
25

26
边界：
27
- 不修改文件，不运行 shell 命令。
28
- 如果缺少必要材料，报告缺口。
29
- 如需主 agent 做决定，使用 contact_supervisor 请求确认。
30

31
输出：
32
1. 审查范围。
33
2. 已确认问题：严重程度、文件路径、行号、证据与修复建议。
34
3. 未验证事项与剩余风险。
35
4. 若无已确认问题，明确说明。

字段说明：

如果不需要这些控制项，最小定义也可以很简单：

1
---
2
name: security-reviewer
3
description: 只读安全审查员
4
tools: read, grep, find, ls
5
---
6

7
审查指定代码中的安全问题，只报告有证据的问题，不修改文件。

保存后执行：

1
/reload

然后告诉 Pi：

1
请使用 security-reviewer 审查 src/auth/ 下的认证和权限逻辑，只报告有证据的问题。

也可以让 Pi 帮你确认加载结果：

1
列出当前可用的 subagents，并显示 security-reviewer 的配置。

1.1.2 修改内置 subagent：方式 A，覆盖部分字段#

适合：改模型、推理强度、工具权限、上下文策略、描述等少量配置。

例如，将内置 reviewer 调整为高推理强度、默认使用新上下文，并修改简介。

编辑：

1
~/.pi/agent/settings.json

合并以下内容：

1
{
2
  "subagents": {
3
    "agentOverrides": {
4
      "reviewer": {
5
        "description": "独立只读审查员，重点检查正确性、回归风险和测试覆盖",
6
        "model": "inherit",
7
        "thinking": "high",
8
        "defaultContext": "fresh",
9
        "inheritProjectContext": true,
10
        "inheritGlobalContext": false,
11
        "inheritSkills": false
12
      }
13
    }
14
  }
15
}

这里：

• subagents：扩展的设置命名空间。
• agentOverrides：按 agent 正式名称配置覆盖项。
• reviewer：要修改的角色。
• 内层字段替换该角色对应的默认值；没写的字段继续保留原定义，包括原系统提示词和工具白名单。

如果仅希望某个项目采用这个配置，写到：

1
<项目根目录>/.pi/settings.json

已有 settings.json 时，请合并字段，不要用示例覆盖整个文件。 修改后执行 /reload。

还可以禁用某个角色：

1
{
2
  "subagents": {
3
    "agentOverrides": {
4
      "reviewer": {
5
        "disabled": true
6
      }
7
    }
8
  }
9
}

1.1.3 修改内置 subagent：方式 B，创建同名完整定义#

适合：大幅改变角色职责、重写系统提示词或重新设计工具集。

以 reviewer 为例，可以先把随包定义复制到用户目录：

1
mkdir -p ~/.pi/agent/agents
2

3
cp ~/.pi/agent/npm/node_modules/pi-subagents/agents/reviewer.md \
4
   ~/.pi/agent/agents/reviewer.md

然后编辑：

1
~/.pi/agent/agents/reviewer.md

保留：

1
name: reviewer

并按需求修改配置与正文。执行 /reload 后，你的同名定义会覆盖随包的 reviewer。

也可以直接请 Pi 使用扩展的管理操作：

1
请将内置 reviewer eject 到用户级目录，供我编辑；不要启动审查任务。

其对应工具操作是：

1
subagent({
2
  action: "eject",
3
  agent: "reviewer",
4
  agentScope: "user"
5
})

重要区别：同名文件是完整替换，不是字段合并。 自定义文件中省略的字段不会从原内置定义继承。

恢复默认时，可以删除同名自定义文件，并清除相应覆盖项；也可以请 Pi 执行 reset。如果项目级仍有同名定义或覆盖项，用户级恢复后也仍会受项目级影响。

1.2.1 /parallel-review：多角度并行审查#

让多个 reviewer 从不同角度独立检查当前改动，再由主 agent 汇总。

典型流程：

1
确定目标与审查角度
2
    ↓
3
并行 reviewer：正确性 / 测试 / 可维护性等
4
    ↓
5
主 agent 汇总：立即修复 / 可选改进 / 忽略或延期

• 默认使用 fresh 上下文，不依赖主会话的推理历史。
• 倾向使用 3 个有明确分工的 reviewer，但角度和数量不是固定死的。
• 默认只审查，不修改文件。
• 添加 autofix，会在汇总后修复“值得现在处理”的问题，并验证结果，不自动执行可选改进。

示例：

1
/parallel-review 审查当前 diff，重点关注权限校验和回归风险

1
/parallel-review autofix 审查 src/auth/ 的当前改动

1.2.2 /review-loop：实现、审查、修复循环#

典型流程：

1
worker 实现（如果尚未实现）
2
    ↓
3
并行 reviewer 审查
4
    ↓
5
主 agent 筛选问题
6
    ↓
7
worker 修复 → 必要时再次审查

• 默认最多 3 轮审查，可以指定其他上限。
• 如果目标是已有 diff，直接从审查开始。
• 不会为了可选润色一直循环。
• 遇到未批准的产品、范围或架构决定，会暂停询问。
• 默认同一工作区一次只有一个 writer。

示例：

1
/review-loop 为登录接口增加速率限制，最多审查 2 轮

1
/review-loop 审查并修复当前 diff，最多 3 轮，不做范围外重构

这里的“干净”并非必须消灭所有建议，而是没有尚需处理的阻塞问题或重要修复；可选项可以记录并延期。

1.2.3 /parallel-research：并行调研与代码侦察#

组合 researcher 和 scout，同时调查外部证据、本地实现和实践取舍。

典型流程：

1
researcher：官方资料与外部证据 ─┐
2
scout：本地代码、约束与接入点 ──┼→ 主 agent 综合结论
3
researcher/scout：实践取舍 ─────┘

默认角度是：

1. 外部证据。
2. 本地代码上下文。
3. 实践取舍与风险。

通常使用 2–3 个子 agent，默认只研究，不实现。

示例：

1
/parallel-research 结合当前项目，比较 PostgreSQL 和 SQLite 的适用性

条件： 使用 researcher 的部分要求子会话加载 pi-web-access 及所需网络工具。

1.2.4 /gather-context-and-clarify：先收集上下文，再澄清需求#

适合需求较模糊，但你希望 agent 先看代码，再问有针对性的问题。

典型流程：

1
scout 查看代码
2
    ＋
3
必要时 researcher 查外部资料
4
    ↓
5
汇总已知信息与缺口
6
    ↓
7
向用户提出关键澄清问题

示例：

1
/gather-context-and-clarify 我想给这个项目增加多租户支持，先看现有实现再问我问题

1.2.5 /parallel-cleanup：并行清理审查#

这是聚焦代码与文字质量的专项审查，不是完整的正确性审查。

默认启动两个只读 reviewer：

• 如果有 deslop 或 verbosity-cleaner skill，就使用它们。
• 没有这些 skill，也有模板内置指导，不是必需依赖。
• 默认只报告；添加 autofix 后应用筛选出的必要修复。
• 强调必须更短，同时更清晰且不改变行为。

示例：

1
/parallel-cleanup 检查当前 diff 中的冗余代码和注释

1
/parallel-cleanup autofix 仅清理本次改动，不做大规模重构

1.2.6 /council：有边界的顾问讨论#

适合重要架构选择、存在明显取舍的技术决策，或需要多个独立观点的问题。

典型流程：

1
主 agent 明确问题、范围和非目标
2
    ↓
3
2–3 名顾问给出意见
4
    ↓
5
主 agent 筛选并传递质疑，组织有限轮交叉检验
6
    ↓
7
主 agent 输出最终决策备忘录

• 默认最多 2 个讨论 pass，可指定 2 或 3。
• 通常选择 2–3 名顾问，最多 4 名。
• 优先使用已配置的 council-* 自定义角色；没有足够角色时，通常使用 oracle 和 reviewer 补齐。
• 顾问不直接互聊，也不默认共享完整彼此对话。
• 主 agent 始终负责综合与最终决策。
• council-* 是可自行添加的角色配置，不是随包默认提供的一组 agent。

示例：

1
/council 是否应该把当前单体拆成微服务？ --max-passes 2

1
/council 比较两个迁移方案 --advisors oracle,reviewer --max-passes 3

1.2.7 2 个命名工作流资源#

这两个不是上述斜杠模板，而是扩展提供的可按名字解析的工作流资源。

对应工具调用示例：

1
subagent({
2
  workflow: "review",
3
  args: {
4
    task: "审查当前 diff，报告有证据的正确性问题"
5
  }
6
})

1
subagent({
2
  workflow: "run-ci",
3
  cwd: "/path/to/project",
4
  args: {
5
    command: "npm run typecheck",
6
    timeoutMs: 120000
7
  }
8
})

run-ci 当前仅支持：

1
npm test
2
npm run typecheck

1.2.8 创建自定义工作流#

有两种主要方式：

• Markdown 提示模板：适合自然语言流程、简单串行步骤、斜杠命令。
• JavaScript 工作流脚本：适合明确控制串行、并行、条件分支和结果汇总。

文件位置：

区别：prompts/ 下的直接 .md 子文件会被发现并变成模板命令；工作流 .js 文件不会因为放进某个目录就自动变成斜杠命令，需要显式指定路径调用。

1
~/.pi/agent/prompts/implement-and-review.md

1
---
2
description: 侦察、实现并独立审查一个已批准的任务
3
argument-hint: "<任务>"
4
---
5

6
针对以下任务，使用 pi-subagents：
7

8
$@
9

10
流程：
11
1. 让 scout 检查相关代码，定位关键文件、约束和测试。
12
2. 主 agent 汇总侦察结果。如果任务需要尚未批准的产品或架构决定，
13
   先询问用户，不直接实现。
14
3. 让一个 worker 按已批准范围实现，并运行适当验证。
15
4. 实现完成后，让两个 fresh-context reviewer 并行审查：
16
   - 一个检查正确性和回归风险；
17
   - 一个检查测试覆盖和验证充分性。
18
5. 主 agent 汇总有证据的问题，不盲目接受所有建议。
19
6. 本轮仅报告审查结果，不自动追加修复。
20

21
限制：
22
- 同一工作区一次只允许一个 writer。
23
- reviewer 不修改文件。
24
- 最终报告修改文件、验证结果、审查发现及剩余风险。

1
/reload

1
/implement-and-review 给登录接口增加速率限制，不改变现有响应格式

1
---
2
description: 收集任务所需的代码上下文
3
subagent: scout
4
fresh: true
5
---
6

7
任务：$@
8

9
只收集上下文，不实现。
10
返回关键文件、接口、约束、测试位置和待确认事项。

1
---
2
description: 根据上下文执行已批准任务
3
subagent: worker
4
fresh: true
5
---
6

7
已批准任务：$@
8

9
上一步的代码上下文：
10
{previous}
11

12
执行最小必要修改并验证。
13
如遇到未批准的范围或架构选择，请向主 agent 请求决定。
14
返回修改文件、验证命令与结果、剩余风险。

1
---
2
description: 独立审查实现结果
3
subagent: reviewer
4
fresh: true
5
---
6

7
原任务：$@
8

9
实现者的交接说明：
10
{previous}
11

12
直接检查当前文件和工作区 diff，不把交接说明当作正确性证明。
13
只报告有证据的问题，并注明文件、行号和最小修复建议。
14
不要修改文件。

1
---
2
description: 侦察、实现、审查
3
chain: map-task -> build-task -> check-task
4
---
5

6
通过串行步骤执行任务。

1
/prompt-workflow deliver-task "为已确定的登录方案补充速率限制" --bg

1
<项目>/.pi/workflows/review-change.js

1
const target = args.target;
2

3
if (typeof target !== "string" || !target.trim()) {
4
  throw new Error("必须提供非空的 args.target");
5
}
6

7
// 先串行侦察。
8
const scan = await runs.run("scan", {
9
  label: "梳理审查目标",
10
  agent: "scout",
11
  context: "fresh",
12
  task: `检查 ${target} 的当前改动，定位相关文件、约束和风险。不要实现。`
13
});
14

15
if (!scan.ok) {
16
  throw new Error(`侦察未成功完成：${scan.runId}`);
17
}
18

19
// 再并行审查，runs.all 返回按输入顺序排列的数组。
20
const reviews = await runs.all([
21
  {
22
    key: "correctness",
23
    label: "审查正确性",
24
    agent: "reviewer",
25
    context: "fresh",
26
    task: [
27
      `审查目标：${target}`,
28
      "只读检查正确性和回归风险。直接检查文件与当前 diff。",
29
      "以下上下文仅用于定位，不作为正确性证明：",
30
      scan.output
31
    ].join("\n")
32
  },
33
  {
34
    key: "tests",
35
    label: "审查测试覆盖",
36
    agent: "reviewer",
37
    context: "fresh",
38
    task: [
39
      `审查目标：${target}`,
40
      "只读检查测试覆盖、断言质量和验证缺口。",
41
      "以下上下文仅用于定位：",
42
      scan.output
43
    ].join("\n")
44
  }
45
]);
46

47
return {
48
  ok: reviews.every(result => result.ok),
49
  reviews: reviews.map((result, index) => ({
50
    angle: index === 0 ? "correctness" : "tests",
51
    ok: result.ok,
52
    runId: result.runId,
53
    output: result.output
54
  }))
55
};

1
subagent({
2
  workflow: "./.pi/workflows/review-change.js",
3
  cwd: "/你的项目绝对路径",
4
  args: {
5
    target: "src/auth/ 的当前工作区改动"
6
  },
7
  async: true
8
})

1
请运行 .pi/workflows/review-change.js，
2
target 是 src/auth/ 的当前工作区改动，后台执行。

1
subagent({
2
  action: "validate",
3
  workflow: "./.pi/workflows/review-change.js",
4
  cwd: "/你的项目绝对路径"
5
})