\r \r

知识库问答技能 (knowledge-qa)\r

\r

概述\r

\r 本技能支持多知识库架构，每个知识库对应一个独立的 DashVector Collection。用户可在同一工作目录下创建多个互不干扰的知识库（如"MySQLNotes"、"JavaNotes"等）。\r \r 核心特性：\r

• 多知识库支持（一个知识库 = 一个 DashVector Collection）\r
• 语义向量检索（基于阿里云 DashVector + 百炼 Embedding）\r
• 自动分区（raw_docs 子目录自动映射为分区）\r
• 多分区并行查询 + 结果合并\r
• 报告 + 思维导图双输出\r
• 需要 Python 环境（用户需安装 Python 3.8+）\r \r ---\r \r

前置要求\r

\r

1. 安装 Python 环境\r

\r 用户需在系统上安装 Python 3.8 或更高版本，以及以下依赖：\r \r

pip install pdfplumber python-docx requests\r
```\r
\r
### 2. 安装 WorkBuddy 并打开工作目录\r
\r
用户用 WorkBuddy 打开一个工作目录，在该目录下管理所有知识库。\r
\r
---\r
\r
## 多知识库架构\r
\r
```\r
工作空间 (WorkBuddy 打开的目录)\r
│\r
├── MySQLNotes/              ← 知识库 A → Collection: MySQLNotes\r
│   ├── raw_docs/\r
│   │   ├── mysql/           ← 分区: mysql\r
│   │   └── default/\r
│   ├── config.json          ← 独立配置（不同的 DashVector Collection）\r
│   ├── indexed_files.json\r
│   └── README.md\r
│\r
├── JavaNotes/               ← 知识库 B → Collection: JavaNotes\r
│   ├── raw_docs/\r
│   │   ├── java基础/        ← 分区: java_\r
│   │   └── default/\r
│   ├── config.json\r
│   └── README.md\r
│\r
└── scripts/                 ← （由技能提供，用户不可见）\r
    ├── init_knowledge_base.py\r
    ├── upload_to_vector.py\r
    ├── query_knowledge_base.py\r
    └── partition_list.py\r
