文档智能问答

文档智能问答与处理系统 API 文档

概述

本文档描述了基于Node.js的文档智能问答与处理系统的API接口。该系统能够扫描、读取指定目录和文件中的文档内容，利用AI模型进行智能问答、代码生成、文档分析等任务，并支持将结果直接写入文件。

核心特性

  • 多格式支持：支持 .md, .txt, .json, .js, .html, .css, .xml, .yaml, .yml, .py, .java, .cpp, .c, .go, .rs, .php, .rb, .ts, .jsx, .tsx 等文件格式。
  • 智能问答：基于上传的文档内容进行精准问答。
  • 多任务处理：支持问答、编程、文档整理、分析等多种任务类型。
  • 批量操作：支持批量查询和处理文档。
  • 文件输出：可将AI处理结果直接写入指定格式的文件。
  • 状态跟踪：提供异步批量处理的状态查询接口。

API 端点总览

端点 方法 功能描述
/rtagent/docs/query ALL 智能问答 - 基于文档内容回答问题，返回结果到响应体。
/rtagent/docs/process ALL 批量处理 - 启动异步批量处理任务，返回任务ID。
/rtagent/docs/status ALL 状态查询 - 根据任务ID查询异步处理状态和结果。
/rtagent/docs/clear-cache ALL 清除缓存 - 清除指定的或所有的处理状态缓存。
/rtagent/docs/query-and-write ALL 查询并写入 - 问答并将结果直接写入文件。
/rtagent/docs/batch-write ALL 批量查询并写入 - 批量问答并将每个结果写入独立文件。

1. 智能问答接口

端点

/rtagent/docs/query

功能

根据用户提供的文档目录或文件列表，结合问题，进行智能问答、代码生成或文档分析，并将结果以JSON格式返回。

请求参数

通过请求体（Body）以JSON格式传递。

参数名 类型 必填 默认值 描述
question String 是 - 用户提出的问题或任务要求。
directories Array<String> 否 [] 要扫描的文档目录路径列表。
files Array<String> 否 [] 要读取的单个文件路径列表。
user_id String 否 自动生成 用户标识，用于会话隔离。
task_type String 否 'qa' 任务类型。可选值：'qa'（问答）, 'programming'（编程）, 'documentation'（文档整理）, 'analysis'（分析）。
output_format String 否 'text' 输出格式。可选值：'text', 'code', 'json', 'markdown', 'html', 'xml', 'yaml', 'yml', 'csv'。
max_tokens Number 否 8000 AI生成内容的最大token限制。

返回结果

成功响应 (HTTP 200 OK)

{
  "ret": true,
  "msg": "文档处理完成",
  "data": {
    "question": "用户原始问题",
    "answer": "AI生成的答案或内容",
    "metadata": {
      "request_id": "query_1700000000000_abc123",
      "task_type": "qa",
      "output_format": "text",
      "processed_files": 5,
      "total_chars": 12045,
      "processing_time": 3450,
      "timestamp": "2024-01-01T12:00:00.000Z"
    }
  }
}

失败响应 (HTTP 200 OK)

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

2. 查询并写入文件接口

端点

/rtagent/docs/query-and-write

功能

在 /query 功能的基础上，将AI生成的结果直接写入到指定的文件中，支持覆盖、追加等操作。

请求参数

参数名 类型 必填 默认值 描述
question String 是 - 用户提出的问题或任务要求。
directories Array<String> 否 [] 要扫描的文档目录路径列表。
files Array<String> 否 [] 要读取的单个文件路径列表。
user_id String 否 自动生成 用户标识。
task_type String 否 'qa' 任务类型。
output_format String 否 'text' 输出格式，决定文件扩展名。
output_path String 是 - 输出文件的基础目录路径。
file_name String 否 自动生成 输出文件名。若不提供扩展名，将根据output_format自动添加。
overwrite Boolean 否 false 如果文件已存在，是否覆盖。
append Boolean 否 false 如果文件已存在，是否追加内容。
create_dirs Boolean 否 true 是否自动创建不存在的输出目录。

返回结果

成功响应

