npm package: @qzsy/kag-sdk
Description: SDK for accessing KAG services
Author: Huanghuabin
Latest version: 1.1.5

# KAG-SDK

KAG-SDK 是一个用于与知识图谱系统进行交互的 TypeScript/JavaScript SDK。它提供了一系列功能强大的 API，使您能够轻松地管理和操作知识图谱系统。

## 更新日志

### v1.1.5 (2024-01-XX)
- **重要改进**: 完善README文档和示例代码
- 优化Schema管理相关API的使用说明
- 新增知识图谱结构解析的详细说明
- 改进项目文档结构，提供更清晰的使用指导
- 更新密码加密和安全相关的最佳实践说明

### v1.1.4 (2024-01-XX)
- **新增功能**: 添加获取项目图谱结构API
- 新增 `getSchemaGraph` 方法，支持获取指定项目的图谱结构
- 完善图谱相关的TypeScript类型定义
- 更新示例代码，展示如何获取项目图谱结构

### v1.1.3 (2024-01-XX)
- **更新**: 更新服务器地址配置
- 更新文档中的示例代码和配置说明

### v1.1.2 (2024-01-XX)
- **新增功能**: 完善调度任务搜索API
- 新增通过jobId搜索任务实例列表的接口 `searchTaskInstancesByJobId`
- 新增通过instanceId搜索任务详情列表的接口 `searchTaskDetailsByInstanceId`
- 完善任务相关的TypeScript类型定义
- 更新示例代码，展示新增任务搜索接口的使用

### v1.1.0 (2024-01-XX)
- **新增功能**: 添加调度实例搜索API支持和SchedulerService服务
- 新增 `SchedulerService` 服务类，支持调度实例和任务管理
- 实现 `searchInstance()` 方法，支持 `/public/v1/scheduler/instance/search` API
- 实现 `getInstanceById()` 和 `searchTask()` 方法
- 修复类型定义兼容性问题，改进BaseResponse类型
- 更新示例代码，展示scheduler服务的使用

### v1.0.3 (2024-01-XX)
- **重要更新**: 登录API现在返回完整的账户信息而不是布尔值
- 登录成功后可以通过 `loginResult.result.token` 获取用户token
- 改进了登录响应的类型定义，提供更好的TypeScript支持
- 更新了示例代码，展示如何使用返回的token

## 主要功能

### 1. 账户管理 (Accounts)
- 用户登录（返回完整账户信息，包括token）
- 获取账户信息
- 更新密码（支持SHA-256加盐加密）
- 用户退出登录

### 2. Schema 管理 (Schemas)
- 创建和更新 Schema
- 获取图谱差异分析
- 更新图谱结构
- 获取图谱结构
- **获取项目图谱结构**（支持实体类型和关系类型的完整定义）
- 支持实体类型定义和属性配置
- 支持关系类型定义和索引配置

### 3. 项目管理 (Projects)
- 获取项目列表（支持分页和排序）
- 创建新项目
- 项目信息查询和管理
- 支持项目配置和权限管理

### 4. 权限管理 (Permissions)
- 获取权限列表
- 权限验证和管理
- 用户权限分配

### 5. 系统配置 (Configs)
- 获取系统配置
- 更新配置信息（支持全局配置和LLM配置）
- 支持版本控制
- 配置项管理和验证

### 6. 数据服务 (Datas)
- 获取枚举值
- 获取 LLM 模型列表
- 数据查询和管理
- 支持数据类型定义

### 7. 知识构建 (Builder)
- 获取构建任务列表
- 查看任务详情
- 预览分片结果
- 提交知识构建任务
- 获取差异分析结果
- 支持文件上传和处理

### 8. 推理服务 (Reasoner)
- 获取推理会话列表
- 知识图谱查询（KG Query）
- 文件上传功能
- 支持多种推理模式
- 节点和边的查询结果处理

### 9. 调度服务 (Scheduler)
- 搜索调度实例
- 获取调度实例详情
- 搜索任务
- 支持分页查询和状态管理
- 任务实例和详情管理

## 安装

```bash
pnpm install @qzsy/kag-sdk
```

## 快速开始

### 基础配置

```typescript
import { KAGSDK, KAGError } from '@qzsy/kag-sdk';
import { sha256EncryptWithSalt } from '@qzsy/kag-sdk/utils';

// 创建 SDK 实例
const sdk = new KAGSDK({
  baseURL: 'http://your-server-domain:port',
  timeout: 15000,
  ctoken: 'your_ctoken_here'
});
```

### 用户认证

```typescript
async function authenticate() {
  try {
    // 密码加密（推荐使用SHA-256加盐）
    const plainPassword = 'your_password';
    const salt = 'OPENSPG'; // 默认盐值
    const encryptedPassword = sha256EncryptWithSalt(plainPassword, salt);
    
    // 用户登录
    const loginResult = await sdk.accounts.login({
      account: 'your_account',
      password: encryptedPassword
    });
    
    if (loginResult.success && loginResult.result) {
      const token = loginResult.result.token;
      console.log('登录成功，获取到token:', token);
      return token;
    }
  } catch (error) {
    console.error('登录失败:', error);
  }
}
```

### 项目管理

