pi-shadow-mind 0.1.13 → 0.1.15

package/DESIGN.md

@@ -4,7 +4,7 @@
 
 Shadow Mind 是一个运行在 Pi 主 Agent 旁边的通用并行认知运行时。
 
-主 Agent 继续正常推理和执行任务；插件以 heartbeat 随机唤醒多个 Shadow Mind，让它们沿各自的职责独立观察或推进任务。Shadow 既可以检查 Main，也可以承担文档维护等并行工作，并在有结果需要同步时向主 Agent 注入消息。
+主 Agent 继续正常推理和执行任务；插件可以通过 heartbeat 随机唤醒多个 Shadow Mind，也可以在主 Agent 完成最终回复后确定性唤醒指定 Shadow。它们沿各自的职责独立观察或推进任务，在有结果需要同步时向主 Agent 注入消息。
 
 第一版要验证的核心假设是：
 
@@ -23,9 +23,9 @@ Main Agent
 Trajectory Builder
     │  生成净化后的行为轨迹
     ▼
-Heartbeat Scheduler
-    │  按 heartbeat_probability 随机触发
-    │  每个 Shadow 按自己的概率独立参与
+Trigger Scheduler
+    │  heartbeat：按两级概率随机触发
+    │  final_response：Main settled 后必定触发
     │  并行数量受 max_parallel_shadows 限制
     ▼
 Shadow Runtime × N
@@ -65,7 +65,7 @@ Shadow 的 Markdown 定义持久存在，但运行实例不保留长期记忆。
 
 `config.json` 保存默认 Shadow 模型、`default_thinking_level`、`heartbeat_probability`、`max_parallel_shadows`、`default_shadow_timeout_seconds` 和 `result_batch_window_ms` 等全局调度配置。`default_shadow_model` 省略时，插件使用激活时的当前 Main 模型；用户也可以配置一个固定默认模型。`default_thinking_level` 的内置默认值为 `low`。
 
-每次符合调度条件的 Main `turn_end` 进行 heartbeat 判断前，插件检查并重新加载发生变化的 `config.json`。纯文本轮次不会进入 heartbeat。新配置只影响后续调度和新建实例；已经运行的 Shadow 继续使用启动时取得的配置快照。
+每次 heartbeat 判断或 final-response 调度前，插件检查并重新加载发生变化的 `config.json`。纯文本轮次不会进入 heartbeat，但 Main 的最终文字可以触发 final-response 检查。新配置只影响后续调度和新建实例；已经运行的 Shadow 继续使用启动时取得的配置快照。
 
 `config.json` 使用 last-known-good 策略。解析失败或字段无效时，插件继续使用最后一次有效配置，在界面及 `/shadow status` 中持续显示错误和当前实际生效值。只有首次加载就不存在有效配置时才使用内置默认值；插件不会自动用默认内容覆盖用户的无效文件。
 
@@ -80,6 +80,7 @@ name: 项目事实检查者
 enabled: true
 debug: false
 activation_probability: 0.6
+trigger: [heartbeat]
 run_with_model: openai/gpt-5-mini
 thinking_level: low
 timeout_seconds: 120
@@ -104,7 +105,8 @@ active_for_models:
 | `name` | 展示名称；省略时使用最终解析出的 `id` |
 | `enabled` | 是否参与调度；默认 `true` |
 | `debug` | 是否保存完整 Shadow Session 日志；默认 `false` |
-| `activation_probability` | 每次 heartbeat 时独立激活的概率，范围为 `0` 到 `1`；默认 `0.3` |
+| `activation_probability` | 每次 heartbeat 时独立激活的概率，范围为 `0` 到 `1`；默认 `0.3`，不影响 final_response |
+| `trigger` | 激活方式，可包含 `heartbeat`、`final_response` 或两者；默认 `[heartbeat]` |
 | `active_for_models` | 适用于哪些 Main 模型；`"*"` 表示全部模型，省略时默认 `["*"]` |
 | `run_with_model` | Shadow 自己使用的模型；省略时使用插件默认模型 |
 | `thinking_level` | Shadow 使用的 thinking level；省略时使用插件默认值，再回退到 Main 会话当前生效等级 |
