iBBot 智能代理系统 API 文档

概述

iBBot 智能代理系统是一个智能代理系统，负责理解用户输入的自然语言指令，智能识别用户意图和需求，分析用户偏好和习惯，识别技能的特殊要求和依赖关系，调度和执行合适的技能任务，管理任务生命周期和状态。

系统配置

配置项	默认值	说明
TASK_DIR	`./tasks`	任务文件存储目录
USER_PREFS_DIR	`./user_prefs`	用户偏好文件存储目录
SKILLS_DIR	`./skills`	技能文档存储目录
TASK_CHECK_INTERVAL	2000ms	任务状态检查间隔
MAX_TASK_HISTORY	1000	最大任务历史记录数
TASK_TIMEOUT	300分钟	任务超时时间

API 端点列表

1. 用户输入处理接口

`POST /ibbot/process`

处理用户输入的自然语言指令，进行意图分析并执行相应操作。

请求参数：

参数名	类型	必填	说明
user_id	string	是	用户唯一标识符
input	string	是	用户输入的自然语言指令
s_id	string	否	会话ID

请求示例：

{
  "user_id": "user123",
  "input": "帮我创建一个网站",
  "s_id": "session_abc"
}

返回结果：

{
  "ret": true,
  "msg": "请求已接收，正在处理",
  "data": {
    "ibbot_task_id": "ibbot_1700000000000_abc123",
    "status": "processing",
    "check_status_url": "/ibbot/task?task_id=ibbot_1700000000000_abc123"
  }
}

返回字段说明：

ret: 布尔值，表示请求是否成功接收
msg: 消息描述
data.ibbot_task_id: iBBot任务ID，用于后续查询任务状态
data.status: 任务初始状态，通常为"processing"
data.check_status_url: 任务状态查询URL

2. 任务管理接口

`GET /ibbot/tasks`

获取用户的任务列表，主要返回rtagent_task的任务。

请求参数：

参数名	类型	必填	说明
user_id	string	是	用户唯一标识符
s_id	string	否	会话ID，用于筛选特定会话的任务
status	string	否	任务状态筛选（如：processing, completed, failed等）
limit	number	否	返回结果数量限制，默认20
offset	number	否	分页偏移量，默认0

请求示例：

GET /ibbot/tasks?user_id=user123&limit=10&offset=0

返回结果：

{
  "ret": true,
  "data": {
    "tasks": [
      {
        "task_id": "rtagent_1700000000000_def456",
        "user_id": "user123",
        "instruction": "帮我创建一个网站",
        "status": "processing",
        "created_at": "2024-01-01T12:00:00.000Z",
        "updated_at": "2024-01-01T12:00:10.000Z",
        "task_type": "rtagent_task",
        "real_time_info": {
          "is_active": true,
          "last_updated": "2024-01-01T12:00:10.000Z",
          "can_monitor": true,
          "monitor_url": "/ibbot/task?task_id=rtagent_1700000000000_def456"
        },
        "progress": 50,
        "execution_duration": 10,
        "execution_duration_formatted": "10秒"
      }
    ],
    "total": 15,
    "limit": 10,
    "offset": 0,
    "summary": {
      "total_tasks": 15,
      "active_tasks": 3,
      "completed_tasks": 10,
      "failed_tasks": 2
    }
  }
}

返回字段说明：

tasks: 任务数组
- task_id: 任务唯一标识符
- user_id: 用户ID
- instruction: 用户指令内容
- status: 任务状态（processing, executing, running, completed, failed, cancelled等）
- created_at: 任务创建时间
- updated_at: 任务最后更新时间
- task_type: 任务类型（rtagent_task）
- real_time_info: 实时监控信息
  - is_active: 是否活跃任务
  - last_updated: 最后更新时间
  - can_monitor: 是否可以监控
  - monitor_url: 监控URL
- progress: 任务进度百分比（0-100）
- execution_duration: 执行持续时间（秒）
- execution_duration_formatted: 格式化后的执行时间
total: 总任务数
limit: 本次查询限制数
offset: 本次查询偏移量
summary: 任务统计摘要

`GET /ibbot/task`

获取任务详情，支持ibbot任务和rtagent任务。

请求参数：

