smartcompact 0.0.0-stage → 0.1.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# SmartCompact
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**English summary.** SmartCompact makes long coding-agent sessions compact *earlier, at the right moment* — once the context is past a threshold (200k tokens by default) and a piece of work has just been finished, typically a commit. Every request re-reads the whole context, so keeping it smaller saves money; picking the moment right after a commit avoids interrupting work. It never compacts in the middle of a task by itself. It works with Claude Code (CLI and desktop app), [pi](https://github.com/earendil-works/pi) and the Codex CLI. In controlled A/B runs (18–30 consecutive coding tasks, 3 runs per arm) it cut cost by 7–22% with no loss in hidden acceptance tests or recall questions. Details: [docs/TEST-REPORT.md](docs/TEST-REPORT.md) (Chinese).
+
+---
+
+让长会话早点、挑对时机压缩：降低成本，同时不损失结果。
+
+## 为什么
+
+agent 每发一次请求，都要把整段上下文重新读一遍。上下文越长，每一步越贵。原生的自动压缩通常要等到快满了才触发（Claude Code 接近 100 万，Codex 可以配到 80 万），在那之前每一步都在为很长的上下文付钱；而且原生压缩不看时机，常常发生在一件事做到一半的时候。
+
+SmartCompact 的做法：
+
+- 上下文超过**允许压缩线**（默认 20 万）以后，等到**刚做完一件事**（一次提交、测试刚通过、任务完成）再压缩。
+- 不在一件事做到一半时主动压缩；测试失败、构建失败、连续报错或后台任务还在跑时也不压缩。
+- 一直等不到合适时机、上下文超过**宽限线**（允许压缩线 × 1.3）时，在一轮结束时压缩，作为兜底。
+- 压缩前后用一份**进度笔记**接上：改过的文件、最近的提交和测试结果、记下的决定，压缩后补回给模型。
+- 预计腾不出足够空间时不压缩，避免刚压缩完又压缩。
+
+## 效果
+
+同一个代码库、连续 18～30 个开发任务（后面的任务会修改前面任务的结果），每个平台装与不装各跑 3 次。验收由脚本跑模型看不到的隐藏测试；每轮结束问几道记忆题，包括很早之前随口提到的细节。
+
+| 平台（模型） | 原生压缩点 | 成本 | 任务验收 | 记忆题 |
+|---|---|---|---|---|
+| Codex（gpt-6-astra） | 80 万 | **−19%** | 两组都 18/18 | 两组都 54/54 |
+| pi（gpt-5.5） | 约 25.6 万 | −11%～−22% | 两组都 18/18 | 原生 51/54，插件 53/54 |
+| Claude Code（Haiku 5.5，30 题） | 接近 100 万 | −7%（波动较大） | 两组都 30/30 | 两组都 90/90 |
+
+成本按各家价格比例折算成"缓存读取 token 当量"。规律：原生压缩得越晚、会话涨得越快，省得越多；会话没超过 20 万时插件不起作用，也没有坏处。完整方法、数据、代价和局限见 [docs/TEST-REPORT.md](docs/TEST-REPORT.md)。
+
+## 安装
+
+### Claude Code（终端和桌面 App）
+
+需要 Claude Code ≥ 2.1.295。
+
+```
+/plugin marketplace add coffeecoproject/SmartCompact
+/plugin install smartcompact@smartcompact
+```
+
+装好后新开会话生效。插件会把原生自动压缩线调到宽限线附近，`/smartcompact pause` 可以让当前会话恢复原生行为。
+
+### pi
+
+```bash
+pi install npm:smartcompact
+```
+
+也可以从 GitHub 装：`pi install git:github.com/coffeecoproject/SmartCompact`。
+
+pi 默认配置下，插件在一轮结束（`agent_settled`）时挑阶段节点主动压缩。如果你把 `reserveTokens` 调大、让 pi 的原生压缩提前，插件会在那个点按工作状态决定是否推迟。
+
+### Codex 命令行
+
+需要 Node ≥ 22.18（直接运行 TypeScript）和 Codex CLI ≥ 0.162。
+
+```bash
+git clone https://github.com/coffeecoproject/SmartCompact.git
+cd SmartCompact
+node scripts/codex.ts install
+```
+
+安装脚本只在 `~/.codex/config.toml`（或 `$CODEX_HOME/config.toml`）末尾写入一段带标记的 hook 配置，改之前备份原文件；`node scripts/codex.ts uninstall` 移除。下次启动 Codex 时按提示信任这 4 个 hook。升级 Node 或移动仓库后重新运行一次 install。
+
+Codex 的 hook 不能推迟一轮中间的压缩，所以插件在一轮结束时判断，需要压缩就通过 Codex 的共享后台服务（交互界面默认会用它）在会话空闲时发起。`codex exec` 和 Codex App（ChatGPT.app）默认不走共享后台服务，这时插件只补回进度笔记，压缩仍按 Codex 原生规则。
+
+## 参数
+
+| 参数 | 默认 | 含义 |
+|---|---|---|
+| 允许压缩线 | 200000 | 超过它且刚做完一件事时压缩 |
+| 宽限倍数 | 1.3 | 超过 允许压缩线 × 倍数 时不再等阶段节点 |
+| 最少腾出空间 | 60000 | 预计腾出的空间少于它时不压缩 |
+
+- Claude Code：安装插件时的配置项（`allowLineTokens`、`graceFactor`、`minFreedTokens`），留空用默认值。
+- pi：命令行开关 `--smartcompact-allow-line`、`--smartcompact-grace`、`--smartcompact-min-freed`。
+- Codex：环境变量 `SMARTCOMPACT_ALLOW_LINE`、`SMARTCOMPACT_GRACE`、`SMARTCOMPACT_MIN_FREED`。
+
+## 查看效果
+
+- Claude Code 和 pi：`/smartcompact`（或 `/smartcompact report`）查看三条线、阶段节点计数和成本估算；`/smartcompact pause` / `resume` 暂停或恢复。Claude Code 和 pi 里模型还可以调用 checkpoint 工具记下决定，压缩后一起补回。
+- Codex：`node adapters/codex/report.ts <会话 ID>`，记录在 `~/.codex/smartcompact/`。
+
+## 局限
+
+- 判断"刚做完一件事"靠识别命令：提交只要真的执行了 `git commit` 且没报错就算；测试命令接了管道（`| tail`）又没开 `pipefail` 时退出码不可信，不算测试结果。
+- 进度笔记只记文件、提交、测试和模型主动记下的决定。用户在对话里随口交代的细节靠压缩时的说明要求摘要保留，pi 上能明显减少丢失，但不能保证不丢。
+- Claude Code 上，插件的兜底压缩点和它调整后的原生压缩点接近；长时间认不出阶段节点时，可能由原生压缩在一轮中间触发。
+- 评测只用了一个代码库和一种任务类型，Claude 只测了 Haiku。
+
+## 开发
+
+```bash
+sh scripts/check.sh
+```
+
+结构校验、core 依赖边界检查和全部测试。目录：
+
+- `plugin/`：Claude Code 插件；`plugin/src/core/` 是和平台无关的决策、信号、进度笔记和成本估算，其他适配都复用它。
+- `adapters/pi/`、`adapters/codex/`：pi 和 Codex 的适配。
+- `eval/`：对照评测脚本（Claude、pi、Codex 各一个），任务格式见 `eval/day.py`；评测用的题目和隐藏测试涉及内部项目，没有放进仓库。
+- `DESIGN.md`：设计说明；`docs/TEST-REPORT.md`：测试报告。
+
+## 许可证
+
+[MIT](LICENSE)

package/adapters/pi/index.ts

@@ -0,0 +1,237 @@
+// SmartCompact 的 pi 扩展：把 pi 的事件接到 core 的决策上。
+// 和 Claude 版的区别：插件改不了 pi 的原生压缩线。
+// - 兜底线 = pi 配置的原生压缩点（窗口 − reserveTokens），上限 = 窗口 − pi 默认预留。
+// - 默认配置下两者相同，插件只在 agent_settled（不会再自动继续时）挑阶段节点主动压缩；
+//   用户把 reserveTokens 调大、让原生压缩提前时，插件在提前的那个点按工作状态决定是否取消。
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
+import { SettingsManager } from '@earendil-works/pi-coding-agent'
+import { Type } from 'typebox'
+import { decideAtTurnEnd, decideMidTurn, shouldNudge } from '../../plugin/src/core/decide.ts'
+import { applyCheckpoint, COMPACT_INSTRUCTIONS, parseCheckpoint, renderLedger } from '../../plugin/src/core/ledger.ts'
+import type { Lines } from '../../plugin/src/core/lines.ts'
+import { resolveParams } from '../../plugin/src/core/params.ts'
+import { countDecisions, renderReport } from '../../plugin/src/core/report.ts'
+import {
+  type DecisionLogEntry,
+  expectedAfterTokens,
+  INITIAL_SESSION_STATE,
+  parseState,
+  type SessionState,
+  withCompaction,
+  withSample,
+  withSignals,
+} from '../../plugin/src/core/state.ts'
+import { pricesFor } from '../../plugin/src/core/usage.ts'
+import { recognizePi } from './recognize.ts'
+
+const STATE_ENTRY = 'smartcompact-state'
+const LOG_ENTRY = 'smartcompact-log'
+const LEDGER_MESSAGE = 'smartcompact-ledger'
+const NUDGE_MESSAGE = 'smartcompact-nudge'
+const CHECKPOINT_TOOL = 'smartcompact_checkpoint'
+/** pi 内置的默认 reserveTokens，即不配置时原生压缩点离满窗的距离 */
+const PI_DEFAULT_RESERVE = 16_384
+/** 压缩后除了保留的最近内容，还有系统提示、工具和摘要，粗估这么多 */
+const PI_AFTER_OVERHEAD = 10_000
+
+const nudgeText = (tokens: number): string =>
+  `SmartCompact: the context is at about ${Math.round(tokens / 1000)}k tokens and will be compacted at the next finished piece of work. ` +
+  `If decisions or progress are not yet recorded, call ${CHECKPOINT_TOOL} briefly. If the user is waiting for an answer, answer first.`
+
+export default function smartCompact(pi: ExtensionAPI) {
+  pi.registerFlag('smartcompact-allow-line', { description: 'SmartCompact 允许压缩线（token）', type: 'string' })
+  pi.registerFlag('smartcompact-grace', { description: 'SmartCompact 宽限倍数', type: 'string' })
+  pi.registerFlag('smartcompact-min-freed', { description: 'SmartCompact 最少腾出空间（token）', type: 'string' })
+
+  let state: SessionState = INITIAL_SESSION_STATE
+  let saved = ''
+  /** 插件自己发起的压缩在 pi 里同样是 manual，据此和用户的 /compact 区分。 */
+  let ours = false
+  /** 当前模型的 reserveTokens 和 keepRecentTokens；读设置文件有开销，按会话和模型缓存。 */
+  let compaction: { reserve: number; keepRecent: number } | undefined
+
+  const compactionSettings = (ctx: ExtensionContext) => {
+    if (!compaction) {
+      // 和 pi 自己一样：项目未被信任时不读项目目录下的设置。
+      const settings = SettingsManager.create(ctx.cwd, undefined, { projectTrusted: ctx.isProjectTrusted() }).getCompactionSettings(ctx.model)
+      compaction = { reserve: settings.reserveTokens, keepRecent: settings.keepRecentTokens }
+    }
+    return compaction
+  }
+
+  // pi 的基础占用比 Claude 小得多：压缩后的大小按 pi 保留的最近内容估算，而不是用 core 的默认值。
+  const params = (ctx: ExtensionContext) =>
+    resolveParams({
+      allowLineTokens: Number(pi.getFlag('smartcompact-allow-line')) || undefined,
+      graceFactor: Number(pi.getFlag('smartcompact-grace')) || undefined,
+      minFreedTokens: Number(pi.getFlag('smartcompact-min-freed')) || undefined,
+      defaultAfterTokens: compactionSettings(ctx).keepRecent + PI_AFTER_OVERHEAD,
+    })
+
+  const lines = (ctx: ExtensionContext): Lines | null => {
+    const usage = ctx.getContextUsage()
+    if (!usage) return null
+    const { reserve } = compactionSettings(ctx)
+    return {
+      allow: params(ctx).allowLineTokens,
+      midTurn: usage.contextWindow - reserve,
+      ceiling: usage.contextWindow - Math.min(reserve, PI_DEFAULT_RESERVE),
+      adjustsNative: false,
+    }
+  }
+
+  const tokensOf = (ctx: ExtensionContext): number | undefined => ctx.getContextUsage()?.tokens ?? undefined
+
+  // 成本估算对比的是"没有插件时"：pi 原生会在它配置的压缩点（兜底线）压缩，而不是等到真正的极限。
+  const sample = (ctx: ExtensionContext, current: Lines | null) => {
+    const tokens = tokensOf(ctx)
+    const model = `${ctx.model?.provider ?? ''} ${ctx.model?.id ?? ''}`
+    if (tokens !== undefined && current) state = withSample(state, tokens, current.midTurn, pricesFor(model))
+    return tokens
+  }
+
+  // 状态变了才写一条，避免会话文件膨胀。
+  const persist = () => {
+    const json = JSON.stringify(state)
+    if (json === saved) return
+    saved = json
+    pi.appendEntry(STATE_ENTRY, state)
+  }
+
+  const log = (entry: Omit<DecisionLogEntry, 'at' | 'session'>) => pi.appendEntry(LOG_ENTRY, { at: new Date().toISOString(), ...entry })
+
+  const report = (ctx: ExtensionContext): string => {
+    const current = lines(ctx)
+    if (!current) return 'SmartCompact 尚未读到上下文用量。'
+    const entries = ctx.sessionManager
+      .getBranch()
+      .flatMap(entry => (entry.type === 'custom' && entry.customType === LOG_ENTRY ? [entry.data as DecisionLogEntry] : []))
+    return renderReport({ state, lines: current, tokens: tokensOf(ctx), counts: countDecisions(entries) })
+  }
+
+  pi.on('session_start', async (_event, ctx) => {
+    // 恢复当前分支上最后一次保存的状态。
+    const last = ctx.sessionManager
+      .getBranch()
+      .filter(entry => entry.type === 'custom' && entry.customType === STATE_ENTRY)
+      .at(-1)
+    state = parseState(last && last.type === 'custom' ? last.data : undefined)
+    saved = JSON.stringify(state)
+    ours = false
+    compaction = undefined
+  })
+
+  pi.on('model_select', async () => {
+    compaction = undefined
+  })
+
+  pi.registerTool({
+    name: CHECKPOINT_TOOL,
+    label: 'Checkpoint',
+    description:
+      'Record a short progress note that survives context compaction: the goal, decisions made, where the work stands, and what is next. ' +
+      'Call it after finishing a piece of work (set milestone: true) or after an important decision. Keep it brief; do not call it for trivial steps.',
+    parameters: Type.Object({
+      goal: Type.Optional(Type.String({ description: 'The overall goal of the current work.' })),
+      decisions: Type.Optional(Type.Array(Type.String(), { description: 'Decisions made since the last checkpoint.' })),
+      next: Type.Optional(Type.String({ description: 'What to do next.' })),
+      current: Type.Optional(Type.String({ description: 'Where the work stands right now.' })),
+      milestone: Type.Optional(Type.Boolean({ description: 'True when a piece of work was just finished.' })),
+    }),
+    async execute(_toolCallId, input) {
+      const parsed = parseCheckpoint(input)
+      if (!parsed.ok) return { content: [{ type: 'text', text: `Not recorded: ${parsed.error}` }], details: {} }
+      state = withSignals({ ...state, ledger: applyCheckpoint(state.ledger, parsed.value), notesUpdated: true }, [
+        { kind: 'checkpoint', milestone: parsed.value.milestone === true },
+      ])
+      persist()
+      log({ event: 'checkpoint', action: parsed.value.milestone ? 'milestone' : 'note' })
+      return { content: [{ type: 'text', text: 'Recorded. Continue with the work.' }], details: {} }
+    },
+  })
+
+  pi.registerCommand('smartcompact', {
+    description: 'SmartCompact：report 查看效果，pause / resume 暂停或恢复',
+    handler: async (args, ctx) => {
+      const action = args.trim() || 'report'
+      if (action === 'pause' || action === 'resume') {
+        state = { ...state, paused: action === 'pause' }
+        persist()
+        ctx.ui.notify(action === 'pause' ? 'SmartCompact 已暂停：本会话不再干预压缩。' : 'SmartCompact 已恢复。', 'info')
+        return
+      }
+      ctx.ui.notify(action === 'report' ? report(ctx) : '用法：/smartcompact [report|pause|resume]', 'info')
+    },
+  })
+
+  pi.on('tool_result', async (event, ctx) => {
+    if (event.toolName === CHECKPOINT_TOOL) return
+    sample(ctx, lines(ctx))
+    const text = event.content.flatMap(block => (block.type === 'text' ? [block.text] : [])).join('\n')
+    const { signals, ledger } = recognizePi({ toolName: event.toolName, input: event.input, isError: event.isError, text }, state.ledger)
+    state = withSignals({ ...state, ledger }, signals)
+  })
+
+  pi.on('before_agent_start', async (_event, ctx) => {
+    const current = lines(ctx)
+    const tokens = tokensOf(ctx)
+    if (!current || !shouldNudge({ tokens, lines: current, notesUpdated: state.notesUpdated, nudged: state.nudged, paused: state.paused }, params(ctx))) return
+    state = { ...state, nudged: true }
+    return { message: { customType: NUDGE_MESSAGE, content: nudgeText(tokens ?? 0), display: false } }
+  })
+
+  // agent_settled：pi 不会再自动继续，此时压缩不会打断工作。
+  pi.on('agent_settled', async (_event, ctx) => {
+    const current = lines(ctx)
+    if (!current) return
+    const tokens = sample(ctx, current)
+    persist()
+    const decision = decideAtTurnEnd(
+      { tokens, lines: current, work: state.work, expectedAfterTokens: expectedAfterTokens(state, params(ctx).defaultAfterTokens), paused: state.paused },
+      params(ctx),
+    )
+    if (decision.action !== 'none') log({ event: 'turn-end', action: decision.action, reason: decision.reason, tokens })
+    if (decision.action !== 'compact' || !ctx.isIdle() || ctx.hasPendingMessages()) return
+    ours = true
+    ctx.compact({
+      customInstructions: COMPACT_INSTRUCTIONS,
+      onError: error => {
+        ours = false
+        log({ event: 'compacted', action: 'failed', trigger: 'plugin', detail: error.message })
+      },
+    })
+  })
+
+  pi.on('session_before_compact', async (event, ctx) => {
+    // 只在原生按阈值压缩时判断；上下文溢出的恢复压缩和用户的 /compact 一律放行。
+    if (event.reason !== 'threshold') return
+    const current = lines(ctx)
+    if (!current) return
+    const tokens = sample(ctx, current)
+    const decision = decideMidTurn(
+      { tokens, lines: current, work: state.work, expectedAfterTokens: expectedAfterTokens(state, params(ctx).defaultAfterTokens), paused: state.paused },
+      params(ctx),
+    )
+    log({ event: 'mid-turn', action: decision.action, reason: decision.reason, tokens })
+    if (decision.action === 'veto') return { cancel: true }
+  })
+
+  pi.on('session_compact', async (event, ctx) => {
+    const fromPlugin = event.reason === 'manual' && ours
+    ours = false
+    const summaryTokens = Math.round(event.compactionEntry.summary.length / 4)
+    // 原生按阈值的压缩、溢出恢复和用户的 /compact，没有插件时也会发生；只有插件发起的压缩计入节省。
+    state = withCompaction(state, event.compactionEntry.tokensBefore, summaryTokens, fromPlugin)
+    persist()
+    log({ event: 'compacted', trigger: fromPlugin ? 'plugin' : event.reason === 'threshold' ? 'auto' : event.reason, tokensBefore: event.compactionEntry.tokensBefore })
+    pi.sendMessage(
+      { customType: LEDGER_MESSAGE, content: renderLedger(state.ledger, params(ctx).ledgerMaxChars), display: false },
+      { deliverAs: ctx.isIdle() ? 'nextTurn' : 'steer' },
+    )
+  })
+
+  pi.on('session_compact_failed', async () => {
+    ours = false
+  })
+}

package/adapters/pi/recognize.ts

@@ -0,0 +1,30 @@
+// 把 pi 的工具结果翻译成 core 的信号和笔记事实。
+
+import { classifyCommand } from '../../plugin/src/core/commands.ts'
+import { type Ledger, recordFileChanged } from '../../plugin/src/core/ledger.ts'
+import type { Signal } from '../../plugin/src/core/signals.ts'
+
+export type PiToolOutcome = {
+  toolName: string
+  input: Readonly<Record<string, unknown>>
+  isError: boolean
+  /** 结果里的文本内容 */
+  text: string
+}
+
+const EDIT_TOOLS = new Set(['edit', 'write'])
+
+export function recognizePi(outcome: PiToolOutcome, ledger: Ledger): { signals: Signal[]; ledger: Ledger } {
+  const signals: Signal[] = [{ kind: 'tool-result', isError: outcome.isError }]
+  let next = ledger
+  const { path, command } = outcome.input
+  if (EDIT_TOOLS.has(outcome.toolName) && !outcome.isError && typeof path === 'string' && path) {
+    next = recordFileChanged(next, path)
+  }
+  if (outcome.toolName === 'bash' && typeof command === 'string' && command) {
+    const classified = classifyCommand(command, outcome.isError, outcome.text, next)
+    signals.push(...classified.signals)
+    next = classified.ledger
+  }
+  return { signals, ledger: next }
+}

package/package.json

@@ -1,6 +1,14 @@
 {
   "name": "smartcompact",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Compact long agent sessions earlier, at a finished piece of work, to cut cost without losing results (Claude Code, pi, Codex)",
+  "license": "MIT",
+  "author": "coffeecoproject",
+  "homepage": "https://github.com/coffeecoproject/SmartCompact",
+  "repository": { "type": "git", "url": "git+https://github.com/coffeecoproject/SmartCompact.git" },
+  "keywords": ["pi-package", "compaction", "context", "claude-code", "codex", "coding-agent"],
+  "engines": { "node": ">=22.18" },
+  "files": ["adapters/pi", "plugin/src/core", "README.md", "LICENSE"],
+  "pi": { "extensions": ["./adapters/pi/index.ts"] }
+}

package/plugin/src/core/commands.ts

@@ -0,0 +1,47 @@
+// shell 命令结果的识别：提交、测试、构建。各平台的 shell 工具名不同，但命令和输出的规则相同。
+
+import { type Ledger, recordBuild, recordCommit, recordTest } from './ledger.ts'
+import type { Signal } from './signals.ts'
+
+// 吞掉退出码的写法（`npm test || true`）看不出真实结果，不当作测试或构建结果。
+const SWALLOWS_EXIT = /\|\|\s*(true|:)\b|;\s*(true|exit\s+0)\s*$/
+// 接了管道（`npm test | tail`）又没开 pipefail 时，退出码是最后一个命令的，同样看不出真实结果。
+const PIPE = /(^|[^|])\|(?!\|)/
+const PIPEFAIL = /\bpipefail\b/
+
+// 真的在执行 git commit：一段命令以它开头（不是 `echo "git commit"` 这类只是提到它的）。
+// 不再核对提交是否真的成功：插件只在一轮结束、且超过允许压缩线时才压缩，误认一次失败的提交代价很小，
+// 而核对规则（看输出、看退出码）会漏掉模型的各种写法（`-q`、提交后接 `git log`、前面连着接管道的测试）。
+const COMMIT = /(^|&&|;|\n)\s*git(\s+-[Cc]\s+\S+)*\s+commit\b/
+// git commit 正常输出 "[分支 短哈希] 提交说明"，有就记进笔记，没有就记命令
+const COMMIT_OUTPUT = /^\[[^\]\n]+ [0-9a-f]{7,40}\][^\n]*/m
+
+const TEST =
+  /\b(npm|pnpm|yarn|bun)\b[^|;&\n]*\s(run\s+)?test(:[\w:-]+)?(?=[\s;&|)]|$)|\bvitest\b|\bjest\b|\bpytest\b|\bgo\s+test\b|\bcargo\s+(test|nextest)\b|\bmvn\b.*\btest\b|\bgradlew?\b.*\btest\b|\bdotnet\s+test\b|\bswift\s+test\b|\bxcodebuild\b.*\btest\b|\bphpunit\b|\brspec\b|\bclaude\s+plugin\s+test\b|\bnode\s+--test\b/
+
+const BUILD =
+  /\btsc\b|\b(npm|pnpm|yarn|bun)\s+run\s+(build|typecheck|check)\b|\bcargo\s+(build|check)\b|\bgo\s+(build|vet)\b|\bxcodebuild\b|\bmake\b|\bgradlew?\b.*\b(build|assemble)\b/
+
+/**
+ * @param isError 命令是否以非零退出码结束
+ * @param output 命令输出
+ */
+export function classifyCommand(command: string, isError: boolean, output: string, ledger: Ledger): { signals: Signal[]; ledger: Ledger } {
+  const signals: Signal[] = []
+  let next = ledger
+  if (COMMIT.test(command) && !isError && !/--dry-run\b/.test(command)) {
+    signals.push({ kind: 'commit' })
+    next = recordCommit(next, COMMIT_OUTPUT.exec(output)?.[0] ?? command.slice(0, 200))
+  }
+  if (!SWALLOWS_EXIT.test(command) && !(PIPE.test(command) && !PIPEFAIL.test(command))) {
+    const passed = !isError
+    if (TEST.test(command)) {
+      signals.push({ kind: 'tests', passed })
+      next = recordTest(next, command.slice(0, 200), passed)
+    } else if (BUILD.test(command)) {
+      signals.push({ kind: 'build', passed })
+      next = recordBuild(next, command.slice(0, 200), passed)
+    }
+  }
+  return { signals, ledger: next }
+}