@@ -278,7 +280,11 @@ shell({ command: "npm test" }) · 失败，12 项通过、2 项失败
 
 这样，Shadow 可以观察 Main 做了什么以及行动的大致结果，但无法直接继承 Main 的证据内容和推理路径。需要核实时，Shadow 使用自己的工具重新调查，形成独立证据链。
 
-## 5. Heartbeat 调度
+## 5. Trigger 调度
+
+每个 Shadow 通过 `trigger` 声明激活时机。省略时默认使用 `heartbeat`，因此已有定义保持原有行为。配置为 `[heartbeat, final_response]` 时，两套调度相互独立。
+
+### 5.1 Heartbeat
 
 第一版不识别 plan change、uncertainty、risk 等语义事件，也不使用 Gate Model。
 
@@ -330,6 +336,14 @@ P(activation) = heartbeat_probability × activation_probability
 
 Main 在会话中切换模型后，后续 heartbeat 直接依据新模型重新筛选。
 
+### 5.2 Final response
+
+配置了 `final_response` 的 Shadow 在 Main 发出非空最终文字，并进入 `agent_settled` 状态后参与调度。该模式仍应用 `enabled` 和 `active_for_models`，但绕过 `heartbeat_probability` 与 `activation_probability`，所有匹配项都必须获得一次运行机会。
+
+最终回复检查使用当时的完整净化轨迹快照。`max_parallel_shadows` 仍是硬并发上限；没有空闲槽位或同一 Shadow 正在运行时，检查进入专用队列，槽位释放后继续执行。新用户输入或 Session 关闭会清空旧 epoch 的队列，防止过期结果介入新任务。
+
+检查结果沿用普通 `shadow-report` 的 steer/follow-up 机制。因此 Main 根据报告修正并再次给出最终回复后，可以再次触发完成检查；Shadow 没有发现时保持沉默，循环自然结束。
+
 ## 6. Shadow 的输出与介入
 
 Shadow 可以得出“没有值得介入的发现”，此时保持沉默。插件不要求每次激活都产生消息。
@@ -405,8 +419,9 @@ heartbeat_probability
 max_parallel_shadows
 result_batch_window_ms
 default_shadow_timeout_seconds
-Shadow activation probabilities
+Shadow activation probabilities and triggers
 running Shadow IDs