```typescript
async function manageProjects() {
  // 获取项目列表
  const projectList = await sdk.projects.getProjectList({
    sort: 'desc',
    sortBy: 'time',
    page: 1,
    size: 10
  });
  
  console.log('项目列表:', projectList.result?.results);
  
  // 创建新项目
  const newProject = await sdk.projects.createProject({
    name: '测试项目',
    description: '这是一个测试项目',
    // 其他项目配置...
  });
  
  return projectList.result?.results[0]?.id;
}
```

### Schema图谱管理

```typescript
async function manageSchema(projectId: number) {
  // 获取项目图谱结构
  const schemaGraph = await sdk.schemas.getSchemaGraph(projectId);
  
  console.log('实体类型列表:', schemaGraph.result.entityTypeDTOList);
  console.log('关系类型列表:', schemaGraph.result.relationTypeDTOList);
  
  // 创建或更新Schema
  const schemaResult = await sdk.schemas.createSchema({
    entityTypes: [
      {
        name: 'Test.Medicine',
        nameZh: '药物',
        description: '药物实体类型',
        // 更多属性定义...
      }
    ],
    relationTypes: [
      {
        name: 'treats',
        nameZh: '治疗',
        startEntity: 'Test.Medicine',
        endEntity: 'Test.Disease'
      }
    ]
  });
  
  return schemaResult;
}
```

### 知识构建

```typescript
async function buildKnowledge(projectId: number) {
  // 获取构建任务列表
  const jobList = await sdk.builder.getJobList({
    projectId,
    start: 1,
    limit: 10
  });
  
  if (jobList.result.data.length > 0) {
    const jobId = jobList.result.data[0].id;
    
    // 获取任务详情
    const jobDetail = await sdk.builder.getJob({ id: jobId });
    
    // 预览分片结果
    const previewResult = await sdk.builder.previewSplit(jobDetail.result);
    
    console.log('分片预览:', previewResult);
  }
}
```

### 知识图谱查询

```typescript
async function queryKnowledgeGraph(projectId: number, jobId: number) {
  // 执行KG查询
  const kgQuery = await sdk.reasoner.getKGQuery({
    id: jobId,
    jobId
  });
  
  console.log('查询结果节点:', kgQuery.result.resultNodes);
  console.log('查询结果边:', kgQuery.result.resultEdges);
  
  // 获取差异分析
  const diffResult = await sdk.builder.getDiffResult({
    job: jobDetail.result,
    subGraph: {
      resultNodes: kgQuery.result.resultNodes,
      resultEdges: kgQuery.result.resultEdges
    }
  });
  
  return diffResult;
}
```

### 配置管理

```typescript
async function manageConfigs() {
  // 获取系统配置
  const config = await sdk.configs.getConfig({
    configId: 'KAG_CONFIG',
    version: 1
  });
  
  console.log('系统配置:', config.result);
  
  // 更新配置
  const updateResult = await sdk.configs.updateConfig({
    configData: {
      // 配置数据...
    }
  });
  
  return updateResult;
}
```

## 理解知识图谱结构

### 实体类型 (EntityType)
实体类型定义了知识图谱中节点的结构：

```typescript
interface EntityType {
  id: number;                    // 实体类型唯一ID
  name: string;                  // 英文名称（如：'Test.Medicine'）
  nameZh: string;                // 中文名称（如：'药物'）
  description: string;           // 描述信息
  inheritedPropertyList: Property[]; // 继承的属性列表
  propertyList: Property[];      // 自定义属性列表
  relations: Relation[];         // 关系定义
  parentId: number;              // 父类ID
  parentName: string;            // 父类名称（如：'Thing'）
  belongToProject: number;       // 所属项目ID
  entityCategory: string;        // 实体类别
}
```

### 关系类型 (RelationType)
关系类型定义了实体之间的连接：

```typescript
interface RelationType {
  name: string;                  // 英文名称（如：'treats'）
  nameZh: string;                // 中文名称（如：'治疗'）
  startEntity: EntityType;       // 起始实体类型
  endEntity: EntityType;         // 终止实体类型
  propertyList: Property[];      // 关系属性列表
  relationCategory: string;      // 关系类别
}
```

## 最佳实践

### 1. 安全性
- 始终使用加密密码进行登录
- 定期更新访问令牌
- 妥善保管ctoken和敏感信息

### 2. 错误处理
```typescript
try {
  const result = await sdk.someMethod();
  // 处理成功结果
} catch (error) {
  if (error instanceof KAGError) {
    console.error('KAG错误:', error.message);
  } else {
    console.error('未知错误:', error);
  }
}
```

### 3. 性能优化
- 合理设置超时时间
- 使用分页查询大量数据
- 缓存频繁访问的配置信息

## API参考

完整的API文档请参考TypeScript类型定义文件，所有方法都有详细的类型注解和注释说明。

## 特性
- ✅ 完整的 TypeScript 支持
- ✅ 简单易用的 API 设计
- ✅ 完善的错误处理机制
- ✅ 支持自定义配置
- ✅ 支持异步操作
- ✅ 内置密码加密工具
- ✅ 完整的知识图谱管理功能

## 注意事项
- 使用前需要先进行初始化和登录
- 部分功能可能需要特定的权限
- 建议参考示例代码进行开发
- 密码需要使用SHA-256加盐加密
- 确保网络连接稳定，合理设置超时时间

## 示例代码

完整的使用示例请查看 `example/sdk-usage.ts` 文件，其中包含了所有主要功能的使用方法。

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request 来帮助改进这个项目。