compress-usage

Files (1)

• SKILL.md

SKILL.md (first lines)

# Compress / Decompress 使用规程

本技能用于在上下文过长、历史已完成一个独立主题，或需要重新查看已压缩内容时，正确使用 `compress` 和 `decompress`。工具会校验保护区、范围边界、已有压缩块和压缩收益；不要试图绕过这些检查。

## 快速决策

- 需要为后续工具结果和工作腾出空间，且某段历史已经完成一个独立主题：使用 `compress`。
- 需要已压缩主题的精确原文，且对应 block 仍为 active：使用 `decompress` 恢复。
- 只需要已压缩主题的结论：先读当前可见摘要；只有需要索引行背后的旧摘要时才调用 `decompress`。对 active block 调用会恢复原文，不能指定只读摘要。
- 正在执行一个不可中断的原子步骤：先完成该步骤，再压缩其他已结束的历史。需要逐字使用的内容保留原文；未验证结论可以总结，但必须明确标注未验证。
- 压缩和原文恢复会改变压缩状态；相关调用串行执行，多段压缩优先合并为一次 `ranges` 提交。

## 地址规则

### 消息 ref

`compress` 使用当前轮次视图中实际显示的消息地址，例如 `[m2]`。调用前必须从当前上下文重新读取这些地址：

- `fromRef` 和 `toRef` 都是包含边界；`m2` 到 `m5` 包含 `m2`、`m3`、`m4`、`m5`。
- ref 是当前视图地址，不是永久消息 ID。压缩、解压或新一轮上下文变换后，`mN` 可能重新编号。
- 不要凭记忆编造 ref，也不要复用上一轮的 `mN`。旧编号可能仍合法却指向其他内容，工具不能替你识别这种误选。
- 端点落在压缩块的 summary 行时，会覆盖该 block 代表的整个范围，而不是只覆盖一行。
- 首条用户消息、末尾保护区以及工具明确保护的内容不能压缩；如果工具返回保护边界错误，按错误提示缩小范围。

### 压缩 block ID

`decompress` 使用持久的 block ID，例如 `b3`。只使用当前上下文中看到的 block ID：

- active block 通常显示为 `[Block b3 · K 条]`。
- 被更大范围消费后的 block 可能显示为 `--- b3: 标题 ---` 索引行。
- 只接受 `b` 加正整数，例如 `b3`、`b12`；不要传 `3`、`b0` 或自行猜编号。
- block ID 跨轮次稳定，但 block 的状态可能改变；调用结果取决于当前状态。

## 什么时候压缩

压缩前先确认以下各项：

1. 范围已经完成一个独立主题，而不是正在进行的当前步骤。
2. 范围外的后续工作不需要逐字引用其中的代码、报错或对话。
3. 范围内的结论、约束、文件路径、验证状态和未完成事项都能写入摘要。
4. 范围没有部分覆盖已有 active block；要么完整覆盖该 block，要么避开它。
5. 多个范围彼此不重叠，并且每个范围是独立主题。
6. `summary` 明显短于原文，能够带来实际空间收益。
7. `fromRef` 和 `toRef` 都来自当前可见视图，且起点不晚于终点。

不要为了满足 nudge 而压缩当前正在使用的上下文。nudge 提供的可压缩窗口只是可选范围，不要求全部压缩；在窗口内选择一个能安全总结的连续子范围即可。

## 调用 compress

参数必须是一个包含非空 `ranges` 数组的对象。每个范围必须包含四个字符串字段。以下示例的编号、路径、结论与返回数字均为假设，不是本会话的可调用范围或验证记录；必须按当前历史替换：

```json
{
  "ranges": [
    {
      "fromRef": "m2",
      "toRef": "m5",
      "title": "认证方案调查",
      "summary": "结论：认证入口位于 src/auth.ts，当前使用 session cookie。已检查 src/auth.ts 和 src/middleware.ts；集成测试尚未完成，仍需验证过期 cookie 行为。"
    }
  ]
}
```

字段规则：

- `fromRef`：当前视图中的起始消息，包含。
- `toRef`：当前视图中的结束消息，包含。
- `title`：非空单行标题，最多 80 个字符，不含控制字符或连续三个及以上的连字符。它会出现在 block 头或未来的索引行中。
- `summary`：替代整段原文的长期摘要；不是给工具看的临时说明。
- `ranges`：一个或多个范围。范围之间不能重叠。

可以在一次调用中提交多个独立主题：

```json
{
  "ranges": [
    {
      "fromRef": "m2",
      "toRef": "m4",
      "title": "配置调查",
      "summary": "配置入口是 config.toml；阈值由 src/core/config-parse.ts 解析。当前未修改配置。"
    },
    {
      "fromRef": "m7",
      "toRef": "m9",
      "title": "测试结果",
      "summary": "src/core/context/nudge.test.ts 的相关测试已通过；端到端测试尚未运行。"
    }
  ]
}
```

批量调用是原子的：所有范围先统一校验，任一范围失败时整次调用不生效。一次调用不能依赖同一调用中刚创建的 block；超过配置的 `max_ranges` 时分批提交。

## 编写 title 和 summary

`title` 要让未来看到索引行时能立即识别主题，例如“上下文 nudge 边界分析”，不要写“历史记录”或“之前的内容”。

`summary` 必须让未来的 agent 在没有原文时仍能继续工作。优先保留：

- 目标：这段历史解决了什么问题。
- 结论：已经确定了什么，以及依据是什么。
- 路径和符号：关键文件、函数、配置键、命令或错误文本。
- 决策：采用了什么方案，放弃了什么方案，为什么。
- 验证状态：哪些测试、构建或检查已经运行，结果是什么。
- 未完成事项：哪些内容仍是假设、待确认或失败。
- 后续动作：继续工作时首先应该做什么。

可以使用下面的内部结构，但不要为了格式而丢失信息：

```text
目标：...
结论：...
关键证据：...
关键路径/符号：...
验证：...
未完成/风险：...
后续：...

From 418-teapot/ZooKeeper, MIT.

More from 418-teapot/ZooKeeper