Preface¶

When making EU4 mods, common pain points are: scripting effects and triggers easily mix scopes; writing event IDs as bare numbers causes game crashes; and omitting details like localization keys, BOM, namespace, etc., leads to silent failures in-game. Relying solely on model memory to guess syntax makes it hard to align with game files and indexes.

EU4 Mod Workbench is a client plugin for DeepSeek Harness (DSH) with optional accompanying Agent presets. It consolidates documentation verification, script validation, map and event/task views, and AI-oriented instruction generation into a sidebar workspace. It does not launch external programs for you in the background, nor does it directly overwrite Mod files; export and write paths are explicit and reject .. escaping. The following sections introduce its positioning, capabilities, installation, and typical usage.

What is this¶

Plugin repository: shihuadexiaoyugan/eu4-mod-workbench, maintainer shihuadexiaoyugan, categorized as a DSH client plugin. Version in package.json is 0.3.0, license MIT, requires Node >= 20.

One-sentence positioning: A DSH-based visual development workbench for EU4 mods — Host tool + loopback HTTP API + browser React sidebar; built-in with approximately 1901 script documents and 28 scope indexes (lib/docs-data.json), and it declares not to generate EU4 syntax based on memory; query_script_doc only returns real entries from package indexes or game files.

The accompanying Agent preset directory eu4-mod-preset/ is an independent bundle (modern installation entry is cordis.patch.yml, Persona and discipline are in prompt.md) and can be packaged separately from the plugin.

What it doesn’t do (Boundaries)¶

Before installation, you should understand the clear boundaries mentioned in the README:

• It does not draw pixel-perfect maps; the map is a simplified province grid, clicking returns the real province ID.
• It does not launch external programs in the background; bridges like Clausewitz MCP, Eu4-Mod-Editing-Tool, etc., require the user to click to probe/start.
• The UI will no longer write any .txt files directly; the original /api/file/save and /api/missions/save return 410. The editing workflow is changed to generating AI instructions, which are actually written to disk by the Agent’s editing tools, and the Prompt requires running validate_script before and after writing.

Core Functions¶

Host Tools (Agent-callable)¶

The main tools listed in the README include:

There is also eu4_pending_edit (reads and clears pending edits when clear=true), which works with the panel’s “Save as Pending” feature.

Sidebar Panel & Global Tag Synchronization¶

The top “Country Tag” maintains the global activeTag. Maps, event trees, and mission trees filter in sync (according to rules like starting province ownership at 1444). activeTag is persisted to the workspace JSON (POST /api/tag), affecting only rendering, not modifying game/Mod files.

Event/Task editing: After filling out the form, click “Generate AI Instruction” → POST /api/ai/build constructs a Prompt containing [File Path], [Target Location], [Modifications], [Validation Requirements]; this can be copied to a chat or written to pendingEdit in workspace.json.

Other UI capabilities (all based on README): Searchable event dropdowns (bare number event IDs are prohibited), custom dictionary word completion, annual conversion and on-the-fly modifier creation for country modifiers add_country_modifier, event localization contracts (zz_eu4_workbench_l_simp_chinese.yml, BOM, namespace validation), and condition builders like owns/controls and ProvincePicker.

Installation and Enablement¶

Installing Plugin Bundle from GitHub¶

In DSH’s plugin_manager, select install_bundle, and fill in target (replace <username> with the repository owner’s account):

github:<username>/eu4-mod-workbench

This repository has committed index.js, client.js, lib/*.js; no build is required during installation. The repository documentation also mentions that the absolute path of the cloned directory can be used as target; if you install using a local path, please assume responsibility for reviewing the source code yourself.

The plugin bundle’s patch only inserts one Host line eu4-mod-workbench. Do not mount workbench repeatedly, otherwise duplicate tools and routes will be generated; index.ts uses a global active flag to prevent duplication.

Presets and Other Bundles¶

• The preset bundle inserts preset-eu4-mod; do not mount it repeatedly along with workbench.
• The MCP adapter @auggieteo/dsh-mcp-adapter is Host-level; install it once and it should not be mounted again by presets.

Configuration Items¶

The plugin Config supports (excerpted from README):

After modifying TypeScript for local development, run node scripts/build.mjs to regenerate the runtime files; some test scripts require EU4 to be installed locally (default Steam path, can be overridden by EU4_ROOT environment variable).

Typical Usage¶

1. Install Plugin and Point to Mod Workspace¶

After completing install_bundle, set modDir (and eu4Root if necessary) in the plugin configuration. Use eu4_workspace_status or check the sidebar to see if the index and activeTag are normal.

2. Verify before Writing Scripts, Validate after Finishing¶

In the chat, ask the Agent to call:

• search_script_docs / query_script_doc to check trigger/effect names and scopes;
• validate_script to check scope mixing and localization references;
• check_loc_keys to verify if yml keys are complete.

This aligns with the plugin’s design of not generating syntax based on memory.

3. Edit Events/Tasks in the Panel, Let Agent Handle Disk Write¶

1. Select the global Tag in the sidebar, and filter maps/event/mission views as needed.
2. Use the form to edit events or tasks; use the event selector to bind event IDs with dots (e.g., flavor_boh.1) to avoid bare numbers.
3. Click “Generate AI Instruction” or “Save as Pending”, then let the Agent execute eu4_pending_edit or read → write → validate_script again as required by the Prompt, and complete localisation.

4. Map and History Fragments¶

When you need province IDs or batch history, you can use eu4_map_query, eu4_batch_history; the panel’s province selector supports searching by Chinese name, English name, or ID.

Suitable Scenarios and Notes¶

Who is it for: Mod authors who use DSH locally for EU4 Modding, want script validation and documentation indexes to align with game/Mod files, and are willing to use the Agent toolchain to complete final file writing.

Permissions and Security: The plugin runs with the permissions of the current DSH process and can read/write your configured modDir, statePath, and the detected EU4 directory. Please read the repository source code and the MIT license before installation to confirm that paths and external tool calls align with your environment’s policies.

Ecosystem Note: DSH follows the “everything is a plugin” philosophy; community directory sites and DeepSeek/Synthesizer have no official affiliation. The plugin introduced here is a community-maintained client plugin, not an official app store entry.

Conclusion¶

EU4 Mod Workbench brings verification, validation, visual browsing, and structured AI editing instructions into the DSH sidebar and Host tools, and clarifies the boundaries of “the panel does not write txt directly, the Agent is responsible for disk write and re-validation”. For directory information and source code, you can visit the plugin directory page and GitHub repository:

• Directory page: https://www.skillhub.cn/plugins/shihuadexiaoyugan/eu4-mod-workbench
• GitHub: https://github.com/shihuadexiaoyugan/eu4-mod-workbench