看门狗与子智能体权限

本页为 pi-subagents 官方文档的非官方中文翻译，请以官方英文文档为准。原文 · 许可证

看门狗（watchdog）是一个可选启用的第二个模型，用于审查智能体刚刚做了什么，并把发现的问题推回对话记录。它会查找遗漏的约束条件、正确性风险、测试缺口、不安全的变更、循环风险与范围漂移；当本轮结果干净时它保持沉默。它并不是 reviewer 子智能体；subagents.defaultModel 和 agentOverrides.reviewer 都不用于配置它。

何时运行

时机	触发	门槛	投递
边界审查	每次主轮或子轮的 `agent_end`	代码库发生变更	引导进入对话记录；智能体获得一次续接机会，之后该轮会被再次审查
主活动审查	`agent_end`，且 `clarification: true`	出现新的已交付编排证据；每次用户提示至多一次额外审查	同样的警告/澄清路径，即便没有本地编辑
节奏审查	每 `cadence.everyNTools` 个工具结果一次，最低 5	可选启用	在当前工具之后、下一步之前引导
LSP 预扫	边界审查之前	TypeScript/JavaScript 文件发生变化	诊断信息直接成为看门狗发现项，不发起模型调用

边界审查会把一轮的多次编辑聚合为对最终状态的单一审查。未变更或被回滚的差异会被跳过，除非下方"仅主会话活动"的可选启用接纳了新的证据；.pi/subagents/ 与 tmp/ 中的产物始终被排除。在编排式运行中，每个写入型子智能体各自审查它的工作树，父会话则在所有子变更落地后审查聚合差异。不存在空闲定时器审查。节奏监控的设计灵感来自 Scopey。

子智能体同样具备边界、节奏与 LSP 行为。子智能体的节奏解析顺序为 children.overrides.<agent>.cadence → children.cadence → 顶层 cadence：

json

{
  "subagents": {
    "watchdog": {
      "enabled": true,
      "cadence": { "everyNTools": 10 },
      "children": {
        "enabled": true,
        "cadence": { "everyNTools": 20 },
        "overrides": {
          "worker": { "cadence": { "everyNTools": 5 } },
          "reviewer": { "enabled": false }
        }
      }
    }
  }
}

也就是说：主会话每 10 个工具一次，worker 每 5 个一次，其他子智能体每 20 个一次，reviewer 从不审查。

你将看到什么

每一条发现都是一条普通的对话记录消息：可展开、可滚动，并持久化到会话的 JSONL 中。干净的审查不会显示任何内容。

text

you ─▶ agent turn ─▶ edits repo ─▶ agent_end ─▶ watchdog review
                                             ├─ clean: turn ends
                                             └─ warning: steered in; agent continues once

折叠的警告显示标题与证据行。展开后的警告显示证据、推荐动作、类别与来源：

text

● Subagent watchdog Blocker (displayed): Claims tests passed without running them
  Evidence: The transcript claims `npm test` passed but no test command appears in the tool log.
  Recommended action: Run the focused test before finishing.
  Category: Test Gap · Source: main

当连续的边界审查反复出现同一条警告时，说明智能体没有取得进展。在连续 stalemateRepeats（默认 3）次相同警告后，该警告会被标记为 stalemate，不再触发续接，本轮就此结束。下一次用户提示会重置计数。

子智能体看门狗的发现项会以三种方式上浮到父会话：

结果信封中带有 watchdog.warnings，包含严重程度、类别、摘要、证据、推荐动作、addressed 与 stalemate，上限为最近 20 条。
验收运行时校验 watchdog-blocker 在存在未处理或僵局的阻塞项时失败。
完成通知中包含 Watchdog blockers: 行，舰队/状态视图会显示 wd:<n> 与 resolve watchdog blockers。

/subagents-watchdog status 会显示设置来源、启用状态、运行时状态、审查触发器、作用域、节奏、LSP 状态、所选模型/思考级别、子智能体覆盖、超时、僵局计数、启动规则数量、审查后端、上一次警告、变更路径，以及配置错误（如有）。

评审者拿到什么

本轮差异（Turn delta），含已变更的代码库路径。输入过长时保留前 6,000 字符与尾部。
当前作用域（scope.enabled，默认开启）：有边界的真实用户提示。旁支问题是叠加性的；只有显式变更才能取代更早的需求。
watchdog_diff（在 Git 内时）：自会话起始提交起的差异，包含之后的提交，再加上可用 read 检查的未跟踪路径；接受 path 与 stat:true。
WATCHDOG.md 常驻指令，每次审查时重新读取：先读 <project>/.pi/WATCHDOG.md，再读 ~/.pi/agent/WATCHDOG.md，上限 8,000 字符。设置 guidance.watchdogMd: false 即可忽略。
LSP 诊断来自 typescript-language-server，自动从 node_modules/.bin 或 PATH 中检测；扩展从不安装它，也不会对整个工作区运行它。错误成为阻塞项，警告成为关注项，info/hint 留在状态信息中。

选择模型

