# Magic-Script 脚本开发助手

Magic-API 是一个基于 Java 的接口快速开发框架，支持通过 magic-script 脚本语言编写接口。magic-script 是一种基于 Mozilla Rhino 的脚本语言，语法类似 JavaScript，专为接口开发优化。

> **说明**：本 Skill 同时兼容以下称呼方式：
> - magic-api / magicapi（框架名称）
> - magic-script / MagicScript / magicscript（脚本语言名称）
    > 无论用户使用哪种称呼，都指代同一套技术栈。

## 任务目标
- 本 Skill 用于：为 magic-api/magicapi 框架提供 magic-script/MagicScript 脚本编写的完整指导
- 能力包含：magic-script 语法参考、内置模块（db、http 等）使用方法、接口开发示例和脚本故障排查
- 触发条件：用户需要在 magic-api/magicapi 中编写接口脚本、调试 magic-script/MagicScript 代码或解决脚本执行错误时使用

## 功能特性

- **语法参考**：关键字、运算符、数据类型、Lambda 表达式、异步调用、类型转换
- **函数扩展**：字符串、数字、集合、日期、聚合函数、数学函数
- **数据库操作**：查询、增删改、单表操作、分页、事务
- **内置模块**：HTTP、Lambda/LINQ、日志、环境配置、请求响应处理
- **接口示例**：CRUD 操作、带事务的业务处理、HTTP 集成
- **故障排查**：参数获取、SQL 注入、${} 与 #{} 区别、多数据源配置

## 使用方式

### 在 Coze 中使用

1. 解压 `magic-script.zip` 文件
2. 将 `magic-script` 文件夹放入 skills 目录
3. 在技能管理中选择该技能使用

### 在 Claude Code 中使用

```bash
# 解压并复制到技能目录
unzip magic-script.zip
cp -r magic-script ~/.claude/skills/
```

### 在 OpenCode 中使用

```bash
# 解压并复制到技能目录
unzip magic-script.zip
cp -r magic-script ~/.config/opencode/skills/
```

### 目录结构

```
magic-script/
├── SKILL.md
├── README.md
└── references/
    ├── keywords.md            # 关键字、运算符、数据类型
    ├── script-syntax.md       # 脚本语法详解
    ├── lambda-async.md        # Lambda表达式与异步调用
    │
    ├── aggregation.md         # 聚合函数
    ├── string-functions.md    # 字符串函数
    ├── date-functions.md      # 日期函数
    ├── array-functions.md     # 数组创建函数
    ├── math-functions.md      # 数学函数
    ├── other-functions.md     # 其它函数
    │
    ├── object-extensions.md   # Object扩展方法
    ├── number-extensions.md   # Number扩展方法
    ├── collection-extensions.md # 列表与Map扩展
    ├── date-extensions.md     # 日期扩展
    ├── class-extensions.md    # Class扩展方法
    ├── pattern-extensions.md  # Pattern扩展方法
    │
    ├── db-query.md            # 数据库查询
    ├── db-update.md           # 数据库增删改
    ├── db-transaction.md      # 事务操作
    ├── db-cache.md            # 缓存操作
    ├── single-table.md        # 单表操作（db.table链式API）
    ├── sql-param.md           # SQL参数（#{}、${}、动态SQL）
    ├── page.md                # 分页查询
    │
    ├── http-module.md         # HTTP模块
    ├── request-module.md      # Request模块
    ├── response-module.md     # Response模块
    ├── log-module.md          # 日志模块
    ├── env-module.md          # 环境配置模块
    ├── magic-module.md        # Magic模块
    │
    ├── java-integration.md    # 脚本调用Java
    ├── api-integration.md     # Java调用接口
    │
    ├── quick-start.md         # 快速入门
    ├── quick-param.md         # 请求参数获取
    ├── quick-crud.md          # CRUD操作示例
    ├── linq.md                # Lambda/LINQ操作示例
    │
    ├── faq.md                 # 常见问题
    └── validate.md            # 参数校验
```

## 技术栈

- **框架**：magic-api（又称 magicapi）
- **脚本语言**：magic-script（又称 MagicScript、magicscript）

## 适用场景

- 需要在 magic-api 框架中编写接口脚本
- 调试 magic-script 脚本代码
- 解决脚本执行错误

## 注意事项

1. 本技能专注于编写 magic-script 脚本代码，不包含 magic-api 框架配置相关内容
2. magic-script 不是标准 JavaScript，有语法限制（如不支持 forEach 用 each 替代）
3. SQL 参数建议使用 `#{param}` 防注入，`${param}` 慎用
