Skip to content

zzfx1166/minecraft-command-agent

BranchesTags

Repository files navigation

Minecraft Command Agent

AI-assisted Minecraft server automation mod for Forge 1.21.8.

它提供三层能力：

  • 通过 HTTP API 执行服务端命令、查询玩家状态、触发 AI 推理。
  • 在游戏内通过 /agent 命令与全局/私有 Agent 会话交互。
  • 通过 OpenAI-compatible 接口 + 工具调用，让模型直接编排服务器操作。

当前状态

  • 开发阶段（v0.1.0）。
  • 已有完整单元测试与本地构建流程。
  • 尚未大规模实服验证，建议先在测试服使用。

特性概览

  • Forge 1.21.8 + Java 21。
  • OpenAI-compatible 调用链（Chat Completions + Tools）。
  • 多提供商模型目录：OpenAI / Anthropic / Gemini。
  • 多会话：global + 私有会话 playername.xxx。
  • 会话级配置覆盖：model/systemPrompt/userPrompt。
  • 会话级权限系统：allow/deny/defaultPolicy + * / **。
  • 上下文压缩：手动 /agent compact + 阈值自动压缩。
  • 固定用户提示词（全局注入，支持文件）。
  • 模型互调：call_model（return / handoff）。
  • 工作流系统 V1：interval/cron 调度 + run_workflow 工具调用。

已实现工具

  • 基础：execute_command、get_player_state
  • 方块：set_block、get_block_data、merge_block_data
  • 实体：summon_entity、get_entity_data、merge_entity_data、kill_entity
  • 管理：ban_player、kick_player、unban_player
  • 联网：search_web、fetch_url
  • 模型：call_model
  • 工作流：run_workflow
  • 视觉（模型配置启用时）：get_item_texture

环境要求

  • JDK: 21
  • Minecraft: 1.21.8
  • Forge: 58.1.14

构建

GRADLE_USER_HOME=/tmp/gradle gradle --no-daemon build

产物位于 build/libs/。