```\r
\r
**映射关系：**\r
- 1 个知识库文件夹 = 1 个 DashVector Collection（独立配置）\r
- Collection 内按 raw_docs 子目录分区（mysql / oracle / java_ 等）\r
- 切换知识库：由用户在提问时指定，如"基于 MySQLNotes 知识库回答..."\r
\r
---\r
\r
## 工作流程一：创建新知识库\r
\r
**触发词：** "创建知识库"、"初始化一个知识库"、"新建知识库"\r
\r
### 步骤 1：确认知识库名称和工作目录\r
\r
用户告诉 AI 要创建的知识库名称，以及是否在当前工作目录下创建。\r
\r
### 步骤 2：运行初始化脚本\r
\r
```bash\r
python \x3C技能路径>/scripts/init_knowledge_base.py \x3C知识库名称> --path \x3C工作目录>\r
```\r
\r
AI 自动执行脚本，在工作目录下创建以下结构：\r
\r
```\r
知识库名称/\r
├── raw_docs/\r
│   └── default/\r
├── config.json       ← 模板文件，用户需填写阿里云凭证\r
├── indexed_files.json\r
└── README.md\r
```\r
\r
### 步骤 3：提示用户填写配置\r
\r
告知用户打开 `config.json`，填入：\r
- `dashvector.api_key`\r
- `dashvector.endpoint`\r
- `dashvector.collection_name`（建议与知识库名一致）\r
- `bailian.api_key`\r
\r
凭证获取地址：\r
- DashVector: https://dashvector.console.aliyun.com/api-key\r
- 百炼: https://bailian.console.aliyun.com/api-key\r
\r
---\r
\r
## 工作流程二：上传文件到向量库\r
\r
**触发词：** "上传知识库"、"有新文件了"、"帮我索引文件"\r
\r
### 步骤 1：确认目标知识库\r
\r
用户必须指定知识库名称（如"MySQLNotes"）。AI 在工作目录下查找对应的知识库文件夹。\r
\r
### 步骤 2：运行上传脚本\r
\r
```bash\r
python \x3C技能路径>/scripts/upload_to_vector.py --kb-path \x3C知识库路径>\r
```\r
\r
脚本自动：\r
1. 扫描 `raw_docs/` 下所有文件\r
2. 识别新增或变更的文件（对比 `indexed_files.json`）\r
3. 提取文本内容并分块\r
4. 调用百炼 API 生成向量\r
5. 调用 DashVector API 上传（自动创建分区）\r
6. 更新 `indexed_files.json`\r
\r
### 分区识别规则\r
\r
| 文件位置 | 分区名 |\r
|---------|--------|\r
| `raw_docs/文档.pdf` | `default` |\r
| `raw_docs/mysql/文档.pdf` | `mysql` |\r
| `raw_docs/MySQL实战/文档.pdf` | `mysql_`（小写、非字母数字转下划线）|\r
\r
---\r
\r
## 工作流程三：知识问答与报告生成\r
\r
**触发词：** "基于知识库回答"、"查一下知识库"、"帮我写报告"\r
\r
### 步骤 1：确认目标知识库和分区\r
\r
用户必须指定知识库名称（如"基于 MySQLNotes 知识库"）。\r
可选指定分区（如"基于 MySQLNotes 的 mysql 和 oracle 分区"）。\r
\r
### 步骤 2：运行查询脚本\r
\r
```bash\r
python \x3C技能路径>/scripts/query_knowledge_base.py "\x3C问题>" --kb-path "\x3C知识库路径>" --partition \x3C分区名>\r
```\r
\r
示例（单分区）：\r
```bash\r
python scripts/query_knowledge_base.py "InnoDB 有哪些特性" --kb-path "MySQLNotes" --partition mysql\r
```\r
\r
示例（多分区）：\r
```bash\r
python scripts/query_knowledge_base.py "MySQL 和 Oracle 有什么区别" --kb-path "MySQLNotes" --partition mysql,oracle\r
```\r
\r
示例（全分区）：\r
```bash\r
python scripts/query_knowledge_base.py "介绍一下这个知识库" --kb-path "MySQLNotes"\r
```\r
\r
**多分区查询说明：** DashVector 查询 API 的 `partition` 参数只接受字符串（不支持数组），脚本通过**串行多次查询**实现多分区，每个分区独立查询后合并结果，按相似度排序。\r
\r
### 步骤 3：读取原始文档补充上下文\r
\r
根据检索结果中的 `source` 字段，用 `read_file` / `pdf` / `docx` 加载相关章节。\r
\r
### 步骤 4：网络搜索补充（如需要）\r
\r
使用 `Web Search` 搜索实时信息或知识库未覆盖的背景知识。\r
\r
### 步骤 5：生成 Markdown 报告\r
\r
报告格式规范：\r
\r
```markdown\r
# [报告标题]\r
\r
> 生成时间：[YYYY-MM-DD HH:mm]\r
> 知识库：[知识库名称]\r
> 来源：[x] 篇相关文档 + 网络补充\r
\r
## 摘要\r
[简要概述]\r
\r
## 一、[章节标题]\r
[内容...]\r
\r
## 参考来源\r
- [文件名] - 分区: [分区名]\r
```\r
\r
**报告保存路径：** `\x3C工作目录>/\x3C知识库名称>/reports/report_[时间戳]_[主题].md`\r
\r
### 步骤 6：生成思维导图\r
\r
使用 `visualizer:interactive` 工具生成交互式思维导图：\r
- 提取标题层级（# / ## / ###）\r
- 每个节点不超过 20 字\r
- 最多 3 级展示\r
\r
**导图保存路径：** `\x3C工作目录>/\x3C知识库名称>/mindmaps/mindmap_[时间戳]_[主题].html`\r
\r
### 步骤 7：输出结果\r
\r
1. 对话中展示 Markdown 报告\r
2. `visualizer:interactive` 展示思维导图\r
3. 告知用户文件保存路径\r
\r
---\r
\r
## 工作流程四：查看分区状态\r
\r
**触发词：** "有哪些分区"、"分区列表"、"查看分区"\r
\r
```bash\r
python \x3C技能路径>/scripts/partition_list.py --kb-path \x3C知识库路径>\r
```\r
\r
---\r
\r
## 文档格式支持\r
\r
| 格式 | 读取方式 |\r
|------|--------|\r
| `.md` | 直接 `read_file` |\r
| `.pdf` | `pdf` skill |\r
| `.docx` / `.doc` | `docx` skill |\r
\r
---\r
\r
## 脚本汇总\r
\r
| 脚本 | 用途 | 关键参数 |\r
|------|------|--------|\r
| `init_knowledge_base.py` | 创建新知识库 | `\x3C名称> --path \x3C工作目录>` |\r
| `upload_to_vector.py` | 上传/索引文件 | `--kb-path \x3C知识库路径>` |\r
| `query_knowledge_base.py` | 多分区查询 | `\x3C问题> --kb-path --partition` |\r
| `partition_list.py` | 查看分区状态 | `--kb-path` |\r
\r
所有脚本均支持 **自动发现知识库**：不传 `--kb-path` 时，自动在当前目录或父目录中查找第一个包含 `raw_docs/` + `config.json` 的文件夹。\r
\r
---\r
\r
## 注意事项\r
\r
1. **Python 环境**：用户需先安装 Python 3.8+ 和依赖包（pdfplumber, python-docx, requests）\r
2. **首次使用**：提醒用户先创建知识库并填写 `config.json`\r
3. **知识库为空**：告知用户先往 `raw_docs` 目录放入文档\r
4. **上传失败**：提示检查 API Key、Endpoint、Collection 名称是否正确\r
5. **分区路由**：上传时 `partition` 必须放在请求体顶层\r
6. **分区查询**：DashVector `partition` 参数只接受字符串，多分区通过串行查询实现\r
7. **多知识库切换**：由用户指定知识库名称，AI 负责在工作目录下查找\r