AI Native Game Harness 迁移操作手册
适用对象 ：已用 Claude Skill / MCP 完成"魔兽争霸3式地图生成 + 游戏操作语义"能力，计划迁移到 DSH SDK + 自研 Web UI 的团队。
手册目标 ：让团队在一周内完成环境准备和最小跑通，两周内完成现有能力的分层映射，并在 DSH 预览版的不确定性下保住领域核心的长期可维护性。
第一章 先对齐三件事，再动手
1.1 你要迁移到的到底是什么
AI Native Game Harness 不是一个"游戏 AI 框架"，它是DSH Runtime 的游戏领域发行版 。它的核心主张只有一句话：复用 DSH 通用运行时，用 Harness 组织游戏语义，用薄 Adapter / Mod 连接原生 API，并让游戏本体保持事实权威。
对你团队最关键的含义：模型、Agent Loop、Tool 调用、Session、凭据管理，全部不要自己写。 你从 Claude 对话模式中带过来的资产，不是"一套需要翻译成 DSH 代码的逻辑"，而是游戏领域语义------地图生成规则、操作动词、参数校验、游戏知识。这些应该进入 Harness 的领域层，而不是散落在提示词里。
1.2 三层职责，一条边界
Harness 的架构用一条核心规则划分职责：
凡是不依赖具体游戏就能完成的能力，都归 Harness；游戏知识和专属工具进入可选 Adapter；只有必须运行在游戏进程内、调用游戏 API 的工作才进入 Bridge / Mod。
具体到你的场景：
| 层 | 你的东西放在这里 | 不应该放在这里 |
|---|---|---|
| Harness 插件（DSH 侧） | 通用 Agent 调度、多模态、记忆、UI 挂载、工具注册 | 魔兽争霸3专属的地图语法、单位类型表 |
| Adapter（可选游戏插件） | 地图生成算法、游戏知识、专属工具 Schema、协议翻译 | 模型调用、规划逻辑、Provider Key |
| Bridge / Mod（游戏进程内） | 读取游戏状态、调用游戏地图 API、执行"放置单位"等原生动作、返回权威结果 | 任何模型 SDK、任何规划、任何记忆存储 |
Adapter 和 Bridge 都不能依赖模型厂商的 SDK，Provider 密钥不能进入这两层。 这是硬边界。你之前 Claude 对话模式里的 MCP Server，如果包含了地图生成算法，迁移时应该把算法下沉到 Adapter，而不是留在 MCP 形态里。
1.3 你不需要做的事
- 不需要重写 Agent Loop。 DSH 原生提供模型、Gateway、Tool Registry、Session、Agent、后台任务等基础能力。你的精力应该全部放在游戏领域层。
- 不需要自己实现 Tool 重试、审计、权限。 这些是 Harness 通用工具注册层的事。
- 不需要在 Bridge 里做"智能"。 Bridge 的职责是"诚实"：读取准确状态、执行原生动作、原样返回成功或失败。模型负责决策，但地图是否真的生成成功，必须由游戏 API 返回确认。
第二章 环境准备（Day 1）
2.1 硬性前置条件
| 组件 | 要求 | 说明 |
|---|---|---|
| Node.js | v22.19+ LTS | DSH 核心的最低要求。Windows / macOS / Linux 均支持 |
| 包管理器 | npm 或 pnpm | 安装插件和本地开发构建均需要 |
| 游戏侧运行环境 | 取决于你的 Adapter/Bridge | 魔兽争霸3地图编辑相关 API 的调用方式需要团队自行确认 |
不要跳过版本校验。 在终端执行：
bash
node -v输出必须 ≥ v22.19.0。低于此版本后续所有步骤都会失败。
2.2 安装 DSH 本体（二选一）
方式 A：npx 临时启动（推荐第一天用）
bash
npx @deepseek-ai/dsh web浏览器打开 http://127.0.0.1:3080，看到 DSH 的 Web 界面即表示本体安装成功。这种方式不需要全局安装，适合快速验证环境。
方式 B：全局安装（长期开发推荐）
bash
npm install -g @deepseek-ai/dsh
dsh web后续所有 dsh plugin 命令都依赖全局安装或 npx 上下文，团队统一用同一种方式，避免命令路径混乱。
2.3 安装 AI Native Game Harness
在 DSH 已经可运行的前提下，安装 Harness 发行版插件。安装命令使用 DSH 的 plugin add 机制，指向 Harness 的发布包：
bash
dsh plugin --profile web add "<AI Native Game Harness 的发布包 URL>"关于发布包 URL ：Harness 的安装方式和版本会随项目迭代变化，不要从博客或第三方页面复制过期的 URL 。正确做法是：打开 github.com/qimidandapigu/ai-native-game-harness 的 Releases 页面，找到最新稳定版的 .tgz 下载链接，粘贴到上述命令中。Harness 的安装机制继承自 DSH 的 dsh plugin add，支持 GitHub Release 直链和本地 .tgz 路径。
安装完成后，重启 DSH 进程，然后在 Web 界面中确认 Harness 相关插件已加载。
第三章 最小跑通：先让一个"假游戏"动起来（Day 1--2）
3.1 为什么先做 Fake Game，而不是直接接魔兽争霸3
Harness 的架构原则中有一条：版本固定，升级可验证；升级先通过 Fake Game、协议兼容和真实存档验收。在你的团队完全没有 DSH 经验的情况下，直接接真实游戏会把"DSH 学习成本"和"游戏 Adapter 调试成本"混在一起，一旦出问题很难定位。
Fake Game 的目标是：用最少的代码验证"Harness 插件 → Adapter → Bridge"这条链路是通的，不涉及真实地图 API。
3.2 最小链路验证步骤
第一步：确认 Harness 插件已加载。 在 DSH Web 界面中，Agent 应该能识别到 Harness 提供的游戏领域工具（例如 adapter.hello 相关的连接能力）。如果看不到任何游戏相关工具，回到第二章检查插件安装和 profile 是否正确。
第二步：编写一个最小 Adapter。 Adapter 的核心接口只有一个必须实现的：adapter.hello，用于上报"游戏进程 ID"或一个 Fake 的游戏标识。Harness 的通用媒体层会基于这个 ID 定位游戏窗口；Fake Game 阶段可以返回一个占位值，但接口形状必须真实。
Adapter 同时需要声明你的游戏专属工具 Schema。哪怕是 Fake 阶段，也建议把"生成地图"这个工具的入参和出参 Schema 写出来------这是你从 Claude Skill 迁移过来的第一块真实资产。
第三步：编写一个最小 Bridge。 Bridge 只做一件事：收到 Adapter 转来的"生成地图"动作，返回一个确定性的结果 （例如 { success: true, mapId: "fake-001", revision: 1 }）。不要在这一步引入任何模型调用。Bridge 的结果必须是权威回执，模型后续的剧情和记忆只能在这个回执之后继续。
第四步：在 DSH Web 界面中发起一次对话 ，让 Agent 调用"生成地图"工具。观察控制台或日志，确认调用链是：Agent → Harness 工具注册 → Adapter → Bridge → 结果返回 → Agent 接收回执。只要这条链路通了，后续所有工作都是把 Fake 替换成真实实现。
第四章 分层开发：把你 Claude 里的资产搬到正确的位置（Day 3--5）
4.1 迁移映射表
你团队从 Claude 对话模式带过来的资产，按以下规则映射：
| Claude 侧资产 | 迁移目标 | 迁移方式 |
|---|---|---|
| 地图生成算法（代码或 Skill 中的确定性逻辑） | Adapter 内部的领域模块 | 算法本身不依赖 DSH，用 TypeScript/JavaScript 模块实现；Adapter 只做参数映射和协议翻译 |
| 游戏知识（单位类型、地形规则、触发器等） | Adapter 的知识库或 Prompt 注入层 | 作为结构化数据或 Adapter 管理的上下文，不进入 Harness 通用 Prompt |
| 操作语义（"放置单位""调整地形""生成区域"） | Adapter 的 Tool Schema + Bridge 的原生动作 | Tool Schema 定义"Agent 能看到什么参数"；Bridge 定义"游戏 API 如何执行" |
| MCP Server 中的工具 | Adapter 的专属工具集 | 如果 MCP Server 纯做协议转换，可以废弃；如果包含领域逻辑，下沉到 Adapter |
| Claude Skill 中的提示词 | Harness 插件或 Adapter 的 Prompt 片段 | 只保留与游戏语义相关的部分；通用 Agent 行为交给 Harness |
| 自研 Web UI 的交互逻辑 | Harness 的 UI 扩展 slot + 你的前端模块 | UI 状态管理尽量走你自己的领域核心，DSH Session 只负责 Agent 侧调度 |
一个关键判断 ：你现有的 MCP Server 如果只是把 Claude 的 tool call 翻译成游戏 API 调用，那么它本质上就是一个 Bridge 的角色；如果它还包含了地图生成的决策逻辑（"根据用户描述推断地形布局"），那么这部分逻辑必须上移到 Adapter，而不是留在 Bridge 里。Bridge 不允许做规划。
4.2 Adapter 的职责边界（最容易踩坑的地方）
Adapter 是可选游戏插件，它的职责矩阵非常明确：
- ✅ 游戏角色规则和知识
- ✅ 游戏专属工具 Schema
- ✅ 参数落地与协议翻译
- ✅ 选择并注册游戏进程
- ❌ 不保存 Provider Key
- ❌ 不接触模型 SDK
- ❌ 不做 Agent 循环调度
Adapter 可以保留完整的 observation（原始游戏状态）在本机 ，用于寻路、目标 ID 校验、动作前置条件和结果校验；但不能默认把完整 observation 塞进模型提示词 。只有经过白名单裁剪的 modelContext 才能进入模型上下文。这意味着你在 Adapter 中需要显式设计"哪些字段给模型看，哪些字段只用于本地校验"。
4.3 Bridge 的"薄"如何量化
Bridge 的代码应该薄到：如果明天把模型从 DeepSeek 换成任何其他模型，Bridge 一行都不用改。 如果发现 Bridge 里出现了"判断用户意图""决定下一步动作"之类的逻辑，立即上移到 Adapter 或让 Agent 承担。Bridge 只暴露真实状态、事件和原生动作，不调用模型、不做规划、不保存 Harness 记忆。
第五章 版本策略：在 DSH 预览版上安全地活着（持续）
5.1 为什么这件事必须从第一天就做
DSH 仍处于快速迭代阶段，0.1.7 起有一道 bundle 级 peer 门禁：peer 依赖范围不满足的 bundle 会被整体跳过，界面上表现为"插件凭空消失"，而且只往 stderr 写一行日志。旧插件常把 DSH 依赖精确锁在某个 rc 版本上，只满足一条宿主线，换到另一条线就会安装被拒或加载被跳过。
这不意味着不能用，意味着版本声明和升级流程必须被当作工程事件对待。
5.2 三条硬性规则
规则一：Adapter 和 Bridge 不依赖 DSH 运行时版本。 你的游戏领域核心（地图生成算法、知识库、操作语义定义）应该以不依赖 DSH 的接口存在。Adapter 和 Bridge 是 DSH 感知层，领域核心不是。这样即使 DSH 发生破坏性变更，你只需要调整 Adapter 的 DSH 对接部分，领域核心的测试仍然通过。
规则二：peer 依赖显式声明宽窗口，不要精确锁 rc。 如果 Harness 插件或 Adapter 需要声明 @deepseek-ai/dsh* 的 peer 依赖，使用形如 "^0.1.7-rc.2 || ^0.2.0-rc.1" 的窗口声明，同时覆盖多条宿主线；engines.dsh 同步该窗口。不要写成单条 >=x <y 的范围，它可能过得了运行时预检，却过不了 npm 的预发布规则。
规则三：升级前跑契约验证，不要跟随 latest。 把"升级 DSH / Harness"当作一个需要回归测试的事件。Harness 自身的版本策略也支持这一点：Harness 插件和游戏包独立发版，版本号不要求完全相同。这意味着你可以固定 Harness 插件的版本，独立迭代你的 Game Pack / Adapter，不必被 Harness 的每次发布拖着走。
第六章 测试与验收：什么算"迁移完成"
6.1 分层验收标准
不要用"对话里能生成地图了"作为迁移完成的标志。按层验收：
| 层 | 验收项 | 通过标准 |
|---|---|---|
| 领域核心（与 DSH 无关） | 地图生成算法、参数校验、操作语义定义的单元测试 | 不启动 DSH，纯 Node 测试全部通过 |
| Adapter | 工具 Schema 正确暴露；adapter.hello 能注册；modelContext 白名单生效 |
Agent 能看到工具；完整 observation 不进入模型上下文 |
| Bridge | 动作执行返回权威回执；失败原因原样返回 | 游戏 API 的结果未经模型加工到达 Agent |
| 端到端 | Fake Game → 真实 Adapter → 真实 Bridge → Agent 接收回执 → UI 展示 | 回执驱动 UI 状态，而不是 Agent 的文字描述驱动 UI |
| 版本兼容 | 在当前锁定的 DSH 宿主线上安装、加载、运行 | 插件不"凭空消失"；peer 预检通过 |
6.2 一个容易忽略的验收项：事实权威
Harness 的原则是 "事实先于模型推测" ：视觉负责理解，模型负责决策，确定性结果来自游戏 API ；只有游戏确认后，剧情和记忆才能继续。验收时专门测一个场景：Bridge 返回失败时，Agent 是否仍然在 UI 或后续对话中声称"地图已生成"。如果发生这种情况，说明你的 Adapter 或 UI 层把模型输出当成了事实来源，需要修正------UI 的状态应该绑定 Bridge 的权威回执，而不是模型生成的文本。
第七章 团队分工建议
| 角色 | 负责范围 | 不需要做的事 |
|---|---|---|
| DSH / Harness 集成 | DSH 环境、插件安装、版本锁定、Web UI slot 集成 | 不写地图生成算法 |
| Adapter 开发 | 工具 Schema、协议翻译、游戏知识注入、modelContext 白名单 |
不碰 DSH 内核 |
| Bridge / 游戏侧 | 读取状态、调用地图 API、权威回执 | 不做任何模型调用或规划 |
| 领域核心 | 地图生成算法、操作语义的确定性逻辑、单元测试 | 不依赖 DSH 运行时 |
检查清单（打印出来贴墙上）
- Node.js ≥ v22.19，
node -v通过 - DSH 可以本地启动，Web 界面可打开
- AI Native Game Harness 插件从 GitHub Releases 获取并安装成功
- Fake Game 链路跑通：Agent → Adapter → Bridge → 回执返回
- 地图生成算法已从 MCP/Skill 中剥离，放在不依赖 DSH 的领域模块中，单元测试通过
- Adapter 的工具 Schema 已定义，完整 observation 不进入
modelContext - Bridge 中没有模型调用、没有规划逻辑、没有 Provider Key
- 失败场景验收通过：Bridge 返回失败时，UI/Agent 不声称成功
- peer 依赖窗口覆盖多条 DSH 宿主线，
engines.dsh同步 - DSH 版本已固定到具体线上，升级流程有回归测试清单
- UI 状态绑定的是 Bridge 回执，而不是模型输出文本
最后一句提醒 ：这份手册的节奏是"先跑通、再分层、再迁移"。你的团队没有 DSH 经验，不要在 Fake Game 跑通之前就开始改写真实地图生成逻辑。Harness 的架构已经替你处理了 Agent Loop、Session、Tool 注册这些最容易消耗精力的部分；你的竞争优势在领域层，把时间花在那里。