GitHub Actions 自动构建

  • 工作流文件：.github/workflows/build.yml
  • 触发时机：每次 push 自动触发（同时支持手动 workflow_dispatch）
  • Gradle 版本：固定 8.12.1（Forge Gradle 目前不支持 9.x）
  • 构建命令：GRADLE_USER_HOME=/tmp/gradle gradle --no-daemon build
  • 产物上传：build/libs/*.jar 与 build/reports/**
  • Artifact 名称：minecraft-command-agent-<commit_sha>

快速开始

  1. 构建并将产物放入服务器 mods/。
  2. 启动服务器一次，生成 config/minecraft-command-agent/server-config.json 与其它 JSON 配置文件。
  3. 配置 AI：在 config/minecraft-command-agent/models.json 填写 providers[].apiKey、baseUrl、模型映射。
  4. 在 config/minecraft-command-agent/server-config.json 中设置 api.bearerToken（默认是 change-me，必须修改）。
  5. （可选）按需调整 config/minecraft-command-agent/permissions.json 与 config/minecraft-command-agent/workflows.json。
  6. 重启服务器，开始调用。

HTTP API

默认监听：127.0.0.1:8787。

鉴权头：

Authorization: Bearer <api.bearerToken>

1) 执行命令

POST /v1/command

{
  "command": "time set day"
}

2) 查询玩家状态

GET /v1/players/{username}/state

返回字段：dimension + x/y/z + yaw/pitch + sampledAt

3) AI 运行

POST /v1/ai/run

{
  "prompt": "把 Steve 传送到主城",
  "source": "[http]",
  "model": "openai.default",
  "systemPrompt": "",
  "maxIterations": 8
}

说明：

  • model/systemPrompt/maxIterations/source 都是可选。
  • 当前 HTTP 入口固定走 global 会话。

游戏内命令

默认要求权限等级：OP3+（可配置）。

  • /agent chat <message>
  • /agent cancel
  • /agent compact
  • /agent reset
  • /agent chatswitch list
  • /agent chatswitch new <id>
  • /agent chatswitch <id|global>
  • /agent chatconfig <chat> <model|systemPrompt|userPrompt> <value|inherit>
  • /agent perm reload
  • /agent workflow list
  • /agent workflow reload
  • /agent workflow run <id> [input]

备注：/agent model 已废弃，改用 chatconfig。

配置参考（完整）

下面是当前代码中所有可配置项。
配置来源分为 5 类：

  • config/minecraft-command-agent/server-config.json
  • config/minecraft-command-agent/models.json
  • config/minecraft-command-agent/permissions.json
  • config/minecraft-command-agent/workflows.json
  • config/minecraft-command-agent/chats.json（运行时状态持久化）

1) 服务端配置 server-config.json

键 类型 默认值 范围/约束 说明
api.host string 127.0.0.1 非空字符串 HTTP API 监听地址
api.port int 8787 1..65535 HTTP API 监听端口
api.bearerToken string change-me 非空且建议高强度随机串 HTTP 鉴权 Bearer Token；保留默认值时 API 会被禁用
api.commandTimeoutMs int 5000 500..30000 执行命令/查询玩家状态超时
openai.requestTimeoutMs int 30000 1000..180000 模型请求超时（provider 未单独设置 timeout 时生效）
openai.maxToolIterations int 8 -1 或 >=1（无上限） 单轮推理工具调用循环上限；-1=不限制
agent.contextMaxMessages int 30 4..200 会话滚动上下文最大条数
agent.fixedUserPrompt string "" 可空 固定用户提示词（每次模型调用注入）
agent.fixedUserPromptFile string "" 可空；支持相对/绝对路径 固定用户提示词文件路径；非空时优先于 agent.fixedUserPrompt
agent.reasonTemplates string[] `["default Default moderation reason=Player {player} was moderated by {actor}. Reason: {input}. Time: {time}"]` 每项需 `key
agent.autoCompactEnabled boolean true true/false 是否启用自动上下文压缩
agent.compactAutoThresholdTokens int 12000 512..200000 触发自动压缩的 token 估算阈值
agent.compactTargetTokens int 5000 128..200000 压缩目标 token 估算值
agent.compactKeepRecentMessages int 4 0..64 压缩后保留的最近原始消息条数
agent.maxModelCallDepth int 3 -1 或 >=0（无上限） call_model 最大递归深度；0=禁用模型互调，-1=不限制
agent.maxModelCallsPerRun int 8 -1 或 >=0（无上限） 单次运行最大 call_model 次数；0=禁用模型互调，-1=不限制
agent.commandPermissionLevel int 3 0..4 游戏内 /agent 命令权限等级

模板变量说明（agent.reasonTemplates）：

  • 仅支持 {player}、{actor}、{input}、{time}
  • 其他变量会在运行时报错
  • 模板格式：key|description=template
  • 其中 description 可省略（写成 key=template 也可）
  • none 为保留 key，表示不使用模板，直接使用 reasonInput
  • templateKey 必须匹配 [a-z0-9_-]{1,32}

示例文件（config/minecraft-command-agent/server-config.json）：

{
  "api.host": "127.0.0.1",
  "api.port": 8787,
  "api.bearerToken": "replace-with-long-random-token",
  "api.commandTimeoutMs": 5000,
  "openai.requestTimeoutMs": 30000,
  "openai.maxToolIterations": 8,
  "agent.contextMaxMessages": 30,
  "agent.fixedUserPrompt": "",
  "agent.fixedUserPromptFile": "",
  "agent.reasonTemplates": [
    "default|Default moderation reason=Player {player} was moderated by {actor}. Reason: {input}. Time: {time}",
    "cheat|Cheat detected=Player {player} was punished by {actor}. Cheat evidence: {input}. Time: {time}"
  ],
  "agent.autoCompactEnabled": true,
  "agent.compactAutoThresholdTokens": 12000,
  "agent.compactTargetTokens": 5000,
  "agent.compactKeepRecentMessages": 4,
  "agent.maxModelCallDepth": 3,
  "agent.maxModelCallsPerRun": 8,
  "agent.commandPermissionLevel": 3
}

2) 模型目录 models.json

路径：config/minecraft-command-agent/models.json
说明：该文件必须存在且合法，启动时会加载。

顶层字段

字段 类型 必填 默认 约束/说明
defaultModelKey string 是 无 必须存在于 models[].key
compactModelKey string 否 回落到 defaultModelKey 必须存在于 models[].key
providers array 是 无 非空
models array 是 无 非空

providers[] 字段

字段 类型 必填 默认 约束/说明
alias string 是 无 非空；不能包含 .
type string 是 无 支持：openai/openai-compatible、anthropic、gemini/google
baseUrl string 是 无 provider API 基础地址
apiKey string 是 无 provider API Key
timeoutMs int 否 null 1000..180000；设置后覆盖全局 openai.requestTimeoutMs
headers object<string,string> 否 {} 附加请求头

models[] 字段

字段 类型 必填 默认 约束/说明
key string 是 无 格式 providerAlias.modelAlias
providerAlias string 否 从 key 前缀推导 若显式填写，必须与 key 前缀一致
description string 否 "" 供模型互调选择参考
upstreamModel string 是 无 上游模型名
reasoningLevel string 否 null 推理强度提示（按 provider 自行处理）
enableVision boolean 否 false 开启后暴露 get_item_texture
networkTimeoutMs int 否 12000 1000..120000；search_web/fetch_url 等联网工具超时
networkMaxResponseBytes int 否 524288 4096..4194304；联网工具单次响应字节上限

额外语义：

  • 模型选择优先级：请求参数 model > 当前会话模型覆盖 > defaultModelKey
  • compact 固定使用 compactModelKey

示例文件（config/minecraft-command-agent/models.json）：

{
  "defaultModelKey": "openai.default",
  "compactModelKey": "openai.default",
  "providers": [
    {
      "alias": "openai",
      "type": "openai",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "sk-xxxx",
      "timeoutMs": 45000,
      "headers": {
        "X-Client-Name": "minecraft-command-agent"
      }
    },
    {
      "alias": "anthropic",
      "type": "anthropic",
      "baseUrl": "https://api.anthropic.com/v1",
      "apiKey": "sk-ant-xxxx"
    }
  ],
  "models": [
    {
      "key": "openai.default",
      "description": "General planner model",
      "upstreamModel": "gpt-4.1-mini",
      "reasoningLevel": "medium",
      "enableVision": false,
      "networkTimeoutMs": 12000,
      "networkMaxResponseBytes": 524288
    },
    {
      "key": "anthropic.default",
      "providerAlias": "anthropic",
      "description": "Long-form reasoning model",
      "upstreamModel": "claude-3-7-sonnet-latest",
      "enableVision": false,
      "networkTimeoutMs": 12000,
      "networkMaxResponseBytes": 524288
    }
  ]
}

3) 权限策略 permissions.json

路径：config/minecraft-command-agent/permissions.json
说明：文件不存在时会自动生成默认配置。

顶层结构

字段 类型 必填 默认 说明
chats object 是 无 key 是 chatId，value 是策略对象

chats.<chatId> 字段

字段 类型 必填 默认 说明
defaultPolicy string 否 deny allow 或 deny
allow string[] 否 [] 允许规则列表
deny string[] 否 [] 拒绝规则列表（优先级最高）

匹配与优先级：

  • 规则节点按 . 分段
  • * 匹配单段，** 匹配多段
  • 判定顺序：deny > allow > defaultPolicy
  • 若目标会话无独立策略，回退 chats.global

默认生成内容：

  • chats.global.defaultPolicy = "deny"
  • chats.global.allow = ["tools.**"]
  • chats.global.deny = []

常用权限节点示例：

  • tools.execute_command
  • tools.command.tp.<targets>
  • tools.command.ban-ip.<target>
  • tools.ban_player.cheat
  • tools.ban_player.none
  • tools.kick_player.warn
  • tools.run_workflow
  • tools.run_workflow.hourly_audit

示例文件（config/minecraft-command-agent/permissions.json）：

{
  "chats": {
    "global": {
      "defaultPolicy": "deny",
      "allow": [
        "tools.get_player_state",
        "tools.search_web",
        "tools.fetch_url",
        "tools.command.say",
        "tools.ban_player.cheat",
        "tools.ban_player.none",
        "tools.run_workflow.hourly_audit"
      ],
      "deny": [
        "tools.command.op.**",
        "tools.command.stop",
        "tools.ban_player.**",
        "tools.kick_player.**"
      ]
    },
    "steve.audit": {
      "defaultPolicy": "allow",
      "allow": [],
      "deny": [
        "tools.command.ban.**",
        "tools.command.ban-ip.**",
        "tools.command.pardon.**"
      ]
    }
  }
}

4) 工作流配置 workflows.json

路径：config/minecraft-command-agent/workflows.json
说明：文件不存在时会自动生成示例。

顶层结构

字段 类型 必填 默认 说明
version int 否 无 目前仅作保留字段
workflows array 是 无 工作流列表

workflows[] 字段

字段 类型 必填 默认 约束/说明
id string 是 无 匹配 [a-z0-9._-]{1,64}，全局唯一
description string 否 "" 工作流描述
enabled boolean 否 true 是否启用
boundChatId string 否 global 必须是 global 或 owner.alias
prompt string 是 无 工作流提示词
model string 否 null 覆盖会话默认模型
systemPrompt string/null 否 null 覆盖会话系统提示词
userPrompt string/null 否 null 覆盖会话用户提示词
allowManual boolean 否 true 是否允许 /agent workflow run
allowSessionCall boolean 否 true 是否允许工具 run_workflow 调用
schedules array 否 [] 定时触发列表

schedules[] 字段

字段 类型 必填 默认 约束/说明
type string 是 无 interval 或 cron
intervalSeconds int type=interval 时必填 无 1..604800
cron string type=cron 时必填 无 5 段表达式：分 时 日 月 周

cron 支持语法：

  • *
  • 单值：5
  • 列表：1,15,30
  • 区间：9-18
  • 步长：*/10、1-30/5
  • 周字段支持 0..7，其中 7 视为 0（周日）

