游戏代理

Name: 游戏代理
Author: korchasa

作者：korchasa4 星标更新：2025-11-20

安装使用来源：spider==github.com

项目介绍

Speelka Agent

基于模型上下文协议（MCP）的通用大语言模型代理，支持外部工具、灵活配置和可扩展日志。

主要特性

多代理编排：支持其他MCP服务器的工具。
灵活配置：YAML、JSON、环境变量、覆盖层和基于属性的覆盖层。
可扩展日志：集中式LogConfig，输出到stdout、stderr、文件、MCP协议、自定义/json/text格式。
安全性：密钥隔离、日志保护、工具访问控制。
测试：黄金序列化测试、基于属性的覆盖层、单元/集成/E2E测试。
可扩展性：支持HTTP和stdio，动态工具/会话管理。

架构

所有组件都是接口驱动的，经过测试，并遵循单一职责原则。
详情见documents/architecture.md。

示例配置（YAML）

runtime:
  log:
    defaultLevel: info
    output: ':mcp:'
    format: json
  transports:
    stdio:
      enabled: true
      buffer_size: 1024
    http:
      enabled: false
      host: localhost
      port: 3000
agent:
  name: "speelka-agent"
  version: "v1.0.0"
  tool:
    name: "process"
    description: "用于用户查询的过程工具"
    argument_name: "input"
    argument_description: "用户查询"
  chat:
    max_tokens: 0
    max_llm_iterations: 25
    request_budget: 0.0
  llm:
    provider: "openai"
    apiKey: "dummy-api-key"
    model: "gpt-4o"
    temperature: 0.7
    promptTemplate: "您是一个乐于助人的助手。{{input}}。可用工具：{{tools}}"
    retry:
      max_retries: 3
      initial_backoff: 1.0
      max_backoff: 30.0
      backoff_multiplier: 2.0
  connections:
    mcpServers:
      time:
        command: "docker"
        args: ["run", "-i", "--rm", "mcp/time"]
        timeout: 10
      filesystem:
        command: "mcp-filesystem-server"
        args: ["/path/to/directory"]
    retry:
      max_retries: 2
      initial_backoff: 1.5
      max_backoff: 10.0
      backoff_multiplier: 2.5

日志

通过LogConfig管理：级别、格式、输出（stdout、stderr、文件、MCP）。
可通过协议或回退到stderr（对于stdio服务器）获取MCP日志。
格式：自定义、json、文本、未知。
详情见documents/architecture.md和documents/implementation.md。

测试

单元、集成、E2E测试。
基于属性的覆盖层测试（边缘案例、映射合并、零值保留）。
测试示例：documents/implementation.md。

项目结构

详情见documents/file_structure.md。
关键目录：internal/agent、internal/logger、internal/mcp_connector、internal/types。

快速开始

克隆仓库并构建代理：

git clone https://github.com/korchasa/speelka-agent-go.git
cd speelka-agent-go
go build ./cmd/server

准备配置（参见上面的示例）或使用环境变量（SPL_...）。
运行代理：
- HTTP模式：./speelka-agent --daemon [--config config.yaml]
- CLI/stdio：./speelka-agent [--config config.yaml]

文档

关于覆盖层、MCP日志、测试和结构细节，请参阅documents/文件夹中的文档。

flowchart TB
    User["任何MCP客户端"] --> |"1.请求"| Agent["Speelka Agent"]
    Agent --> |"2.格式化提示"| LLM["LLM服务"]
    LLM --> |"3.调用工具"| Agent
    Agent --> |"4.执行工具"| Tools["外部MCP工具"]
    Tools --> |"5.返回结果"| Agent
    Agent --> |"6.处理重复"| LLM
    Agent --> |"7.最终答案"| User

使用场景

通过将大型复杂指令拆分为专门且聚焦的任务来提高准确性。
通过使用不同的模型来处理不同任务部分以降低成本。
扩展、缩小或修改第三方MCP服务器响应。
在“真实”和基于LLM的工具实现之间轻松切换。
通过限制MCP服务器中可用的工具来限制功能。
在单个会话中跨多个MCP工具编排多步骤工作流。
对每个请求的令牌和成本预算进行预测使用。
对瞬时LLM或MCP服务器错误自动重试和指数退避。
通过统一配置在LLM服务（OpenAI、Anthropic）之间无缝切换提供者。

主要特性

精确代理定义：通过提示工程定义代理行为
客户端上下文优化：减少上下文大小以高效使用令牌
LLM灵活性：在客户端和代理端使用不同的LLM提供商
集中式工具管理：所有工具的单一控制点
多种集成选项：MCP stdio、MCP HTTP、简单HTTP API
内置可靠性：瞬时故障的重试机制
可扩展性：无需更改客户端即可扩展系统行为
MCP感知日志：带有MCP通知的结构化日志
令牌管理：自动令牌计数
灵活配置：环境变量、YAML、JSON
LLMService.SendRequest 返回一个 LLMResponse 结构，包含：
- 响应文本
- 工具调用列表
- CompletionTokens、PromptTokens、ReasoningTokens、TotalTokens（令牌使用情况）
接口：SendRequest(ctx, messages, tools) (LLMResponse, error)

