Pi Shadow Mind

为 Pi 配置多个独立的认知核心。

English · 中文

Pi Shadow Mind 让多个专业化认知核心与主 Agent 并行工作。每个 Shadow Mind 都拥有一项持续、稳定的职责，例如架构审阅、正确性检查、文档维护、项目事实核验，或任何由你定义的任务。

主 Agent 负责持续推进，其他认知核心则独立审阅决策、核验事实、维护相关文件，并在错误产生高昂返工成本之前介入。

让实现与审阅发生在同一轮工作中。

一个 Agent，多项独立职责

| 认知核心 | 职责 | | --- | --- | | 架构审阅 | 在编码过程中发现上帝组件、职责错位、模块边界缺失和脆弱的扩展点 | | 项目事实核验 | 对照真实仓库检查结论，发现模型编造的 API、文件、约束和实现细节 | | 文档维护 | 跟踪实现变化，让架构说明、设计决策和使用文档保持同步 | | 完成度审阅 | 在主 Agent 宣布完成前，独立检查结果是否真正满足任务要求 |

它们不是主 Agent 临时委派的任务，而是由用户定义、持续存在的认知职责，可以独立决定何时检查、行动或汇报。

Shadow 不只审阅，也可以工作

Shadow Mind 可以保持只读，只向主 Agent 汇报发现；也可以获得额外工具，独立负责另一条任务线。

当主 Agent 编写代码时，另一个 Shadow 可以同步维护文档、更新架构决策，或处理独立文件。工具权限由每个 Shadow 单独配置，因此每个认知核心只获得其职责真正需要的能力。

主 Agent             Architecture Shadow
实现功能              审阅模块边界

主 Agent             Documentation Shadow
编写代码              维护设计文档

审阅只是一种职责。Shadow Mind 可以观察、核验、维护，也可以直接构建。

从 Architecture Shadow 开始

创建 ~/.pi/agent/shadow-minds/architecture-review.md：

---
id: architecture-review
name: Architecture review
activation_probability: 0.3
trigger: [heartbeat]
active_for_models: ["*"]
tools: [read, grep]
---

审阅主 Agent 当前实现是否正在偏离合理架构。

检查每项职责是否有明确所有者、模块边界是否内聚、新能力是否使用了合适的扩展点。
发现不断膨胀的上帝组件、堆积在同一模块中的无关状态与方法，以及用持续增长的条件
分支承载业务差异的实现。

只报告能够从当前轨迹或仓库中得到证据、并且可以采取行动的问题。如果当前工作与该职责
无关，不要介入。

这个 Shadow 默认只读。它会在实现过程中并行审阅架构，并向主 Agent 报告具体问题，但不会接管主任务。tools 中的名称会追加到默认只读工具集；只有确实需要继承 Main Session 当前注册的全部工具（包括未来新增工具）时，才使用 tools: ["*"]。

工作方式

每个 Shadow 可以通过 trigger 选择一种或两种激活方式。默认值是 [heartbeat]：主 Agent 的一次 turn_end 只有在该轮至少完成过一个工具调用时，扩展才进行全局 heartbeat 概率判断，符合条件的 Shadow 再按照各自的 activation_probability 独立抽选。纯文本对话轮次不会触发 heartbeat。全局配置 heartbeat_tools 限定哪些 Main 工具可以触发心跳判断；单个 Shadow 的 activation_tools 限定它自己的 heartbeat 候选资格。两者默认 []（不限制），按工具名精确匹配，命中列表中任意一个即可，例如 [edit, write]。每个工具轮次先刷新配置再过滤。这两个过滤项只影响 heartbeat，不影响 final_response，也不同于授权 Shadow 自己使用工具的 tools。

使用 trigger: [final_response] 可以进行完成后审查。它在主 Agent 发出最终文字并完全 settled 后激活，不受 heartbeat 和 activation_probability 影响。同一最终回复的全部检查结束后，发现会合并为一次 shadow-report follow-up，较慢的同批检查不会介入已经修订的回复。可用 Shadow 级 final_response_rounds 限制主 Agent 输出结束后的运行轮数：设为 1 表示仅运行一轮，避免反馈循环导致持续对话；缺省或设为 0 表示不限制。trigger: [heartbeat, final_response] 会同时启用两种模式。max_parallel_shadows 仍然限制并发数；超出并发槽位的最终回复检查会排队，而不会被跳过。

每次激活都会创建一个全新的临时 Session。它继承主 Agent 原封不动的 system prompt，但只接收净化后的文本轨迹：思考内容会被移除，工具调用后仅保留简洁、确定性的结果概述。

Shadow 会先判断轨迹是否与自己的职责相关。无关时直接结束，不调用工具或 report_to_main；需要向主 Agent 提交具体结果时，通过 report_to_main 上报并立即结束本轮。

Shadow 定义只是普通 Markdown 文件，可以由用户创建和调整，也可以由 Agent 通过扩展工具管理。模型过滤和独立激活概率允许不同模型获得不同的辅助认知核心。

安装

pi install npm:pi-shadow-mind

首次启动 Session 时，扩展会创建：

~/.pi/agent/shadow-minds/
  config.json
  *.md
  logs/<shadow-id>/*.jsonl   # 仅在 debug: true 时生成

扩展不会默认创建 Shadow Mind。全局默认运行超时为 300 秒，单个 Shadow 可以通过 timeout_seconds 覆盖。

Shadow 会话加载的扩展与 Main 相同，只去掉本插件和 excluded_extensions 里列出的扩展。按会话归档或记录的扩展会把每次 Shadow 运行也记成一条用户会话，因此默认排除 pi-experiencev2。每个条目是精确标识，不是通配：包名（pi-experiencev2、@scope/name）、包目录名、单文件扩展的文件名，或绝对路径。写 "excluded_extensions": [] 就恢复加载 Main 的全部扩展。Shadow 需要自己的模型 provider，不要把 provider 扩展写进这个列表。

按 F6 或 Alt+S 可以暂停或恢复当前 Session 的 Shadow Mind。macOS 上可能需要按 Fn+F6；Alt+S 对应 Option+S，是否生效取决于终端的 Option 键映射。暂停时底部状态显示为 🐙 Paused，不再显示没有信息量的零计数。使用 /shadow 显示或隐藏状态面板，/shadow status 查看摘要，也可以通过 /shadow toggle、/shadow pause 和 /shadow resume 控制状态。TUI 模式下，/shadow reports 直接打开限高、可滚动的查看器，展示最近交付的 5 份报告，独立于最近运行列表。使用 ↑/↓、PageUp/PageDown 或 Home/End 滚动，Escape 或 /shadow reports hide 关闭。查看器显示打开时的快照，重新打开可查看新报告。报告历史仅保留在当前 Session 内存中，切换会话或 reload 时清空；已持久化的报告仍可在对话记录中查看。状态面板保持简短摘要。管理工具可以查询、创建、更新、启用、禁用和删除 Shadow Mind，以及读取或修改全局配置。所有写操作都需要用户确认。

在 DSH 中使用

如果希望在 DSH 中使用 Shadow Mind，请前往 whutzefengxie-ops/dsh-shadow-mind。该项目提供了面向 DSH 的集成实现。

开发

npm install
pi -e ./src/index.ts

完整行为约定见 DESIGN.md，Benchmark 方法与经验见 BENCHMARK.md。