OpenHarness 全面配置教学——从游戏开发工作流引入-171主机测评

一、引子

1.1 四模型分工的游戏制作流水线

设想一个场景：用 AI 打造一套四模型分工的游戏制作流水线，让 AI 自动完成从游戏设计到代码实现的全流程：

角色

模型

职责

1	决策总监（game-director）	kimi-k2.6	愿景/范围/里程碑/任务分解/验收决策
2	机制工程师（gameplay-engineer）	deepseek-v4-flash	GDScript 机制、场景、UI、系统 + 自写测试
3	美术-机制桥（blender-bridge）	deepseek-v4-flash	资产规格、资产集成验证、接口
4	美术专精（blender-artist）	kimi-k2.6	建模/材质/光照/特效

这套流水线基于 OpenHarness（多模型 Agent 编排框架）+ godot-ai（Godot 编辑器的 MCP 服务器）搭建（也是我前段时间尝试搭建的一个工作流）。

1.2 五个问题速览

问题

根因

1	godot-ai 插件加载失败	源码检出目录与已安装插件全局类名冲突
2	MCP transport 参数错误	http 不是合法 transport，必须用 streamable-http
3	kimi 模型名过时	kimi-k2.5 已下线，需用 kimi-k2.6
4	credentials.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_pid=0 说明插件从未成功启动服务器

手动启动对照实验：uv run godot-ai –transport streamable-http 手动启动成功，但 session_manage 返回 count=0——服务器通了，编辑器没连上

捕获编辑器启动日志：用 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 profile

3.2 架构设计——关键决策

决策点

选择

理由

编排者	conductor 做编排，不做实现	SKILL 机制天然支持；上下文保持很小
角色定义	用户级 agent 定义（~/.openharness/agents/*.md）	全局可用，支持 frontmatter 字段
任务看板	tasks/manifest.yaml + 状态机	机器可读、可校验、可恢复
任务卡	tasks/cards/<id>.md，最小上下文	子代理只收到手头任务的上下文
测试门禁	test_run 独立复验	子代理自测 ≠ 验收通过
多模型	agent model + config 切换 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 9500

3.7 配置陷阱总结

陷阱

错误方式

正确方式

transport 参数	–transport http	–transport streamable-http
模型名	盲信旧配置 kimi-k2.5	用 /v1/models 核对：kimi-k2.6
credentials 写入	直接编辑带 BOM	先备份，确认读取成功再写
编码	依赖系统默认	显式设置 PYTHONIOENCODING=utf-8

四、SKILLs 机制详解

4.1 什么是 SKILL

SKILL 是 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 是什么

MCP（Model 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 "Name='python.exe' OR Name='Godot_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 + 正文系统提示词：

你是一位资深的 Godot 游戏机制工程师。
严格遵循 TDD 红-绿-重构循环，每次只做垂直切片…

6.2 frontmatter 字段详解

字段

必填

说明

示例值

name	✅	Agent 唯一标识	gameplay-engineer
model	✅	使用的模型	deepseek-v4-flash
mcp_servers	❌	可用的 MCP 服务器列表	["godot-ai"]
required_mcp_servers	❌	必需的 MCP 服务器	["godot-ai"]
permission_mode	❌	权限模式	bypassPermissions
disallowed_tools	❌	禁用的工具	["agent"]
max_turns	❌	最大对话轮次	50

6.3 四模型分工架构

七、排查与调试实战

常见问题速查表

问题

根因

修复方法

插件加载失败	源码与插件全局类名冲突	放 .gdignore 文件
transport 错误	–transport http 非法	用 –transport streamable-http
模型名 404	模型名已过时	用 /v1/models 核对
credentials 丢失	BOM → 覆盖写	写前备份，确认读取成功
编码崩溃	父子编码不一致	PYTHONIOENCODING=utf-8

排障方法论

分层排查：现象 → 网络层 → 进程层 → 配置层 → 应用层 → 根因对照实验：每次只改一个变量字节级验证：用 md5/hex 比对，不依赖控制台显示

总结

从一个真实排障故事出发，系统讲解了 OpenHarness 的五大核心配置：环境搭建、SKILLs 机制、MCP 协议、自定义 Agent、排查调试。关键收获：配置纪律（写前备份）、编码统一（PYTHONIOENCODING）、模型验证（/v1/models）、文档沉淀（每个坑写进 README）。

参考资料

OpenHarness 官方文档
MCP 协议规范（modelcontextprotocol.io）
godot-ai 项目（GitHub hi-godot/godot-ai）