前言¶
Agent 在跑工具链时，日志、JSON 数组、搜索结果往往会一次性塞进上下文。窗口一紧，要么截断丢信息，要么把整段原文硬塞进去，后续推理成本陡增。手工删行既慢，也容易把错误栈或异常记录一并删掉。
下面介绍 SkillHub 上的社区 Skill TokenLite 安全上下文压缩策略（@user_a72d54a9/tokenlite，当前版本 4.0.1）。它面向「大块非代码工具输出」做评估与压缩，并通过本地 CCR 机制保留全文，需要时再按行、grep 或 JSON 路径取回。源码与用户输入在规则上被明确排除，避免把压缩当成改代码或改用户话的捷径。
这是什么¶
TokenLite 是一套基于通用 SKILL.md 的 Agent Skill，由 SkillHub 发布者 user_a72d54a9 维护（SkillHub 页面标注作者 Bruno），分类为 ai-agent，requires_api_key=false，无需额外 API Key。
一句话定位：在上下文压力大时，对大型日志、JSON、搜索结果和重复文本做安全、可审计的压缩；压缩后的视图用于当前推理，完整内容仍可在本地检索。
核心功能¶
能力以 scripts/tokenlite.py 为主入口，Agent 按 Skill 内工作流调用即可。
安全契约（Skill 中标注为不可妥协）
- 不压缩源码：自动识别为代码的内容，以及
--format code，均原样返回，reason=protected:code。 - 不压缩用户输入：带
--is-user-input标记的内容保持keep_raw。 - 短堆栈保留：估计低于 2,000 token 的 traceback 不压缩，便于对照行号排错。
- CCR 视为本地未加密临时存储：不应在无用户知情的情况下缓存敏感信息。
- 不自动安装全局 Hook：可选 SessionStart Hook 须用户明确同意后再装。
主要命令
| 需求 | 命令 |
|---|---|
| 评估并视情况压缩 | tokenlite.py sense --input FILE --json |
| 显式压缩 | tokenlite.py compress --input FILE --format auto |
| 仅判断是否该压 | tokenlite.py should --input FILE --json |
| 从 CCR 取原文或片段 | tokenlite.py retrieve --id ID [--grep P\|--line N-M\|--field PATH] |
| 查看 CCR 状态 | tokenlite.py stats |
| 清理过期 CCR | tokenlite.py cleanup |
| 审计近期 sense 调用 | tokenlite.py audit --json |
| 回复预算建议 | tokenlite.py lean budget --user-msg "..." --json |
格式相关行为（摘自官方算法说明）
- JSON 数组：超过五条记录时，优先保留嵌套错误、失败状态、模式变体、稀有分类值与数值离群点，再按预算做确定性抽样；结果带
_tokenlite_meta统计。全文仍可通过 CCRretrieve。 - 日志：规范化时间戳、ID、路径等变量后折叠重复模式，错误/致命行保持原序可见。
- 搜索结果：按文件分组、去重，保留有代表性的匹配与稀有唯一匹配。
- 纯文本：去重与低信息填充，保留标题、列表、警告等结构行；若压缩后体积不降反升，则回退原文（anti-expansion）。
遥测默认关闭；仅当设置 TOKENLITE_TELEMETRY=1 时启用，且仍为本地行为。
安装与启用¶
SkillHub 官方安装说明见 skillhub.md。先确认 CLI：
command -v skillhub && skillhub --version
未安装时可执行完整安装（含默认 Skill）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
安装本 Skill 时，必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 可能不会被识别：
skillhub install @user_a72d54a9/tokenlite --dir <skills 目录>
常用路径示例（来自 SkillHub 安装文档）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
也可将提示词交给 AI，让其按上述文档安装 @user_a72d54a9/tokenlite。
典型用法¶
收到较大的非代码工具输出后，建议先 sense，再使用返回的 content 字段参与后续对话；若 auto_compressed=true，记下 ccr_id 以便按需取回。
- 评估（多行或大文件优先
--input，避免--text在 shell 引号下损坏内容）：
python "{{skillDir}}/scripts/tokenlite.py" sense --input OUTPUT_FILE --json
- 需要细节时局部检索：
python "{{skillDir}}/scripts/tokenlite.py" retrieve --id ID --grep "ERROR|timeout"
python "{{skillDir}}/scripts/tokenlite.py" retrieve --id ID --line 100-160
python "{{skillDir}}/scripts/tokenlite.py" retrieve --id ID --field results.0.error.detail
- 若返回
reason=protected:code，应直接使用原始content，不要对源码再走压缩流程。
可选：在用户阅读 references/privacy-and-hooks.md 并同意后，可预览或安装 SessionStart Hook：
python "{{skillDir}}/scripts/hooks/install-hook.py" --dry-run
python "{{skillDir}}/scripts/hooks/install-hook.py"
python "{{skillDir}}/scripts/hooks/install-hook.py" --uninstall
{{skillDir}} 替换为安装后的 Skill 目录路径；完整参数见 tokenlite.py --help。
适用场景与注意¶
适合
- 工具返回超大日志、JSON 数组、搜索结果或重复文本，上下文即将触顶。
- 用户明确要求减少 token、压缩上下文、取回被省略细节，或核对是否执行过压缩（
audit）。
不适合
- Skill 简介明确写出：不要用于缩短源代码或用户手写输入。
- 需要逐字保留的 prose：文本压缩是启发式，精确措辞应走 CCR
retrieve。 - 把 CCR 当长期密文存储：本地临时、未加密，敏感内容需用户接受风险。
在 SkillHub 上，该 Skill 评分为 100000，下载约 782 次（以页面与索引数据为准，会随时间变化）。
结尾¶
TokenLite 把「省上下文」和「别压坏关键证据」绑在同一套契约里：压缩的是可归纳的工具输出，代码与用户输入守住底线，遗漏部分靠 CCR 按 grep、行号或 JSON 路径补回。若要安装或查看说明，可访问 SkillHub 页面 TokenLite 安全上下文压缩策略 或 API 坐标 https://api.skillhub.cn/user_a72d54a9/tokenlite。
