添加新工具

CocoCat 的工具系统位于 cococat/core/tools/，基于 Tool 基类和 ToolRegistry 注册模式。添加一个新工具需要完成以下步骤。

第一步：创建 Tool 子类

在 cococat/core/tools/ 中，新建一个继承 Tool 的类：

class MyNewTool(Tool):
    name = "my_new_tool"
    description = "What this tool does"
    required_permission = PermissionMode.READONLY  # 或 WORKSPACE_WRITE / FULL_ACCESS
    parameters = {
        "type": "object",
        "properties": {
            "param1": {"type": "string", "description": "参数说明"},
            "param2": {"type": "integer", "description": "参数说明"},
        },
        "required": ["param1"],
    }

字段说明

字段	必填	说明
name	是	工具名称，字母数字+下划线，LLM 通过此名称调用
description	是	工具描述，LLM 据此判断何时使用
parameters	是	OpenAI function calling schema，定义参数
required_permission	否	权限级别，默认 FULL_ACCESS

权限级别

级别	说明	适用场景
READONLY	读操作，不修改任何数据	文件读取、搜索、查询
WORKSPACE_WRITE	写操作，限于 workspace 内	文件写入、记忆修改
FULL_ACCESS	完整访问，可执行命令	命令执行、跨 agent 操作

第二步：实现 execute() 方法

def execute(self, param1="", param2=0, **kwargs) -> str:
    """执行工具逻辑。所有参数通过 **kwargs 传入，建议显式声明默认值。"""
    try:
        # 工具逻辑
        result = do_something(param1, param2)
        return f"Success: {result}"
    except Exception as e:
        return f"Error: {e}"

编码规范

• 返回字符串：所有 execute 方法必须返回 str，LLM 读取此结果
• 错误处理：捕获所有异常，返回友好错误信息（不要抛出异常）
• 参数默认值：所有参数设置默认值（空字符串 "" 或 0），避免 LLM 漏传参数时报错
• 沙箱集成：需要路径验证的使用 PathValidator，需要命令过滤的使用 CommandValidator

沙箱集成示例

def execute(self, path="", **kwargs) -> str:
    from cococat.core.sandbox_path import PathValidator
    PROJECT_ROOT = Path(__file__).resolve().parent.parent
    pv = PathValidator()
    is_safe, reason = pv.validate(path, PROJECT_ROOT)
    if not is_safe:
        return f"Error: {reason}"
    # 继续工具逻辑...

第三步：注册到默认注册表

在 create_default_registry() 函数中注册新工具：

def create_default_registry(...) -> ToolRegistry:
    registry = ToolRegistry()
    # ... 已有工具 ...
    registry.register(MyNewTool())
    return registry

第四步：验证

启动 agent 后，调用 list_skills 或检查 system prompt 中的工具描述，确认新工具已加载。也可以通过发送一条触发该工具的 prompt 进行端到端测试。

完整示例

class GreetUserTool(Tool):
    name = "greet_user"
    description = "Send a greeting message to the user"
    required_permission = PermissionMode.READONLY
    parameters = {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "User name to greet"},
        },
        "required": ["name"],
    }

    def execute(self, name="", **kwargs) -> str:
        return f"Hello, {name}! Welcome to CocoCat."

然后在 create_default_registry() 中 registry.register(GreetUserTool())。