\r \r

知识库管理系统 (KB Manager)\r

\r 基于ChromaDB的本地知识库管理系统，支持多种文档格式的上传、管理和智能问答。\r \r

使用方法\r

\r

对话式交互\r

• 发送文件并添加说明: "upload to kb" 或 "上传到知识库"\r
• 直接提问进行智能问答\r
• 支持格式: PDF, DOCX, TXT, MD\r \r

命令行使用\r

# 进入对话模式\r
python main.py chat\r
\r
# 上传文档\r
python main.py upload \x3C文件路径> [文档名称]\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
用户: [附件: 公司政策.pdf] 上传到知识库\r
助手: ✅ 文档上传成功！已处理 公司政策.pdf，创建了 45 个文档块。\r
```\r
\r
### 智能问答\r
```\r
用户: 公司的休假政策是什么？\r
助手: 根据公司政策文档，休假政策包括：\r
- 年假：每年15天带薪年假\r
- 病假：每年10天带薪病假\r
- 远程办公：每周可远程2天\r
```\r
\r
### 文档管理\r
```\r
用户: list kb 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-manager\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
**方式二：OpenClaw配置文件**\r
编辑 `~/.openclaw/openclaw.json`:\r
```json\r
{\r
  "skills": {\r
    "entries": {\r
      "kb-manager": {\r
        "enabled": true,\r
        "env": {\r
          "DASHSCOPE_API_KEY": "your-dashscope-key"\r
        },\r
        "config": {\r
          "embeddingProvider": "dashscope",\r
          "embeddingModel": "text-embedding-v3",\r
          "chunkSize": 500,\r
          "retrievalTopK": 5\r
        }\r
      }\r
    }\r
  }\r
}\r
```\r
\r
### 3. 初始化系统环境\r
\r
```bash\r
# 首次使用时，初始化系统环境\r
python main.py setup\r
```\r
\r
这个命令会：\r
- 创建系统级数据目录\r
- 初始化ChromaDB数据库\r
- 设置正确的权限\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
- 发送文件并添加说明: **"upload to kb"** 或 **"上传到知识库"**\r
- 支持格式: PDF, DOCX, TXT, MD\r
- 示例: `[附件: 公司政策.pdf] 上传到知识库`\r
\r
### 智能问答\r
- 直接提问，系统会自动搜索相关文档\r
- 示例: \r
  - `公司的休假政策是什么？`\r
  - `如何申请病假？`\r
  - `远程办公的规定是什么？`\r