+queued final-response checks
 active Shadow runs and their start epoch
 lightweight Shadow run events in Main Session custom entries
 ```
@@ -417,7 +432,7 @@ Shadow 的临时 AgentSession 不跨激活复用，也不写回记忆。
 
 轻量事件属于运行观测数据，不参与任何 Agent 的上下文。`debug: true` 产生的完整 Session 日志也只用于调试，不会成为后续 Shadow 的记忆。
 
-插件提供 `Alt+S` 快捷键以及 `/shadow toggle`、`/shadow pause`、`/shadow resume` 命令，只控制当前 Main Session 是否继续产生 heartbeat，不修改全局 Shadow Markdown。执行 pause 时立即中止当前 Session 已运行的 Shadow、清空尚未发送的聚合结果并释放并发槽位；resume 后从后续 Main `turn_end` 恢复概率判断。暂停时底部状态固定显示 `🐙 Paused`，不展示恒为零的运行数量。
+插件提供 `Alt+S` 快捷键以及 `/shadow toggle`、`/shadow pause`、`/shadow resume` 命令，控制当前 Main Session 是否继续产生 heartbeat 或 final-response 检查，不修改全局 Shadow Markdown。执行 pause 时立即中止当前 Session 已运行的 Shadow、清空排队检查和尚未发送的聚合结果并释放并发槽位；resume 后恢复后续调度。暂停时底部状态固定显示 `🐙 Paused`，不展示恒为零的运行数量。
 
 同一个 Shadow 在前一次实例仍运行时不重复激活；不同 Shadow 可以并行运行。
 

package/README.md

@@ -4,11 +4,7 @@
 
 **Configurable cognitive cores for Pi.**
 
-**为 Pi 配置多个独立的认知核心。**
-
-[English](#english) · [中文](#中文)
-
-## English
+[English](./README.md) · [中文](./README.zh-CN.md)
 
 Pi Shadow Mind runs specialized agents alongside the main agent. Each Shadow Mind owns a persistent responsibility—architecture, correctness, documentation, project grounding, or anything else you define.
 
@@ -16,12 +12,12 @@ While the main agent implements, other minds can independently review decisions,
 
 > Build and review in the same pass.
 
-### One agent, multiple responsibilities
+## One agent, multiple responsibilities
 
 The main agent keeps moving. Shadow Minds independently protect the parts of the work that matter to you.
 
 | Cognitive core | Responsibility |
-|---|---|
+| --- | --- |
 | Architecture review | Detect growing god components, misplaced responsibilities, missing module boundaries, and fragile extension points while code is being written |
 | Project grounding | Check claims against the actual repository and catch invented APIs, files, constraints, or implementation details |
 | Documentation maintenance | Track implementation changes and keep architecture notes, decisions, and usage documentation aligned |
@@ -29,7 +25,7 @@ The main agent keeps moving. Shadow Minds independently protect the parts of the
 
 These are not temporary tasks delegated by the main agent. They are persistent, user-defined cognitive roles that decide independently when to inspect, act, or report.
 
-### Shadows can review—or work
+## Shadows can review—or work
 
 A Shadow Mind may remain read-only and report findings to the main agent, or receive additional tools and own a parallel line of work.
 
@@ -45,7 +41,7 @@ writes code         maintains design documentation
 
 Review is only one possible responsibility. A Shadow Mind can observe, verify, maintain, or build.
 
-### Start with an Architecture Shadow
+## Start with an Architecture Shadow
 
 Create `~/.pi/agent/shadow-minds/architecture-review.md`:
 
@@ -54,6 +50,7 @@ Create `~/.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]
 ---
@@ -71,9 +68,11 @@ repository. If the current work is unrelated, do not intervene.
 
 This Shadow is read-only. It reviews the implementation in parallel and reports concrete architectural concerns without taking control of the main task.
 
-### How it works
+## How it works
 
-After a main-agent `turn_end` that completed at least one tool call, the extension evaluates a heartbeat. Pure text-only conversation turns are skipped, so ordinary discussion does not wake Shadows. By default, eligible turns fire a heartbeat with probability `1/3`; Shadow Minds then roll independently using their own activation probabilities, with at most two running concurrently.
+Each Shadow chooses one or both activation triggers with `trigger`. The default is `[heartbeat]`: after a main-agent `turn_end` that completed at least one tool call, the extension evaluates the global heartbeat probability, then eligible Shadows roll independently using `activation_probability`. Pure text-only conversation turns are skipped.
+
+Use `trigger: [final_response]` for completion review. It activates after the main agent has emitted its final text, bypasses both heartbeat and activation probability, and sends findings back through the normal `shadow-report` follow-up flow. `trigger: [heartbeat, final_response]` enables both modes. `max_parallel_shadows` remains the concurrency limit; excess final-response checks are queued rather than skipped.
 
 Each activation starts a fresh temporary session. It inherits the main agent's unchanged system prompt but receives only a sanitized plain-text trajectory: assistant thinking is removed, while tool calls retain compact, deterministic result summaries.
 
@@ -81,7 +80,7 @@ A Shadow first decides whether the trajectory is relevant to its responsibility.
 
 Shadow definitions are ordinary Markdown files. They can be created and adjusted by the user or managed by the agent through the extension's tools. Model filters and activation probabilities allow different models to receive different supporting minds.
 
