Chatbot Agent API 文档

概述

chatbot角色扮演聊天智能体是一个具备人性的聊天机器人智能体系统（角色智能体：数字生命），支持多角色聊天频道、记忆管理、任务管理、心跳机制。系统集成了角色扮演的 AI 对话功能和 ibbot智体机灵任务调用，拥有系统感知、任务识别、创建、追踪和通知功能。

数据存储结构

所有数据统一组织到 roles 目录下
每个角色有独立的目录结构：
- role.json - 角色信息
- memory.json - 记忆文件
- task_results.json - 任务结果
- tasks/ - 任务目录（每个任务单独保存为 JSON 文件）
- task_history/ - 任务历史目录（每个任务单独保存为 ${task_id}.json）
- notifications/ - 通知目录

API 端点列表

1. 角色管理

1.1 创建角色

端点: /rtagent/chatbot/create_role
方法: ALL
功能: 创建一个新的聊天机器人角色

请求参数:

参数名	类型	必填	说明
name	string	是	角色名称
prompt	string	否	角色提示词，默认为基础角色设定
description	string	否	角色描述
config	object	否	角色配置信息

返回结果:

{
  "ret": true,
  "msg": "角色创建成功",
  "data": {
    "id": "role_时间戳_随机字符串",
    "name": "角色名称",
    "prompt": "角色提示词",
    "description": "角色描述",
    "created_at": "ISO时间戳",
    "updated_at": "ISO时间戳",
    "is_active": true,
    "config": {}
  }
}

1.2 获取角色列表

端点: /rtagent/chatbot/roles
方法: ALL
功能: 获取所有角色列表

请求参数: 无

返回结果:

{
  "ret": true,
  "msg": "获取角色列表成功",
  "data": {
    "roles": [
      {
        "id": "角色ID",
        "name": "角色名称",
        "prompt": "角色提示词",
        "description": "角色描述",
        "created_at": "创建时间",
        "updated_at": "更新时间",
        "is_active": true,
        "config": {}
      }
    ],
    "total": 角色数量
  }
}

1.3 更新角色

端点: /rtagent/chatbot/update_role
方法: ALL
功能: 更新角色信息

请求参数:

参数名	类型	必填	说明
role_id	string	是	角色ID
name	string	否	角色名称
prompt	string	否	角色提示词
description	string	否	角色描述
config	object	否	角色配置信息

返回结果:

{
  "ret": true,
  "msg": "角色更新成功",
  "data": {
    "id": "角色ID",
    "name": "更新后的名称",
    "prompt": "更新后的提示词",
    "description": "更新后的描述",
    "updated_at": "更新时间",
    "is_active": true,
    "config": {}
  }
}

1.4 删除角色

端点: /rtagent/chatbot/delete_role
方法: ALL
功能: 删除指定角色

请求参数:

参数名	类型	必填	说明
role_id	string	是	角色ID

返回结果:

{
  "ret": true,
  "msg": "角色删除成功"
}

1.5 获取角色上下文信息

端点: /rtagent/chatbot/role_context
方法: ALL
功能: 获取角色的完整上下文信息，包含角色信息、最近任务、通知、记忆摘要等

请求参数:

参数名	类型	必填	说明
role_id	string	是	角色ID

返回结果:

{
  "ret": true,
  "msg": "获取角色上下文成功",
  "data": {
    "context": {
      "role_info": {
        "id": "角色ID",
        "name": "角色名称",
        "prompt": "角色提示词",
        "description": "角色描述",
        "created_at": "创建时间",
        "updated_at": "更新时间",
        "is_active": true,
        "config": {}
      },
      "recent_tasks": [
        {
          "id": "任务ID",
          "description": "任务描述",
          "status": "任务状态",
          "created_at": "创建时间",
          "type": "任务类型",
          "is_rtagent_task": true/false,
          "rtagent_task_id": "rtagent任务ID"
        }
      ],
      "recent_notifications": [
        {
          "id": "通知ID",
          "message": "通知消息",
          "type": "通知类型",
          "created_at": "创建时间",
          "read": true/false
        }
      ],
      "memory_summary": "记忆摘要文本",
      "interaction_stats": {
        "total_tasks": 总任务数,
        "total_notifications": 总通知数,
        "active_tasks": 活跃任务数,
        "unread_notifications": 未读通知数,
        "rtagent_tasks": "rtagent任务数"
      },
      "task_results": [
        {
          "task_id": "任务ID",
          "rtagent_task_id": "rtagent任务ID",
          "final_result": "最终结果",
          "status": "状态",
          "completed_at": "完成时间",
          "task_description": "任务描述"
        }
      ],
      "collected_at": "收集时间"
    },
    "context_prompt": "AI可理解的上下文提示文本",
    "collected_at": "收集时间"
  }
}