触发语义：

  • 定时触发：使用空上下文
  • run_workflow 调用：复制调用方上下文快照（只读）
  • 手动 /agent workflow run：空上下文
  • 工作流执行结果不写回任何会话上下文
  • 同一 workflow 运行中再次触发会返回 WORKFLOW_BUSY

示例文件（config/minecraft-command-agent/workflows.json）：

{
  "version": 1,
  "workflows": [
    {
      "id": "hourly_audit",
      "description": "每小时分析玩家行为并输出风险摘要",
      "enabled": true,
      "boundChatId": "global",
      "prompt": "Inspect recent player activity and summarize suspicious behavior patterns.",
      "model": "openai.default",
      "systemPrompt": "You are a strict anti-cheat reviewer.",
      "userPrompt": "Only output actionable findings.",
      "allowManual": true,
      "allowSessionCall": true,
      "schedules": [
        {
          "type": "interval",
          "intervalSeconds": 3600
        },
        {
          "type": "cron",
          "cron": "0 * * * *"
        }
      ]
    },
    {
      "id": "nightly_report",
      "description": "每天 03:30 生成日报",
      "enabled": true,
      "boundChatId": "global",
      "prompt": "Generate a daily summary of server operations.",
      "allowManual": false,
      "allowSessionCall": false,
      "schedules": [
        {
          "type": "cron",
          "cron": "30 3 * * *"
        }
      ]
    }
  ]
}