每个端点对应一个模型设置，同时服务于边界审查与节奏审查。对于稀有的对抗式边界审查，可以选用一个强力互补模型；对于频繁的节奏监控，可以选用一个轻量模型。

text

/subagents-watchdog recommend-model
/subagents-watchdog session model recommended
/subagents-watchdog model recommended
/subagents-watchdog model anthropic/claude-opus-4-8:high
/subagents-watchdog model openai-codex/gpt-5.5:high
/subagents-watchdog model inherit
/subagents-watchdog check
/subagents-watchdog on

当配置了主看门狗模型（包括会话级覆盖）时，推荐会沿用该模型及其实际思考级别，而非评判它的强度或独立性。配置的模型不可用或未鉴权时会被报告，但不会被替换。在没有配置主模型时，推荐仍然是 Opus 4.8 或 GPT 5.5（思考级别 high），选择你的主会话未在使用且已鉴权的那一个。

session model recommended 只作用于当前会话。model recommended 会显式把推荐结果保存到 用户设置，影响其他没有覆盖的项目，但不会修改项目设置。项目级与会话级覆盖仍然优先。如要替换已配置的模型，请使用显式模型。保存模型不会启用看门狗；请另行使用 on。

json

{
  "subagents": {
    "watchdog": {
      "enabled": true,
      "main": { "model": "anthropic/claude-opus-4-8", "thinking": "high" },
      "scope": { "enabled": true },
      "cadence": { "everyNTools": 10 },
      "stalemateRepeats": 3
    }
  }
}

省略 main.model 即继承会话模型与思考级别。若 main.model 没有思考后缀、且没有 main.thinking，则按思考关闭运行，因此推荐使用 :high 以获得强力配对。

在 JSON 设置中给 main、children 或 children.overrides.<agent> 设置 fallbackModels，即可选择有序的回退链，例如 "fallbackModels": ["openai-codex/gpt-5.5:high"]。子智能体的覆盖优先级高于 children.fallbackModels；两者均不继承主看门狗的链。用户 → 项目 → 会话设置中，数组会被整体替换，[] 表示清空已继承的链。状态信息会显示已配置的链。

不可用的已配置候选项会被跳过；解析到重复的候选则只尝试一次。每次尝试都会使用一个新的评审者，它拥有独立的模型鉴权、提供方流与思考级别；继承而来的主模型保持实际的会话模型/思考级别，而回退则按显式模型的思考规则运行。回退遵循标准的子智能体提供方失败语义（包括速率限制、配额、鉴权、不可用与提供方超时），仅在任何工具工作之前，包括只读探查。干净/正常完成、长度限制、发现项、澄清、取消以及整体看门狗截止时间都不会触发回退。所有尝试共享同一原始截止时间；耗尽即视为审查失败。在没有回退链时，现有的单模型行为保持不变。

智能体可以调用 subagent({ action: "watchdog.recommend-model" }) 与 subagent({ action: "watchdog.configure", model: "recommended", scope: "session" | "user" | "project" })。除非你要求长期生效的默认值，否则应使用 scope: "session"。

可选的主会话澄清

直接使用 watchdog_warn 来对有证据支撑的、被遗忘的已授权工作进行提醒；问题不是前提条件。请区分"被遗忘的工作"与"仍在等待的依赖"或"明确的保留"。当任务状态或意图真正不清楚时再使用澄清。编排者始终拥有自己的任务/泳道板。

启用该可选功能后，已完成的 turn_end 事件会保留一段近期的真实活动尾部：成对的 subagent 调度（无 action）的调用/结果，subagent 的 status、resume、interrupt、steer、stop、bg_wait 动作，以及 subagent_supervisor 的 pending、list、reply 动作。配对要求工具名相同且工具调用 ID 完全一致；裸结果、不相关工具名以及看门狗管理动作不符合条件。每条活动记录上限 3,000 字符，跨常规新提示保留 6,000 字符的近期尾部，并跳过编辑边界。会话替换、压缩、关闭或禁用会清空它。这是观察到的文本，不是推断出的任务板。

新的未审查活动在每次用户提示中至多允许一次额外的边界审查，即便没有本地编辑。旁支问题会让更早的已授权任务证据继续可用；它们本身不会触发模型调用。该提示之后的额外审查所收集的活动仍对下一个提示开放。警告续接不能提供新的触发活动。不会增加轮询、任务调度、跨工作树扫描或空闲调用。

可见性限制： 通过父智能体的工具结果返回的外部任务/门槛完成可见。独立原生完成通知、任意的自定义消息、直接的 Shell/CI 输出，以及未通过这些契约交付给父智能体的事件，都不会被本活动尾部摄取。现有作用域至多保留 8 条提示（每条 2,000 字符）；新的流式用户输入会取消正在进行的审查，但除非 before_agent_start 触发，否则不会加入作用域。提醒依赖于已保留证据与模型判断，而非对运行中工作的穷尽视图。

