pi-shadow-mind 0.1.10 → 0.1.13

package/DESIGN.md

@@ -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`。新配置只影响后续调度和新建实例；已经运行的 Shadow 继续使用启动时取得的配置快照。
+每次符合调度条件的 Main `turn_end` 进行 heartbeat 判断前，插件检查并重新加载发生变化的 `config.json`。纯文本轮次不会进入 heartbeat。新配置只影响后续调度和新建实例；已经运行的 Shadow 继续使用启动时取得的配置快照。
 
 `config.json` 使用 last-known-good 策略。解析失败或字段无效时，插件继续使用最后一次有效配置，在界面及 `/shadow status` 中持续显示错误和当前实际生效值。只有首次加载就不存在有效配置时才使用内置默认值；插件不会自动用默认内容覆盖用户的无效文件。
 
@@ -161,7 +161,7 @@ report_to_main({ content: "..." })
 
 所有 Shadow 都记录轻量运行事件，包括激活、沉默、上报、超时、中止、耗时、执行模型以及工具使用摘要。工具摘要只记录工具名、调用次数和成功/失败统计，不保存参数或结果。事件作为自定义 entries 写入当前 Main Session，随会话持久化和恢复，但不参与 Main 的模型上下文。
 
-每次 Main `turn_end` 的 heartbeat 判断都会写入一条轻量调度事件：先记录 heartbeat 随机值与是否触发；触发后再记录候选 Shadow、各自随机值、概率命中项、模型过滤、运行中排除、并发槽位裁剪和最终激活项。事件不保存 Main 或 Shadow 上下文，用于完整复盘调度决策。
+每次 Main `turn_end` 都会写入一条轻量调度事件。没有工具活动的纯文本轮次记录为跳过；符合条件的轮次记录 heartbeat 随机值与是否触发，触发后再记录候选 Shadow、各自随机值、概率命中项、模型过滤、运行中排除、并发槽位裁剪和最终激活项。事件不保存 Main 或 Shadow 上下文，用于完整复盘调度决策。
 
 `/shadow` 打开统一状态面板，展示当前 Session 的暂停状态、有效与无效 Shadow、正在运行的实例、最近事件和实际生效配置；`/shadow status` 提供对应的摘要视图。第一版面板以观察为主，不内置完整 Markdown 编辑器。
 
@@ -282,18 +282,18 @@ shell({ command: "npm test" }) · 失败，12 项通过、2 项失败
 
 第一版不识别 plan change、uncertainty、risk 等语义事件，也不使用 Gate Model。
 
-每次 Main model call 完成后，按插件配置 `heartbeat_probability` 独立判断是否产生 heartbeat。默认值为 `1/3`：
+Main model call 完成后，只有该 `turn_end` 至少包含一个已完成的工具调用，才按插件配置 `heartbeat_probability` 独立判断是否产生 heartbeat。默认值为 `1/3`：
 
 ```text
