smartcompact 0.1.5 → 0.1.7

package/README.md

@@ -13,10 +13,10 @@
 
 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.
+- **A progress ledger bridges the gap.** Files changed, the latest commit and test result, and the user requirements and decisions the agent recorded are handed back to the model after compaction.
 - **No pointless compactions.** It skips compaction when it would not free enough space.
 
 ## Results
@@ -75,14 +75,14 @@ Codex hooks cannot postpone a compaction in the middle of a turn, so SmartCompac
 
 ## Seeing what it did
 
-- Claude Code and Pi: `/smartcompact` (or `/smartcompact report`) shows the allow line, the native compaction point, the finished-work signals it saw and a cost estimate; `/smartcompact pause` and `resume` turn it off and on for the session. The model can also call a `checkpoint` tool to record decisions, which come back with the ledger after compaction.
+- Claude Code and Pi: `/smartcompact` (or `/smartcompact report`) shows the allow line, the native compaction point, the finished-work signals it saw and a cost estimate; `/smartcompact pause` and `resume` turn it off and on for the session. The model can also call a `checkpoint` tool to record the user's requirements and decisions, which come back with the ledger after compaction.
 - Codex: `node ~/.codex/plugins/cache/smartcompact/smartcompact/<version>/adapters/codex/report.ts <session ID>` (Node.js 22.18+); records are kept in `~/.codex/smartcompact/`.
 
 ## 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.
+**Will the model forget things after compaction?** Sometimes, for details mentioned in passing. The ledger only records files, commits, tests and the requirements and decisions the model chose to record; user requirements have their own section, so later notes do not push them out, and only the oldest are dropped once there are more than 30. 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.
 
 **Does it change Claude Code's own settings?** No. Native auto-compaction stays where it is (close to 1M). Versions up to 0.1.2 moved it to about 260k by setting `CLAUDE_CODE_AUTO_COMPACT_WINDOW` in the session (which child processes inherited) and also compacted there without a finished piece of work. 0.1.3 removed both: a long task is no longer cut off at a fixed size. A session opened on 0.1.2 or earlier keeps the old setting until you start a new one.
 

package/README.zh-CN.md

