# Semantic Compressor

> 带质量保证循环的agent/skill压缩。5阶段迭代流程确保理解保留。 触发词: semantic-compressor, compress skill, optimize agent, reduce tokens, benchmark

- Skill: `majiayu000/semantic-compressor` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/semantic-compressor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/semantic-compressor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/semantic-compressor

---


# 语义压缩器

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

## 工作流: 5阶段质量循环

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

### 阶段 1: 原始验证

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

```bash
# 从原始文件提取理解
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 正确理解压缩版本。

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

<压缩内容>

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

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

### 阶段 4: 比较与决策

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

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

原始:
<original-understanding.yaml>

压缩:
<compressed-understanding.yaml>

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

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

**决策:**
- 如果通过 → 阶段 5 (报告)
- 如果需要改进 → 带着反馈返回阶段 2

### 阶段 5: 报告

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

```markdown
## <name>

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

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

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

---

## 快速命令

| 命令 | 操作 |
|---------|--------|
| `/semantic-compressor` | 自动扫描项目 `.claude/skills/` 和 `.claude/agents/`，压缩所有 |
| `/semantic-compressor <file>` | 对单个文件运行5阶段循环 |
| `/semantic-compressor benchmark` | 对所有示例运行5阶段循环 |
| `/semantic-compressor verify <file>` | 仅阶段1+3(不压缩) |

---

## 项目目录自动扫描模式

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

### 步骤 1: 发现
```bash
# 查找项目中的所有技能和代理文件
find .claude/skills -name "*.md" -o -name "SKILL.md"
find .claude/agents -name "*.md"
```

### 步骤 2: 备份(必需)
```bash
# 在任何更改之前创建时间戳备份
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: 生成报告
```markdown
## 压缩报告

| 文件 | 原始 | 压缩 | 比例 | 迭代次数 | 状态 |
|------|----------|------------|-------|------------|--------|
| 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/     # 压缩版本
```

## 不要压缩

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

## 质量阈值

| 类型 | 最小比例 | 最大信息丢失 |
|------|-----------|---------------|
| 技能描述 | 2.5:1 | 0% 触发词 |
| 技能正文 | 2:1 | 0% 命令 |
| 代理 | 2:1 | 0% 工具 |

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