\r \r

知识库只读查询器 (KB Reader)\r

\r

⚠️ 重要提示: 这是一个严格只读的查询系统，无法创建、上传、修改或删除任何数据。使用前必须确保已有管理员通过 kb-manager 初始化了系统环境。\r \r 专门用于查询和读取企业知识库内容的轻量级系统，不支持文档上传和管理功能。\r \r

使用方法\r

\r

对话式查询\r

• 直接提问进行智能问答\r
• 支持语义搜索和关键词匹配\r
• 自动从知识库中检索相关内容\r \r

命令行使用\r

# 进入对话模式\r
python main.py chat\r
\r
# 直接查询\r
python main.py query \x3C查询内容>\r
\r
# 列出文档（只读）\r
python main.py list\r
\r
# 显示统计（只读）\r
python main.py stats\r
```\r
\r
## 示例\r
\r
### 智能问答\r
```\r
用户: 公司的休假政策是什么？\r
助手: 根据知识库文档，休假政策包括：\r
- 年假：每年15天带薪年假\r
- 病假：每年10天带薪病假\r
- 远程办公：每周可远程2天\r
```\r
\r
### 文档查看\r
```\r
用户: list documents\r
助手: 📚 知识库文档列表：\r
1. 公司政策.pdf (45 chunks)\r
2. 员工手册.docx (23 chunks)\r
```\r
\r
## 🚀 快速开始\r
\r
### 1. 安装依赖\r
\r
```bash\r
cd skills/kb-reader\r
pip install -r requirements.txt\r
```\r
\r
### 2. 配置API密钥\r
\r
**方式一：环境变量**\r
```powershell\r
# DashScope (阿里云千问) - 推荐\r
$env:DASHSCOPE_API_KEY='your-dashscope-key'\r
\r
# 或者 OpenAI\r
$env:OPENAI_API_KEY='your-openai-key'\r
```\r
\r
### 3. 确保知识库已初始化\r
\r
⚠️ **重要**: kb-reader 是只读系统，无法创建或初始化知识库。使用前必须确保 kb-manager 已经初始化了系统环境。\r
\r
```bash\r
# 1. 检查系统目录是否存在\r
python main.py stats\r
\r
# 2. 如果提示"系统数据目录不存在"，说明需要先用 kb-manager 初始化\r
# kb-reader 无法自行创建系统环境，必须由管理员使用 kb-manager 完成初始化\r
```\r
\r
**如果系统未初始化，请联系管理员或在有 kb-manager 的环境中运行：**\r
```bash\r
cd \x3Ckb-manager-directory>\r
python main.py setup\r
```\r
\r
### 4. 测试查询\r
\r
```bash\r
# 测试系统状态\r
python main.py stats\r
\r
# 测试查询功能\r
python main.py query "测试查询"\r
```\r
\r
## 📋 使用方法\r
\r
### 智能查询\r
- 直接提问，系统会自动搜索相关文档\r
- 支持中文和英文查询\r
- 示例: \r
  - `公司的休假政策是什么？`\r
  - `如何申请病假？`\r
  - `远程办公的规定是什么？`\r
\r
### 文档浏览\r
- `python main.py list` - 查看所有文档\r
- `python main.py stats` - 显示统计信息\r
- `python main.py search \x3Cquery>` - 详细搜索文档内容\r
\r
## ⚙️ 配置选项\r
\r
在 `config.json` 中设置:\r
\r
```json\r
{\r
  "embeddingProvider": "dashscope",\r
  "embeddingModel": "text-embedding-v3", \r
  "embeddingBaseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",\r
  "retrievalTopK": 5,\r
  "milvusUri": "系统自动配置",\r
  "collectionName": "enterprise_kb",\r
  "documentsDir": "系统自动配置"\r
}\r
```\r
\r
## 📁 系统数据目录\r
\r
kb-reader 自动访问系统级知识库目录：\r
\r
**Windows**: `C:/ProgramData/kb-data/`\r
**Linux/Mac**: `/usr/local/share/kb-data/` 或 `~/.local/share/kb-data/`\r
\r
```\r
kb-data/\r
├── chroma_db/     # 向量数据库 (只读访问)\r
└── documents/     # 原始文档 (只读访问)\r
```\r
\r
## 🔗 与kb-manager的关系\r
\r
- **kb-manager**: 负责创建和管理知识库，具有完整的读写权限\r
  - ✅ 创建系统目录 (`python main.py setup`)\r
  - ✅ 上传和管理文档\r
  - ✅ 删除和修改数据\r
  - ✅ 初始化数据库\r
\r
- **kb-reader**: 只能读取kb-manager创建的知识库，**严格只读权限**\r
  - ❌ 无法创建系统目录\r
  - ❌ 无法上传文档\r
  - ❌ 无法修改或删除数据\r
  - ❌ 无法初始化数据库\r
  - ✅ 仅能查询和浏览现有数据\r
\r
- **数据共享**: 两个skills访问同一个系统目录，实现数据共享\r
- **权限分离**: kb-reader无法修改或删除数据，确保数据安全\r
- **部署灵活**: 可以部署在不同的agent上，实现分布式知识库访问\r
\r
## 📋 使用前提\r
\r
1. **系统环境**: 必须已经有管理员使用 kb-manager 初始化了系统环境\r
2. **只读权限**: kb-reader 无法创建、修改或删除知识库数据\r
3. **数据存在**: 知识库中必须已经有文档数据（由 kb-manager 上传）\r
4. **API配置**: 需要配置相同的嵌入模型API密钥\r
5. **依赖关系**: kb-reader 完全依赖 kb-manager 创建的系统环境\r
\r
## 🏗️ 技术特性\r
\r
- **严格只读**: 代码层面限制，无任何写入或修改功能\r
- **高效检索**: 基于向量相似度和关键词匹配\r
- **多种查询模式**: 支持语义搜索、关键词搜索和混合搜索\r
- **轻量级**: 最小化依赖，专注查询功能\r
- **兼容性**: 可以读取kb-manager创建的知识库\r
- **安全设计**: 无权限创建、修改或删除任何数据\r
\r
## 🔧 故障排除\r
\r
### 知识库不存在\r
```bash\r
# 如果提示知识库不存在，kb-reader 无法自行解决此问题\r
# 必须联系管理员或在有 kb-manager 的环境中初始化\r
\r
# 检查系统状态\r
python main.py stats\r
\r
# 如果显示"系统数据目录不存在"，需要管理员运行：\r
# cd \x3Ckb-manager-directory>\r
# python main.py setup\r
```\r
\r
**注意**: kb-reader 作为只读系统，无权限创建系统目录或初始化数据库。\r
\r
### 无查询结果\r
```bash\r
# 检查知识库是否有数据\r
python main.py stats\r
\r
# 如果没有数据，需要管理员使用 kb-manager 上传文档\r
# kb-reader 无法上传文档，只能查询已存在的数据\r
```\r
\r
**注意**: kb-reader 无法上传文档，如需添加文档请联系管理员。\r
\r
### API密钥问题\r
```bash\r
# 检查环境变量 (Windows)\r
echo $env:DASHSCOPE_API_KEY\r
\r
# 检查环境变量 (Linux/Mac)\r
echo $DASHSCOPE_API_KEY\r
\r
# 设置API密钥 (Windows)\r
$env:DASHSCOPE_API_KEY='your-api-key'\r
\r
# 设置API密钥 (Linux/Mac)\r
export DASHSCOPE_API_KEY='your-api-key'\r
```\r
\r
### 权限问题\r
```bash\r
# 如果遇到权限错误，检查系统目录权限\r
# Windows: C:/ProgramData/kb-data/\r
# Linux/Mac: /usr/local/share/kb-data/ 或 ~/.local/share/kb-data/\r
\r
# 确保kb-manager有创建目录的权限\r
cd ../kb-manager\r
python main.py setup\r
```\r
\r
## 🌐 部署场景\r
\r
### 场景1: 单机多Agent\r
```\r
同一台机器上的多个Agent\r
├── Agent-Admin (kb-manager)\r
├── Agent-User1 (kb-reader)  \r
├── Agent-User2 (kb-reader)\r
└── 共享系统目录: C:/ProgramData/kb-data/\r
```\r
\r
### 场景2: 分布式部署\r
```\r
多台机器，共享网络存储\r
├── 机器A: Agent-Admin (kb-manager) → 网络存储\r
├── 机器B: Agent-User1 (kb-reader) → 网络存储  \r
└── 机器C: Agent-User2 (kb-reader) → 网络存储\r
```\r
\r
### 场景3: 容器化部署\r
```\r
Docker容器间数据共享\r
├── Container-Admin: kb-manager + 数据卷\r
├── Container-User1: kb-reader + 数据卷\r
└── Container-User2: kb-reader + 数据卷\r
```\r
\r
## 🔒 安全特性\r
\r
- **严格只读权限**: 代码层面强制只读，任何写入操作都会抛出异常\r
- **无创建权限**: 无法创建目录、数据库或集合\r
- **本地访问**: 仅访问本地知识库文件\r
- **API安全**: 支持多种API提供商，密钥加密存储\r
- **数据隔离**: 与kb-manager共享数据但权限完全隔离\r
- **故障安全**: 如果系统环境不存在，会立即报错而不是尝试创建\r
\r
## 📊 性能指标\r
\r
- **搜索延迟**: \x3C500ms (本地向量搜索)\r
- **内存占用**: 最小化内存使用\r
- **并发支持**: 支持多用户同时查询