-### Installation
+## Installation
 
 ```bash
 pi install npm:pi-shadow-mind@0.1.11
@@ -100,109 +99,15 @@ No default Shadow Mind is created. The global runtime timeout defaults to 300 se
 
 Press `Alt+S` to pause or resume Shadow Mind for the current session. The paused footer reads `🐙 Paused` without a redundant zero count. Use `/shadow` to toggle the status panel, `/shadow status` for a summary, or `/shadow toggle`, `/shadow pause`, and `/shadow resume` for command-based control. Management tools can list, create, update, enable, disable, and delete Shadow Minds, as well as read or update the global configuration. Every write requires user confirmation.
 
-For development:
-
-```powershell
-npm install
-pi -e ./src/index.ts
-```
-
-See [DESIGN.md](./DESIGN.md) for the behavioral contract and [BENCHMARK.md](./BENCHMARK.md) for benchmark methodology and lessons learned.
-
-## 中文
-
-Pi Shadow Mind 让多个专业化认知核心与主 Agent 并行工作。每个 Shadow Mind 都拥有一项持续、稳定的职责，例如架构审阅、正确性检查、文档维护、项目事实核验，或任何由你定义的任务。
-
-主 Agent 负责持续推进，其他认知核心则独立审阅决策、核验事实、维护相关文件，并在错误产生高昂返工成本之前介入。
-
-> 让实现与审阅发生在同一轮工作中。
-
-### 一个 Agent，多项独立职责
-
-| 认知核心 | 职责 |
-|---|---|
-| 架构审阅 | 在编码过程中发现上帝组件、职责错位、模块边界缺失和脆弱的扩展点 |
-| 项目事实核验 | 对照真实仓库检查结论，发现模型编造的 API、文件、约束和实现细节 |
-| 文档维护 | 跟踪实现变化，让架构说明、设计决策和使用文档保持同步 |
-| 完成度审阅 | 在主 Agent 宣布完成前，独立检查结果是否真正满足任务要求 |
-
-它们不是主 Agent 临时委派的任务，而是由用户定义、持续存在的认知职责，可以独立决定何时检查、行动或汇报。
-
-### Shadow 不只审阅，也可以工作
-
-Shadow Mind 可以保持只读，只向主 Agent 汇报发现；也可以获得额外工具，独立负责另一条任务线。
-
-当主 Agent 编写代码时，另一个 Shadow 可以同步维护文档、更新架构决策，或处理独立文件。工具权限由每个 Shadow 单独配置，因此每个认知核心只获得其职责真正需要的能力。
-
-```text
-主 Agent             Architecture Shadow
-实现功能              审阅模块边界
-
-主 Agent             Documentation Shadow
-编写代码              维护设计文档
-```
-
-审阅只是一种职责。Shadow Mind 可以观察、核验、维护，也可以直接构建。
-
-### 从 Architecture Shadow 开始
-
-创建 `~/.pi/agent/shadow-minds/architecture-review.md`：
-
-```markdown
----
-id: architecture-review
-name: Architecture review
-activation_probability: 0.3
-active_for_models: ["*"]
-tools: [read, grep]
----
-
-审阅主 Agent 当前实现是否正在偏离合理架构。
-
-检查每项职责是否有明确所有者、模块边界是否内聚、新能力是否使用了合适的扩展点。
-发现不断膨胀的上帝组件、堆积在同一模块中的无关状态与方法，以及用持续增长的条件
-分支承载业务差异的实现。
-
-只报告能够从当前轨迹或仓库中得到证据、并且可以采取行动的问题。如果当前工作与该职责
-无关，不要介入。
-```
-
-这个 Shadow 默认只读。它会在实现过程中并行审阅架构，并向主 Agent 报告具体问题，但不会接管主任务。
-
-### 工作方式
-
-主 Agent 的一次 `turn_end` 只有在该轮至少完成过一个工具调用时，扩展才进行 heartbeat 判断。纯文本对话轮次会被跳过，因此普通讨论不会唤醒 Shadow。符合条件的轮次默认以 `1/3` 的概率触发 heartbeat，Shadow Minds 再按照各自的激活概率独立抽选，默认最多同时运行两个。
-
-每次激活都会创建一个全新的临时 Session。它继承主 Agent 原封不动的 system prompt，但只接收净化后的文本轨迹：思考内容会被移除，工具调用后仅保留简洁、确定性的结果概述。
-
-Shadow 会先判断轨迹是否与自己的职责相关。无关时直接结束，不调用工具或 `report_to_main`；需要向主 Agent 提交具体结果时，通过 `report_to_main` 上报并立即结束本轮。
+## Using with DSH
 
-Shadow 定义只是普通 Markdown 文件，可以由用户创建和调整，也可以由 Agent 通过扩展工具管理。模型过滤和独立激活概率允许不同模型获得不同的辅助认知核心。
+To use Shadow Mind in DSH, see [`whutzefengxie-ops/dsh-shadow-mind`](https://github.com/whutzefengxie-ops/dsh-shadow-mind). That project provides the DSH-specific integration.
 
-### 安装
-
-```bash
-pi install npm:pi-shadow-mind@0.1.11
-```
-
-首次启动 Session 时，扩展会创建：
-
-```text
-~/.pi/agent/shadow-minds/
-  config.json
-  *.md
-  logs/<shadow-id>/*.jsonl   # 仅在 debug: true 时生成
-```
-
-扩展不会默认创建 Shadow Mind。全局默认运行超时为 300 秒，单个 Shadow 可以通过 `timeout_seconds` 覆盖。
-
-按 `Alt+S` 可以暂停或恢复当前 Session 的 Shadow Mind。暂停时底部状态显示为 `🐙 Paused`，不再显示没有信息量的零计数。使用 `/shadow` 显示或隐藏状态面板，`/shadow status` 查看摘要，也可以通过 `/shadow toggle`、`/shadow pause` 和 `/shadow resume` 控制状态。管理工具可以查询、创建、更新、启用、禁用和删除 Shadow Mind，以及读取或修改全局配置。所有写操作都需要用户确认。
-
-开发模式：
+## Development
 
 ```powershell
 npm install
 pi -e ./src/index.ts
 ```
 
-完整行为约定见 [DESIGN.md](./DESIGN.md)，Benchmark 方法与经验见 [BENCHMARK.md](./BENCHMARK.md)。
+See [DESIGN.md](./DESIGN.md) for the behavioral contract and [BENCHMARK.md](./BENCHMARK.md) for benchmark methodology and lessons learned.

package/README.zh-CN.md

@@ -0,0 +1,110 @@
+# Pi Shadow Mind
+
+![Pi Shadow Mind——主 Agent 负责构建，Shadow Minds 负责审阅、核验与维护](./assets/shadow-mind-hero-v2.png)
+
+**为 Pi 配置多个独立的认知核心。**
+
+[English](./README.md) · [中文](./README.zh-CN.md)
+
+Pi Shadow Mind 让多个专业化认知核心与主 Agent 并行工作。每个 Shadow Mind 都拥有一项持续、稳定的职责，例如架构审阅、正确性检查、文档维护、项目事实核验，或任何由你定义的任务。
+
+主 Agent 负责持续推进，其他认知核心则独立审阅决策、核验事实、维护相关文件，并在错误产生高昂返工成本之前介入。
+
+> 让实现与审阅发生在同一轮工作中。
+
+## 一个 Agent，多项独立职责
+
+| 认知核心 | 职责 |
+| --- | --- |
+| 架构审阅 | 在编码过程中发现上帝组件、职责错位、模块边界缺失和脆弱的扩展点 |
+| 项目事实核验 | 对照真实仓库检查结论，发现模型编造的 API、文件、约束和实现细节 |
+| 文档维护 | 跟踪实现变化，让架构说明、设计决策和使用文档保持同步 |
+| 完成度审阅 | 在主 Agent 宣布完成前，独立检查结果是否真正满足任务要求 |
+
+它们不是主 Agent 临时委派的任务，而是由用户定义、持续存在的认知职责，可以独立决定何时检查、行动或汇报。
+
+## Shadow 不只审阅，也可以工作
+
+Shadow Mind 可以保持只读，只向主 Agent 汇报发现；也可以获得额外工具，独立负责另一条任务线。
+
+当主 Agent 编写代码时，另一个 Shadow 可以同步维护文档、更新架构决策，或处理独立文件。工具权限由每个 Shadow 单独配置，因此每个认知核心只获得其职责真正需要的能力。
+
+```text
+主 Agent             Architecture Shadow
+实现功能              审阅模块边界
+
+主 Agent             Documentation Shadow
+编写代码              维护设计文档
+```
+
+审阅只是一种职责。Shadow Mind 可以观察、核验、维护，也可以直接构建。
+
+## 从 Architecture Shadow 开始
+
+创建 `~/.pi/agent/shadow-minds/architecture-review.md`：
+
+```markdown
+---
+id: architecture-review
+name: Architecture review
+activation_probability: 0.3
+trigger: [heartbeat]
+active_for_models: ["*"]
+tools: [read, grep]
+---
+
+审阅主 Agent 当前实现是否正在偏离合理架构。
+
+检查每项职责是否有明确所有者、模块边界是否内聚、新能力是否使用了合适的扩展点。
+发现不断膨胀的上帝组件、堆积在同一模块中的无关状态与方法，以及用持续增长的条件
+分支承载业务差异的实现。
+
+只报告能够从当前轨迹或仓库中得到证据、并且可以采取行动的问题。如果当前工作与该职责
+无关，不要介入。
+```
+
+这个 Shadow 默认只读。它会在实现过程中并行审阅架构，并向主 Agent 报告具体问题，但不会接管主任务。
+
+## 工作方式
+
+每个 Shadow 可以通过 `trigger` 选择一种或两种激活方式。默认值是 `[heartbeat]`：主 Agent 的一次 `turn_end` 只有在该轮至少完成过一个工具调用时，扩展才进行全局 heartbeat 概率判断，符合条件的 Shadow 再按照各自的 `activation_probability` 独立抽选。纯文本对话轮次不会触发 heartbeat。
+
+使用 `trigger: [final_response]` 可以进行完成后审查。它在主 Agent 发出最终文字并完全 settled 后激活，不受 heartbeat 和 `activation_probability` 影响，检查结果仍通过正常的 `shadow-report` follow-up 流程返回。`trigger: [heartbeat, final_response]` 会同时启用两种模式。`max_parallel_shadows` 仍然限制并发数；超出并发槽位的最终回复检查会排队，而不会被跳过。
+
+每次激活都会创建一个全新的临时 Session。它继承主 Agent 原封不动的 system prompt，但只接收净化后的文本轨迹：思考内容会被移除，工具调用后仅保留简洁、确定性的结果概述。
+
+Shadow 会先判断轨迹是否与自己的职责相关。无关时直接结束，不调用工具或 `report_to_main`；需要向主 Agent 提交具体结果时，通过 `report_to_main` 上报并立即结束本轮。
+
+Shadow 定义只是普通 Markdown 文件，可以由用户创建和调整，也可以由 Agent 通过扩展工具管理。模型过滤和独立激活概率允许不同模型获得不同的辅助认知核心。
+
+## 安装
+
+```bash
+pi install npm:pi-shadow-mind@0.1.11
+```
+
+首次启动 Session 时，扩展会创建：
+
+```text
+~/.pi/agent/shadow-minds/
+  config.json
+  *.md
+  logs/<shadow-id>/*.jsonl   # 仅在 debug: true 时生成
+```
+
+扩展不会默认创建 Shadow Mind。全局默认运行超时为 300 秒，单个 Shadow 可以通过 `timeout_seconds` 覆盖。
+
+按 `Alt+S` 可以暂停或恢复当前 Session 的 Shadow Mind。暂停时底部状态显示为 `🐙 Paused`，不再显示没有信息量的零计数。使用 `/shadow` 显示或隐藏状态面板，`/shadow status` 查看摘要，也可以通过 `/shadow toggle`、`/shadow pause` 和 `/shadow resume` 控制状态。管理工具可以查询、创建、更新、启用、禁用和删除 Shadow Mind，以及读取或修改全局配置。所有写操作都需要用户确认。
+
+## 在 DSH 中使用
+
+如果希望在 DSH 中使用 Shadow Mind，请前往 [`whutzefengxie-ops/dsh-shadow-mind`](https://github.com/whutzefengxie-ops/dsh-shadow-mind)。该项目提供了面向 DSH 的集成实现。
+
+## 开发
+
+```powershell
+npm install
+pi -e ./src/index.ts
+```
+
+完整行为约定见 [DESIGN.md](./DESIGN.md)，Benchmark 方法与经验见 [BENCHMARK.md](./BENCHMARK.md)。