package/plugin/src/core/decide.ts

@@ -0,0 +1,63 @@
+// 两个决策函数：一轮结束时要不要主动压缩；一轮进行中原生自动压缩来问时放不放行。
+// 读不到用量时一律不干预，按原生行为来。
+
+import type { Lines } from './lines.ts'
+import type { Params } from './params.ts'
+import { type HardSignal, hardSignal, type MilestoneSource, type WorkState } from './signals.ts'
+
+export type DecisionInput = {
+  /** 当前上下文用量；undefined 表示读不到 */
+  tokens: number | undefined
+  lines: Lines
+  work: WorkState
+  /** 预计压缩后的大小（上次实测值，没有时用默认估计） */
+  expectedAfterTokens: number
+  paused: boolean
+}
+
+export type TurnEndDecision =
+  | { action: 'none'; reason: 'paused' | 'no-reading' | 'below-line' }
+  | { action: 'wait'; reason: HardSignal | 'insufficient-benefit' | 'waiting-for-milestone' }
+  | { action: 'compact'; reason: MilestoneSource | 'past-grace' }
+
+export type MidTurnDecision =
+  | { action: 'allow'; reason: 'paused' | 'no-reading' | 'at-ceiling' | 'default' }
+  | { action: 'veto'; reason: HardSignal | 'insufficient-benefit' }
+
+function freesEnough(tokens: number, input: DecisionInput, params: Params): boolean {
+  return tokens - input.expectedAfterTokens >= params.minFreedTokens
+}
+
+export function decideAtTurnEnd(input: DecisionInput, params: Params): TurnEndDecision {
+  const { tokens, lines, work } = input
+  if (input.paused) return { action: 'none', reason: 'paused' }
+  if (tokens === undefined) return { action: 'none', reason: 'no-reading' }
+  if (tokens < lines.allow) return { action: 'none', reason: 'below-line' }
+  const hard = hardSignal(work, params)
+  if (hard) return { action: 'wait', reason: hard }
+  if (!freesEnough(tokens, input, params)) return { action: 'wait', reason: 'insufficient-benefit' }
+  if (work.milestone) return { action: 'compact', reason: work.milestone }
+  if (tokens >= lines.midTurn) return { action: 'compact', reason: 'past-grace' }
+  return { action: 'wait', reason: 'waiting-for-milestone' }
+}
+
+/** 快到允许压缩线、本周期笔记没更新也没提醒过时，提醒模型更新笔记。 */
+export function shouldNudge(
+  input: { tokens: number | undefined; lines: Lines; notesUpdated: boolean; nudged: boolean; paused: boolean },
+  params: Params,
+): boolean {
+  if (input.paused || input.notesUpdated || input.nudged || input.tokens === undefined) return false
+  return input.tokens >= input.lines.allow * params.nudgeAtShare
+}
+
+export function decideMidTurn(input: DecisionInput, params: Params): MidTurnDecision {
+  const { tokens, lines, work } = input
+  if (input.paused) return { action: 'allow', reason: 'paused' }
+  if (tokens === undefined) return { action: 'allow', reason: 'no-reading' }
+  // 用量读数不含最新的工具结果，接近上限时留出余量，绝不挡住快满时的压缩。
+  if (tokens >= lines.ceiling - params.ceilingMarginTokens) return { action: 'allow', reason: 'at-ceiling' }
+  const hard = hardSignal(work, params)
+  if (hard) return { action: 'veto', reason: hard }
+  if (!freesEnough(tokens, input, params)) return { action: 'veto', reason: 'insufficient-benefit' }
+  return { action: 'allow', reason: 'default' }
+}

