Skill: uctoocom/uctoo-api-skill (version 0.0.1)

--- name: uctoo-api-skill description: 完整的 uctoo 后端 API 集成技能。将自然语言请求转换为 uctoo-backend API 调用，支持用户管理、产品管理、订单管理、登录认证等功能。使用时用户提及 "uctoo"、"后端API"、"用户管理"、"产品"、"订单"、"登录"、"认证" 等关键词时，你应该直接使用 http_request 工具发起实际的 API 请求。 license: MIT compatibility: 需要网络访问 uctoo 后端 API metadata: author: UCToo Team version: "7.0.0" category: api-integration allowedTools: --- # 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` **参数说明：** | 参数 | 必需 | 类型 | 说明 | |------|------|------|------| | method | 是 | string | HTTP 方法：GET、POST、PUT、DELETE | | url | 是 | string | 完整的请求 URL | | headers | 否 | string | JSON 字符串格式的请求头（可选，系统会自动注入 Authorization） | | body | 否 | string | JSON 字符串格式的请求体（POST/PUT 需要） | **⚠️ 重要：headers 和 body 参数必须是 JSON 字符串格式！** ## 常用 API 端点 ### 认证相关 | 端点 | 方法 | 说明 | 需要认证 | |------|------|------|----------| | `/api/uctoo/auth/login` | POST | 用户登录 | 否 | | `/api/uctoo/auth/signin` | POST | 用户登录（带验证码） | 否 | | `/api/uctoo/auth/logout` | GET | 用户登出 | 自动 | | `/api/uctoo/auth/me` | GET | 获取当前用户信息 | 自动 | ### Entity 相关 | 端点 | 方法 | 说明 | 需要认证 | |------|------|------|----------| | `/api/uctoo/entity/{limit}/{page}` | GET | 获取实体列表 | 否 | | `/api/uctoo/entity/{id}` | GET | 获取单个实体 | 否 | | `/api/uctoo/entity/add` | POST | 添加实体 | 自动 | | `/api/uctoo/entity/edit` | POST | 编辑实体 | 自动 | | `/api/uctoo/entity/del` | POST | 删除实体 | 自动 | ## 完整调用示例 ### 示例 1：用户登录 **用户请求：** "请以用户名 demo 密码 123456 进行登录" **调用 http_request 工具：** ```json { "method": "POST", "url": "https://javatoarktsapi.uctoo.com/api/uctoo/auth/login", "headers": "{\"Content-Type\": \"application/json\"}", "body": "{\"username\": \"demo\", \"password\": \"123456\"}" } ``` **成功响应示例：** ```json { "access_token": "eyJhbGciOiJIUzI1NiIs...", "refresh_token": "eyJhbGciOiJIUzI1NiIs...", "user": { "id": [REDACTED_SECRET], "name": "UCTooApp", "username": "demo", "email": "[REDACTED_SECRET]" } } ``` **注意**：登录成功后，系统会自动保存 token，后续请求无需手动添加 Authorization header。 ### 示例 2：获取实体列表 **用户请求：** "获取前10条实体数据" **调用 http_request 工具：** ```json { "method": "GET", "url": "https://javatoarktsapi.uctoo.com/api/uctoo/entity/10/0" } ``` ### 示例 3：编辑实体（自动认证） **用户请求：** "将 id 为 fd0a410a-7038-4c62-a5e4-9f7950d3d406 的实体的 link 字段更新为 uctoo.com" **调用 http_request 工具：** ```json { "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 值，格式如 [REDACTED_SECRET] - **不要使用占位符** 如 `实体ID`、`YOUR_ID`、`id` 等 - 如果用户没有提供具体的 ID，先查询列表获取 ID ### 示例 4：获取当前用户信息 **用户请求：** "获取当前登录用户的信息" **调用 http_request 工具：** ```json { "method": "GET", "url": "https://javatoarktsapi.uctoo.com/api/uctoo/auth/me" } ``` **注意**：系统会自动注入 Authorization header。 ## 错误处理 | 状态码 | 说明 | 处理方式 | |--------|------|----------| | 200 | 成功 | 正常处理响应 | | 400 | 请求参数错误 | 检查请求参数格式 | | 401 | 未授权/Token过期 | 提示用户重新登录 | | 403 | 无权限 | 检查是否登录或是否有权限 | | 404 | 资源不存在 | 检查URL路径是否正确 | | 500 | 服务器内部错误 | 联系管理员或稍后重试 | ## 常见错误及解决方案 ### 错误 1：UUID 格式错误 **错误信息：** `Error creating UUID, invalid character` **原因：** 传递的 id 不是有效的 UUID 格式 **解决方案：** 确保 id 是实际的 UUID 值，如 [REDACTED_SECRET] ### 错误 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（系统自动注入）**

path: README.md
content: # UCTOO API Skill (V2)

## 概述

这是 uctoo-api-skill 的 V2 版本，采用完全重构的架构，真正发挥大模型的语义理解和推理能力。

## 核心理念

### 从 V1 到 V2 的转变

**V1 (旧架构)**:
- 硬编码关键词提取
- 固定的 API 调用逻辑
- 大量的代码实现
- 脆弱且难以维护

**V2 (新架构)**:
- 大模型驱动的语义理解
- 灵活的 API 选择和参数组装
- 极简代码实现
- 易于维护和扩展

## 架构设计

### 分层架构

```
┌─────────────────────────────────────────────────────────┐
│                     用户输入                           │
│         "请使用 demo 账号 123456 登录"                │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│              大模型（知识层 + 推理）                    │
│  ┌───────────────────────────────────────────────────┐ │
│  │ 1. 理解用户意图：需要登录                          │ │
│  │ 2. 识别参数：username=demo, [REDACTED_SECRET]      │ │
│  │ 3. 选择 API：POST /api/uctoo/auth/login           │ │
│  │ 4. 组装请求体：{"username":"demo","password":"123456"}│ │
│  │ 5. 调用 HTTP 工具执行请求                          │ │
│  │ 6. 解析响应并生成友好回复                          │ │
│  └───────────────────────────────────────────────────┘ │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│                 HTTP 工具（连接层）                     │
│              执行实际的 API 请求                        │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│                 UCTOO 后端 API                          │
└─────────────────────────────────────────────────────────┘
```

## 文件结构

```
uctoo-api-skill/
├── SKILL.md                          # 主技能文件（知识层）
├── README.md                         # 本文件
├── Main.cj                           # 入口点（用于测试）
├── references/                       # 参考文档
│   ├── api_spec.md                   # 完整的 API 规范
│   ├── examples.md                   # 使用示例
│   └── uctoo_api_design.md          # API 设计文档
├── scripts/                          # 脚本工具
│   ├── api_client.py                 # HTTP 客户端（主要使用）
│   ├── api_client.js                 # JavaScript 版本（备用）
│   └── test_api.py                   # API 测试脚本
├── src/                              # 源代码
│   └── uctoo_api_skill.cj           # 极简技能实现
└── backup-v1/                        # V1 版本备份
    └── ...
```

## 快速开始

### 1. 测试 API 连接

```bash
python scripts/test_api.py
```

### 2. 手动测试登录

```bash
python scripts/api_client.py POST "/api/uctoo/auth/login" '{"username":"demo","password":"123456"}'
```

### 3. 使用技能

技能会通过 Agentskills 运行时自动加载，大模型会根据 SKILL.md 中的说明来使用它。

## SKILL.md 结构

SKILL.md 采用渐进式披露（Progressive Disclosure）原则：

### Level 1: YAML Frontmatter
- 快速扫描信息
- 技能名称、描述、元数据
- 允许的工具列表

### Level 2: Markdown 主体
- 详细说明
- API 快速参考
- 使用示例
- 工作流程

### Level 3: 链接的参考文档
- 完整的 API 规范
- 更多使用示例
- 深入的技术文档

## 核心优势

1. **充分利用大模型能力**
   - 语义理解、推理、决策都由大模型完成
   - 能处理各种自然语言变体

2. **极高的灵活性**
   - 不需要硬编码每个 API 的处理逻辑
   - 大模型可以自适应各种用户输入

3. **易于维护**
   - API 变更只需更新文档
   - 不需要修改代码

4. **易于扩展**
   - 新增 API 只需在文档中添加说明
   - 大模型会自动学会使用新 API

5. **符合最佳实践**
   - 完全符合 Agentskills 标准
   - 采用渐进式披露原则

## 自动 Token 管理（V7.0+）

### 概述

从 V7.0 版本开始，系统实现了**会话级自动 Token 管理机制**，彻底解决了大模型在多轮对话中无法正确传递认证 Token 的问题。

### 架构设计

```
┌─────────────────────────────────────────────────────────────┐
│                    WebSocket Session                         │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                 SessionContext                        │    │
│  │  - setCurrentSession(sessionId)                       │    │
│  │  - getAccessToken() → TokenManager.getAccessToken()   │    │
│  └─────────────────────────────────────────────────────┘    │
│                            │                                 │
│                            ▼                                 │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                   TokenManager                        │    │
│  │  - setToken(sessionId, tokenInfo)                     │    │
│  │  - getAccessToken(sessionId)                          │    │
│  │  - parseLoginResponse(response)                       │    │
│  │  - isLoginEndpoint(url)                               │    │
│  └─────────────────────────────────────────────────────┘    │
│                            │                                 │
│                            ▼                                 │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                     HttpTool                          │    │
│  │  1. 检测登录请求 → 自动保存 token                      │    │
│  │  2. 检测非登录请求 → 自动注入 Authorization header     │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
```

### 核心组件

| 组件 | 文件 | 功能 |
|------|------|------|
| TokenInfo | `src/tool/token_manager.cj` | Token 信息封装，包含过期时间检查 |
| TokenManager | `src/tool/token_manager.cj` | Token 存储和管理，支持多会话 |
| SessionContext | `src/tool/token_manager.cj` | 当前会话上下文，线程安全 |
| HttpTool | `src/tool/http_tool.cj` | 自动 token 保存和注入 |

### 工作流程

#### 1. 登录时自动保存 Token

```cangjie
// HttpTool 检测到登录请求
if (tokenManager.isLoginEndpoint(url)) {
    // 解析响应并保存 token
    let tokenInfoOpt = tokenManager.parseLoginResponse(responseJson)
    match (tokenInfoOpt) {
        case Some(tokenInfo) =>
            tokenManager.setToken(sessionId, tokenInfo)
            LogUtils.info("[HttpTool] Auto-saved token for session")
        case None => ()
    }
}
```