2. 消息与对话

2.1 发送消息

端点: /rtagent/chatbot/send_message
方法: ALL
功能: 向指定角色发送消息，支持自动识别消息类型（任务/聊天）

请求参数:

参数名	类型	必填	说明
role_id	string	是	角色ID
message	string	是	消息内容
user_id	string	否	用户ID，用于AI对话
s_id	string	否	会话ID
msg_type	string	否	消息类型：`auto`（自动识别，默认）、`chat`（闲聊模式）、`task`（任务模式）

返回结果（自动识别为任务时）:

{
  "ret": true,
  "msg": "任务消息已识别并创建",
  "data": {
    "role_id": "角色ID",
    "message": "原始消息",
    "identification": {
      "isTask": true,
      "isChat": false,
      "confidence": 0.8,
      "reason": "分析理由",
      "suggested_context_elements": ["建议的上下文元素"]
    },
    "task_result": {
      "success": true,
      "task_id": "任务ID",
      "ibbot_task_id": "ibbot任务ID",
      "rtagent_task_id": "rtagent任务ID",
      "task_type": "任务类型",
      "message": "任务创建消息",
      "is_complex_task": true/false,
      "context_included": true/false,
      "task_results_included": true/false,
      "polling_info": {
        "retries": 重试次数,
        "elapsed_ms": 耗时毫秒,
        "reason": "轮询原因"
      }
    },
    "is_task": true,
    "is_complex_task": true/false,
    "context_included": true/false,
    "task_results_included": true/false,
    "timestamp": "时间戳",
    "msg_type": "auto",
    "mode": "task_auto_detected"
  }
}

返回结果（闲聊模式时）:

{
  "ret": true,
  "msg": "消息发送成功",
  "data": {
    "role_id": "角色ID",
    "message": "原始消息",
    "response": "AI响应内容",
    "is_task": false,
    "context_included": true,
    "task_results_included": true,
    "timestamp": "时间戳",
    "msg_type": "chat",
    "mode": "chat_only"
  }
}

3. 记忆管理

3.1 获取角色记忆

端点: /rtagent/chatbot/memory
方法: ALL
功能: 获取指定角色的记忆信息

请求参数:

参数名	类型	必填	说明
role_id	string	是	角色ID

返回结果:

{
  "ret": true,
  "msg": "获取角色记忆成功",
  "data": {
    "role_id": "角色ID",
    "short_term": [
      {
        "role": "user/assistant",
        "content": "内容",
        "timestamp": "时间戳"
      }
    ],
    "long_term": [
      {
        "role": "user/assistant",
        "content": "内容",
        "timestamp": "时间戳"
      }
    ],
    "conversations": [
      {
        "timestamp": "时间戳",
        "message": "用户消息",
        "response": "AI响应",
        "type": "user_assistant"
      }
    ],
    "created_at": "创建时间",
    "updated_at": "更新时间"
  }
}

4. 任务管理

4.1 创建任务

端点: /rtagent/chatbot/create_task
方法: ALL
功能: 直接创建任务（不通过消息识别）

请求参数:

参数名	类型	必填	说明
role_id	string	是	角色ID
description	string	是	任务描述
type	string	否	任务类型：`general`（默认）、`rtagent_document`等
priority	string	否	优先级：`low`、`medium`（默认）、`high`
metadata	object	否	任务元数据

返回结果:

{
  "ret": true,
  "msg": "任务创建成功",
  "data": {
    "id": "任务ID",
    "role_id": "角色ID",
    "type": "任务类型",
    "description": "任务描述",
    "status": "pending",
    "priority": "优先级",
    "created_at": "创建时间",
    "updated_at": "更新时间",
    "started_at": null,
    "completed_at": null,
    "result": null,
    "error": null,
    "metadata": {}
  }
}

