pi-shadow-mind 0.1.18 → 0.1.19

package/DESIGN-Evolution.md

@@ -1,35 +1,39 @@
 # DESIGN Evolution
 
-本文件保存 `DESIGN.md` 主线之外仍有长期价值的设计理由、边界来源和候选方向。`DESIGN.md` 只描述当前运行时契约。
+本日志记录 `DESIGN.md` 当前契约之外仍需保留的约束、分析与变更原因；更新时先压缩历史，再追加新的变更单元。
 
-## 稳定设计护栏
+## 2026-09-04 · 确立最小可验证的调度模型
 
-- 2026-09-04: 初始设计以“随机 heartbeat + 确定性 final-response review”验证多个持久职责 Shadow 是否能够稳定补充 Main。复杂智能调度会改变实验变量，因此留待基础机制获得数据后再评估。
-- 2026-09-04: Shadow 定义采用全局 registry，运行实例保持一次性。全局实体先验证跨项目复用价值；临时 AgentSession 则保持实例隔离，避免隐式继承旧运行历史。
-- 2026-09-04: 工具授权以用户显式白名单为边界。Pi 的通用 `ToolDefinition` 无法声明只读性，插件也无法完整预知第三方工具副作用，因此运行时不制造“文件写入已被安全互斥”的假保证。
-- 2026-09-04: Shadow 上下文采用 Main 可见上下文的净化子集。它保留用户约束、Main 行为和工具调用概述，同时排除 Main thinking、完整工具结果与未上报的 Shadow 推理，使 Shadow 能独立核查而不是复制 Main 的证据链。
-- 2026-09-04: 完成后检查由独立 generation 聚合整批结果。新输入或修订会使旧 generation 失效，防止较慢的检查在 Main 已经进入下一条任务线后继续介入。
-- 2026-09-04: `report_to_main` 保持单字段、单次上报协议。严重度、类别和表达结构属于各 Shadow 的职责定义，公共运行时只负责终止当前 loop 与可靠投递。
+- 发生：系统需要验证多个持久职责 Shadow 能否稳定补充 Main。
+- 分析：复杂语义调度会同时改变过多实验变量，基础机制尚未产生足够收益、误报、成本和延迟数据。
+- 改变：采用随机 heartbeat 与确定性 final-response review；语义 Gate、Expected Value of Thinking、学习型调度和自动策略优化保留为获得运行数据后的候选。
 
-## 候选方向
+## 2026-09-04 · 分离持久定义与一次运行
 
-- 基于实际收益、误报、成本和延迟数据，评估语义 Gate、Expected Value of Thinking 或学习型调度器。
-- 当项目级职责出现稳定需求时，设计项目 registry 及全局/项目覆盖规则。
-- 为能够声明目标文件的工具设计自愿接入的协作式锁；未知工具继续明确处于协议之外。
-- 在不削弱独立核查的前提下，评估跨次 Shadow 记忆或显式 Shadow 间通信。
-- 当不同执行模型的上下文窗口形成真实限制时，评估独立摘要或截断策略。
-- 根据跨供应商运行的实际隐私需求，评估工具参数中的凭据识别与脱敏。
-- 当观察需求成熟后，评估内置 Markdown 编辑体验以及调试日志轮转策略。
+- 发生：Shadow 既需要跨项目复用职责，又需要避免运行历史在任务间隐式泄漏。
+- 分析：全局定义适合表达持久身份，一次性 AgentSession 适合隔离状态；Main 可见上下文足以支持独立核查，Main thinking、完整工具结果和未上报 Shadow 推理会污染证据链。
+- 改变：Shadow 定义进入全局 registry，运行实例保持一次性；上下文使用 Main 可见内容的净化子集。项目 registry、跨次记忆、Shadow 间通信及独立摘要/截断留待真实需求出现后评估。
 
-## 延后路径
+## 2026-09-04 · 建立完成检查的 generation 边界
 
-- 依据错误、风险、计划变化等语义事件直接进行规则调度。
-- 自动训练或优化 Shadow 及其调度策略。
-- 把 Main thinking 或完整工具结果直接传递给 Shadow。
-- 由运行时强制所有 Main、Shadow 与第三方工具参加文件级写入锁。
-- 用模型对同期 Shadow 报告进行二次总结或去重。
-- 在公共报告协议中加入固定严重度、类别或报告模板。
+- 发生：多个 completion Shadow 可能晚于新输入或修订返回。
+- 分析：旧检查若继续介入，会把过期判断投递到新的任务线；同期结果也需要一次性聚合，而不是逐条打断 Main。
+- 改变：每轮完成检查由独立 generation 管理并整批交付，新输入或修订使旧 generation 失效；模型二次总结或去重暂不进入公共流程。
 
