agentic-awesome-skills 实战指南：用 Strategic Compact 在阶段边界安全压缩 Agent 上下文-育师

agentic-awesome-skills 实战指南：用 Strategic Compact 在阶段边界安全压缩 Agent 上下文

【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills

在长任务会话中，上下文窗口里的重复推理与过时日志会逐渐挤占有效空间，但"何时压缩"绝不能只凭工具调用次数判断。本指南以 AAS（agentic-awesome-skills）仓库中的cc-skill-strategic-compact技能（SKILL.md）为核心，讲解如何在已验证的阶段边界生成"经核实的检查点（verified checkpoint）"，再执行压缩；读完你可以在自己的 Agent 会话中落地一整套"压缩前留证、恢复后核验"的流程，并掌握配套无状态提醒脚本suggest-compact.sh的用法与实现原理。

核心思想：压缩是"留证"而非"删记忆"

cc-skill-strategic-compact定义了一个清晰的原则：先产出足够的耐久信息（durable information）以便恢复同一任务，再压缩上下文。它的description明确指出，该技能用于"在阶段边界压缩 Agent 对话之前，准备一个经过验证的检查点"，适用于上下文重复、任务漫长的场景，需要保留约束（constraints）、证据（evidence）、决策（decisions）和下一步动作（next action）。

原文档特别强调一个反模式：工具调用次数（tool-call count）只是一个提醒信号，它既不能度量上下文质量，也不能决定压缩是否安全。这意味着计数到达阈值时，正确的反应是"检查当前阶段是否已闭环、检查点是否已生成"，而不是机械地触发压缩。

何时使用与何时禁用

适合压缩的场景

探索（exploration）已经结束，即将进入实现阶段；
一个经过测试的里程碑（tested milestone）已经落地；
长对话中充斥着重复或过时的推理（repeated or obsolete reasoning）。

严禁压缩的场景

原文档给出了三条硬性红线，任何时候都不应在以下中间状态压缩：

某个工具调用尚未解析完成（unresolved tool call）；
存在未记录的审批决策（unrecorded approval decision）；
存在未捕获确切证据的失败（a failure whose exact evidence has not been captured）。

未解决的失败要先保存复现证据，再谈压缩——这是整个技能的第一优先级。如果压缩发生在证据捕获之前，恢复后的新上下文将无法定位根因，等于丢失了排障的关键资产。

输入与前置条件

在执行检查点流程前，需要确认以下四项齐备：

目标与边界：用户当前的目标（objective）、已接受的约束（accepted constraints）以及完成定义（definition of done）；
代码与文件状态：当前分支与源码修订号（source revision）、本地改动、相关产物路径和实际检查结果（actual check results）；
运行态信息：正在运行的进程、挂起的工具调用、审批事项或外部阻塞因素（external blockers）；
宿主压缩机制：一个由客户端支持的上下文压缩机制。该技能不假设每个客户端都存在/compact命令，也不操作任何内部上下文文件——它只负责"留证"，压缩动作由客户端完成。

六步操作流程

原文档给出了标准程序，六个步骤环环相扣：

选择阶段边界：从发现（discovery）到实现（implementation）、从实现到验证（verification）、或从一个已完成批次到下一个批次。若存在未解决的失败，首先保存其复现信息。
对账任务状态：将任务状态与文件系统、Git 进行核对，明确区分四类工作——已完成（completed）、未提交（uncommitted）、已计划（planned）、已失败（failed）。
产出检查点：按下文模板生成检查点，包含恢复所需的精确命令、结果摘要与路径；同时省略已复制的日志和不再相关的被否假设（discarded hypotheses）。检查点追求"够用且精简"，不是对话全文备份。
验证下一步可执行：确认下一步动作可以被新上下文直接执行，且不会出现以下事故：重复执行 merge、重复发送消息、丢失约束、覆盖无关工作（overwrite unrelated work）。
保存位置受限：只保存到**已被授权的项目产物（authorized project artifact）**中，或直接在对话中返回检查点；不得自动改写全局记忆（global memory）或宿主配置。
执行压缩并恢复核验：如用户要求且客户端支持，使用客户端的压缩命令；恢复时先读取检查点，再重新验证可变状态（mutable state），之后才继续工作。

检查点模板（Checkpoint Template）

原文档提供的模板共有八个字段，压缩前必须逐项填写，这是恢复任务的"最小可执行信息集"：

Objective and done condition: User constraints and authorization boundaries: Source revision, branch and local changes: Completed outcomes with verification: Outstanding work and known failures: Running process/tool identifiers: Artifacts and exact paths needed next: Next action, expected result and fallback:

逐字段说明（结合技能语义补充）：

Objective and done condition：当前目标与完成判定，防止新上下文"跑偏"或提前收工；
User constraints and authorization boundaries：用户的约束与授权边界，压缩后约束不得丢失；
Source revision, branch and local changes：源码修订、分支与本地改动，保证恢复后操作基于同一代码基线；
Completed outcomes with verification：已完成事项及其验证结果，测试只有针对实际测过的修订号才记为通过；
Outstanding work and known failures：未完成工作与已知失败，含失败证据路径；
Running process/tool identifiers：运行中的进程/工具标识，便于恢复后不重复启动或误杀；
Artifacts and exact paths needed next：下一步需要的产物与精确路径；
Next action, expected result and fallback：下一步动作、预期结果与回退方案（fallback），保证即使预期落空也有预案。

