核心概念

Recipe 配置系统

声明式 Agent 配置和可复用模板

Recipe 配置系统

Recipe 是 Aster 的声明式 Agent 配置系统，允许通过 YAML 文件定义可复用的 Agent 模板。

🎯 核心概念

Recipe 将 Agent 配置抽象为声明式的 YAML 文件，包括：

📝 指令和提示 - 系统提示和初始消息
🔧 工具配置 - 启用的工具列表
🔌 MCP 扩展 - 外部服务集成
📊 参数化 - 可配置的参数
🔐 权限模式 - 工具审批策略

📋 Recipe 结构

version: "1.0"
title: My Assistant
description: 助手描述

# 系统指令
instructions: |
  你是一个专业的助手...

# 初始提示（可选）
prompt: 请帮我完成任务

# 启用的工具
tools:
  - Read
  - Write
  - Bash
  - Search

# MCP 扩展
extensions:
  - type: stdio
    name: github
    cmd: npx
    args: ["-y", "@anthropics/mcp-github"]
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"

# 可配置参数
parameters:
  - key: project_name
    input_type: string
    requirement: required
    description: 项目名称

# 权限模式
permission_mode: smart_approve

# 建议活动
activities:
  - 审查代码
  - 写测试
  - 修复 Bug

# 作者信息
author:
  name: Your Name
  url: https://github.com/you

🚀 快速开始

从 YAML 加载

import "github.com/astercloud/aster/pkg/recipe"

// 加载 Recipe
r, err := recipe.Load("./recipes/code-review.yaml")
if err != nil {
    log.Fatal(err)
}

// 验证 Recipe
if err := r.Validate(); err != nil {
    log.Printf("验证警告: %v", err)
}

fmt.Printf("标题: %s\n", r.Title)
fmt.Printf("工具: %v\n", r.Tools)

使用 Builder 创建

r := recipe.NewBuilder().
    WithTitle("Code Review Assistant").
    WithDescription("专业的代码审查助手").
    WithVersion("1.0").
    WithInstructions(`你是专业的代码审查专家。
请仔细检查代码质量、安全性和最佳实践。`).
    WithTools("Read", "List", "Search", "Bash").
    WithPermissionMode(recipe.PermissionModeSmartApprove).
    WithActivities(
        "审查 PR 代码",
        "检查安全漏洞",
        "优化性能",
    ).
    Build()

// 保存为 YAML
r.Save("./my-recipe.yaml")

🔌 MCP 扩展

stdio 类型

启动外部进程作为 MCP 服务：

extensions:
  - type: stdio
    name: github
    description: GitHub API 集成
    cmd: npx
    args:
      - "-y"
      - "@anthropics/mcp-github"
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"
    timeout: 30
    enabled: true

sse 类型

连接远程 MCP 服务：

extensions:
  - type: sse
    name: search
    description: 搜索服务
    url: http://localhost:3000/mcp
    timeout: 10
    enabled: true

builtin 类型

使用内置扩展：

extensions:
  - type: builtin
    name: filesystem
    description: 文件系统工具
    enabled: true

📝 参数化

参数类型

类型	说明	示例
`string`	文本输入	项目名称
`number`	数字输入	并发数
`boolean`	布尔开关	是否启用测试
`select`	下拉选择	编程语言
`file`	文件选择	配置文件路径

定义参数

parameters:
  - key: language
    input_type: select
    requirement: required
    description: 编程语言
    default: go
    options:
      - go
      - python
      - typescript
      - rust

  - key: with_tests
    input_type: boolean
    requirement: optional
    description: 是否包含测试模板
    default: true

  - key: project_name
    input_type: string
    requirement: required
    description: 项目名称
    validation:
      pattern: "^[a-z][a-z0-9-]*$"
      message: 项目名称只能包含小写字母、数字和连字符

在提示中使用参数