4.2 获取任务状态

端点: /rtagent/chatbot/task
方法: ALL
功能: 获取指定任务的详细状态信息

请求参数:

参数名	类型	必填	说明
task_id	string	是	任务ID
role_id	string	否	角色ID（可选，用于提高查询性能）

返回结果:

{
  "ret": true,
  "msg": "获取任务状态成功",
  "data": {
    "id": "任务ID",
    "role_id": "角色ID",
    "type": "任务类型",
    "description": "任务描述",
    "status": "任务状态",
    "priority": "优先级",
    "created_at": "创建时间",
    "updated_at": "更新时间",
    "started_at": "开始时间",
    "completed_at": "完成时间",
    "result": {
      "ibbot": "ibbot任务数据",
      "rtagent": "rtagent任务数据"
    },
    "error": "错误信息",
    "metadata": {
      "user_id": "用户ID",
      "original_message": "原始消息",
      "enriched_message": "增强后的消息",
      "ibbot_task_id": "ibbot任务ID",
      "task_type": "任务类型",
      "is_rtagent_task": true/false,
      "rtagent_task_id": "rtagent任务ID",
      "s_id": "会话ID",
      "check_status_url": "状态检查URL",
      "context_included": true/false,
      "context_summary": {
        "has_role_info": true/false,
        "recent_tasks_count": 最近任务数,
        "recent_notifications_count": 最近通知数,
        "recent_task_results_count": 最近任务结果数
      }
    },
    "tracking": {
      "task_id": "任务ID",
      "ibbot_task_id": "ibbot任务ID",
      "rtagent_task_id": "rtagent任务ID",
      "role_id": "角色ID",
      "status": "追踪状态",
      "progress": 进度百分比,
      "last_check_time": "最后检查时间",
      "retry_count": 重试次数,
      "notification_sent": true/false,
      "history_length": 历史记录长度,
      "is_tracking": true/false,
      "is_complex_task": true/false,
      "rtagent_detail": {
        "status": "rtagent任务状态",
        "current_step": "当前步骤",
        "total_steps": "总步骤数",
        "history_length": "历史长度",
        "execution_time": "执行时间"
      }
    },
    "task_result": {
      "role_id": "角色ID",
      "task_id": "任务ID",
      "rtagent_task_id": "rtagent任务ID",
      "final_result": "最终结果",
      "status": "状态",
      "task_description": "任务描述",
      "created_at": "创建时间",
      "completed_at": "完成时间",
      "metadata": {
        "is_rtagent_task": true/false,
        "user_id": "用户ID",
        "original_message": "原始消息",
        "task_type": "任务类型"
      },
      "saved_at": "保存时间"
    },
    "task_history": {
      "role_id": "角色ID",
      "task_id": "任务ID",
      "description": "任务描述",
      "type": "任务类型",
      "status": "任务状态",
      "priority": "优先级",
      "created_at": "创建时间",
      "updated_at": "更新时间",
      "started_at": "开始时间",
      "completed_at": "完成时间",
      "result": "结果",
      "error": "错误信息",
      "metadata": "元数据",
      "history_saved_at": "历史保存时间"
    }
  }
}

4.3 获取角色任务列表

端点: /rtagent/chatbot/role_tasks
方法: ALL
功能: 获取指定角色的所有任务列表

请求参数:

参数名	类型	必填	说明
role_id	string	是	角色ID

返回结果:

{
  "ret": true,
  "msg": "获取角色任务列表成功",
  "data": {
    "tasks": [
      {
        "id": "任务ID",
        "role_id": "角色ID",
        "type": "任务类型",
        "description": "任务描述",
        "status": "任务状态",
        "priority": "优先级",
        "created_at": "创建时间",
        "updated_at": "更新时间",
        "started_at": "开始时间",
        "completed_at": "完成时间",
        "result": "结果",
        "error": "错误信息",
        "metadata": "元数据"
      }
    ],
    "total": "总任务数",
    "pending": "待处理任务数",
    "running": "运行中任务数",
    "completed": "已完成任务数",
    "failed": "失败任务数",
    "rtagent_tasks": "rtagent任务数"
  }
}

4.4 获取任务追踪状态

