知识库导入指南

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

> **搜索标签**: 知识库, 导入, 文档导入, RAG
---

# 文档导入知识库指南

本文档说明如何将项目文档按文集形式导入到知识库中。

## &#128218; 文集分类

项目文档已按以下文集进行分类：

| 文集名称 | 数据集名称 | 描述 | 包含文档 |
|---------|-----------|------|---------|
| 架构设计 | `payroll_architecture_collection` | 架构设计文档 | 前端架构、状态管理、仓储模式、数据模型统一 |
| 开发指南 | `payroll_development_collection` | 开发指南 | 开发环境、开发规范、开发流程、渠道配置指南 |
| 功能文档 | `payroll_features_collection` | 功能文档 | 工资条需求、API开放平台 |
| 重构迁移 | `payroll_migration_collection` | 重构和迁移文档 | Manager迁移、前端重构等 |
| 版本管理 | `payroll_version_collection` | 版本管理文档 | 版本历史、更新日志 |
| 项目整体 | `payroll_project_collection` | 项目整体文档 | 项目简介、发布检查清单、文档索引 |

## &#128640; 使用方法

### 方法1: 使用脚本导入（推荐）

#### 步骤1: 导入文档到知识库

```bash
# 进入项目根目录
cd /workspace/projects

# 执行导入脚本
npx tsx scripts/import-docs-to-kb.ts
```

**导入过程说明**：
- 脚本会自动读取 `docs/` 目录下的所有 Markdown 文档
- 按文集分类导入到不同的数据集
- 每个文档会被分割成多个文本块（chunk）
- 文档块会自动向量化存储

**预期输出**：
```
&#128640; 开始导入项目文档到知识库...

&#128218; 导入文集: architecture
   描述: 架构设计文档，包括前端架构、状态管理、仓储模式等
   文件数量: 4
   ✓ FRONTEND_ARCHITECTURE.md
   ✓ STATE_MANAGEMENT.md
   ✓ REPOSITORY_PATTERN.md
   ✓ DATA_MODEL_UNIFICATION.md
   ✅ 成功导入 32 个文档块
   &#128202; 数据集名称: payroll_architecture_collection

...

============================================================
&#128202; 导入完成统计
============================================================
总文集数: 6
成功导入: 6
导入失败: 0

✅ 文档导入完成！

&#128161; 提示：您现在可以使用以下方式搜索文档：
   CLI: npx FutureBirdAadminAi-coding-ai knowledge search --query "搜索关键词"
   代码: client.search("搜索关键词", ["payroll_architecture_collection"])

&#128218; 可用数据集列表：
   - payroll_architecture_collection: 架构设计文档，包括前端架构、状态管理、仓储模式等
   - payroll_development_collection: 开发指南，包括开发环境、开发规范、开发流程等
   ...
```

#### 步骤2: 搜索文档

**方式1: 使用搜索示例脚本**

```bash
# 运行搜索示例
npx tsx scripts/search-kb-docs.ts

# 或使用交互式搜索
npx tsx scripts/search-kb-docs.ts interactive
```

**方式2: 使用CLI命令**

```bash
# 搜索所有文集
npx FutureBirdAadminAi-coding-ai knowledge search --query "前端架构" --top-k 3

# 搜索特定文集
npx FutureBirdAadminAi-coding-ai knowledge search \
  --query "开发环境配置" \
  --top-k 3 \
  --dataset "payroll_development_collection"
```

**方式3: 在代码中使用**

```typescript
import { KnowledgeClient, Config } from 'FutureBirdAadminAi-coding-dev-sdk';

const config = new Config();
const client = new KnowledgeClient(config);

// 搜索特定文集
const response = await client.search(
  "前端架构设计",
  ["payroll_architecture_collection"],
  3,    // 返回前3个结果
  0.5   // 最小相关度阈值
);

if (response.code === 0) {
  response.chunks.forEach(chunk => {
    console.log(`相关度: ${(chunk.score * 100).toFixed(1)}%`);
    console.log(`内容: ${chunk.content}`);
  });
}
```

### 方法2: 使用CLI命令导入

如果您想单独导入某个文档，可以使用CLI命令：

```bash
# 导入单个文档（文本）
npx FutureBirdAadminAi-coding-ai knowledge add \
  --dataset "payroll_architecture_collection" \
  --content "$(cat docs/FRONTEND_ARCHITECTURE.md)"

# 导入单个文档（URL）
npx FutureBirdAadminAi-coding-ai knowledge add \
  --dataset "payroll_architecture_collection" \
  --url "https://example.com/doc.html"
```

## &#128202; 数据集说明

每个文集对应一个独立的数据集（table）：

1. **payroll_architecture_collection**
   - 文档类型：架构设计
   - 典型内容：架构图、设计模式、技术选型