实战示例：源 PR 合并后的同步场景

原文档用"搜索功能"的例子演示了检查点如何防止重复操作：

某个搜索功能的源 PR（source PR）已经合并，但规范同步（canonical synchronization）仍在进行中。

此时检查点必须记录：

源合并的 SHA（source merge SHA）；
规范 PR 编号（canonical PR number）；
预期生成的产物文件（expected generated files）。

关键纪律：测试只有在"实际测试过的修订号"上才记为通过——不能把别的分支上的测试结果张冠李戴。恢复后的下一步动作是"验证规范 PR 与更新后的main"，而不是再次合并源 PR。示例还提示：如果某个浏览器检查仍依赖"已解锁的桌面"这样的外部条件，应把该条件保持可见，同时继续可以独立进行的代码审查。

预期结果：新上下文恢复的是"未完成的验证"，保留无关的本地编辑（unrelated local edits），并且不会把一次源合并误宣传为发布（publication）——源合并 ≠ 正式发布，这是恢复会话中极易出错的语义陷阱。

配套脚本：suggest-compact.sh 无状态提醒器

技能目录包含一个可选的 Bash 助手（仓库中有两份相同实现：plugins 版与 skills 版），用于在达到阈值时打印"该准备检查点了"的提醒，仅此而已。

用法

bash skills/cc-skill-strategic-compact/suggest-compact.sh 50

第一个位置参数是观察到的工具调用计数（tool-call count），可省略；
第二个可选参数是阈值（threshold），默认50；
脚本在达到阈值时提醒一次，之后每增加 25 次调用再提醒一次；
也可以通过显式调用方适配器传入环境变量COMPACT_TOOL_COUNT与COMPACT_THRESHOLD；
未提供计数时脚本静默退出（exit 0），不产生任何输出。

源码实现解读

从 suggest-compact.sh 的实现可以看到几个关键设计：

参数严格校验：先校验参数个数（超过 2 个报错并给出Usage: suggest-compact.sh [tool-count [threshold]]），随后用正则^[0-9]{1,6}$同时校验计数与阈值必须是"有界非负十进制整数"（最多 6 位），非整数直接报[StrategicCompact] Count and threshold must be bounded decimal integers.并以退出码 2 结束——这对应原文档"Counts are caller-provided, bounded non-negative decimal integers"的限制说明。
阈值下限：threshold必须 ≥ 1，否则报Threshold must be positive.
提醒触发逻辑：当count >= threshold且(count - threshold) % 25 == 0时，向 stderr 打印一条提醒：[StrategicCompact] $count tool calls; prepare a verified checkpoint if this phase has finished. Nothing compacted or saved.——注意消息末尾特意声明"Nothing compacted or saved"（什么都没压缩、什么都没保存），把提醒与压缩动作严格解耦。
严格无状态：脚本头注释写明 "Stateless reminder using a caller-supplied session count. Never compacts or saves."，并设置了set -euo pipefail保证健壮性。它不存储任何计数器、不估算 token 用量、永远不执行压缩——压缩必须由宿主客户端的能力完成。

向后兼容说明：共享计数器已废弃

原文档明确记录了版本演进：早期版本曾在无关会话之间共享一个用户状态计数器（shared user-state counter），该计数器如今已不再读写。因此：

现有自定义包装器（custom wrappers）必须显式传入会话计数（即位置参数或COMPACT_TOOL_COUNT）；
早期遗留的状态文件保持原样、不予改动（left untouched）；
该技能不安装也不编辑任何 hook。

如果你曾基于旧版封装过调用，升级后需要把"读取共享计数器"改为"由调用方显式传入本次会话的计数"，否则脚本会静默退出或提醒失效。

已知限制与使用边界

原文档在最后给出四条限制，使用时应始终牢记：

检查点保存的是"已记录的证据"，而非全部对话细节：当"精确字节"（exact bytes）至关重要时，保留主要产物（primary artifacts），不能只依赖检查点摘要；
计数由调用方提供，提醒不等于上下文容量测量：达到阈值只说明"该看一看了"，不代表窗口真的满了或压缩一定安全；
分支、进程和远端状态会随时间变化：恢复时必须重新验证（revalidate）这些可变状态，不能把摘要当作当前真相（treating a summary as current truth）；
客户端上下文管理机制各不相同：禁止通过删除聊天数据库、日志、缓存或项目文件来模拟压缩——压缩是宿主能力，不是文件清理操作。

小结：一套可复用的安全压缩纪律

把cc-skill-strategic-compact提炼成可操作的纪律就是四句话：边界清晰才压缩（只在已闭环的阶段边界操作）、证据先行再压缩（未解决的失败先留复现证据）、检查点完整才压缩（八字段模板逐项填全）、恢复必核验（分支/进程/远端状态重新验证）。配合 suggest-compact.sh 的阈值提醒，开发者可以在任意支持上下文压缩的客户端中，把"压缩"从一次有风险的操作，变成一套有检查点、有回退、可恢复的标准流程。相关技能元数据（risk: none、source: community）记录在 SKILL.md 的文件头中，仓库内skills/与plugins/agentic-awesome-skills-claude/skills/两份目录结构保持一致，均可作为参考入口。