pi-shadow-mind 0.1.20 → 0.1.22

package/DESIGN-Evolution.md

@@ -55,3 +55,15 @@
 - 发生：PR #9 将报告正文挂到最近运行下；审计复现报告被后续沉默运行挤出视图、长报告生成超高常驻组件，以及面板关闭时显示命令只提示成功。
 - 分析：最近运行与最近交付报告是不同的保留口径；常驻摘要面板也不适合承载完整正文。继续在 Runtime 中叠加可见性状态、命令解析和正文排版会扩大入口职责。
 - 改变：ReportHistory 独立按交付保留 5 份报告，ReportBrowser 管理命令与会话生命周期，ReportViewer 提供限高滚动快照。定向回归经过实际交付、命令和组件渲染，验证 200 行正文完整可达、终端缩放、关闭重开、会话重置及非 TUI 模式。
+
+## 2026-09-12 · 为完成检查增加按 Shadow 的轮次上限
+
+- 发生：PR #11 与 issue #10 记录到同一用户任务内的反复整改：终检报告触发 Main 修订后，新的最终回复再次触发同一 Shadow，缺少停止条件；heartbeat 报告接力也会持续唤醒整改轮。
+- 分析：跳过由 shadow-report 触发的修复轮会失去对修订结果的复核，统一预算又涉及整个调度层、不适合放进单个 Shadow 定义。因此停止条件放在单个 Shadow 的完成检查上：整批审查进入终态后才提交轮次，被新输入、新报告或会话切换失效的检查不消耗配额；超时或错误的运行同样提交一次尝试，避免对同一用户任务重复重试。存在待交付的 heartbeat 报告时先交付已知问题，避免在旧文本上启动终检并浪费有限的验收轮次。缺省与 0 都表示不限制，维持现有默认行为。
+- 改变：新增 `final_response_rounds` frontmatter 字段与调度过滤；独立的 FinalResponseBudget 拥有轮次语义、计数与重置，Runtime 只接线 Session 生命周期与整批完成回调；CompletionReview 增加完成回调，FinalResponseQueue 增加启动门禁，batcher 有待交付报告时优先刷新。heartbeat 接力、跨 Shadow 统一预算与 stop 后不自动 follow-up 仍留在 issue #10。
+
+## 2026-09-15 · active_for_models 支持排除语法与模型短名
+
+- 发生：用户希望仅对特定主力模型（如 `gpt-6-astra`）关闭某 Shadow，而对其余模型保持启用。
+- 分析：此前仅支持全量 `*` 或显式枚举白名单，针对特定模型禁用必须穷举所有其他合法模型，配置维护成本高；应支持以 `!` 开头的排除规则，支持模型短名与 glob 通配，并在纯排除配置时默认全量模型候选。
+- 改变：`matchesModel` 区分正向与否定规则；命中任一排除规则立即过滤；纯排除列表默认继承 `*`；补充短名、通配、格式破坏与调度过滤回归。

package/DESIGN.md

@@ -109,8 +109,9 @@ frontmatter 包含以下运行字段：
 | `debug` | 是否保存完整 Shadow Session 日志；默认 `false` |
 | `activation_probability` | 每次 heartbeat 时独立激活的概率，范围为 `0` 到 `1`；默认 `0.3`，不影响 final_response |
 | `trigger` | 激活方式，可包含 `heartbeat`、`final_response` 或两者；默认 `[heartbeat]` |
+| `final_response_rounds` | 主 Agent 输出结束后的最大运行轮数。设为 `1` 时仅运行一次，避免反馈循环导致持续对话；缺省或 `0` 表示不限制 |
 | `activation_tools` | heartbeat 候选工具过滤；该 Main 轮次命中任意指定工具名即可，默认 `[]` 表示不限制；final_response 独立于此过滤 |
-| `active_for_models` | 适用于哪些 Main 模型；`"*"` 表示全部模型，省略时默认 `["*"]` |
+| `active_for_models` | 适用于哪些 Main 模型；`"*"` 表示全部模型，省略时默认 `["*"]`；支持 `"!pattern"` 排除语法及通配符 |
 | `run_with_model` | Shadow 自己使用的模型；省略时使用插件默认模型 |
 | `thinking_level` | Shadow 使用的 thinking level；省略时使用插件默认值，再回退到 Main 会话当前生效等级 |
 | `timeout_seconds` | Shadow 单次运行超时；省略时使用插件默认超时 |
@@ -118,7 +119,7 @@ frontmatter 包含以下运行字段：
 
 `name` 只用于 `shadow-report` 和状态界面展示，不参与身份判断；省略时回退到最终解析出的 `id`。Markdown 正文就是 Shadow 的认知定义、长期职责和行为要求。
 
