ForgeaX-Games/forgeax-dsh-game-plugin
ForgeaX game development inside DeepSeek Harness. This is a DSH bundle: installing it into a profile adds one patch layer that wires the already-published @forgeax/game MCP server, its bundled ForgeaX Skills, and a workspace guard into your DSH session.
catalog 简介 / catalog descriptioncatalog description:DeepSeek Harness (DSH) bundle plugin for ForgeaX game dev — @forgeax/dsh-game
编辑导读Editor's Brief
## 核心特性
- 该插件新增了一个 DSH bundle 层,将已发布的 @forgeax/game MCP 服务器接入 DeepSeek Harness 配置。
- 它将 mcp__forgeax__forgeax_status_lite 和 mcp__forgeax__forgeax_run_current_game 暴露为 DSH 工具。
- 它会在启动时将 forgeax-game Skill 以及解析出的包中附带的所有 forgeax-engine-* Skill 注册到 ctx.skills。
- 它强制执行工作区守卫,拒绝在 realpath 解析后 target_dir 不是当前会话 cwd 的 ForgeaX 工具调用。
- 它会校验解析出的 @forgeax/game 包身份,而不是包含游戏逻辑或 ForgeaX 副本。
## 使用场景
- 在 DSH 会话中运行 ForgeaX 游戏开发工作流,无需手动将 ForgeaX Skills 安装到仓库中。
- 通过 DSH 工具界面检查 ForgeaX 运行时状态。
- 从 DSH 会话运行当前 ForgeaX 游戏,同时让工具调用限制在当前活动工作区内。
## 技术细节
- 该 bundle 为启动规范、MCP 客户端、Skill 来源和工作区守卫插入四条带命名空间的条目。
- 解析器模块 @forgeax/dsh-game/forgeax-package 会定位通过 pnpm 安装的 @forgeax/game 包,并发布 forgeaxGameLaunch 服务。
- MCP 客户端使用 stdio 传输,并设置 serverName: forgeax,桥接的是工具而非资源。
- 工作区守卫会在 tools/pre-execute 阶段进行评估;当没有可用的会话 cwd 时,会在 tools/post-execute 阶段报告无法校验的调用。
## 注意事项
- pnpm 必须位于 PATH 中,因为 dsh plugin 只是一个轻量 pnpm 转发器;Node 必须为 22 或更高版本,并与 DSH 保持一致。
- 支持 macOS arm64、Linux x64 和 Windows x64;对于没有发布对应 @forgeax/game-runtime 变体的平台,虽然可以安装,但运行时启动会失败。
- 添加 bundle 后必须重启 DSH;一次性 ForgeaX 操作仍然保留为 CLI 子命令,而不是 MCP 工具。
## Core Features
- The plugin adds a DSH bundle layer that connects the published @forgeax/game MCP server into a DeepSeek Harness profile.
- It exposes mcp__forgeax__forgeax_status_lite and mcp__forgeax__forgeax_run_current_game as DSH tools.
- It registers the forgeax-game Skill and every forgeax-engine-* Skill shipped in the resolved package on ctx.skills at boot.
- It enforces a workspace guard that denies ForgeaX tool calls whose target_dir is not the current session cwd after realpath resolution.
- It verifies the resolved @forgeax/game package identity instead of containing game logic or a copy of ForgeaX.
## Use Cases
- Running ForgeaX game development workflows inside a DSH session without manually installing ForgeaX Skills into the repository.
- Checking ForgeaX runtime status through the DSH tool surface.
- Running the current ForgeaX game from a DSH session while keeping tool calls confined to the active workspace.
## Technical Details
- The bundle inserts four namespaced rows for launch specification, MCP client, Skill source, and workspace guard.
- The resolver module @forgeax/dsh-game/forgeax-package locates the pnpm-installed @forgeax/game package and publishes the forgeaxGameLaunch service.
- The MCP client uses a stdio transport with serverName: forgeax and bridges tools rather than resources.
- The workspace guard evaluates tools/pre-execute and reports unverifiable calls on tools/post-execute when no session cwd is available.
## Notes
- pnpm must be on PATH because dsh plugin is a thin pnpm forwarder, and Node must be version 22 or higher, matching DSH.
- macOS arm64, Linux x64, and Windows x64 are supported, while platforms without a published @forgeax/game-runtime variant install but fail when the runtime starts.
- DSH must be restarted after adding the bundle, and one-time ForgeaX operations remain CLI subcommands rather than MCP tools.
安装Install
dsh plugin --profile web add @forgeax/dsh-game
把 ForgeaX-Games/forgeax-dsh-game-plugin 加入你的 DSH 配置(web profile)即可启用。
READMEREADME
@forgeax/dsh-game
ForgeaX game development inside DeepSeek Harness.
This is a DSH bundle: installing it into a profile adds one patch layer that wires the
already-published @forgeax/game MCP server,
its bundled ForgeaX Skills, and a workspace guard into your DSH session.
It contains no game logic and no copy of ForgeaX. It resolves the @forgeax/game
package that pnpm installed next to it, verifies its identity, and connects it.
What you get
| Surface | Effect |
|---|---|
| Tools | mcp__forgeax__forgeax_status_lite, mcp__forgeax__forgeax_run_current_game |
| Skills | forgeax-game plus every forgeax-engine-* Skill shipped in the resolved package, registered on ctx.skills at boot |
| Guard | Every mcp__forgeax__* call whose target_dir is not the current session cwd is denied. A call that carries no session cwd to compare against (Code Mode, nested dispatch) is allowed after an existence check, and the model is told it was not fully checked |
You do not run forgeax-game devkit install. This bundle registers the Skills
directly; running the installer as well only leaves duplicate copies in your repo
that DSH never reads.
Requirements
- macOS arm64, Linux x64, or Windows x64. This bundle is pure JS and declares no
os/cpu; it inherits its platform reach from@forgeax/game, whose@forgeax/game-runtimeships a native binary as oneoptionalDependenciesentry per platform. Your machine installs only the matching one. Platforms with no published variant (Intel Mac, ARM Linux, ARM Windows) install cleanly but fail when the runtime starts, exactly as@forgeax/gamedoes on its own. pnpmonPATH.dsh pluginis a thin pnpm forwarder; without pnpm it exits127.- Node ≥ 22, matching DSH.
Install
dsh plugin installs into one named profile and self-activates: because this package
declares dsh.bundle, adding it as a dependency also appends it to that profile's
dsh.profile.bundles layer stack.
dsh plugin --profile web add @forgeax/dsh-game
--profile is mandatory — DSH has no implicit default profile, and the layer stack is
per profile. Repeat the command for every profile that should have ForgeaX.
Then restart dsh. Bundle layers are read once at boot; only the profile's own user
patch file is watched. A freshly added bundle is inert until the next launch.
Verify after restarting:
dsh --profile web
# then, in the session:
# ask for the ForgeaX status — the model should call mcp__forgeax__forgeax_status_lite
Configuration
The four rows this bundle inserts, all namespaced so they can never collide with another bundle:
| Row id | Module | Purpose |
|---|---|---|
forgeax-game.launch-spec |
@forgeax/dsh-game/launch-spec |
Resolves + verifies @forgeax/game, publishes the forgeaxGameLaunch service |
forgeax-game.mcp-client |
@deepseek-ai/dsh-mcp-client |
stdio bridge, serverName: forgeax |
forgeax-game.skill-source |
@forgeax/dsh-game/skill-source |
Registers the package's Skills |
forgeax-game.workspace-guard |
@forgeax/dsh-game/workspace-guard |
Tool policy: denies on tools/pre-execute, reports an unverifiable call on tools/post-execute |
The resolver itself lives in a fifth module, @forgeax/dsh-game/forgeax-package, which
imports no framework. Provenance tooling can load it from an installed profile, where the
DSH packages are peers the profile never installs a second copy of.
To change something, add a row with the same id to your profile's user patch file.
A patch replaces the whole config of the targeted row — there is no deep merge — so
you must restate every field you want to keep. For example, to shorten the tool-call
timeout:
# $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
Limits worth knowing
- Tools only. DSH's MCP client bridges tools, not resources.
forgeax://statusis unreachable in a DSH session;mcp__forgeax__forgeax_status_litereturns the same state. The registered Skill says so, so the model does not try the resource. - No transitive bundles. Only packages listed directly in
dsh.profile.bundlescontribute a patch layer. A bundle that depends on this one does not inherit its rows. - One-time ForgeaX operations stay on the CLI. Creating a game, switching the active
game, and upgrading the plugin are
forgeax-game <init|use|doctor|devkit|upgrade>subcommands, not MCP tools.
Failure modes
| Symptom | Cause |
|---|---|
dsh plugin exits 127 |
pnpm not on PATH |
| Runtime fails to start after a clean install | no @forgeax/game-runtime variant for this platform (Intel Mac, ARM Linux, ARM Windows) — none is published yet |
pnpm refuses a git-hosted spec's prepare |
allowlist it under allowBuilds in <profileDir>/pnpm-workspace.yaml (pnpm ≥ 10) |
| ForgeaX tools absent after install | dsh not restarted |
| Boot fails with a launch-spec error | the resolved @forgeax/game does not match the pinned version or is missing bundled Skill assets — reinstall rather than patching around it |
failOnStartupError is true on purpose: a ForgeaX session whose MCP server never
started is broken, not degraded, and a boot-time error is cheaper to read than a
mystery at the first tool call.
Security
- The child process is launched with
env: {}. DSH scrubs the parent environment and mergesconfig.envafter the scrub, so anything listed there would re-inject a secret the harness just removed. - The workspace guard compares
target_diragainst the session cwd afterrealpathresolution — never by string prefix, which symlinks and..defeat. - No API key, token, or secret value is read, stored, or logged by this bundle.
Changelog
Every user-visible change is recorded in CHANGELOG.md. To contribute,
see CONTRIBUTING.md; to report a vulnerability, see
SECURITY.md.
License
MIT
amruthpillai/reactive-resume
anywhere-labs/deepseek-harness-desktop
tt-a1i/archify
strukto-ai/mirage
liustack/modlens
omdsh-dev/DSH-better-sidebar
dsh-market/dsh-market