-P(heartbeat after model call) = heartbeat_probability
+P(heartbeat after eligible tool-bearing turn) = heartbeat_probability
 default heartbeat_probability = 1 / 3
 ```
 
-实现上以 Main Agent 的每次 `turn_end` 作为一次 model call 边界。带工具调用的中间轮次与不带工具调用的最终回复轮次都参与判断；Shadow AgentSession 自己的 `turn_end` 不参与 Main heartbeat。
+纯文本轮次直接跳过，不消耗随机数，也不启动 Shadow。这会压制普通问答、方案讨论和 Shadow 报告后的纯文本回应产生的无效唤醒。带工具调用的中间轮次仍参与判断，因此 Main 一旦开始读取、验证或修改项目，Shadow 仍可并行介入。Shadow AgentSession 自己的 `turn_end` 不参与 Main heartbeat。
 
-由 `shadow-report` 触发的 Main 补充或修正也属于正常 Main 工作链，其 `turn_end` 继续参与 heartbeat。第一版不限制 Shadow 介入链的深度，允许后续 Shadow 再次检查 Main 的修正；概率、并发上限、超时和结果聚合共同承担节流。
+由 `shadow-report` 触发的 Main 补充或修正只有在实际调用工具时才重新获得 heartbeat 机会，避免纯文本报告与回应形成递归唤醒链。
 
-默认情况下，相邻 heartbeat 的期望间隔为 3 次 model call，但实际间隔保持随机：可能连续发生，也可能较长时间不发生。
+默认情况下，相邻 heartbeat 的期望间隔为 3 个符合条件的工具轮次，但实际间隔保持随机：可能连续发生，也可能较长时间不发生。
 
 第一版直接使用运行时随机数，不提供或持久化随机 seed，也不承诺重放同一调度序列。实际抽样值通过轻量调度事件保留，供事后分析。
 
@@ -318,13 +318,13 @@ available_slots = max_parallel_shadows - running_shadow_count
 
 命中数量超过剩余槽位时，未被随机选中的 Shadow 直接跳过，不进入等待队列，也不保留本次轨迹快照。后续 heartbeat 会基于届时的最新上下文重新判断。
 
-`activation_probability` 表示 heartbeat 已经发生之后，该 Shadow 被选中的基础概率。因此某个 Shadow 在单次 Main model call 后获得激活机会的基础概率为：
+`activation_probability` 表示 heartbeat 已经发生之后，该 Shadow 被选中的基础概率。因此某个 Shadow 在单次符合条件的 Main 工具轮次后获得激活机会的基础概率为：
 
 ```text
 P(activation) = heartbeat_probability × activation_probability
 ```
 
-`activation_probability` 省略时使用默认值 `0.3`。在默认 heartbeat 概率 `1/3` 下，且不考虑并发槽位竞争时，该 Shadow 每次 Main `turn_end` 的基础激活概率约为 `10%`。
+`activation_probability` 省略时使用默认值 `0.3`。在默认 heartbeat 概率 `1/3` 下，且不考虑并发槽位竞争时，该 Shadow 每次符合条件的 Main `turn_end` 的基础激活概率约为 `10%`；纯文本轮次为 `0%`。
 
 当一次 heartbeat 的命中数量超过剩余并发槽位时，并发上限会进一步降低每个命中项的最终激活概率。
 
@@ -417,7 +417,7 @@ Shadow 的临时 AgentSession 不跨激活复用，也不写回记忆。
 
 轻量事件属于运行观测数据，不参与任何 Agent 的上下文。`debug: true` 产生的完整 Session 日志也只用于调试，不会成为后续 Shadow 的记忆。
 
-插件提供 `/shadow pause` 与 `/shadow resume`，只控制当前 Main Session 是否继续产生 heartbeat，不修改全局 Shadow Markdown。执行 pause 时立即中止当前 Session 已运行的 Shadow、清空尚未发送的聚合结果并释放并发槽位；resume 后从后续 Main `turn_end` 恢复概率判断。
+插件提供 `Alt+S` 快捷键以及 `/shadow toggle`、`/shadow pause`、`/shadow resume` 命令，只控制当前 Main Session 是否继续产生 heartbeat，不修改全局 Shadow Markdown。执行 pause 时立即中止当前 Session 已运行的 Shadow、清空尚未发送的聚合结果并释放并发槽位；resume 后从后续 Main `turn_end` 恢复概率判断。暂停时底部状态固定显示 `🐙 Paused`，不展示恒为零的运行数量。
 
 同一个 Shadow 在前一次实例仍运行时不重复激活；不同 Shadow 可以并行运行。
 
@@ -436,6 +436,7 @@ Shadow 的临时 AgentSession 不跨激活复用，也不写回记忆。
 - AI 写入全局 Shadow registry 前取得用户确认；
 - 按 Main 模型筛选 Shadow；
 - 为每个 Shadow 配置执行模型，并支持插件级默认模型；
+- 纯文本 Main 轮次跳过 heartbeat，只在完成工具调用的轮次参与调度；
 - 通过 `heartbeat_probability` 配置随机 heartbeat，默认概率为 `1/3`；
 - 每个 Shadow 按自己的概率参与 heartbeat；
 - 通过 `max_parallel_shadows` 配置最大并行数量；

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 liuzhengdongfortest
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,36 +1,93 @@
 # Pi Shadow Mind
 
-Shadow Mind is a Pi extension that occasionally starts independent, temporary agent sessions beside the main agent. Each Shadow Mind is a Markdown entity with its own responsibility, model filter, activation probability, tools, model, thinking level, timeout, and optional debug log.
+![Pi Shadow Mind — the main agent builds while Shadow Minds review, verify, and maintain](./assets/shadow-mind-hero-v2.png)
 
-The first version activates on each main-agent `turn_end`: the heartbeat fires with probability `1/3`, eligible Shadow Minds roll independently (default `0.3`), and at most two run concurrently. Shadow sessions inherit the unchanged main system prompt. Their compacted visible trajectory is flattened into plain text: assistant thinking is removed, and each tool call is followed by a deterministic result summary.
+**Configurable cognitive cores for Pi.**
 
-## Install for development
+**为 Pi 配置多个独立的认知核心。**
 
-```powershell
-npm install
-pi -e ./src/index.ts
-```
+[English](#english) · [中文](#中文)
 
-Pi also discovers this package when installed as a Pi package because `package.json` declares `pi.extensions`.
+## English
 
-## Build and distribute
+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.
 
-```powershell
-npm run build
-npm pack
+While the main agent implements, other minds can independently review decisions, verify claims, maintain related files, and intervene before mistakes become expensive to undo.
+
+> Build and review in the same pass.
+
+### 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 |
+| Completion review | Independently verify that the result satisfies the task before the main agent declares it finished |
+
+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
+
+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.
+
+While the main agent writes code, another Shadow can maintain documentation, update architectural decisions, or work on a separate file. Tool access is configured per Shadow, so each cognitive core receives only the capabilities its responsibility requires.
+
+```text
+Main Agent          Architecture Shadow
+implements feature  reviews module boundaries
+
+Main Agent          Documentation Shadow
+writes code         maintains design documentation
 ```
 