-`active_for_models` 绑定的是被观察的 Main 模型，`run_with_model` 则指定 Shadow 自己运行时使用的模型。匹配前由 Pi 将 Main 的别名或简写解析为完整 `provider/model-id`；模型过滤使用完整 ID 和精确值 `"*"` 进行匹配。模型选择优先级为：Shadow 的 `run_with_model` → 插件的 `default_shadow_model` → 激活时的当前 Main 模型。
+`active_for_models` 绑定的是被观察的 Main 模型，`run_with_model` 则指定 Shadow 自己运行时使用的模型。匹配前由 Pi 将 Main 的别名或简写解析为完整 `provider/model-id`；模型过滤使用完整 ID、纯模型短名、精确值 `"*"` 及通配符进行匹配；支持以 `!` 开头的排除规则（如 `"!gpt-6-astra"` 或 `"!openai-codex/*"`），命中任一排除项即跳过该 Shadow；当列表仅包含排除规则时，默认正向范围为全量 `*`。模型选择优先级为：Shadow 的 `run_with_model` → 插件的 `default_shadow_model` → 激活时的当前 Main 模型。
 
 如果显式配置的 `run_with_model` 当前不存在、未认证或不可用，本次激活失败并写入轻量运行事件，不自动换用其他模型。只有省略该字段时才使用插件默认 Shadow 模型。
 
@@ -346,7 +347,9 @@ Main 在会话中切换模型后，后续 heartbeat 直接依据新模型重新
 
 每次最终回复检查拥有独立、递增的 review generation。独立的 completion-review 协调器统一拥有 generation、等待队列、运行完成计数和报告聚合，Runtime 只转发宿主生命周期事件与 Shadow 启停通知。同一 generation 的报告先暂存，所有匹配 Shadow 都进入终态后才合并为一次 `shadow-report`；因此较慢的同批检查不会在 Main 已开始修订后单独 steer。新的最终回复、新用户输入、其他报告触发的修订或 Session 关闭都会使旧 generation 失效，并清空尚未启动的项目；仍在收尾的旧运行只能记录 lifetime usage，不能再投递报告。异步刷新配置和 Registry 时还会同时校验启动请求与 epoch，防止等待 I/O 的旧最终回复在新任务中恢复调度。
 
-检查结果沿用普通 `shadow-report` 的 steer/follow-up 机制。因此 Main 根据聚合报告修正并再次给出最终回复后，可以再次触发新一代完成检查；Shadow 没有发现时保持沉默，循环自然结束。
+检查结果沿用普通 `shadow-report` 的 steer/follow-up 机制。Main 根据聚合报告修正并再次给出最终回复后，默认会再次触发完成检查。若需避免反馈循环导致持续对话，可设置 `final_response_rounds: 1` 限制仅运行一轮（缺省或 `0` 表示不限制）。该轮次仅在整批审查进入终态且未被失效打断时提交；无报告以及超时或错误的运行同样计为一次尝试，被中途失效打断的审查不消耗轮次。轮次预算由独立的 FinalResponseBudget 持有，Runtime 只提交整批完成结果，并在新用户输入与 Session 开始时重置。
+
+若在触发最终回复检查时，缓冲队列中已有待交付的过程巡检报告（如 heartbeat 产出的报告），系统会优先刷新交付已有报告以驱动 Main 修复已知问题，暂不启动针对旧文本的最终检查。这避免了终检门禁在尚未修复过程缺陷的半成品上被提前唤醒并白白消耗唯一的验收轮次。Shadow 没有发现时保持沉默，循环自然结束。
 
 ## 6. Shadow 的输出与介入
 

package/README.md

@@ -72,7 +72,7 @@ This Shadow is read-only. It reviews the implementation in parallel and reports
 
 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. The global configuration `heartbeat_tools` restricts which Main tools can trigger a heartbeat evaluation; individual Shadows can use `activation_tools` to restrict their own heartbeat eligibility. Both default to `[]` (no filtering) and match any listed tool by exact name, e.g. `[edit, write]`. Config is refreshed before filtering each tool-bearing turn. These filters apply only to heartbeat, not `final_response`, and are separate from `tools`, which grants tools to the Shadow itself.
 