开始使用

预备条件

Go 1.19 或更高版本
LLM API 凭证（OpenAI 或 Anthropic）
外部 MCP 工具（可选）

安装

git clone https://github.com/korchasa/speelka-agent-go.git
cd speelka-agent-go
go build ./cmd/server

配置

可以通过 YAML、JSON 或环境变量提供配置。

注意：./examples 目录已弃用。请使用 ./site/examples 中的示例。

示例配置文件位于 site/examples：

site/examples/minimal.yaml：基本代理配置（YAML）
site/examples/ai-news.yaml：AI新闻代理配置（YAML）
site/examples/architect.yaml：架构师代理配置（YAML）

简单的 YAML 配置示例：

agent:
  name: "simple-speelka-agent"
  version: "1.0.0"
  tool:
    name: "process"
    description: "使用LLM处理用户查询的过程工具"
    argument_name: "input"
    argument_description: "要处理的用户查询"
  llm:
    provider: "openai"
    apiKey: ""  # 通过环境变量设置以保证安全
    model: "gpt-4o"
    temperature: 0.7
    promptTemplate: "您是一个乐于助人的AI助手。请回复以下请求：{{input}}。提供详细且有用的答复。可用工具：{{tools}}"
  chat:
    max_tokens: 0
    max_llm_iterations: 25
    request_budget: 0.0
  connections:
    mcpServers:
      time:
        command: "docker"
        args: ["run", "-i", "--rm", "mcp/time"]
        includeTools:
          - now
          - utc
      filesystem:
        command: "mcp-filesystem-server"
        args: ["/path/to/directory"]
        excludeTools:
          - delete
runtime:
  log:
    level: "info"
  transports:
    stdio:
      enabled: true

使用环境变量

所有环境变量都以前缀 SPL_ 开头：

环境变量	默认值	描述
代理配置
`SPL_AGENT_NAME`	必需	代理名称
`SPL_AGENT_VERSION`	"1.0.0"	代理版本
工具配置
`SPL_AGENT_TOOL_NAME`	必需	代理提供的工具名称
`SPL_AGENT_TOOL_DESCRIPTION`	必需	工具功能描述
`SPL_AGENT_TOOL_ARGUMENT_NAME`	必需	工具参数名称
`SPL_AGENT_TOOL_ARGUMENT_DESCRIPTION`	必需	工具参数描述
LLM配置
`SPL_AGENT_LLM_PROVIDER`	必需	LLM服务提供商（例如，“openai”，“anthropic”）
`SPL_AGENT_LLM_APIKEY`	必需	LLM提供商的API密钥
`SPL_AGENT_LLM_MODEL`	必需	模型名称（例如，“gpt-4o”，“claude-3-opus-20240229”）
`SPL_AGENT_LLM_MAX_TOKENS`	0	最大生成令牌数（0表示无限制）
`SPL_AGENT_LLM_TEMPERATURE`	0.7	生成过程中的随机性温度参数
`SPL_AGENT_LLM_PROMPTTEMPLATE`	必需	系统提示模板（必须包含与 `SPL_AGENT_TOOL_ARGUMENT_NAME` 值匹配的占位符和 `{{tools}}`）
聊天配置
`SPL_AGENT_CHAT_MAX_LLM_ITERATIONS`	100	最大LLM迭代次数
`SPL_AGENT_CHAT_MAX_TOKENS`	0	聊天历史记录的最大令牌数（0表示基于模型）
`SPL_AGENT_CHAT_REQUEST_BUDGET`	1.0	每个请求的最大成本（美元或等价令牌数）（0=无限）
LLM重试配置
`SPL_AGENT_LLM_RETRY_MAX_RETRIES`	3	LLM API调用的最大重试次数
`SPL_AGENT_LLM_RETRY_INITIAL_BACKOFF`	1.0	初始退避时间（秒）
`SPL_AGENT_LLM_RETRY_MAX_BACKOFF`	30.0	最大退避时间（秒）
`SPL_AGENT_LLM_RETRY_BACKOFF_MULTIPLIER`	2.0	增加退避时间的乘数
MCP服务器配置
`SPL_AGENT_CONNECTIONS_MCPSERVERS_0_ID`	""	第一个MCP服务器的标识符
`SPL_AGENT_CONNECTIONS_MCPSERVERS_0_COMMAND`	""	执行第一个服务器的命令
`SPL_AGENT_CONNECTIONS_MCPSERVERS_0_ARGS`	""	命令参数作为空格分隔的字符串
`SPL_AGENT_CONNECTIONS_MCPSERVERS_0_ENV_*`	""	服务器的环境变量（前缀为 `SPL_AGENT_CONNECTIONS_MCPSERVERS_0_ENV_`）
`SPL_AGENT_CONNECTIONS_MCPSERVERS_1_ID` 等	""	额外服务器的配置（递增索引）
MCP重试配置
`SPL_AGENT_CONNECTIONS_RETRY_MAX_RETRIES`	3	MCP服务器连接的最大重试次数
`SPL_AGENT_CONNECTIONS_RETRY_INITIAL_BACKOFF`	1.0	初始退避时间（秒）
`SPL_AGENT_CONNECTIONS_RETRY_MAX_BACKOFF`	30.0	最大退避时间（秒）
`SPL_AGENT_CONNECTIONS_RETRY_BACKOFF_MULTIPLIER`	2.0	增加退避时间的乘数
运行时配置
`SPL_RUNTIME_LOG_DEFAULTLEVEL`	"info"	日志默认级别（debug、info、warn、error）
`SPL_RUNTIME_LOG_OUTPUT`	":stderr:"	日志输出目标（:stdout:、:stderr:、:mcp:、文件路径）
`SPL_RUNTIME_STDIO_ENABLED`	true	启用stdin/stdout传输
`SPL_RUNTIME_STDIO_BUFFER_SIZE`	8192	stdio传输的缓冲区大小
`SPL_RUNTIME_HTTP_ENABLED`	false	启用HTTP传输
`SPL_RUNTIME_HTTP_HOST`	"localhost"	HTTP服务器主机
`SPL_RUNTIME_HTTP_PORT`	3000	HTTP服务器端口