@@ -13,10 +13,10 @@
 
 agent 每发一次请求，都要把整段上下文重新读一遍，上下文越长，每一步越贵。原生的自动压缩要等到快满了才触发（Claude Code 接近 100 万，Codex 可以配到 80 万），而且不看时机，常常发生在一件事做到一半的时候。SmartCompact 支持 Claude Code（终端和桌面 App）、[Pi](https://github.com/earendil-works/pi) 和 Codex 命令行：
 
-- **挑对时机压缩。** 上下文超过**允许压缩线**（默认 20 万）以后，只要上次压缩以来做完过一件事（一次提交、测试通过、任务完成），就在这一轮结束时压缩。
+- **挑对时机压缩。** 上下文超过**允许压缩线**（默认 20 万）以后，只要上次压缩以来做完过一件事（一次提交、测试通过、任务完成），之后又没开始改文件，就在这一轮结束时压缩。
 - **不在做到一半时压缩。** 只在一轮结束时判断，从不在一轮中间主动压缩；测试失败、构建失败或连续报错时先等着。
 - **不设自己的上限。** 一直没做完一件事，多半是在干一件大活，这时正需要大上下文。插件不去打断，压缩按平台原生规则来，和没装插件时一样。
-- **用进度笔记接上。** 改过的文件、最近的提交和测试结果、记下的决定，压缩后补回给模型。
+- **用进度笔记接上。** 改过的文件、最近的提交和测试结果、记下的用户要求和决定，压缩后补回给模型。
 - **不做白费的压缩。** 预计腾不出足够空间时不压缩，避免刚压缩完又压缩。
 
 ## 实验结果
@@ -75,14 +75,14 @@ Codex 的 hook 不能推迟一轮中间的压缩，所以插件在一轮结束
 
 ## 查看效果
 
-- Claude Code 和 Pi：`/smartcompact`（或 `/smartcompact report`）查看允许压缩线、原生压缩点、识别到的阶段节点和成本估算；`/smartcompact pause` / `resume` 暂停或恢复当前会话。模型还可以调用 `checkpoint` 工具记下决定，压缩后和进度笔记一起补回。
+- Claude Code 和 Pi：`/smartcompact`（或 `/smartcompact report`）查看允许压缩线、原生压缩点、识别到的阶段节点和成本估算；`/smartcompact pause` / `resume` 暂停或恢复当前会话。模型还可以调用 `checkpoint` 工具记下用户的要求和决定，压缩后和进度笔记一起补回。
 - Codex：`node ~/.codex/plugins/cache/smartcompact/smartcompact/<版本>/adapters/codex/report.ts <会话 ID>`（Node.js 22.18 及以上），记录在 `~/.codex/smartcompact/`。
 
 ## 常见问题
 
-**怎么判断"做完一件事"？** 靠识别 agent 执行的命令。看的是上次压缩以来有没有做完过一件事，不要求正好在这一轮：一轮结束本身就是停顿点，非要等下一次提交，多半只是多花钱。提交只要真的执行了 `git commit` 且工具调用没报错就算；测试命令接了管道（`| tail`）又没开 `pipefail` 时退出码不可信，不算测试结果。
+**怎么判断"做完一件事"？** 靠识别 agent 执行的命令。看的是上次压缩以来有没有做完过一件事，不要求正好在这一轮：一轮结束本身就是停顿点，非要等下一次提交，多半只是多花钱。但做完之后又开始改文件，就算在做下一件事，要等它做完。提交只要真的执行了 `git commit` 且工具调用没报错就算；测试命令接了管道（`| tail`）又没开 `pipefail` 时退出码不可信，不算测试结果。
 
-**压缩后模型会不会忘事？** 随口提到的细节有时会丢。进度笔记只记文件、提交、测试和模型主动记下的决定。用户在对话里随口交代的细节，靠压缩时要求摘要原样保留用户说过的具体信息。Pi 上这样做明显减少了丢失，但不能保证不丢。
+**压缩后模型会不会忘事？** 随口提到的细节有时会丢。进度笔记只记文件、提交、测试和模型主动记下的要求和决定；用户要求单独一栏，不会因为后来记的内容多了被挤掉，超过 30 条才丢最旧的。用户在对话里随口交代的细节，靠压缩时要求摘要原样保留用户说过的具体信息。Pi 上这样做明显减少了丢失，但不能保证不丢。
 
 **会改 Claude Code 自己的设置吗？** 不会，原生自动压缩点保持原样（接近 100 万）。0.1.2 及以前的版本会在会话里设置 `CLAUDE_CODE_AUTO_COMPACT_WINDOW`，把原生压缩点挪到约 26 万（子进程也会继承），并且到了那里不等做完一件事也压缩。0.1.3 去掉了这两点：大活不会再在固定大小处被打断。升级前就开着的会话还留着旧设置，新开一个会话就没有了。
 

package/adapters/pi/index.ts

@@ -6,12 +6,21 @@
 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 { decideAtTurnEnd, decideMidTurn } from '../../plugin/src/core/decide.ts'
+import {
+  applyCheckpoint,
+  CHECKPOINT_DESCRIPTION,
+  CHECKPOINT_INPUT_SCHEMA,
+  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 { promptReminder } from '../../plugin/src/core/reminder.ts'
 import { countDecisions, renderReport } from '../../plugin/src/core/report.ts'
 import {
+  checkpointLog,
   cycleReads,
   type DecisionLogEntry,
   expectedAfterTokens,
@@ -30,16 +39,14 @@ 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 REMINDER_MESSAGE = 'smartcompact-reminder'
 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.`
+const field = CHECKPOINT_INPUT_SCHEMA.properties
 
 export default function smartCompact(pi: ExtensionAPI) {
   pi.registerFlag('smartcompact-allow-line', { description: 'SmartCompact 允许压缩线（token）', type: 'string' })
@@ -125,24 +132,22 @@ export default function smartCompact(pi: ExtensionAPI) {
   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.',
+    description: CHECKPOINT_DESCRIPTION,
     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.' })),
+      goal: Type.Optional(Type.String({ description: field.goal.description })),
+      requirements: Type.Optional(Type.Array(Type.String(), { description: field.requirements.description })),
+      decisions: Type.Optional(Type.Array(Type.String(), { description: field.decisions.description })),
+      next: Type.Optional(Type.String({ description: field.next.description })),
+      current: Type.Optional(Type.String({ description: field.current.description })),
+      milestone: Type.Optional(Type.Boolean({ description: field.milestone.description })),
     }),
     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 },
-      ])
+      const ledger = applyCheckpoint(state.ledger, parsed.value)
+      state = withSignals({ ...state, ledger, notesUpdated: true }, [{ kind: 'checkpoint', milestone: parsed.value.milestone === true }])
       persist()
-      log({ event: 'checkpoint', action: parsed.value.milestone ? 'milestone' : 'note' })
+      log(checkpointLog(parsed.value, ledger))
       return { content: [{ type: 'text', text: 'Recorded. Continue with the work.' }], details: {} }
     },
   })
@@ -172,10 +177,12 @@ export default function smartCompact(pi: ExtensionAPI) {
 
   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 } }
+    const reminder = current && promptReminder(state, tokensOf(ctx), current, params(ctx), CHECKPOINT_TOOL)
+    if (!reminder) return
+    state = reminder.state
+    persist()
+    log(reminder.log)
+    return { message: { customType: REMINDER_MESSAGE, content: reminder.text, display: false } }
   })
 
   // agent_settled：pi 不会再自动继续，此时压缩不会打断工作。

package/adapters/pi/recognize.ts

@@ -20,6 +20,7 @@ export function recognizePi(outcome: PiToolOutcome, ledger: Ledger): { signals:
   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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smartcompact",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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/README.md

@@ -1,6 +1,6 @@
 # SmartCompact for Claude Code
 
-SmartCompact compacts long Claude Code sessions earlier, at a pause after a piece of work is finished, so every later request re-reads a smaller context. Once the context passes 200k tokens, it compacts at the end of a turn if a commit, passing tests or a completed task happened since the last compaction. It waits while tests or the build are failing or errors repeat. It sets no limit of its own: if no piece of work gets finished, the session keeps its context and Claude Code's native auto-compaction applies as usual. A short progress ledger (files changed, latest commit and test result, recorded decisions) is handed back to the model after compaction.
+SmartCompact compacts long Claude Code sessions earlier, at a pause after a piece of work is finished, so every later request re-reads a smaller context. Once the context passes 200k tokens, it compacts at the end of a turn if a commit, passing tests or a completed task happened since the last compaction. It waits while tests or the build are failing or errors repeat. It sets no limit of its own: if no piece of work gets finished, the session keeps its context and Claude Code's native auto-compaction applies as usual. A short progress ledger (files changed, latest commit and test result, recorded user requirements and decisions) is handed back to the model after compaction.
 
 In a 60-task A/B run on Claude Haiku it cut estimated cost by 44% with no loss in hidden acceptance tests; the model missed 6 of 180 recall questions about details mentioned in passing long before. Method and data: [docs/EVALUATION.md](https://github.com/coffeecoproject/SmartCompact/blob/main/docs/EVALUATION.md).
 
@@ -8,8 +8,8 @@ In a 60-task A/B run on Claude Haiku it cut estimated cost by 44% with no loss i
 
 Everything runs locally inside Claude Code. **The plugin makes no network requests, starts no processes, and does not read or change environment variables or Claude Code's settings.**
 
-- **Reads**: the session's token usage; the tool name, input and success of each tool call, to recognize work: file paths from Edit/Write, Bash command text (to recognize `git commit` and test or build commands, and whether they failed), the `[branch hash] message` line from a commit's output, TodoWrite items and task events. It reads no credentials or tokens and no file contents, and nothing it reads leaves the machine.
-- **Writes**: only the plugin's own storage (`$.store`): per-session state and the progress ledger (file paths, the latest commit line, the latest test command and result, in-progress task names, notes recorded with the `checkpoint` tool) and a short decision log. Old session records are pruned automatically.
+- **Reads**: the session's token usage; the tool name, input and success of each tool call, to recognize work: file paths from Edit/Write, file paths from Read (to count files re-read after a compaction), Bash command text (to recognize `git commit` and test or build commands, and whether they failed), the `[branch hash] message` line from a commit's output, TodoWrite items and task events. It reads no credentials or tokens and no file contents, and nothing it reads leaves the machine.
+- **Writes**: only the plugin's own storage (`$.store`): per-session state and the progress ledger (file paths, the latest commit line, the latest test command and result, in-progress task names, notes recorded with the `checkpoint` tool), the paths of files read before and since the last compaction, and a short decision log. Old session records are pruned automatically.
 
 ### What each hook does
 
@@ -19,7 +19,7 @@ All hooks live in one module, `hooks/register.ts`.
 - **`/smartcompact` command**: answers only its own command (`report`, `pause`, `resume`).
 - **Tool calls**: answers calls to its own `checkpoint` tool by recording the note. For every other tool it only looks at the result to recognize commits, tests, builds and edited files, and passes the result through unchanged.
 - **Task created / completed**: keeps the list of in-progress task names for the ledger.
-- **Prompt submit**: adds context to the turn, never changes the user's message. After a compaction it adds the progress ledger; once per cycle, when the context nears the allow line, it adds a one-line reminder to record progress with `checkpoint`.
+- **Prompt submit**: adds context to the turn, never changes the user's message. After a compaction it adds the progress ledger; once per cycle, when the context nears the allow line, it adds a one-line reminder to record progress with `checkpoint`; past the allow line, while it waits for a finished piece of work, it reminds the model to mark each finished step with `checkpoint`, again every further 100k tokens.
 - **Turn complete**: decides whether to compact. When it should, it compacts the session. Where a session cannot compact directly (headless sessions such as the desktop app), it runs the `/compact` command itself with SmartCompact's compaction instructions; it runs no other commands.
 - **Compaction**: never blocks or changes a compaction itself. After any compaction of the main session it appends the progress ledger to the compacted context. Subagent compactions are left alone.
 

package/plugin/src/core/decide.ts

@@ -1,4 +1,5 @@
 // 两个决策函数：一轮结束时要不要主动压缩；一轮进行中原生自动压缩来问时放不放行（只有原生压缩点能提前的平台用到，目前是 pi）。
+// 另有两个判断供 reminder.ts 用：要不要提醒记笔记、要不要提醒标完成。
 // 读不到用量时一律不干预，按原生行为来。
 
 import type { Lines } from './lines.ts'
@@ -17,7 +18,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 +37,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' }
 }
@@ -50,6 +53,18 @@ export function shouldNudge(
   return input.tokens >= input.lines.allow * params.nudgeAtShare
 }
 
+/** 超过允许线、因为还没做完一件事在等时，提醒模型做完一步就标完成；上下文每涨 remindEveryTokens 才再提醒一次。 */
+export function shouldRemindMilestone(
+  decision: TurnEndDecision,
+  tokens: number,
+  remindedAtTokens: number | undefined,
+  params: Params,
+): boolean {
+  if (decision.action !== 'wait') return false
+  if (decision.reason !== 'changed-since-milestone' && decision.reason !== 'waiting-for-milestone') return false
+  return remindedAtTokens === undefined || tokens - remindedAtTokens >= params.remindEveryTokens
+}
+
 export function decideMidTurn(input: DecisionInput, params: Params): MidTurnDecision {
   const { tokens, lines, work } = input
   if (input.paused) return { action: 'allow', reason: 'paused' }

package/plugin/src/core/ledger.ts

@@ -11,6 +11,8 @@ export type LedgerFacts = {
 
 export type LedgerNotes = {
   goal?: string
+  /** 用户交代的要求和具体信息；单独存、只追加，再记一次的挪到最后，超过上限才丢最旧的。旧版本存下的笔记没有这一项 */
+  requirements?: string[]
   decisions: string[]
   next?: string
   current?: string
@@ -37,8 +39,10 @@ export const COMPACT_INSTRUCTIONS =
   'A SmartCompact progress ledger is attached after the summary; do not restate it.'
 
 const MAX_FILES = 30
-const MAX_DECISIONS = 20
+const MAX_DECISIONS = 30
 const MAX_FIELD_CHARS = 1_000
+/** 用户要求只追加，超过这么多条才丢最旧的 */
+const MAX_REQUIREMENTS = 30
 
 export function recordFileChanged(ledger: Ledger, path: string): Ledger {
   const files = [...ledger.facts.filesChanged.filter(file => file !== path), path].slice(-MAX_FILES)
@@ -63,6 +67,7 @@ export function recordTasksInProgress(ledger: Ledger, tasks: readonly string[]):
 
 export type CheckpointInput = {
   goal?: string
+  requirements?: string[]
   decisions?: string[]
   next?: string
   current?: string
@@ -70,11 +75,28 @@ export type CheckpointInput = {
   milestone?: boolean
 }
 
+/** checkpoint 工具的说明，适配层注册工具时使用。 */
+export const CHECKPOINT_DESCRIPTION =
+  'Record a short progress note that survives context compaction: the goal, requirements and specific facts the user stated, decisions made, ' +
+  'where the work stands, and what is next. ' +
+  'Call it after finishing a piece of work (set milestone: true), after an important decision, or when the user states a requirement or a specific fact. ' +
+  'Keep it brief; do not call it for trivial steps.'
+
 /** checkpoint 工具的输入 schema，适配层注册工具时使用。 */
 export const CHECKPOINT_INPUT_SCHEMA = {
   type: 'object',
   properties: {
     goal: { type: 'string', description: 'The overall goal of the current work.' },
+    requirements: {
+      type: 'array',
+      items: { type: 'string' },
+      description:
+        'Facts and requirements the user stated for this session: names of people and customers, dates, ticket or ID numbers, constraints, ' +
+        'things to avoid. One per item, with the context needed to use it later (such as which task it belongs to), in the user\'s words ' +
+        'where possible; record them when the user states them. Not for progress, task status or commit IDs; those go in current and decisions. ' +
+        'Items are added to the list and only the oldest are dropped when it gets long. If the user changes one, record the new version; ' +
+        'the later one wins. Long-term preferences belong in your own memory, not here.',
+    },
     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.' },
@@ -98,29 +120,32 @@ export function parseCheckpoint(raw: unknown): CheckpointParse {
     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)
+  for (const key of ['requirements', 'decisions'] as const) {
+    const field = input[key]
+    if (field === undefined) continue
+    if (!Array.isArray(field) || !field.every(text)) return { ok: false, error: `${key} must be an array of non-empty strings` }
+    value[key] = field.map(clip)
   }
-  if (milestone !== undefined) {
-    if (typeof milestone !== 'boolean') return { ok: false, error: 'milestone must be a boolean' }
-    value.milestone = milestone
+  if (input.milestone !== undefined) {
+    if (typeof input.milestone !== 'boolean') return { ok: false, error: 'milestone must be a boolean' }
+    value.milestone = input.milestone
   }
-  if (!value.goal && !value.next && !value.current && !value.decisions?.length) {
-    return { ok: false, error: 'record at least one of goal, decisions, next, current' }
+  if (!value.goal && !value.next && !value.current && !value.decisions?.length && !value.requirements?.length) {
+    return { ok: false, error: 'record at least one of goal, requirements, decisions, next, current' }
   }
   return { ok: true, value }
 }
 
 export function applyCheckpoint(ledger: Ledger, input: CheckpointInput): Ledger {
   const decisions = [...ledger.notes.decisions, ...(input.decisions ?? [])]
+  // 再记一次的要求挪到最后：用户刚重申过，不该因为最早写进去而先被丢掉。
+  const added = input.requirements ?? []
+  const requirements = [...(ledger.notes.requirements ?? []).filter(requirement => !added.includes(requirement)), ...added]
   return {
     ...ledger,
     notes: {
       goal: input.goal ?? ledger.notes.goal,
+      requirements: [...new Set(requirements)].slice(-MAX_REQUIREMENTS),
       next: input.next ?? ledger.notes.next,
       current: input.current ?? ledger.notes.current,
       decisions: [...new Set(decisions)].slice(-MAX_DECISIONS),
@@ -128,20 +153,22 @@ export function applyCheckpoint(ledger: Ledger, input: CheckpointInput): Ledger
   }
 }
 
-/** 排版成补回上下文的文本，超长时先丢最旧的决定、再丢最早改过的文件，仍超长才截断。 */
+type Kept = { requirements: readonly string[]; decisions: readonly string[]; files: readonly string[] }
+
+/** 排版成补回上下文的文本，超长时先丢最旧的决定、再丢最早改过的文件、最后才丢最旧的用户要求，仍超长才截断。 */
 export function renderLedger(ledger: Ledger, maxChars: number): string {
-  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)
+  let kept: Kept = { requirements: ledger.notes.requirements ?? [], decisions: ledger.notes.decisions, files: ledger.facts.filesChanged }
+  let rendered = layoutLedger(ledger, kept)
+  while (rendered.length > maxChars) {
+    const key = (['decisions', 'files', 'requirements'] as const).find(k => kept[k].length)
+    if (!key) break
+    kept = { ...kept, [key]: kept[key].slice(1) }
+    rendered = layoutLedger(ledger, kept)
   }
   return rendered.length <= maxChars ? rendered : `${rendered.slice(0, maxChars - 20)}\n…(truncated)`
 }
 
-function layoutLedger({ facts, notes }: Ledger, decisions: readonly string[], files: readonly string[]): string {
+function layoutLedger({ facts, notes }: Ledger, { requirements, decisions, files }: Kept): string {
   const lines = [
     LEDGER_MARKER,
     'Generated by the SmartCompact plugin to keep continuity across compaction. It is not a message from the user.',
@@ -152,6 +179,10 @@ function layoutLedger({ facts, notes }: Ledger, decisions: readonly string[], fi
   }
   const omitted = (dropped: number, what: string) => (dropped ? `- …(${dropped} earlier ${what} omitted)` : undefined)
   section('Goal', [notes.goal])
+  section('User requirements', [
+    omitted((notes.requirements?.length ?? 0) - requirements.length, 'requirements'),
+    ...requirements.map(requirement => `- ${requirement}`),
+  ])
   section('Current state', [notes.current])
   section('Next', [notes.next])
   section('Latest results', [

package/plugin/src/core/params.ts

@@ -17,6 +17,8 @@ export type Params = {
   ledgerMaxChars: number
   /** 用量到 L × 这个比例、笔记又没更新时，提醒模型记一下 */
   nudgeAtShare: number
+  /** 超过 L、在等做完一件事时，上下文每涨这么多提醒一次模型做完一步就标完成 */
+  remindEveryTokens: number
 }
 
 export const DEFAULT_PARAMS: Params = Object.freeze({
@@ -28,6 +30,7 @@ export const DEFAULT_PARAMS: Params = Object.freeze({
   errorStreakLimit: 3,
   ledgerMaxChars: 6_000,
   nudgeAtShare: 0.85,
+  remindEveryTokens: 100_000,
 })
 
 const MINIMUMS: Record<keyof Params, number> = {
@@ -39,6 +42,7 @@ const MINIMUMS: Record<keyof Params, number> = {
   errorStreakLimit: 1,
   ledgerMaxChars: 200,
   nudgeAtShare: 0,
+  remindEveryTokens: 1,
 }
 
 /** 用户覆盖的值逐项校验，不合法的项沿用默认值。 */

package/plugin/src/core/reminder.ts

@@ -0,0 +1,54 @@
+// 用户发消息前要不要附一句用户看不到的提醒。两种提醒的文字、判断、状态和日志都在这里，适配层只负责注入。
+
+import { decideAtTurnEnd, shouldNudge, shouldRemindMilestone } from './decide.ts'
+import type { Lines } from './lines.ts'
+import type { Params } from './params.ts'
+import { type DecisionLogEntry, expectedAfterTokens, type SessionState } from './state.ts'
+
+/** 快到允许压缩线时提醒模型更新笔记。 */
+export const checkpointNudge = (tokens: number, tool: string): 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, user requirements or progress are not yet recorded, call ${tool} briefly; if a piece of work was just finished, set milestone: true. ` +
+  'If the user is waiting for an answer, answer first.'
+
+/** 超过允许线、在等做完一件事时，提醒模型做完一步就标完成。 */
+export const milestoneReminder = (tokens: number, tool: string): string =>
+  `SmartCompact: the context is at about ${Math.round(tokens / 1000)}k tokens and will be compacted once a piece of work is finished. ` +
+  `When you finish a step (a fix, a subtask, a passing test run), call ${tool} with milestone: true, even without a commit; ` +
+  'do not mark unfinished work as done. If the user is waiting for an answer, answer first.'
+
+export type PromptReminder = { text: string; state: SessionState; log: Omit<DecisionLogEntry, 'at' | 'session'> }
+
+/**
+ * 超过允许线、在等做完一件事时，提醒模型做完一步就标完成；否则快到允许线、笔记没更新时，提醒记笔记。
+ * 两种都算本周期提醒过，不重复提醒记笔记。不需要提醒时返回 undefined。
+ */
+export function promptReminder(
+  state: SessionState,
+  tokens: number | undefined,
+  lines: Lines,
+  params: Params,
+  tool: string,
+): PromptReminder | undefined {
+  if (tokens === undefined) return undefined
+  // 用户发下一条消息前状态没变，判断和上一轮结束时一样。
+  const waiting = decideAtTurnEnd(
+    { tokens, lines, work: state.work, expectedAfterTokens: expectedAfterTokens(state, params.defaultAfterTokens), paused: state.paused },
+    params,
+  )
+  if (shouldRemindMilestone(waiting, tokens, state.remindedAtTokens, params)) {
+    return {
+      text: milestoneReminder(tokens, tool),
+      state: { ...state, nudged: true, remindedAtTokens: tokens },
+      log: { event: 'reminder', action: 'milestone', reason: waiting.reason, tokens },
+    }
+  }
+  if (shouldNudge({ tokens, lines, notesUpdated: state.notesUpdated, nudged: state.nudged, paused: state.paused }, params)) {
+    return {
+      text: checkpointNudge(tokens, tool),
+      state: { ...state, nudged: true },
+      log: { event: 'reminder', action: 'nudge', reason: 'notes-not-updated', tokens },
+    }
+  }
+  return undefined
+}

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
@@ -31,9 +35,9 @@ export function renderReport(input: {
     `SmartCompact${state.paused ? '（已暂停）' : ''}`,
     `- 当前用量 ${k(tokens)}；允许压缩线 ${k(lines.allow)}，原生压缩点 ${k(lines.ceiling)}`,
     `- 本会话压缩 ${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}`,
+    `- 本会话决策：插件压缩 ${(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}，提醒记笔记 ${counts['reminder:nudge'] ?? 0}，提醒标完成 ${counts['reminder:milestone'] ?? 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

@@ -1,6 +1,6 @@
 // 会话状态与决策日志的数据格式。读写由适配层负责，core 只定义格式。
 
-import { EMPTY_LEDGER, type Ledger } from './ledger.ts'
+import { type CheckpointInput, 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'
 
@@ -15,8 +15,10 @@ export type SessionState = {
   paused: boolean
   /** 自上次压缩以来，模型是否通过 checkpoint 更新过笔记 */
   notesUpdated: boolean
-  /** 自上次压缩以来，是否提醒过模型更新笔记 */
+  /** 自上次压缩以来，是否提醒过模型（记笔记或标完成）；提醒过就不再提醒记笔记 */
   nudged: boolean
+  /** 本周期最近一次提醒模型标完成时的用量 */
+  remindedAtTokens?: number
   /** 各种信号出现过的次数，用于确认识别是否生效 */
   seen: SignalsSeen
   usage: UsageTally
@@ -102,6 +104,7 @@ export function withCompaction(state: SessionState, before: number, summary: num
     compactions: state.compactions + 1,
     notesUpdated: false,
     nudged: false,
+    remindedAtTokens: undefined,
     usage: attributed ? recordCompaction(state.usage, before, summary) : state.usage,
   }
 }
@@ -125,11 +128,21 @@ export function cycleReads(state: SessionState): Pick<DecisionLogEntry, 'reads'
   return state.reads ? { reads: state.reads.reads, rereads: state.reads.rereads } : {}
 }
 
+/** checkpoint 的日志：有没有标完成、用户要求有几条。 */
+export function checkpointLog(input: CheckpointInput, ledger: Ledger): Omit<DecisionLogEntry, 'at' | 'session'> {
+  const requirements = ledger.notes.requirements?.length ?? 0
+  return {
+    event: 'checkpoint',
+    action: input.milestone ? 'milestone' : 'note',
+    ...(requirements ? { requirements } : {}),
+  }
+}
+
 export type DecisionLogEntry = {
   at: string
   /** 会话 ID，报告据此只统计当前会话 */
   session?: string
-  event: 'setup' | 'turn-end' | 'mid-turn' | 'compacted' | 'checkpoint' | 'error'
+  event: 'setup' | 'turn-end' | 'mid-turn' | 'compacted' | 'checkpoint' | 'reminder' | 'error'
   action?: string
   reason?: string
   tokens?: number
@@ -140,6 +153,8 @@ export type DecisionLogEntry = {
   /** 压缩时：上次压缩以来读文件的次数，以及其中重读压缩前看过的文件的次数 */
   reads?: number
   rereads?: number
+  /** checkpoint 之后用户要求的条数 */
+  requirements?: number
   trigger?: string
   detail?: string
 }