OpenHarness 全面配置教学——从游戏开发工作流引入

一、引子

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 + 正文系统提示词：

复制代码

---
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-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）