5) 会话存储 chats.json

路径：config/minecraft-command-agent/chats.json
说明：运行时自动维护，建议通过命令管理而不是手改文件。

顶层结构

字段 类型 说明
version int 存储版本（当前写入 1）
global object 全局会话配置与上下文
privateChats array 私有会话列表
currentByOwner object 每个 owner 当前会话指针

global / privateChats[] 可覆盖字段

字段 类型 说明
model string/null 会话模型覆盖
systemPrompt string/null 会话系统提示词覆盖
userPrompt string/null 会话用户提示词覆盖
context string[] 会话上下文滚动窗口

privateChats[] 额外字段：

  • owner: 玩家名（小写）
  • alias: 会话别名，匹配 [a-z0-9_-]{1,32}，global 为保留值

currentByOwner：

  • key 是 owner（小写）
  • value 是当前别名（global 或某个私有 alias）

示例文件（config/minecraft-command-agent/chats.json，运行时自动生成/更新）：

{
  "version": 1,
  "global": {
    "model": "openai.default",
    "systemPrompt": "You are the global server agent.",
    "userPrompt": "",
    "context": [
      "[user][source:steve] 帮我查看在线玩家",
      "[assistant] 我先调用 get_player_state"
    ]
  },
  "privateChats": [
    {
      "owner": "steve",
      "alias": "build",
      "model": "anthropic.default",
      "systemPrompt": "Focus on building planning.",
      "userPrompt": "Prefer minimal commands.",
      "context": [
        "[user][source:steve] 设计一个中世纪塔楼",
        "[assistant] 我会先给出分步建造方案"
      ]
    }
  ],
  "currentByOwner": {
    "steve": "build",
    "alex": "global"
  }
}

运行语义（重要）

  • 并发粒度：普通对话按会话并发；工作流按 workflow id 并发保护。
  • 取消：/agent cancel 作用于当前会话运行任务。
  • 广播：工具调用与 Agent 文本结果会实时推送。
  • 工具执行输出本身不会广播。
  • 私有会话仅 owner + initiator 可见。

代码结构

  • Mod 入口：src/main/java/com/autominecraft/mod/AutoMinecraftMod.java
  • 编排器：src/main/java/com/autominecraft/mod/ai/AgentOrchestrator.java
  • AI 执行与工具：src/main/java/com/autominecraft/mod/ai/OpenAiAgentService.java
  • 模型目录：src/main/java/com/autominecraft/mod/ai/ModelRegistry.java
  • 权限目录：src/main/java/com/autominecraft/mod/ai/PermissionRegistry.java
  • 工作流目录：src/main/java/com/autominecraft/mod/ai/WorkflowRegistry.java
  • HTTP 服务：src/main/java/com/autominecraft/mod/http/HttpApiServer.java
  • 游戏命令注册：src/main/java/com/autominecraft/mod/command/AgentCommandRegistrar.java

开发文档

  • AGENTS.md: 项目约束与实现状态
  • Todo.md: 任务清单
  • write-by-AGENT.md: 上下文辅助记录

License

MIT

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages