一、引子1.1 四模型分工的游戏制作流水线设想一个场景用 AI 打造一套四模型分工的游戏制作流水线让 AI 自动完成从游戏设计到代码实现的全流程#角色模型职责1决策总监game-directorkimi-k2.6愿景/范围/里程碑/任务分解/验收决策2机制工程师gameplay-engineerdeepseek-v4-flashGDScript 机制、场景、UI、系统 自写测试3美术-机制桥blender-bridgedeepseek-v4-flash资产规格、资产集成验证、接口4美术专精blender-artistkimi-k2.6建模/材质/光照/特效这套流水线基于OpenHarness多模型 Agent 编排框架godot-aiGodot 编辑器的 MCP 服务器搭建也是我前段时间尝试搭建的一个工作流。1.2 五个问题速览#问题根因1godot-ai 插件加载失败源码检出目录与已安装插件全局类名冲突2MCP transport 参数错误http不是合法 transport必须用streamable-http3kimi 模型名过时kimi-k2.5已下线需用kimi-k2.64credentials.json 被误冲UTF-8 BOM 导致读失败覆盖写5中文 Windows 编码 Bug父进程写 UTF-8子进程用 GBK 读每个问题的根源恰恰对应着 OpenHarness 配置的关键环节。1.3 问题一godot-ai 插件加载失败这是搭建过程中最棘手的问题——MCP 服务器根本启动不起来。现象编辑器开着、插件启用了但端口 8000/9500 都没有进程监听OpenHarness 里 MCP 工具全部不可用。排查过程端口与进程检查Get-NetTCPConnection确认 8000/9500 无监听Get-CimInstance确认 Godot 编辑器在跑但无服务器进程读插件源码addons/godot_ai/client_configurator.gd确认端口 8000/9500 配置正确但editor_settings-4.7.tres中的managed_server_pid0说明插件从未成功启动服务器手动启动对照实验uv run godot-ai --transport streamable-http手动启动成功但session_manage返回count0——服务器通了编辑器没连上捕获编辑器启动日志用 console 版 Godot 重启并重定向 stderr发现大量全局类名冲突Class McpLogBacktrace hides a global script class数十条根因定位godot-ai-main源码检出目录含有plugin/addons/godot_ai插件的完整副本含class_name声明Godot 递归扫描res://把源码副本也当成项目内容 → 与已安装插件定义了相同全局类 → 插件编译失败 → 服务器永不启动修复在godot-ai-main/放.gdignore文件让 Godot 跳过删除.godot/类缓存重启编辑器验证pipeline.py ensure-server确认 MCP 在线、编辑器会话1、test_run 通过1.4 问题二MCP transport 参数踩坑现象uv run godot-ai --transport http --port 8000直接报错invalid choice: http根因OpenHarness 的type: http表示客户端用 HTTP 协议连接但 godot-ai 服务器端的--transport只接受stdio | sse | streamable-http没有http。修复使用--transport streamable-http。这个参数对应的握手协议不是简单 POST 一把梭而是POST /mcp发initialize→ 取Mcp-Session-Id→ 发notifications/initialized→ 发tools/list发现能力 → 正常调用tools/call。响应可能以 SSE 格式流式返回需要解析data:行。二、OpenHarness 是什么OpenHarness是一个开源的多模型 Agent 编排框架核心概念只有四个概念类比说明Conductor项目经理当前会话负责协调整个流程Agent团队成员具有特定角色和模型的子智能体SKILL项目流程可复用的任务编排模块MCP Server工具箱通过 Model Context Protocol 提供外部工具安装pip install openharness # 或推荐使用 uvx uvx openharness三、环境搭建与配置3.1 环境勘察——先摸清家底动手搭建前先搞清楚有什么可用godog是什么E:\Godog\下有 Godot 4.7.1 安装包E:\Godog_projects\game-1\是 Godot 项目——godog是用户给 Godot 取的昵称godot-ai 是什么game-1\godot-ai-main是源码game-1\addons\godot_ai是已安装插件。它是一个 MCP 服务器把 AI 客户端直接连接到正在运行的 Godot 编辑器提供 45 个工具OpenHarness 已有配置~/.openharness/settings.json已配好mcp_servers.godot-ai和多个 provider profile3.2 架构设计——关键决策决策点选择理由编排者conductor 做编排不做实现SKILL 机制天然支持上下文保持很小角色定义用户级 agent 定义~/.openharness/agents/*.md全局可用支持 frontmatter 字段任务看板tasks/manifest.yaml 状态机机器可读、可校验、可恢复任务卡tasks/cards/id.md最小上下文子代理只收到手头任务的上下文测试门禁test_run独立复验子代理自测 ≠ 验收通过多模型agentmodelconfig切换 profile按角色切 provider美术默认Godot 程序化美术Blender 可选项避免硬依赖3.3 落地实现——产出物清单~/.openharness/agents/ ← 4 个角色智能体定义 .openharness/skills/godot-pipeline/ ├── SKILL.md ← 编排手册阶段 0-5 ├── pipeline.yaml ← 角色→模型→profile 映射 ├── scripts/pipeline.py ← 看板工具 ├── references/role-prompts.md ← 角色派发模板 ├── references/test-conventions.md ← 测试约定 ├── references/manifest-spec.md ← 看板规范 └── assets/task_card_template.md ← 任务卡模板 game-1/tasks/manifest.yaml ← 看板 game-1/tasks/cards/T001.md ← 具体任务卡Agent 定义 frontmatter 示例--- name: gameplay-engineer model: deepseek-v4-flash mcp_servers: [godot-ai] required_mcp_servers: [godot-ai] permission_mode: bypassPermissions disallowed_tools: - agent - task_create max_turns: 50 ---pipeline.py 的 ROOT 解析Path(__file__).resolve().parents[4]从 scripts 向上 4 层定位到项目根目录。加载级验证每次修改 SKILL 后用load_skill_registry(cwd...)确认 skill 被加载用get_all_agent_definitions()确认 4 个角色加载正确。3.4 配置文件结构OpenHarness 使用两个核心配置文件都位于~/.openharness/目录下settings.json——全局配置包含 profile 定义、MCP 服务器配置等{ active_profile: openrouter, profiles: { openrouter: { provider: openai, base_url: https://openrouter.ai/api/v1, default_model: deepseek/deepseek-chat, credential_slot: profile:openrouter }, moonshot: { provider: openai, base_url: https://api.moonshot.cn/v1, default_model: kimi-k2.6, credential_slot: moonshot } }, mcp_servers: { godot-ai: { type: http, url: http://127.0.0.1:8000/mcp } } }credentials.json——API Key 管理{ profile:openrouter: {api_key: sk-or-v1-xxx}, moonshot: {api_key: sk-xxx} }3.5 Profile 切换机制OpenHarness 的config工具只写文件不改变当前会话的内存态。子代理 spawn 时重新读settings.json所以切换 profile 需要在派发子代理之前完成config set active_profile moonshot为什么不能直接在会话中切换因为 auth 系统在会话启动时已解析了active_profile对应的 credential_slot。子代理是新进程重新读文件才会拿到新值。3.6 MCP 服务器配置配置 MCP 服务器时transport 参数是最容易踩的坑。godot-ai 服务器启动时必须使用streamable-http# ❌ 错误 uv run godot-ai --transport http --port 8000 # ✅ 正确 uv run godot-ai --transport streamable-http --port 8000 --ws-port 95003.7 配置陷阱总结陷阱错误方式正确方式transport 参数--transport http--transport streamable-http模型名盲信旧配置kimi-k2.5用/v1/models核对kimi-k2.6credentials 写入直接编辑带 BOM先备份确认读取成功再写编码依赖系统默认显式设置PYTHONIOENCODINGutf-8四、SKILLs 机制详解4.1 什么是 SKILLSKILL 是 OpenHarness 中可复用的任务编排模块。一个 SKILL 定义了一套完整的工作流。4.2 SKILL 目录结构.openharness/skills/skill-name/ ├── SKILL.md # 编排手册核心 ├── pipeline.yaml # 项目配置 ├── scripts/pipeline.py # 工具脚本 ├── references/ # 参考文档 └── assets/ # 模板资源4.3 SKILL.md 编排流程4.4 pipeline.yaml 配置default_project: E:/Godog_projects/game-1 roles: game-director: model: kimi-k2.6 profile: moonshot gameplay-engineer: model: deepseek-v4-flash profile: openrouter五、MCP 协议与配置5.1 MCP 是什么MCPModel Context Protocol是一种开放协议定义了 AI 客户端如何与外部工具和服务通信。你可以把它理解为AI 世界的 USB 接口。5.2 godot-ai 实战案例godot-ai 提供45 个工具覆盖 Godot 编辑器的全部核心操作场景管理、节点操作、脚本编辑、测试运行、会话管理。5.3 MCP 架构图5.4 排查 MCP 问题# 检查端口监听 Get-NetTCPConnection -State Listen | Where-Object { $_.LocalPort -in 8000,9500 } # 检查进程 Get-CimInstance Win32_Process -Filter Namepython.exe OR NameGodot_v4.7.1* # 手动启动服务器诊断用 uv run godot-ai --transport streamable-http --port 8000 --ws-port 9500六、自定义智能体Agent定义6.1 Agent 定义文件Agent 定义位于~/.openharness/agents/*.md使用 YAML frontmatter 正文系统提示词--- name: gameplay-engineer model: deepseek-v4-flash mcp_servers: [godot-ai] required_mcp_servers: [godot-ai] permission_mode: bypassPermissions disallowed_tools: - agent - task_create max_turns: 50 --- 你是一位资深的 Godot 游戏机制工程师。 严格遵循 TDD 红-绿-重构循环每次只做垂直切片...6.2 frontmatter 字段详解字段必填说明示例值name✅Agent 唯一标识gameplay-engineermodel✅使用的模型deepseek-v4-flashmcp_servers❌可用的 MCP 服务器列表[godot-ai]required_mcp_servers❌必需的 MCP 服务器[godot-ai]permission_mode❌权限模式bypassPermissionsdisallowed_tools❌禁用的工具[agent]max_turns❌最大对话轮次506.3 四模型分工架构七、排查与调试实战常见问题速查表问题根因修复方法插件加载失败源码与插件全局类名冲突放.gdignore文件transport 错误--transport http非法用--transport streamable-http模型名 404模型名已过时用/v1/models核对credentials 丢失BOM → 覆盖写写前备份确认读取成功编码崩溃父子编码不一致PYTHONIOENCODINGutf-8排障方法论分层排查现象 → 网络层 → 进程层 → 配置层 → 应用层 → 根因对照实验每次只改一个变量字节级验证用 md5/hex 比对不依赖控制台显示总结从一个真实排障故事出发系统讲解了 OpenHarness 的五大核心配置环境搭建、SKILLs 机制、MCP 协议、自定义 Agent、排查调试。关键收获配置纪律写前备份、编码统一PYTHONIOENCODING、模型验证/v1/models、文档沉淀每个坑写进 README。参考资料OpenHarness 官方文档MCP 协议规范modelcontextprotocol.iogodot-ai 项目GitHub hi-godot/godot-ai OpenHarness 全面配置教学——从游戏开发工作流引入
一、引子1.1 四模型分工的游戏制作流水线设想一个场景用 AI 打造一套四模型分工的游戏制作流水线让 AI 自动完成从游戏设计到代码实现的全流程#角色模型职责1决策总监game-directorkimi-k2.6愿景/范围/里程碑/任务分解/验收决策2机制工程师gameplay-engineerdeepseek-v4-flashGDScript 机制、场景、UI、系统 自写测试3美术-机制桥blender-bridgedeepseek-v4-flash资产规格、资产集成验证、接口4美术专精blender-artistkimi-k2.6建模/材质/光照/特效这套流水线基于OpenHarness多模型 Agent 编排框架godot-aiGodot 编辑器的 MCP 服务器搭建也是我前段时间尝试搭建的一个工作流。1.2 五个问题速览#问题根因1godot-ai 插件加载失败源码检出目录与已安装插件全局类名冲突2MCP transport 参数错误http不是合法 transport必须用streamable-http3kimi 模型名过时kimi-k2.5已下线需用kimi-k2.64credentials.json 被误冲UTF-8 BOM 导致读失败覆盖写5中文 Windows 编码 Bug父进程写 UTF-8子进程用 GBK 读每个问题的根源恰恰对应着 OpenHarness 配置的关键环节。1.3 问题一godot-ai 插件加载失败这是搭建过程中最棘手的问题——MCP 服务器根本启动不起来。现象编辑器开着、插件启用了但端口 8000/9500 都没有进程监听OpenHarness 里 MCP 工具全部不可用。排查过程端口与进程检查Get-NetTCPConnection确认 8000/9500 无监听Get-CimInstance确认 Godot 编辑器在跑但无服务器进程读插件源码addons/godot_ai/client_configurator.gd确认端口 8000/9500 配置正确但editor_settings-4.7.tres中的managed_server_pid0说明插件从未成功启动服务器手动启动对照实验uv run godot-ai --transport streamable-http手动启动成功但session_manage返回count0——服务器通了编辑器没连上捕获编辑器启动日志用 console 版 Godot 重启并重定向 stderr发现大量全局类名冲突Class McpLogBacktrace hides a global script class数十条根因定位godot-ai-main源码检出目录含有plugin/addons/godot_ai插件的完整副本含class_name声明Godot 递归扫描res://把源码副本也当成项目内容 → 与已安装插件定义了相同全局类 → 插件编译失败 → 服务器永不启动修复在godot-ai-main/放.gdignore文件让 Godot 跳过删除.godot/类缓存重启编辑器验证pipeline.py ensure-server确认 MCP 在线、编辑器会话1、test_run 通过1.4 问题二MCP transport 参数踩坑现象uv run godot-ai --transport http --port 8000直接报错invalid choice: http根因OpenHarness 的type: http表示客户端用 HTTP 协议连接但 godot-ai 服务器端的--transport只接受stdio | sse | streamable-http没有http。修复使用--transport streamable-http。这个参数对应的握手协议不是简单 POST 一把梭而是POST /mcp发initialize→ 取Mcp-Session-Id→ 发notifications/initialized→ 发tools/list发现能力 → 正常调用tools/call。响应可能以 SSE 格式流式返回需要解析data:行。二、OpenHarness 是什么OpenHarness是一个开源的多模型 Agent 编排框架核心概念只有四个概念类比说明Conductor项目经理当前会话负责协调整个流程Agent团队成员具有特定角色和模型的子智能体SKILL项目流程可复用的任务编排模块MCP Server工具箱通过 Model Context Protocol 提供外部工具安装pip install openharness # 或推荐使用 uvx uvx openharness三、环境搭建与配置3.1 环境勘察——先摸清家底动手搭建前先搞清楚有什么可用godog是什么E:\Godog\下有 Godot 4.7.1 安装包E:\Godog_projects\game-1\是 Godot 项目——godog是用户给 Godot 取的昵称godot-ai 是什么game-1\godot-ai-main是源码game-1\addons\godot_ai是已安装插件。它是一个 MCP 服务器把 AI 客户端直接连接到正在运行的 Godot 编辑器提供 45 个工具OpenHarness 已有配置~/.openharness/settings.json已配好mcp_servers.godot-ai和多个 provider profile3.2 架构设计——关键决策决策点选择理由编排者conductor 做编排不做实现SKILL 机制天然支持上下文保持很小角色定义用户级 agent 定义~/.openharness/agents/*.md全局可用支持 frontmatter 字段任务看板tasks/manifest.yaml 状态机机器可读、可校验、可恢复任务卡tasks/cards/id.md最小上下文子代理只收到手头任务的上下文测试门禁test_run独立复验子代理自测 ≠ 验收通过多模型agentmodelconfig切换 profile按角色切 provider美术默认Godot 程序化美术Blender 可选项避免硬依赖3.3 落地实现——产出物清单~/.openharness/agents/ ← 4 个角色智能体定义 .openharness/skills/godot-pipeline/ ├── SKILL.md ← 编排手册阶段 0-5 ├── pipeline.yaml ← 角色→模型→profile 映射 ├── scripts/pipeline.py ← 看板工具 ├── references/role-prompts.md ← 角色派发模板 ├── references/test-conventions.md ← 测试约定 ├── references/manifest-spec.md ← 看板规范 └── assets/task_card_template.md ← 任务卡模板 game-1/tasks/manifest.yaml ← 看板 game-1/tasks/cards/T001.md ← 具体任务卡Agent 定义 frontmatter 示例--- name: gameplay-engineer model: deepseek-v4-flash mcp_servers: [godot-ai] required_mcp_servers: [godot-ai] permission_mode: bypassPermissions disallowed_tools: - agent - task_create max_turns: 50 ---pipeline.py 的 ROOT 解析Path(__file__).resolve().parents[4]从 scripts 向上 4 层定位到项目根目录。加载级验证每次修改 SKILL 后用load_skill_registry(cwd...)确认 skill 被加载用get_all_agent_definitions()确认 4 个角色加载正确。3.4 配置文件结构OpenHarness 使用两个核心配置文件都位于~/.openharness/目录下settings.json——全局配置包含 profile 定义、MCP 服务器配置等{ active_profile: openrouter, profiles: { openrouter: { provider: openai, base_url: https://openrouter.ai/api/v1, default_model: deepseek/deepseek-chat, credential_slot: profile:openrouter }, moonshot: { provider: openai, base_url: https://api.moonshot.cn/v1, default_model: kimi-k2.6, credential_slot: moonshot } }, mcp_servers: { godot-ai: { type: http, url: http://127.0.0.1:8000/mcp } } }credentials.json——API Key 管理{ profile:openrouter: {api_key: sk-or-v1-xxx}, moonshot: {api_key: sk-xxx} }3.5 Profile 切换机制OpenHarness 的config工具只写文件不改变当前会话的内存态。子代理 spawn 时重新读settings.json所以切换 profile 需要在派发子代理之前完成config set active_profile moonshot为什么不能直接在会话中切换因为 auth 系统在会话启动时已解析了active_profile对应的 credential_slot。子代理是新进程重新读文件才会拿到新值。3.6 MCP 服务器配置配置 MCP 服务器时transport 参数是最容易踩的坑。godot-ai 服务器启动时必须使用streamable-http# ❌ 错误 uv run godot-ai --transport http --port 8000 # ✅ 正确 uv run godot-ai --transport streamable-http --port 8000 --ws-port 95003.7 配置陷阱总结陷阱错误方式正确方式transport 参数--transport http--transport streamable-http模型名盲信旧配置kimi-k2.5用/v1/models核对kimi-k2.6credentials 写入直接编辑带 BOM先备份确认读取成功再写编码依赖系统默认显式设置PYTHONIOENCODINGutf-8四、SKILLs 机制详解4.1 什么是 SKILLSKILL 是 OpenHarness 中可复用的任务编排模块。一个 SKILL 定义了一套完整的工作流。4.2 SKILL 目录结构.openharness/skills/skill-name/ ├── SKILL.md # 编排手册核心 ├── pipeline.yaml # 项目配置 ├── scripts/pipeline.py # 工具脚本 ├── references/ # 参考文档 └── assets/ # 模板资源4.3 SKILL.md 编排流程4.4 pipeline.yaml 配置default_project: E:/Godog_projects/game-1 roles: game-director: model: kimi-k2.6 profile: moonshot gameplay-engineer: model: deepseek-v4-flash profile: openrouter五、MCP 协议与配置5.1 MCP 是什么MCPModel Context Protocol是一种开放协议定义了 AI 客户端如何与外部工具和服务通信。你可以把它理解为AI 世界的 USB 接口。5.2 godot-ai 实战案例godot-ai 提供45 个工具覆盖 Godot 编辑器的全部核心操作场景管理、节点操作、脚本编辑、测试运行、会话管理。5.3 MCP 架构图5.4 排查 MCP 问题# 检查端口监听 Get-NetTCPConnection -State Listen | Where-Object { $_.LocalPort -in 8000,9500 } # 检查进程 Get-CimInstance Win32_Process -Filter Namepython.exe OR NameGodot_v4.7.1* # 手动启动服务器诊断用 uv run godot-ai --transport streamable-http --port 8000 --ws-port 9500六、自定义智能体Agent定义6.1 Agent 定义文件Agent 定义位于~/.openharness/agents/*.md使用 YAML frontmatter 正文系统提示词--- name: gameplay-engineer model: deepseek-v4-flash mcp_servers: [godot-ai] required_mcp_servers: [godot-ai] permission_mode: bypassPermissions disallowed_tools: - agent - task_create max_turns: 50 --- 你是一位资深的 Godot 游戏机制工程师。 严格遵循 TDD 红-绿-重构循环每次只做垂直切片...6.2 frontmatter 字段详解字段必填说明示例值name✅Agent 唯一标识gameplay-engineermodel✅使用的模型deepseek-v4-flashmcp_servers❌可用的 MCP 服务器列表[godot-ai]required_mcp_servers❌必需的 MCP 服务器[godot-ai]permission_mode❌权限模式bypassPermissionsdisallowed_tools❌禁用的工具[agent]max_turns❌最大对话轮次506.3 四模型分工架构七、排查与调试实战常见问题速查表问题根因修复方法插件加载失败源码与插件全局类名冲突放.gdignore文件transport 错误--transport http非法用--transport streamable-http模型名 404模型名已过时用/v1/models核对credentials 丢失BOM → 覆盖写写前备份确认读取成功编码崩溃父子编码不一致PYTHONIOENCODINGutf-8排障方法论分层排查现象 → 网络层 → 进程层 → 配置层 → 应用层 → 根因对照实验每次只改一个变量字节级验证用 md5/hex 比对不依赖控制台显示总结从一个真实排障故事出发系统讲解了 OpenHarness 的五大核心配置环境搭建、SKILLs 机制、MCP 协议、自定义 Agent、排查调试。关键收获配置纪律写前备份、编码统一PYTHONIOENCODING、模型验证/v1/models、文档沉淀每个坑写进 README。参考资料OpenHarness 官方文档MCP 协议规范modelcontextprotocol.iogodot-ai 项目GitHub hi-godot/godot-ai