-## 退役表达
+## 2026-09-04 · 明确工具授权边界
 
-- 将“多核”或“章鱼”隐喻作为运行时技术定义。它们可以服务产品表达，但不拥有架构语义。
+- 发生：Shadow 需要显式工具能力，广泛授权的静态列表又会随 Main Session registry 漂移。
+- 分析：Pi 的通用 `ToolDefinition` 不能声明只读性，运行时也无法预知第三方工具副作用，因此不能承诺普适文件锁；全工具授权应继承实时 registry，而非复制名称。
+- 改变：普通 Shadow 使用用户白名单，`tools: ["*"]` 动态解析当前工具 registry。协作式目标文件锁、未知工具协调和凭据脱敏仅作为未来可选协议。
+
+## 2026-09-04 · 保持最小报告协议
+
+- 发生：公共运行时需要可靠接收不同职责 Shadow 的结论。
+- 分析：严重度、类别和表达结构属于职责定义；把它们固化进协议会限制新 Shadow，并增加无必要的运行时分支。
+- 改变：`report_to_main` 保持单字段、单次上报，负责终止当前 loop 和可靠投递；固定严重度、类别、模板及同期报告的模型总结均不进入公共协议。
+
+## 2026-09-04 · 收敛设计语言与扩展范围
+
+- 发生：早期讨论包含产品隐喻、内置编辑体验和可观测性扩展等非运行时主线内容。
+- 分析：“多核”“章鱼”等隐喻适合产品表达但不拥有架构语义；Markdown 编辑器和日志轮转需要先由真实使用证明价值。
+- 改变：`DESIGN.md` 只保留当前运行时契约；隐喻退出技术定义，编辑体验、日志轮转及其他尚未验证的扩展保留在本变更历史中。

package/README.md

@@ -97,7 +97,7 @@ On the first session start, the extension creates:
 
 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.
+Press `F6` or `Alt+S` to pause or resume Shadow Mind for the current session. On macOS, you may need `Fn+F6`; `Alt+S` corresponds to `Option+S` and depends on the terminal's Option key mapping. 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.
 
 ## Using with DSH
 

package/README.zh-CN.md

@@ -94,7 +94,7 @@ pi install npm:pi-shadow-mind
 
 扩展不会默认创建 Shadow Mind。全局默认运行超时为 300 秒，单个 Shadow 可以通过 `timeout_seconds` 覆盖。
 
-按 `Alt+S` 可以暂停或恢复当前 Session 的 Shadow Mind。暂停时底部状态显示为 `🐙 Paused`，不再显示没有信息量的零计数。使用 `/shadow` 显示或隐藏状态面板，`/shadow status` 查看摘要，也可以通过 `/shadow toggle`、`/shadow pause` 和 `/shadow resume` 控制状态。管理工具可以查询、创建、更新、启用、禁用和删除 Shadow Mind，以及读取或修改全局配置。所有写操作都需要用户确认。
+按 `F6` 或 `Alt+S` 可以暂停或恢复当前 Session 的 Shadow Mind。macOS 上可能需要按 `Fn+F6`；`Alt+S` 对应 `Option+S`，是否生效取决于终端的 Option 键映射。暂停时底部状态显示为 `🐙 Paused`，不再显示没有信息量的零计数。使用 `/shadow` 显示或隐藏状态面板，`/shadow status` 查看摘要，也可以通过 `/shadow toggle`、`/shadow pause` 和 `/shadow resume` 控制状态。管理工具可以查询、创建、更新、启用、禁用和删除 Shadow Mind，以及读取或修改全局配置。所有写操作都需要用户确认。
 
 ## 在 DSH 中使用
 

package/dist/index.js

@@ -8520,13 +8520,15 @@ var ShadowMindRuntime = class {
         this.updateStatus(ctx);
       }
     });
-    this.pi.registerShortcut("alt+s", {
-      description: "Pause or resume Shadow Mind",
-      handler: (ctx) => {
-        this.latestContext = ctx;
-        this.setPaused(!this.paused, ctx);
-      }
-    });
+    for (const shortcut of ["f6", "alt+s"]) {
+      this.pi.registerShortcut(shortcut, {
+        description: "Pause or resume Shadow Mind",
+        handler: (ctx) => {
+          this.latestContext = ctx;
+          this.setPaused(!this.paused, ctx);
+        }
+      });
+    }
     this.pi.registerMessageRenderer(
       "shadow-report",
       (message, _options, theme) => {