{
  "ret": true,
  "msg": "文档处理并写入文件完成",
  "data": {
    "write_info": {
      "file_path": "/absolute/path/to/output/file.md",
      "file_name": "file.md",
      "file_size": 2048,
      "file_size_formatted": "2.00 KB",
      "created": "2024-01-01T12:00:00.000Z",
      "modified": "2024-01-01T12:00:05.000Z",
      "operation": "created",
      "content_length": 2000,
      "format": "markdown"
    },
    "metadata": {
      "request_id": "write_1700000000000_def456",
      "task_type": "documentation",
      "output_format": "markdown",
      "processed_files": 3,
      "total_chars": 8901,
      "processing_time": 4200,
      "timestamp": "2024-01-01T12:00:05.000Z"
    }
  }
}

3. 批量查询并写入文件接口

端点

/rtagent/docs/batch-write

功能

执行多个查询任务，共享同一组文档源，并将每个任务的结果分别写入独立的文件。

请求参数

参数名 类型 必填 默认值 描述
queries Array<Object> 是 - 查询任务对象数组。每个对象包含以下字段：
• question (String, 必填): 问题。
• task_type (String): 同前。
• output_format (String): 同前。
• output_path (String): 该任务的输出路径，默认为base_output_path。
• file_name (String): 文件名。
• overwrite (Boolean): 同前。
• append (Boolean): 同前。
• id (String): 可选的任务标识符。
directories Array<String> 否 [] 共享的文档目录路径列表。
files Array<String> 否 [] 共享的单个文件路径列表。
user_id String 否 自动生成 用户标识。
base_output_path String 是 - 默认的输出文件基础目录路径。
create_dirs Boolean 否 true 是否自动创建目录。

返回结果

成功响应

{
  "ret": true,
  "msg": "批量处理完成，成功 3 个，失败 0 个",
  "data": {
    "results": [
      {
        "task_id": "task_0",
        "status": "success",
        "question": "第一个问题",
        "write_info": { /* 同 query-and-write 的 write_info */ },
        "content_preview": "答案的前200字符..."
      },
      // ... 其他任务结果
    ],
    "summary": {
      "total": 3,
      "success": 3,
      "failed": 0,
      "success_rate": 100.0,
      "processing_time": 12500,
      "timestamp": "2024-01-01T12:05:00.000Z"
    }
  }
}

4. 批量处理接口

端点

/rtagent/docs/process

功能

启动一个异步的批量处理任务，适用于需要长时间处理的大量任务。立即返回一个request_id，用于后续查询状态。

请求参数

参数名 类型 必填 默认值 描述
directories Array<String> 否 [] 文档目录路径列表。
files Array<String> 否 [] 单个文件路径列表。
tasks Array<Object> 是 - 处理任务列表。每个任务对象包含：
• question (String, 必填): 问题。
• type (String): 任务类型，同task_type。
• format (String): 输出格式，同output_format。
• id (String): 可选的任务标识符。
user_id String 否 自动生成 用户标识。

返回结果

成功响应 (任务已启动)

{
  "ret": true,
  "msg": "批量处理任务已启动",
  "data": {
    "request_id": "process_1700000000000_ghi789",
    "total_tasks": 10,
    "status_url": "/rtagent/docs/status?request_id=process_1700000000000_ghi789"
  }
}

5. 处理状态查询接口

端点

/rtagent/docs/status

功能

查询由 /process 接口启动的异步批量处理任务的状态和结果。

请求参数

通过URL Query String或请求体传递。

参数名 类型 必填 描述
request_id String 是 由 /process 接口返回的任务ID。

返回结果

成功响应

{
  "ret": true,
  "msg": "处理状态获取成功",
  "data": {
    "status": "completed", // 状态: processing, completed, error
    "progress": 100, // 进度百分比
    "total_tasks": 10,
    "completed_tasks": 10,
    "results": [ /* 每个任务的处理结果，结构同 batch-write 的 results */ ],
    "start_time": "2024-01-01T12:00:00.000Z",
    "end_time": "2024-01-01T12:10:00.000Z",
    "error": "仅在 status 为 error 时存在"
  }
}

