sanguo_moziplus_v2/skills/skill-management/references/distill.md

# DISTILL — 蒸馏规范

## 核心原则：HOW not WHAT

蒸馏的是「怎么做」不是「发生了什么」：

```
❌ "PR #83 修复了 event_type 未知的问题"
    → 这是 WHAT，无法复用

✅ "消费者/生产者字段同步：新增 dataclass 字段时，必须同步所有从 JSON 提取该字段的代码路径"
    → 这是 HOW，可复用到任何消费者/生产者场景
```

## SKILL.md 编写规范

```yaml
---
name: skill-name
description: Use when [触发条件/问题模式描述]，不描述工作流
---

# Skill 标题

## 什么时候用
（具体的触发场景，按问题模式描述，不按技术特定症状）

## 怎么做
（根因分析 + 操作步骤）

## 常见错误
（反模式：什么不该做）

## 来源
（evidence：哪些 task/PR/review 提炼了这条经验）
```

## description 关键规则

- 只描述触发条件（when to use），**绝不描述工作流**（how）
- 以「Use when...」开头
- 描述问题模式，不描述技术特定症状
- 原因：测试发现 description 如果总结了工作流，agent 会按 description 执行而跳过读完整 SKILL.md

### 示例

```yaml
# ❌ BAD：描述了工作流
description: Use when modifying dataclass — checks all extraction points, runs tests

# ✅ GOOD：只描述触发条件
description: Use when modifying a dataclass that is populated from JSON extraction by another module

# ❌ BAD：太抽象
description: Use for code quality

# ✅ GOOD：描述问题模式
description: Use when a field added to a dataclass appears empty or as default value at runtime
```

## 蒸馏示例

**一级蒸馏**（从具体案例提取）：

```yaml
# 案例 1：PromptContext event_type 未知
# 案例 2：PromptContext from_agent/mail_type 缺失（PR #26 D2）
→ 共同根因：消费者/生产者字段同步问题

## 消费者/生产者字段同步

**什么时候用**：修改 dataclass 时，如果该 dataclass 由外部 JSON 提取填充

**怎么做**：
1. 改 dataclass 定义
2. 检查所有从 JSON 提取字段的代码路径，同步新增提取逻辑
3. 检查所有构造该 dataclass 的调用点，同步新增参数
4. 跑一次构建测试验证字段不为空

**常见错误**：只改 dataclass 不改提取逻辑 → 字段默认值为空 → 运行时不报错但行为异常
```

**二级蒸馏**（从多个一级经验提取通用模式）：

如果经验在 ≥2 个不同场景复现，验证通过后，可以提升为独立 Skill 或固化到 AGENTS.md 规则。

## 验证标准

从 draft → active：

| 维度 | 标准 | 不通过 |
|------|------|--------|
| Recurrence-Count ≥ 2 | 同一 Pattern-Key 在 ≥2 个场景出现 | 降级为 MEMORY.md |
| 有生成力 | 能给出具体操作指引 | 丢弃 |
| 有排他性 | 不是常识 | 丢弃 |

提升触发（全部满足）：30 天内 ≥3 次 + 跨 ≥2 个任务。

## Skill Extraction 质量 Gate

| 标准 | 描述 |
|------|------|
| Recurring | 有 See Also 链接到 2+ 个相似信号 |
| Verified | Status 是 resolved 且有工作修复 |
| Non-obvious | 需要实际调试才能发现 |
| Broadly applicable | 不是项目特定，可跨场景复用 |

## 质量检查

| 检查项 | 标准 |
|--------|------|
| trigger 是否具体 | 不是「注意代码质量」 |
| action 是否可执行 | 不是「要小心」 |
| 是否与已有 Skill 重复 | 检查现有 skills 目录 |
| description 是否只含触发条件 | 不包含工作流描述 |

## 矛盾处理

新经验与已有经验冲突时：
- **时间性矛盾**（观点演化）→ 记录演化轨迹，以近期为主
- **领域性矛盾**（不同场景不同规则）→ 分场景记录
- **本质性张力**（价值观内在冲突）→ 标注为「核心张力」，两个版本都保留

**矛盾是特征，不是 Bug。** 强制调和会丢失关键信号。

## 信号输出格式

每条信号包含：
```
信号类型 | 来源 | 时间 | 简述（≤100 字）
ID: SIG-YYYYMMDD-XXX
Priority: low | medium | high | critical
Status: pending | in_progress | resolved | promoted
See Also: SIG-YYYYMMDD-XXX
Recurrence-Count: N
Pattern-Key: category.subcategory
```