工作资料蒸馏器（Work Distill Skill）

核心理念（先看这个）

把"工作资料"（任何格式）蒸馏为"可直接调用的工作方法论 skill"。

铁律：蒸馏产出的每一份 skill 必须能回答两个问题——
1. "加载这个 skill 后，agent 会有什么不一样的行为？" 答不出 → 这是知识摘抄，不是 skill，删掉重做。
2. "用这个 skill 比不用，能省多少 token / 少调多少次？" 答不出 → 没有经济价值，不值得蒸馏。

触发条件

适用以下任一情景（用户原话或意图匹配）：

• "把这份 PPT/方案/纪要蒸馏成 skill"
• "用这个文档整理出工作方法"
• "把这次投标经验沉淀下来"
• "把这个做成 SOP 让以后都用得上"
• "把这段对话/微信记录整理成可复用的"
• "蒸馏一下 <文件/URL/对话>"
• "这个文档能变成 skill 吗？"
• "我的工作流能不能自动化？"
• 用户扔过来一份文件 + "整理一下/沉淀一下/变方法论"

不适用的反触发（避免误判）：

• "把这个文档翻译成英文" → 翻译 skill
• "帮我写一篇 XX 文章" → 写作 skill
• "看看这个文件讲了什么" → 普通读文件
• 不带工作属性的纯学习/娱乐资料

跨平台输出约定（核心差异）

任何蒸馏产出必须同时写两个文件，覆盖不同 agent 平台：

两者内容主体一致，frontmatter 格式不同（详见 references/cross-platform-output.md）。

本蒸馏器支持的 9 个主流平台路径（机器上有哪个就装到哪个，由用户自行选择）：

核心工作流

阶段 0｜文件获取与格式识别

3件事按顺序做：

1. 文件类型判断（看扩展名，不读内容）：
   - .md/.docx/.pdf/.pptx/.xlsx → 直接读取内容
   - .jpg/.jpeg/.png/.gif/.bmp → vision_analyze 读图
   - .mp3/.wav/.m4a/.aac → audio_transcribe 转文字
   - .mp4/.mov/.avi/.webm → 先提音频再转文字
   - .html/.htm → html2markdown 或 browser_snapshot
   - .txt → 直接读
   - 未知/混合 → 提示用户确认文件类型

2. 编码检查（读到的文本）：
   - 是否有大量乱码（PDF 扫描件特征：字符集异常、符号代替汉字）→ 扫描件，跳门 1
   - 编码是否是 GBK/GB2312（中文 PDF 常见）→ 尝试 encoding='gbk' 重新读
   - 编码是否是 Latin-1（表格/特殊字符 PDF 常见）→ 尝试 encoding='latin-1' 重新读

3. 门 0｜扫描件检查（失败则跳转 OCR）：
   - PDF 总字符 < 1k 且有大量连续空格/乱码 → 扫描件，进 OCR
   - OCR 失败必须告知用户，不能默默跳过

门 0｜扫描件检查：
- 扫描 PDF 转化率：总字符 > 10k 且无明显乱码 → ✅；< 1k → ⚠️ 需换工具或告知用户
- 图片理解：vision_analyze 识别失败（返回空白/报错）→ 直接用 OCR 结果，不卡死
- OCR 失败的文件必须告知用户，不能默默跳过

阶段 1｜领域识别 + 价值诊断 + 模型密度判断

三件事必须做完才能进阶段 2：

1. 领域识别（domain） —— 给出 6 个候选之一：
   - marketing（营销/客户/招标/评分/匹配度/漏标/跟进）
   - reporting（汇报/PPT/方案/公文）
   - feishu（飞书协作/审批/多维表格）
   - fiction（小说方法论/写作技法）
   - admin（行政管理/日程/财务/合规）
   - sales（销售对话/客户关系/话术）
   - general（跨域通用方法论，如决策框架、沟通技巧、领导力）

2. 价值诊断 —— 三问（必须全部通过才能进阶段 2）：
   - Q1: "这份资料有没有我不知道的 SOP/模板/判断标准？" → 有 → 通过；没有 → 终止
   - Q2: "这个 SOP 未来我还会遇到类似的吗？" → 会 → 通过；不会 → 终止
   - Q3: "这个 SOP 比现在用的版本有改进吗？" → 有 → 通过；没有 → 终止

若 Q2 答"只能停在道理"，不要产出 skill——避免污染 skill 库。

3. 模型密度判断（决定读多深）：
   - 精华散落（方法论类书籍/经验总结）→ 用定向提取，不读全文
   - 精华集中（方案/报告/SOP）→ 直接读对应章节
   - 表格/图示 → 用 vision_analyze 补充

阶段 2｜定向取材 + 五要素笔记

4步：

1. 定向关键词提取（按 domain，不读全文）：
   - 领域关键词 + 同类场景词 + 方法论词
   - 用 targeted_extract.py 跑，输出结构化片段
   - 全程 token 上限：max_tokens=2048

2. 五要素笔记写进 Layer 1 文件（每条素材一段）：

## <素材编号> <一句话主题>

- **来源**：<文件名> / <章节>
- **原文精华**：<50-200字核心内容>
- **我的疑问**：<读到这里时的困惑>
- **关联概念**：<已掌握的哪些概念与此相关>
- **行动指引**：<准备用在哪里>