更多详情，请参阅环境变量参考。

运行代理

守护进程模式（HTTP服务器）

./speelka-agent --daemon [--config config.yaml]

CLI模式（标准输入/输出）

./speelka-agent [--config config.yaml]

使用示例

HTTP API

当以守护进程模式运行时，代理暴露HTTP端点：

# 向代理发送请求
curl -X POST http://localhost:3000/message -H "Content-Type: application/json" -d '{
  "method": "tools/call",
  "params": {
    "name": "process",
    "arguments": {
      "input": "您的查询在这里"
    }
  }
}'

外部工具集成

在您的YAML配置中使用MCP协议连接到外部工具：

agent:
  # ... 其他代理配置 ...
  connections:
    mcpServers:
      # Playwright浏览器自动化MCP服务器
      playwright:
        command: "mcp-playwright"
        args: []

      # 文件系统操作MCP服务器
      filesystem:
        command: "mcp-filesystem-server"
        args: ["."]

或者使用环境变量：

# Playwright浏览器自动化MCP服务器
export SPL_AGENT_CONNECTIONS_MCPSERVERS_0_ID="playwright"
export SPL_AGENT_CONNECTIONS_MCPSERVERS_0_COMMAND="mcp-playwright"
export SPL_AGENT_CONNECTIONS_MCPSERVERS_0_ARGS=""

# 文件系统操作MCP服务器
export SPL_AGENT_CONNECTIONS_MCPSERVERS_1_ID="filesystem"
export SPL_AGENT_CONNECTIONS_MCPSERVERS_1_COMMAND="mcp-filesystem-server"
export SPL_AGENT_CONNECTIONS_MCPSERVERS_1_ARGS="."

支持的LLM提供商

OpenAI：GPT-3.5、GPT-4、GPT-4o
Anthropic：Claude模型

文档

更多详情，请参阅：

开发

运行测试

go test ./...

辅助命令

run 脚本提供了常见操作的命令：

# 开发
./run build        # 构建项目
./run test         # 运行带覆盖率的测试
./run check        # 运行所有检查
./run lint         # 运行代码检查器

# 交互
./run call         # 使用简单查询测试
./run call-multistep # 使用多步查询测试
./run call-news    # 测试新闻代理
./run fetch_url    # 使用MCP抓取URL

# 检查
./run inspect      # 使用MCP检查器运行

更多选项，请参阅命令参考。

许可证

MIT许可证

MCP服务器工具过滤

您可以在 mcpServers 部分使用以下选项来控制从每个MCP服务器导出哪些工具：

includeTools：（可选）要包含的工具名称列表。只有这些工具将从服务器中可用。
excludeTools：（可选）要排除的工具名称列表。这些工具将不可用。
如果两者都设置，则首先应用 includeTools，然后是 excludeTools。
工具名称区分大小写。

示例：

connections:
  mcpServers:
    time:
      command: "docker"
      args: ["run", "-i", "--rm", "mcp/time"]
      includeTools:
        - now
        - utc
    filesystem:
      command: "mcp-filesystem-server"
      args: ["/path/to/directory"]
      excludeTools:
        - delete

直接调用模式

您可以将代理运行在直接调用模式下，以处理单个查询并输出JSON