package/plugin/src/core/ledger.ts

@@ -0,0 +1,159 @@
+// 进度笔记：程序自动记录的事实 + 模型通过 checkpoint 补充的内容。
+// core 只负责内容和排版，怎么补回上下文由适配层决定。
+
+export type LedgerFacts = {
+  filesChanged: string[]
+  lastTest?: { command: string; passed: boolean }
+  lastBuild?: { command: string; passed: boolean }
+  lastCommit?: { summary: string }
+  tasksInProgress: string[]
+}
+
+export type LedgerNotes = {
+  goal?: string
+  decisions: string[]
+  next?: string
+  current?: string
+}
+
+export type Ledger = { facts: LedgerFacts; notes: LedgerNotes }
+
+export const EMPTY_LEDGER: Ledger = Object.freeze({
+  facts: Object.freeze({ filesChanged: [], tasksInProgress: [] }),
+  notes: Object.freeze({ decisions: [] }),
+}) as Ledger
+
+/** 笔记文本的开头，适配层据此认出上一次放入的笔记并替换。 */
+export const LEDGER_MARKER = '[SmartCompact progress ledger]'
+
+/**
+ * 插件发起压缩时给摘要的说明。用户顺口交代的具体信息（人名、日期、编号）当下代码用不到，
+ * 摘要最容易丢，进度笔记也不记，所以要明确要求原样保留。
+ */
+export const COMPACT_INSTRUCTIONS =
+  'Preserve the current goal, decisions and their reasons, unfinished work, failed attempts, and exact file paths. ' +
+  'Also keep every specific fact the user stated, verbatim, even if the current work does not need it: ' +
+  'names of people and customers, dates and time windows, ticket or ID numbers, and constraints. ' +
+  'A SmartCompact progress ledger is attached after the summary; do not restate it.'
+
+const MAX_FILES = 30
+const MAX_DECISIONS = 20
+const MAX_FIELD_CHARS = 1_000
+
+export function recordFileChanged(ledger: Ledger, path: string): Ledger {
+  const files = [...ledger.facts.filesChanged.filter(file => file !== path), path].slice(-MAX_FILES)
+  return { ...ledger, facts: { ...ledger.facts, filesChanged: files } }
+}
+
+export function recordTest(ledger: Ledger, command: string, passed: boolean): Ledger {
+  return { ...ledger, facts: { ...ledger.facts, lastTest: { command, passed } } }
+}
+
+export function recordBuild(ledger: Ledger, command: string, passed: boolean): Ledger {
+  return { ...ledger, facts: { ...ledger.facts, lastBuild: { command, passed } } }
+}
+
+export function recordCommit(ledger: Ledger, summary: string): Ledger {
+  return { ...ledger, facts: { ...ledger.facts, lastCommit: { summary } } }
+}
+
+export function recordTasksInProgress(ledger: Ledger, tasks: readonly string[]): Ledger {
+  return { ...ledger, facts: { ...ledger.facts, tasksInProgress: [...tasks] } }
+}
+
+export type CheckpointInput = {
+  goal?: string
+  decisions?: string[]
+  next?: string
+  current?: string
+  /** 模型声明刚完成一块工作 */
+  milestone?: boolean
+}
+
+/** checkpoint 工具的输入 schema，适配层注册工具时使用。 */
+export const CHECKPOINT_INPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    goal: { type: 'string', description: 'The overall goal of the current work.' },
+    decisions: { type: 'array', items: { type: 'string' }, description: 'Decisions made since the last checkpoint.' },
+    next: { type: 'string', description: 'What to do next.' },
+    current: { type: 'string', description: 'Where the work stands right now.' },
+    milestone: { type: 'boolean', description: 'True when a piece of work was just finished.' },
+  },
+  additionalProperties: false,
+} as const
+
+export type CheckpointParse = { ok: true; value: CheckpointInput } | { ok: false; error: string }
+
+const text = (value: unknown): value is string => typeof value === 'string' && value.trim().length > 0
+const clip = (value: string): string => value.trim().slice(0, MAX_FIELD_CHARS)
+
+export function parseCheckpoint(raw: unknown): CheckpointParse {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { ok: false, error: 'input must be an object' }
+  const input = raw as Record<string, unknown>
+  const value: CheckpointInput = {}
+  for (const key of ['goal', 'next', 'current'] as const) {
+    const field = input[key]
+    if (field === undefined) continue
+    if (!text(field)) return { ok: false, error: `${key} must be a non-empty string` }
+    value[key] = clip(field)
+  }
+  const { decisions, milestone } = input
+  if (decisions !== undefined) {
+    if (!Array.isArray(decisions) || !decisions.every(text)) {
+      return { ok: false, error: 'decisions must be an array of non-empty strings' }
+    }
+    value.decisions = decisions.map(clip)
+  }
+  if (milestone !== undefined) {
+    if (typeof milestone !== 'boolean') return { ok: false, error: 'milestone must be a boolean' }
+    value.milestone = milestone
+  }
+  if (!value.goal && !value.next && !value.current && !value.decisions?.length) {
+    return { ok: false, error: 'record at least one of goal, decisions, next, current' }
+  }
+  return { ok: true, value }
+}
+
+export function applyCheckpoint(ledger: Ledger, input: CheckpointInput): Ledger {
+  const decisions = [...ledger.notes.decisions, ...(input.decisions ?? [])]
+  return {
+    ...ledger,
+    notes: {
+      goal: input.goal ?? ledger.notes.goal,
+      next: input.next ?? ledger.notes.next,
+      current: input.current ?? ledger.notes.current,
+      decisions: [...new Set(decisions)].slice(-MAX_DECISIONS),
+    },
+  }
+}
+
+/** 排版成补回上下文的文本，超长时截断。 */
+export function renderLedger(ledger: Ledger, maxChars: number): string {
+  const { facts, notes } = ledger
+  const lines = [
+    LEDGER_MARKER,
+    'Generated by the SmartCompact plugin to keep continuity across compaction. It is not a message from the user.',
+  ]
+  const section = (title: string, body: (string | undefined)[]) => {
+    const rows = body.filter((row): row is string => Boolean(row))
+    if (rows.length) lines.push('', `## ${title}`, ...rows)
+  }
+  section('Goal', [notes.goal])
+  section('Current state', [notes.current])
+  section('Next', [notes.next])
+  section('Decisions', notes.decisions.map(decision => `- ${decision}`))
+  section('Tasks in progress', facts.tasksInProgress.map(task => `- ${task}`))
+  section('Files changed', facts.filesChanged.map(file => `- ${file}`))
+  section('Latest results', [
+    facts.lastTest && `- tests ${facts.lastTest.passed ? 'passed' : 'FAILED'}: ${facts.lastTest.command}`,
+    facts.lastBuild && `- build ${facts.lastBuild.passed ? 'passed' : 'FAILED'}: ${facts.lastBuild.command}`,
+    facts.lastCommit && `- last commit: ${facts.lastCommit.summary}`,
+  ])
+  const rendered = lines.join('\n')
+  return rendered.length <= maxChars ? rendered : `${rendered.slice(0, maxChars - 20)}\n…(truncated)`
+}
+
+export function isLedgerText(value: string): boolean {
+  return value.startsWith(LEDGER_MARKER)
+}