\r
### 文档管理\r
- `python main.py list` - 查看所有文档\r
- `python main.py stats` - 显示统计信息\r
- `python main.py delete \x3C文档ID>` - 删除文档\r
- `python main.py setup` - 初始化系统环境\r
\r
## ⚙️ 配置选项\r
\r
在 `config.json` 或 OpenClaw 配置中设置:\r
\r
```json\r
{\r
  "embeddingProvider": "dashscope",\r
  "embeddingModel": "text-embedding-v3", \r
  "embeddingBaseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",\r
  "chunkSize": 500,\r
  "chunkOverlap": 50,\r
  "retrievalTopK": 5,\r
  "collectionName": "enterprise_kb",\r
  "vectorDimension": 1024\r
}\r
```\r
\r
**注意**: 数据库路径和文档目录由系统自动管理，无需手动配置。\r
\r
## 🏗️ 技术架构\r
\r
- **向量数据库**: ChromaDB (本地存储，无需Docker)\r
- **文档存储**: 系统级目录 (自动配置)\r
- **向量存储**: 系统级目录 (自动配置)\r
- **嵌入模型**: DashScope text-embedding-v3 (1024维) 或 OpenAI\r
- **支持格式**: PDF, DOCX, TXT, Markdown\r
- **分块策略**: 可配置大小和重叠度\r
- **搜索算法**: 余弦相似度\r
\r
## 📁 系统数据目录\r
\r
知识库数据存储在系统级固定目录中，所有skills自动共享：\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
这种设计的优势：\r
- **固定路径**: 所有agent自动使用相同路径\r
- **无需配置**: 不需要环境变量或符号链接  \r
- **系统标准**: 遵循操作系统标准目录结构\r
- **自动权限**: 智能处理权限问题\r
\r
## 🔧 故障排除\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
# 测试API连接\r
python -c "import os; print('API Key:', os.getenv('DASHSCOPE_API_KEY', 'Not Set'))"\r
```\r
\r
### 依赖安装问题\r
```bash\r
# 重新安装依赖\r
pip install -r requirements.txt --force-reinstall\r
\r
# 如果遇到grpcio问题，ChromaDB已默认配置无需Docker\r
pip install chromadb --upgrade\r
```\r
\r
### 系统环境问题\r
```bash\r
# 初始化系统环境\r
python main.py setup\r
\r
# 检查系统状态和路径\r
python main.py stats\r
\r
# 验证系统目录权限\r
python -c "from src.system_config import print_system_info; print_system_info()"\r
```\r
\r
### 数据库问题\r
```bash\r
# 系统会自动管理数据库，如需重置：\r
# 1. 备份重要文档\r
# 2. 删除系统目录 (需要管理员权限)\r
# 3. 重新初始化\r
python main.py setup\r
\r
# 检查ChromaDB状态\r
python -c "from src.chroma_client import ChromaVectorDB; db = ChromaVectorDB(); print('DB Status:', db.get_collection_info())"\r
```\r
\r
### 权限问题\r
```bash\r
# Windows: 确保对 C:/ProgramData/ 有写权限\r
# Linux/Mac: 如果 /usr/local/share/ 无权限，会自动使用 ~/.local/share/\r
\r
# 检查当前使用的路径\r
python -c "from src.system_config import get_system_kb_path; print('KB Path:', get_system_kb_path())"\r
```\r
\r
## 📊 性能指标\r
\r
- **处理速度**: ~100页/分钟 (PDF)\r
- **搜索延迟**: \x3C500ms (本地向量搜索)\r
- **存储效率**: ~1MB/1000页文档\r
- **支持规模**: 10万+文档块\r
\r
## 🌐 多Agent部署\r
\r
### 部署架构\r
```\r
Agent A (管理员)          Agent B (用户)           Agent C (用户)\r
├── kb-manager           ├── kb-reader            ├── kb-reader  \r
│   ├── 上传文档          │   ├── 查询知识库        │   ├── 查询知识库\r
│   ├── 管理知识库        │   └── 浏览文档          │   └── 浏览文档\r
│   └── 系统维护          └── 只读访问              └── 只读访问\r
└── 系统级数据目录 ←──────────────┴─────────────────────┘\r
    C:/ProgramData/kb-data/ (Windows)\r
    /usr/local/share/kb-data/ (Linux/Mac)\r
```\r
\r
### 部署步骤\r
\r
1. **管理员Agent设置**\r
```bash\r
# 在管理员Agent上安装kb-manager\r
cd agent-admin/skills/\r
git clone \x3Ckb-manager-repo>\r
cd kb-manager\r
pip install -r requirements.txt\r
\r
# 初始化系统环境\r
python main.py setup\r
\r
# 上传初始文档\r
python main.py upload company-docs.pdf\r
```\r
\r
2. **用户Agent设置**\r
```bash\r
# 在用户Agent上安装kb-reader\r
cd agent-user/skills/\r
git clone \x3Ckb-reader-repo>\r
cd kb-reader\r
pip install -r requirements.txt\r
\r
# 测试连接\r
python main.py stats\r
python main.py query "测试查询"\r
```\r
\r
### 权限管理\r
- **kb-manager**: 完整权限，可创建、修改、删除\r
- **kb-reader**: 只读权限，仅能查询和浏览\r
- **系统目录**: 自动权限管理，确保数据安全\r
\r
## 🔒 安全特性\r
\r
- **本地存储**: 所有数据保存在本地，不上传云端\r
- **API安全**: 支持多种API提供商，密钥加密存储\r
- **访问控制**: 基于OpenClaw的用户权限管理\r
- **数据隔离**: 每个技能实例独立的数据存储\r
- **权限分离**: 管理和查询权限分离，防止误操作\r
\r