端点: /rtagent/chatbot/task_tracking
方法: ALL
功能: 获取任务的详细追踪状态信息

请求参数:

参数名	类型	必填	说明
task_id	string	是	任务ID

返回结果:

{
  "ret": true,
  "msg": "获取任务追踪状态成功",
  "data": {
    "task_id": "任务ID",
    "ibbot_task_id": "ibbot任务ID",
    "rtagent_task_id": "rtagent任务ID",
    "role_id": "角色ID",
    "status": "追踪状态",
    "progress": "进度百分比",
    "last_check_time": "最后检查时间",
    "retry_count": "重试次数",
    "notification_sent": true/false,
    "history_length": "历史记录长度",
    "is_tracking": true/false,
    "is_complex_task": true/false,
    "rtagent_detail": {
      "status": "rtagent任务状态",
      "current_step": "当前步骤",
      "total_steps": "总步骤数",
      "history_length": "历史长度",
      "execution_time": "执行时间",
      "instruction": "指令",
      "final_result": "最终结果"
    }
  }
}

4.5 获取任务结果

端点: /rtagent/chatbot/task_results
方法: ALL
功能: 获取任务执行结果

请求参数:

参数名	类型	必填	说明
role_id	string	是	角色ID
task_id	string	否	任务ID（不传则获取所有任务结果）
limit	number	否	限制数量，默认10

返回结果:

{
  "ret": true,
  "msg": "获取任务结果成功",
  "data": {
    "results": [
      {
        "role_id": "角色ID",
        "task_id": "任务ID",
        "rtagent_task_id": "rtagent任务ID",
        "final_result": "最终结果",
        "status": "状态",
        "task_description": "任务描述",
        "created_at": "创建时间",
        "completed_at": "完成时间",
        "metadata": {
          "is_rtagent_task": true/false,
          "user_id": "用户ID",
          "original_message": "原始消息",
          "task_type": "任务类型"
        },
        "saved_at": "保存时间"
      }
    ],
    "total": "结果总数",
    "has_rtagent_results": "包含rtagent结果的数量"
  }
}

4.6 获取任务历史记录

端点: /rtagent/chatbot/task_histories
方法: ALL
功能: 获取任务历史记录（从task_history目录）

请求参数:

参数名	类型	必填	说明
role_id	string	是	角色ID
task_id	string	否	任务ID（不传则获取所有任务历史）
limit	number	否	限制数量，默认10

返回结果:

{
  "ret": true,
  "msg": "获取任务历史记录成功",
  "data": {
    "histories": [
      {
        "role_id": "角色ID",
        "task_id": "任务ID",
        "description": "任务描述",
        "type": "任务类型",
        "status": "任务状态",
        "priority": "优先级",
        "created_at": "创建时间",
        "updated_at": "更新时间",
        "started_at": "开始时间",
        "completed_at": "完成时间",
        "result": "结果",
        "error": "错误信息",
        "metadata": "元数据",
        "history_saved_at": "历史保存时间"
      }
    ],
    "total": "历史记录总数",
    "has_complex_tasks": "包含复杂任务的数量"
  }
}

5. 通知管理

5.1 获取用户通知

端点: /rtagent/chatbot/notifications
方法: ALL
功能: 获取指定角色的通知列表

请求参数:

参数名	类型	必填	说明
role_id	string	是	角色ID
limit	number	否	限制数量，默认20
offset	number	否	偏移量，默认0

返回结果:

{
  "ret": true,
  "msg": "获取通知成功",
  "data": {
    "notifications": [
      {
        "id": "通知ID",
        "role_id": "角色ID",
        "task_id": "任务ID",
        "ibbot_task_id": "ibbot任务ID",
        "rtagent_task_id": "rtagent任务ID",
        "user_id": "用户ID",
        "status": "任务状态",
        "message": "通知消息",
        "timestamp": "时间戳",
        "data": {
          "ibbot": "ibbot任务数据",
          "rtagent": "rtagent任务数据"
        },
        "type": "通知类型",
        "is_complex_task": true/false,
        "created_at": "创建时间",
        "read": true/false,
        "delivered": true/false,
        "delivered_at": "发送时间",
        "read_at": "阅读时间"
      }
    ],
    "total": "通知总数",
    "unread": "未读通知数",
    "complex_tasks": "复杂任务通知数"
  }
}

