# {{ display_name }}

{{ description }}

这是一个基于 Adam Tool Protocol (ATP) 开发的 Toolbox 智能体项目，通过对话方式为用户提供智能化服务。

## 项目信息

- **项目名称**: {{ name }}
- **显示名称**: {{ display_name }}
- **版本**: {{ version }}
- **作者**: {{ author }}
- **类型**: Toolbox (智能体工具)

## 快速开始

### 1. 环境准备

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

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

### 2. 开发智能体流程

#### 2.1 修改工具实现
编辑 `{{ name.replace('-', '_') }}.py` 文件，实现你的工具逻辑。项目包含两种工具类型：

**Bash 类型工具 (默认)**：
```python
class {{ name.replace("-", "_") }}_tool(Tool):
    def call(self, kwargs):
        # 获取用户输入参数
        input_text = kwargs['args']['input_text']
        
        # 返回要执行的 bash 命令
        bash_script = f'''
        # 你的 bash 脚本
        echo "处理: {input_text}"
        # 添加你的命令...
        '''
        return bash_script
```

**Python 类型工具**：
```python
class {{ name.replace("-", "_") }}_advanced_tool(Tool, calltype="python"):
    DISPLAY_NAME = "{{ display_name }}高级工具"
    NETWORK = False     # 是否需要网络访问
    CPU = 1            # 需要的CPU数量
    GPU = 0            # 需要的GPU数量
    SIF = "adam-base:1.0.0"  # 容器镜像
    CONDA_ENV = "base"  # 指定运行环境
    
    def call(self, kwargs):
        # Python 代码逻辑
        result = your_python_logic()
        
        # 必须使用 print 输出结果
        print(f"处理结果: {result}")
```

#### 2.2 配置智能体提示词
编辑以下文件来配置智能体的行为：

**`config/initial_system_prompt.md`** - 系统提示词：
```markdown
# 你的信息
您是一位专业的{{ display_name }}专家...

# 你的任务范围
1. 理解用户需求
2. 选择合适工具
3. 执行操作
4. 生成报告

# 工作流程
1. 分析需求
2. 制定计划
3. 执行工具
4. 分析结果
5. 生成报告
```

**`config/initial_assistant_message.md`** - 欢迎消息：
```markdown
# 欢迎使用{{ display_name }}工具！

我可以帮助您：
- 功能1：描述
- 功能2：描述
- 功能3：描述

请告诉我您的需求...
```

#### 2.3 完善项目描述
编辑 `config/long_description.md` 来完善项目的详细描述。

### 3. 构建和测试

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

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

#### 3.3 本地调试

**测试 Bash 工具**：
```python
# 创建测试脚本 test_bash_tool.py
from {{ name.replace('-', '_') }} import {{ name.replace("-", "_") }}_tool

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

# 测试工具
tool = {{ name.replace("-", "_") }}_tool()
bash_script = tool.call(test_kwargs)
print(f"生成的 bash 脚本:\n{bash_script}")

# 测试输出显示
output_kwargs = {
    'stdout': '命令执行输出',
    'stderr': '',
    'exitcode': 0
}
display_text, file_list = tool.outputShow(output_kwargs)
print(f"显示文本:\n{display_text}")
```

**测试 Python 工具**：
```python
# 创建测试脚本 test_python_tool.py
from {{ name.replace('-', '_') }} import {{ name.replace("-", "_") }}_advanced_tool

# 模拟参数
test_kwargs = {
    'args': {
        'input_file': 'test.txt',
        'output_format': 'json'
    }
}

# 测试工具
tool = {{ name.replace("-", "_") }}_advanced_tool()
tool.call(test_kwargs)  # Python工具直接执行
```

### 4. 部署和发布

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

#### 4.2 测试智能体
1. 在平台的「智能体」页面找到你的智能体
2. 通过对话方式测试功能
3. 观察智能体如何调用你的工具

## 开发指南

### Toolbox 智能体特点
- **对话驱动**: 用户通过自然语言对话与智能体交互
- **工具调用**: 智能体根据需要调用相应的工具函数
- **多轮对话**: 支持复杂的多轮对话场景
- **智能决策**: AI 自动决定何时调用哪个工具

### 工具类型说明

#### Bash 工具 (`calltype = "bash"`)
- 适用于系统命令、脚本执行、文件操作等
- `call` 方法返回要执行的 bash 命令字符串
- 系统会执行返回的命令并捕获输出