package/plugin/src/core/lines.ts

@@ -0,0 +1,31 @@
+// 三条线：允许压缩线 L、轮中兜底线 M、上限 C（原生压缩点）。
+
+import type { Params } from './params.ts'
+
+export type Lines = {
+  allow: number
+  midTurn: number
+  ceiling: number
+  /** false 表示窗口本身放不下 L 和 M，插件不调整原生压缩线，只负责进度笔记 */
+  adjustsNative: boolean
+}
+
+/** CLAUDE_CODE_AUTO_COMPACT_WINDOW 允许的最小值 */
+export const MIN_NATIVE_SETTING = 100_000
+
+/**
+ * @param nativeSettingTokens 插件调整之前，原生压缩线的设定值（窗口或用户自己的配置）
+ */
+export function planLines(nativeSettingTokens: number, params: Params): Lines {
+  const ceiling = nativeSettingTokens - params.nativeBufferTokens
+  const allow = params.allowLineTokens
+  // 原生压缩线设定值有下限，M 不会低于它对应的触发点，否则算出的 M 与原生实际行为不符。
+  const midTurn = Math.max(Math.round(allow * params.graceFactor), MIN_NATIVE_SETTING - params.nativeBufferTokens)
+  if (midTurn >= ceiling) return { allow, midTurn: ceiling, ceiling, adjustsNative: false }
+  return { allow, midTurn, ceiling, adjustsNative: true }
+}
+
+/** 让原生自动压缩从 M 开始尝试，需要写入的压缩线设定值。 */
+export function nativeSettingFor(lines: Lines, params: Params): number {
+  return lines.midTurn + params.nativeBufferTokens
+}

