Goose-Perception项目中的Recipe文件规范详解

前言

在Goose-Perception项目中，Recipe文件扮演着至关重要的角色。它本质上是一个JSON/YAML格式的配置文件，能够将Goose转变为功能完备、预先配置好的智能代理。本文将深入解析Recipe文件的规范细节，帮助开发者更好地理解和运用这一强大功能。

核心概念

Recipe文件的核心价值在于其可移植性和预配置能力。通过一个简单的配置文件，开发者可以：

1. 定义智能代理的行为模式
2. 配置所需的扩展功能
3. 预设用户交互流程
4. 控制模型参数和运行环境

文件结构详解

1. 顶层结构

Recipe文件的顶层结构包含多个关键字段：

• version：文件格式版本号，遵循semver规范
• title：代理的简短名称（必填）
• description：代理功能的简要描述（必填）
• instructions/prompt：至少需要提供其中一个
  • instructions：系统级别的角色设定指令
  • prompt：用户可见的首条助手消息
• extensions：扩展功能配置数组
• context：附加的上下文片段
• settings：模型和运行参数设置
• activities：UI快速操作项
• author：作者信息
• parameters：用户输入参数定义

2. 基本示例

最小配置示例

{
  "title": "问候机器人",
  "description": "友好地向用户打招呼",
  "instructions": "始终以欢快的语气问候用户"
}

完整功能示例

{
  "version": "1.2.0",
  "title": "周报生成器",
  "description": "汇总Jira问题，生成Markdown格式报告并发送邮件",
  "prompt": "您好！请提供Jira看板URL和截止日期",
  "extensions": [
    {
      "type": "sse",
      "name": "jira",
      "uri": "https://jira.example.com/sse",
      "env_keys": ["JIRA_TOKEN"],
      "timeout": 30
    },
    {
      "type": "builtin",
      "name": "email"
    }
  ],
  "settings": { 
    "goose_provider": "openai", 
    "goose_model": "gpt-4o-mini", 
    "temperature": 0.3 
  },
  "activities": ["生成", "优化", "发送"],
  "author": { "contact": "[e-mail]" },
  "parameters": [
    { 
      "key": "jira_board", 
      "input_type": "string", 
      "requirement": "required", 
      "description": "完整的看板URL" 
    },
    { 
      "key": "due_date",   
      "input_type": "date",   
      "requirement": "user_prompt", 
      "description": "截止日期是什么时候？" 
    }
  ]
}

嵌套对象详解

1. 作者信息(Author)

• contact：联系方式（邮箱/网站/社交媒体）
• metadata：自由格式的元数据（如许可证信息）

2. 设置参数(Settings)

• goose_provider：AI服务提供商（如openai、anthropic等）
• goose_model：具体模型名称（如gpt-4、claude-3等）
• temperature：创意度参数（0-2.0）

3. 输入参数(Parameters)

• key：参数标识符（用于模板替换）
• input_type：输入类型（字符串/数字/布尔值/日期/文件）
• requirement：必填要求
  • required：必须提供
  • optional：可选
  • user_prompt：首次运行时弹出对话框
• description：参数说明
• default：默认值

扩展功能配置

扩展功能是Recipe文件中最强大的部分，支持多种集成方式：

1. 通用字段

• name：唯一标识符
• timeout：超时设置（秒）
• bundled：是否为内置扩展
• description：功能描述
• envs：显式环境变量
• env_keys：允许透传的环境变量名

2. 扩展类型

SSE扩展

通过Server-Sent Events协议连接远程服务

{
  "type": "sse",
  "name": "向量搜索",
  "uri": "http://localhost:8008/sse",
  "description": "向量嵌入和语义搜索",
  "timeout": 20,
  "env_keys": ["VECTOR_API_KEY"]
}

STDIO扩展

通过标准输入输出与子进程通信

{
  "type": "stdio",
  "name": "图像处理",
  "cmd": "/usr/local/bin/python",
  "args": ["image_tools.py"],
  "envs": { "PYTHONUNBUFFERED": "1" },
  "timeout": 45
}

内置扩展

直接使用Goose内置功能

{ "type": "builtin", "name": "filesystem" }

前端扩展

由前端实现的工具

{
  "type": "frontend",
  "name": "浏览器自动化",
  "tools": [
    {
      "name": "打开URL",
      "description": "在Safari中打开URL",
      "parameters": ["url"]
    }
  ],
  "instructions": "仅对http(s)链接使用open_url"
}

最佳实践

1. 命名规范：建议使用.recipe.json或.recipe.yaml作为文件后缀
2. 参数设计：合理使用required/user_prompt控制用户输入流程
3. 扩展选择：根据功能需求选择最适合的扩展类型
4. 安全考虑：谨慎处理环境变量和外部连接

常见场景配置速查

目标场景	需要配置的关键字段
基础聊天机器人	title, description, instructions
带欢迎语的聊天机器人	增加prompt字段
集成外部工具	配置extensions数组
收集用户输入	定义parameters数组
指定模型和风格	设置settings中的模型和temperature参数

总结

Goose-Perception的Recipe文件提供了一种高度灵活且强大的方式来定义和配置智能代理。通过掌握本文介绍的规范细节，开发者可以创建出功能丰富、交互友好的AI应用。无论是简单的聊天机器人还是复杂的业务自动化流程，都可以通过精心设计的Recipe文件来实现。