smartcompact 0.1.4 → 0.1.6

package/README.md

@@ -13,7 +13,7 @@
 
 Every request re-reads the whole context, so a long context makes every step expensive. Native auto-compaction waits until the context is nearly full (close to 1M tokens in Claude Code, up to 800k in Codex if configured), and it ignores timing, so it often lands in the middle of a task. SmartCompact works with Claude Code (CLI and desktop app), [Pi](https://github.com/earendil-works/pi) and the Codex CLI:
 
-- **Compact at a good moment.** Once the context passes the **allow line** (200k tokens by default), it compacts when a turn ends, if a piece of work has been finished since the last compaction (a commit, tests passing, a task completed).
+- **Compact at a good moment.** Once the context passes the **allow line** (200k tokens by default), it compacts when a turn ends, if a piece of work has been finished since the last compaction (a commit, tests passing, a task completed) and no file has been changed since.
 - **Never in the middle of work.** It only decides when a turn ends, never mid-turn, and it waits while tests or the build are failing or errors keep repeating.
 - **No limit of its own.** If no piece of work gets finished, the agent is usually deep in one large task, which is when a large context pays off. SmartCompact leaves it alone, and the platform's native compaction applies as it would without the plugin.
 - **A progress ledger bridges the gap.** Files changed, the latest commit and test result, and decisions the agent recorded are handed back to the model after compaction.
@@ -80,7 +80,7 @@ Codex hooks cannot postpone a compaction in the middle of a turn, so SmartCompac
 
 ## FAQ
 
-**How does it know a piece of work is finished?** From the commands the agent runs. Any finished piece of work since the last compaction counts, not only one in the current turn: the end of a turn is already a pause, so waiting for the next commit would mostly just cost more. A commit counts if `git commit` actually ran and the tool call did not fail. A test command piped into something else (`| tail`) without `pipefail` does not count, since its exit code cannot be trusted.
+**How does it know a piece of work is finished?** From the commands the agent runs. Any finished piece of work since the last compaction counts, not only one in the current turn: the end of a turn is already a pause, so waiting for the next commit would mostly just cost more. Once files are changed again after it, the next piece of work has started, and SmartCompact waits for that one to finish. A commit counts if `git commit` actually ran and the tool call did not fail. A test command piped into something else (`| tail`) without `pipefail` does not count, since its exit code cannot be trusted.
 
 **Will the model forget things after compaction?** Sometimes, for details mentioned in passing. The ledger only records files, commits, tests and decisions the model chose to record. Details the user mentions in passing are kept by asking the compaction summary to keep every specific fact the user stated. On Pi this clearly reduced losses, but it is not a guarantee.
 

package/README.zh-CN.md

@@ -13,7 +13,7 @@
 
 agent 每发一次请求，都要把整段上下文重新读一遍，上下文越长，每一步越贵。原生的自动压缩要等到快满了才触发（Claude Code 接近 100 万，Codex 可以配到 80 万），而且不看时机，常常发生在一件事做到一半的时候。SmartCompact 支持 Claude Code（终端和桌面 App）、[Pi](https://github.com/earendil-works/pi) 和 Codex 命令行：
 
-- **挑对时机压缩。** 上下文超过**允许压缩线**（默认 20 万）以后，只要上次压缩以来做完过一件事（一次提交、测试通过、任务完成），就在这一轮结束时压缩。
+- **挑对时机压缩。** 上下文超过**允许压缩线**（默认 20 万）以后，只要上次压缩以来做完过一件事（一次提交、测试通过、任务完成），之后又没开始改文件，就在这一轮结束时压缩。
 - **不在做到一半时压缩。** 只在一轮结束时判断，从不在一轮中间主动压缩；测试失败、构建失败或连续报错时先等着。
 - **不设自己的上限。** 一直没做完一件事，多半是在干一件大活，这时正需要大上下文。插件不去打断，压缩按平台原生规则来，和没装插件时一样。
 - **用进度笔记接上。** 改过的文件、最近的提交和测试结果、记下的决定，压缩后补回给模型。
@@ -80,7 +80,7 @@ Codex 的 hook 不能推迟一轮中间的压缩，所以插件在一轮结束
 
 ## 常见问题
 
-**怎么判断"做完一件事"？** 靠识别 agent 执行的命令。看的是上次压缩以来有没有做完过一件事，不要求正好在这一轮：一轮结束本身就是停顿点，非要等下一次提交，多半只是多花钱。提交只要真的执行了 `git commit` 且工具调用没报错就算；测试命令接了管道（`| tail`）又没开 `pipefail` 时退出码不可信，不算测试结果。
+**怎么判断"做完一件事"？** 靠识别 agent 执行的命令。看的是上次压缩以来有没有做完过一件事，不要求正好在这一轮：一轮结束本身就是停顿点，非要等下一次提交，多半只是多花钱。但做完之后又开始改文件，就算在做下一件事，要等它做完。提交只要真的执行了 `git commit` 且工具调用没报错就算；测试命令接了管道（`| tail`）又没开 `pipefail` 时退出码不可信，不算测试结果。
 
 **压缩后模型会不会忘事？** 随口提到的细节有时会丢。进度笔记只记文件、提交、测试和模型主动记下的决定。用户在对话里随口交代的细节，靠压缩时要求摘要原样保留用户说过的具体信息。Pi 上这样做明显减少了丢失，但不能保证不丢。
 

package/adapters/pi/index.ts

@@ -12,6 +12,7 @@ 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 {
+  cycleReads,
   type DecisionLogEntry,
   expectedAfterTokens,
   growthSinceMilestone,
@@ -19,6 +20,7 @@ import {
   parseState,
   type SessionState,
   withCompaction,
+  withRead,
   withSample,
   withSignals,
 } from '../../plugin/src/core/state.ts'
@@ -163,8 +165,9 @@ export default function smartCompact(pi: ExtensionAPI) {
     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)
+    const { signals, ledger, read } = recognizePi({ toolName: event.toolName, input: event.input, isError: event.isError, text }, state.ledger)
     state = withSignals({ ...state, ledger }, signals)
+    if (read) state = withRead(state, read)
   })
 
   pi.on('before_agent_start', async (_event, ctx) => {
@@ -216,10 +219,11 @@ export default function smartCompact(pi: ExtensionAPI) {
     const fromPlugin = event.reason === 'manual' && ours
     ours = false
     const summaryTokens = Math.round(event.compactionEntry.summary.length / 4)
+    const reads = cycleReads(state)
     // 原生按阈值的压缩、溢出恢复和用户的 /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 })
+    log({ event: 'compacted', trigger: fromPlugin ? 'plugin' : event.reason === 'threshold' ? 'auto' : event.reason, tokensBefore: event.compactionEntry.tokensBefore, ...reads })
     pi.sendMessage(
       { customType: LEDGER_MESSAGE, content: renderLedger(state.ledger, params(ctx).ledgerMaxChars), display: false },
       { deliverAs: ctx.isIdle() ? 'nextTurn' : 'steer' },

package/adapters/pi/recognize.ts

@@ -14,17 +14,19 @@ export type PiToolOutcome = {
 
 const EDIT_TOOLS = new Set(['edit', 'write'])
 
-export function recognizePi(outcome: PiToolOutcome, ledger: Ledger): { signals: Signal[]; ledger: Ledger } {
+export function recognizePi(outcome: PiToolOutcome, ledger: Ledger): { signals: Signal[]; ledger: Ledger; read?: string } {
   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)
+    signals.push({ kind: 'file-changed' })
   }
   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 }
+  const read = outcome.toolName === 'read' && !outcome.isError && typeof path === 'string' && path ? path : undefined
+  return { signals, ledger: next, read }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smartcompact",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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",

package/plugin/src/core/decide.ts

@@ -17,7 +17,7 @@ export type DecisionInput = {
 
 export type TurnEndDecision =
   | { action: 'none'; reason: 'paused' | 'no-reading' | 'below-line' }
-  | { action: 'wait'; reason: HardSignal | 'insufficient-benefit' | 'waiting-for-milestone' }
+  | { action: 'wait'; reason: HardSignal | 'insufficient-benefit' | 'changed-since-milestone' | 'waiting-for-milestone' }
   | { action: 'compact'; reason: MilestoneSource }
 
 export type MidTurnDecision =
@@ -36,7 +36,9 @@ export function decideAtTurnEnd(input: DecisionInput, params: Params): TurnEndDe
   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 (work.milestone && !work.changedSinceMilestone) return { action: 'compact', reason: work.milestone }
+  // 做完一件事之后又改了文件，已经在做下一件事，等它做完。
+  if (work.milestone) return { action: 'wait', reason: 'changed-since-milestone' }
   // 不设兜底线：一直等不到做完一件事，多半是在做一件大活，正需要大上下文；交给原生在上限处压缩。
   return { action: 'wait', reason: 'waiting-for-milestone' }
 }

package/plugin/src/core/ledger.ts

@@ -128,9 +128,20 @@ export function applyCheckpoint(ledger: Ledger, input: CheckpointInput): Ledger
   }
 }
 
-/** 排版成补回上下文的文本，超长时截断。 */
+/** 排版成补回上下文的文本，超长时先丢最旧的决定、再丢最早改过的文件，仍超长才截断。 */
 export function renderLedger(ledger: Ledger, maxChars: number): string {
-  const { facts, notes } = ledger
+  let decisions = ledger.notes.decisions
+  let files = ledger.facts.filesChanged
+  let rendered = layoutLedger(ledger, decisions, files)
+  while (rendered.length > maxChars && (decisions.length || files.length)) {
+    if (decisions.length) decisions = decisions.slice(1)
+    else files = files.slice(1)
+    rendered = layoutLedger(ledger, decisions, files)
+  }
+  return rendered.length <= maxChars ? rendered : `${rendered.slice(0, maxChars - 20)}\n…(truncated)`
+}
+
+function layoutLedger({ facts, notes }: Ledger, decisions: readonly string[], files: readonly string[]): string {
   const lines = [
     LEDGER_MARKER,
     'Generated by the SmartCompact plugin to keep continuity across compaction. It is not a message from the user.',
@@ -139,19 +150,19 @@ export function renderLedger(ledger: Ledger, maxChars: number): string {
     const rows = body.filter((row): row is string => Boolean(row))
     if (rows.length) lines.push('', `## ${title}`, ...rows)
   }
+  const omitted = (dropped: number, what: string) => (dropped ? `- …(${dropped} earlier ${what} omitted)` : undefined)
   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)`
+  section('Tasks in progress', facts.tasksInProgress.map(task => `- ${task}`))
+  section('Decisions', [omitted(notes.decisions.length - decisions.length, 'decisions'), ...decisions.map(decision => `- ${decision}`)])
+  section('Files changed', [omitted(facts.filesChanged.length - files.length, 'files'), ...files.map(file => `- ${file}`)])
+  return lines.join('\n')
 }
 
 export function isLedgerText(value: string): boolean {

package/plugin/src/core/report.ts

@@ -1,6 +1,7 @@
 // /smartcompact report 的内容：当前状态、决策次数、信号次数、成本估算。只排版，不读写。
 
 import type { Lines } from './lines.ts'
+import type { WorkState } from './signals.ts'
 import type { DecisionLogEntry, SessionState } from './state.ts'
 import { savingsRatio } from './usage.ts'
 
@@ -18,6 +19,9 @@ export function countDecisions(entries: readonly DecisionLogEntry[]): DecisionCo
 
 const k = (tokens: number | undefined): string => (tokens === undefined ? '—' : `${Math.round(tokens / 1000)}k`)
 
+const milestoneStatus = (work: WorkState): string =>
+  !work.milestone ? '等待阶段节点' : work.changedSinceMilestone ? `上一件事已做完（${work.milestone}），之后又改了文件，等这件事做完` : `已到阶段节点（${work.milestone}）`
+
 export function renderReport(input: {
   state: SessionState
   lines: Lines
@@ -33,7 +37,7 @@ export function renderReport(input: {
     `- 本会话压缩 ${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}`,
-    `- 当前状态：${state.work.milestone ? `已到阶段节点（${state.work.milestone}）` : '等待阶段节点'}${state.work.testsFailing ? '，测试失败中' : ''}${state.work.buildFailing ? '，构建失败中' : ''}`,
+    `- 当前状态：${milestoneStatus(state.work)}${state.work.testsFailing ? '，测试失败中' : ''}${state.work.buildFailing ? '，构建失败中' : ''}`,
     ratio === undefined
       ? '- 成本估算：还没有读数'
       : `- 成本估算：上下文成本约节省 ${Math.round(ratio * 100)}%（${state.usage.samples} 次读数，已扣除压缩本身的开销；对比的是没有插件、一直涨到原生压缩点的情况）${

package/plugin/src/core/signals.ts

@@ -9,6 +9,7 @@ export type Signal =
   | { kind: 'task-completed' }
   | { kind: 'checkpoint'; milestone: boolean }
   | { kind: 'tool-result'; isError: boolean }
+  | { kind: 'file-changed' }
 
 export type MilestoneSource = 'commit' | 'tests-passed' | 'task-completed' | 'checkpoint'
 
@@ -19,6 +20,8 @@ export type WorkState = {
   milestone: MilestoneSource | null
   /** 最近的阶段节点出现时的上下文用量，用来看它到压缩时隔了多远 */
   milestoneTokens?: number
+  /** 最近的阶段节点之后又改过文件：已经开始下一件事，这个阶段节点不再算数 */
+  changedSinceMilestone?: boolean
   testsFailing: boolean
   buildFailing: boolean
   errorStreak: number
@@ -26,6 +29,7 @@ export type WorkState = {
 
 export const INITIAL_WORK_STATE: WorkState = Object.freeze({
   milestone: null,
+  changedSinceMilestone: false,
   testsFailing: false,
   buildFailing: false,
   errorStreak: 0,
@@ -50,7 +54,7 @@ export function milestoneOf(signal: Signal): MilestoneSource | null {
 export function applySignal(state: WorkState, signal: Signal): WorkState {
   const milestone = milestoneOf(signal)
   // 失败之后又做完了一件事（比如提交、checkpoint），那段失败就算过去了，不再挡着压缩。
-  const next = milestone ? { ...state, milestone, testsFailing: false, buildFailing: false } : state
+  const next = milestone ? { ...state, milestone, changedSinceMilestone: false, testsFailing: false, buildFailing: false } : state
   switch (signal.kind) {
     case 'tests':
       return { ...next, testsFailing: !signal.passed }
@@ -58,6 +62,9 @@ export function applySignal(state: WorkState, signal: Signal): WorkState {
       return { ...next, buildFailing: !signal.passed }
     case 'tool-result':
       return { ...next, errorStreak: signal.isError ? state.errorStreak + 1 : 0 }
+    // 做完一件事之后又改文件，说明已经开始下一件事，要等它做完。
+    case 'file-changed':
+      return next.milestone ? { ...next, changedSinceMilestone: true } : next
     default:
       return next
   }
@@ -65,7 +72,7 @@ export function applySignal(state: WorkState, signal: Signal): WorkState {
 
 /** 压缩后清空阶段节点；失败这些仍然成立的事实保留。 */
 export function afterCompaction(state: WorkState): WorkState {
-  return { ...state, milestone: null, milestoneTokens: undefined }
+  return { ...state, milestone: null, milestoneTokens: undefined, changedSinceMilestone: false }
 }
 
 /** 表明工作做到一半的硬信号，没有则返回 null。 */

package/plugin/src/core/state.ts

@@ -20,8 +20,24 @@ export type SessionState = {
   /** 各种信号出现过的次数，用于确认识别是否生效 */
   seen: SignalsSeen
   usage: UsageTally
+  /** 读文件的统计；平台认不出读文件时没有这一项 */
+  reads?: ReadStats
 }
 
+/** 用来看压缩后要花多少次读取重新熟悉代码。 */
+export type ReadStats = {
+  /** 上次压缩之前读过或改过的文件 */
+  known: string[]
+  /** 上次压缩以来读过的文件 */
+  current: string[]
+  /** 上次压缩以来读文件的次数 */
+  reads: number
+  /** 其中读的是压缩前已经看过的文件 */
+  rereads: number
+}
+
+const MAX_KNOWN_FILES = 300
+
 export const INITIAL_SESSION_STATE: SessionState = Object.freeze({
   work: INITIAL_WORK_STATE,
   ledger: EMPTY_LEDGER,
@@ -73,8 +89,15 @@ export function withSample(state: SessionState, tokens: number, ceiling: number,
  * @param attributed 是否算作插件带来的压缩；用户手动 /compact 没有插件时也会发生，不计入节省
  */
 export function withCompaction(state: SessionState, before: number, summary: number, attributed = true): SessionState {
+  const reads = state.reads && {
+    known: [...new Set([...state.reads.known, ...state.reads.current, ...state.ledger.facts.filesChanged])].slice(-MAX_KNOWN_FILES),
+    current: [],
+    reads: 0,
+    rereads: 0,
+  }
   return {
     ...state,
+    ...(reads && { reads }),
     work: afterCompaction(state.work),
     compactions: state.compactions + 1,
     notesUpdated: false,
@@ -83,6 +106,25 @@ export function withCompaction(state: SessionState, before: number, summary: num
   }
 }
 
+/** 记一次读文件：读的是上次压缩前看过的文件就算重读。 */
+export function withRead(state: SessionState, path: string): SessionState {
+  const stats = state.reads ?? { known: [], current: [], reads: 0, rereads: 0 }
+  return {
+    ...state,
+    reads: {
+      known: stats.known,
+      current: [...stats.current.filter(file => file !== path), path].slice(-MAX_KNOWN_FILES),
+      reads: stats.reads + 1,
+      rereads: stats.rereads + (stats.known.includes(path) ? 1 : 0),
+    },
+  }
+}
+
+/** 压缩时记进日志的本周期读文件次数；平台认不出读文件时为空。 */
+export function cycleReads(state: SessionState): Pick<DecisionLogEntry, 'reads' | 'rereads'> {
+  return state.reads ? { reads: state.reads.reads, rereads: state.reads.rereads } : {}
+}
+
 export type DecisionLogEntry = {
   at: string
   /** 会话 ID，报告据此只统计当前会话 */
@@ -95,6 +137,9 @@ export type DecisionLogEntry = {
   tokensAfter?: number
   /** 决定压缩时，距离最近的阶段节点上下文涨了多少 */
   sinceMilestoneTokens?: number
+  /** 压缩时：上次压缩以来读文件的次数，以及其中重读压缩前看过的文件的次数 */
+  reads?: number
+  rereads?: number
   trigger?: string
   detail?: string
 }