# 工具开发代码示例（参考文件）

> 本文件为 `tool_development` 技能的参考文件，提供工具开发的完整代码示例。

## 一、工具脚本完整示例（index.js）

### 基本结构

```javascript
module.exports = {
  // 辅助方法（可选）
  helperFunction: function (param1, param2) {
    // 参数校验
    if (!param1) {
      throw new TypeError('param1 不能为空');
    }
    // 业务逻辑
    return someResult;
  },
  
  /**
   * 主要逻辑
   * @param {object} params 参数
   * @param {string} params.param1 参数1描述
   * @param {number} params.param2 参数2描述
   * @returns {Object} 执行结果
   */
  async main(params) {
    let ret;
    try {
      // 调用辅助方法（使用 this 调用同对象下的方法）
      let result = await this.helperFunction(params.param1, params.param2);
      
      ret = {
        code: 0,
        msg: '操作成功',
        // 返回数据字段按实际命名
        data_field: result
      };
    } catch (error) {
      ret = {
        code: 10000,
        msg: error.message
      };
    }
    return ret;
  }
};
```

### 简单问候工具示例

```javascript
module.exports = {
  validateName: function (name) {
    if (!name) {
      throw new TypeError('名称不能为空');
    }
    if (typeof name !== 'string') {
      throw new TypeError('名称必须是字符串类型');
    }
    return name.trim();
  },
  
  async main(params) {
    let ret;
    try {
      let name = this.validateName(params.name);
      ret = {
        code: 0,
        msg: '问候成功',
        greeting: 'Hello, ' + name + '!'
      };
    } catch (error) {
      ret = {
        code: 10000,
        msg: error.message
      };
    }
    return ret;
  }
};
```

## 二、tool.json 完整配置示例

```json
{
  "name": "tool_name",
  "title": "工具中文标题",
  "description": "工具描述，说明工具的用途",
  "category": "工具分类",
  "type": "function",
  "main": "./index.js",
  "params": [
    {
      "name": "param1",
      "description": "参数1的描述",
      "type": "string",
      "required": true
    },
    {
      "name": "param2",
      "description": "参数2的描述",
      "type": "number",
      "default": 100
    }
  ],
  "returns": [
    {
      "name": "code",
      "type": "number",
      "description": "状态码，0成功 其他失败",
      "default": 0
    },
    {
      "name": "msg",
      "type": "string",
      "description": "状态描述",
      "default": ""
    }
  ]
}
```

## 三、返回值格式标准

### 成功（带返回数据）
```javascript
{
  code: 0,
  msg: '操作成功',
  task: { name: 'task1', title: '任务1' },
  total: 100
}
```

### 成功（无数据）
```javascript
{
  code: 0,
  msg: '操作成功'
}
```

### 失败（通用错误码）
```javascript
{
  code: 10000,
  msg: '错误描述信息'
}
```

### 参数错误
```javascript
{
  code: 10000,
  msg: '参数错误: xxx 不能为空'
}
```

## 四、标准错误码

| 错误码 | 含义 | 使用场景 |
|--------|------|----------|
| `0` | 成功 | 操作正常完成 |
| `10000` | 失败 | 参数错误、资源不存在、系统错误等通用错误 |

## 五、工具目录结构

```
./ai/tool/{tool_name}/
├── index.js       # 工具脚本（入口文件）
└── tool.json      # 工具配置文件
```

## 六、常用工具分类参考

| 分类 | 说明 | 示例工具 |
|------|------|----------|
| 图像处理 | 图片相关操作 | image_convert, image_resize |
| 音频处理 | 音频相关操作 | audio_convert, audio_merge |
| 视频处理 | 视频相关操作 | video_convert, video_merge |
| 文本处理 | 文本相关操作 | text_translate, text_extract |
| 文件管理 | 文件系统操作 | copy_file, delete_file |
| 数据处理 | 数据处理操作 | excel_read, excel_write |
| 画布绘图 | 图形绘制操作 | canvas_draw, canvas_image |
| 任务管理 | 任务相关操作 | get_task_detail, create_task |