smart-precompact

smart-precompact

这项任务：从对话中提取值得保留的内容，并交接提示词，让会话压缩后能够继续，不会让人觉得是在和一个陌生人交谈。

成功标准：压缩后，会话不会重犯已经犯过的错误，不会再问用户已经回答过的问题，也不会再建议已经被否决的方法。

速度要求：运行时间以秒计。不搜索文件、不扫描文件夹、不使用 find。这项技能会在上下文已满时运行，而每一次不必要的调用都会让自动压缩更快到来。

语言：这些说明使用英语，但用户看到的所有内容都应遵循用户消息的语言：回执行、第 1 块、第 2 块（自然翻译其中的标签，例如“正在构建：”和“失败，不要重试：”），以及第 3 块。以下三项绝不改变：/compact 命令本身、从会话中原样复制的字符串（错误、路径、命令），以及交接文件的首行 # Handoff . <root> . <date and time>，钩子会用它来识别自己的文件。

---

运行模式

参数	执行内容
(空)	**默认。**读取、筛选并输出各块内容。不会写入磁盘
handoff	也会将续接提示词保存到项目外的一个文件中，让新会话可以从这里继续
save	也会将条目追加到项目中已存在的文档文件
save notes	与 save 相同，也会写入个人笔记文件夹。仅在明确请求时，且仅当路径已在 config.md 中设置时执行

模式可以组合，例如 handoff save。默认模式不会触碰任何内容。

用自然语言提出的请求：“帮我准备压缩并保存”或“这样我明天可以继续” = handoff。“并更新文档” = save。“也保存到我的笔记”或“也保存到 Obsidian” = save notes。无论用哪种语言提出相同请求，含义都相同。如有疑问，使用默认模式。

自动触发（钩子，可选）

scripts/compact_hook.py 由 scripts/install_hook.py 安装（参见 README.md）。 它会执行两项操作：

1. **压缩前：**当上下文超过第一个阈值（60%）时，会在对话中添加一条提示；超过第二个阈值（80%）时，再添加一条。当提示出现时：
   • **先回答用户提出的问题。**不要为了运行这项技能而中断用户的工作。
   • 在同一条回复的末尾，以 handoff 模式运行这项技能，并使用提示中的路径。
   • 用用户消息所用的语言向用户说明一行：上下文已超过 X%，且 /compact 命令行已准备就绪。达到第二个阈值时，措辞会更明确：现在就该压缩（出现时，点击提示上方栏中的 Smart compact，或粘贴该命令行），以免自动压缩自行启动。
   • 如果用户已在同一条消息中要求运行这项技能，则只运行一次，并添加 handoff。
2. **压缩后：**自动将会话的交接文件放回对话中。因此，安装钩子后，用户只需点击提示上方栏中的 Smart compact，或粘贴 /compact 命令行。

---

步骤 1：上下文（一条命令）

date "+%Y-%m-%d %H:%M"; echo "root: $(git rev-parse --show-toplevel 2>/dev/null || pwd)"; echo "session: ${CLAUDE_CODE_SESSION_ID:-none}"; git status --short 2>/dev/null | head -10; grep -qs compact_hook.py ~/.claude/settings.json && echo "restore-hook: on"

就这些。不用 ls，也不扫描。root 是项目根目录：每个项目路径（docs/、CLAUDE.md）都从这里读取，即使对话已经切换到子文件夹也是如此。分支和提交信息不会写入提示词：压缩后，以及每个新会话中，Claude Code 都会自行加载最新的 git 状态。

对话是否已经压缩过一次？（你看到的部分内容会以摘要形式呈现。）如果存在会话的交接文件，就读取它（路径在步骤 4b 中，因此这是读取，而非搜索）。它记录了压缩前发生的内容。如果没有文件，请在回执行中说明你只能通过摘要获知部分对话内容，不要对此编造细节。

---

步骤 2：筛选

逐条查看对话，并询问：“如果这一条消失了，下个会话会有什么问题？”

按重要性排序的五个类别：

1. 失败尝试。 我们尝试了什么但没成功，以及失败原因。代价最高的一类。 没有这条，下个会话就会再次尝试相同的方法。
2. 决策。 我们选择了 X 而不是 Y，并且有原因。没有原因，就不算决策。
3. 用户纠正。“不，要这样”“始终这样做”。用用户自己的话记录工作规则。
4. 当前状态。 我们改动了哪些文件，哪些工作尚未完成，哪些还未经测试。
5. 未完成事项。 剩下什么，按顺序列出。

