@genee/omp-opsx-addon 0.2.0 → 0.4.0

package/README.md

@@ -63,6 +63,15 @@ tiers:
 # 可选：role → tier 期望
 role_tiers:
   planner: top
+
+# 可选：OMP 内置/自定义 model role → tier 期望（或 skip 排除）
+# 仅影响 /pick-model 后 session 覆盖写入哪些模型；合法值 tiny/low/mid/high/top/skip
+model_role_tiers:
+  advisor: skip
+  plan: skip
+  tiny: skip
+  vision: skip   # vision 固定 high 档候选，仅 skip 有效（见下文）
+  task: low
 ```
 
 ---
@@ -73,6 +82,79 @@ role_tiers:
 
 决策日志打印到 stderr：`[omp-opsx-addon] planner → anthropic/claude-opus-4-6 (tier=top, gap=0, remaining=0.80)`
 
+
+### 子 agent 模型落点：session-scoped modelRoles
+
+`/pick-model <selector>` / `refresh` / `reset` 应用选择结果时，插件**不**再按 agent 名写
+`task.agentModelOverrides`，而是写 OMP session 运行时覆盖
+`settings.overrideModelRoles({ …全 role… })`——覆盖**宿主当前已知的全部 model role**
+（10 个内置 role + 自定义 role：`getKnownRoleIds` 从 cycleOrder/modelRoles/modelTags 汇总）：
+
+- 每个 role 跟随一个 tier 的选中模型；同一 tier 的多个 role 共用同一个模型（同候选集
+  排序结果唯一）。mid/high 复用 opsx 4 role 的选择（coder→mid、reviewer→high），
+  tiny/low/top 在同一过滤候选集上补选。
+- **内置 role 默认 tier 映射**：
+
+  | role | tier | 触发场景 |
+  | --- | --- | --- |
+  | `tiny` | tiny | 极小任务 |
+  | `smol` | mid | scout 等快速任务 |
+  | `task` | mid | task 工具委派的全能力子 agent（与 scout 同档，防能力倒挂） |
+  | `commit` | low | AI commit |
+  | `default` | high | 主会话 / reviewer |
+  | `designer` | high | designer agent |
+  | `vision` | high | `/vision`、图像输入（**能力门控**，见下） |
+  | `slow` | top | 深度思考 |
+  | `plan` | top | plan mode |
+  | `advisor` | top | advisor 会话 |
+
+  **激活语义**：advisor/plan/tiny 等默认未配置的 role 被写入覆盖后，**只在对应功能真正
+  触发时**（plan mode、advisor 会话、auto-thinking、AI commit、`/vision`）才会解析到
+  selector 模型；功能不触发就不产生消耗。覆盖 session 结束即还原。
+- **自定义 role**（cycleOrder/modelTags 里出现、不在内置表中的 role）默认跟随 `high`，
+  并一次性 warn 提示可用 `model_role_tiers` 调档或排除。
+- **`model_role_tiers`（opsx.yml）**：OMP role 名 → `tiny/low/mid/high/top` 或 `skip`，
+  覆盖上表默认值；自定义 role 也可配。`skip` 是唯一逃生舱——该 role **不写** session
+  覆盖、保留你的 config 值（默认策略是全量覆盖，包含 config 里的 `modelRoles.*` 钉值，
+  不做「自动跳过钉值」）。**例外：`vision` role 固定使用 high 档候选**（仅在具备 image
+  能力的模型中挑选，见下条），`model_role_tiers.vision` **仅 `skip` 生效**——配
+  `top/low/…` 等其他 tier 值会被静默接受但**不改变其选档**（仍按 high 档选图像模型）。
+  保守配置示例：
+
+  ```yaml
+  model_role_tiers:
+    advisor: skip   # 不想让 advisor 会话走 selector 模型
+    plan: skip      # plan mode 保留 config 钉值
+    tiny: skip      # 无 tiny 档模型时避免回落
+    vision: skip    # 不覆盖 vision（vision 固定 high 档选图像模型，仅 skip 有效）
+    task: low       # 显式降档
+  ```
+
+- **vision 能力门控**：vision 候选**固定按 high 档**、只从声明 `input` 含 `image` 的模型
+  中挑选（不按 `model_role_tiers.vision` 的 tier 值选档，该键仅 `skip` 有效）；当前选择里
+  没有图像模型时，vision role **不写覆盖**（warn 汇总为 `vision(capability)`，绝不写入
+  纯文本模型），vision 功能回落 config/default。恢复手段：换一个含图像模型的 selector
+  或用 `model_allowlist` 纳入图像模型；**`model_role_tiers.vision` 改 tier 绕不过门控、
+  也不改选档**。
+- **auto role 的 agent 定义**在 `.omp/agents/*.md` frontmatter 注入带引号的 tier alias
+  （coder `model: "@smol"`，其余三者 `model: "@default"`）；task 工具经 modelRoles 解析。
+- 因此**所有经 role 解析的 agent 都跟随切换**——包括插件未枚举的 OMP 内置/bundled/
+  project agent（例如内置 scout 走 `smol`，`/pick-model` selector/refresh/reset 后
+  scout 自动换到选中模型）。
+- auto role 与 omp-alias（如 `slow`，值无 `/`）的 dispatch 提示词**不传 `model=`**，
+  由 frontmatter alias 声明式接管；pinned 具体 provider/model 仍显式传 model，行为不变。
+- 某 tier 补选没有可用模型（候选耗尽/allowlist 全过滤）时，该 tier 的各 role 不写覆盖、
+  warn 汇总（`no-pick`），命令不中断；无任何模型时计划为空，与既有「模型注册表不可用」
+  分支一致。
+- 覆盖为 **session 作用域、不写盘**：`overrideModelRoles` 只写 runtime overlay，
+  session 结束即还原；不会修改你的 `~/.omp/agent/config.yml`。每次应用前先
+  `clearOverride('modelRoles')`，避免上一 selector 的旧 role 值残留；`reset` 重算无约束
+  默认并覆盖（**不清空**，否则回落 config 硬钉）。
+
+> **手动清理建议**：若全局 `~/.omp/agent/config.yml` 里有 `modelRoles.smol` 钉在会耗尽的
+> 套餐模型（scout 会一直打它直到被 session 覆盖压过），或 `task.agentModelOverrides` 残留
+> 已删除的 `tester` 等 key，可手动删除这些钉值；插件运行期间会以 session 空串中和 per-agent
+> 钉值，但不改动你的配置文件。
 ---
 
 ## 开发

package/index.ts

@@ -104,23 +104,37 @@ function handleSubagentEvent(payload: unknown, primarySessionId: string): void {
         sessionUsageRecorder.record(canonicalizeProvider(provider), usage, subagentStreamKey);
     } catch (err) {
         // Silently fail to avoid breaking the plugin
-        console.error('Failed to handle subagent event:', err);
+        getLogger().error('Failed to handle subagent event', { err });
     }
 }
-import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from '@oh-my-pi/pi-coding-agent';
+import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext, Settings } from '@oh-my-pi/pi-coding-agent';
+import { getKnownRoleIds, MODEL_ROLE_IDS } from '@oh-my-pi/pi-coding-agent/config/model-roles';
 import type { Model, Api } from '@oh-my-pi/pi-catalog/types';
 import type { UsageReport } from '@oh-my-pi/pi-ai';
 import { createCachedScanner } from './lib/change-scanner.js';
 import { installAgents } from './lib/agent-defs.js';
+import {
+    applyRoleModelOverrides,
+    buildRoleOverridePlan,
+    dispatchModelHint,
+    frontmatterModel,
+    ROLE_TO_OMP_ALIAS,
+    OMP_ROLE_TO_TIER,
+    ROLE_CAPABILITY,
+    type SkippedRole,
+} from './lib/model-roles.js';
 import { buildStaticPrompt, buildDynamicPrompt } from './lib/system-prompt.js';
 import { type ProviderHealth, canonicalizeProvider, listDetectableProviders, healthCacheKey } from './lib/usage-resolver.js';
 import { readOpsxSettings, type ResolvedOpsxConfig, type RoleValue, OPSX_ROLES } from './lib/unified-config.js';
-import { selectAllRoles, mergePlanProviders, type SelectorResult } from './lib/model-selector.js';
-import { scoreModelWithProvider } from './lib/model-tiers.js';
+import { selectAllRoles, selectModel, mergePlanProviders, type SelectorResult } from './lib/model-selector.js';
+import { scoreModelWithProvider, type TierName } from './lib/model-tiers.js';
 import { DIRECT_FETCHERS } from './lib/direct-fetchers.js';
 import { createUsageWidget } from './lib/usage-widget.js';
 import { renderUsageReports, type ConsumptionTrack } from './lib/usage-render.js';
 import { markExhausted, markAvailable, getExhaustedProviders } from './lib/provider-status.js';
+import { registerPipeCore } from './lib/pipe-core.js';
+import { registerPipePush } from './lib/pipe-push.js';
+import { scheduleStatusProbes } from './lib/status-probe.js';
 import {
     startSharedPoller,
     getUnconfirmedProviders,
@@ -157,6 +171,7 @@ import { filterSelectableModels, reachabilityFingerprint } from './lib/selection
 import { parseAutoModelArgs, CHINA_EXCLUDE_FAMILIES, listFamilies, listProviders } from './lib/family-filter.js';
 import { hasRateLimitError, hasRegionError, buildErrorDiagnosis, exclusionReasonStats } from './lib/error-scan.js';
 import { applyEditVariantPin } from './lib/edit-variant-pin.js';
+import { setOpsxLogger, getLogger } from './lib/logger.js';
 type Role = 'coder' | 'reviewer' | 'planner' | 'proposal-reviewer';
 
 /** Session-scoped selector constraint for `/pick-model <selector> [--china]`. */
