AI搜索代理 API 文档

概述

AI搜索智能体agent是一个智能文档搜索和分析系统，能够自动扫描指定目录中的文档文件，构建缓存，并使用AI分析技术为用户提供精准的文档搜索和问答服务。

基础信息

• Agent名称: ai_search_agent_c
• 缓存文件路径: /tmp/ai-search-agent-cache.md
• 搜索路径: ['/home/docs', '/data/dtns.os']
• 数据目录: __dirname + '/data/'
• 缓存有效期: 30分钟
• 最大相关文件数: 10个
• 单个文件最大内容长度: 100万字符

API端点

1. 标准搜索接口

端点: /rtagent/ai_search_agent_c/search

HTTP方法: ALL (支持GET/POST)

功能: 执行AI驱动的文档搜索和分析

请求参数:

请求示例:

{
  "user_id": "user123",
  "question": "如何配置系统日志？",
  "force_update_cache": false
}

返回结果:

{
  "ret": true,
  "msg": "搜索完成",
  "data": {
    "question": "搜索问题",
    "result": "格式化后的搜索结果",
    "detailed_result": "详细的AI分析结果",
    "cache_updated": true,
    "result_file": "/tmp/ai-search-result-1234567890.md",
    "relevant_files": [
      {
        "file_path": "/home/docs/log_config.md",
        "relevance_score": 0.9,
        "relevance_reason": "包含日志配置相关内容"
      }
    ],
    "search_time": "2024-01-01T12:00:00.000Z"
  }
}

返回字段说明:

2. 增强版搜索接口

端点: /rtagent/ai_search_agent_c/search_enhanced

HTTP方法: ALL (支持GET/POST)

功能: 使用完整文档内容进行更深入的AI分析，提供更精准的搜索结果

请求参数:

请求示例:

{
  "user_id": "user123",
  "question": "系统架构设计文档的主要内容是什么？",
  "force_update_cache": false,
  "max_files": 5
}

返回结果:

{
  "ret": true,
  "msg": "增强版搜索完成",
  "data": {
    "question": "搜索问题",
    "result": "增强版格式化结果",
    "detailed_result": "详细的增强版分析结果",
    "cache_updated": true,
    "result_file": "/tmp/ai-search-enhanced-result-1234567890.md",
    "relevant_files": [
      {
        "file_path": "/home/docs/architecture.md",
        "relevance_score": 0.95,
        "relevance_reason": "直接包含系统架构相关内容"
      }
    ],
    "files_content": [
      {
        "file_path": "/home/docs/architecture.md",
        "relevance_score": 0.95,
        "content_length": 15000,
        "relevance_reason": "直接包含系统架构相关内容"
      }
    ],
    "search_time": "2024-01-01T12:00:00.000Z",
    "search_type": "enhanced"
  }
}

返回字段说明:

3. 手动更新缓存接口

端点: /rtagent/ai_search_agent_c/update_cache

HTTP方法: ALL (支持GET/POST)

功能: 手动触发缓存更新，重新扫描所有文档文件

请求参数:

请求示例:

{
  "user_id": "user123"
}

返回结果:

{
  "ret": true,
  "msg": "缓存更新完成",
  "data": {
    "cache_file": "/tmp/ai-search-agent-cache.md",
    "cache_size": 1024000,
    "file_count": 45,
    "last_updated": "2024-01-01T12:00:00.000Z",
    "search_paths": ["/home/docs", "/data/dtns.os"]
  }
}

返回字段说明:

4. 获取搜索历史接口

端点: /rtagent/ai_search_agent_c/get_search_history

HTTP方法: ALL (支持GET/POST)

功能: 获取用户的搜索历史记录

请求参数:

请求示例:

{
  "user_id": "user123",
  "limit": 10
}

返回结果:

{
  "ret": true,
  "msg": "获取搜索历史成功",
  "data": {
    "user_id": "user123",
    "history": [
      {
        "question": "如何配置系统日志？",
        "cache_status": {
          "cache_updated": false,
          "reason": "cache_valid"
        },
        "result_file": "/tmp/ai-search-result-1234567890.md",
        "relevant_files": [
          {
            "file_path": "/home/docs/log_config.md",
            "relevance_score": 0.9,
            "relevance_reason": "包含日志配置相关内容"
          }
        ],
        "timestamp": 1704067200000,
        "search_time": "2024-01-01T12:00:00.000Z"
      }
    ],
    "total": 1,
    "limit": 10
  }
}

返回字段说明:

数据结构说明

1. 缓存文件结构

缓存文件为Markdown格式，包含以下部分：

# AI搜索缓存文件

生成时间: 2024-01-01T12:00:00.000Z

## 搜索路径: /home/docs

### 文件: /home/docs/log_config.md
- 修改时间: 2024-01-01T11:30:00.000Z
- 大小: 2048 bytes
- 预览内容:

日志配置说明...

### 文件: /home/docs/api_docs.md
- 修改时间: 2024-01-01T11:25:00.000Z
- 大小: 4096 bytes
- 预览内容:

API文档...

2. 相关文件分析结果

{
  "relevant_files": [
    {
      "file_path": "文件完整路径",
      "relevance_score": 0.95,  // 0-1之间的相关度分数
      "relevance_reason": "相关原因说明"
    }
  ]
}

3. 文件内容信息

{
  "file_path": "文件路径",
  "relevance_score": 0.95,
  "relevance_reason": "相关原因",
  "content": "文件内容（可能被截断）",
  "content_length": 15000,
  "original_length": 20000,
  "error": "错误信息（如果有）"
}

搜索流程说明

标准搜索流程

1. 缓存检查: 检查缓存文件是否存在及是否过期
2. 缓存更新: 根据需要更新或重建缓存
3. 相关文件分析: 使用AI分析缓存内容，找出与问题最相关的文件
4. 内容读取: 读取相关文件的完整内容
5. AI分析: 使用talkAgentFromHistory进行综合分析
6. 结果保存: 将结果保存到临时文件
7. 历史记录: 保存搜索历史

增强版搜索流程

1. 缓存检查: 同标准流程
2. 缓存更新: 同标准流程
3. 相关文件分析: 使用AI分析找出相关文件
4. 完整内容读取: 读取相关文件的完整内容（支持智能截断）
5. 深度AI分析: 使用增强版talkAgentFromHistory进行完整文档分析
6. 结果保存: 将详细结果保存到临时文件
7. 历史记录: 保存增强版搜索历史

错误处理

所有API接口都包含错误处理机制，返回格式如下：

{
  "ret": false,
  "msg": "错误描述信息",
  "data": null
}

常见错误信息：

• 用户ID和搜索问题不能为空
• 搜索失败: [具体错误信息]
• 获取搜索历史失败: [具体错误信息]
• 更新缓存失败: [具体错误信息]

注意事项

1. 缓存机制: 系统会自动维护缓存，30分钟内不会重复扫描文件系统
2. 文件类型支持: 支持.md、.txt、.html、.js、.json格式文件
3. 内容限制: 单个文件最大处理100万字符
4. 历史记录: 每个用户最多保存100条搜索历史
5. 性能考虑: 增强版搜索会读取完整文件内容，可能消耗更多资源
6. 文件权限: 确保应用有权限访问搜索路径中的文件

使用建议

1. 对于简单查询，使用标准搜索接口
2. 对于复杂问题或需要深度分析的情况，使用增强版搜索接口
3. 定期使用update_cache接口手动更新缓存，确保数据最新
4. 使用get_search_history接口查看历史搜索记录，避免重复工作
5. 注意force_update_cache参数的使用，避免不必要的文件系统扫描