package/plugin/src/core/params.ts

@@ -0,0 +1,56 @@
+// 决策用到的全部参数。规则里不写死数字，试用后按数据校准，也可由用户配置覆盖。
+
+export type Params = {
+  /** 允许压缩线 L：一轮结束时超过它才考虑压缩 */
+  allowLineTokens: number
+  /** 轮中兜底线 M = L × graceFactor */
+  graceFactor: number
+  /** 一次压缩至少要腾出的空间，不够就不压，防止连续压缩 */
+  minFreedTokens: number
+  /** 还没实测到压缩后大小时，用这个估计值 */
+  defaultAfterTokens: number
+  /** 原生触发点 ≈ 压缩线设定值 − 这个值（实测约 33k） */
+  nativeBufferTokens: number
+  /** 用量读数可能落后于最新的工具结果，接近上限时留出的余量 */
+  ceilingMarginTokens: number
+  /** 连续报错多少次算硬信号 */
+  errorStreakLimit: number
+  /** 进度笔记的最大字符数 */
+  ledgerMaxChars: number
+  /** 用量到 L × 这个比例、笔记又没更新时，提醒模型记一下 */
+  nudgeAtShare: number
+}
+
+export const DEFAULT_PARAMS: Params = Object.freeze({
+  allowLineTokens: 200_000,
+  graceFactor: 1.3,
+  minFreedTokens: 60_000,
+  defaultAfterTokens: 50_000,
+  nativeBufferTokens: 33_000,
+  ceilingMarginTokens: 50_000,
+  errorStreakLimit: 3,
+  ledgerMaxChars: 6_000,
+  nudgeAtShare: 0.85,
+})
+
+const MINIMUMS: Record<keyof Params, number> = {
+  allowLineTokens: 1,
+  graceFactor: 1,
+  minFreedTokens: 0,
+  defaultAfterTokens: 0,
+  nativeBufferTokens: 0,
+  ceilingMarginTokens: 0,
+  errorStreakLimit: 1,
+  ledgerMaxChars: 200,
+  nudgeAtShare: 0,
+}
+
+/** 用户覆盖的值逐项校验，不合法的项沿用默认值。 */
+export function resolveParams(overrides: Readonly<Record<string, unknown>> = {}): Params {
+  const resolved = { ...DEFAULT_PARAMS }
+  for (const key of Object.keys(DEFAULT_PARAMS) as (keyof Params)[]) {
+    const value = overrides[key]
+    if (typeof value === 'number' && Number.isFinite(value) && value >= MINIMUMS[key]) resolved[key] = value
+  }
+  return resolved
+}