3. 判断每条素材的模型密度：
   - 精华散落（200+ 条无详解标题列表）→ 提取可操作原则 + 合并相似主题 + 有详解的深挖为核心模型
   - 有具体 SOP / 模板 / 判断标准 → 直接进入阶段 3

4. 实施：用 scripts/targeted_extract.py 跑（支持多文件输入的关键词定向提取）。

Layer 1 文献笔记：五要素模板（阶段 2 的中间产物）

目录结构（阶段 2 产出）：

<工作域>_skill_库/
├── _index.md          # 目录（按域、token节省量、调用次数减少量排序）
├── _layer1/
│   ├── _index.md      # Layer 1 汇总
│   └── 001_<主题>.md  # 五要素笔记

阶段 3｜结构化 skill 写出（SKILL.md + AGENTS.md）

SKILL.md 标准格式（必须含以下部分）：

---
name: <skill-name>
description: <trigger condition + output format>
aid: e5b0b9e9be99
version: 1.0.0
metadata:
  hermes:
    skill_type: skill
    project: null
    area: <domain>
    status: active
    use_count: 0
    created_at: <today>
    last_used: null
---

# <Skill 标题>

## 使用场景
（用户什么情况下该调用这个 skill）

## 使用方法
（agent 加载后执行的具体 SOP，分步骤）

## 示例对话
（用前/用后对比，token/call 节省估算）

## 注意事项
（常见错误/边界情况）

关键纪律（写在前面）

1. "知识摘抄" ≠ skill。蒸馏不是把资料压成摘要，是把资料里"未来还会遇到的事"变成 SOP。
2. 每个 skill 必须能"行为自证"。问"加载后 agent 会怎么不一样"，答得出 → 过；答不出 → 删。
3. 省 token 是硬指标，不是软指标。每次产出必给"用前/用后"对照数字（哪怕是估算）。
4. 不蒸馏纯个人观点/娱乐内容。工作资料 = 与"你某项工作"直接相关的内容。
5. 跨平台双产物不可省略。只产 SKILL.md 不可接受，至少覆盖 SKILL.md + AGENTS.md。
6. 跨域不混做。一份 skill 只做一个域。营销和小说不要写在同一个 skill 里（避免加载后行为错乱）。

常见陷阱（实测）

阶段 0 相关

• ❌ PDF 是扫描件但当文字型处理 —— pymupdf 返回 0 字符但文件体积 20-50MB，这是扫描件。必须走 OCR 路径。
• ❌ OCR 引擎选了 tesseract —— Windows 上 tesseract 路径配置繁琐，中文包难装。优先 rapidocr-onnxruntime（pip 一键，14MB，无需配置）。
• ❌ 并行 worker 数设太高 —— Windows 上 ProcessPoolExecutor 有进程上限（max_workers > 125 会卡死），设 7 就好。
• ❌ OCR 失败不告知用户 —— 默默跳过导致后面阶段拿到空白文本，浪费大量时间。

阶段 1 相关

• ❌ 不判断模型密度直接读全文 —— 方法论类书籍 200+ 页，全读不如精选。模型密度判断决定是否值得深挖。
• ❌ 图片占位符当正文 —— 某页 OCR 不到 50 字符但前后页内容丰富，说明该页有图。需要 vision_analyze 补全。

阶段 2 相关

• ❌ Layer 2 永久笔记直接复制 Layer 1 —— 必须重写，要变成"可执行的 SOP"，不是"概念的重新表述"。
• ❌ 写得抽象 —— "提升客户满意度"不是 skill；"招标评审得分 < 60 分 → 启动客户申诉流程，24h 内响应"才是 skill。

阶段 3 相关

• ❌ SKILL.md 缺少示例对话 —— 没有"用前/用后"对照，agent 不知道该怎么用这个 skill。
• ❌ description 太模糊 —— 必须是"当用户说 X 时，输出 Y 格式"，不是"这个 skill 很有用"。
• ❌ AGENTS.md 与 SKILL.md 脱节 —— 两者主体必须一致，只是 frontmatter 格式不同。
• ❌ domain 标签打错 —— 标签决定 agent 是否加载，必须与阶段 1 一致。

通用相关

• ❌ 不更新 _index.md —— 新 skill 加入后必须更新目录，否则石沉大海。
• ❌ 蒸馏完不告知 token 节省量 —— 用户最关心的指标，每份产出必给。
• ❌ 不记录使用 —— 每次蒸馏/使用后记一笔到 references/使用记录.md，skill 才有生命周期。

质量自检清单（发出前必过）

# 1. 五要素笔记检查
python scripts/layer_quality_check.py <layer1_dir>

# 2. SKILL.md 结构完整性（description / 使用场景 / 示例对话 / 注意事项）
python scripts/skill_structure_check.py <SKILL.md>

# 3. 价值自检（10 项必过）
python scripts/value_check.py <skill 目录>

# 4. 省 token 测算（≥ 30% 算 PASS）
python scripts/token_estimate.py <SKILL.md> <原文字符数>

# 5. 定向取材
python scripts/targeted_extract.py <源文件> --domain marketing

附录

domain 关键词速查

脚本工具说明

版本与作者