ForgeaX-Games/forgeax-dsh-game-plugin

@forgeax/dsh-game

npm
ci
DSH bundle
platform

在 DeepSeek Harness 中进行 ForgeaX 游戏开发。
这是一个 DSH bundle：将其安装到某个 profile 中会添加一个补丁层，该补丁层会把已发布的
@forgeax/game MCP 服务器、其捆绑的 ForgeaX Skills，
以及一个工作区守卫接入你的 DSH 会话。

它不包含任何游戏逻辑，也不包含 ForgeaX 的副本。它会解析 pnpm 安装在它旁边的 @forgeax/game
包，验证其身份，并将其连接起来。

你将获得

| 界面 | 效果 |
|---|---|
| 工具 | mcp__forgeax__forgeax_status_lite、mcp__forgeax__forgeax_run_current_game |
| 技能 | forgeax-game 以及解析出的包中随附的每个 forgeax-engine- Skill，在启动时注册到 ctx.skills |
| 守卫 | 每个 mcp__forgeax__ 调用，如果其 target_dir 不是当前会话 cwd，都会被拒绝。如果调用没有可比较的会话 cwd（Code Mode、嵌套调度），则在存在性检查后允许，并会告知模型它未被完整检查 |

你不需要运行 forgeax-game devkit install。此 bundle 会直接注册 Skills；
同时运行安装器只会在你的仓库中留下 DSH 永远不会读取的重复副本。

要求

- macOS arm64、Linux x64 或 Windows x64。 此 bundle 是纯 JS，且未声明
os/cpu；它的平台覆盖范围继承自 @forgeax/game，后者的
@forgeax/game-runtime 会为每个平台提供一个原生二进制文件，作为 optionalDependencies 中的一项。
你的机器只会安装匹配的那一个。没有已发布变体的平台（Intel Mac、ARM Linux、ARM Windows）
可以正常安装，但在运行时启动时会失败，这与 @forgeax/game 单独使用时的行为完全一致。
- PATH 中有 pnpm。 dsh plugin 是一个轻量的 pnpm 转发器；没有 pnpm 时它会以 127 退出。
- Node ≥ 22，与 DSH 保持一致。

安装

dsh plugin 会安装到一个指定的 profile 并自动激活：因为此包声明了
dsh.bundle，将其添加为依赖项也会把它追加到该 profile 的
dsh.profile.bundles 层栈中。

dsh plugin --profile web add @forgeax/dsh-game

--profile 是必需的——DSH 没有隐式默认 profile，而且层栈是按 profile 区分的。
对于每个应拥有 ForgeaX 的 profile，请重复执行该命令。
然后重启 dsh。 Bundle 层在启动时只读取一次；只有 profile 自己的用户补丁文件会被监听。新添加的 bundle 在下一次启动前都是惰性的。

重启后验证：

dsh --profile web
then, in the session:
ask for the ForgeaX status — the model should call mcp__forgeax__forgeax_status_lite

配置

此 bundle 插入的四行，全部带有命名空间，因此它们永远不会与另一个 bundle 冲突：

| 行 id | 模块 | 用途 |
|---|---|---|
| forgeax-game.launch-spec | @forgeax/dsh-game/launch-spec | 解析并验证 @forgeax/game，发布 forgeaxGameLaunch 服务 |
| forgeax-game.mcp-client | @deepseek-ai/dsh-mcp-client | stdio 桥接，serverName: forgeax |
| forgeax-game.skill-source | @forgeax/dsh-game/skill-source | 注册该包的 Skills |
| forgeax-game.workspace-guard | @forgeax/dsh-game/workspace-guard | 工具策略：在 tools/pre-execute 上拒绝，在 tools/post-execute 上报告一次无法验证的调用 |

解析器本身位于第五个模块 @forgeax/dsh-game/forgeax-package 中，该模块不导入任何框架。溯源工具可以从已安装的 profile 中加载它，在那里 DSH 包是 peer，profile 永远不会安装第二份副本。

要更改某些内容，请向你的 profile 的用户补丁文件中添加一行，使用相同的 id。补丁会替换目标行的整个 config——不存在深度合并——因此你必须重新声明你想保留的每个字段。例如，要缩短工具调用超时：

$DSH_HOME/profiles/web/cordis.patch.yml
- insert:
- id: forgeax-game.mcp-client
name: '@deepseek-ai/dsh-mcp-client'
inject:
- forgeaxGameLaunch
config:
serverName: forgeax
transport: stdio
command: !!js ctx.forgeaxGameLaunch.spec.command
args: !!js ctx.forgeaxGameLaunch.spec.args
cwd: !!js ctx.forgeaxGameLaunch.spec.cwd
env: !!js ctx.forgeaxGameLaunch.spec.env
failOnStartupError: true
toolCallTimeoutMs: 120000
reconnect:
enabled: true

值得了解的局限

- 仅限工具。 DSH 的 MCP 客户端桥接的是工具，而不是资源。forgeax://status 在 DSH 会话中不可达；mcp__forgeax__forgeax_status_lite 返回相同的状态。注册的 Skill 说明了这一点，因此模型不会尝试该资源。
- 没有传递性 bundle。 只有直接列在 dsh.profile.bundles 中的包才会贡献补丁层。依赖此 bundle 的 bundle 不会继承它的行。
- 一次性的 ForgeaX 操作仍留在 CLI 上。 创建游戏、切换活动游戏以及升级插件是 forgeax-game  子命令，而不是 MCP 工具。

失败模式

| 症状 | 原因 |
|---|---|
| dsh plugin 退出码为 127 | pnpm 不在 PATH 上 |
| 全新安装后运行时无法启动 | 此平台（Intel Mac、ARM Linux、ARM Windows）没有 @forgeax/game-runtime 变体——目前尚未发布任何变体 |
| pnpm 拒绝 git 托管规范的 prepare | 在 /pnpm-workspace.yaml 中的 allowBuilds 下将其加入允许列表（pnpm ≥ 10） |
| 安装后 ForgeaX 工具缺失 | dsh 未重启 |
| 启动因启动规范错误而失败 | 解析出的 @forgeax/game 与固定版本不匹配，或缺少捆绑的 Skill 资源——请重新安装，而不是绕过它打补丁 |

failOnStartupError 故意设为 true：一个 MCP 服务器从未启动的 ForgeaX 会话是损坏的，而不是降级的，而且启动时的错误比第一次工具调用时的谜团更容易阅读。

安全

- 子进程以 env: {} 启动。DSH 会清除父环境，并在清除之后合并 config.env，因此其中列出的任何内容都会重新注入 harness 刚刚移除的密钥。
- 工作区守卫在 realpath 解析后，将 target_dir 与会话 cwd 进行比较——绝不通过字符串前缀比较，因为符号链接和 .. 会使其失效。
- 此 bundle 不会读取、存储或记录任何 API 密钥、令牌或密钥值。

变更日志

每个用户可见的变更都记录在 CHANGELOG.md 中。要贡献，请参阅 CONTRIBUTING.md；要报告漏洞，请参阅 SECURITY.md。

许可证

MIT