#### 2. 后续请求自动注入 Authorization

```cangjie
// HttpTool 检测到非登录请求
if (!hasAuthorization && !tokenManager.isLoginEndpoint(url)) {
    let tokenOpt = sessionContext.getAccessToken()
    match (tokenOpt) {
        case Some(token) =>
            headers.add("Authorization", "Bearer ${token}")
            LogUtils.info("[HttpTool] Auto-injected Authorization header")
        case None => ()
    }
}
```

#### 3. 会话结束时清理

```cangjie
// WebSocket 会话关闭时
tokenManager.removeToken(sessionId)
sessionContext.clearCurrentSession()
```

### 优势

1. **对模型透明**：大模型无需关心 token 管理，只需正常调用 API
2. **可靠性高**：不依赖大模型的记忆能力，避免 token 丢失或格式错误
3. **支持多用户**：每个 WebSocket 会话独立管理 token
4. **自动过期处理**：TokenInfo 包含过期时间，自动检查 token 有效性
5. **线程安全**：使用 Mutex 保护共享状态

### 使用示例

用户只需正常对话，系统自动处理认证：

```
用户: 请使用 demo 账号 123456 登录
助手: 登录成功！用户信息：...

用户: 编辑 id 为 fd0a410a-xxx 的实体，将 link 改为 uctoo.com
助手: 编辑成功！  # 系统自动注入了 Authorization header
```

### 技术细节

- **登录端点检测**：通过 URL 中是否包含 `/auth/login` 或 `/auth/signin` 判断
- **Token 解析**：从 JSON 响应中提取 `access_token`、`refresh_token`、`user.id`、`user.username`
- **默认过期时间**：24 小时（86400000 毫秒）
- **Header 注入格式**：`Authorization: Bearer {token}`

## 工作原理

### 1. 技能激活
当用户提及 "uctoo"、"登录"、"用户管理" 等关键词时，技能会被激活。

### 2. 大模型理解
大模型读取 SKILL.md 中的说明，理解：
- 有哪些 API 可用
- 如何调用这些 API
- 需要什么参数
- 如何处理响应

### 3. 决策与执行
大模型根据用户需求：
1. 选择合适的 API
2. 从用户输入中提取参数
3. 调用 Python 脚本发送 HTTP 请求
4. 解析 API 响应
5. 生成友好的自然语言回复

## 与 V1 的对比

| 特性 | V1 | V2 |
|------|-----|-----|
| 代码量 | 大量（10+ 文件） | 极少（2 个文件） |
| 语义理解 | 硬编码关键词 | 大模型自然语言理解 |
| API 选择 | 固定逻辑 | 大模型动态决策 |
| 参数提取 | 正则表达式 | 大模型智能提取 |
| 可维护性 | 低（需改代码） | 高（只需改文档） |
| 可扩展性 | 低 | 高 |
| 灵活性 | 低 | 极高 |

## 注意事项

1. **Token 管理**
   - 登录成功后，大模型会保存 access_token
   - 后续请求需要使用这个 token

2. **API 格式**
   - 所有 API 都使用 `/api/uctoo/` 前缀
   - POST 请求的请求体必须是有效的 JSON

3. **错误处理**
   - 大模型会自动处理 API 错误
   - 向用户提供友好的错误信息和解决方案

## 下一步

- 测试通过聊天界面使用技能
- 验证登录功能
- 测试基本的 CRUD 操作
- 根据实际使用情况优化 SKILL.md

## 参考资料