package/plugin/src/core/report.ts

@@ -0,0 +1,43 @@
+// /smartcompact report 的内容：当前状态、决策次数、信号次数、成本估算。只排版，不读写。
+
+import type { Lines } from './lines.ts'
+import type { DecisionLogEntry, SessionState } from './state.ts'
+import { savingsRatio } from './usage.ts'
+
+export type DecisionCounts = Record<string, number>
+
+/** 按"事件:动作"统计决策日志，例如 compacted:plugin、mid-turn:veto。 */
+export function countDecisions(entries: readonly DecisionLogEntry[]): DecisionCounts {
+  const counts: DecisionCounts = {}
+  for (const entry of entries) {
+    const key = entry.event === 'compacted' ? `compacted:${entry.action ?? entry.trigger ?? ''}` : `${entry.event}:${entry.action ?? ''}`
+    counts[key] = (counts[key] ?? 0) + 1
+  }
+  return counts
+}
+
+const k = (tokens: number | undefined): string => (tokens === undefined ? '—' : `${Math.round(tokens / 1000)}k`)
+
+export function renderReport(input: {
+  state: SessionState
+  lines: Lines
+  tokens: number | undefined
+  counts: DecisionCounts
+}): string {
+  const { state, lines, tokens, counts } = input
+  const ratio = savingsRatio(state.usage)
+  const seen = state.seen
+  return [
+    `SmartCompact${state.paused ? '（已暂停）' : ''}`,
+    `- 当前用量 ${k(tokens)}；允许压缩线 ${k(lines.allow)}，兜底线 ${k(lines.midTurn)}，上限 ${k(lines.ceiling)}${lines.adjustsNative ? '' : '（原生压缩线未调整）'}`,
+    `- 本会话压缩 ${state.compactions} 次；最近一次压缩后约 ${k(state.measuredAfterTokens)}`,
+    `- 本会话决策：插件压缩 ${(counts['compacted:plugin'] ?? 0) + (counts['compacted:plugin-queued'] ?? 0)}，自动压缩放行 ${counts['compacted:auto'] ?? 0}，手动压缩 ${counts['compacted:manual'] ?? 0}，轮中否决 ${counts['mid-turn:veto'] ?? 0}，轮末等待 ${counts['turn-end:wait'] ?? 0}`,
+    `- 信号：提交 ${seen.commit}，测试通过 ${seen['tests-passed']}，任务完成 ${seen['task-completed']}，checkpoint 完成 ${seen.checkpoint}，后台任务 ${seen.background}`,
+    `- 当前状态：${state.work.milestone ? `已到阶段节点（${state.work.milestone}）` : '等待阶段节点'}${state.work.testsFailing ? '，测试失败中' : ''}${state.work.buildFailing ? '，构建失败中' : ''}`,
+    ratio === undefined
+      ? '- 成本估算：还没有读数'
+      : `- 成本估算：上下文成本约节省 ${Math.round(ratio * 100)}%（${state.usage.samples} 次读数，已扣除压缩本身的开销；对比的是没有插件、一直涨到原生压缩点的情况）${
+          ratio < 0 ? '。刚压缩完时压缩开销还没赚回来，继续使用后会转正' : ''
+        }`,
+  ].join('\n')
+}