6. 清除缓存接口

端点

/rtagent/docs/clear-cache

功能

清除系统内存中存储的处理状态缓存。

请求参数

参数名 类型 必填 描述
request_id String 否 指定要清除的请求ID。若不提供，则清除所有缓存。

返回结果

成功响应

{
  "ret": true,
  "msg": "已清除请求 xyz 的缓存"
}

或

{
  "ret": true,
  "msg": "已清除所有缓存，共 5 条记录"
}

数据结构说明

1. 收集的文档对象 (Collected Document)

{
  path: "/full/path/to/file.md", // 文件绝对路径
  name: "file.md",               // 文件名
  size: 1024,                    // 文件大小（字节）
  content: "文件内容字符串",      // 文件文本内容
  chars: 500                     // 内容字符数
}

2. 任务类型 (Task Type)

  • qa: 标准问答模式。AI基于文档回答问题。
  • programming: 编程模式。AI生成代码、分析代码或解决编程问题。
  • documentation: 文档整理模式。AI编辑、整理、总结文档。
  • analysis: 分析模式。AI对文档内容进行深度分析，提取模式、趋势和见解。

3. 输出格式与文件扩展名映射

output_format 文件扩展名 说明
text .txt 纯文本
code .js 代码（默认.js，实际根据内容推断）
json .json JSON格式
markdown .md Markdown格式
html .html HTML文档
xml .xml XML格式
yaml, yml .yaml, .yml YAML格式
csv .csv CSV表格

4. 系统配置常量

  • DEFAULT_MAX_FILE_SIZE: 5 * 1024 * 1024 (5MB)，单个文件大小限制。
  • MAX_TOTAL_CONTENT_SIZE: 100 * 1024 * 1024 (100MB)，总处理内容大小限制。
  • SUPPORTED_EXTENSIONS: 支持的文件扩展名列表。

错误处理

所有API均通过返回JSON中的 ret: false 和 msg 字段来指示错误。常见错误信息包括：

  • 问题不能为空
  • 必须提供至少一个目录或文件
  • 未找到任何有效文档内容
  • 输出路径不能为空
  • 文件已存在: ...。请设置 overwrite=true 或 append=true
  • 查询任务列表不能为空
  • 请求ID不能为空
  • 未找到对应的处理任务
  • AI未能生成有效内容
  • 文档查询失败: [具体系统错误]

日志

系统会在项目根目录的 logs/ 文件夹下生成按日期命名的日志文件（如 2024-01-01.log），记录所有API请求的处理进度、参数和错误信息，便于调试和审计。

重要的规则

  1. 对于简单的即时问答（知识库问答），使用 /query。
  2. 需要将结果保存为文件时（特别是AI编程)，使用 /query-and-write ，并且这个api调用的question参数可以是AI编程的提示语（编程指令）。
  3. 需要对同一组文档提出多个不同问题并分别保存时，使用 /batch-write。
  4. 对于大量、耗时的处理任务，使用 /process 异步接口，并通过 /status 轮询结果。
  5. 对于ai编程的需求，强烈推荐直接使用/query-and-write这个API，并且一定直接在question参数中传递AI编程的要求、编程内容等（应直接包含需要做的编程工作、需要参考哪个文档、分析哪些内容等等）。并且引用文件放在files参数中。
  6. 本智能体agent特别适合ai编程（第一位）、其次是基于文档的问答。————docs-agent
  7. 【特别注意】ai编程不要策划过长的plan计划，而是尽量把要做的编程需求一次性放在question参数中讲清楚，引用的参考文档需尽量全面。也就是：/query-and-write这个api可以一次完成AI编程任务，不必过度拆分多次进行。
  8. 【特别注意2】如果是AI编程任务，一定要引用 /home/agents/user-agent.js作为参考文件，并且涉及AI分析、AI对话或者自然语言识别或者AI处理等的需要使用talkAgent或talkAgentFromHistory函数，这两个函数在 /home/agents/user-agent.js文件中有定义，新开发的agent智能体代码务必复制这一份这两个函数和相关代码过去。