5.2 标记通知为已读

端点: /rtagent/chatbot/notification_read
方法: ALL
功能: 将指定通知标记为已读

请求参数:

参数名	类型	必填	说明
notification_id	string	是	通知ID
role_id	string	是	角色ID

返回结果:

{
  "ret": true,
  "msg": "通知已标记为已读"
}

6. 系统管理

6.1 心跳检查

端点: /rtagent/chatbot/heartbeat
方法: ALL
功能: 检查系统运行状态，返回系统统计信息

请求参数: 无

返回结果:

{
  "ret": true,
  "msg": "心跳检查完成",
  "data": {
    "timestamp": "时间戳",
    "status": "healthy/error",
    "total_roles": "总角色数",
    "pending_tasks": "待处理任务数",
    "running_tasks": "运行中任务数",
    "total_tasks": "总任务数",
    "rtagent_tasks": "rtagent任务数",
    "task_results": "任务结果数",
    "task_histories": "任务历史记录数",
    "error": "错误信息（仅当status为error时）"
  }
}

数据结构说明

1. 角色数据结构

{
  "id": "角色唯一标识",
  "name": "角色名称",
  "prompt": "角色提示词，用于AI对话",
  "description": "角色描述",
  "created_at": "ISO时间戳",
  "updated_at": "ISO时间戳",
  "is_active": "是否激活",
  "config": "角色配置对象"
}

2. 任务数据结构

{
  "id": "任务唯一标识",
  "role_id": "所属角色ID",
  "type": "任务类型：general/rtagent_document",
  "description": "任务描述",
  "status": "状态：pending/running/completed/failed/cancelled",
  "priority": "优先级：low/medium/high",
  "created_at": "创建时间",
  "updated_at": "更新时间",
  "started_at": "开始时间",
  "completed_at": "完成时间",
  "result": "任务结果",
  "error": "错误信息",
  "metadata": {
    "user_id": "用户ID",
    "original_message": "原始消息",
    "enriched_message": "增强后的消息",
    "ibbot_task_id": "ibbot任务ID",
    "task_type": "任务类型",
    "is_rtagent_task": "是否为rtagent任务",
    "rtagent_task_id": "rtagent任务ID",
    "s_id": "会话ID",
    "check_status_url": "状态检查URL",
    "context_included": "是否包含上下文",
    "context_summary": "上下文摘要",
    "polling_result": "轮询结果",
    "result_saved": "结果是否已保存",
    "result_saved_at": "结果保存时间"
  }
}

3. 记忆数据结构

{
  "role_id": "角色ID",
  "short_term": [
    {
      "role": "user/assistant",
      "content": "内容",
      "timestamp": "时间戳"
    }
  ],
  "long_term": [
    {
      "role": "user/assistant",
      "content": "内容",
      "timestamp": "时间戳"
    }
  ],
  "conversations": [
    {
      "timestamp": "时间戳",
      "message": "用户消息",
      "response": "AI响应",
      "type": "user_assistant"
    }
  ],
  "created_at": "创建时间",
  "updated_at": "更新时间"
}

4. 通知数据结构

{
  "id": "通知唯一标识",
  "role_id": "角色ID",
  "task_id": "任务ID",
  "ibbot_task_id": "ibbot任务ID",
  "rtagent_task_id": "rtagent任务ID",
  "user_id": "用户ID",
  "status": "任务状态",
  "message": "通知消息",
  "timestamp": "时间戳",
  "data": {
    "ibbot": "ibbot任务数据",
    "rtagent": "rtagent任务数据"
  },
  "type": "通知类型：task_status等",
  "is_complex_task": "是否为复杂任务",
  "created_at": "创建时间",
  "read": "是否已读",
  "delivered": "是否已发送",
  "delivered_at": "发送时间",
  "read_at": "阅读时间"
}

5. 任务结果数据结构

{
  "role_id": "角色ID",
  "task_id": "任务ID",
  "rtagent_task_id": "rtagent任务ID",
  "final_result": "最终结果",
  "status": "状态",
  "task_description": "任务描述",
  "created_at": "创建时间",
  "completed_at": "完成时间",
  "metadata": {
    "is_rtagent_task": "是否为rtagent任务",
    "user_id": "用户ID",
    "original_message": "原始消息",
    "task_type": "任务类型"
  },
  "saved_at": "保存时间"
}