参数名	类型	必填	说明
task_id	string	是	任务ID（可以是ibbot_task_id或rtagent_task_id）
user_id	string	否	用户ID，用于权限验证
s_id	string	否	会话ID

请求示例：

GET /ibbot/task?task_id=rtagent_1700000000000_def456&user_id=user123

返回结果（rtagent任务）：

{
  "ret": true,
  "data": {
    "task_type": "rtagent_task",
    "task_id": "rtagent_1700000000000_def456",
    "user_id": "user123",
    "instruction": "帮我创建一个网站",
    "status": "processing",
    "skill": "aiweb-skill.md",
    "skills": ["aiweb-skill.md", "mail-skill.md"],
    "created_at": "2024-01-01T12:00:00.000Z",
    "start_time": "2024-01-01T12:00:00.000Z",
    "updated_at": "2024-01-01T12:00:10.000Z",
    "progress": 50,
    "result": null,
    "error": null
  }
}

返回结果（ibbot任务）：

{
  "ret": true,
  "data": {
    "task_type": "ibbot_task",
    "task_id": "ibbot_1700000000000_abc123",
    "user_id": "user123",
    "input": "帮我创建一个网站",
    "status": "skill_executed",
    "phase": "task_execution",
    "skill_names": ["aiweb-skill.md"],
    "rtagent_task_id": "rtagent_1700000000000_def456",
    "rtagent_status": "processing",
    "created_at": "2024-01-01T12:00:00.000Z",
    "updated_at": "2024-01-01T12:00:10.000Z",
    "history": [
      {
        "timestamp": "2024-01-01T12:00:05.000Z",
        "phase": "intent_analysis",
        "response": {
          "phase": "intent_analysis",
          "is_skill_task": true,
          "skill_names": ["aiweb-skill.md"]
        }
      }
    ]
  }
}

返回字段说明（通用）：

task_type: 任务类型（ibbot_task 或 rtagent_task）
task_id: 任务ID
user_id: 用户ID
status: 任务状态

ibbot任务特有字段：

input: 原始用户输入
phase: 处理阶段（intent_analysis, task_execution, preference_recording）
skill_names: 识别的技能文档名称数组
rtagent_task_id: 关联的rtagent任务ID
rtagent_status: rtagent任务状态
history: 处理历史记录

rtagent任务特有字段：

instruction: 处理后的指令
skill: 单个技能文档名称（当只有一个技能时）
skills: 多个技能文档名称数组
start_time: 任务开始时间
progress: 任务进度
result: 任务结果
error: 错误信息

`POST /ibbot/task/cancel`

取消正在执行的任务，支持ibbot任务和rtagent任务。

请求参数：

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

请求示例：

{
  "task_id": "rtagent_1700000000000_def456"
}

返回结果：

{
  "ret": true,
  "msg": "任务已取消",
  "data": {
    "task_id": "rtagent_1700000000000_def456",
    "status": "cancelled",
    "cancelled_at": "2024-01-01T12:00:15.000Z"
  }
}

返回字段说明：

ret: 布尔值，表示取消是否成功
msg: 消息描述
data.task_id: 被取消的任务ID
data.status: 取消后的状态
data.cancelled_at: 取消时间

3. 用户偏好接口

`GET /ibbot/preferences`

获取用户偏好信息。

请求参数：

参数名	类型	必填	说明
user_id	string	是	用户唯一标识符

请求示例：

GET /ibbot/preferences?user_id=user123

返回结果：

{
  "ret": true,
  "data": {
    "user_id": "user123",
    "email": "user@example.com",
    "address": "北京市朝阳区",
    "preferences": [
      {
        "summary": "喜欢蓝色主题",
        "category": "design",
        "details": "用户表示喜欢蓝色系的网站设计",
        "timestamp": "2024-01-01T10:00:00.000Z"
      }
    ],
    "history": [
      "2024-01-01T10:00:00.000Z: 用户表示喜欢蓝色主题",
      "2024-01-01T11:00:00.000Z: 用户需要快速加载的网站"
    ],
    "metadata": {
      "language": "zh-CN",
      "timezone": "Asia/Shanghai"
    },
    "created_at": "2024-01-01T00:00:00.000Z",
    "updated_at": "2024-01-01T12:00:00.000Z"
  }
}