#### Python 工具 (`calltype = "python"`)
- 适用于复杂的 Python 逻辑、数据处理、API 调用等
- `call` 方法直接执行 Python 代码
- 必须使用 `print()` 输出结果
- 需要指定 `CONDA_ENV` 运行环境

### 重要配置项

#### 工具属性（必填配置）
```python
DISPLAY_NAME = "工具显示名称"  # 工具的显示名称
NETWORK = True/False           # 是否需要网络访问
CPU = 1                        # 需要的CPU数量（必填）
GPU = 0                        # 需要的GPU数量（必填）
SIF = "adam-base:1.0.0"       # 容器镜像（必填）
CONDA_ENV = "base"             # Conda环境（仅Python工具）
```

#### docstring 格式
```python
"""
工具的功能描述

:param str input_text: 必需参数描述
:param str? mode: 可选参数描述（注意?标记）
"""
```

### 重要方法说明

#### `call(self, kwargs)` - 核心执行方法
- **必须实现**
- Bash工具：返回要执行的命令字符串
- Python工具：直接执行逻辑并用print输出

#### `inputShow(self, **kwargs)` - 输入显示
- **可选实现**
- 自定义用户看到的输入格式
- 默认显示完整的命令或代码

#### `outputShow(self, kwargs)` - 输出显示
- **可选实现**  
- 自定义用户看到的输出格式
- 返回 `(display_text, file_list)` 元组

#### `summary(self, kwargs)` - AI摘要
- **可选实现**
- 为 AI 生成执行摘要，用于后续决策
- 控制输出长度，避免上下文过长

#### `monitor(self, process, kwargs)` - 进度监控
- **可选实现**
- 监控长时间运行的任务进度
- 设置 `kwargs["PIPELINE"]` 和 `kwargs["PROCESS"]`

### 智能体提示词编写指南

#### 系统提示词 (`initial_system_prompt.md`)
- 定义智能体的身份和专业领域
- 描述任务范围和工作流程
- 设置工具调用的优先级和策略
- 包含重要的注意事项和限制

#### 欢迎消息 (`initial_assistant_message.md`)
- 向用户介绍智能体的功能
- 提供使用建议和最佳实践
- 引导用户正确描述需求

### 常见问题

#### Q: 如何处理长时间运行的任务？
A: 实现 `monitor` 方法来报告进度，或者将任务分解为多个步骤。

#### Q: 如何让智能体调用特定工具？
A: 在系统提示词中明确工具的使用场景和调用条件。

#### Q: 如何处理错误和异常？
A: 在工具中使用适当的错误处理，通过 stderr 输出错误信息。

#### Q: 如何优化智能体的响应质量？
A: 精心设计 docstring 和系统提示词，提供清晰的工具描述和使用指导。

#### Q: Python工具的依赖如何管理？
A: 确保指定的 CONDA_ENV 环境中安装了所有需要的依赖包。

## 文件结构说明

```
{{ name }}/
├── config/
│   ├── configure.json              # 智能体基本配置
│   ├── initial_system_prompt.md    # 系统提示词
│   ├── initial_assistant_message.md # 欢迎消息
│   └── long_description.md         # 详细描述
├── {{ name.replace('-', '_') }}.py                 # 主要实现文件
├── functions.json                  # 自动生成的工具描述
├── Makefile                       # 构建脚本
└── README.md                      # 本文件
```

## 调试技巧

### 1. 单独测试工具
创建独立的测试脚本来验证工具逻辑：

```python
# test_individual_tool.py
if __name__ == "__main__":
    from your_module import your_tool
    
    # 模拟真实调用场景
    tool = your_tool()
    result = tool.call(mock_kwargs)
    print(result)
```

### 2. 输出调试信息
在工具中添加详细的调试输出：

```python
def call(self, kwargs):
    print(f"DEBUG: 收到参数: {kwargs}")
    # 你的逻辑
    print(f"DEBUG: 处理结果: {result}")
    return result
```

### 3. 测试提示词效果
在本地模拟对话场景，测试智能体的响应质量。

## 参考资源

- [Adam Tool Protocol 文档](https://docs.example.com/atp)
- [智能体开发指南](https://docs.example.com/agent-guide)
- [现有智能体示例](https://github.com/example/adam-tools)

## 贡献和支持

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

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