重要功能说明

1. 消息类型识别

系统支持三种消息处理模式：

auto（默认）: 自动识别消息类型（任务/聊天）
chat: 强制作为闲聊消息处理
task: 强制作为任务消息处理

2. 任务识别与创建流程

消息类型识别（关键词匹配或AI分析）
收集角色上下文信息（包含历史任务结果）
调用iBBot API创建任务
轮询检查任务状态，获取rtagent_task_id
创建chatbot任务记录
启动任务追踪（针对复杂任务）

3. 轮询配置

const POLLING_CONFIG = {
    MAX_RETRIES: 35,           // 最大重试次数
    RETRY_INTERVAL: 1000,      // 重试间隔（毫秒）
    TIMEOUT: 30000,            // 总超时时间（毫秒）
    INITIAL_DELAY: 1000        // 初始延迟（毫秒）
};

4. 数据存储结构

chatbot-agent/data/
├── roles/
│   ├── role_xxx/
│   │   ├── role.json          # 角色信息
│   │   ├── memory.json        # 记忆文件
│   │   ├── task_results.json  # 任务结果
│   │   ├── tasks/             # 任务目录
│   │   │   ├── task_xxx.json
│   │   │   └── task_yyy.json
│   │   ├── task_history/      # 任务历史目录
│   │   │   ├── task_xxx.json
│   │   │   └── task_yyy.json
│   │   └── notifications/     # 通知目录
│   │       ├── notify_xxx.json
│   │       └── notify_yyy.json
│   └── role_yyy/
│       └── ...

5. 任务状态映射

ibbot状态 → chatbot状态:
- processing/executing/running → running
- completed/skill_completed → completed
- failed/skill_failed → failed
- cancelled → cancelled

6. 错误处理

所有API端点都包含错误处理，返回格式：

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

注意事项

数据存储: 所有数据按角色ID组织，每个角色有独立的目录结构
任务历史: 任务历史记录使用目录结构，每个任务单独保存为JSON文件
消息类型: 支持通过msg_type参数控制消息处理模式
上下文集成: 任务创建时会自动包含角色上下文和历史任务结果
轮询机制: 复杂任务会自动轮询检查状态，直到获取rtagent_task_id或超时
错误处理: 所有API都包含完整的错误处理和日志记录
性能优化: 使用内存缓存提高频繁访问数据的性能

版本信息

当前版本: 重构版本（数据存储结构重构 + 角色上下文支持）
主要修改:
1. 数据存储结构重构：统一组织到roles目录下
2. 角色上下文支持：在创建任务时带上角色相关的上下文信息
3. 存储rtagent任务结果并在新任务上下文中带上这些结果
4. 任务历史记录存储方式重构：改为${role_id}/task_history/${task_id}.json文件存储方式
5. 新增msg_type参数支持，可控制消息处理模式
依赖模块:
- fs/promises: 文件系统操作
- path: 路径处理
- user-agent.js: AI对话功能
- ibbot任务API: 任务处理功能

🧩 角色扮演聊天

🗂️ 技能一览

角色扮演聊天

Chatbot Agent API 文档

概述

数据存储结构

API 端点列表

1. 角色管理

1.1 创建角色

1.2 获取角色列表

1.3 更新角色

1.4 删除角色

1.5 获取角色上下文信息

2. 消息与对话

2.1 发送消息

3. 记忆管理

3.1 获取角色记忆

4. 任务管理

4.1 创建任务

4.2 获取任务状态

4.3 获取角色任务列表

4.4 获取任务追踪状态

4.5 获取任务结果

4.6 获取任务历史记录

5. 通知管理

5.1 获取用户通知

5.2 标记通知为已读

6. 系统管理

6.1 心跳检查

数据结构说明

1. 角色数据结构

2. 任务数据结构

3. 记忆数据结构

4. 通知数据结构

5. 任务结果数据结构

重要功能说明

1. 消息类型识别

2. 任务识别与创建流程

3. 轮询配置

4. 数据存储结构

5. 任务状态映射

6. 错误处理

注意事项

版本信息