-The generated `pi-shadow-mind-<version>.tgz` contains the compiled `dist/` extension. Publish it to npm for normal Pi installation, or unpack the standalone ZIP release and install that directory:
+Review is only one possible responsibility. A Shadow Mind can observe, verify, maintain, or build.
 
-```powershell
-pi install npm:pi-shadow-mind@0.1.10
-# or, after unpacking the ZIP
-pi install ./pi-shadow-mind-0.1.0
+### Start with an Architecture Shadow
+
+Create `~/.pi/agent/shadow-minds/architecture-review.md`:
+
+```markdown
+---
+id: architecture-review
+name: Architecture review
+activation_probability: 0.3
+active_for_models: ["*"]
+tools: [read, grep]
+---
+
+Review the main agent's current implementation for architectural drift.
+
+Check whether responsibilities have clear owners, modules have coherent
+boundaries, and new behavior uses appropriate extension points. Detect growing
+god components, unrelated state or methods accumulating in one module, and
+business differences implemented as expanding conditionals.
+
+Report only concrete, actionable issues grounded in the visible trajectory or
+repository. If the current work is unrelated, do not intervene.
 ```
 
-## Global files
+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
 
-On first session start, the extension creates:
+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 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.
+
+A Shadow first decides whether the trajectory is relevant to its responsibility. If unrelated, it exits without calling tools or `report_to_main`. When the main agent should receive a concrete result, the Shadow calls `report_to_main`, which immediately ends that run.
+
+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
+
+```bash
+pi install npm:pi-shadow-mind@0.1.11
+```
+
+On the first session start, the extension creates:
 
 ```text
 ~/.pi/agent/shadow-minds/
@@ -39,20 +96,113 @@ On first session start, the extension creates:
   logs/<shadow-id>/*.jsonl   # only when debug: true
 ```
 
-No default Shadow Mind is created. A minimal definition is:
+No default Shadow Mind is created. The global runtime timeout defaults to 300 seconds, and individual Shadows may override it with `timeout_seconds`.
+
+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: project-grounding
-name: Project grounding
+id: architecture-review
+name: Architecture review
 activation_probability: 0.3
-active_for_models: ["openai/gpt-5"]
+active_for_models: ["*"]
 tools: [read, grep]
 ---
 
-Check whether the main agent is inventing project facts. Inspect the repository when needed and report only concrete discrepancies.
+审阅主 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` 上报并立即结束本轮。
+
+Shadow 定义只是普通 Markdown 文件，可以由用户创建和调整，也可以由 Agent 通过扩展工具管理。模型过滤和独立激活概率允许不同模型获得不同的辅助认知核心。
+
+### 安装
+
+```bash
+pi install npm:pi-shadow-mind@0.1.11
 ```
 
-Use `/shadow` to toggle the compact status panel, `/shadow status` for a summary, and `/shadow pause` or `/shadow resume` for the current main session. The extension also exposes tools to list, create, update, enable, disable, and delete definitions, plus read/update the global config. Every write requires user confirmation.
+首次启动 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，以及读取或修改全局配置。所有写操作都需要用户确认。
+
+开发模式：
+
+```powershell
+npm install
+pi -e ./src/index.ts
+```
 
-See [DESIGN.md](./DESIGN.md) for the complete behavioral contract.
+完整行为约定见 [DESIGN.md](./DESIGN.md)，Benchmark 方法与经验见 [BENCHMARK.md](./BENCHMARK.md)。