-Use `trigger: [final_response]` for completion review. It activates after the main agent has emitted its final text and bypasses both heartbeat and activation probability. All checks for that final response finish before their findings are sent together through one `shadow-report` follow-up, so a slow sibling cannot leak into a revised answer. `trigger: [heartbeat, final_response]` enables both modes. `max_parallel_shadows` remains the concurrency limit; excess final-response checks are queued rather than skipped.
+Use `trigger: [final_response]` for completion review. It activates after the main agent has emitted its final text and bypasses both heartbeat and activation probability. All checks for that final response finish before their findings are sent together through one `shadow-report` follow-up, so a slow sibling cannot leak into a revised answer. Set the per-Shadow `final_response_rounds` to limit execution rounds after completion: `1` allows at most one round to prevent feedback loops, while omitted or `0` means unlimited. `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.
 

package/README.zh-CN.md

@@ -69,7 +69,7 @@ tools: [read, grep]
 
 每个 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，较慢的同批检查不会介入已经修订的回复。`trigger: [heartbeat, final_response]` 会同时启用两种模式。`max_parallel_shadows` 仍然限制并发数；超出并发槽位的最终回复检查会排队，而不会被跳过。
+使用 `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，但只接收净化后的文本轨迹：思考内容会被移除，工具调用后仅保留简洁、确定性的结果概述。
 

package/dist/index.js

@@ -26,6 +26,7 @@ var FinalResponseQueue = class {
     this.pending.length = 0;
   }
   pump() {
+    if (this.options.canLaunch && !this.options.canLaunch()) return;
     while (this.options.activeCount() < this.options.maxParallel() && this.pending.length > 0) {
       const epoch = this.options.currentEpoch();
       const activeShadowIds = this.options.activeShadowIds();
@@ -49,6 +50,7 @@ var CompletionReview = class {
       maxParallel: () => this.host.maxParallel(),
       activeCount: () => this.host.activeCount(),
       activeShadowIds: () => this.host.activeShadowIds(),
+      canLaunch: () => this.host.canLaunch ? this.host.canLaunch() : true,
       launch: ({ job, run }) => host.launch(job, run)
     });
   }