在 Pi 设置中将 subagents.watchdog.clarification: true 与 enabled: true 一起设置。它默认为 false，且 仅作用于主看门狗，不作用于子看门狗或子智能体的权限仲裁。

json

{ "subagents": { "watchdog": { "enabled": true, "clarification": true } } }

在符合条件活动或代码库编辑边界，评审者可以在缺少编排者上下文而无法给出具体判断时使用 watchdog_ask 提出一个聚焦的问题。它不能在节奏审查中、已被接受的警告之后或僵局期间提问。每次真实的用户提示至多一个问题。

该工具 会产出结果并结束该次审查。带有具体证据的可见问题会在边界钩子返回后，将主会话引导进入 Pi 原生的自动续接。编排者按需处理上下文并继续；不需要回答、回执、截止时间或后续审查，也不会被追踪。问题 既不是审批，也不是权限或警告。

提问会消耗当前审查的证据，因此未变更的 Git 边界不会立即再次被审查。后续审查沿用常规的编辑、节奏与有界活动触发器，保留相同的只读工具、警告阈值、预算与僵局保护。非 Git 的观察到的编辑也可以触发提问：不存在跨回答的证据保证来验证。禁用看门狗或澄清、新的用户输入、模型变更与会话生命周期会取消适用的进行中审查并抑制过期结果；已交付的问题仍作为普通的对话记录消息保留。

审查沿用现有的 agentEndTimeoutMs。问题与证据上限分别为 1,000 与 2,000 字符；作用域、活动与差异共享现有的 24,000 字符输入上限。启用成本上每个提示至多增加一次活动边界审查与一次问题触发的续接，而非专用的回答审查。禁用的执行既不收集活动，也不增加轮询、模型调用或评审者的提示/工具内容。子智能体的警告消息与权限决策保持不变。

子看门狗

在 subagents.watchdog.children 下启用。model、fallbackModels 与 thinking 设置默认的子看门狗；overrides.<agent> 可按角色设置 model、fallbackModels、thinking、enabled 或 cadence。

启动规则

subagents.watchdog.rules 用于固定每个角色可以运行的模型。它在子智能体启动前运行，不需要模型调用，并且在模型审查关闭时同样生效。

json

{
  "subagents": {
    "watchdog": {
      "rules": {
        "action": "warn",
        "roleModels": {
          "scout": { "allow": ["openai-codex/gpt-5.6-luna:max"] },
          "oracle": {
            "deny": ["*"],
            "note": "oracle is for hard questions only; ask before launching"
          },
          "worker": { "deny": ["openai-codex/gpt-5.6-sol:high"] }
        }
      }
    }
  }
}

action: "warn" 会把一条关注推入编排者的对话记录并允许启动继续。action: "block" 返回工具错误且不启动任何东西。allow 与 deny 是锚定的、区分大小写的 glob（*、?），匹配 provider/id[:thinking] 与裸 provider/id；deny 优先。规则适用于直接启动、工作流子任务，以及在启动 cwd 可见的设置下使用的链式/并行步骤。

原生子智能体的工具权限

可选启用，仅适用于 Pi 子运行时。在没有规则时，所有工具调用直接放行。全局非 bash 规则位于 ~/.pi/agent/extensions/subagent/config.json；智能体可以在 permission: 或 permissions: frontmatter 中覆盖与之匹配的规则：

yaml

---
name: worker
permission:
  write: allow
  edit: ask
---

值可以是 allow、ask、deny。智能体的规则覆盖全局规则；省略或未知工具默认为 allow；显式的 allow 用于移除已继承的限制；当解析后的策略中既无 ask 也无 deny 时，本门槛不被注册。

ask 会暂停该精确的工具调用，并向子看门狗拥有的、一次性的仲裁器发送一份有界且经过脱敏的预览，仲裁器使用配置的子看门狗模型。仲裁器只返回 approve 或 deny，且不通知父智能体。看门狗被禁用、缺少模型/鉴权、超时、响应格式错误或运行时错误会以明确的错误拒绝该调用。请求与决策会写入有界的审计 JSONL。contact_supervisor 与可选的 pi-intercom 扩展从不接受权限门控。

Bash 始终直接放行；bash 规则会被拒绝。请使用 pi-guard 处理命令级策略。子智能体是父进程内部（前台）或分离的运行器进程（后台）中的 Pi 会话，不是独立的 pi 可执行文件，因此没有针对每个子智能体的命令封装器；可通过智能体的 extensions 或 subagentOnlyExtensions 将 pi-guard 加载到子智能体中，后台子智能体也会把它作为环境扩展加载。外部 CLI 配置档是不透明进程，原生权限无法拦截它们的工具；具有有效 ask 或 deny 规则的外部 CLI 智能体启动会被拒绝。

何时运行 ​

你将看到什么 ​

评审者拿到什么 ​

选择模型 ​

可选的主会话澄清 ​

子看门狗 ​

启动规则 ​

原生子智能体的工具权限 ​

何时运行

你将看到什么

评审者拿到什么

选择模型

可选的主会话澄清

子看门狗

启动规则

原生子智能体的工具权限