tool-writer-skill

0	n
1	a
2	m
3	e
4	:
5	T
6	o
7	o
8	l
9
10	W
11	r
12	i
13	t
14	e
15	r
16
17	S
18	k
19	i
20	l
21	l
22
23	-
24
25	工
26	具
27	编
28	写
29	技
30	能
31
32	d
33	e
34	s
35	c
36	r
37	i
38	p
39	t
40	i
41	o
42	n
43	:
44	这
45	是
46	一
47	个
48	帮
49	助
50
51	d
52	e
53	e
54	p
55	a
56	g
57	e
58	n
59	t
60
61	自
62	主
63	编
64	写
65	新
66	工
67	具
68	的
69	技
70	能
71	。

Tool Writer Skill - 工具编写技能

概述

这是一个帮助 deepagent 自主编写新工具的技能。通过这个技能，agent 可以：

• 分析需求，编写符合规范的工具函数
• 自动注册到系统工具列表
• 测试和验证新工具

何时使用

当用户需要新功能且现有工具无法满足时，应该使用这个技能来编写新工具。

⚠️ 重要：编写工具前必须先进行 Planning！

使用步骤

第一步：Planning（必须！）

在编写任何工具前，必须先进行 Planning：

1. 分析用户需求

   • 理解工具要解决什么问题
   • 确定输入和输出
   • 识别边界情况

2. 设计工具接口

   • 工具名称（使用下划线命名法）
   • 参数列表（类型注解）
   • 返回值类型（必须是 str）
   • docstring 描述

3. 规划实现逻辑

   • 核心算法
   • 错误处理
   • 性能优化

第二步：编写工具

使用以下模板在 /tools/tools.py 中添加新工具：

@tool
def your_tool_name(param1: str = "default", param2: int = 10) -> str:
    """工具的详细描述

    Args:
        param1: 参数1的说明
        param2: 参数2的说明
    """
    # 工具实现逻辑
    return "工具执行结果"

重要规范：

• 必须使用 @tool 装饰器
• 函数名即为工具名，使用下划线命名法
• 参数必须有类型注解
• 返回类型必须为 str
• 写详细的 docstring，说明功能和参数
• 优先返回结构化文本（如 JSON、表格等）

第三步：验证工具

1. 检查语法是否正确
2. 确保工具可以被系统自动识别
3. 在对话中测试工具是否能正常工作

第四步：重启系统（如果需要）

如果新添加工具后系统未自动识别，可能需要重启 deepagent 实例。

工具类型示例

1. 数据查询工具

@tool
def query_database(query: str) -> str:
    """查询数据库

    Args:
        query: SQL查询语句或数据标识
    """
    # 实现查询逻辑
    return "查询结果"

2. 计算工具

@tool
def calculate(expression: str) -> str:
    """计算数学表达式

    Args:
        expression: 数学表达式，如 "2*3+5"
    """
    try:
        result = eval(expression)
        return f"{expression} = {result}"
    except:
        return "计算错误"

3. 文件处理工具

@tool
def process_file(file_path: str, operation: str = "read") -> str:
    """处理文件

    Args:
        file_path: 文件路径
        operation: 操作类型（read/write/analyze）
    """
    # 实现文件处理
    return "处理结果"

Planning 示例

场景：编写密码生成器

Planning：

1. 需求分析

   • 生成随机密码
   • 支持自定义长度
   • 支持选择字符类型

2. 接口设计

   • 工具名：generate_password
   • 参数：
     • length (int): 密码长度，默认12
     • include_special (bool): 是否包含特殊字符，默认True
   • 返回：str 格式的密码

3. 实现逻辑

   • 使用 random 和 string 模块
   • 字符集：字母+数字+可选特殊字符
   • 随机选择组合

4. 代码实现

@tool
def generate_password(length: int = 12, include_special: bool = True) -> str:
    """生成随机密码

    Args:
        length: 密码长度，默认12
        include_special: 是否包含特殊字符，默认是
    """
    import random
    import string

    chars = string.ascii_letters + string.digits
    if include_special:
        chars += "!@#$%^&*"

    password = ''.join(random.choice(chars) for _ in range(length))
    return f"生成的密码: {password}"

注意事项

1. 安全性：避免执行危险操作，如删除系统文件、执行任意代码
2. 错误处理：添加适当的错误处理和默认值
3. 性能：避免长时间阻塞的操作
4. 文档：确保工具描述清晰，参数说明完整
5. 测试：在添加新工具后进行测试验证

常见问题

Q: 新工具不显示在可用工具列表中？ A: 确保使用了 @tool 装饰器，函数名和参数有正确注解。重启系统可能需要。

Q: 如何删除工具？ A: 从 /tools/tools.py 中删除对应的函数定义即可。

Q: 可以添加外部API调用吗？ A: 可以，注意处理网络错误和超时情况。