cms-tbs-knowledge-splitter

SKILL.md

---
name: cms-tbs-knowledge-splitter
description: 知识条目拆分 Skill。执行前须向用户采集品种名称、待转换PPTX、存放目录（新建会话禁止沿用历史目录）。将PPTX解析为MD，两步法生成知识条目JSON，合并去重Excel。触发词：拆分知识条目/生成知识条目/知识库构建/构建知识库。
skillcode: cms-tbs-knowledge-splitter
github: https://github.com/xgjk/tbs-skills/tree/main/cms-tbs-knowledge-splitter
dependencies:
  - cms-auth-skills
version: 1.5.2
---

# cms-tbs-knowledge-splitter

## 核心定位

本 Skill **只做编排**：按 `references/stage1-parse.md` → `references/stage2-generate.md` → `references/stage3-merge.md` **单主线**推进。阶段一 PPTX→MD（文件处理服务）；阶段二 MD→知识条目 JSON（两步法）；阶段三合并去重 Excel。

适用场景：从培训类 PPTX 系统性构建药品/器械知识库条目。

## 任务分流（进入链路前先判断意图）

| 用户意图 | 判断依据 | 处理方式 |
|---------|---------|---------|
| **执行类**（拆分/建库） | 「拆分知识条目」「生成知识库」「构建知识库」等主动动作 | **先**完成「任务参数采集」门禁（见下节），再进入阶段一至三 |
| **咨询类**（了解规则/流程） | 询问用法、流程、分类体系等 | 不执行脚本；结合 `SKILL.md` 与相关 `references/` 说明 |
| **排障类**（某步失败/结果异常） | 具体报错、条数不对、Excel 异常等 | 先读 `references/pitfalls.md`；未覆盖再查 `references/failure-examples.md`；定向到对应阶段文档；不重置已通过的前置阶段 |

> 同一会话内，用户「咨询」后表达执行意图，再切换到执行类。排障不默认重做已完成阶段。

## 任务参数采集（执行类门禁 — 最先执行）

**新建会话**或用户**未在本条消息中**同时给出下列三项时，**只向用户提问，禁止调用任何工具**（含扫盘、`read`、`exec`、鉴权、阶段脚本）。细则见 `references/session-bootstrap.md`。

| 必填项 | 用途 |
|--------|------|
| **品种名称** | `{品种}_source`、`knowledge_entries_{品种}` 等 |
| **待转换文档** | 明确 PPTX 路径/文件名，或「源目录内全部」 |
| **存放目录** | 本次产出工作根目录（见 `references/output-layout.md`） |

**禁止**：因工作区已存在 `美泰彤_source` 等历史目录、或侧边栏旧会话记录，而默认本次任务参数。**本会话须由用户明文提供或确认**后，方可复述并进入鉴权。

用户已一次性给出三要素 → **先复述确认**，用户确认后再执行标准流程。

## Quick Reference

**每步必读（正常执行路径）**

| 阶段 | 必读文档 |
|------|---------|
| 执行类启动（进鉴权前） | `references/session-bootstrap.md` |
| 鉴权（进阶段一前） | `references/auth.md` |
| 阶段一：PPTX→MD | `references/stage1-parse.md` |
| 阶段二：MD→JSON | `references/stage2-generate.md` |
| 阶段三：合并 Excel | `references/stage3-merge.md` |

**按需查阅（出错 / 疑问时才读，正常路径不触发）**

| 场景 | 查阅文档 |
|------|---------|
| 目录与产出路径 | `references/output-layout.md` |
| 12 分类 / JSON 字段名 | `references/glossary.md` |
| 跨阶段易错点 | `references/pitfalls.md` |
| 报错样例与处理 | `references/failure-examples.md` |
| 文件处理服务 API | 仓库内 `tbs-skills/文件处理服务API说明.md`（与 skill 同级；未入库时见 `stage1-parse.md` 接口摘要） |

## 全局约束（横切）

