企业官网建设流程全解析

一、引子

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

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

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

1.2 五个问题速览

每个问题的根源，恰恰对应着 OpenHarness 配置的关键环节。

1.3 问题一：godot-ai 插件加载失败

这是搭建过程中最棘手的问题——MCP 服务器根本启动不起来。

现象：编辑器开着、插件启用了，但端口 8000/9500 都没有进程监听，OpenHarness 里 MCP 工具全部不可用。

排查过程：

1. 端口与进程检查：Get-NetTCPConnection确认 8000/9500 无监听；Get-CimInstance确认 Godot 编辑器在跑但无服务器进程

2. 读插件源码：addons/godot_ai/client_configurator.gd确认端口 8000/9500 配置正确，但editor_settings-4.7.tres中的managed_server_pid=0说明插件从未成功启动服务器

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

4. 捕获编辑器启动日志：用 console 版 Godot 重启并重定向 stderr，发现大量全局类名冲突：Class "McpLogBacktrace" hides a global script class（数十条）

5. 根因定位：godot-ai-main源码检出目录含有plugin/addons/godot_ai（插件的完整副本，含class_name声明），Godot 递归扫描res://把源码副本也当成项目内容 → 与已安装插件定义了相同全局类 → 插件编译失败 → 服务器永不启动

6. 修复：在godot-ai-main/放.gdignore文件让 Godot 跳过，删除.godot/类缓存，重启编辑器

7. 验证：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 编排框架，核心概念只有四个：

安装：

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 架构设计——关键决策

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 配置陷阱总结

四、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 字段详解

6.3 四模型分工架构

七、排查与调试实战

常见问题速查表

排障方法论

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

总结

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

参考资料

• OpenHarness 官方文档

• MCP 协议规范（modelcontextprotocol.io）

• godot-ai 项目（GitHub hi-godot/godot-ai）