Semantic Compressor

语义压缩器

压缩代理/技能同时保留理解能力。使用5阶段迭代质量保证流程。

工作流: 5阶段质量循环

对每个要压缩的文件，按顺序执行所有阶段:

阶段 1: 原始验证

目标: 确认 Claude 正确理解原始文件。

# 从原始文件提取理解
claude -p "阅读并回答:
1. 主要目的是什么?(1句话)
2. 有哪些关键特性?(要点列表)
3. 有哪些命令/工具可用?
4. 应该由哪些触发词激活?

<文件内容>

以结构化的 YAML 格式输出。"

将输出保存为 <name>.original-understanding.yaml

阶段 2: 压缩

目标: 应用压缩规则创建压缩版本。

⚠️ 必须保留检查清单 (67%的文件因遗漏这些需要迭代)

压缩之前，从原始文件提取并列出:
□ 所有触发词(每个关键词都必须保留)
□ 所有命令(每个命令都必须列出)
□ 所有工具(每个工具都必须列出)
□ 所有支持的格式/类型(文件格式、输出格式、协议)
□ 所有功能类别(功能不能省略)
□ 所有数据库名称/语言名称(特定名称不能用"等"替代)

压缩规则:

针对描述(frontmatter):
  - 移除: "此技能/代理提供..."、"全面的"、"高级的"
  - 移除: "在...时使用"、"旨在..."、"使用户能够"
  - 保留: 所有触发关键词、文件扩展名、动作动词
  - 格式: [目的 <15词]。[特性列表]。触发词: [关键词]
  - 目标: 3:1 比例

针对正文内容:
  - 段落 → 单句
  - 冗长的列表 → 简洁的要点
  - 多个示例 → 最佳单个示例
  - 保留: 代码块、表格(压缩)、命令
  - ⚠️ 永远不要使用"等"、"以及更多"、"例如" - 列出所有项目
  - 目标: 2:1 比例

针对代理:
  - 描述: 最多1-2句话
  - 工具: 列出所有，不加描述
  - 流程: 编号单行
  - 输出: 仅模板
  - 目标: 2:1 比例

阶段2检查清单(压缩前验证)

在编写压缩版本之前，验证:
✓ 原始文件中的每个触发词都出现在压缩版本中
✓ 原始文件中的每个命令都出现在压缩版本中
✓ 原始文件中的每个工具都出现在压缩版本中
✓ 每个功能类别都被提及(可以简短)
✓ 所有特定名称(数据库、语言、格式)都已列出

将压缩版本写入 <name>.compressed.md

阶段 3: 压缩验证

目标: 确认 Claude 正确理解压缩版本。

# 从压缩版本提取理解
claude -p "阅读并回答:
1. 主要目的是什么?(1句话)
2. 有哪些关键特性?(要点列表)
3. 有哪些命令/工具可用?
4. 应该由哪些触发词激活?

<压缩内容>

以结构化的 YAML 格式输出。"

将输出保存为 <name>.compressed-understanding.yaml

阶段 4: 比较与决策

目标: 比较原始理解与压缩理解。

claude -p "比较这两个理解提取。

原始:
<original-understanding.yaml>

压缩:
<compressed-understanding.yaml>

问题:
1. 目的是否相同?(是/否)
2. 是否保留了所有关键特性?(列出任何遗漏的)
3. 是否保留了所有命令/工具?(列出任何遗漏的)
4. 是否保留了所有触发词?(列出任何遗漏的)
5. 总体: 通过 或 需要改进?

如果需要改进，指定需要添加回什么。"

决策:

• 如果通过 → 阶段 5 (报告)
• 如果需要改进 → 带着反馈返回阶段 2

阶段 5: 报告

目标: 生成最终比较报告。

## <name>

| 指标 | 原始 | 压缩 | 比例 |
|--------|----------|------------|-------|
| 行数 | X | Y | X:Y |
| Token(估算) | X | Y | X:Y |

### 理解比较
- 目的: ✓ 已保留
- 特性: ✓ 全部保留 / × 遗漏: [列表]
- 命令: ✓ 全部保留 / × 遗漏: [列表]
- 触发词: ✓ 全部保留 / × 遗漏: [列表]

### 质量: 通过 ✓ / 失败 ×

快速命令

项目目录自动扫描模式

运行无参数的 /semantic-compressor 时:

步骤 1: 发现

# 查找项目中的所有技能和代理文件
find .claude/skills -name "*.md" -o -name "SKILL.md"
find .claude/agents -name "*.md"

步骤 2: 备份(必需)

# 在任何更改之前创建时间戳备份
BACKUP_DIR=".claude/backups/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"
cp -r .claude/skills "$BACKUP_DIR/"
cp -r .claude/agents "$BACKUP_DIR/"
echo "✓ 备份已创建: $BACKUP_DIR"

步骤 3: 处理每个文件

对每个发现的文件:

1. 跳过已压缩的文件(检查 # 已压缩 注释)
2. 运行5阶段工作流
3. 用压缩版本替换原始版本(原始文件在备份中)
4. 添加 # 由 semantic-compressor 在 <日期> 压缩 头部

步骤 4: 生成报告

## 压缩报告

| 文件 | 原始 | 压缩 | 比例 | 迭代次数 | 状态 |
|------|----------|------------|-------|------------|--------|
| skill-a.md | 500 | 120 | 4.2:1 | 1 | ✓ 通过 |
| agent-b.md | 300 | 80 | 3.8:1 | 2 | ✓ 通过 |

总计: 压缩了 X 个文件，节省了 Y 个 token
备份: .claude/backups/YYYYMMDD_HHMMSS/

示例文件

位于 .claude/skills/semantic-compressor/samples/:

samples/
├── skills/
│   ├── verbose/        # 原始冗长版本
│   └── compressed/     # 压缩版本
└── agents/
    ├── verbose/        # 原始冗长版本
    └── compressed/     # 压缩版本

不要压缩

• 错误消息(需要确切文本)
• 安全指令
• 代码语法
• 数值阈值
• 文件路径

质量阈值

如果比例 < 阈值 或 信息丢失 > 0%，标记为需要改进。