- **鉴权**：细则见 `references/auth.md`（`appKey` 获取/注入/禁止项；**禁止**用 `access-token` 调文件处理服务）。
- **分类 / 过滤 / 拆分 / 条数控制 / 两步法 prompt**：以 `references/stage2-generate.md` 为准（1 课件 1 MD 1 次阶段二；条数由内容决定，非固定 30 条）。
- **去重与 Excel 列**：以 `references/stage3-merge.md` 与 `scripts/merge_excel.py` 为准。
- **产出路径**：以 `references/output-layout.md` 为准。
- **阶段一 MD**：落盘前剔除 API 输出的演讲者 `### Notes:` 讲稿；幻灯片上的「备注：」等正文保留（见 `references/stage1-parse.md`）。

## 门禁（必须遵守）

- **任务参数未采集/未确认**（品种、待转换文档、存放目录）→ **禁止**鉴权与阶段一至三（见 `references/session-bootstrap.md`）。
- 未取得有效 **`appKey`**（经 `cms-auth-skills`）→ **禁止**调用 `convert_pptx.py`（见 `references/auth.md`）。
- **阶段一**：存在解析失败文件时，可继续阶段二，但须汇总失败列表；是否阻断由业务要求决定，默认继续处理已成功 `.md`（见 `references/stage1-parse.md`）。
- **阶段二**：**禁止**对 `*_partN.md` 分别生成 JSON；每课件 **1 个 MD → 1 个 JSON**；**净字符 >8000 禁止子代理**（用档位 B 主会话）。须通过 **JSON 完成判定** 后才可进阶段三（见 `references/stage2-generate.md`）。
- **阶段一 413**：**禁止**拆 PPT 后继续链路；优先异步重试或压缩源文件（见 `references/stage1-parse.md`）。
- **阶段三**：`merge_excel.py` 无任何有效 `知识条目` → **禁止**视为建库完成；退出码 `2` 时不得进入交付（见 `references/stage3-merge.md`）。

## 标准执行流程（必须遵循）

0. **任务参数采集**（仅执行类）：按 `references/session-bootstrap.md` 向用户索取或复述确认三要素；**新建会话不得跳过**。
1. **鉴权**：读取 `references/auth.md`，经 `cms-auth-skills` 取得 `appKey`；未就绪禁止阶段一。
2. **阶段一**：读取 `references/stage1-parse.md`，完成 PPTX→MD。
3. **阶段二**：读取 `references/stage2-generate.md`；按净字符选档位 A/B/C；逐文档 MD→JSON；**每文档通过 JSON 完成判定后**再处理下一文档或进阶段三。
4. **阶段三**：**全部待合并 JSON 均通过完成判定后**，同一会话内立即执行 `merge_excel.py`（**不等**用户再下指令）。
5. **收尾**：汇总各阶段失败/跳过列表；阶段三退出码 `1` 时须向用户说明部分文件未纳入合并。

## OpenClaw / 编排器执行约定

细则见 `references/stage2-generate.md`（档位、JSON 完成判定）。编排器**必须**遵守：

### 禁止

- **未采集并确认**品种、待转换文档、存放目录前，扫工作区或调用 `convert_pptx.py`（即使用户只说「使用本技能拆分」）
- 启动子代理 / 长任务后说「完成后会自动通知」并**结束当前轮次**
- **未通过 JSON 完成判定**即进入阶段三
- **重型文档**（净字符 **>8000**）使用子代理处理（须用档位 **B** 主会话）

### 必须 — 进度汇报

- **启动阶段二前**：告知「共 **Y** 个 MD，当前第 **X** 个：**{文件名}**，档位：**A/B/C**」
- **长任务**（重型文档或预计 **>3 分钟**）：主会话**每约 2 分钟**更新一次，格式：  
  `阶段二进行中：{文档名}，已用时约 N 分钟，状态：{主会话生成中 / 子代理运行中 / 校验 JSON}`
- **单个文档完成**：立即汇报条数与 JSON 完成判定结果，**不必**等全部 MD 完成
- **全部通过完成判定**：**同一会话内立即**执行阶段三，不等用户指令

### 用户追问「好了吗 / 没动静」

先查产出目录与 **JSON 完成判定**，再回答；未完成则说明**当前档位**与进度，**不得**仅回答「还在等子代理」。

## 排障说明（按需）

正常路径以各阶段文档中的脚本与门禁为准。`references/pitfalls.md`、`references/failure-examples.md` 仅在异常时查阅，不在正常路径中强制读取。