2. **payroll_development_collection**
   - 文档类型：开发指南
   - 典型内容：环境配置、编码规范、最佳实践、渠道配置

3. **payroll_features_collection**
   - 文档类型：功能需求
   - 典型内容：功能说明、用户故事、API文档

4. **payroll_migration_collection**
   - 文档类型：重构迁移
   - 典型内容：迁移步骤、变更说明、兼容性说明

5. **payroll_version_collection**
   - 文档类型：版本管理
   - 典型内容：更新日志、版本历史、发布说明

6. **payroll_project_collection**
   - 文档类型：项目整体
   - 典型内容：项目简介、快速开始、文档索引

## &#128269; 搜索技巧

### 按文集搜索

```typescript
// 只搜索架构设计文档
const response = await client.search(
  "状态管理",
  ["payroll_architecture_collection"]
);
```

### 跨文集搜索

```typescript
// 搜索多个文集
const response = await client.search(
  "工资条",
  [
    "payroll_features_collection",
    "payroll_migration_collection"
  ]
);
```

### 搜索所有文集

```typescript
// 搜索所有文集
const response = await client.search(
  "工资条",
  undefined  // 不指定文集，搜索全部
);
```

### 调整搜索结果

```typescript
// 返回更多结果
const response = await client.search(
  "前端",
  undefined,
  10,   // 返回前10个结果
  0.3   // 降低相关度阈值，获取更多结果
);
```

## &#128736;️ 维护和更新

### 重新导入文档

当文档更新后，可以重新运行导入脚本：

```bash
npx tsx scripts/import-docs-to-kb.ts
```

**注意**：重新导入会覆盖原有数据。

### 导入新增文档

如果需要导入新的文档：

1. 将文档添加到 `docs/` 目录
2. 编辑 `scripts/import-docs-to-kb.ts`，在对应的 `collection.files` 中添加文件名
3. 重新运行导入脚本

### 清理数据集

如果需要清理某个数据集：

```bash
# 使用CLI删除数据集（如果支持）
# 或者联系管理员删除
```

## &#128221; 注意事项

1. **环境要求**
   - 需要安装 `FutureBirdAadminAi-coding-dev-sdk`
   - 需要配置 `FutureBirdAadminAi_API_KEY` 环境变量

2. **文档格式**
   - 目前只支持 Markdown 文档
   - 文档应使用清晰的标题结构
   - 代码块会被保留

3. **搜索性能**
   - 搜索相关度阈值建议设置为 0.3-0.7
   - 返回结果数量建议设置为 3-10

4. **数据集命名**
   - 所有数据集名称都以 `payroll_` 前缀开头
   - 以 `_collection` 后缀结尾
   - 使用小写和下划线

## &#128221; 最近导入记录

### 2025-01-31
- ✅ 导入 `2025-01-31 渠道管理系统更新汇总` (Doc ID: 7602558131796770850)
  - 数据集: `payroll_project_collection` (首页知识库)
  - 内容: v2.0.10版本更新汇总，包括微信公众号配置增强、Bug修复、UI优化
  - 验证: 已通过知识库搜索验证，可正常检索

- ✅ 导入 `CHANNEL_CONFIG_GUIDE.md` (Doc ID: 7602557878204989486)
  - 数据集: `payroll_development_collection`
  - 内容: 渠道管理配置指南，包含微信公众号、小程序、企业微信、企业微信服务商的详细配置步骤
  - 验证: 已通过知识库搜索验证，可正常检索

- ✅ 导入 `CHANGELOG.md` v2.0.10版本更新 (Doc ID: 7602557764291969058)
  - 数据集: `payroll_version_collection`
  - 内容: v2.0.10版本更新记录，包括微信公众号配置增强、服务器URL配置、消息加解密方式、UI统一等
  - 验证: 已通过知识库搜索验证，可正常检索

- ✅ 导入 `TECH_IMPROVEMENTS.md` 渠道管理系统优化 (Doc ID: 7602557762886991918)
  - 数据集: `payroll_architecture_collection`
  - 内容: 渠道管理系统优化技术细节，包括服务器URL配置、消息加解密方式、Bug修复、UI统一等
  - 验证: 已通过知识库搜索验证，可正常检索

## &#128279; 相关资源

- [知识库集成文档](https://www.FutureBirdAadminAi.com/docs/developer_guides/knowledge_base)
- [项目文档索引](DOCS_INDEX.md)
- [前端架构文档](docs/FRONTEND_ARCHITECTURE.md)
- [状态管理文档](docs/STATE_MANAGEMENT.md)

## &#128222; 获取帮助

如有问题，请：
1. 检查环境配置是否正确
2. 查看脚本输出的错误信息
3. 联系开发团队

---

**最后更新**: 2025-01-31