uctoo-api-skill（uctoo API 技能）

UCTOO API Skill - 后端 API 集成技能

概述

本技能指导你使用框架内置的 http_request 工具来发起 HTTP 请求。

当用户请求 uctoo 相关的 API 操作时，你必须：

1. 分析用户需求，确定要调用哪个 API 端点
2. 直接调用 http_request 工具发起 HTTP 请求
3. 将响应结果返回给用户

⚠️ 禁止事项：

• ❌ 不要调用 uctoo-api-skill 工具（这是技能文档，不是工具）
• ✅ 直接使用 http_request 工具

🎉 自动 Token 管理（重要）

系统已实现自动 Token 管理机制，你无需手动处理认证！

自动管理功能

1. 自动保存：当登录接口返回 access_token 时，系统会自动保存到会话中
2. 自动注入：后续请求会自动在 headers 中添加 Authorization: Bearer {token}
3. 无需手动传递：你不需要在请求中手动添加 Authorization header

你只需要做的事

• 调用登录接口完成登录
• 后续请求直接调用即可，系统会自动处理认证

API 基础配置

API 基础地址：https://javatoarktsapi.uctoo.com

完整 URL 格式：{基础地址}{API路径}

• 示例：https://javatoarktsapi.uctoo.com/api/uctoo/auth/login

http_request 工具参数格式

工具名称：http_request

参数说明：

⚠️ 重要：headers 和 body 参数必须是 JSON 字符串格式！

常用 API 端点

认证相关

Entity 相关

完整调用示例

示例 1：用户登录

用户请求： "请以用户名 demo 密码 123456 进行登录"

调用 http_request 工具：

{
  "method": "POST",
  "url": "https://javatoarktsapi.uctoo.com/api/uctoo/auth/login",
  "headers": "{\"Content-Type\": \"application/json\"}",
  "body": "{\"username\": \"demo\", \"password\": \"123456\"}"
}

成功响应示例：

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "505cf909-5e0e-4dde-b215-74274d2cc548",
    "name": "UCTooApp",
    "username": "demo",
    "email": "demo@uctoo.com"
  }
}

注意：登录成功后，系统会自动保存 token，后续请求无需手动添加 Authorization header。

示例 2：获取实体列表

用户请求： "获取前10条实体数据"

调用 http_request 工具：

{
  "method": "GET",
  "url": "https://javatoarktsapi.uctoo.com/api/uctoo/entity/10/0"
}

示例 3：编辑实体（自动认证）

用户请求： "将 id 为 fd0a410a-7038-4c62-a5e4-9f7950d3d406 的实体的 link 字段更新为 uctoo.com"

调用 http_request 工具：

{
  "method": "POST",
  "url": "https://javatoarktsapi.uctoo.com/api/uctoo/entity/edit",
  "headers": "{\"Content-Type\": \"application/json\"}",
  "body": "{\"id\": \"fd0a410a-7038-4c62-a5e4-9f7950d3d406\", \"link\": \"uctoo.com\"}"
}

注意：系统会自动注入 Authorization header，你不需要手动添加。

⚠️ 关键注意事项：

• id 必须是实际的 UUID 值，格式如 fd0a410a-7038-4c62-a5e4-9f7950d3d406
• 不要使用占位符 如 实体ID、YOUR_ID、id 等
• 如果用户没有提供具体的 ID，先查询列表获取 ID

示例 4：获取当前用户信息

用户请求： "获取当前登录用户的信息"

调用 http_request 工具：

{
  "method": "GET",
  "url": "https://javatoarktsapi.uctoo.com/api/uctoo/auth/me"
}

注意：系统会自动注入 Authorization header。

错误处理

常见错误及解决方案

错误 1：UUID 格式错误

错误信息： Error creating UUID, invalid character 原因： 传递的 id 不是有效的 UUID 格式 解决方案： 确保 id 是实际的 UUID 值，如 fd0a410a-7038-4c62-a5e4-9f7950d3d406

错误 2：未登录

错误信息： not login 或 403 Forbidden 原因： 用户尚未登录或 token 已过期 解决方案： 先调用登录接口，系统会自动保存 token

错误 3：参数格式错误

错误信息： 400 Bad Request 原因： body 参数格式不正确 解决方案： 确保 body 是有效的 JSON 字符串，且字段名和值正确

重要提醒

1. ✅ 直接调用 http_request 工具
2. ✅ headers 和 body 必须是 JSON 字符串格式
3. ✅ POST 请求必须设置 Content-Type: application/json
4. ✅ 认证 token 由系统自动管理，无需手动处理
5. ✅ id 参数必须是实际的 UUID 值，不能是占位符
6. ❌ 不要调用 uctoo-api-skill 工具
7. ❌ 不要使用 实体ID、YOUR_ID 等占位符
8. ❌ 不要手动添加 Authorization header（系统自动注入）