prompt: |
  请为我创建一个名为 {{project_name}} 的 {{language}} 项目。
  {{#if with_tests}}包含测试模板。{{/if}}

🔐 权限模式

三种模式

# 自动批准所有操作（开发环境）
permission_mode: auto_approve

# 智能审批（推荐）
permission_mode: smart_approve

# 所有操作都需确认（高安全性）
permission_mode: always_ask

与 Permission 系统集成

import (
    "github.com/astercloud/aster/pkg/permission"
    "github.com/astercloud/aster/pkg/recipe"
)

r, _ := recipe.Load("./my-recipe.yaml")

// 根据 Recipe 配置创建 Inspector
var mode permission.Mode
switch r.PermissionMode {
case recipe.PermissionModeAutoApprove:
    mode = permission.ModeAutoApprove
case recipe.PermissionModeSmartApprove:
    mode = permission.ModeSmartApprove
case recipe.PermissionModeAlwaysAsk:
    mode = permission.ModeAlwaysAsk
}

inspector, _ := permission.NewInspector(
    permission.WithMode(mode),
)

🔄 与 Agent 集成

转换为 Agent 配置

import (
    "github.com/astercloud/aster/pkg/agent"
    "github.com/astercloud/aster/pkg/recipe"
)

// 加载 Recipe
r, _ := recipe.Load("./recipes/code-review.yaml")

// 转换为 Agent 配置
agentConfig := r.ToAgentConfig()

// 补充运行时配置
agentConfig.ModelConfig = &types.ModelConfig{
    Provider: "anthropic",
    Model:    "claude-sonnet-4-5",
    APIKey:   os.Getenv("ANTHROPIC_API_KEY"),
}

agentConfig.Sandbox = &types.SandboxConfig{
    Kind:    types.SandboxKindLocal,
    WorkDir: "./workspace",
}

// 创建 Agent
ag, err := agent.Create(ctx, agentConfig, deps)

使用 Recipe 启动对话

// 获取初始提示
if r.Prompt != "" {
    // 发送初始消息
    ag.Send(ctx, r.Prompt)
}

// 显示建议活动
fmt.Println("建议活动:")
for _, activity := range r.Activities {
    fmt.Printf("  - %s\n", activity)
}

📚 示例 Recipe

代码审查助手

version: "1.0"
title: Code Review Assistant
description: 专业的代码审查助手

instructions: |
  你是一个专业的代码审查专家。你的职责是：
  1. 分析代码质量和可读性
  2. 发现潜在的 Bug 和安全问题
  3. 提供改进建议和最佳实践

  请遵循以下原则：
  - 给出具体的代码示例
  - 解释为什么某些做法更好
  - 保持友好但专业的语气

tools:
  - Read
  - List
  - Search
  - Bash

permission_mode: smart_approve

activities:
  - 审查这个 PR 的代码
  - 检查是否有安全漏洞
  - 分析代码复杂度
  - 检查测试覆盖率

写作助手

version: "1.0"
title: Writing Assistant
description: 帮助撰写和编辑文档

instructions: |
  你是专业的写作助手，擅长：
  - 文章撰写和润色
  - 语法和风格检查
  - 结构优化建议
  - 多语言翻译

tools:
  - Read
  - Write
  - Search

parameters:
  - key: style
    input_type: select
    description: 写作风格
    default: professional
    options:
      - professional
      - casual
      - academic

permission_mode: smart_approve

activities:
  - 帮我润色这篇文章
  - 检查语法错误
  - 翻译成英文
  - 优化文章结构

💡 最佳实践

1. 版本控制

version: "1.0"  # 使用语义化版本

2. 清晰的指令

instructions: |
  # 角色定义
  你是一个专业的...

  # 行为准则
  1. 规则一
  2. 规则二

  # 输出格式
  请按以下格式输出...

3. 合理的权限

# 只启用必要的工具
tools:
  - Read
  - Search
  # 不需要 Bash 就不启用

# 使用智能审批
permission_mode: smart_approve

📚 相关文档

Permission 系统 - 权限配置详解
MCP 扩展 - MCP 集成指南
Agent 配置 - Agent 生命周期

🔗 示例代码

# 运行 Recipe 示例
go run ./examples/recipe/

# 查看示例 Recipe 文件
cat examples/recipes/code-review.yaml
cat examples/recipes/writing-assistant.yaml

Edit this pageorReport an issue

SQLite 会话存储

使用 SQLite 持久化 Agent 会话，适用于桌面应用和单机场景

执行计划 (Execution Plan)

执行计划是 Aster 中用于管理复杂多步骤任务的核心功能。它允许 Agent 将复杂任务分解为多个步骤，支持依赖管理、并行执行、审批流程和错误处理。