Coze KB Organizer — 扣子知识库整理与汇总

定位

本 Skill 是连接「原始文档」与「Coze 智能体高效检索」之间的核心管道。它不只是格式转换器，而是一套完整的知识工程流水线，把任意 PDF/DOCX 文档加工成 Coze Bot 能「真正理解并精准检索」的结构化知识单元。

为什么需要这个 Skill？

Coze 知识库的检索质量不取决于文档数量，而取决于文档的结构化程度和语义密度。原始文档直接导入存在以下问题：

本 Skill 系统性解决上述问题。

v2.0 更新 (2026-05-14)

基于 RAG 检索最佳实践（Redis/Databricks/Coze官方文档）的 6 项重大改进：

触发词

以下关键词或短语出现时，立即加载并执行本 Skill：

处理流水线

原始文档 (PDF/DOCX)
    │
    ▼
【阶段一：格式转换】 doc_converter.py
    ├── PDF → 文本提取（PyMuPDF，保留段落/表格/图片描述）
    ├── DOCX → 文本提取（python-docx，保留标题层级/表格/列表）
    └── 输出：原始结构化 Markdown
    │
    ▼
【阶段二：知识增强】 kb_enhancer.py
    ├── 语义分块：按主题边界智能切分（非固定长度）
    ├── 元数据生成：标题、分类、标签、实体、关键词
    ├── FAQ 生成：从内容中抽取/生成 5-10 个问答对
    ├── 多级摘要：文档级摘要 + 章节级摘要
    ├── 实体标注：人名/地名/技术术语/产品名/版本号
    └── 输出：增强版 Markdown
    │
    ▼
【阶段三：双格式输出】
    ├── MD 输出：可直接导入 Coze 知识库
    └── DOCX 输出：md_to_docx.py 生成格式化的 Word 文档

阶段一：格式转换

执行方式

调用 scripts/doc_converter.py，支持单文件和批量处理：

python scripts/doc_converter.py --input <文件路径> --output <输出目录>
python scripts/doc_converter.py --batch <文件夹路径> --output <输出目录>

转换规则

DOCX → MD 映射：

PDF → MD 映射：

• 使用 PyMuPDF 提取文本
• 自动检测标题（通过字号/加粗/位置）
• 表格区域检测并转为 Markdown table
• 保留页眉页脚标注
• 图片区域标注为 [图片: 描述]

预处理规则

• 去噪：移除页眉页脚中的页码/日期等元信息
• 断行合并：将 PDF 中因换页导致的段落断裂重新拼接
• 编码统一：全角半角标点统一为中文标点规范
• 空行规范：段落间保留一个空行

阶段二：知识增强（核心）

这是提升 Coze Bot 检索精度的关键阶段。

2.1 语义分块策略

不使用固定长度切分，而是按语义边界智能分块：

识别规则：
1. 以 ## 二级标题为分块边界
2. 单块最小长度：100 字（过短合并到上一块）
3. 单块最大长度：1500 字（超长在段落边界切分）
4. 表格独立成块，不切断
5. 列表保持完整，不被分断

每块输出格式：

<!-- chunk:id=001 | type:概述 | entities:Unreal Engine 5,AI插件 | keywords:UE5,AI辅助开发,编辑器插件 -->
## [分块标题]
[内容]

2.2 元数据头部生成

每份文档在开头插入 YAML 元数据头部：

---
doc_id: "游戏产品-萌坦大作战"
title: "萌坦大作战游戏设计文档"
category: "游戏产品"
subcategory: "坦克对战"
tags: ["卡通风格", "坦克对战", "无尽模式", "UE4", "排行榜"]
entities:
  - 人物: ["独立游戏Sun", "孙天愉"]
  - 引擎: ["虚幻引擎4"]
  - 阵营: ["帝国军统", "反抗军", "军团"]
  - 等级: ["Probationary", "Elite", "Guardian", "Master", "God of War", "Chief", "Chief Master"]
summary: "一款卡通风格的坦克对战游戏，包含三大阵营、七级等级系统、五大连杀奖励、传奇坦克雇佣等核心玩法。"
keywords: ["萌坦大作战", "坦克对战", "卡通风格", "无尽模式", "排行榜", "UE4"]
created: "2025-05-14"
processed_by: "coze-kb-organizer v1.0"
---

2.3 FAQ 自动生成

从文档内容中提取或推理 5-10 个高频问题，以 Q&A 对 格式追加到文档末尾：

## 常见问题 (FAQ)

**Q1: 萌坦大作战有多少个阵营？**
A: 三大阵营：帝国军统（紫色，设计精良火力强大）、反抗军（废墟拼凑，灵活多变）、军团（蓝色，质量过关火力强劲）。