@@ -75,7 +77,8 @@ var CompletionReview = class {
       requestId: request.id,
       epoch: request.epoch,
       remaining: jobs.length,
-      reports: []
+      reports: [],
+      shadowIds: jobs.map((job) => job.shadowId)
     };
     this.queue.enqueue(
       jobs.map((job) => {
@@ -99,7 +102,9 @@ var CompletionReview = class {
     this.state.remaining -= 1;
     if (this.state.remaining > 0) return;
     const reports = this.state.reports;
+    const shadowIds = this.state.shadowIds;
     this.retire(requestId);
+    this.host.onReviewCompleted?.(shadowIds);
     if (reports.length > 0) this.host.deliver(reports);
   }
   cancel(request) {
@@ -6986,6 +6991,10 @@ function parseShadowMarkdown(source, filePath) {
       value.timeout_seconds,
       "timeout_seconds"
     ),
+    finalResponseRounds: optionalNonNegativeInteger(
+      value.final_response_rounds,
+      "final_response_rounds"
+    ),
     activationTools: cleanStringArray(
       value.activation_tools,
       [],
@@ -7022,6 +7031,12 @@ function optionalPositiveNumber(value, name) {
     throw new Error(`${name} must be positive`);
   return value;
 }
+function optionalNonNegativeInteger(value, name) {
+  if (value === void 0) return void 0;
+  if (!isFiniteNumber(value) || !Number.isInteger(value) || value < 0)
+    throw new Error(`${name} must be a non-negative integer`);
+  return value;
+}
 function triggerArray(value, fallback, name) {
   const values = typeof value === "string" ? [value] : value;
   const items = cleanStringArray(values, fallback, name);
@@ -7110,6 +7125,7 @@ function serializeShadow(shadow) {
     ...shadow.runWithModel ? { run_with_model: shadow.runWithModel } : {},
     ...shadow.thinkingLevel ? { thinking_level: shadow.thinkingLevel } : {},
     ...shadow.timeoutSeconds !== void 0 ? { timeout_seconds: shadow.timeoutSeconds } : {},
+    ...shadow.finalResponseRounds !== void 0 ? { final_response_rounds: shadow.finalResponseRounds } : {},
     ...shadow.activationTools && shadow.activationTools.length ? { activation_tools: shadow.activationTools } : {},
     tools: shadow.tools ?? []
   };
@@ -7122,7 +7138,8 @@ ${(shadow.prompt ?? "").trim()}
 }
 function describeShadow(shadow) {
   const actTools = shadow.activationTools.length ? ` act_tools=${shadow.activationTools.join(",")}` : "";
-  return `${shadow.enabled ? "enabled" : "disabled"} ${shadow.id} (${shadow.name}) p=${shadow.activationProbability} trigger=${shadow.trigger.join(",")} models=${shadow.activeForModels.join(",")}${actTools} tools=${shadow.tools.join(",") || "default"} file=${basename2(shadow.filePath)}`;
+  const finalRounds = shadow.finalResponseRounds ? ` final_rounds=${shadow.finalResponseRounds}` : "";
+  return `${shadow.enabled ? "enabled" : "disabled"} ${shadow.id} (${shadow.name}) p=${shadow.activationProbability} trigger=${shadow.trigger.join(",")} models=${shadow.activeForModels.join(",")}${finalRounds}${actTools} tools=${shadow.tools.join(",") || "default"} file=${basename2(shadow.filePath)}`;
 }
 function definedOnly(value) {
   return Object.fromEntries(
@@ -7130,6 +7147,27 @@ function definedOnly(value) {
   );
 }
 
+// src/final-response-budget.ts
+var FinalResponseBudget = class {
+  counts = /* @__PURE__ */ new Map();
+  canRun(shadow) {
+    const limit = shadow.finalResponseRounds ?? 0;
+    if (limit <= 0) return true;
+    return this.used(shadow.id) < limit;
+  }
+  commit(shadowIds) {
+    for (const id of shadowIds) {
+      this.counts.set(id, this.used(id) + 1);
+    }
+  }
+  used(shadowId) {
+    return this.counts.get(shadowId) ?? 0;
+  }
+  reset() {
+    this.counts.clear();
+  }
+};
+
 // src/management-tools.ts
 import { Type } from "typebox";
 var ID = Type.String({ pattern: "^[a-z0-9][a-z0-9_-]*$" });
@@ -7157,6 +7195,7 @@ var SHADOW_FIELDS = {
   run_with_model: Type.Optional(Type.String()),
   thinking_level: Type.Optional(THINKING),
   timeout_seconds: Type.Optional(Type.Number({ exclusiveMinimum: 0 })),
+  final_response_rounds: Type.Optional(Type.Integer({ minimum: 0 })),
   activation_tools: Type.Optional(Type.Array(Type.String())),
   tools: Type.Optional(Type.Array(Type.String())),
   prompt: Type.Optional(Type.String())
@@ -7347,6 +7386,7 @@ function toPatch(raw) {
     runWithModel: raw.run_with_model,
     thinkingLevel: raw.thinking_level,
     timeoutSeconds: raw.timeout_seconds,
+    finalResponseRounds: raw.final_response_rounds,
     activationTools: raw.activation_tools,
     tools: raw.tools,
     prompt: raw.prompt
@@ -7711,6 +7751,7 @@ function decideHeartbeat(options) {
       candidates: [],
       modelFiltered: [],
       runningExcluded: [],
+      roundFiltered: [],
       toolFiltered: []
     };
   }
@@ -7752,11 +7793,13 @@ function decideHeartbeat(options) {
     })),
     modelFiltered,
     runningExcluded,
+    roundFiltered: [],
     toolFiltered
   };
 }
 function decideFinalResponse(options) {
   const modelFiltered = [];
+  const roundFiltered = [];
   const candidates = options.shadows.filter((shadow) => {
     if (!shadow.enabled || !hasTrigger(shadow, "final_response"))
       return false;
@@ -7764,6 +7807,10 @@ function decideFinalResponse(options) {
       modelFiltered.push(shadow.id);
       return false;
     }
+    if (options.canRunFinalResponse && !options.canRunFinalResponse(shadow)) {
+      roundFiltered.push(shadow.id);
+      return false;
+    }
     return true;
   }).map((shadow) => ({ shadow, roll: 0 }));
   return {
@@ -7774,11 +7821,54 @@ function decideFinalResponse(options) {
       selected: true
     })),
     modelFiltered,
-    runningExcluded: []
+    runningExcluded: [],
+    roundFiltered
   };
 }
 function matchesModel(shadow, fullModelId) {
-  return shadow.activeForModels.includes("*") || shadow.activeForModels.includes(fullModelId);
+  if (!shadow.activeForModels || shadow.activeForModels.length === 0) {
+    return false;
+  }
+  const negatives = [];
+  const positives = [];
+  for (const item of shadow.activeForModels) {
+    const trimmed = item.trim();
+    if (!trimmed) continue;
+    if (trimmed.startsWith("!")) {
+      const pattern = trimmed.slice(1).trim();
+      if (pattern) negatives.push(pattern);
+    } else {
+      positives.push(trimmed);
+    }
+  }
+  for (const neg of negatives) {
+    if (modelPatternMatches(neg, fullModelId)) {
+      return false;
+    }
+  }
+  if (positives.length === 0) {
+    return negatives.length > 0;
+  }
+  return positives.some((pos) => modelPatternMatches(pos, fullModelId));
+}
+function modelPatternMatches(pattern, fullModelId) {
+  if (pattern === "*") return true;
+  if (pattern === fullModelId) return true;
+  const slashIndex = fullModelId.indexOf("/");
+  const modelId = slashIndex !== -1 ? fullModelId.slice(slashIndex + 1) : fullModelId;
+  if (!pattern.includes("/") && pattern === modelId) {
+    return true;
+  }
+  if (pattern.includes("*")) {
+    const regex = wildcardToRegex(pattern);
+    if (regex.test(fullModelId)) return true;
+    if (!pattern.includes("/") && regex.test(modelId)) return true;
+  }
+  return false;
+}
+function wildcardToRegex(pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped.replace(/\*/g, ".*")}$`);
 }
 function matchesActivationTools(shadow, executedTools) {
   if (shadow.activationTools.length === 0) {
@@ -8682,13 +8772,16 @@ var ShadowMindRuntime = class {
   runner = new ShadowRunner();
   usageStore = new UsageStore(this.agentDir);
   active = /* @__PURE__ */ new Map();
+  finalResponseBudget = new FinalResponseBudget();
   completionReview = new CompletionReview({
     currentEpoch: () => this.epoch,
     maxParallel: () => this.configStore.current.maxParallelShadows,
     activeCount: () => this.active.size,
     activeShadowIds: () => new Set([...this.active.values()].map(({ shadow }) => shadow.id)),
+    canLaunch: () => !this.batcher.hasPending,
     launch: (pending, review) => this.launchShadow({ ...pending, completionReview: review }),
-    deliver: (reports) => void this.deliverReports(reports)
+    deliver: (reports) => void this.deliverReports(reports),
+    onReviewCompleted: (shadowIds) => this.finalResponseBudget.commit(shadowIds)
   });
   recentEvents = [];
   recentRuns = [];
@@ -8720,6 +8813,7 @@ var ShadowMindRuntime = class {
       this.latestContext = ctx;
       this.modelCalls = 0;
       this.completedWithFinalText = false;
+      this.finalResponseBudget.reset();
       this.sessionUsage = zeroUsage();
       this.recentRuns.length = 0;
       this.reports.reset();
@@ -8737,6 +8831,7 @@ var ShadowMindRuntime = class {
       this.latestContext = ctx;
       if (event.source === "extension") return;
       this.completedWithFinalText = false;
+      this.finalResponseBudget.reset();
       this.epoch += 1;
       this.abortAll("new-user-input");
     });
@@ -8866,10 +8961,7 @@ var ShadowMindRuntime = class {
     const fullModelId = `${ctx.model.provider}/${ctx.model.id}`;
     const decision = decideHeartbeat({
       heartbeatProbability: config.heartbeatProbability,
-      availableSlots: Math.max(
-        0,
-        config.maxParallelShadows - this.active.size
-      ),
+      availableSlots: Math.max(0, config.maxParallelShadows - this.active.size),
       shadows: snapshot.shadows,
       activeShadowIds: new Set(
         [...this.active.values()].map(({ shadow }) => shadow.id)
@@ -8911,6 +9003,10 @@ var ShadowMindRuntime = class {
     }
   }
   async onFinalResponse(ctx) {
+    if (this.batcher.hasPending) {
+      await this.batcher.flush();
+      return;
+    }
     const request = this.completionReview.begin(this.epoch);
     const snapshot = await this.refresh(ctx);
     if (!this.completionReview.isCurrent(request)) {
@@ -8928,13 +9024,15 @@ var ShadowMindRuntime = class {
     const fullModelId = `${mainModel.provider}/${mainModel.id}`;
     const decision = decideFinalResponse({
       shadows: snapshot.shadows,
-      mainModelId: fullModelId
+      mainModelId: fullModelId,
+      canRunFinalResponse: (shadow) => this.finalResponseBudget.canRun(shadow)
     });
     this.record("final-response", {
       candidates: decision.candidates,
       activated: decision.activated.map(({ shadow }) => shadow.id),
       ...decision.modelFiltered.length ? { modelFiltered: decision.modelFiltered } : {},
-      ...decision.runningExcluded.length ? { runningExcluded: decision.runningExcluded } : {}
+      ...decision.runningExcluded.length ? { runningExcluded: decision.runningExcluded } : {},
+      ...decision.roundFiltered.length ? { roundFiltered: decision.roundFiltered } : {}
     });
     if (!decision.activated.length) {
       this.completionReview.schedule(request, []);