package/plugin/src/core/signals.ts

@@ -0,0 +1,79 @@
+// 信号词表与工作状态。适配层把平台事件翻译成这里的信号，core 不认识任何平台的工具名。
+
+import type { Params } from './params.ts'
+
+export type Signal =
+  | { kind: 'commit' }
+  | { kind: 'tests'; passed: boolean }
+  | { kind: 'build'; passed: boolean }
+  | { kind: 'task-completed' }
+  | { kind: 'checkpoint'; milestone: boolean }
+  | { kind: 'tool-result'; isError: boolean }
+  | { kind: 'background'; running: number }
+
+export type MilestoneSource = 'commit' | 'tests-passed' | 'task-completed' | 'checkpoint'
+
+export type HardSignal = 'tests-failing' | 'build-failing' | 'error-streak' | 'background-running'
+
+export type WorkState = {
+  /** 自上次压缩以来最近的阶段节点 */
+  milestone: MilestoneSource | null
+  testsFailing: boolean
+  buildFailing: boolean
+  errorStreak: number
+  backgroundRunning: number
+}
+
+export const INITIAL_WORK_STATE: WorkState = Object.freeze({
+  milestone: null,
+  testsFailing: false,
+  buildFailing: false,
+  errorStreak: 0,
+  backgroundRunning: 0,
+})
+
+/** 这个信号代表哪种阶段节点，不是阶段节点时为 null。 */
+export function milestoneOf(signal: Signal): MilestoneSource | null {
+  switch (signal.kind) {
+    case 'commit':
+      return 'commit'
+    case 'tests':
+      return signal.passed ? 'tests-passed' : null
+    case 'task-completed':
+      return 'task-completed'
+    case 'checkpoint':
+      return signal.milestone ? 'checkpoint' : null
+    default:
+      return null
+  }
+}
+
+export function applySignal(state: WorkState, signal: Signal): WorkState {
+  const next = { ...state, milestone: milestoneOf(signal) ?? state.milestone }
+  switch (signal.kind) {
+    case 'tests':
+      return { ...next, testsFailing: !signal.passed }
+    case 'build':
+      return { ...next, buildFailing: !signal.passed }
+    case 'tool-result':
+      return { ...next, errorStreak: signal.isError ? state.errorStreak + 1 : 0 }
+    case 'background':
+      return { ...next, backgroundRunning: Math.max(0, signal.running) }
+    default:
+      return next
+  }
+}
+
+/** 压缩后清空阶段节点；失败、后台任务这些仍然成立的事实保留。 */
+export function afterCompaction(state: WorkState): WorkState {
+  return { ...state, milestone: null }
+}
+
+/** 表明工作做到一半的硬信号，没有则返回 null。 */
+export function hardSignal(state: WorkState, params: Params): HardSignal | null {
+  if (state.testsFailing) return 'tests-failing'
+  if (state.buildFailing) return 'build-failing'
+  if (state.errorStreak >= params.errorStreakLimit) return 'error-streak'
+  if (state.backgroundRunning > 0) return 'background-running'
+  return null
+}

package/plugin/src/core/state.ts

