@aiwayds/dsh-dcp 0.9.0 → 0.10.0

package/README.en.md

@@ -137,7 +137,7 @@ Removing the package without the reverse step leaves the mount pointing at the v
 
 Settable: `dedup`, `purgeErrors`, `maxItems`, `maxItemChars`,
 `maxSummaryTokens`, `language`, `tokenEstimate`, `thresholdRatio`,
-`roundInterval`, `notice`.
+`roundInterval`, `notice`, `onModelSwitch`, `modelSwitchMinTokens`.
 
 The `/dcp` status also lists every session that has compacted (subagents
 included): `per-session: session-1 (2 compactions, ~444 tokens), child
@@ -153,9 +153,11 @@ for the rest) so the status stays one line.
 | Pressure | before every step | tokens ≥ `thresholdRatio` (inherited upstream default 0.8; this plugin's bundle mounts 0.7 — see config table) × context window |
 | Overflow recovery | on a provider context-window error | inherited |
 | **Round interval** | every `roundInterval` assistant messages | added by this plugin; one round = one LLM roundtrip (each tool-iteration response counts, so one-shot subagents trigger too). **Default 50**: first compaction after message 50, then every 50 more (100, 150, …); any compaction (pressure included) restarts the clock. Fires at the first idle boundary after the count is reached (below the pressure threshold too). `0` disables; requires the default `auto: true` |
+| **Model switch** | the session's effective provider/model route changes | added by this plugin (`onModelSwitch`). Default `notice`: appends one row suggesting `/dcp compact` first to shadow the old model's history and save tokens; `auto` compacts at the session's next idle boundary; `off` disables. Two gates: switches within 10 assistant messages of the last compaction are ignored (nothing stale to shadow), and switches while the context is below `modelSwitchMinTokens` (default 32768, `0` disables this gate) are ignored (not enough to be worth shadowing); `auto` requires the default `auto: true`, otherwise it degrades to `notice` |
 | Manual | `/dcp compact`, `/compact` | anytime |
 
-- **Subagents are covered**: in-process subagents (including continuable and one-shot children) dispatch through the same events, so pressure/overflow/round triggers count and fire per child session independently. The round trigger counts assistant messages, so a one-shot subagent whose whole run is a single turn (many tool iterations) triggers too.
+- **Subagents are covered**: in-process subagents (including continuable and one-shot children) dispatch through the same events, so pressure/overflow/round/model-switch triggers count and fire per child session independently. The round trigger counts assistant messages, so a one-shot subagent whose whole run is a single turn (many tool iterations) triggers too.
+- **How model-switch detection works**: the per-request `request/context` routing snapshot is folded per session (a provider or model change alone counts as a switch), covering every switch entry point — TUI `/model`, web clients, changed default-model settings. A session's first observed request only seeds the baseline. `notice: false` silences the compaction rows only; the switch row is controlled by `onModelSwitch` independently. The size floor is measured by the host token meter (`measure().surfaceTokens`) and fails open when unavailable.
 - **Visibility**: after every trigger event a one-line notice row (`dcp: compacted N history items (~X tokens, trigger)`) is appended to the session; frontends render it as a collapsed row. Note the row also rides the model request context (~15–25 tokens per compaction), and it is **on by default since 0.4.0** — disable with `notice: false`. `/dcp` stats count every committed region (a pressure retry loop may commit several).
 
 ## Configuration
@@ -166,6 +168,8 @@ All optional, defaults work out of the box:
 |---|---|---|
 | `thresholdRatio` | 0.8 | pressure trigger (inherited upstream compaction-basic default 0.8; this plugin's bundle patch mounts 0.7, recommended for CJK-heavy sessions) |
 | `roundInterval` | 50 | compact every N assistant messages (one LLM roundtrip) (0 disables). Default 50: 50, 100, 150… — the clock restarts after every compaction |
+| `onModelSwitch` | `notice` | after a model switch: `notice` suggests `/dcp compact` (default); `auto` compacts at the next idle boundary; `off` disables |
+| `modelSwitchMinTokens` | 32768 | minimum priced context size (measured by the host token meter) for a model switch to be announced; `0` disables this gate. 32k default ≈ the post-compaction baseline (~16% of the window) plus some real growth |
 | `notice` | `true` | append the one-line compaction notice to the session |
 | `language` | `zh` | summary language; `zh` also enables Chinese error/"待办：" detection |
 | `tokenEstimate` | `cjk` | CJK (zh/ja/ko/full-width) at ~2 chars/token; `ascii` matches the host |
@@ -178,7 +182,7 @@ All optional, defaults work out of the box:
 
 ## Bundled skill
 
-The package registers a `dsh-dcp` skill (`skills/dsh-dcp/SKILL.md`, served via
+The package registers a `dsh-dcp-config` skill (`skills/dsh-dcp-config/SKILL.md`, served via
 `ctx.skills.registerProvider`): ask the agent to tune compaction, configure dcp,
 or debug compaction behavior and the guide loads automatically — it carries an
 interactive `ask_user_question` tuning wizard (collect the expectation first,

package/README.md

@@ -114,7 +114,7 @@ npx dsh-dcp-setup --remove /path/to/cordis.patch.yml
 | `/dcp compact` | 立即压缩（零 LLM） |
 | `/dcp set <k> <v>` | 会话内调参，并提示如何持久化 |
 
-可调键：`dedup`、`purgeErrors`、`maxItems`、`maxItemChars`、`maxSummaryTokens`、`language`、`tokenEstimate`、`thresholdRatio`、`roundInterval`、`notice`。
+可调键：`dedup`、`purgeErrors`、`maxItems`、`maxItemChars`、`maxSummaryTokens`、`language`、`tokenEstimate`、`thresholdRatio`、`roundInterval`、`notice`、`onModelSwitch`、`modelSwitchMinTokens`。
 
 `/dcp` 状态还会列出每个发生过压缩的会话（per-session 概览，含子代理），例如 `per-session: session-1 (2 compactions, ~444 tokens), child (1 compaction, ~22 tokens)`。压缩按会话独立计数；已销毁的会话（含 one-shot 子代理）自动从概览消失；列表封顶一行（最多前 10 个会话，超出显示 `+N more`）。
 
@@ -125,9 +125,11 @@ npx dsh-dcp-setup --remove /path/to/cordis.patch.yml
 | 压力触发 | 每步请求前 | token ≥ `thresholdRatio`（继承上游默认 0.8；本插件 bundle 挂载默认 0.7，见配置表）× 上下文窗口 |
 | 溢出恢复 | 模型报 context 超限时 | 继承官方 |
 | **轮数触发** | 会话每收到 `roundInterval` 条 assistant message | 本插件新增；一条 = 一次 LLM 往返（每轮工具迭代各算一条，one-shot 子代理也能触发）。**默认 50**：第 50 条后触发第一次，之后每 50 条一次（100、150……）；任何一次压缩（含压力触发）都会重置轮数时钟。到达条数后的第一个空闲点触发（阈值之下也压）。`0` 关闭；需保持 `auto: true`（默认开） |
+| **模型切换** | 会话实际路由的 provider/model 变化时 | 本插件新增（`onModelSwitch`）。默认 `notice`：追加一行提醒"建议先执行 `/dcp compact` 压缩旧模型历史，节省 token"；`auto` 在该会话下一个空闲点自动压缩；`off` 关闭。两道门控：距上次压缩不足 10 条 assistant message 忽略（没有旧账可甩），上下文不足 `modelSwitchMinTokens`（默认 32768，`0` 关闭该门）忽略（不够甩的量）；`auto` 需保持 `auto: true`（默认开），否则降级为 `notice` |
 | 手动 | `/dcp compact`、`/compact` | 随时可用 |
 
-- **subagent 同样生效**：进程内 subagent（含 continuable 与 one-shot 子代理）走同一套事件分发，压力/溢出/轮数触发对子会话独立计数、独立触发。轮数触发按 assistant message 计数，所以全程只有 1 个 turn 的 one-shot 子代理（多次工具迭代）也能触发。
+- **subagent 同样生效**：进程内 subagent（含 continuable 与 one-shot 子代理）走同一套事件分发，压力/溢出/轮数/模型切换对子会话独立计数、独立触发。轮数触发按 assistant message 计数，所以全程只有 1 个 turn 的 one-shot 子代理（多次工具迭代）也能触发。
+- **模型切换检测原理**：折叠每请求的 `request/context` 路由快照（provider 或 model 任一变化即判定切换），覆盖所有切换入口（TUI `/model`、Web 客户端、默认模型设置变更）；会话首个请求只播种基线不告警。`notice: false` 只关压缩通知行，模型切换提醒行由 `onModelSwitch` 独立控制。上下文下限按宿主 tokenMeter 的实测计价（`measure().surfaceTokens`），测不到时 fail-open（只留轮数门控）。
 - **压缩可见性**：每次压缩成功后，会话里追加一行 `dcp: 已压缩 N 条历史（约 X tokens，触发方式）` 通知行（前端渲染为折叠行）。注意该行也会作为上下文随请求发给模型（每次压缩约 15–25 tokens），且 **0.4.0 起默认开启**；`notice: false` 可关闭。`/dcp` 的 stats 持续累计（压力触发的多次 region 提交各计一次）。
 
 ## 配置
@@ -138,6 +140,8 @@ npx dsh-dcp-setup --remove /path/to/cordis.patch.yml
 |---|---|---|
 | `thresholdRatio` | 0.8 | 压力触发阈值（继承上游 compaction-basic 默认 0.8；本插件 bundle patch 挂载时默认 0.7，中文场景建议 0.7） |
 | `roundInterval` | 50 | 每 N 条 assistant message（一次 LLM 往返）触发一次压缩（0 关闭）。默认 50：50、100、150……每次压缩后重数 |
+| `onModelSwitch` | `notice` | 模型切换后：`notice` 提醒执行 `/dcp compact`（默认）；`auto` 下一个空闲点自动压缩；`off` 关闭 |
+| `modelSwitchMinTokens` | 32768 | 模型切换提醒/自动压缩的上下文下限（按宿主 tokenMeter 实测计价）：不足则忽略该次切换；`0` 关闭此门。默认 32k ≈ 压缩后基线（~16% 窗口）之上再涨一截才有得甩 |
 | `notice` | `true` | 压缩后在会话中追加一行通知 |
 | `language` | `zh` | 摘要语言；`zh` 额外识别中文报错和"待办：" |
 | `tokenEstimate` | `cjk` | CJK（中/日/韩/全角）按 ~2 字符/token 计价；`ascii` 与宿主一致 |
@@ -150,7 +154,7 @@ npx dsh-dcp-setup --remove /path/to/cordis.patch.yml
 
 ## 内置技能 / Bundled skill
 
-插件随包注册了 `dsh-dcp` skill（`skills/dsh-dcp/SKILL.md`，经 `ctx.skills.registerProvider`）：在会话里让 agent 调压缩、配置 dcp 或排查压缩行为时，指南自动加载——内含 ask_user_question 交互式调参向导（先问期望再映射到具体键）与 cordis.patch.yml 挂载块 `config:` 段的持久化写法，无需翻文档。
+插件随包注册了 `dsh-dcp-config` skill（`skills/dsh-dcp-config/SKILL.md`，经 `ctx.skills.registerProvider`）：在会话里让 agent 调压缩、配置 dcp 或排查压缩行为时，指南自动加载——内含 ask_user_question 交互式调参向导（先问期望再映射到具体键）与 cordis.patch.yml 挂载块 `config:` 段的持久化写法，无需翻文档。
 
 ## 设计参考
 

package/lib/command.js

@@ -14,7 +14,8 @@ const USAGE = `Usage:
   /dcp compact        compact now (deterministic, no LLM call)
   /dcp set <k> <v>    adjust a knob for this session (dedup, purgeErrors,
                       maxItems, maxItemChars, maxSummaryTokens, language,
-                      tokenEstimate, thresholdRatio, roundInterval, notice)`
+                      tokenEstimate, thresholdRatio, roundInterval, notice,
+                      onModelSwitch, modelSwitchMinTokens)`
 
 const FAILURE_TEXT = Object.freeze({
   busy: 'Compaction is unavailable because this process has an active compaction, or the agent is not idle.',
@@ -53,6 +54,11 @@ function applySet(engine, key, rawValue) {
     engine.dcp.tokenEstimate = value
     return `tokenEstimate = ${value} (this session)`
   }
+  if (kind === 'model-switch-mode') {
+    if (value !== 'off' && value !== 'notice' && value !== 'auto') return 'onModelSwitch expects off/notice/auto'
+    engine.dcp.onModelSwitch = value
+    return `onModelSwitch = ${value} (this session)`
+  }
   const numeric = Number(rawValue)
   if (!Number.isFinite(numeric)) return `${key} expects a number`
   if (kind === 'ratio') {
@@ -78,7 +84,7 @@ function statusText(engine, version) {
   const stats = engine.dcpStats
   const lines = [
     `dsh-dcp ${version} — deterministic compaction backend (zero LLM summarization calls)`,
-    `config: dedup=${engine.dcp.dedup} purgeErrors=${engine.dcp.purgeErrors} maxItems=${engine.dcp.maxItems} maxItemChars=${engine.dcp.maxItemChars} maxSummaryTokens=${engine.dcp.maxSummaryTokens} language=${engine.dcp.language} tokenEstimate=${engine.dcp.tokenEstimate} protectedTools=[${engine.dcp.protectedTools.join(', ')}] thresholdRatio=${engine.config.thresholdRatio} roundInterval=${engine.dcp.roundInterval}${engine.dcp.roundInterval > 0 ? '' : ' (off)'} notice=${engine.dcp.notice}`,
+    `config: dedup=${engine.dcp.dedup} purgeErrors=${engine.dcp.purgeErrors} maxItems=${engine.dcp.maxItems} maxItemChars=${engine.dcp.maxItemChars} maxSummaryTokens=${engine.dcp.maxSummaryTokens} language=${engine.dcp.language} tokenEstimate=${engine.dcp.tokenEstimate} protectedTools=[${engine.dcp.protectedTools.join(', ')}] thresholdRatio=${engine.config.thresholdRatio} roundInterval=${engine.dcp.roundInterval}${engine.dcp.roundInterval > 0 ? '' : ' (off)'} notice=${engine.dcp.notice} onModelSwitch=${engine.dcp.onModelSwitch}${engine.dcp.onModelSwitch === 'off' ? '' : ` minTokens=${engine.dcp.modelSwitchMinTokens}${engine.dcp.modelSwitchMinTokens > 0 ? '' : ' (off)'}`}`,
     `stats: ${stats.compactions} compaction${stats.compactions === 1 ? '' : 's'}, ~${stats.shadowedTokens} tokens shadowed, ${stats.compactions} LLM summary call${stats.compactions === 1 ? '' : 's'} avoided`,
   ]
   // Per-session dimension: one compacted session per entry, in store

package/lib/config.js

@@ -18,6 +18,8 @@ export const DCP_CONFIG_KEYS = [
   'protectedTools',
   'roundInterval',
   'notice',
+  'onModelSwitch',
+  'modelSwitchMinTokens',
 ]
 
 /** compaction-basic policy keys forwarded to the parent engine verbatim. */
@@ -45,6 +47,8 @@ const DEFAULTS = Object.freeze({
   protectedTools: Object.freeze(['write', 'edit', 'apply_patch']),
   roundInterval: 50,
   notice: true,
+  onModelSwitch: 'notice',
+  modelSwitchMinTokens: 32768,
 })
 
 /**
@@ -75,7 +79,7 @@ export function splitConfig(config = {}) {
  * Validate and resolve dcp defaults.
  *
  * @param {Record<string, unknown>} raw - the dcp half of {@link splitConfig}.
- * @returns {Readonly<{dedup: boolean, purgeErrors: boolean, maxItems: number, maxItemChars: number, maxSummaryTokens: number, language: 'en'|'zh', tokenEstimate: 'cjk'|'ascii', protectedTools: readonly string[], roundInterval: number, notice: boolean}>}
+ * @returns {Readonly<{dedup: boolean, purgeErrors: boolean, maxItems: number, maxItemChars: number, maxSummaryTokens: number, language: 'en'|'zh', tokenEstimate: 'cjk'|'ascii', protectedTools: readonly string[], roundInterval: number, notice: boolean, onModelSwitch: 'off'|'notice'|'auto', modelSwitchMinTokens: number}>}
  */
 export function resolveDcpConfig(raw = {}) {
   if (raw.dedup !== undefined && typeof raw.dedup !== 'boolean') {
@@ -110,6 +114,15 @@ export function resolveDcpConfig(raw = {}) {
   if (raw.notice !== undefined && typeof raw.notice !== 'boolean') {
     throw new Error('DcpConfig: notice must be a boolean')
   }
+  if (raw.onModelSwitch !== undefined && raw.onModelSwitch !== 'off' && raw.onModelSwitch !== 'notice' && raw.onModelSwitch !== 'auto') {
+    throw new Error('DcpConfig: onModelSwitch must be "off", "notice", or "auto"')
+  }
+  if (raw.modelSwitchMinTokens !== undefined) {
+    const value = raw.modelSwitchMinTokens
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+      throw new Error('DcpConfig: modelSwitchMinTokens must be a non-negative integer (0 disables the size gate)')
+    }
+  }
   return Object.freeze({ ...DEFAULTS, ...raw })
 }
 
@@ -125,4 +138,6 @@ export const RUNTIME_SETTABLE = Object.freeze({
   thresholdRatio: 'ratio',
   roundInterval: 'nonnegative-integer',
   notice: 'boolean',
+  onModelSwitch: 'model-switch-mode',
+  modelSwitchMinTokens: 'nonnegative-integer',
 })

package/lib/index.js

@@ -21,6 +21,7 @@
  *   config:
  *     thresholdRatio: 0.7   # optional; 0.7 = this bundle patch's mount value, package default is 0.8; every key is optional
  *     roundInterval: 100    # optional; also compact every N assistant messages, one per LLM roundtrip (default 50)
+ *     onModelSwitch: auto   # optional; after a model switch: notice (default) | auto-compact | off
  * ```
  *
  * @module dsh-dcp
@@ -33,7 +34,7 @@ import { BasicCompactionEngine } from '@deepseek-ai/dsh-compaction-basic'
 import { boundContextSummary, createUserMessage } from '@deepseek-ai/dsh-llm'
 import { ManualCompactionError } from '@deepseek-ai/dsh-compaction'
 import { splitConfig, resolveDcpConfig } from './config.js'
-import { summarizeDeterministically, noticeText } from './summarizer.js'
+import { summarizeDeterministically, noticeText, modelSwitchNoticeText } from './summarizer.js'
 import { registerDcpCommand } from './command.js'
 import { skillProvider } from './skill.js'
 
@@ -61,11 +62,29 @@ const kRounds = Symbol('dsh-dcp.rounds')
 const kTriggerLabels = Symbol('dsh-dcp.triggerLabels')
 const kRoundInFlight = Symbol('dsh-dcp.roundInFlight')
 const kSessionStats = Symbol('dsh-dcp.sessionStats')
+const kRoutes = Symbol('dsh-dcp.routes')
+const kSwitchPending = Symbol('dsh-dcp.switchPending')
+const kRegisterAssistantMessageCounter = Symbol('dsh-dcp.registerAssistantMessageCounter')
 const kRegisterRoundTrigger = Symbol('dsh-dcp.registerRoundTrigger')
 const kMaybeRoundCompact = Symbol('dsh-dcp.maybeRoundCompact')
+const kRegisterModelSwitchWatch = Symbol('dsh-dcp.registerModelSwitchWatch')
+const kMaybeOnModelSwitch = Symbol('dsh-dcp.maybeOnModelSwitch')
+const kAttemptSwitchCompaction = Symbol('dsh-dcp.attemptSwitchCompaction')
 const kRecordStats = Symbol('dsh-dcp.recordStats')
 const kRecordSessionStats = Symbol('dsh-dcp.recordSessionStats')
 const kAppendNotice = Symbol('dsh-dcp.appendNotice')
+const kAppendSwitchNotice = Symbol('dsh-dcp.appendSwitchNotice')
+const kMeetsMinTokens = Symbol('dsh-dcp.meetsMinTokens')
+
+/**
+ * A model switch detected fewer than this many assistant messages after the
+ * session's last committed compaction is ignored (both notice and auto
+ * modes): a switch right after a compaction has no stale history to shadow,
+ * so prompting (or compacting again) would only add noise and rewrites.
+ * Deliberately not a config key — it is a guard rail, not a user-intent knob.
+ * The token-size counterpart is the user-tunable `modelSwitchMinTokens`.
+ */
+const MODEL_SWITCH_MIN_ROUNDS = 10
 
 /**
  * Deterministic compaction engine: `summarize()` overridden, everything else
@@ -112,6 +131,8 @@ export class DcpEngine extends BasicCompactionEngine {
     protectedTools: z.array(z.string()),
     roundInterval: z.number().step(1).min(0),
     notice: z.boolean(),
+    onModelSwitch: z.string(),
+    modelSwitchMinTokens: z.number().step(1).min(0),
   })
 
   /** Resolved dcp knobs; mutable at runtime through `/dcp set`. */
@@ -138,6 +159,10 @@ export class DcpEngine extends BasicCompactionEngine {
     this[kRoundInFlight] = new WeakSet()
     /** Per-session compaction records for `/dcp` (weak so disposed sessions drop out). */
     this[kSessionStats] = new WeakMap()
+    /** Per-session last routed `{provider, model}` for model-switch detection. */
+    this[kRoutes] = new WeakMap()
+    /** Sessions with a model-switch auto compaction waiting for an idle boundary. */
+    this[kSwitchPending] = new WeakSet()
     this.dcp = { ...resolveDcpConfig(dcp) }
     this.dcpStats = { compactions: 0, shadowedTokens: 0, lastAt: null }
     this.pluginPath = fileURLToPath(import.meta.url)
@@ -154,30 +179,41 @@ export class DcpEngine extends BasicCompactionEngine {
     ctx.effect(function* () {
       yield registerDcpCommand(ctx, engine, VERSION)
     }, 'dsh-dcp /dcp command lifecycle')
+    // The counter is unconditional: the round trigger reads it, and so does
+    // the model-switch recency gate. Counting also continues while the round
+    // trigger is disabled (`roundInterval: 0`), so `/dcp set roundInterval N`
+    // can arm it mid-session and the switch gate stays meaningful.
+    this[kRegisterAssistantMessageCounter]()
     if (this.config.auto) this[kRegisterRoundTrigger]()
+    this[kRegisterModelSwitchWatch]()
   }
 
   /**
-   * Round-interval trigger: count assistant messages (one per LLM roundtrip)
-   * per session and, once the configured `roundInterval` is reached, compact
-   * at the agent's next idle boundary through the manual-compaction seam
-   * (`compactNow`). In-process subagents run through the same session/event
-   * and agent/status dispatch, so continuable children are covered exactly
-   * like the top-level session — and because one-shot subagents emit many
-   * assistant messages inside a single turn, they now trigger too.
+   * Unconditional per-session assistant-message counting: every assembled
+   * assistant message is one completed LLM roundtrip, so this WeakMap is the
+   * "rounds since the session's last committed compaction" clock shared by
+   * the round trigger and the model-switch recency gate.
    */
-  [kRegisterRoundTrigger]() {
+  [kRegisterAssistantMessageCounter]() {
     const { ctx } = this
     ctx.on('session/event', (session, event) => {
-      // Counting is skipped while disabled, but the listener stays registered
-      // so `/dcp set roundInterval N` can arm it again at runtime.
-      if (!this.dcp.roundInterval) return
-      // Every assembled assistant message is one completed LLM roundtrip;
-      // counting it (instead of completed turns) also covers one-shot
-      // subagents, whose whole run is a single turn with many model calls.
       if (event.type !== 'assistant/message') return
       this[kRounds].set(session, (this[kRounds].get(session) ?? 0) + 1)
     })
+  }
+
+  /**
+   * Round-interval trigger: once the session's assistant-message clock
+   * (kept by `[kRegisterAssistantMessageCounter]`) reaches the configured
+   * `roundInterval`, compact at the agent's next idle boundary through the
+   * manual-compaction seam (`compactNow`). In-process subagents run through
+   * the same session/event and agent/status dispatch, so continuable
+   * children are covered exactly like the top-level session — and because
+   * one-shot subagents emit many assistant messages inside a single turn,
+   * they now trigger too.
+   */
+  [kRegisterRoundTrigger]() {
+    const { ctx } = this
     ctx.on('agent/status', ({ agent, status }) => {
       if (status === 'idle') this[kMaybeRoundCompact](agent)
     })
@@ -213,6 +249,136 @@ export class DcpEngine extends BasicCompactionEngine {
     })
   }
 
+  /**
+   * Model-switch watch: fold `request/context` (the per-request routing
+   * snapshot, logged on change) per session; a provider or model change from
+   * the session's previous route is a switch. Covers every entry point — TUI
+   * `/model`, web clients, changed default settings — because it observes the
+   * effective route rather than any client's selection intent. Subagent
+   * sessions fold independently, mirroring the round trigger's stance.
+   */
+  [kRegisterModelSwitchWatch]() {
+    const { ctx } = this
+    ctx.on('session/event', (session, event) => {
+      if (event.type !== 'request/context') return
+      const data = /** @type {{data?: {provider?: unknown, model?: unknown}}} */ (event).data
+      if (typeof data?.provider !== 'string' || typeof data?.model !== 'string') return
+      const route = { provider: data.provider, model: data.model }
+      const previous = this[kRoutes].get(session)
+      this[kRoutes].set(session, route)
+      // First observed request only seeds the baseline: without a previous
+      // route there is no "switched from" to report.
+      if (previous === undefined) return
+      if (previous.provider === route.provider && previous.model === route.model) return
+      this[kMaybeOnModelSwitch](session, previous, route)
+    })
+    // The auto mode's compaction needs a real agent (`runMaintenance`, routed
+    // options), which `session/event` never carries — so pending switches
+    // wait for the same idle boundary the round trigger uses.
+    ctx.on('agent/status', ({ agent, status }) => {
+      if (status === 'idle') this[kAttemptSwitchCompaction](agent)
+    })
+  }
+
+  /**
+   * Handle one detected model switch. Two gates guard every mode: the
+   * recency gate (fewer than `MODEL_SWITCH_MIN_ROUNDS` assistant messages
+   * since the session's last committed compaction — nothing stale has
+   * accumulated, so prompting or compacting again only adds noise and
+   * rewrites) and the size gate (`modelSwitchMinTokens` — the context is
+   * too small for shadowing to be worth anything). `notice` appends the
+   * suggest-`/dcp compact` row; `auto` appends the in-progress row and
+   * marks the session for the next idle boundary. The `auto` mode is an
+   * automatic compaction trigger, so the `auto: false` master switch
+   * downgrades it to `notice`.
+   */
+  [kMaybeOnModelSwitch](session, previous, route) {
+    let mode = this.dcp.onModelSwitch
+    if (mode === 'off') return
+    if (mode === 'auto' && !this.config.auto) mode = 'notice'
+    if ((this[kRounds].get(session) ?? 0) < MODEL_SWITCH_MIN_ROUNDS) return
+    if (!this[kMeetsMinTokens](session)) return
+    const from = `${previous.provider}/${previous.model}`
+    const to = `${route.provider}/${route.model}`
+    if (mode === 'notice') {
+      this[kAppendSwitchNotice](session, 'notice', from, to)
+      return
+    }
+    this[kSwitchPending].add(session)
+    this[kAppendSwitchNotice](session, 'auto', from, to)
+  }
+
+  /**
+   * Size gate for the model-switch feature: the session's current priced
+   * surface must reach `modelSwitchMinTokens` before a switch is worth
+   * announcing — below it there is not enough history for shadowing to save
+   * anything meaningful. `0` disables the gate. Measured per switch (the
+   * `request/context` event only fires on route changes, so this is rare).
+   * Measurement failure or absence fails open: the recency gate still
+   * applies, and a meterless exotic host keeps the feature alive.
+   */
+  [kMeetsMinTokens](session) {
+    const min = this.dcp.modelSwitchMinTokens
+    if (!min) return true
+    try {
+      // tokenMeter arrives through `static inject`, which checkJs cannot see
+      // on the Context type — the optional chain plus cast is the contract.
+      const meter = /** @type {{measure?: (s: unknown) => {surfaceTokens?: number} | null}} */ (/** @type {any} */ (this.ctx).tokenMeter)
+      const measurement = meter?.measure?.(session)
+      if (typeof measurement?.surfaceTokens !== 'number') return true
+      return measurement.surfaceTokens >= min
+    } catch {
+      return true
+    }
+  }
+
+  /**
+   * Serve one pending model-switch compaction at an idle boundary. The
+   * attempt shares the round trigger's single-flight WeakSet, so the two
+   * idle listeners can never drive concurrent `compactNow` calls on the
+   * same agent; the trigger label is claimed here (not at detection time)
+   * so a manual `/dcp compact` in between cannot steal it. `busy` and
+   * `cancelled` restore the pending mark for the next boundary, mirroring
+   * the round trigger; any other failure warns and drops it — the pressure
+   * trigger remains the safety net.
+   */
+  [kAttemptSwitchCompaction](agent) {
+    const session = agent?.session
+    if (session === undefined || !this[kSwitchPending].has(session)) return
+    if (this[kRoundInFlight].has(session)) return
+    this[kSwitchPending].delete(session)
+    this[kTriggerLabels].set(session, 'model-switch')
+    this[kRoundInFlight].add(session)
+    const settle = () => this[kRoundInFlight].delete(session)
+    void this.compactNow(agent, new AbortController().signal).then(settle, (error) => {
+      settle()
+      if (error instanceof ManualCompactionError && (error.code === 'busy' || error.code === 'cancelled')) {
+        this[kSwitchPending].add(session)
+        return
+      }
+      this.ctx.logger.warn(`model-switch compaction failed: ${error instanceof Error ? error.message : String(error)}`)
+    })
+  }
+
+  /**
+   * Append the model-switch notice row (same collapsed-row channel as the
+   * compaction notice). Failures never surface as switch-handling failures —
+   * in auto mode the compaction still proceeds, in notice mode the switch is
+   * simply unannounced.
+   */
+  [kAppendSwitchNotice](session, mode, from, to) {
+    const summary = boundContextSummary(modelSwitchNoticeText(this.dcp.language, mode, from, to))
+    try {
+      session.append('user/message', createUserMessage({
+        content: [{ type: 'text', text: summary }],
+        source: { kind: 'plugin', plugin: 'dsh-dcp', form: 'notice', summary },
+      }))
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      this.ctx.logger.warn(`dsh-dcp model-switch notice append failed: ${message}`)
+    }
+  }
+
   /**
    * The sole overridden seam: condense the replayed region deterministically.
    * No LLM call, no cancellation window beyond the fast synchronous walk.
@@ -243,18 +409,19 @@ export class DcpEngine extends BasicCompactionEngine {
   }
 
   /**
-   * Manual seam (`/dcp compact`, `/compact`) and this plugin's own
-   * round-interval trigger — the parent's `compactNow` bypasses
-   * `compactRegion` (it drives `compactSurfaceRegion` directly), so without
-   * this override the manual path would miss stats and the transcript notice.
+   * Manual seam (`/dcp compact`, `/compact`) and this plugin's own automatic
+   * idle-boundary triggers (round interval, model switch) — the parent's
+   * `compactNow` bypasses `compactRegion` (it drives `compactSurfaceRegion`
+   * directly), so without this override those paths would miss stats and the
+   * transcript notice.
    *
    * alpha.3 note: the base dereferences `signal` unguarded
    * (`signal.throwIfAborted()`), so the signal is required — both this
-   * plugin's round trigger and the command invocation always pass one.
+   * plugin's triggers and the command invocation always pass one.
    */
   async compactNow(agent, signal, sourceCommandId) {
     const session = agent.session
-    const trigger = this[kTriggerLabels].get(session) === 'round' ? 'round' : 'manual'
+    const trigger = this[kTriggerLabels].get(session) ?? 'manual'
     try {
       const result = await super.compactNow(agent, signal, sourceCommandId)
       // `null` means no useful range existed: release the round counter so an
@@ -277,14 +444,18 @@ export class DcpEngine extends BasicCompactionEngine {
   }
 
   /**
-   * Record one committed compaction: bump the `/dcp` counters and restart the
-   * round-interval counting.
+   * Record one committed compaction: bump the `/dcp` counters and restart
+   * the round-interval counting. A committed compaction also clears any
+   * pending model-switch compaction — the stale history the switch was
+   * going to shadow is now shadowed by this compaction, whatever triggered
+   * it.
    */
   [kRecordStats](session, result) {
     this.dcpStats.compactions += 1
     this.dcpStats.shadowedTokens += result.shadowedTokenCount
     this.dcpStats.lastAt = Date.now()
     this[kRounds].delete(session)
+    this[kSwitchPending].delete(session)
     this[kRecordSessionStats](session, result.shadowedTokenCount)
   }
 

package/lib/skill.js

@@ -1,7 +1,7 @@
 /**
  * Bundled usage/configuration skill for dsh-dcp.
  *
- * Ships `skills/dsh-dcp/SKILL.md` through `ctx.skills.registerProvider`
+ * Ships `skills/dsh-dcp-config/SKILL.md` through `ctx.skills.registerProvider`
  * (same mechanism as dsh-llm-proxy and dsh-vault): an agent asked to tune
  * compaction, run `/dcp`, or persist a config change loads the guide
  * automatically instead of guessing at key names and mount shapes.
@@ -25,21 +25,21 @@ import { fileURLToPath } from 'node:url'
 const BUNDLED_SKILL_RANK = 600
 
 /** Provider name under `ctx.skills`; doubles as the skill name. */
-export const SKILL_PROVIDER_NAME = 'dsh-dcp'
+export const SKILL_PROVIDER_NAME = 'dsh-dcp-config'
 
 /** Packaged skill body; `../skills/` resolves to the package root from lib/. */
-const SKILL_BODY_URL = new URL('../skills/dsh-dcp/SKILL.md', import.meta.url)
+const SKILL_BODY_URL = new URL('../skills/dsh-dcp-config/SKILL.md', import.meta.url)
 
 /** Resource base served with the skill so its relative links resolve. */
 const SKILL_RESOURCE_BASE = {
   kind: 'directory',
-  path: fileURLToPath(new URL('../skills/dsh-dcp/', import.meta.url)),
+  path: fileURLToPath(new URL('../skills/dsh-dcp-config/', import.meta.url)),
 }
 
 const SKILL_INVOCATION = { modelInvocable: true, userInvocable: true }
 
 /** Routing description; must stay identical to the SKILL.md frontmatter (asserted in tests). */
-export const SKILL_DESCRIPTION = 'dsh 压缩引擎插件（@aiwayds/dsh-dcp）使用与配置指南。凡涉及上下文压缩、/dcp 命令、压缩调参（阈值/密度/语言/轮数触发），或要配置 dcp 时先读本指南：/dcp 状态与 /dcp set 十个可调键、持久化到 cordis.patch.yml 挂载块 config: 段（dsh-dcp-setup 管理）、ask_user_question 调参向导、四类触发（压力/溢出/轮数/手动）、subagent 会话独立计数生效。触发词：dcp、压缩、compaction、上下文超限、摘要、thresholdRatio、roundInterval。'
+export const SKILL_DESCRIPTION = 'dsh 压缩引擎插件（@aiwayds/dsh-dcp）使用与配置指南。凡涉及上下文压缩、/dcp 命令、压缩调参（阈值/密度/语言/轮数触发/模型切换），或要配置 dcp 时先读本指南：/dcp 状态与 /dcp set 十二个可调键、持久化到 cordis.patch.yml 挂载块 config: 段（dsh-dcp-setup 管理）、ask_user_question 调参向导、五类触发（压力/溢出/轮数/模型切换/手动）、subagent 会话独立计数生效。触发词：dcp、压缩、compaction、上下文超限、摘要、thresholdRatio、roundInterval、onModelSwitch。'
 
 const SKILL_CANDIDATE = {
   name: SKILL_PROVIDER_NAME,

package/lib/summarizer.js

@@ -133,6 +133,8 @@ const i18n = Object.freeze({
     carried: 'carried from prior checkpoint',
     terseHeader: '{messages} messages ({calls} tool calls) compacted deterministically by dsh-dcp.',
     notice: 'dcp: compacted {items} history items (~{tokens} tokens, {trigger})',
+    modelSwitchNotice: 'dcp: model switched {from} → {to} — run /dcp compact first to shadow the old model\'s history and save tokens',
+    modelSwitchAuto: 'dcp: model switched {from} → {to} — compacting the previous model\'s history automatically',
   }),
   zh: Object.freeze({
     none: '（无）',
@@ -143,6 +145,8 @@ const i18n = Object.freeze({
     carried: '继承自上一次压缩检查点',
     terseHeader: 'dsh-dcp 确定性压缩了 {messages} 条消息（{calls} 次工具调用）。',
     notice: 'dcp: 已压缩 {items} 条历史（约 {tokens} tokens，{trigger}）',
+    modelSwitchNotice: 'dcp: 模型已切换 {from} → {to} —— 建议先执行 /dcp compact 压缩旧模型的历史，节省 token',
+    modelSwitchAuto: 'dcp: 模型已切换 {from} → {to} —— 正在自动压缩旧模型的历史',
   }),
 })
 
@@ -154,6 +158,23 @@ export function noticeText(language, items, tokens, trigger = 'auto') {
     .replace('{trigger}', trigger) ?? ''
 }
 
+/**
+ * One-line model-switch notice for the transcript row. `mode` picks the
+ * copy: `notice` suggests the command, `auto` announces the upcoming
+ * automatic compaction. Unknown languages fall back to English.
+ *
+ * @param {'en'|'zh'} language
+ * @param {'notice'|'auto'} mode
+ * @param {string} fromModel - model id routed before the switch.
+ * @param {string} toModel - model id routed now.
+ */
+export function modelSwitchNoticeText(language, mode, fromModel, toModel) {
+  const table = i18n[language] ?? i18n.en
+  return (mode === 'auto' ? table.modelSwitchAuto : table.modelSwitchNotice)
+    .replace('{from}', fromModel)
+    .replace('{to}', toModel)
+}
+
 /** Collapse whitespace and hard-cap one item's length with an ellipsis. */
 export function clip(text, maxChars) {
   const flat = String(text).replace(/\s+/g, ' ').trim()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwayds/dsh-dcp",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Deterministic context-pruning compaction backend for dsh (DeepSeek Harness) — zero-LLM summaries, /dcp command, works out of the box. Design references Opencode-DCP/opencode-dynamic-context-pruning.",
   "type": "module",
   "main": "lib/index.js",

package/skills/{dsh-dcp → dsh-dcp-config}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: dsh-dcp
-description: "dsh 压缩引擎插件（@aiwayds/dsh-dcp）使用与配置指南。凡涉及上下文压缩、/dcp 命令、压缩调参（阈值/密度/语言/轮数触发），或要配置 dcp 时先读本指南：/dcp 状态与 /dcp set 十个可调键、持久化到 cordis.patch.yml 挂载块 config: 段（dsh-dcp-setup 管理）、ask_user_question 调参向导、四类触发（压力/溢出/轮数/手动）、subagent 会话独立计数生效。触发词：dcp、压缩、compaction、上下文超限、摘要、thresholdRatio、roundInterval。"
+name: dsh-dcp-config
+description: "dsh 压缩引擎插件（@aiwayds/dsh-dcp）使用与配置指南。凡涉及上下文压缩、/dcp 命令、压缩调参（阈值/密度/语言/轮数触发/模型切换），或要配置 dcp 时先读本指南：/dcp 状态与 /dcp set 十二个可调键、持久化到 cordis.patch.yml 挂载块 config: 段（dsh-dcp-setup 管理）、ask_user_question 调参向导、五类触发（压力/溢出/轮数/模型切换/手动）、subagent 会话独立计数生效。触发词：dcp、压缩、compaction、上下文超限、摘要、thresholdRatio、roundInterval、onModelSwitch。"
 ---
 
 # dsh-dcp 使用指南（确定性上下文压缩）
@@ -11,9 +11,10 @@ description: "dsh 压缩引擎插件（@aiwayds/dsh-dcp）使用与配置指南
 
 ## 配置入口（两条路）
 
-1. **会话内临时调参**：`/dcp set <键> <值>`，只影响当前会话，重启失效。十个可调键：
+1. **会话内临时调参**：`/dcp set <键> <值>`，只影响当前会话，重启失效。十二个可调键：
    `dedup` `purgeErrors` `maxItems` `maxItemChars` `maxSummaryTokens` `language`
-   `tokenEstimate` `thresholdRatio` `roundInterval` `notice`。
+   `tokenEstimate` `thresholdRatio` `roundInterval` `notice` `onModelSwitch`
+   `modelSwitchMinTokens`。
 2. **持久化**：cordis.patch.yml 里 dsh-dcp 挂载块的 `config:` 段。用
    `npx dsh-dcp-setup` 写入并维护（带 marker 注释、改动前日期备份、幂等）；
    `--remove` 只删 setup 写的块，手工写的块不受影响。bundle 方式
@@ -48,6 +49,8 @@ dsh-dcp 自有键（除 `thresholdRatio` 外全部可用 `/dcp set` 调）：
 | `protectedTools` | `['write', 'edit', 'apply_patch']` | 写侧工具（子串匹配）的重复调用不折叠进 dedup 标注 |
 | `roundInterval` | 50 | 每 N 条 assistant message（一次 LLM 往返）触发一次压缩；`0` 关闭 |
 | `notice` | `true` | 压缩后在会话追加一行通知 |
+| `onModelSwitch` | `notice` | 模型切换后：`notice` 提醒执行 `/dcp compact`；`auto` 下一个空闲点自动压缩；`off` 关闭 |
+| `modelSwitchMinTokens` | 32768 | 模型切换提醒/自动压缩的上下文下限（宿主 tokenMeter 实测）：不足则忽略该次切换；`0` 关闭此门 |
 
 转发上游 compaction-basic 的策略键：`thresholdRatio`（上游默认 0.8；**本插件 bundle 挂载默认 0.7**，中文场景建议 0.7）、`retainRatio`、`retainTokens`、`maxTokens`、`summarizationProvider`、`summarizationModel`、`compactionRetries`、`maxOverflowRetries`、`modelPolicies`、`auto`。
 
@@ -63,21 +66,25 @@ dsh-dcp 自有键（除 `thresholdRatio` 外全部可用 `/dcp set` 调）：
 3. **摘要语言** → `language: en|zh`。
 4. **token 计价** → `tokenEstimate: cjk|ascii`。
 5. **通知行** → `notice: on|off`。
+6. **模型切换行为**：问用户切模型后想怎样——只提醒（默认 `notice`）/
+   自动压缩（`auto`，省心但切换频繁时会多次重写历史）/ 不管（`off`）。
 
 流程：先用 `/dcp set <键> <值>` 在会话内试效果，满意后再代写持久 config——
 直接改 cordis.patch.yml 里 dsh-dcp 挂载块的 `config:` 段（setup 写的块可原位改，marker 保留）。
 
-## 触发条件（四类）
+## 触发条件（五类）
 
 | 触发 | 时机 | 说明 |
 |---|---|---|
 | 压力 | 每步请求前 | token ≥ `thresholdRatio` × 上下文窗口 |
 | 溢出 | 模型报 context 超限 | 继承官方恢复流程 |
 | 轮数 | 每累计 `roundInterval` 条 assistant message | 任何一次压缩（含压力/手动）都重置时钟；`0` 关闭；需保持 `auto: true`（默认开） |
+| 模型切换 | 会话实际路由的 provider/model 变化 | `onModelSwitch` 控制（默认 `notice` 提醒）；`auto` 在下一个空闲点自动压缩；两道门：距上次压缩 <10 条消息、上下文 <`modelSwitchMinTokens` |
 | 手动 | `/dcp compact`、`/compact` | 随时可用 |
 
 - **subagent 同样生效**：进程内子代理（含 continuable 与 one-shot）走同一套事件分发，
-  压力/溢出/轮数对每个会话独立计数、独立触发。
+  压力/溢出/轮数/模型切换对每个会话独立计数、独立触发。
+- **两类通知行相互独立**：压缩通知行受 `notice` 管，模型切换提醒行受 `onModelSwitch` 管。
 - `notice` 通知行本身也是上下文（每次压缩约 15–25 tokens）；`notice: false` 可关。
 
 ## 排障