措辞准确。 如果某条内容取决于某个字符串（路径、错误消息、字段名、命令），就逐字复制。概述错误消息，就已经变成了另一条错误消息。

绝不记录机密。 API 密钥、令牌、密码、连接字符串或卡号都必须替换为 [REDACTED: 具体内容]，即使是在精确字符串中也是如此。这些内容块会保存到文件并粘贴到对话中，一旦机密进入其中，就已经泄露。

省略测试

删除每条符合以下条件的内容：

• git、代码或 CLAUDE.md 已经说明的内容（每次 compact 后都会重新加载 CLAUDE.md）
• 只在对话当前时刻成立的内容（“给我看看文件”、中间措辞）
• 已被后续结论取代的内容

平均每条只值得占一行，而不是一段。如果筛选后还剩 8 条以上，说明筛选得不够。

---

步骤 3：编写内容块

阅读 reference/prompt-templates.md，并在写入磁盘前先写好两个内容块。交接文件是内容块 2 的副本，因此必须先定稿内容块 2，再保存。

如何拆分：

• 内容块 2（恢复提示词）必须独立完整。 新会话也会读取这个文件，而新会话没有摘要。因此，内容块 2 必须包含所有信息：失败尝试及其原因、决策及其原因、规则、当前状态、文件位置，以及下一步。
• 内容块 1（/compact 行）保护摘要中的推理。 它告诉摘要生成器哪些内容要保留，哪些可以压缩。绝不能包含当前状态。
• **唯一允许的重叠内容：**简要提及失败尝试和用户纠正。这两类内容丢失的代价最高，重复一行也比会话再次犯同样的错误更划算。反过来说：包含失败尝试的部分绝不能归入“可压缩”内容。

长度：compact 行最多 60 个词。恢复提示词最多 200 个词，“接下来”最多列 3 个步骤。

---

步骤 4：写入（仅在用户要求时）

如果用户没有要求 save、save notes 或 handoff，就完全跳过此步骤。

4a. 保存

只能写入已经存在的文件，路径相对于 root。绝不要在项目中创建文件或文件夹。如果没有任何可写入的目标文件，就在回执行中说明，并将相关内容留在内容块 2 中。

内容	位置	每次运行的上限
决策和失败尝试	docs/DECISIONS.md	2
未完成事项，以及已完成事项的 [x]	docs/TASKS.md	5
明确的工作规则	项目根目录中的 CLAUDE.md	1，而且几乎总是 0

格式、边界情况和冲突处理：reference/routing-table.md。

CLAUDE.md 的准入标准。 该文件会在之后的每个会话中永久加载，其中重复的一行会在每次未来对话中消耗令牌。只有以下三项全部满足时，才能将一条规则写入其中：(1) 用户明确说过（例如“始终”“绝不”“不，要这样”），绝不能推断规则；(2) 文件中尚未用其他措辞涵盖该规则（写入前先阅读）；(3) 删除该规则会改变未来的行为。如有疑虑，就不要写入，并在回执中说明有一条候选规则以及拒绝写入的原因。

仅追加。 不得重写、删除或“清理”。仅有两个例外：在已完成的任务上标记 [x]；如果用户在本次运行中立即纠正了你对某条内容的归档位置，则更正该条。写入前先阅读，并跳过已经存在的内容。

4b. handoff

**路径：**钩子说明中是否给出了路径？如果有，就使用它。否则使用 ~/.claude/handoffs/<first 8 characters of session>.md。如果 session 是 none： ~/.claude/handoffs/<name of the root folder>.md。

**内容：**第一行是 # Handoff . <root> . <date and time from step 1>，空一行，然后按步骤 3 中的原样写入区块 2，并在最后一行以隐藏注释写入区块 1：``。 Smart PreCompact mod 会读取这一行，以便一键运行完全相同的 compact；钩子会在将文件放回对话前移除这一行。每个会话仅有一个文件，每次运行都会覆盖，不存档：工作状态会过时，旧版本会造成误导。钩子会删除 14 天无人触碰的文件，并通过第一行识别文件：不要更改标题，否则文件永远不会被删除。这是该技能在项目外创建的唯一文件。文件夹不存在？ mkdir -p ~/.claude/handoffs。