@@ -0,0 +1,92 @@
+// 会话状态与决策日志的数据格式。读写由适配层负责，core 只定义格式。
+
+import { EMPTY_LEDGER, type Ledger } from './ledger.ts'
+import { afterCompaction, applySignal, INITIAL_WORK_STATE, milestoneOf, type MilestoneSource, type Signal, type WorkState } from './signals.ts'
+import { EMPTY_TALLY, type Prices, recordCompaction, recordSample, type UsageTally } from './usage.ts'
+
+export type SignalsSeen = Record<MilestoneSource | 'background', number>
+
+export type SessionState = {
+  work: WorkState
+  ledger: Ledger
+  /** 最近一次实测的压缩后大小 */
+  measuredAfterTokens?: number
+  compactions: number
+  paused: boolean
+  /** 自上次压缩以来，模型是否通过 checkpoint 更新过笔记 */
+  notesUpdated: boolean
+  /** 自上次压缩以来，是否提醒过模型更新笔记 */
+  nudged: boolean
+  /** 各种信号出现过的次数，用于确认识别是否生效 */
+  seen: SignalsSeen
+  usage: UsageTally
+}
+
+export const INITIAL_SESSION_STATE: SessionState = Object.freeze({
+  work: INITIAL_WORK_STATE,
+  ledger: EMPTY_LEDGER,
+  compactions: 0,
+  paused: false,
+  notesUpdated: false,
+  nudged: false,
+  seen: Object.freeze({ commit: 0, 'tests-passed': 0, 'task-completed': 0, checkpoint: 0, background: 0 }),
+  usage: EMPTY_TALLY,
+}) as SessionState
+
+/** 读回的状态结构不对时，从初始状态开始。 */
+export function parseState(raw: unknown): SessionState {
+  if (!raw || typeof raw !== 'object') return INITIAL_SESSION_STATE
+  const state = raw as Partial<SessionState>
+  if (!state.work || !state.ledger || !state.seen || !state.usage) return INITIAL_SESSION_STATE
+  return state as SessionState
+}
+
+export function expectedAfterTokens(state: SessionState, defaultAfterTokens: number): number {
+  return state.measuredAfterTokens ?? defaultAfterTokens
+}
+
+/** 应用信号，同时更新信号计数。 */
+export function withSignals(state: SessionState, signals: readonly Signal[]): SessionState {
+  const seen = { ...state.seen }
+  for (const signal of signals) {
+    const milestone = milestoneOf(signal)
+    if (milestone) seen[milestone] += 1
+    if (signal.kind === 'background' && signal.running > 0) seen.background += 1
+  }
+  return { ...state, work: signals.reduce(applySignal, state.work), seen }
+}
+
+/** 记一次用量读数：压缩后的第一次读数同时记为实测的压缩后大小。 */
+export function withSample(state: SessionState, tokens: number, ceiling: number, prices: Prices): SessionState {
+  const measured = state.usage.pending ? { measuredAfterTokens: tokens } : {}
+  return { ...state, ...measured, usage: recordSample(state.usage, tokens, ceiling, prices) }
+}
+
+/**
+ * 一次压缩完成：清空阶段节点和本周期的笔记标记，等待读到压缩后大小。
+ * @param attributed 是否算作插件带来的压缩；用户手动 /compact 没有插件时也会发生，不计入节省
+ */
+export function withCompaction(state: SessionState, before: number, summary: number, attributed = true): SessionState {
+  return {
+    ...state,
+    work: afterCompaction(state.work),
+    compactions: state.compactions + 1,
+    notesUpdated: false,
+    nudged: false,
+    usage: attributed ? recordCompaction(state.usage, before, summary) : state.usage,
+  }
+}
+
+export type DecisionLogEntry = {
+  at: string
+  /** 会话 ID，报告据此只统计当前会话 */
+  session?: string
+  event: 'setup' | 'turn-end' | 'mid-turn' | 'compacted' | 'checkpoint' | 'error'
+  action?: string
+  reason?: string
+  tokens?: number
+  tokensBefore?: number
+  tokensAfter?: number
+  trigger?: string
+  detail?: string
+}

package/plugin/src/core/usage.ts

@@ -0,0 +1,70 @@
+// 成本估算：把实际上下文和"没有插件时会是多大"逐次对比，并扣掉压缩本身的开销。
+// 单位都是"缓存读取 token"：每次调用的成本 ≈ 当时的上下文大小。
+
+/** 压缩摘要的输出价、压缩后新前缀的缓存写入价，各相当于缓存读取价的多少倍。 */
+export type Prices = { outputOverCacheRead: number; cacheWriteOverCacheRead: number }
+
+// Anthropic：缓存读取 0.1、1 小时缓存写入 2、输出 5（以输入价为 1）。
+const ANTHROPIC: Prices = Object.freeze({ outputOverCacheRead: 50, cacheWriteOverCacheRead: 20 })
+// OpenAI：缓存读取 0.1、写入不加价 1、输出 8。
+const OPENAI: Prices = Object.freeze({ outputOverCacheRead: 80, cacheWriteOverCacheRead: 10 })
+
+/**
+ * 按模型选价格比例，传入供应商名和模型名（例如 "github-copilot gpt-5"）。
+ * 不认识的按 Anthropic 算，压缩开销估得偏高、结论偏保守。
+ */
+export function pricesFor(model: string): Prices {
+  return /openai|codex|gpt|\bo[134]\b/i.test(model) ? OPENAI : ANTHROPIC
+}
+
+export type UsageTally = {
+  /** 计入的读数次数 */
+  samples: number
+  /** 实际上下文之和 */
+  sumTokens: number
+  /** 没有插件时上下文之和 */
+  sumBaseline: number
+  /** 本插件压缩累计腾出的空间：没有插件时的上下文 = 实际 + freed */
+  freed: number
+  /** 压缩本身的开销之和 */
+  overhead: number
+  lastTokens?: number
+  /** 刚压缩完、还没读到压缩后大小时，记下压缩前大小和摘要长度 */
+  pending?: { before: number; summary: number }
+}
+
+export const EMPTY_TALLY: UsageTally = Object.freeze({ samples: 0, sumTokens: 0, sumBaseline: 0, freed: 0, overhead: 0 })
+
+export function recordCompaction(tally: UsageTally, before: number, summary: number): UsageTally {
+  return { ...tally, pending: { before, summary } }
+}
+
+/**
+ * 记一次用量读数。同一次调用可能读到多次（并行的工具调用），和上一次相同的读数不重复计入。
+ * @param ceiling 原生压缩点：没有插件时上下文超过它，原生也会压缩
+ */
+export function recordSample(tally: UsageTally, tokens: number, ceiling: number, prices: Prices): UsageTally {
+  if (tokens === tally.lastTokens) return tally
+  let { freed, overhead } = tally
+  if (tally.pending) {
+    const { before, summary } = tally.pending
+    freed += Math.max(0, before - tokens)
+    overhead += before + prices.outputOverCacheRead * summary + prices.cacheWriteOverCacheRead * tokens
+  }
+  // 没有插件时，涨过原生压缩点也会被压缩，之后两边大小相近。
+  if (tokens + freed > ceiling) freed = 0
+  return {
+    samples: tally.samples + 1,
+    sumTokens: tally.sumTokens + tokens,
+    sumBaseline: tally.sumBaseline + tokens + freed,
+    freed,
+    overhead,
+    lastTokens: tokens,
+  }
+}
+
+/** 估算节省的比例：1 − (实际 + 压缩开销) / 没有插件时。没有读数时为 undefined。 */
+export function savingsRatio(tally: UsageTally): number | undefined {
+  if (tally.sumBaseline <= 0) return undefined
+  return 1 - (tally.sumTokens + tally.overhead) / tally.sumBaseline
+}