**Q2: 无尽模式有哪些要素？**
A: 可破坏的红色砖块、不可破坏的白色砖块、道具（技能点、急救包）、危险物（灰色地雷）、基地摧毁扣2000分。

**Q3: 连杀奖励系统的最高级别是什么？**
A: 炮艇舰，需50级以上且击杀25辆坦克，拥有三种口径炮弹，属于超级武器级别。

FAQ 生成原则：

• 优先从文档中直接提取「定义性问题」
• 补充「对比性问题」（如 A 和 B 的区别）
• 补充「场景性问题」（如什么情况下触发 X）
• 补充「操作性问题」（如如何使用 X）
• 每个 Q&A 控制在 30-150 字

2.4 关键词提取与标注

为每个语义块和整篇文档提取关键词，增强 Coze 的语义检索匹配度：

• 技术类文档：提取技术名词、API 名称、版本号、配置参数
• 产品类文档：提取产品名、功能名、竞品名、使用场景
• 工作流文档：提取步骤关键词、工具名、输入输出格式

关键词追加到每个 chunk 的注释和文档头部元数据中。

2.5 实体关系标注

在文档末尾生成实体关系表，帮助 Bot 理解概念关联：

## 实体关系索引

| 实体A | 关系 | 实体B | 说明 |
|-------|------|-------|------|
| 帝国军统 | 拥有 | 传奇坦克 | 可雇佣的超级战车 |
| 玩家 | 达到等级 | Guardian | 30级解锁 |
| 连杀5辆 | 激活 | UAV无人侦察机 | 持续250秒 |
| 幻影左轮手枪 | 属于 | 猎鹰小队 | 最新研发武器 |

阶段三：双格式输出

MD 输出（Coze 知识库导入）

输出到 {output_dir}/md/ 目录：

{output_dir}/
├── md/
│   ├── {文档名}_enhanced.md     # 增强版（含元数据+FAQ+实体索引）
│   └── {文档名}_original.md     # 原始版（纯格式转换，无增强）

推荐导入 Coze 时使用 _enhanced.md，它包含了完整的元数据和增强标注，可显著提升检索精度。

DOCX 输出

调用 scripts/md_to_docx.py：

python scripts/md_to_docx.py --input {增强版MD路径} --output {输出目录}

生成格式化的 Word 文档，保留：

• 标题层级样式（Heading 1-4，蓝色主题色）
• 表格（带边框和交替行底色）
• 代码块（Consolas 字体，灰色背景）
• 元数据头部（灰色提示框样式）
• FAQ 区域（Q 加粗蓝色，A 常规黑色）
• 实体关系表（绿色表头）

执行规范

批量处理流程

当用户提供文件夹或多文件时：

1. 扫描：识别所有 .docx / .pdf 文件
2. 分类：按文件目录结构自动推断分类（如 游戏产品/ → category: "游戏产品"）
3. 并行处理：每个文件独立执行完整的「转换→增强→输出」流水线
4. 汇总报告：生成 _汇总报告.md，列出所有处理结果

分类自动推断规则

质量检查清单

处理完成后自动检查：

• [ ] 所有标题层级完整无丢失
• [ ] 表格全部转换为 Markdown table 格式
• [ ] 元数据头部包含所有必要字段
• [ ] 每个语义块有 chunk 注释
• [ ] FAQ 数量 ≥ 5 条
• [ ] 关键词 ≥ 5 个
• [ ] 实体关系表非空（如有实体）

错误处理

使用示例

示例 1：单文件处理

用户输入：

> 帮我把这个文档整理成Coze知识库格式 E:/知识库/游戏产品/萌坦大作战.docx

执行步骤：

1. 加载本 Skill
2. 执行 doc_converter.py --input "...萌坦大作战.docx" → 生成原始 MD
3. 执行 kb_enhancer.py --input "原始MD" → 生成增强 MD
4. 执行 md_to_docx.py --input "增强MD" → 生成 DOCX
5. 输出双格式文件，展示增强效果摘要

示例 2：批量文件夹处理

用户输入：

> 把 E:/OpenCLaw数字员工系统/知识库整理/ 下面所有的文档都整理一遍

执行步骤：

1. 扫描目录，发现 5 个 .docx 文件
2. 按子目录自动推断分类
3. 逐文件执行完整流水线
4. 生成汇总报告
5. 打包输出

示例 3：仅转换不做增强

用户输入：

> 把这些PDF转成Markdown就行，不用增强

执行步骤：

1. 仅执行 doc_converter.py（阶段一）
2. 跳过知识增强（阶段二）
3. 输出纯格式转换的 MD 文件

参考资源

• 格式转换脚本：scripts/doc_converter.py
• 知识增强脚本：scripts/kb_enhancer.py
• MD→DOCX 脚本：scripts/md_to_docx.py
• Coze 知识库最佳实践：references/coze_kb_best_practices.md