4c. 保存笔记

路径和文件夹名称来自技能文件夹中的 config.md。不要搜索。 没有路径，或路径在磁盘上不存在？在收据中写一行，然后跳过。格式： reference/routing-table.md。在笔记文件夹中，如果今天的日志尚不存在，你可以创建它；也可以为每项决策新建一个文件 （<decisions>/YYYY-MM-DD <short title>.md）。

---

步骤 5：输出

一行收据，使用对话所用的语言（即使最后一条消息仅是一条命令）：包含项目数量、写入了什么及其位置、丢弃了什么及原因、发现的矛盾，以及此前是否压缩过对话。从钩子运行时，此行还要包含百分比，且不得有额外行。

随后输出各区块，类型为 text 而非 bash，区块之间不得有任何文本。（某些界面会在 bash 区块中显示“运行”按钮，点击后会在终端中运行其中的文本。）

模式	输出内容
不使用 handoff	区块 1、区块 2
使用 handoff，且 restore-hook: on 未启用	区块 1（以文件路径结尾）、区块 2、区块 3
使用 handoff，且 restore-hook: on 已启用	区块 1（以文件路径结尾）、区块 3。收据行说明续接提示词已保存，并会在 compact 后自动回到对话中

区块 3 是给新会话的一句话：Read <path> and continue from there.

**下一项任务与我们刚才做的无关吗？**添加一行：最好使用 /clear 开启干净会话，并使用区块 2 或区块 3。干净会话的成本低于 compact，也不会携带不需要的摘要。

打印前自检

• 每个死胡同和每项决策都有原因
• 未参与过对话的会话也能理解区块 2
• compact 行不描述状态
• 不超过 60 和 200 个词，后续步骤不超过 3 项
• 精确字符串均逐字复制，且机密内容已替换为 [REDACTED]
• 不对已压缩的部分编造任何细节

---

示例

使用其他语言时，各区块仍保持此形式，标签和正文使用相应语言。

/compact Keep: why the checkouts/update webhook was rejected (it fired dozens of times
per cart and created duplicate emails), the exact wording of the 429 error from
Klaviyo, and the user's correction: "never send to real customers in tests". You can
compress the JSON debugging round and the log reading.

Continue where we left off.

Building: an automatic abandoned cart email for a Shopify store.
State: the function in jobs/cart.ts is written and tested on a demo cart. Not tested against real Klaviyo, not deployed.
Decisions: Klaviyo and not Mailchimp, because Klaviyo has a built-in cart event.
Failed, don't retry: the checkouts/update webhook (it fired dozens of times per cart,
  created duplicate emails). Error: `429 Too Many Requests: rate limit 75/s exceeded`.
Rules set: never send to real customers in tests, only to the test address.
Read before touching: docs/DECISIONS.md
Next up: 1) deploy to staging  2) test on the test address  3) show me before turning it on.

---

准确性约定

已知信息：当前对话的内容、本次会话中运行的工具输出、本次运行中读取的文件。

未知信息（必须使用工具）：

• 日期：步骤 1 中的 date。绝不可凭记忆或上下文获取。
• 目标文件中已有的内容：写入前先 Read。绝不可假设。

需要询问时：某项看似是决策，但没有说明原因。不要编造原因。用一行询问，或省略该项。

拒绝时：有人要求删除、压缩或“清理”文档文件中的现有内容；或者对话已被压缩、没有 handoff 文件，却要求提供有关被压缩内容的细节。应明确说明，而不是编造。

边界

允许：阅读对话。运行步骤 1 的命令。读取已知路径中的文件 （目标文件、交接文件、config.md）。打印代码块。仅在指定的模式下写入，且只能写入 步骤 4 中指定的目标文件。

禁止：自行运行 /compact（用户会粘贴该命令或按下 Smart compact； 运行它会清除用户的上下文）。搜索文件或文件夹。在项目中创建文件或文件夹。 未指定写入模式时写入。重写或删除现有行，但 4a 中的两个例外除外。将秘密内容复制到代码块或文件中。编造未说明的决策原因。该技能本身不会提交或推送。用户另行提出的提交请求按常规处理，并在代码块之后执行。