# {{ display_name }}

{{ description }}

这是一个基于 Adam Tool Protocol (ATP) 开发的 Kit 工具项目，通过表单界面为用户提供功能。

## 项目信息

- **项目名称**: {{ name }}
- **显示名称**: {{ display_name }}
- **版本**: {{ version }}
- **作者**: {{ author }}
- **类型**: Kit (表单工具)

## 快速开始

### 1. 环境准备

确保你已经安装了 adam-community：

```bash
# 在项目根目录安装依赖
cd /path/to/adam-community
python setup.py develop
```

### 2. 开发工具流程

#### 2.1 修改代码实现
编辑 `{{ name.replace('-', '_') }}.py` 文件，实现你的业务逻辑：

```python
def call(self, kwargs):
    # 获取表单输入参数
    input_text = kwargs['args']['input_text']
    
    # TODO: 在这里实现你的主要逻辑
    # 示例：处理输入文本
    result = process_your_logic(input_text)
    
    # 生成报告文件 (Kit工具必须生成 report.md)
    generate_report(result)
    
    return result
```

#### 2.2 自定义表单配置
编辑 `config/input.json` 来配置用户输入表单：

```json
{
  "formName": "你的表单名称",
  "description": "表单说明",
  "fields": [
    {
      "name": "input_field",
      "label": "输入字段",
      "type": "string",
      "description": "字段说明",
      "validation": {
        "required": true,
        "message": "错误提示"
      }
    }
  ]
}
```

支持的字段类型：
- `string`: 文本输入
- `number`: 数字输入
- `boolean`: 布尔值
- `select`: 单选下拉框
- `multiselect`: 多选框
- `file`: 文件上传
- `date`: 日期选择
- `object`: 对象（嵌套字段）
- `array`: 数组

#### 2.3 完善项目描述
编辑 `config/long_description.md` 来完善项目的详细描述，包括：
- 概览：工具的主要功能和用途
- 特性：核心特性和优势
- 指标：性能指标和使用统计

### 3. 构建和测试

#### 3.1 解析工具函数
```bash
# 生成 functions.json
make parse
```

#### 3.2 构建项目包
```bash
# 构建 ZIP 包
make build
```

#### 3.3 本地调试
你可以通过以下方式进行本地调试：

```python
# 创建测试脚本 test_local.py
from {{ name.replace('-', '_') }} import runner

# 模拟参数
test_kwargs = {
    'args': {
        'input_text': '测试输入'
    },
    'message': '用户消息',
    'files': [],
    'user': '测试用户',
    'task_id': 'test_task'
}

# 创建工具实例并测试
tool = runner()
result = tool.call(test_kwargs)
print(f"执行结果: {result}")

# 测试输出显示
output_kwargs = {
    'stdout': '测试输出',
    'stderr': '',
    'exitcode': 0
}
display_text, file_list = tool.outputShow(output_kwargs)
print(f"显示文本: {display_text}")
print(f"文件列表: {file_list}")
```

### 4. 部署和发布

#### 4.1 上传到平台
1. 运行 `make build` 生成 ZIP 包
2. 在 Adam 平台控制台选择生成的 ZIP 包
3. 点击发布
4. 设置为可见状态

#### 4.2 测试工具
1. 在平台的「工具」页面找到你的工具
2. 填写表单测试功能
3. 查看生成的报告和结果

## 开发指南

### Kit 工具特点
- **表单驱动**: 用户通过填写表单提供输入参数
- **报告生成**: 必须生成 `report.md` 文件作为结果展示
- **文件输出**: 可以生成多个文件供用户下载
- **同步执行**: 用户提交表单后同步执行并返回结果

### 重要方法说明

#### `call(self, kwargs)` - 核心执行方法
- **必须实现**
- 参数包含：`args`(表单数据)、`message`、`files`、`user`、`task_id`
- 必须生成 `report.md` 文件
- 返回处理结果

#### `outputShow(self, kwargs)` - 输出显示格式
- **可选实现**
- 自定义用户看到的结果展示格式
- 返回 `(display_text, file_list)` 元组
- `file_list` 中的文件会提供给用户下载

#### `summary(self, kwargs)` - AI摘要
- **可选实现**
- 为 AI 生成简短的执行摘要
- 用于 AI 理解工具执行结果

### 常见问题

#### Q: 如何处理文件上传？
A: 在表单配置中使用 `file` 类型字段，在 `call` 方法中通过 `kwargs['files']` 获取上传的文件列表。

#### Q: 如何生成多个输出文件？
A: 在 `call` 方法中创建多个文件，然后在 `outputShow` 方法的 `file_list` 中返回文件名列表。

#### Q: 如何处理错误？
A: 使用 `print()` 输出错误信息到 stderr，系统会自动捕获并显示给用户。

#### Q: 如何调试代码？
A: 创建本地测试脚本，模拟 `kwargs` 参数来测试你的工具逻辑。

#### Q: 必须配置哪些属性？
A: 以下属性是必填的：
```python
DISPLAY_NAME = "工具显示名称"  # 工具的显示名称
NETWORK = True/False           # 是否需要网络访问
CPU = 1                        # 需要的CPU数量（必填）
GPU = 0                        # 需要的GPU数量（必填）
SIF = "adam-base:1.0.0"       # 容器镜像（必填）
```

## 文件结构说明

```
{{ name }}/
├── config/
│   ├── configure.json      # 工具基本配置
│   ├── input.json          # 表单配置
│   └── long_description.md # 详细描述
├── {{ name.replace('-', '_') }}.py         # 主要实现文件
├── functions.json          # 自动生成的函数描述
├── Makefile               # 构建脚本
└── README.md              # 本文件
```

## 参考资源

- [Adam Tool Protocol 文档](https://docs.example.com/atp)
- [表单配置指南](https://docs.example.com/form-config)
- [现有工具示例](https://github.com/example/adam-tools)

## 贡献和支持

如有问题或建议，请联系：{{ author }}

---
Generated by Adam CLI - {{ name }} v{{ version }}