返回字段说明：

user_id: 用户ID
email: 用户邮箱
address: 用户地址
preferences: 用户偏好记录数组
- summary: 偏好摘要
- category: 分类（design, performance, content等）
- details: 详细信息
- timestamp: 记录时间
history: 历史记录文本数组
metadata: 元数据键值对
created_at: 创建时间
updated_at: 最后更新时间

`POST /ibbot/preferences/update`

更新用户偏好信息。

请求参数：

参数名	类型	必填	说明
user_id	string	是	用户唯一标识符
email	string	否	用户邮箱
address	string	否	用户地址
metadata	object	否	元数据键值对

请求示例：

{
  "user_id": "user123",
  "email": "newemail@example.com",
  "metadata": {
    "language": "en-US",
    "preferred_theme": "dark"
  }
}

返回结果：

{
  "ret": true,
  "msg": "用户偏好已更新",
  "data": {
    "user_id": "user123",
    "email": "newemail@example.com",
    "address": "北京市朝阳区",
    "updated_at": "2024-01-01T12:30:00.000Z"
  }
}

返回字段说明：

ret: 布尔值，表示更新是否成功
msg: 消息描述
data: 更新后的用户偏好信息

4. 系统状态接口

`GET /ibbot/status`

获取系统状态信息，包括任务统计、性能指标等。

请求参数： 无

请求示例：

GET /ibbot/status

返回结果：

{
  "ret": true,
  "data": {
    "system": "iBBot 智能代理系统",
    "version": "1.0.0",
    "uptime": 3600,
    "uptime_formatted": "1小时",
    
    "performance": {
      "memory_usage_mb": 256,
      "memory_total_mb": 1024,
      "memory_usage_percent": 25,
      "platform": "linux",
      "node_version": "v18.17.0"
    },
    
    "task_tracker": {
      "running": true,
      "last_check": "2024-01-01T12:00:10.000Z",
      "check_interval": 2000,
      "checks_performed": 1800
    },
    
    "rtagent_task_stats": {
      "total": 150,
      "processing": 3,
      "executing": 2,
      "running": 5,
      "completed": 120,
      "failed": 10,
      "cancelled": 5,
      "skill_completed": 100,
      "skill_failed": 5,
      "other": 0,
      "active_tasks": 10,
      "long_running_tasks": 2,
      "active_tasks_list": [
        {
          "task_id": "rtagent_1700000000000_abc123",
          "user_id": "user123",
          "status": "processing",
          "instruction": "帮我创建一个网站...",
          "start_time": "2024-01-01T12:00:00.000Z",
          "duration": 600
        }
      ],
      "long_running_tasks_list": [
        {
          "task_id": "rtagent_1700000000000_xyz789",
          "user_id": "user456",
          "duration": 1800,
          "duration_formatted": "30分钟"
        }
      ]
    },
    
    "ibbot_task_stats": {
      "total": 200,
      "analyzing": 2,
      "executing_skill": 3,
      "recording_preference": 1,
      "completed": 180,
      "failed": 10,
      "cancelled": 2,
      "skill_completed": 150,
      "skill_failed": 8
    },
    
    "user_count": 50,
    "skill_count": 15,
    
    "cache_stats": {
      "rtagent_tasks": 150,
      "ibbot_tasks": 200,
      "user_preferences": 50,
      "skill_docs": 15
    },
    
    "directories": {
      "tasks": "/path/to/tasks",
      "user_prefs": "/path/to/user_prefs",
      "skills": "/path/to/skills"
    },
    
    "monitoring": {
      "real_time_updates": true,
      "task_check_interval": 2000,
      "max_concurrent_tasks": 100,
      "task_timeout": 18000000,
      "task_timeout_formatted": "300分钟"
    }
  }
}

返回字段说明：

system: 系统名称
version: 系统版本
uptime: 系统运行时间（秒）
uptime_formatted: 格式化后的运行时间
performance: 性能指标
- memory_usage_mb: 内存使用量（MB）
- memory_total_mb: 总内存（MB）
- memory_usage_percent: 内存使用百分比
- platform: 运行平台
- node_version: Node.js版本
task_tracker: 任务追踪器状态
rtagent_task_stats: rtagent任务统计
ibbot_task_stats: ibbot任务统计
user_count: 用户数量
skill_count: 技能文档数量
cache_stats: 缓存统计
directories: 系统目录路径
monitoring: 监控配置信息