- [Agentskills 最佳实践](https://github.com/vercel-labs/agent-skills)
- [UCTOO API 设计规范](../../../../apps/backend/docs/uctooAPI设计规范.md)
- [重构方案文档](./REFACTORING_PLAN_v2.md)


path: README_zh_CN.md
content: # UCToo API Agent Skills

## 概述
本项目实现了Agent Skills，将自然语言请求转换为uctoo-backend服务器API调用。技能遵循agentskills标准规范，允许AI助手使用自然语言与uctoo-backend服务进行交互。

该实现使用CangjieMagic框架的技能系统创建可互操作的agent技能，以连接自然语言查询和后端API功能。

## 架构
系统由以下主要组件组成：

### 1. UctooAPISkill (src/uctoo_api_skill.cj)
- 处理自然语言请求的核心技能
- 将自然语言映射到适当的后端API调用
- 处理身份验证和会话管理
- 返回结构化响应

### 2. 自然语言处理器 (src/natural_language_processor.cj)
- 解析来自AI助手的自然语言请求
- 使用基于关键字的评分识别用户意图
- 使用模式匹配从自然语言中提取参数
- 使用建议机制处理模糊查询

### 3. API映射器 (src/api_mapper.cj)
- 将自然语言意图映射到特定API端点
- 处理自然语言和API格式之间的参数转换
- 管理API端点配置和元数据

### 4. 认证管理器 (src/auth_manager.cj)
- 处理认证令牌管理
- 在API调用之间维护会话状态
- 提供安全凭证处理

### 5. 配置 (src/config.cj)
- 通过环境变量管理系统配置

## 主要功能

### 自然语言处理
- 基于关键字和模式的意图识别，带有评分算法
- 使用正则表达式模式从自然语言查询中提取参数
- 支持常见实体类型（用户、产品、订单）
- 使用建议机制处理模糊请求
- 上下文感知处理

### API集成
- 与uctoo-backend服务器API无缝集成
- 支持标准CRUD操作
- 身份验证和会话管理
- 错误处理和响应格式化

### Agentskills标准兼容性
- 完全符合agentskills标准规范
- 支持SKILL.md文件中的YAML frontmatter
- 支持技能元数据和验证
- 外部资源访问（scripts/, references/, assets/）

### 错误处理
- 为所有系统组件提供全面的错误处理
- 为调试提供详细的错误消息
- 优雅处理API故障和网络问题

## 自动 Token 管理（V7.0+）

### 概述

从 V7.0 版本开始，系统实现了**会话级自动 Token 管理机制**，彻底解决了大模型在多轮对话中无法正确传递认证 Token 的问题。

### 架构设计

```
┌─────────────────────────────────────────────────────────────┐
│                    WebSocket Session                         │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                 SessionContext                        │    │
│  │  - setCurrentSession(sessionId)                       │    │
│  │  - getAccessToken() → TokenManager.getAccessToken()   │    │
│  └─────────────────────────────────────────────────────┘    │
│                            │                                 │
│                            ▼                                 │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                   TokenManager                        │    │
│  │  - setToken(sessionId, tokenInfo)                     │    │
│  │  - getAccessToken(sessionId)                          │    │
│  │  - parseLoginResponse(response)                       │    │
│  │  - isLoginEndpoint(url)                               │    │
│  └─────────────────────────────────────────────────────┘    │
│                            │                                 │
│                            ▼                                 │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                     HttpTool                          │    │
│  │  1. 检测登录请求 → 自动保存 token                      │    │
│  │  2. 检测非登录请求 → 自动注入 Authorization header     │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
```

### 核心组件

| 组件 | 文件 | 功能 |
|------|------|------|
| TokenInfo | `src/tool/token_manager.cj` | Token 信息封装，包含过期时间检查 |
| TokenManager | `src/tool/token_manager.cj` | Token 存储和管理，支持多会话 |
| SessionContext | `src/tool/token_manager.cj` | 当前会话上下文，线程安全 |
| HttpTool | `src/tool/http_tool.cj` | 自动 token 保存和注入 |

### 工作流程

#### 1. 登录时自动保存 Token

```cangjie
// HttpTool 检测到登录请求
if (tokenManager.isLoginEndpoint(url)) {
    // 解析响应并保存 token
    let tokenInfoOpt = tokenManager.parseLoginResponse(responseJson)
    match (tokenInfoOpt) {
        case Some(tokenInfo) =>
            tokenManager.setToken(sessionId, tokenInfo)
            LogUtils.info("[HttpTool] Auto-saved token for session")
        case None => ()
    }
}
```

#### 2. 后续请求自动注入 Authorization

```cangjie
// HttpTool 检测到非登录请求
if (!hasAuthorization && !tokenManager.isLoginEndpoint(url)) {
    let tokenOpt = sessionContext.getAccessToken()
    match (tokenOpt) {
        case Some(token) =>
            headers.add("Authorization", "Bearer ${token}")
            LogUtils.info("[HttpTool] Auto-injected Authorization header")
        case None => ()
    }
}
```

#### 3. 会话结束时清理

```cangjie
// WebSocket 会话关闭时
tokenManager.removeToken(sessionId)
sessionContext.clearCurrentSession()
```

### 优势

1. **对模型透明**：大模型无需关心 token 管理，只需正常调用 API
2. **可靠性高**：不依赖大模型的记忆能力，避免 token 丢失或格式错误
3. **支持多用户**：每个 WebSocket 会话独立管理 token
4. **自动过期处理**：TokenInfo 包含过期时间，自动检查 token 有效性
5. **线程安全**：使用 Mutex 保护共享状态

### 使用示例

用户只需正常对话，系统自动处理认证：

```
用户: 请使用 demo 账号 123456 登录
助手: 登录成功！用户信息：...

用户: 编辑 id 为 fd0a410a-xxx 的实体，将 link 改为 uctoo.com
助手: 编辑成功！  # 系统自动注入了 Authorization header
```

### 技术细节

- **登录端点检测**：通过 URL 中是否包含 `/auth/login` 或 `/auth/signin` 判断
- **Token 解析**：从 JSON 响应中提取 `access_token`、`refresh_token`、`user.id`、`user.username`
- **默认过期时间**：24 小时（86400000 毫秒）
- **Header 注入格式**：`Authorization: Bearer {token}`

## 技能

该实现公开以下agent技能：

### UctooAPISkill
- 处理自然语言查询并将其转换为后端API调用
- 根据意图和参数返回结构化的API响应

## 配置
系统可通过环境变量进行配置：
- `BACKEND_URL` - uctoo-backend服务器的后端URL（默认：http://localhost:3000）
- `DEFAULT_TIMEOUT` - 请求超时（毫秒）（默认：10000）
- `LOG_LEVEL` - 日志级别（默认：INFO）

## 使用示例

### 自然语言查询
- "获取所有用户" → 处理为用户的GET请求
- "查找ID为123的用户" → 处理为带ID参数的GET请求
- "创建名为John的新用户" → 处理为带名称参数的POST请求
- "使用邮箱[REDACTED_SECRET]更新用户456" → 处理为带ID和邮箱参数的PUT请求

## 开发

### 项目结构
```
apps/CangjieMagic/src/examples/uctoo_api_skill/
├── src/
│   ├── main.cj                          # 主入口点和代理定义
│   ├── uctoo_api_skill.cj               # 核心API技能实现
│   ├── natural_language_processor.cj    # NLP处理
│   ├── api_mapper.cj                    # API映射和转换
│   ├── auth_manager.cj                  # 身份验证管理
│   ├── config.cj                        # 配置管理
│   ├── utils.cj                         # 实用函数
│   ├── error_handler.cj                 # 错误处理
│   ├── models/                          # 数据模型
│   │   ├── api_request.cj               # API请求模型
│   │   └── api_response.cj              # API响应模型
│   └── skills/                          # 额外技能实现
│       └── ...
├── resources/
│   └── api_definitions.json             # 用于映射的API定义（计划中）
├── tests/
│   ├── unit/                            # 单元测试（计划中）
│   ├── integration/                     # 集成测试（计划中）
│   └── contract/                        # 合约测试（计划中）
└── SKILL.md                             # 标准技能定义文件
```

### Agent实现

系统实现了AI Agent，使用Magic Framework的@agent注解：

```cangjie
@agent[
  model: "dashscope:qwen3-max-preview",
  description: "UCToo后端API的MCP适配器，支持自然语言查询",
  tools: [processNaturalLanguageRequest, getMcpServiceById, listApiMappings]
]
class UctooMCPAdapterAgent {
  @prompt("您是一个MCP适配器，可以将自然语言请求转换为uctoo-backend服务器的API调用。根据用户的自然语言描述，调用适当的后端服务并返回结果。")
}
```

### 关键实现细节

#### 自然语言处理
系统采用基于关键字的意图确定算法，通过评分从自然语言查询中识别用户意图。多个关键字与不同意图（GET_RESOURCE、CREATE_RESOURCE、UPDATE_RESOURCE、DELETE_RESOURCE等）相关联，评分系统确定最可能的意图。

参数提取使用正则表达式模式识别ID、名称、电子邮件和电话号码等常见实体。

#### API映射
系统包括自动API映射生成器，为以下内容创建MCP适配器：
- 基于数据库模式的标准CRUD操作（确定性算法）
- 通过算法遍历的非标准API

映射包括自然语言模式和转换规则，用于将查询转换为API端点。

## 程序流程

系统当前版本遵循以下正确的程序流程：

### 1. 客户端（uctoo_api_mcp_client）流程
1. **客户端启动**：运行 `cjpm run --name magic.examples.uctoo_api_mcp_client`
2. **发送请求**：
   - 发送"调用hello接口"请求
   - 发送"使用账户demo和密码123456登录"请求
   - 发送"获取ID为3a5a079d-38b2-4ea2-b8cd-f3c0d93dacfb的实体"请求
3. **接收响应**：
   - Hello接口调用成功，返回"Hello World"
   - 登录请求成功，返回用户信息和访问令牌
   - 获取实体请求返回"未找到"信息

### 2. 服务器（uctoo_api_mcp_server）流程
1. **接收MCP协议请求**：通过MCP协议接收客户端请求
2. **请求分发处理**：
   - 对于hello接口请求：直接返回"Hello World"
   - 对于登录请求：通过AI代理（UctooMCPAdapterAgent）处理
   - 对于实体请求：通过AI代理处理
3. **详细登录处理流程**：
   - AI代理识别登录意图
   - 调用`processNaturalLanguageRequest`工具
   - `NaturalLanguageProcessor`处理登录请求
   - 调用`callLoginApiDirectly`方法直接调用后端登录API
   - 使用`Utils.extractTokenFromResponse`方法从JSON响应中解析access_token
   - 成功提取并存储access_token以供后续API调用

### 3. 关键技术实现
1. **统一的access_token解析**：
   - 所有access_token解析使用`Utils.extractTokenFromResponse`公共方法
   - 该方法首先尝试JSON解析，失败时回退到正则表达式解析
   - 成功解析的令牌存储在`UctooMCPAdapter`中以供后续API调用
2. **日志系统重构**：
   - 所有`Utils.logMessage`调用现在写入日志文件
   - 与`main.cj`中的`logToFile`函数保持一致的日志记录方法
   - 提供完整的调试信息跟踪

### 4. 问题解决
**之前程序流程异常的原因**：
- 旧版本的日志系统存在JSON解析错误bug
- `Utils.logMessage`方法仅输出到控制台，无法记录调试信息
- 使得追踪和调试JSON解析问题变得困难

**修复后效果**：
- 所有日志现在写入文件，便于调试
- JSON解析功能正常工作，能够正确从登录响应中提取access_token
- 登录流程顺利完成，返回完整的用户信息和访问令牌
- 整个MCP适配器流程按预期工作

## 部署
适配器可使用标准Cangjie部署实践进行部署：
1. 配置后端服务URL和其他设置的环境变量
2. 使用`cjpm build`构建项目
3. 运行编译的二进制文件
4. 监控日志以了解运行状况

系统设计为与Magic Framework的MCP服务器基础架构配合使用，可与支持Model Context Protocol的AI助手集成。

## 🧰 如何运行

1. 部署 https://gitee.com/UCT/uctoo-backend 开发框架服务端应用程序

2. **配置API密钥**：在uctoo_api_mcp_client项目的`main.cj`文件中，将`<your api key>`替换为您的DeepSeek API密钥。修改config.cj中的配置参数以匹配步骤1中uctoo_backend的部署参数。
   ```cangjie
   Config.env["DEEPSEEK_API_KEY"] = "sk-xxxxxxxxxx";
   ```

您需要打开两个终端窗口：

3. **启动服务器**：在第一个终端中，在CangjieMagic目录中运行以下命令以启动MCP服务。
   ```bash
   cjpm run --name magic.examples.uctoo_api_mcp_server
   ```
   
   **为什么要运行 uctoo_api_mcp_server 服务**：
   
   `uctoo_api_skill` 项目是基于 Agent Skills 标准的技能实现，它与 `uctoo_api_mcp_server` 项目共同构成了完整的MCP（Model Context Protocol）适配器功能。尽管 `uctoo_api_skill` 项目专注于将自然语言请求转换为后端API调用的技能实现，但仍然需要一个MCP服务器来处理AI助手客户端的连接和通信。
   
   `uctoo_api_mcp_server` 项目提供了以下关键功能：
   - MCP协议服务：处理AI助手客户端的连接和通信协议
   - Agent服务：提供AI助手可以调用的工具集
   - 请求路由：将AI助手的自然语言请求转发给相应的技能处理器
   - 响应处理：将技能执行结果格式化后返回给AI助手
   
   因此，尽管 `uctoo_api_skill` 是技能的核心实现，但仍需要 `uctoo_api_mcp_server` 作为通信桥梁，使AI助手能够通过MCP协议与技能进行交互。
   
4. **启动客户端**：在第二个终端中，在CangjieMagic目录中运行以下命令以启动客户端并与其交互。
   ```bash
   cjpm run --name magic.examples.uctoo_api_mcp_client
   ```

## 详细运行流程

### 与 uctooAPI 设计规范的兼容性

`uctoo_api_skill` 项目完全符合 `apps\backend\docs\uctooAPI设计规范.md` 中定义的 API 设计规范：

1. **HTTP 方法使用**：严格按照规范仅使用 GET 和 POST 方法，不使用 PUT、DELETE 等其他方法
   - GET 请求用于数据查询操作
   - POST 请求用于创建、更新和删除操作

2. **端点命名规范**：
   - 查询单条数据：`/api/uctoo/entity/{id}` (GET)
   - 查询多条数据：`/api/uctoo/entity/:limit/:page` (GET)
   - 创建数据：`/api/uctoo/entity/add` (POST)
   - 更新数据：`/api/uctoo/entity/edit` (POST)
   - 删除数据：`/api/uctoo/entity/del` (POST)

3. **其他实体类型也遵循相同规范**：
   - 附件管理：`/api/uctoo/attachments/*`
   - CMS 文章：`/api/uctoo/cms_articles/*`
   - 用户管理：`/api/uctoo/uctoo_user/*`

4. **认证机制**：使用 JWT 进行接口权限验证，通过 `/api/uctoo/auth/login` 获取动态 token

### 1. 初始化阶段

1. **环境检查**：系统检查必需的环境变量，如 `BACKEND_URL` 和 `DEEPSEEK_API_KEY`
2. **组件初始化**：初始化以下核心组件：
   - `UctooAPISkill`：主要技能处理器
   - `NaturalLanguageProcessor`：自然语言处理器
   - `ApiMapper`：API映射器
   - `AuthManager`：认证管理器
3. **配置加载**：从以下路径加载系统配置：
   - 配置文件路径：`src/config.cj`
   - 加载的配置项包括：
     - `BACKEND_URL`：uctoo-backend服务器的后端URL（默认：http://localhost:3000）
     - `DEFAULT_TIMEOUT`：请求超时（毫秒）（默认：10000）
     - `LOG_LEVEL`：日志级别（默认：INFO）
     - `API_KEY`：用于API调用的访问密钥（如果提供）

### 2. 客户端-服务器交互流程

1. **客户端启动**：`apps\CangjieMagic\src\examples\uctoo_api_mcp_client` 启动，创建 `EnhancedUctooMCPTestAgent`
2. **MCP连接建立**：客户端通过 `stdioMCP("cjpm run --skip-build --name magic.examples.uctoo_api_mcp_server")` 命令与服务器建立MCP协议连接
3. **自然语言请求发送**：客户端将用户输入的自然语言请求（如"调用hello接口"、"请使用账号demo和密码123456登录"等）发送到服务器

### 3. 服务器端请求处理流程

1. **请求接收**：`apps\CangjieMagic\src\examples\uctoo_api_mcp_server` 接收来自客户端的自然语言请求
2. **AI处理**：服务器端的 `UctooMCPAdapterAgent` 使用AI模型处理请求
3. **工具调用**：服务器调用 `processNaturalLanguageRequest` 工具函数
4. **技能执行**：在 `processNaturalLanguageRequest` 函数内部，`NaturalLanguageProcessor` 调用 `UctooAPISkill` 的 `execute` 方法
5. **意图识别**：`UctooAPISkill` 中的 `NaturalLanguageProcessor` 使用基于关键字的评分算法识别用户意图
6. **参数提取**：使用正则表达式模式从自然语言中提取参数
7. **API映射**：`ApiMapper` 将自然语言意图映射到特定的API端点
8. **认证检查**：`AuthManager` 检查当前会话的认证状态
9. **API调用**：执行相应的后端API调用
10. **响应处理**：将API响应处理后返回给客户端

### 4. 技能执行细节

`apps\CangjieMagic\src\examples\uctoo_api_skill` 项目中的 `UctooAPISkill` 负责：
- **自然语言到API的映射**：`NaturalLanguageProcessor` 负责解析自然语言请求并识别用户意图
- **API映射**：`ApiMapper` 将识别的意图转换为具体的API端点和参数
- **认证管理**：`AuthManager` 管理认证令牌和会话状态
- **请求执行**：协调整个请求处理流程

`apps\CangjieMagic\src\examples\uctoo_api_mcp_server` 项目负责：
- **MCP协议处理**：处理客户端与服务器之间的通信协议
- **AI代理**：提供AI能力来理解用户请求
- **工具调度**：调用适当的工具函数（如 `processNaturalLanguageRequest`）
- **响应格式化**：将结果格式化为适合客户端的响应

**框架增强支持**：

`apps\CangjieMagic\src\examples\uctoo_api_mcp_server` 能够调用 `apps\CangjieMagic\src\examples\uctoo_api_skill` 的技能，是通过 `specs\003-agentskills-enhancement` 项目对 CangjieMagic 框架的增强支持实现的。这个增强项目实现了对 agentskills 标准的全面支持，包括：

- **SKILL.md 文件加载**：框架现在可以加载和解析标准的 SKILL.md 文件
- **技能验证**：对技能进行验证以确保符合 agentskills 规范
- **外部资源访问**：允许技能访问 scripts/、references/、assets/ 等外部资源
- **技能执行**：通过标准化的接口执行技能

因此，`uctoo_api_mcp_server` 中的 `processNaturalLanguageRequest` 函数能够调用 `uctoo_api_skill` 中的 `UctooAPISkill` 实例，因为框架增强了对技能的动态加载和执行能力。这使得 `uctoo_api_mcp_server` 可以优先使用 `uctoo_api_skill` 中定义的自然语言处理逻辑，而不是使用 `uctoo_api_mcp_server` 中原有的处理流程，从而实现了技能的模块化和可扩展性。

### 5. 认证处理流程

1. **初始检查**：当收到需要认证的请求时，检查当前会话是否已认证
2. **认证令牌提取**：如果用户提供了认证信息（用户名/密码或API密钥），提取并验证
3. **令牌存储**：成功认证后，将令牌存储在 `AuthManager` 中供后续请求使用
4. **令牌刷新**：如果令牌即将过期，自动刷新令牌

### 6. 错误处理流程

1. **输入验证**：验证请求参数的格式和完整性
2. **API调用错误**：捕获并处理后端API调用错误
3. **认证错误**：处理认证失败和令牌过期情况
4. **响应格式化**：将错误信息格式化为对AI助手友好的格式

### 7. 结束阶段

1. **资源清理**：释放占用的资源，如网络连接和缓存
2. **会话终止**：如果需要，终止当前会话并清理认证令牌
3. **日志记录**：记录操作日志和性能指标

### 8. 特殊场景处理

- **模糊查询**：当自然语言请求不够明确时，系统使用建议机制提示用户提供更多信息
- **批量操作**：处理需要多个API调用的复杂请求
- **并发请求**：管理多个并发的API请求，确保响应顺序正确
- **超时处理**：对长时间运行的API调用实施超时控制

这些流程确保了UCToo API Agent Skills能够高效、可靠地处理自然语言请求，并将其转换为相应的后端API调用。

## API调用发起方分析

基于我们对系统架构和日志的分析，我们确定了以下关于API调用发起的信息：

### API调用发起方

- **`apps\CangjieMagic\src\examples\uctoo_api_mcp_server`** 负责向uctoo后端API发起实际的HTTP请求。
- **`apps\CangjieMagic\src\examples\uctoo_api_skill`** 负责将自然语言请求转换为API调用规范，但不直接发起HTTP请求。

### 技术依据

此架构是由于CangjieMagic框架的agentskills增强机制而实现的。`uctoo_api_mcp_server` 通过来自 `specs\003-agentskills-enhancement` 项目对CangjieMagic框架的增强支持来访问 `uctoo_api_skill` 中的技能。此增强项目为agentskills标准实现全面支持，包括：

- **SKILL.md文件加载**：框架现在可以加载和解析标准的SKILL.md文件
- **技能验证**：验证技能以确保符合agentskills规范
- **外部资源访问**：允许技能访问scripts/、references/、assets/等外部资源
- **技能执行**：通过标准化接口执行技能

因此，`uctoo_api_mcp_server` 中的 `processNaturalLanguageRequest` 函数能够调用 `uctoo_api_skill` 中的 `UctooAPISkill` 实例。框架增强了对技能的动态加载和执行能力。这使得 `uctoo_api_mcp_server` 可以优先使用 `uctoo_api_skill` 中定义的自然语言处理逻辑，而不是使用 `uctoo_api_mcp_server` 中原有的处理流程，从而实现了技能的模块化和可扩展性。

### 责任分工

- **`uctoo_api_skill` 的责任**：
  - 自然语言理解和意图识别
  - 从自然语言查询中提取参数
  - 基于识别的意图进行API端点映射
  - 认证令牌管理
  - 定义自然语言如何映射到API调用

- **`uctoo_api_mcp_server` 的责任**：
  - 与客户端的MCP协议通信
  - 接收请求并路由到适当的技能
  - 向后端API执行实际的HTTP请求
  - 处理和格式化API响应以供客户端使用
  - 管理认证会话

这种关注点分离实现了更好的模块化：`uctoo_api_skill` 专注于理解自然语言和定义API映射，而 `uctoo_api_mcp_server` 处理实际的网络通信和协议管理。

path: REFACTORING_PLAN.md
content: # uctoo_api_skill 重构方案

**文档版本**: 2.0  
**创建日期**: 2026-02-27  
**状态**: 设计中

---

## 一、重构目标

### 1.1 核心目标
将 `uctoo_api_skill` 从当前依赖 `uctoo_api_mcp_server` 的架构重构为**完全独立、自包含的 Agent Skill**，只需依赖 `agentskills-runtime` 即可运行，无需依赖其他 MCP 服务器或技能。

### 1.2 具体目标
- ✅ **完全独立运行**：无需 MCP 服务器，直接在 agentskills-runtime 中执行
- ✅ **符合官方最佳实践**：遵循 Claude 官方技能创建指南
- ✅ **集成门控系统**：利用门控系统检测执行环境能力
- ✅ **多脚本语言支持**：超越标准，支持 JavaScript、Cangjie 等多种脚本
- ✅ **渐进式披露设计**：遵循三层加载模式，优化上下文使用

---

## 二、当前架构分析

### 2.1 当前依赖关系
```
uctoo_api_skill (技能实现)
    ↓ 依赖
uctoo_api_mcp_server (MCP协议处理)
    ↓ 依赖
CangjieMagic框架 + agentskills增强
    ↓ 依赖
agentskills-runtime (运行时内核)
```

### 2.2 当前职责分工
| 组件 | 职责 | 问题 |
|------|------|------|
| `uctoo_api_skill` | 自然语言理解、API映射、认证管理 | 不直接发起HTTP请求 |
| `uctoo_api_mcp_server` | MCP协议通信、实际HTTP请求、响应格式化 | 与技能逻辑耦合 |

### 2.3 存在的问题
1. **依赖关系复杂**：需要同时运行两个项目
2. **职责不清**：HTTP请求逻辑分散在两个组件中
3. **不符合技能标准**：没有遵循官方的技能目录结构
4. **无法独立分发**：技能无法作为独立包发布和使用

---

## 三、重构后的架构设计

### 3.1 目标架构
```
uctoo_api_skill (完全独立的技能包)
    ↓ 直接依赖
agentskills-runtime (运行时内核 + 门控系统)
    ↓ 使用
大模型 API + 后端 API
```

### 3.2 技能目录结构（符合官方标准）
```
uctoo_api_skill/
├── SKILL.md                          # 必需：技能主文件（YAML frontmatter + Markdown）
├── scripts/                          # 可选：可执行脚本
│   ├── api_client.cj                # Cangjie语言的API客户端
│   ├── api_client.js                # JavaScript语言的API客户端（备选）
│   └── utils.cj                     # 通用工具函数
├── references/                       # 可选：参考文档
│   ├── api_spec.md                  # API规范文档
│   ├── uctoo_api_design.md          # uctoo API设计规范
│   └── examples.md                  # 使用示例
└── assets/                           # 可选：输出资源（如模板）
    └── response_template.json       # 响应模板
```

### 3.3 核心组件设计

#### 3.3.1 重构后的SKILL.md
**位置**: `SKILL.md`  
**设计原则**:
- 精简到500行以内
- 只包含核心指令
- 详细文档移至 `references/`
- 使用渐进式披露

```yaml
---
name: uctoo-api-skill
description: 完整的uctoo后端API集成技能。将自然语言请求转换为uctoo-backend API调用，支持用户管理、产品管理、订单管理等功能。使用时用户提及"uctoo"、"后端API"、"用户管理"、"产品"、"订单"等关键词。
license: MIT
compatibility:
  os:
    - Windows
    - Linux
    - macOS
  requires:
    - binary: cjpm
    - environment: BACKEND_URL
    - file: scripts/api_client.cj
metadata:
  author: UCToo Team
  version: "2.0.0"
  category: api-connector
  domain: backend-integration
---

# Uctoo API Skill

## 快速开始

### 基本用法
直接向我描述你想做什么，我会自动调用相应的API。

**示例:**
- "获取所有用户"
- "创建一个名为张三的新用户"
- "查找ID为123的产品"
- "删除订单456"

### 认证
首次使用前需要登录：
> "使用账号demo和密码123456登录"

## 核心功能

### 1. 用户管理
- 查询用户（单个/列表）
- 创建用户
- 更新用户信息
- 删除用户

### 2. 产品管理
- 查询产品
- 创建产品
- 更新产品
- 删除产品

### 3. 订单管理
- 查询订单
- 创建订单
- 更新订单状态
- 删除订单

### 4. 认证
- 用户登录
- Token管理
- 会话保持

## 详细文档

更多详细信息请参考：
- [API规范](references/api_spec.md) - 完整的API端点文档
- [使用示例](references/examples.md) - 丰富的使用场景示例
- [uctoo设计规范](references/uctoo_api_design.md) - API设计原则

## 执行流程

当你提出请求时，我会：
1. 理解你的自然语言需求
2. 识别意图（GET/CREATE/UPDATE/DELETE）
3. 提取必要参数
4. 使用 `scripts/api_client.cj` 执行API调用
5. 返回格式化的结果

## 错误处理

如果遇到问题：
- 认证失败：请先使用"登录"指令
- API错误：我会提供详细的错误信息
- 参数缺失：我会询问你补充必要信息
```

#### 3.3.2 API客户端（Cangjie实现）
**位置**: `scripts/api_client.cj`  
**职责**: 直接发起HTTP请求，处理认证

```cangjie
package scripts

import std.net.http.{HttpClient, HttpRequest, HttpResponse}
import stdx.encoding.json.{JsonValue, JsonObject}
import std.collection.HashMap

public class UctooApiClient {
    private var _backendUrl: String
    private var _authToken: Option<String> = None()
    private let _httpClient: HttpClient
    
    public init(backendUrl: String) {
        _backendUrl = backendUrl
        _httpClient = HttpClient()
    }
    
    public func setAuthToken([REDACTED_SECRET]): Unit {
        _authToken = Some(token)
    }
    
    public func login(username: String, [REDACTED_SECRET]): Result<String, String> {
        let request = HttpRequest.post("${_backendUrl}/api/uctoo/auth/login")
            .header("Content-Type", "application/json")
            .body(JsonObject()
                .set("username", username)
                .set("password", password)
                .toJson())
        
        let response = _httpClient.send(request)
        if response.statusCode != 200 {
            return Result.Error("Login failed: ${response.statusCode}")
        }
        
        let json = response.bodyAsJson()
        let token = json["access_token"]?.asString()
        if let t = token {
            _authToken = Some(t)
            return Result.Ok(t)
        }
        return Result.Error("No token in response")
    }
    
    public func getEntity(entityType: String, id: String): Result<JsonValue, String> {
        return _executeGet("/api/uctoo/${entityType}/${id}")
    }
    
    public func getEntities(entityType: String, limit: Int = 10, page: Int = 1): Result<JsonValue, String> {
        return _executeGet("/api/uctoo/${entityType}/${limit}/${page}")
    }
    
    public func createEntity(entityType: String, data: JsonObject): Result<JsonValue, String> {
        return _executePost("/api/uctoo/${entityType}/add", data)
    }
    
    public func updateEntity(entityType: String, data: JsonObject): Result<JsonValue, String> {
        return _executePost("/api/uctoo/${entityType}/edit", data)
    }
    
    public func deleteEntity(entityType: String, id: String): Result<JsonValue, String> {
        return _executePost("/api/uctoo/${entityType}/del", JsonObject().set("id", id))
    }
    
    private func _executeGet(path: String): Result<JsonValue, String> {
        var request = HttpRequest.get("${_backendUrl}${path}")
        
        if let [REDACTED_SECRET] {
            request = request.header("Authorization", "Bearer ${token}")
        }
        
        let response = _httpClient.send(request)
        return _handleResponse(response)
    }
    
    private func _executePost(path: String, data: JsonObject): Result<JsonValue, String> {
        var request = HttpRequest.post("${_backendUrl}${path}")
            .header("Content-Type", "application/json")
            .body(data.toJson())
        
        if let [REDACTED_SECRET] {
            request = request.header("Authorization", "Bearer ${token}")
        }
        
        let response = _httpClient.send(request)
        return _handleResponse(response)
    }
    
    private func _handleResponse(response: HttpResponse): Result<JsonValue, String> {
        if response.statusCode >= 200 && response.statusCode < 300 {
            return Result.Ok(response.bodyAsJson())
        }
        return Result.Error("API Error: ${response.statusCode} - ${response.bodyAsString()}")
    }
}
```

#### 3.3.3 参考文档
**位置**: `references/api_spec.md`

```markdown
# Uctoo API 规范

## 端点列表

### 用户管理 (uctoo_user)
- `GET /api/uctoo/uctoo_user/{id}` - 获取单个用户
- `GET /api/uctoo/uctoo_user/{limit}/{page}` - 获取用户列表
- `POST /api/uctoo/uctoo_user/add` - 创建用户
- `POST /api/uctoo/uctoo_user/edit` - 更新用户
- `POST /api/uctoo/uctoo_user/del` - 删除用户

### 产品管理 (product)
- `GET /api/uctoo/product/{id}` - 获取单个产品
- `GET /api/uctoo/product/{limit}/{page}` - 获取产品列表
- `POST /api/uctoo/product/add` - 创建产品
- `POST /api/uctoo/product/edit` - 更新产品
- `POST /api/uctoo/product/del` - 删除产品

### 订单管理 (order)
- `GET /api/uctoo/order/{id}` - 获取单个订单
- `GET /api/uctoo/order/{limit}/{page}` - 获取订单列表
- `POST /api/uctoo/order/add` - 创建订单
- `POST /api/uctoo/order/edit` - 更新订单
- `POST /api/uctoo/order/del` - 删除订单

### 认证
- `POST /api/uctoo/auth/login` - 用户登录

## 请求/响应格式

详细的JSON schema请参考 [uctooAPI设计规范.md](../../../../backend/docs/uctooAPI设计规范.md)
```

---

## 四、门控系统集成

### 4.1 门控规则定义
在 `SKILL.md` 的 `compatibility.requires` 中定义执行需求：

```yaml
compatibility:
  os:
    - Windows
    - Linux
    - macOS
  requires:
    # 检查Cangjie环境
    - binary: cjpm
    - binary: cangjie
    
    # 检查环境变量
    - environment: BACKEND_URL
    
    # 检查必需文件
    - file: scripts/api_client.cj
    
    # 自定义检查（通过脚本）
    - custom: scripts/check_dependencies.cj
```

### 4.2 门控检查流程
```
技能加载
    ↓
门控系统检查
    ├─ 检查操作系统兼容性
    ├─ 检查二进制文件存在性 (cjpm, cangjie)
    ├─ 检查环境变量 (BACKEND_URL)
    ├─ 检查脚本文件存在
    └─ 执行自定义检查脚本
    ↓
通过 → 技能可用
失败 → 技能禁用，显示原因
```

### 4.3 多脚本语言支持
通过门控系统，技能可以支持多种语言的脚本：

```
scripts/
├── api_client.cj          # 首选：Cangjie实现
├── api_client.js          # 备选：JavaScript实现
└── api_client.py          # 备选：Python实现
```

门控系统会自动检测可用的语言，并选择最优的实现。

---

## 五、渐进式披露实现

### 5.1 三层加载模式
| 层级 | 内容 | 加载时机 | Token消耗 |
|------|------|----------|-----------|
| Level 1 | YAML frontmatter (name, description) | 始终加载 | ~100 tokens |
| Level 2 | SKILL.md 主体 | 技能触发时加载 | <5000 tokens |
| Level 3 | references/, scripts/ | 按需加载 | 无限 |

### 5.2 实现要点
1. **SKILL.md 保持精简**：<500行
2. **详细内容移至 references/**：API文档、示例等
3. **明确的引用链接**：在 SKILL.md 中指明何时使用哪个参考文件
4. **脚本按需执行**：scripts/ 中的代码可以被执行而无需全部读入上下文

---

## 六、实施计划

### 阶段一：架构重构（1-2天）
**任务**:
1. [ ] 创建新的目录结构
2. [ ] 重构 SKILL.md 符合官方标准
3. [ ] 提取参考文档到 references/
4. [ ] 创建独立的 API 客户端脚本

**交付物**:
- 新的目录结构
- 重构后的 SKILL.md
- references/ 目录下的文档
- scripts/api_client.cj

### 阶段二：门控系统集成（1天）
**任务**:
1. [ ] 在 SKILL.md 中定义 requires 规则
2. [ ] 创建依赖检查脚本
3. [ ] 测试门控检查流程
4. [ ] 添加多语言脚本支持

**交付物**:
- 完整的 compatibility 配置
- 依赖检查脚本
- 多语言脚本实现

### 阶段三：测试验证（1天）
**任务**:
1. [ ] 单元测试 API 客户端
2. [ ] 集成测试完整流程
3. [ ] 测试门控系统
4. [ ] 验证独立运行能力

**交付物**:
- 测试用例
- 测试报告
- 验证文档

### 阶段四：文档完善（0.5天）
**任务**:
1. [ ] 更新 README.md
2. [ ] 创建部署指南
3. [ ] 编写使用示例
4. [ ] 更新 DEPLOYMENT.md

**交付物**:
- 完整的文档
- 使用示例
- 部署指南

---

## 七、关键技术决策

### 7.1 HTTP客户端实现
**决策**: 使用Cangjie标准库的 `std.net.http.HttpClient`  
**理由**:
- 无需外部依赖
- 与运行时内核语言一致
- 性能最优

**备选方案**:
- JavaScript实现（通过Node.js）
- Python实现（通过Python解释器）

### 7.2 认证管理
**决策**: 在脚本层管理token  
**理由**:
- 符合技能自包含原则
- 无需外部状态存储
- 简化架构

### 7.3 错误处理
**决策**: 提供结构化的错误信息  
**理由**:
- 便于AI理解和处理
- 提供可操作的反馈
- 支持重试逻辑

---

## 八、与官方最佳实践对比

| 特性 | Claude官方要求 | 当前状态 | 重构后目标 |
|------|---------------|---------|-----------|
| SKILL.md 存在 | ✅ 必需 | ✅ 已有 | ✅ 保持 |
| YAML frontmatter | ✅ 必需 | ✅ 已有 | ✅ 增强 |
| 渐进式披露 | ✅ 推荐 | ❌ 未实现 | ✅ 实现 |
| scripts/ 目录 | ✅ 可选 | ❌ 缺失 | ✅ 添加 |
| references/ 目录 | ✅ 可选 | ❌ 缺失 | ✅ 添加 |
| assets/ 目录 | ✅ 可选 | ❌ 缺失 | ✅ 添加 |
| 无 README.md | ✅ 要求 | ❌ 存在 | ⚠️ 移至外部 |
| 精简SKILL.md | ✅ <500行 | ❌ 过大 | ✅ 重构 |
| 门控系统 | ❌ 无标准 | ❌ 缺失 | ✅ 超越标准 |
| 多语言支持 | ❌ 仅Python | ❌ 仅Cangjie | ✅ 多语言 |

---

## 九、风险与缓解

### 9.1 技术风险
| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|---------|
| Cangjie HTTP客户端不完善 | 高 | 中 | 准备JavaScript备选实现 |
| 门控系统集成复杂 | 中 | 低 | 分阶段实现，先基础后高级 |
| 向后兼容问题 | 中 | 中 | 保留旧接口，提供迁移指南 |

### 9.2 运维风险
| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|---------|
| 环境配置复杂 | 中 | 低 | 提供.env示例，详细文档 |
| 部署步骤增加 | 低 | 中 | 自动化部署脚本 |

---

## 十、成功标准

### 10.1 功能标准
- [ ] 技能可以独立运行，无需 MCP 服务器
- [ ] 所有现有功能（用户、产品、订单管理）正常工作
- [ ] 认证流程完整
- [ ] 门控系统正确检测环境
- [ ] 支持至少两种脚本语言（Cangjie + JavaScript）

### 10.2 质量标准
- [ ] SKILL.md < 500行
- [ ] 完整的单元测试覆盖
- [ ] 集成测试通过
- [ ] 文档完整准确

### 10.3 性能标准
- [ ] API响应时间 < 2秒
- [ ] 技能加载时间 < 1秒
- [ ] 内存占用合理

---

## 附录

### A. 参考资料
- [Claude官方技能创建指南](../../../agentskills/docs/The-Complete-Guide-to-Building-Skill-for-Claude.md)
- [skill-creator 官方示例](../../skills/skill-creator/SKILL.md)
- [uctoo API设计规范](../../../../backend/docs/uctooAPI设计规范.md)
- [门控系统设计文档](../../../specs/004-agent-skill-runtime/skill_execution_design.md)

### B. 相关文件
- 当前实现: `src/`
- 当前文档: `README_zh_CN.md`, `DEPLOYMENT.md`
- 目标结构: 见本方案第3.2节


path: REFACTORING_PLAN_v2.md
content: # UCTOO API Skill 重构方案

## 概述

本文档描述了对 `uctoo-api-skill` 的完全重构方案，采用 Agentskills 最佳实践，真正发挥大模型的语义理解和推理能力。

## 重构核心理念

### 当前问题
1. **硬编码关键词提取**：使用固定程序提取用户名、密码等参数，脆弱且容易出错
2. **固定的 API 调用逻辑**：无法灵活应对用户的自然语言需求
3. **缺乏语义理解**：没有充分利用大模型的优势

### 重构方向
1. **大模型驱动**：将语义理解、参数提取、API 选择等任务完全交给大模型
2. **极简架构**：只提供必要的工具和 API 规范说明
3. **渐进式披露**：遵循 Agentskills 的三级披露原则
4. **知识层 + 连接层分离**：SKILL.md 作为知识层，HTTP 工具作为连接层

## 技术架构

### 架构图

```
┌─────────────────────────────────────────────────────────┐
│                     用户输入                              │
│         "请使用 demo 账号 123456 登录"                  │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│              大模型（知识层 + 推理）                     │
│  ┌───────────────────────────────────────────────────┐  │
│  │ 1. 理解用户意图：需要登录                          │  │
│  │ 2. 识别参数：username=demo, [REDACTED_SECRET]      │  │
│  │ 3. 选择 API：POST /api/uctoo/auth/login           │  │
│  │ 4. 组装请求体：{"username":"demo","password":"123456"}│  │
│  │ 5. 调用 HTTP 工具执行请求                          │  │
│  │ 6. 解析响应并生成友好回复                          │  │
│  └───────────────────────────────────────────────────┘  │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│                 HTTP 工具（连接层）                      │
│              执行实际的 API 请求                        │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│                 UCTOO 后端 API                          │
└─────────────────────────────────────────────────────────┘
```

## 技能文件结构

```
uctoo-api-skill/
├── SKILL.md                          # 主技能文件（知识层）
├── references/
│   ├── api-spec.md                   # API 完整规范
│   ├── authentication-guide.md       # 认证指南
│   └── examples.md                   # 使用示例
└── src/
    └── uctoo_api_skill.cj            # 极简实现（仅提供 HTTP 工具）
```

## SKILL.md 设计

### YAML Frontmatter（第一级披露）

```yaml
---
name: uctoo-api-skill
description: 完整的 uctoo 后端 API 集成技能。将自然语言请求转换为 uctoo-backend API 调用，支持用户管理、产品管理、订单管理、登录认证等功能。使用时用户提及 "uctoo"、"后端API"、"用户管理"、"产品"、"订单"、"登录"、"认证" 等关键词。
license: MIT
compatibility: 需要网络访问 uctoo 后端 API
metadata:
  author: UCToo Team
  version: "2.0.0"
  category: api-integration
allowedTools: Bash(python:*)
---
```

### 主体内容（第二级披露）

```markdown
# UCTOO API Skill

## 概述

本技能帮助您通过自然语言与 uctoo 后端 API 进行交互。您只需用普通语言描述您的需求，我会自动理解并调用相应的 API。

## 可用工具

### HTTP 请求工具

使用以下 Python 脚本发送 HTTP 请求到 uctoo 后端：

```python
import requests
import json
import sys

BACKEND_URL = "https://javatoarktsapi.uctoo.com"

def make_request(method, endpoint, data=None, token=None):
    url = f"{BACKEND_URL}{endpoint}"
    headers = {"Content-Type": "application/json"}
    
    if [REDACTED_SECRET]"Authorization"] = f"Bearer {token}"
    
    try:
        if method.upper() == "GET":
            response = requests.get(url, headers=headers, params=data)
        elif method.upper() == "POST":
            response = requests.post(url, headers=headers, json=data)
        else:
            return json.dumps({"error": f"Unsupported method: {method}"})
        
        return response.text
    except Exception as e:
        return json.dumps({"error": str(e)})

if __name__ == "__main__":
    if len(sys.argv) < 3:
        print(json.dumps({"error": "Usage: python api_client.py <method> <endpoint> [data_json] [token]"}))
        sys.exit(1)
    
    method = sys.argv[1]
    endpoint = sys.argv[2]
    data = json.loads(sys.argv[3]) if len(sys.argv) > 3 else None
    [REDACTED_SECRET] if len(sys.argv) > 4 else None
    
    result = make_request(method, endpoint, data, token)
    print(result)
```

**使用方式：**
```bash
python scripts/api_client.py <method> <endpoint> [data_json] [token]
```

## API 快速参考

### 认证相关

| 功能 | 方法 | 端点 | 请求体 | 需要认证 |
|------|------|------|--------|----------|
| 登录 | POST | `/api/uctoo/auth/login` | `{"username":"...","password":"..."}` | 否 |
| 退出登录 | POST | `/api/uctoo/auth/logout` | - | 是 |

### 标准 CRUD 操作（以 entity 表为例）

| 操作 | 方法 | 端点 | 需要认证 |
|------|------|------|----------|
| 新增 | POST | `/api/uctoo/entity/add` | 是 |
| 更新 | POST | `/api/uctoo/entity/edit` | 是 |
| 删除 | POST | `/api/uctoo/entity/del` | 是 |
| 查询单条 | GET | `/api/uctoo/entity/:id` | 是 |
| 查询多条 | GET | `/api/uctoo/entity/:limit/:page` | 是 |

**注意：** 将 `/uctoo/entity` 替换为实际的数据库名和表名，如 `/uctoo/user`、`/uctoo/product` 等。

## 工作流程

### 1. 理解用户需求
仔细阅读用户的自然语言请求，理解他们想要做什么。

### 2. 确定是否需要认证
- 如果是登录、注册等操作，不需要 token
- 如果是其他操作，需要先登录获取 token

### 3. 选择合适的 API
根据用户需求选择对应的 API 端点和 HTTP 方法。

### 4. 组装请求参数
从用户请求中提取必要的参数，构建 JSON 请求体。

### 5. 执行 HTTP 请求
使用提供的 Python 脚本发送请求。

### 6. 解析并回复用户
解析 API 响应，用友好的自然语言向用户说明结果。

## 使用示例

### 示例 1：用户登录

**用户请求：**
```
请使用 demo 账号 123456 登录
```

**执行步骤：**
1. 理解用户需要登录
2. 提取参数：username=demo, [REDACTED_SECRET]
3. 调用登录 API：
```bash
python scripts/api_client.py POST "/api/uctoo/auth/login" '{"username":"demo","password":"123456"}'
```
4. 解析响应，保存 token 供后续使用
5. 向用户确认登录成功

### 示例 2：查询用户列表

**用户请求：**
```
列出所有用户
```

**执行步骤：**
1. 理解用户需要查询用户列表
2. 确认已有有效的 token
3. 调用查询 API：
```bash
python scripts/api_client.py GET "/api/uctoo/user/10/0" "" "your_token_here"
```
4. 解析响应，向用户展示用户列表

## 错误处理

如果 API 返回错误：
1. 向用户清晰地说明错误信息
2. 提供可能的解决方案
3. 如果需要，建议用户重新登录或检查参数

## 参考文档

如需更详细的 API 规范，请参考：
- `references/api-spec.md` - 完整的 API 规范文档
- `references/authentication-guide.md` - 认证详细指南
- `references/examples.md` - 更多使用示例
```

## 极简实现（src/uctoo_api_skill.cj）

```cangjie
package uctoo_api_skill

import std.collection.HashMap
import std.convert.*
import std.fs.*
import std.path.*
import std.process.*
import stdx.encoding.json.*

import magic.core.skill.*
import magic.log.LogUtils
import magic.utils.*

public class UctooApiSkill <: Skill {
    public init() {
        super(
            name: "uctoo-api-skill",
            description: "完整的 uctoo 后端 API 集成技能。将自然语言请求转换为 uctoo-backend API 调用，支持用户管理、产品管理、订单管理等功能。"
        )
    }

    public override func execute(parameters: HashMap<String, JsonValue>): String {
        LogUtils.info("[UctooApiSkill] Executing with parameters: ${parameters}")
        
        let query = if let Some(q) <- parameters.get("query") {
            q.asString().getValue()
        } else if let Some(r) <- parameters.get("request") {
            r.asString().getValue()
        } else {
            ""
        }
        
        if query == "" {
            return "{\"status\": \"error\", \"message\": \"Query parameter is required\"}"
        }
        
        LogUtils.info("[UctooApiSkill] Query: ${query}")
        
        // 注意：实际的 API 调用由大模型通过 SKILL.md 中描述的 Python 脚本完成
        // 这里只是一个占位符，大模型会根据 SKILL.md 中的指令来执行
        return "{\"status\": \"success\", \"message\": \"Skill activated. Please refer to SKILL.md for detailed instructions.\"}"
    }
}

public class UctooApiSkillFactory <: SkillFactory {
    public init() {
        super()
    }

    public override func create(): Skill {
        return UctooApiSkill()
    }
}
```

## 优势

1. **充分利用大模型能力**：语义理解、推理、决策都由大模型完成
2. **灵活性高**：可以处理各种自然语言变体
3. **易于维护**：API 变更只需更新 SKILL.md 中的文档
4. **可扩展性强**：新增 API 只需在文档中添加说明
5. **符合最佳实践**：遵循 Agentskills 的渐进式披露原则

## 迁移计划

### 阶段 1：创建新技能结构
1. 创建新的 SKILL.md 文件
2. 编写 API 规范文档到 references/
3. 创建极简的 Skill 实现

### 阶段 2：测试验证
1. 测试登录功能
2. 测试基本的 CRUD 操作
3. 验证错误处理

### 阶段 3：部署上线
1. 替换旧的 uctoo-api-skill
2. 更新文档
3. 监控运行情况

## 总结

这个重构方案将彻底改变 uctoo-api-skill 的工作方式，从硬编码的关键词提取转变为由大模型驱动的智能 API 集成。这不仅能解决当前的问题，还能为未来的功能扩展提供更大的灵活性。


path: scripts/api_client.js
content: const https = require('https');
const http = require('http');

class UctooApiClient {
    constructor() {
        this.baseUrl = process.env.BACKEND_URL || 'https://javatoarktsapi.uctoo.com';
        this.accessToken = null;
        this.tokenExpiration = null;
    }

    login(username, password) {
        return new Promise((resolve, reject) => {
            const endpoint = '/api/uctoo/auth/login';
            const body = JSON.stringify({ username, password });
            
            this.callApi(endpoint, 'POST', body, false)
                .then(result => {
                    try {
                        const json = JSON.parse(result);
                        if (json.data && json.data.access_token) {
                            this.accessToken = json.data.access_token;
                            this.tokenExpiration = Date.now() + 7200 * 1000;
                        }
                    } catch (e) {
                    }
                    resolve(result);
                })
                .catch(reject);
        });
    }

    isAuthenticated() {
        if (!this.accessToken) {
            return false;
        }
        if (this.tokenExpiration) {
            return Date.now() < this.tokenExpiration;
        }
        return true;
    }

    callApi(endpoint, method, body = '{}', requireAuth = true) {
        return new Promise((resolve, reject) => {
            let fullUrl = this.baseUrl;
            if (!this.baseUrl.endsWith('/') && !endpoint.startsWith('/')) {
                fullUrl += '/';
            }
            fullUrl += endpoint;

            const url = new URL(fullUrl);
            const isHttps = fullUrl.startsWith('https://');
            const client = isHttps ? https : http;

            const options = {
                hostname: url.hostname,
                port: url.port || (isHttps ? 443 : 80),
                path: url.pathname + url.search,
                method: method.toUpperCase(),
                headers: {
                    'Content-Type': 'application/json'
                }
            };

            if (requireAuth && this.isAuthenticated()) {
                options.headers['Authorization'] = `Bearer ${this.accessToken}`;
            }

            const req = client.request(options, (res) => {
                let data = '';

                res.on('data', (chunk) => {
                    data += chunk;
                });

                res.on('end', () => {
                    try {
                        JSON.parse(data);
                        resolve(data);
                    } catch (e) {
                        resolve(JSON.stringify({
                            error: 'API returned invalid JSON',
                            message: 'The API response is not in valid JSON format'
                        }));
                    }
                });
            });

            req.on('error', (e) => {
                resolve(JSON.stringify({
                    error: 'API call failed',
                    message: e.message
                }));
            });

            if (method.toUpperCase() !== 'GET' && body) {
                req.write(body);
            }

            req.end();
        });
    }

    getResource(entityType, id) {
        const endpoint = `/api/uctoo/${entityType}/${id}`;
        return this.callApi(endpoint, 'GET');
    }

    getResources(entityType, limit = 10, page = 0) {
        const endpoint = `/api/uctoo/${entityType}/${limit}/${page}`;
        return this.callApi(endpoint, 'GET');
    }

    createResource(entityType, data) {
        const endpoint = `/api/uctoo/${entityType}/add`;
        return this.callApi(endpoint, 'POST', typeof data === 'string' ? data : JSON.stringify(data));
    }

    updateResource(entityType, data) {
        const endpoint = `/api/uctoo/${entityType}/edit`;
        return this.callApi(endpoint, 'POST', typeof data === 'string' ? data : JSON.stringify(data));
    }

    deleteResource(entityType, id) {
        const endpoint = `/api/uctoo/${entityType}/del`;
        const body = JSON.stringify({ id });
        return this.callApi(endpoint, 'POST', body);
    }
}

if (require.main === module) {
    const client = new UctooApiClient();
    console.log('Uctoo API Client initialized');
    console.log('Base URL:', client.baseUrl);
}

module.exports = UctooApiClient;


path: scripts/api_client.py
content: #!/usr/bin/env python3
"""
UCTOO API Client Script
提供与 uctoo 后端 API 交互的功能
"""

import sys
import json
import requests
from typing import Optional, Dict, Any

BACKEND_URL = "https://javatoarktsapi.uctoo.com"


def make_request(
    method: str,
    endpoint: str,
    data: Optional[Dict[str, Any]] = None,
    [REDACTED_SECRET] = None
) -> str:
    """
    发送 HTTP 请求到 uctoo 后端 API
    
    参数:
        method: HTTP 方法 (GET, POST)
        endpoint: API 端点
        data: JSON 请求体
        token: 认证令牌
    
    返回:
        JSON 格式的响应字符串
    """
    url = f"{BACKEND_URL}{endpoint}"
    headers = {"Content-Type": "application/json"}
    
    if [REDACTED_SECRET]"Authorization"] = f"Bearer {token}"
    
    try:
        if method.upper() == "GET":
            response = requests.get(url, headers=headers, params=data)
        elif method.upper() == "POST":
            response = requests.post(url, headers=headers, json=data)
        else:
            return json.dumps({"error": f"Unsupported method: {method}"})
        
        return response.text
    except Exception as e:
        return json.dumps({"error": str(e)})


def main():
    """
    命令行入口
    
    用法: python api_client.py <method> <endpoint> [data_json] [token]
    """
    if len(sys.argv) < 3:
        print(json.dumps({"error": "Usage: python api_client.py <method> <endpoint> [data_json] [token]"}))
        sys.exit(1)
    
    method = sys.argv[1]
    endpoint = sys.argv[2]
    data = json.loads(sys.argv[3]) if len(sys.argv) > 3 else None
    [REDACTED_SECRET] if len(sys.argv) > 4 else None
    
    result = make_request(method, endpoint, data, token)
    print(result)


if __name__ == "__main__":
    main()


path: scripts/test_api.py
content: import requests
import json
import os

BACKEND_URL = os.environ.get('BACKEND_URL', 'https://javatoarktsapi.uctoo.com')

print("Testing UCTOO API Client")
print("========================")
print(f"Backend URL: {BACKEND_URL}")
print()

# Test 1: Login
print("Test 1: Login with demo / 123456")
print("-" * 50)

login_url = f"{BACKEND_URL}/api/uctoo/auth/login"
login_data = {"username": "demo", "password": "123456"}
headers = {"Content-Type": "application/json"}

try:
    response = requests.post(login_url, json=login_data, headers=headers, timeout=60)
    print(f"Status Code: {response.status_code}")
    print(f"Response: {response.text}")
    
    if response.status_code == 200:
        result = response.json()
        if result.get('code') == 200 and 'data' in result:
            access_token = result['data'].get('access_token')
            if access_token:
                print(f"\n✅ Login successful! Access token obtained.")
                print(f"[REDACTED_SECRET]")
            else:
                print("\n⚠️  Login response but no access token found")
        else:
            print(f"\n⚠️  Login failed: {result.get('message', 'Unknown error')}")
    else:
        print(f"\n❌ HTTP Error: {response.status_code}")
        
except Exception as e:
    print(f"\n❌ Exception: {str(e)}")

print()
print("=" * 50)
print("Test completed!")


path: references/api_spec.md
content: # Uctoo API 规范

## 端点列表

### 用户管理 (uctoo_user)
- `GET /api/uctoo/uctoo_user/{id}` - 获取单个用户
- `GET /api/uctoo/uctoo_user/{limit}/{page}` - 获取用户列表
- `POST /api/uctoo/uctoo_user/add` - 创建用户
- `POST /api/uctoo/uctoo_user/edit` - 更新用户
- `POST /api/uctoo/uctoo_user/del` - 删除用户

### 产品管理 (product)
- `GET /api/uctoo/product/{id}` - 获取单个产品
- `GET /api/uctoo/product/{limit}/{page}` - 获取产品列表
- `POST /api/uctoo/product/add` - 创建产品
- `POST /api/uctoo/product/edit` - 更新产品
- `POST /api/uctoo/product/del` - 删除产品

### 订单管理 (order)
- `GET /api/uctoo/order/{id}` - 获取单个订单
- `GET /api/uctoo/order/{limit}/{page}` - 获取订单列表
- `POST /api/uctoo/order/add` - 创建订单
- `POST /api/uctoo/order/edit` - 更新订单
- `POST /api/uctoo/order/del` - 删除订单

### 认证
- `POST /api/uctoo/auth/login` - 用户登录

## HTTP 方法规范

- **GET**: 用于数据查询操作
- **POST**: 用于创建、更新和删除操作

## 请求格式

### GET 请求示例
```
GET /api/uctoo/uctoo_user/123
GET /api/uctoo/uctoo_user/10/1
```

### POST 请求示例
```json
POST /api/uctoo/uctoo_user/add
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "username": "zhangsan",
  "email": "[REDACTED_SECRET]",
  "phone": "13800138000"
}
```

## 响应格式

### 成功响应
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "123",
    "username": "zhangsan",
    "email": "[REDACTED_SECRET]"
  }
}
```

### 错误响应
```json
{
  "code": 400,
  "message": "error message",
  "data": null
}
```

## 认证

使用 JWT 进行接口权限验证：
1. 通过 `/api/uctoo/auth/login` 获取 access_token
2. 在后续请求的 Header 中添加：`Authorization: Bearer <access_token>`

### 登录请求
```json
POST /api/uctoo/auth/login
Content-Type: application/json

{
  "username": "demo",
  "password": "123456"
}
```

### 登录响应
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 7200,
    "user": {
      "id": "1",
      "username": "demo"
    }
  }
}
```


path: references/examples.md
content: # 使用示例

## 目录
- [用户管理示例](#用户管理示例)
- [产品管理示例](#产品管理示例)
- [订单管理示例](#订单管理示例)
- [综合场景示例](#综合场景示例)

---

## 用户管理示例

### 1. 获取所有用户
**请求**:
```
"获取所有用户"
```

**执行流程**:
1. 识别意图: GET_RESOURCE
2. 识别实体类型: uctoo_user
3. 调用API: `GET /api/uctoo/uctoo_user/10/1`
4. 返回用户列表

### 2. 获取特定用户
**请求**:
```
"查找ID为3a5a079d-38b2-4ea2-b8cd-f3c0d93dacfb的用户"
```

**执行流程**:
1. 识别意图: GET_RESOURCE
2. 提取ID: 3a5a079d-38b2-4ea2-b8cd-f3c0d93dacfb
3. 调用API: `GET /api/uctoo/uctoo_user/3a5a079d-38b2-4ea2-b8cd-f3c0d93dacfb`

### 3. 创建新用户
**请求**:
```
"创建一个名为李四的新用户，邮箱是[REDACTED_SECRET]，电话是13900139000"
```

**执行流程**:
1. 识别意图: CREATE_RESOURCE
2. 提取参数:
   - username: 李四
   - email: [REDACTED_SECRET]
   - phone: 13900139000
3. 调用API: `POST /api/uctoo/uctoo_user/add`

### 4. 更新用户信息
**请求**:
```
"更新用户456的邮箱为[REDACTED_SECRET]"
```

**执行流程**:
1. 识别意图: UPDATE_RESOURCE
2. 提取参数:
   - id: 456
   - email: [REDACTED_SECRET]
3. 调用API: `POST /api/uctoo/uctoo_user/edit`

### 5. 删除用户
**请求**:
```
"删除用户789"
```

**执行流程**:
1. 识别意图: DELETE_RESOURCE
2. 提取ID: 789
3. 调用API: `POST /api/uctoo/uctoo_user/del`

---

## 产品管理示例

### 1. 查询产品列表
**请求**:
```
"显示所有产品，每页20个"
```

**执行流程**:
1. 识别意图: GET_RESOURCE
2. 识别实体类型: product
3. 提取参数: limit=20, page=1
4. 调用API: `GET /api/uctoo/product/20/1`

### 2. 创建产品
**请求**:
```
"添加一个新产品，名称是智能手表，价格是999元，库存是100件"
```

**执行流程**:
1. 识别意图: CREATE_RESOURCE
2. 识别实体类型: product
3. 提取参数:
   - name: 智能手表
   - price: 999
   - stock: 100
4. 调用API: `POST /api/uctoo/product/add`

---

## 订单管理示例

### 1. 查询订单
**请求**:
```
"查看最近的订单"
```

**执行流程**:
1. 识别意图: GET_RESOURCE
2. 识别实体类型: order
3. 调用API: `GET /api/uctoo/order/10/1`

### 2. 创建订单
**请求**:
```
"为用户123创建一个订单，购买产品456，数量2个"
```

**执行流程**:
1. 识别意图: CREATE_RESOURCE
2. 识别实体类型: order
3. 提取参数:
   - user_id: 123
   - product_id: 456
   - quantity: 2
4. 调用API: `POST /api/uctoo/order/add`

### 3. 更新订单状态
**请求**:
```
"将订单789的状态更新为已发货"
```

**执行流程**:
1. 识别意图: UPDATE_RESOURCE
2. 识别实体类型: order
3. 提取参数:
   - id: 789
   - status: 已发货
4. 调用API: `POST /api/uctoo/order/edit`

---

## 综合场景示例

### 场景1: 完整的购物流程
**请求序列**:
1. "使用账号demo和密码123456登录"
2. "查看所有产品"
3. "创建一个新订单，购买产品1，数量3个"
4. "查看我的订单"

**执行流程**:
1. 登录 → 获取 access_token
2. 查询产品列表
3. 创建订单
4. 查询订单列表

### 场景2: 用户管理工作流
**请求序列**:
1. "登录系统"
2. "创建用户张三"
3. "查看所有用户"
4. "更新张三的电话为13800138000"
5. "删除测试用户"

**执行流程**:
1. 认证
2. CRUD操作
3. 确认结果

---

## 提示和技巧

### 1. 明确指定操作
- ✅ 好: "创建名为张三的用户"
- ❌ 坏: "处理一下用户"

### 2. 提供完整参数
- ✅ 好: "创建用户李四，邮箱[REDACTED_SECRET]，电话13900139000"
- ❌ 坏: "创建一个用户"

### 3. 使用自然的语言
- ✅ 好: "帮我查一下有哪些产品"
- ❌ 坏: "执行GET /api/uctoo/product"

### 4. 先登录再操作
需要认证的操作，请先登录：
> "使用账号demo和密码123456登录"


path: references/uctoo_api_design.md
content: # API版本 v3.0.0 Beta  

1. 采用RESTFul风格API。  
2. 遵循全栈模型同构UMI设计理念。[UMI参考文章](https://mp.weixin.qq.com/s/ja0jfsfkyIK2hdW6bDg2Ow)  
3. 采用jwt进行接口权限验证。需要权限调用的接口需先通过登录 /api/uctoo/auth/login 接口获取动态token，再以Bearer 动态token拼接成的字符串作为header的Authorization进行需要权限的接口调用。动态token过期时间默认为172800秒，如需定制修改可编辑根目录.env文件中ACCESS_TOKEN_VALIDITY_SEC字段。  
4. 单表对应的CURD操作默认API应以id字段作为数据一致性传输的主标识，如有特殊API不存在id字段的，则以动态token作为主标识。  
5. API不应输出的模型字段，可以使用hideSelectedObjectKeys()方法过滤掉不应输出的字段。需注意接口数据的信息安全。

## 数据表CURD标准接口规范  
以uctoo数据库entity表为例，介绍数据表CURD标准接口规范。多数据库API规则，将/uctoo/entity部分替换为对应的数据库名和表名/database_name/table_name  

### 路由规则  
完整接口URL地址是由.env文件中配置的API_URL拼接路由地址而成。路由地址遵循以下规范。  
1. 新增接口路由地址 /api/uctoo/entity/add ，post请求，需认证权限，body数据以json格式提交，成功调用返回新增的entity全部信息。  
2. 更新接口路由地址 /api/uctoo/entity/edit ，post请求，需认证权限，以id作为主键，body数据以json格式提交，成功调用返回更新后的entity全部信息。恢复一条软删除数据，可以通过调用更新接口，并将deleted_at字段传值"0"，以将deleted_at字段设置为空。支持多条数据编辑，body中以ids参数传编辑数据的多条主键数组以及编辑数据，例如 {ids: JSON.stringify(rowSelectState.selectedRowKeys)，link: "value", privacy_level:2}     
3. 删除接口路由地址 /api/uctoo/entity/del ，post请求，需认证权限，以id作为主键，默认为软删除，如需真删除，body中增加force参数设置为1，成功调用不返回任何数据。支持多条数据删除，body中以ids参数传删除数据的多条主键数组，例如 {ids: JSON.stringify(rowSelectState.selectedRowKeys)}    
4. 单条数据查询接口地址 /api/uctoo/entity/:id ，get请求，根据需要设置认证权限，以id作为主键查询，成功调用返回完整单条数据。  
5. 多条数据查询接口地址 /api/uctoo/entity/:limit/:page，get请求，根据需要设置认证权限，limit参数为一页的数据条数，page参数为页数，起始页数为0，成功调用返回多条完整数据数组。  
6. 多条数据查询接口地址 /api/uctoo/entity/:limit/:page/:skip，get请求，根据需要设置认证权限，limit参数为一页的数据条数，page参数为页数，起始页数为0，skip参数为跳过几条数据，起始条数为0，成功调用返回多条完整数据数组。    
7. 多条数据查询接口可支持prisma orm的where条件查询和orderBy排序，路由地址格式为 /api/entity/:limit/:page?sort=-privacy_level,id&filter={"link":{"endsWith":"opencangjie.com"}}。filter为json格式的查询参数，与prisma官方规范一致(see the [official documentation](https://www.prisma.io/docs/concepts/components/prisma-client/filtering-and-sorting#filtering))。sort为排序参数，负号为降序，如无sort排序，默认按created_at数据创建时间降序。  

### 接口状态代码
与HTTP/HTTPS协议状态代码约定一致（RFC2616）。例如，200为请求成功，400为客户端请求语法错误服务器无法理解，500为服务器处理错误。  

### 错误码  
接口返回错误时，将返回如下结构的错误对象
{
    "errno": "42002", errmsg: "verify code is invalid"
}
errno 错误码一般为 5 位数，errmsg 为错误描述  

### 接口文档
完整接口文档网址  
https://apifox.com/apidoc/shared/9a22079c-a59f-4b65-a7f6-678f0643e7f6/api-170720939

## websocket接口  
websocket接口路由地址以 /ws 开头，大部分为定制接口路由，暂无固定规范。可参考websocket目录中实现。


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)