@@ -265,24 +280,17 @@ export interface SelectionContext {
     roleModels: Record<Role, string | undefined>;
     /** Display label for each role from config, e.g. "auto", "smol", "deepseek-v4-pro". */
     roleConfigs: Record<Role, string | undefined>;
+    /** Parsed role value kind for each role (auto | omp-alias | model | provider-model). */
+    roleKind: Record<Role, RoleValue['kind']>;
+    /** Full-role session overlay payload written to `overrideModelRoles` (all known OMP roles). */
+    roleOverrides: Record<string, string>;
+    /** Known roles left out of the overlay payload (config skip / capability gate / no pick). */
+    skippedRoles: SkippedRole[];
 }
 
 const DEFAULT_PLAN_PROVIDERS = new Set(['minimax-code-cn', 'opencode-go', 'zhipu-coding-plan', 'kimi', 'openai-codex']);
 
-/** OPSX role → OMP role alias used in agent frontmatter `model: @<alias>`. */
-const ROLE_TO_OMP_ALIAS: Record<Role, string> = {
-    coder: 'smol',
-    reviewer: 'default',
-    planner: 'default',
-    'proposal-reviewer': 'default',
-};
 
-/** OMP role alias → expected tier (without the `@`). */
-const OMP_ROLE_TO_TIER: Record<string, string> = {
-    smol: 'mid',
-    default: 'high',
-    slow: 'top',
-};
 
 function roleValueToModelString(value: RoleValue): string | undefined {
     if (value.kind === 'auto') return undefined;
@@ -313,19 +321,39 @@ function synthPinnedResult(role: string, modelString: string | undefined): Selec
 export function buildDispatchPrompt(role: Role, task: string, selection: SelectionContext): string {
     const agent = AGENT_MAP[role];
     const sel = selection.selectorResults[role];
-    const modelHint = sel?.picked ? `${sel.picked.provider}/${sel.picked.id}` : selection.roleModels[role];
-    const parts = [`你的 opsx.${role} 已自动选择 model。`];
+    // auto roles (and omp-alias roles such as @slow) pass NO model: requestModel
+    // is the top-priority resolution layer and would shadow the frontmatter
+    // tier-role alias. Only concrete provider/model pins stay explicit.
+    const modelHint = dispatchModelHint(role, selection);
+    const parts = [`你的 opsx.${role} 模型由 role 自动解析。`];
     if (modelHint) parts.push(`请通过 task 工具调用 ${agent} 并指定 model="${modelHint}"。`);
-    else parts.push(`请通过 task 工具调用 ${agent}。`);
+    else parts.push(`请直接通过 task 工具调用 ${agent}（无需指定 model，模型按 role 自动解析）。`);
     if (sel?.decision) parts.push(`原因: ${sel.decision}`);
     parts.push('直接用内置工具实现。');
     return `请使用 task 工具委派给 ${agent}：\ntask(agent:"${agent}"${modelHint ? `, model:"${modelHint}"` : ''}, task:"${parts.join(' ')}\\n\\n${task}")`;
 }
 
+/**
+ * All model roles the host currently knows (10 built-in + custom roles from
+ * cycleOrder/modelRoles/modelTags). Host settings can throw during early
+ * startup or partial init; fall back to the built-in set rather than
+ * aborting selection (later recomputes pick up custom roles once ready).
+ */
+function safeGetKnownRoleIds(settings: Settings | null | undefined): string[] {
+    if (!settings) return [...MODEL_ROLE_IDS];
+    try {
+        return getKnownRoleIds(settings);
+    } catch (err) {
+        getLogger().warn(`[omp-opsx-addon] getKnownRoleIds failed; using built-in model roles only: ${err instanceof Error ? err.message : String(err)}`);
+        return [...MODEL_ROLE_IDS];
+    }
+}
+
 function computeSelectionSync(
     config: ResolvedOpsxConfig,
     models: Model<Api>[] | null,
     health: Map<string, ProviderHealth> | null,
+    knownRoleIds: string[],
     regionBlockedModels?: Set<string>,
     unreachableProviders?: Set<string>,
     availableByProvider?: Map<string, string[] | null>,
@@ -347,16 +375,23 @@ function computeSelectionSync(
     const selectorResults = {} as Record<Role, SelectorResult>;
     const roleModels = {} as Record<Role, string | undefined>;
     const roleConfigs = {} as Record<Role, string | undefined>;
+    const roleKind = {} as Record<Role, RoleValue['kind']>;
     const planSet = mergePlanProviders(config.planProviders);
     for (const role of OPSX_ROLES) {
         const value = config.roles[role];
-        roleConfigs[role] = value.kind === 'auto' ? ROLE_TO_OMP_ALIAS[role] : (roleValueToModelString(value) ?? '?');
+        roleKind[role] = value.kind;
+        // Config label shown in /pick-model choices markdown (`角色 (label)`):
+        // auto roles display the OMP tier-role alias; pinned roles the pin.
+        roleConfigs[role] = value.kind === 'auto'
+            ? ROLE_TO_OMP_ALIAS[role]
+            : (roleValueToModelString(value) ?? '?');
         const alias = `@${ROLE_TO_OMP_ALIAS[role]}`;
         if (value.kind === 'auto') {
             if (filteredModels && filteredModels.length > 0) {
                 const ompRole = ROLE_TO_OMP_ALIAS[role];
-                const tier = (config.roleTiers[role] ?? OMP_ROLE_TO_TIER[ompRole] ?? 'mid') as
-                    'top' | 'high' | 'mid' | 'low' | 'tiny';
+                const tier = (config.roleTiers[role]
+                    ?? (OMP_ROLE_TO_TIER as Record<string, TierName>)[ompRole]
+                    ?? 'mid') as TierName;
                 const roleTiers = { ...config.roleTiers, [role]: tier };
                 const result = selectAllRoles(
                     [role],
@@ -387,9 +422,56 @@ function computeSelectionSync(
             roleModels[role] = modelString?.includes('/') ? modelString : undefined;
         }
     }
-    return { selectorResults, roleModels, roleConfigs };
+    // change: pick-model-batch-all-roles — build the full-role session overlay:
+    // every host-known role (10 built-in + custom) follows one tier's picked
+    // model. mid/high reuse the opsx picks (coder/reviewer); tiny/low/top are
+    // supplemental picks over the same filtered candidate set; vision picks
+    // from image-capable candidates only. See design D2/D3.
+    let roleOverrides: Record<string, string> = {};
+    let skippedRoles: SkippedRole[] = [];
+    if (filteredModels && filteredModels.length > 0) {
+        const pickString = (r: SelectorResult): string | undefined =>
+            r.picked ? `${r.picked.provider}/${r.picked.id}` : undefined;
+        const tierPicks: Partial<Record<TierName, string | undefined>> = {
+            mid: pickString(selectorResults.coder),
+            high: pickString(selectorResults.reviewer),
+        };
+        for (const supplementalTier of ['tiny', 'low', 'top'] as const) {
+            const synthRole = `__tier_${supplementalTier}`;
+            const result = selectModel({
+                role: synthRole,
+                models: filteredModels,
+                roleTiers: { [synthRole]: supplementalTier },
+                tierOverrides: config.tierOverrides,
+                health: health ?? undefined,
+                allowlist: config.modelAllowlist,
+                planProviders: planSet,
+            });
+            tierPicks[supplementalTier] = pickString(result);
+        }
+        const capabilityPicks: Record<string, string | undefined> = {};
+        const visionModels = filteredModels.filter((m) => ROLE_CAPABILITY.vision(m));
+        if (visionModels.length > 0) {
+            const visionResult = selectModel({
+                role: 'vision',
+                models: visionModels,
+                roleTiers: { vision: 'high' },
+                tierOverrides: config.tierOverrides,
+                health: health ?? undefined,
+                allowlist: config.modelAllowlist,
+                planProviders: planSet,
+            });
+            capabilityPicks.vision = pickString(visionResult);
+        }
+        const plan = buildRoleOverridePlan(
+            { knownRoleIds, ompRoleTiers: config.ompRoleTiers, tierPicks, capabilityPicks },
+            (m) => getLogger().warn(m),
+        );
+        roleOverrides = plan.overrides;
+        skippedRoles = plan.skipped;
+    }
+    return { selectorResults, roleModels, roleConfigs, roleKind, roleOverrides, skippedRoles };
 }
-
 function formatModelChoicesMarkdown(sel: SelectionContext, suffix: string = '', primaryModel?: Model<Api>): string {
     const rows: string[] = [];
     let totalModelCount = 0;
@@ -480,6 +562,9 @@ const sessionUsageRecorder: SessionUsageRecorder = createSessionUsageRecorder({
 // ── plugin entry ────────────────────────────────────────────────────
 
 export default (pi: ExtensionAPI) => {
+    // Route plugin logging through the host logger (rolling file) instead of
+    // console.*, which would corrupt the TUI. Injected before any log path runs.
+    setOpsxLogger(pi.logger);
     // Runtime edit-variant pin for deepseek-v4-flash. The host hard-maps the
     // model to the sloppy §/» marker grammar (it misreads hashline ranges),
     // but the model repeatedly breaks sloppy control lines too — retry loops
@@ -491,7 +576,11 @@ export default (pi: ExtensionAPI) => {
     // host reads the merged view directly, making the file equivalent.
     applyEditVariantPin(pi, { 'deepseek-v4-flash': 'replace' });
     const directory = process.cwd();
-    const warn = (msg: string) => console.warn(msg);
+    const warn = (msg: string) => pi.logger.warn(msg);
+    // Roles known to the host at the moment of a (re)selection: computed per
+    // call so custom roles appearing after startup are covered on
+    // refresh/reset/selector/tick.
+    const currentKnownRoleIds = (): string[] => safeGetKnownRoleIds(pi.pi?.settings);
     const opsxConfig = readOpsxSettings(directory, warn);
     // Static orchestration rules — built once, reused every turn for cache stability.
     const STATIC_PROMPT = buildStaticPrompt();
@@ -582,6 +671,7 @@ export default (pi: ExtensionAPI) => {
                 effectiveConfig,
                 models,
                 health,
+                currentKnownRoleIds(),
                 regionBlockedModels,
                 reach.unreachable,
                 reach.availableByProvider,
@@ -595,30 +685,16 @@ export default (pi: ExtensionAPI) => {
         });
         return selectionPromise;
     };
-    // Push selector-picked models to native task subagents via task.agentModelOverrides.
-    // pi.pi.settings is the host-process Settings singleton (the require()'d copy in
-    // node_modules is a separate, uninitialized instance — writing to it was a no-op).
-    const applyAgentModelOverrides = (sel: SelectionContext, force = false): void => {
-        const settings = pi.pi?.settings;
-        if (!settings) {
-            warn('[omp-opsx-addon] pi.pi.settings unavailable; subagent model overrides skipped');
-            return;
-        }
-        const overrides: Record<string, string> = {};
-        for (const role of OPSX_ROLES) {
-            const picked = sel.selectorResults[role]?.picked;
-            if (picked) {
-                overrides[AGENT_MAP[role]] = `${picked.provider}/${picked.id}`;
-            }
-        }
-        if (Object.keys(overrides).length > 0 || force) {
-            settings.override('task.agentModelOverrides', overrides);
-            warn(
-                `[omp-opsx-addon] task.agentModelOverrides: ${Object.entries(overrides)
-                    .map(([k, v]) => `${k}=${v}`)
-                    .join(', ')}`,
-            );
-        }
+    // Apply selector picks by TIER to session-scoped OMP modelRoles (smol =
+    // coder/mid, default = reviewer/high), so every role-resolving agent —
+    // including built-in scout (smol) — follows selector/refresh/reset.
+    // Persisted per-agent pins are neutralized at runtime with empty strings.
+    // pi.pi.settings is the host-process Settings singleton (the require()'d
+    // copy in node_modules is a separate, uninitialized instance — writing to
+    // it was a no-op). This thin wrapper is the single call site the
+    // constrained-period tick-reselect path (auto-model-family) also uses.
+    const applyRoleModel = (sel: SelectionContext): void => {
+        applyRoleModelOverrides(pi.pi?.settings, sel, warn);
     };
 
     // ── shared usage poller + widget ──────────────────────────────
@@ -794,9 +870,37 @@ export default (pi: ExtensionAPI) => {
             // provider's aggregated consumption RATE (all sessions, main +
             // subagent via cache backflow), and re-renders the widget. It never
             // recomputes a selection, never applies overrides, never setModel.
+            const cfg = buildEffectiveConfig();
             const onTick = () => {
+                // Fire-and-forget status probe: do not block the tick.
+                const { placeholderIds, active } = resolveActiveProviders();
+                let models: { id: string; provider: string; baseUrl?: string }[] = [];
+                try {
+                    if (ctx.modelRegistry && typeof ctx.modelRegistry.getAvailable === 'function') {
+                        models = ctx.modelRegistry.getAvailable() as { id: string; provider: string; baseUrl?: string }[];
+                    }
+                } catch {
+                    if (ctx.modelRegistry && typeof ctx.modelRegistry.getAll === 'function') {
+                        try {
+                            models = ctx.modelRegistry.getAll() as { id: string; provider: string; baseUrl?: string }[];
+                        } catch {
+                            models = [];
+                        }
+                    }
+                }
+                void scheduleStatusProbes({
+                    placeholderIds,
+                    models,
+                    getApiKey,
+                    config: {
+                        enabled: cfg.status_probe_enabled,
+                        ttlMs: cfg.probe_ttl_ms,
+                        timeoutMs: cfg.probe_timeout_ms,
+                        excluded: cfg.excluded_providers,
+                    },
+                }).then((written) => { if (written > 0) render(); }).catch(() => {});
+
                 sessionUsageRecorder.flush();
-                const { active } = resolveActiveProviders();
                 // Waveform source = per-second consumption sequence (timestamped
                 // deltas aggregated across sessions). Sample EVERY elapsed second
                 // for EVERY active provider — zeros when a second had no
@@ -822,7 +926,6 @@ export default (pi: ExtensionAPI) => {
                 lastSampledSec = lastSec;
                 render();
             };
-            const cfg = buildEffectiveConfig();
             await startSharedPoller(auth, DIRECT_FETCHERS, getApiKey, {
                 onTick: claimsOwnership ? onTick : undefined,
                 ownsUi,
@@ -952,7 +1055,12 @@ export default (pi: ExtensionAPI) => {
             // This fallback call is intentionally NOT threaded with familyConstraint:
             // it prefers the cached `selection`, and the fallback passes models=null so
             // filterSelectableModels' family branch never runs — it is not a reselect path.
-            const sel = selection ?? computeSelectionSync(opsxConfig, null, null);
+            const sel = selection ?? computeSelectionSync(
+                opsxConfig,
+                null,
+                null,
+                safeGetKnownRoleIds(pi.pi?.settings),
+            );
             const changes = await changeScanner.scanChanges(directory, 'doing');
             // Layered injection: STATIC_PROMPT is byte-identical every turn → prefix cache
             // hit for [omp-base + skills + static]. Only the dynamic tail re-prefills.
@@ -966,17 +1074,14 @@ export default (pi: ExtensionAPI) => {
 
     pi.on('session_start', async (_event, ctx) => {
         try {
-            const pinned = (role: Role): string | undefined => {
-                const v = opsxConfig.roles[role];
-                if (v.kind === 'auto') return undefined;
-                return roleValueToModelString(v);
-            };
+            const frontmatter = (role: Role): string | undefined =>
+                frontmatterModel(role, opsxConfig.roles[role]);
             await installAgents(
                 directory,
-                pinned('coder'),
-                pinned('reviewer'),
-                pinned('planner'),
-                pinned('proposal-reviewer'),
+                frontmatter('coder'),
+                frontmatter('reviewer'),
+                frontmatter('planner'),
+                frontmatter('proposal-reviewer'),
             );
             warn('[omp-opsx-addon] agents ready (pick-model idle until /pick-model refresh)');
         } catch (e) {
@@ -992,7 +1097,7 @@ export default (pi: ExtensionAPI) => {
         const getApiKey = ctx.modelRegistry?.getApiKeyForProvider
             ? (provider: string) => ctx.modelRegistry.getApiKeyForProvider(provider)
             : undefined;
-        // 429/403 is the only observable exhaustion evidence for providers
+        // Provider exhaustion seen on the response/tool path; mark it locally
         // without a usage fetcher — record it in the process-local binary status
         // so the placeholder column reads 耗尽 (see lib/provider-status.ts).
         markExhausted(canonical);
@@ -1091,6 +1196,7 @@ export default (pi: ExtensionAPI) => {
                         effectiveConfig,
                         models,
                         health,
+                        currentKnownRoleIds(),
                         regionBlockedModels,
                         reach.unreachable,
                         reach.availableByProvider,
@@ -1126,7 +1232,7 @@ export default (pi: ExtensionAPI) => {
                         }
                     }
                     selection = freshSel;
-                    applyAgentModelOverrides(freshSel);
+                    applyRoleModel(freshSel);
                     if (changes.length > 0) {
                         pi.sendMessage({ customType: 'pick-model', content: `✅ 模型已刷新:\n${changes.join('\n')}`, display: true }, { triggerTurn: false });
                     } else {
@@ -1153,6 +1259,7 @@ export default (pi: ExtensionAPI) => {
                         effectiveConfig,
                         models,
                         health,
+                        currentKnownRoleIds(),
                         regionBlockedModels,
                         reach.unreachable,
                         reach.availableByProvider,
@@ -1177,7 +1284,7 @@ export default (pi: ExtensionAPI) => {
                     if (newPrimary) await pi.setModel(newPrimary);
                     selection = sel;
                     selectionHealthKey = buildSelectionHealthKey(health, reach, familyConstraint);
-                    applyAgentModelOverrides(sel, true);
+                    applyRoleModel(sel);
                     pi.sendMessage({
                         customType: 'pick-model',
                         content: changes.length > 0
@@ -1237,6 +1344,7 @@ export default (pi: ExtensionAPI) => {
                         effectiveConfig,
                         models,
                         health,
+                        currentKnownRoleIds(),
                         regionBlockedModels,
                         reach.unreachable,
                         reach.availableByProvider,
@@ -1296,7 +1404,7 @@ export default (pi: ExtensionAPI) => {
                     if (newPrimary) await pi.setModel(newPrimary);
                     selection = sel;
                     selectionHealthKey = buildSelectionHealthKey(health, reach, familyConstraint);
-                    applyAgentModelOverrides(sel);
+                    applyRoleModel(sel);
                     const content = `✅ 已切换 selector 约束 (${formatFamilyConstraint(familyConstraint)}):\n${changes.join('\n')}${hint ? `\n${hint}` : ''}`;
                     pi.sendMessage({
                         customType: 'pick-model',
@@ -1351,4 +1459,14 @@ export default (pi: ExtensionAPI) => {
         if (selection) return selection;
         return ensureSelection(ctx);
     }
+
+    // Cross-broker project-scoped pipe core: registers opsx_pipe_list /
+    // _send / _recv / _wait and starts presence heartbeat + GC on
+    // session_start (managed timers inside lib/pipe-core).
+    registerPipeCore(pi);
+
+    // Cross-broker push/injector: watches the local mbox slot and injects
+    // inbound pipe messages as custom (opsx-pipe) turns; /opsx-pipe mute
+    // toggles the stop-injection flag (managed timers inside lib/pipe-push).
+    registerPipePush(pi);
 };

package/lib/agent-defs.ts

@@ -5,7 +5,7 @@ const MARKER = '<!-- @genee/omp-opsx-addon -->';
 const CODE_REVIEWER_MD = (model?: string) => `---
 name: code-reviewer
 description: OpenSpec 代码审查 agent，审查代码实现并执行全局验证
-tools: read, bash, glob, grep${model ? `\nmodel: ${model}` : ''}
+tools: read, bash, glob, grep${model ? `\nmodel: "${model}"` : ''}
 ---
 
 你是一位资深代码审查员。你根据 OpenSpec 提案和设计文档审查代码实现，并在审阅的同时执行最后一次全局验证。
@@ -14,6 +14,12 @@ tools: read, bash, glob, grep${model ? `\nmodel: ${model}` : ''}
 1. 从 prompt 或上下文确定要审查的变更
 2. 读取 proposal、design 和 tasks 文件
 3. 运行 \`git diff HEAD~1\` 或 \`git diff --stat\` 查看改动
+## scratchpad.md 共享缓存
+- 审查前 MUST 先读 \`openspec/changes/<name>/scratchpad.md\`（若存在），只读不改写（工具集无 write/edit）。
+- 以「调研与设计」+「实现探索」两区累计的涉及文件 \`path:line\` 集合为代码审查与增量验证范围：Tier 1（typecheck/lint）与 Tier 3（E2E，如适用）聚焦涉及文件改动面；Tier 2 冒烟套件仍全量执行项目现有测试套件。
+- 无 scratchpad.md 时回退：从 proposal/design/tasks 确定审查范围。
+- 识别 \`- [R<n> coder] supersede:\` 条目：以紧随其后的新结论为权威，旧 \`path:line\` 不再作为验证范围；只读不改写。
+- 发现 scratchpad.md 结论与代码现状不符时，作为 P0/P1 审查发现发回，不直接改写。
 
 ## 审查维度
 1. **规范遵循**：是否精确实现了 proposal/design/tasks 定义的内容？有无缺失或偏离？
@@ -65,7 +71,7 @@ ${MARKER}
 const PROPOSAL_REVIEWER_MD = (model?: string) => `---
 name: proposal-reviewer
 description: OpenSpec 提案审查 agent，审查提案质量
-tools: read, bash, glob, grep${model ? `\nmodel: ${model}` : ''}
+tools: read, bash, glob, grep${model ? `\nmodel: "${model}"` : ''}
 ---
 
 你是一位资深需求审查员。你审查 OpenSpec 提案的完整性和质量。
@@ -73,6 +79,11 @@ tools: read, bash, glob, grep${model ? `\nmodel: ${model}` : ''}
 ## 启动
 1. 从 prompt 或上下文确定要审查的提案名称
 2. 读取 proposal.md、design.md（如果存在）
+## scratchpad.md 共享缓存
+- 审查前 MUST 先读 \`openspec/changes/<name>/scratchpad.md\`（若存在），复用其中调研结论与涉及文件，避免重复 read/grep。
+- 只读，不改写 scratchpad.md；你的工具集不含 write/edit，物理上无法写入。
+- 识别 \`- [R<n> coder] supersede:\` 条目：以紧随其后的新结论为权威，旧结论不再作为调研依据；只读不改写。
+- 发现的 P0/P1 与关注点写入审查报告，由主 agent 中转回流，不直接写 scratchpad.md。
 
 ## 审查维度
 1. **完整性**：Why/What/Capabilities/Impact 是否齐全？有无缺失章节？
@@ -112,7 +123,7 @@ ${MARKER}
 const CODER_MD = (model?: string) => `---
 name: coder
 description: OpenSpec 变更实现 agent，同步 tasks.md 进度
-tools: read, write, edit, bash, glob, grep, todo${model ? `\nmodel: ${model}` : ''}
+tools: read, write, edit, bash, glob, grep, todo${model ? `\nmodel: "${model}"` : ''}
 skill: openspec-apply-change
 ---
 
@@ -131,6 +142,19 @@ skill: openspec-apply-change
 - 代码全部完成后将所有未完成项标记为 \`- [x]\`，在 ACTION 报告中说明变更已全部实现
 - 不修改 \`proposal.md\`、\`design.md\` 或 \`.openspec.yaml\`
 - 直接用 read/write/edit/bash 等内置工具实现；不要尝试调用 task 二次委派。
+## scratchpad.md 共享缓存
+- 开工前 MUST 读 \`openspec/changes/<name>/scratchpad.md\`（若存在），复用已记录结论，禁止重复探索。
+- 交付前 MUST 将本轮新探索结论 append 到「实现探索」区（关键符号/数据流、新增涉及文件 \`path:line\`、验证/构建命令、已排除假设），标注 \`- [R<n> coder] <结论>\`。
+- 收到主 agent 中转的 code-reviewer P0/P1 关注点时，开工时先将关注点 append 进「代码审查范围」区，再开始修复。
+- 后续轮次只做增量：仅探索未记录的文件/符号/假设，不重复 read/grep 已记录内容；append-only，不得改写他人结论。
+
+## scratchpad.md 与代码不一致时的两档处置
+执行中发现代码现实与 scratchpad.md 记录不一致时，按两档客观判据处置；判据仅为「偏差是否影响任何 task 的前提或产出定义」，禁止主观估量「问题大小」：
+- **档一：事实快照过期**——偏差不影响任何 task 的前提或产出定义（纯探索性信息：路径 / 行号 / 符号 / 命令漂移）。处置：继续执行当前任务，不终止；在「实现探索」区 append supersede 修正。
+- **档二：契约动摇**——偏差导致 tasks / proposal / design / specs 的有效性存疑（前提不成立、产出定义变、代码现状与设计决策冲突）。处置：立即停止实现，输出 STATUS: blocked（无 SESSION）并说明冲突点，交由主 agent 裁决（改提案 / 确认「现状即新设计」/ 开新 change）。
+- supersede 标注格式：\`- [R<n> coder] supersede: <旧结论摘要>\`，随后一行以 \`- [R<n> coder]\` 标注新结论；两条均落「实现探索」分区，旧结论保留（append-only），不删除。
+- 交付摘要 SUMMARY 义务：本轮发生过 supersede 时，输出格式中的 SUMMARY 行 MUST 提及本次 supersede 清单。
+
 ## 验证（交付门槛）
 - 交付前必须跑过 **scoped 到本次改动面** 的 lint、typecheck 与针对性单测（proposal 约定的测试必须通过）；任一未通过不得交付，先修到通过再标记 ACTION: REVIEW_REQUIRED。
 - 项目级全量校验（全仓库 lint/typecheck/\`bun test\`）不属于自验证门槛：若失败可归因于并发 sibling 的半成品改动（与本改动无关），把失败连同「已排查与本改动无关」的证据作为上下文上报（交付摘要中注明），不要被其阻塞；最终由 code-reviewer 的全局验证兜底确认。
@@ -148,6 +172,7 @@ ACTION: REVIEW_REQUIRED
 CHANGE: <change-name 或 "general">
 STATUS: success | partial | blocked
 SESSION: <session_name>（仅 STATUS: blocked 且需 resume 时填写）
+SUMMARY: <交付摘要；若本轮有 supersede，必须包含「supersede: <清单>」>
 TASKS: N/M complete
 FILES: <逗号分隔的修改/创建文件列表>
 ---
@@ -159,7 +184,7 @@ ${MARKER}
 const PLANNER_MD = (model?: string) => `---
 name: planner
 description: OpenSpec 提案规划 agent
-tools: read, write, edit, bash, glob, grep, todo${model ? `\nmodel: ${model}` : ''}\nskill: openspec-propose
+tools: read, write, edit, bash, glob, grep, todo${model ? `\nmodel: "${model}"` : ''}\nskill: openspec-propose
 ---
 
 你是一个 OpenSpec 提案规划 agent。负责创建和更新 OpenSpec 变更提案文档。
@@ -173,6 +198,17 @@ tools: read, write, edit, bash, glob, grep, todo${model ? `\nmodel: ${model}` :
 ## 工作范围
 - **只负责提案文档**：proposal.md、design.md、tasks.md、specs/（openspec/changes/ 目录下）
 - 直接用内置工具；不要尝试调用 task 二次委派。
+## scratchpad.md 共享缓存
+变更目录下维护 \`openspec/changes/<name>/scratchpad.md\` 作四角色共享探索缓存（与 proposal.md/design.md/tasks.md 同级），固定四阶段分区：
+- \`## 调研与设计\`：调研结论、涉及文件（\`path:line\`）、已排除方案
+- \`## 提案审查关注点\`：proposal-reviewer 审查报告中的 P0/P1 与关注点（经主 agent 中转回流）
+- \`## 实现探索\`：coder 每轮 append 的关键符号/数据流、新增涉及文件、验证/构建命令、已排除假设
+- \`## 代码审查范围\`：code-reviewer 审查报告中的 P0/P1 与验证范围结论（经主 agent 中转回流）
+规则：
+- **出提案时 MUST 创建** \`openspec/changes/<name>/scratchpad.md\` 并写入四阶段骨架，预填「调研与设计」初始骨架：调研结论、涉及文件、已排除方案。
+- 后续轮次修改提案时，先读回 scratchpad.md：将 proposal-reviewer 关注点 append 进「提案审查关注点」区，新调研结论增量 append 进「调研与设计」区。
+- 条目以 \`- [R<n> planner] <结论>\` 标注轮次与角色；append-only，不得改写或删除他人结论。
+- 读回 scratchpad.md 时，以最新 supersede 条目为权威（识别 \`- [R<n> coder] supersede:\` 标记，其后的新结论优先于旧结论）。
 
 ## 提案拆分
 - 接大需求先评估契约边界:能拆则拆成多个小变更,先输出拆分建议(契约边界+提案清单)待主 agent 确认后再开写。