数据结构说明

1. 任务状态枚举

状态值	说明
analyzing	意图分析中
executing_skill	执行技能任务中
recording_preference	记录用户偏好中
processing	处理中（通用）
executing	执行中
running	运行中
completed	已完成
failed	已失败
cancelled	已取消
skill_completed	技能任务已完成
skill_failed	技能任务已失败

2. 处理阶段枚举

阶段值	说明
intent_analysis	意图分析阶段
task_execution	任务执行阶段
preference_recording	偏好记录阶段

3. AI响应格式

系统使用AI进行意图分析，AI响应必须遵循以下JSON格式：

意图分析阶段

{
  "phase": "intent_analysis",
  "is_skill_task": true,
  "skill_names": ["aiweb-skill.md", "mail-skill.md"],
  "user_intent": "解析后的用户意图描述",
  "user_preferences_identified": ["偏好1", "偏好2", "邮箱信息", "地址信息"],
  "special_requirements_identified": ["特殊要求1", "特殊要求2"],
  "dependencies_identified": ["依赖技能1.md", "依赖技能2.md"],
  "required_parameters": {
    "user_id": "用户ID",
    "s_id": "会话ID",
    "email": "用户邮箱",
    "address": "用户地址",
    "other_params": "其他参数"
  },
  "execution_plan": "执行计划描述",
  "next_action": "execute_task"
}

任务执行阶段

{
  "phase": "task_execution",
  "task_id": "任务ID",
  "skills_to_use": ["使用的技能名称1.md", "技能名称2.md"],
  "api_endpoint": "/rtagent/task/execute",
  "parameters": {
    "user_id": "用户ID",
    "instruction": "用户指令[要求: 特殊要求1][要求: 特殊要求2] [用户偏好信息:...]",
    "skills": ["技能1.md", "技能2.md", "依赖技能1.md"],
    "s_id": "会话ID"
  },
  "estimated_time": "预计执行时间",
  "next_action": "monitor_task"
}

偏好记录阶段

{
  "phase": "preference_recording",
  "summary": "用户意图的一句话总结",
  "category": "意图分类（如：hobby、idea、request等）",
  "timestamp": "记录时间",
  "relevance_score": "相关性分数0-100",
  "next_action": "acknowledge_user"
}

4. 用户偏好文件格式

用户偏好文件以Markdown格式存储：

# 用户偏好文件 - user123

创建时间: 2024-01-01T00:00:00.000Z
更新时间: 2024-01-01T12:00:00.000Z

## 元数据
邮箱: user@example.com
地址: 北京市朝阳区

## 偏好记录
- 喜欢蓝色主题 (design): 用户表示喜欢蓝色系的网站设计
- 需要快速加载 (performance): 用户强调网站加载速度要快

## 历史记录
2024-01-01T10:00:00.000Z: 用户表示喜欢蓝色主题
2024-01-01T11:00:00.000Z: 用户需要快速加载的网站

错误处理

所有API接口返回统一的错误格式：

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

常见错误码和描述：

错误场景	错误描述
缺少必要参数	"用户ID和输入内容不能为空"
任务不存在	"任务不存在"
无权访问	"无权访问此任务"
系统错误	"处理失败: [具体错误信息]"

🧩 ibbo智体机灵

🗂️ 技能一览

ibbo智体机灵

iBBot 智能代理系统 API 文档

概述

系统配置

API 端点列表

1. 用户输入处理接口

`POST /ibbot/process`

2. 任务管理接口

`GET /ibbot/tasks`

`GET /ibbot/task`

`POST /ibbot/task/cancel`

3. 用户偏好接口

`GET /ibbot/preferences`

`POST /ibbot/preferences/update`

4. 系统状态接口

`GET /ibbot/status`

数据结构说明

1. 任务状态枚举

2. 处理阶段枚举

3. AI响应格式

意图分析阶段

任务执行阶段

偏好记录阶段

4. 用户偏好文件格式

错误处理