dsh-hoi4-modding 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-hoi4-modding contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dsh-hoi4-modding
+
+**English** | [中文](#中文)
+
+A DeepSeek Harness **skill bundle** for Hearts of Iron IV (HOI4) **1.19.3** modding. It registers one
+skill, `hoi4-modding`, which turns the agent into a working HOI4 modder: create a mod from scratch,
+write focus trees / events / decisions / ideas / characters / technologies / MIO / special projects /
+scripted GUI, add localisation and DDS icons, run a static verifier, install into the game, and debug
+`error.log`.
+
+## Install
+
+```sh
+# from npm (market install does the same thing)
+dsh plugin --profile web add dsh-hoi4-modding
+
+# or straight from the source repo
+dsh plugin --profile web add github:a1249070611/dsh-hoi4-modding
+```
+
+Restart / refresh as the host asks. The skill appears in the session skill catalog; invoke it by asking
+for HOI4 modding, or explicitly “load hoi4-modding”.
+
+## What is inside
+
+| Path | Purpose |
+|---|---|
+| `skills/hoi4-modding/SKILL.md` | The skill body: rules, workflow, error-log triage, acceptance checklist |
+| `skills/hoi4-modding/references/cheatsheet.md` | Copy-ready code for 15 common tasks |
+| `skills/hoi4-modding/references/deep-dive.md` | Topic → deep-documentation index |
+| `skills/hoi4-modding/scripts/new_mod.py` | Scaffold a runnable mod (optional focus tree; runs the linter) |
+| `skills/hoi4-modding/scripts/hoi4_lint.py` | Static verifier: syntax, encoding/BOM, localisation, GFX, ID conflicts, `.mod` structure |
+| `skills/hoi4-modding/scripts/install_mod.py` | Copy-install a mod into the player `mod/` directory and enable it |
+| `skills/hoi4-modding/scripts/build_reference.py` | Generate effects/triggers/modifiers/console references from the game's `documentation/*.md` |
+| `skills/hoi4-modding/scripts/dds_helper.py` | Generate / inspect HOI4 DDS icons (needs Pillow) |
+| `skills/hoi4-modding/scripts/pdx_parser.py` | Tolerant PDX script parser used by the linter |
+
+## Requirements
+
+- DeepSeek Harness with the skill registry (0.2.x).
+- **Python 3.10+** for the bundled scripts (stdlib only; `dds_helper.py` needs `pip install pillow`).
+- **HOI4 1.19.3** for the verifier's vanilla index, GFX and ID checks. Without the game the skill still
+  works for scaffolding and code recipes; the game directory is auto-detected (`HOI4_GAME` /
+  `HOI4_USER_DIR` override).
+- No network access, no API keys, no game files are shipped.
+
+## Permissions
+
+The plugin registers skill metadata only. The bundled Python scripts are run by the agent **when the
+user asks**; they read the HOI4 install and, for `install_mod.py`, write into the player
+`Documents/Paradox Interactive/Hearts of Iron IV/mod/` directory (never the game install itself).
+All commands are visible in the conversation before they run.
+
+## License
+
+MIT. The skill text and scripts are original; no Paradox game assets are included.
+
+---
+
+## 中文
+
+**DeepSeek Harness 的 HOI4 1.19.3 Mod 制作技能包。** 安装后注册一个名为 `hoi4-modding` 的技能：
+从零建 Mod、写国策/事件/决议/理念/角色/科技/MIO/特殊项目/scripted GUI、本地化与 DDS 图标、
+静态校验、安装进游戏、按 `error.log` 排错。
+
+### 安装
+
+```sh
+dsh plugin --profile web add dsh-hoi4-modding
+# 或从源码仓库：
+dsh plugin --profile web add github:a1249070611/dsh-hoi4-modding
+```
+
+刷新/重启后，技能出现在技能目录；直接说「做个 HOI4 mod」「加个国策树」「mod 报错了」即可触发，
+也可以显式说「加载 hoi4-modding 技能」。
+
+### 依赖
+
+- DeepSeek Harness（含技能注册表，0.2.x）
+- Python 3.10+（脚本仅标准库；DDS 工具需 Pillow）
+- HOI4 1.19.3（校验器需要；游戏目录自动探测，可用 `HOI4_GAME` / `HOI4_USER_DIR` 覆盖）
+- 不含任何游戏本体资源，不需要网络与 API Key
+
+### 权限说明
+
+插件只注册技能元数据；技能里的 Python 脚本由 agent 在你要求时执行：读取游戏安装目录，
+`install_mod.py` 会把 Mod 复制到玩家 `Documents/Paradox Interactive/Hearts of Iron IV/mod/`
+（不改游戏安装目录）。所有命令在对话中可见。
+
+### 许可
+
+MIT。技能文本与脚本为原创，不包含 Paradox 游戏素材。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: hoi4-modding
+      name: dsh-hoi4-modding

package/icon.svg

@@ -0,0 +1,29 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512">
+  <rect width="512" height="512" rx="96" fill="#12202e"/>
+  <g fill="none" stroke="#5b8db8" stroke-width="10">
+    <circle cx="256" cy="256" r="176" opacity="0.35"/>
+    <circle cx="256" cy="256" r="146" opacity="0.55"/>
+  </g>
+  <g fill="#5b8db8" opacity="0.9">
+    <rect x="246" y="58" width="20" height="34" rx="6"/>
+    <rect x="246" y="420" width="20" height="34" rx="6"/>
+    <rect x="58" y="246" width="34" height="20" rx="6"/>
+    <rect x="420" y="246" width="34" height="20" rx="6"/>
+    <rect x="128" y="96" width="20" height="34" rx="6" transform="rotate(-45 138 113)"/>
+    <rect x="364" y="382" width="20" height="34" rx="6" transform="rotate(-45 374 399)"/>
+    <rect x="96" y="364" width="20" height="34" rx="6" transform="rotate(45 106 381)"/>
+    <rect x="382" y="128" width="20" height="34" rx="6" transform="rotate(45 392 145)"/>
+  </g>
+  <path d="M186 148h96l56 56v160a12 12 0 0 1-12 12H186a12 12 0 0 1-12-12V160a12 12 0 0 1 12-12z"
+        fill="#e8eef4" opacity="0.96"/>
+  <path d="M282 148v52a10 10 0 0 0 10 10h46z" fill="#b9cadb"/>
+  <g fill="#12202e">
+    <rect x="202" y="250" width="118" height="14" rx="7"/>
+    <rect x="202" y="282" width="118" height="14" rx="7"/>
+    <rect x="202" y="314" width="82" height="14" rx="7"/>
+  </g>
+  <text x="256" y="404" font-family="Segoe UI, Arial, sans-serif" font-size="44" font-weight="700"
+        fill="#e8eef4" text-anchor="middle" letter-spacing="2">HOI4</text>
+  <text x="256" y="440" font-family="Segoe UI, Arial, sans-serif" font-size="20" font-weight="600"
+        fill="#8fb4d4" text-anchor="middle" letter-spacing="6">MODDING</text>
+</svg>

package/lib/index.js

@@ -0,0 +1,92 @@
+/**
+ * dsh-hoi4-modding — bundle the HOI4 modding skill into DeepSeek Harness.
+ *
+ * The skill files live in `skills/hoi4-modding/` and stay the single source of
+ * truth (SKILL.md + references + scripts). On load we parse SKILL.md's
+ * frontmatter and register it with the host skill registry, pointing the
+ * resource base at the bundled directory so the model can resolve
+ * `references/...` and `scripts/...` directly.
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const SKILL_DIR = join(HERE, '..', 'skills', 'hoi4-modding')
+const SKILL_FILE = join(SKILL_DIR, 'SKILL.md')
+
+const FALLBACK = {
+  name: 'hoi4-modding',
+  description:
+    'Hearts of Iron IV (HOI4) 1.19.3 modding: create/edit/validate/install/debug mods (focus trees, events, decisions, ideas, characters, technologies, MIO, special projects, GUI, localisation, DDS).',
+  whenToUse:
+    'Use when the user asks to create, edit, fix, validate, install, publish, or debug an HOI4 mod, or asks about HOI4 scripting.',
+}
+
+export const name = 'hoi4-modding-skill'
+export const inject = ['skills']
+
+/** Parse the small YAML frontmatter block used by SKILL.md (name/description/whenToUse). */
+export function parseFrontmatter(raw) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw)
+  if (!match) return { meta: {}, body: raw }
+  const meta = {}
+  for (const line of match[1].split(/\r?\n/)) {
+    const idx = line.indexOf(':')
+    if (idx <= 0) continue
+    const key = line.slice(0, idx).trim()
+    let value = line.slice(idx + 1).trim()
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1)
+    }
+    if (key) meta[key] = value
+  }
+  return { meta, body: raw.slice(match[0].length) }
+}
+
+/** Read the bundled skill and return a registration object for ctx.skills.register(). */
+export function loadSkill() {
+  let raw
+  try {
+    raw = readFileSync(SKILL_FILE, 'utf8')
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    throw new Error(`[dsh-hoi4-modding] cannot read bundled skill at ${SKILL_FILE}: ${reason}`)
+  }
+  const { meta, body } = parseFrontmatter(raw)
+  const description = meta.description || FALLBACK.description
+  const whenToUse = meta.whenToUse || FALLBACK.whenToUse
+  return {
+    name: meta.name || FALLBACK.name,
+    description,
+    whenToUse,
+    content: body.trimStart(),
+    source: 'bundled',
+    provider: 'hoi4-modding',
+    path: SKILL_FILE,
+    resourceBase: { kind: 'directory', path: SKILL_DIR },
+  }
+}
+
+export function apply(ctx) {
+  const register = (target) => {
+    if (typeof target?.skills?.register !== 'function') {
+      target?.logger?.warn?.('[dsh-hoi4-modding] skill registry is unavailable; skill not registered')
+      return
+    }
+    target.skills.register(loadSkill())
+  }
+
+  if (ctx?.skills?.register) {
+    register(ctx)
+  } else if (typeof ctx?.inject === 'function') {
+    ctx.inject(['skills'], (injected) => register(injected))
+  } else {
+    register(ctx)
+  }
+}
+
+export default { name, inject, apply }

package/package.json

@@ -1,6 +1,66 @@
-{
-  "name": "dsh-hoi4-modding",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "dsh-hoi4-modding",
+  "version": "1.0.0",
+  "description": "HOI4 1.19.3 modding skill bundle for DeepSeek Harness: create, edit, validate, install and debug Hearts of Iron IV mods (focus trees, events, decisions, ideas, characters, technologies, MIO, special projects, GUI, localisation, DDS) with bundled verifier/installer scripts.",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "files": [
+    "lib/index.js",
+    "cordis.patch.yml",
+    "skills/**/*",
+    "README.md",
+    "LICENSE",
+    "icon.svg"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-skill": ">=0.1.0-rc.1 <0.3.0-0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-skill": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0",
+    "dsh": ">=0.2.0 <0.3.0"
+  },
+  "scripts": {
+    "test": "node --test tests/smoke.test.mjs"
+  },
+  "keywords": [
+    "deepseek",
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "skill",
+    "hearts-of-iron",
+    "hoi4",
+    "hoi4-modding",
+    "paradox",
+    "modding"
+  ],
+  "icon": "./icon.svg",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/a1249070611/dsh-hoi4-modding.git"
+  },
+  "homepage": "https://github.com/a1249070611/dsh-hoi4-modding#readme",
+  "bugs": {
+    "url": "https://github.com/a1249070611/dsh-hoi4-modding/issues"
+  }
+}

package/skills/hoi4-modding/INSTALL.md

@@ -0,0 +1,78 @@
+# hoi4-modding 技能 —— 安装与共享说明
+
+这是一个 **Agent Skill**：一个以 `SKILL.md`（YAML frontmatter + Markdown 指令）为入口、
+可附带 `scripts/` 与 `references/` 的目录。它不绑定某个具体客户端，**复制目录即可迁移**。
+
+## 目录要求
+
+```
+hoi4-modding/
+├─ SKILL.md          # 必需：frontmatter 含 name、description
+├─ references/       # 可选：参考资料（本技能为 cheatsheet.md、deep-dive.md）
+├─ scripts/          # 可选：可执行工具（Python 3.10+，标准库；DDS 需 Pillow）
+└─ INSTALL.md        # 本文件
+```
+
+## 安装到各平台
+
+| 平台 | 放置位置 | 备注 |
+|---|---|---|
+| **DeepSeek Harness（本项目）** | `~/.agents/skills/hoi4-modding/` | 已安装；重开会话后出现在技能目录 |
+| **Claude Code** | `~/.claude/skills/hoi4-modding/`（个人）或 `<项目>/.claude/skills/hoi4-modding/`（项目级） | 同样读 `SKILL.md` 的 `name`/`description` |
+| **Claude.ai / 支持 Agent Skills 的客户端** | 按其「Skills / 技能」设置上传 zip 或目录 | zip 根目录必须是 `hoi4-modding/`，不要把 `SKILL.md` 放在 zip 顶层 |
+| **其他兼容 Agent Skills 的工具** | 其 skills 目录或配置项 | 只要支持 `SKILL.md` + frontmatter 即可 |
+
+Windows 下路径示例：
+
+```powershell
+# DeepSeek Harness
+Copy-Item -Recurse .\hoi4-modding "$env:USERPROFILE\.agents\skills\hoi4-modding"
+
+# Claude Code
+Copy-Item -Recurse .\hoi4-modding "$env:USERPROFILE\.claude\skills\hoi4-modding"
+```
+
+Linux / macOS：
+
+```bash
+cp -r hoi4-modding ~/.agents/skills/          # DSH
+cp -r hoi4-modding ~/.claude/skills/          # Claude Code
+```
+
+## 运行要求
+
+- **Python 3.10+**（脚本仅用标准库；`dds_helper.py` 需要 `pip install pillow`）。
+- **HOI4 1.19.3** 安装（用于 `hoi4_lint.py` 的原版索引与 GFX/本地化校验）。
+  游戏目录自动探测；探测不到时设置：
+  - `HOI4_GAME`：游戏根目录（含 `hoi4.exe`）
+  - `HOI4_USER_DIR`：玩家数据目录（含 `mod/` 与 `logs/`）
+- 首次运行 `hoi4_lint.py` 会在 `scripts/.cache/` 生成约 6–7 MB 的原版索引（可删除，会自动重建）。
+
+```powershell
+$env:HOI4_GAME = "D:\SteamLibrary\steamapps\common\Hearts of Iron IV"
+$env:HOI4_USER_DIR = "$env:USERPROFILE\Documents\Paradox Interactive\Hearts of Iron IV"
+```
+
+> Linux 上用 Proton 运行 HOI4 时，玩家目录通常在
+> `~/.steam/steam/steamapps/compatdata/394360/pfx/drive_c/users/steamuser/Documents/Paradox Interactive/Hearts of Iron IV`，
+> 请显式设置 `HOI4_USER_DIR`。
+
+## 自检
+
+```powershell
+$S = "<skills>/hoi4-modding/scripts"
+& python "$S\new_mod.py" "$env:TEMP\DemoMod" --name "Demo" --prefix DM --tag LUX
+& python "$S\hoi4_lint.py" "$env:TEMP\DemoMod"
+```
+
+预期：生成成功，`errors=0 warnings=0`。
+
+## 共享边界
+
+- 本技能**不包含任何游戏本体文件/贴图/文本**，只有原创笔记、脚本和代码片段；可自由分享。
+- `references/deep-dive.md` 提到一个可选的本地知识库路径；不存在时技能仍可独立工作（以 cheatsheet 为准）。
+- 游戏更新（如 1.20）后需要更新：`documentation/*.md` 结构、`reference/` 数据、以及本技能里的 1.19 差异条目。
+
+## 更新方法
+
+直接修改技能目录内的文件；若同时维护了知识库项目，修改后同步 `references/deep-dive.md` 的路径索引。

package/skills/hoi4-modding/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: hoi4-modding
+description: 《钢铁雄心4》(Hearts of Iron IV, HOI4) 1.19.3 Mod 开发全流程技能：读游戏文件、新建 Mod、写国策/事件/决议/理念/角色/科技/州/MIO/特殊项目/scripted GUI、本地化与 DDS 图标、静态校验、安装启用、按 error.log 排错、发布创意工坊。Use whenever the user asks to create, edit, fix, validate, install, publish, or debug an HOI4 mod or asks about HOI4 scripting (scopes, effects, triggers, variables, focus trees, events, decisions, ideas, characters, MIO, special projects, GUI, localisation, DDS), even if they only say "做个国策树"/"加个事件"/"mod 报错了".
+whenToUse: 用户要做/改/修/校验/安装/发布 HOI4 Mod，或问 HOI4 脚本写法（scope/effect/trigger/变量/国策/事件/决议/理念/角色/MIO/特殊项目/GUI/本地化/DDS）时。
+---
+
+# HOI4 1.19.3 Mod 制作全流程
+
+面向 **1.19.3.0 "Operation Postern"**（`E:\Steam\steamapps\common\Hearts of Iron IV`）实测整理。
+目标不是讲概念，而是**一次把可运行的 Mod 做出来**：放对文件 → 写对语法 → 本地化齐全 → 校验通过 → 装进游戏 → error.log 干净。
+
+> 本机还保留了一套 57 篇的深度知识库（见文末「深度资料」）：需要查字段细节时读它；本 SKILL 与 `references/` 是压缩版，足够完成 90% 任务。
+
+## 0. 开始前先确认 3 件事
+
+1. **游戏路径**：`E:\Steam\steamapps\common\Hearts of Iron IV`（`HOI4_GAME` 环境变量可覆盖）。
+2. **版本**：`launcher-settings.json` 里 `rawVersion` 应为 `1.19.3.0`；不是就按对应版本调整语法（尤其学说/特殊项目）。
+3. **目标国家有没有专属国策树**：**1.19 每个国家同一时间只有一棵激活国策树**（`country = { }` 是打分，取最高分）。
+   - 没有专属树（用 `generic_focus`，如 LUX、IRE、BHU）：可以新建一整棵树，`add = 10` 就接管。
+   - 已有专属树（SWE、GER、SOV…）：不能"再加一棵"；只能覆盖原树文件、或 `load_focus_tree` 换树（会顶掉原树）。先向用户确认接受哪种。
+
+## 1. 铁律（违反任何一条都会踩坑）
+
+1. **永不改游戏安装目录**；所有内容写在 Mod 目录，装到 `Documents/Paradox Interactive/Hearts of Iron IV/mod/`。
+2. **同名文件 = 整体替换**（不是合并）。优先**新增文件**，不要复制整份原版文件。
+3. **同 ID = 后者覆盖前者**；ID 用你的 `NS_` 前缀，事件用独立 `add_namespace`。
+4. **本地化 `.yml` 必须 UTF-8 with BOM**；目录名与首行根键一致（`english` → `l_english:`，`simp_chinese` → `l_simp_chinese:`）。
+5. **2D sprite 定义放 `interface/*.gfx`**，DDS 文件放 `gfx/interface/...`；`gfx/` 下的 `.gfx` 是 3D 用的。
+6. **图标尺寸**：国策 100×88（+ `_shine`）、理念 60×68、决议 32×33、决议类别 40×51、肖像 156×210、旗帜 82×52 TGA。
+7. **DDS 用未压缩 raw32 最稳**（原版 UI 同构：`dwFlags=0x81007`、无 mipmap）；DXT 要求宽高为 4 的倍数。
+8. **`.mod` 的 `path` 用纯 ASCII 正斜杠**；中文路径可能加载失败 → 用 `install_mod.py` 复制到玩家目录。
+9. **`.mod` 字段是 `picture=`**，不是 `thumbnail=`；`supported_version` 写 `"1.19.*"` 或 `"1.19.3.0"`，写 `*`/`1.*` 会报错。
+10. **不要依赖 DLC**：需要 DLC 内容时用 `has_dlc = "..."` 分支并标注；特殊项目依赖 `Gotterdammerung`。
+11. **错误看 `logs/error.log`**（`[时间][游戏日期][文件:行]: 消息`），只 grep 自己的文件名/ID；原版噪声占 95%+。
+12. **脚本改动必须重启游戏**，没有完整热重载；静态校验不能替代进游戏。
+
+## 2. 标准工作流
+
+```
+0) 侦察    读游戏文件确认目标系统/字段/原版参考（grep 原版用例）
+1) 骨架    scripts/new_mod.py 生成 descriptor.mod + .mod + 本地化 + 示例内容
+2) 内容    按 references/cheatsheet.md 的配方逐类添加（国策/事件/决议/理念/角色/科技/州/GUI…）
+3) 本地化  每个 ID 同时补 english + simp_chinese（BOM），key 规则见 cheatsheet §2
+4) 校验    python scripts/hoi4_lint.py <Mod目录>
+5) 安装    python scripts/install_mod.py <Mod目录> --yes --enable
+6) 实测    启动游戏（-debug_mode）→ 新开档 → 控制台触发 → 看 error.log
+7) 发布    descriptor.mod 的 name/supported_version/tags/picture 齐全；干净 playset 复测
+```
+
+每次只加一类内容、加完就校验；不要一次写 2000 行再排错。
+
+## 3. 配方索引（代码在 `references/cheatsheet.md`）
+
+| 任务 | 章节 |
+|---|---|
+| 新建 Mod 骨架 / `.mod` 与 `descriptor.mod` | cheatsheet §1 |
+| 本地化规则、key 命名、颜色/变量/图标 | §2 |
+| 国家精神（idea） | §3 |
+| 国策树（含一国一树规则、互斥/前置/奖励） | §4 |
+| 事件（MTTH / is_triggered_only / 选项 / 事件链） | §5 |
+| 决议（category / decision / targeted / 任务型） | §6 |
+| 角色（领袖/顾问/将领/科学家） | §7 |
+| 科技（folder / dependencies / on_research_complete） | §8 |
+| 州、资源、建筑 | §9 |
+| 动态变量 + 动态修正 | §10 |
+| scripted GUI 面板（4 文件挂载） | §11 |
+| MIO / 特殊项目 | §12 |
+| 贴图、DDS、GFX 注册 | §13 |
+| 调试命令与 error.log 对照表 | §14 |
+| 1.19 与旧教程差异清单 | §15 |
+
+## 4. 工具（`scripts/`，仅标准库；DDS 工具需 Pillow）
+
+`$S` = **本技能资源目录**下的 `scripts`（加载技能时返回的 Base directory；本地安装通常是
+`~/.agents/skills/hoi4-modding/scripts`，从插件市场安装时在插件包的 `skills/hoi4-modding/scripts`）。
+Windows PowerShell 示例（`python` 不可用时换成本机 Python 绝对路径）：
+
+```powershell
+$S = "$env:USERPROFILE\.agents\skills\hoi4-modding\scripts"   # 市场安装：换成技能返回的 Base directory\scripts
+$GAME = "E:\Steam\steamapps\common\Hearts of Iron IV"
+
+# 新建 Mod 骨架（--focus 可选；--tag 默认 LUX，因为 LUX 没有专属国策树）
+& python "$S\new_mod.py" "D:\mods\MyMod" --name "My Mod" --prefix MY --tag LUX --focus
+
+# 静态校验（语法/编码/本地化/GFX/ID冲突/.mod 结构；首次约 20s 建原版索引）
+& python "$S\hoi4_lint.py" "D:\mods\MyMod" --game $GAME
+
+# 只查语法、不建原版索引（快）
+& python "$S\hoi4_lint.py" "D:\mods\MyMod" --no-vanilla
+
+# 从官方 documentation/*.md 生成 effects/triggers/modifiers/console 参考
+& python "$S\build_reference.py" --game $GAME --out .\reference
+
+# 安装到玩家 mod 目录并启用（复制安装；不要 --link，路径含中文时会被警告）
+& python "$S\install_mod.py" "D:\mods\MyMod" --yes --enable
+
+# 卸载
+& python "$S\install_mod.py" "D:\mods\MyMod" --uninstall --yes
+
+# DDS 图标：生成/检查（Pillow）
+& python "$S\dds_helper.py" make icon.png out.dds --width 60 --height 68
+& python "$S\dds_helper.py" check out.dds
+```
+
+> Git Bash 中把 `$S\x.py` 写成 `"$S/x.py"`、`$GAME` 写成 `/e/Steam/...` 即可。
+> 本机 DSH 自带 Python：`C:\Users\17876\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\python\python.exe`（含 Pillow）。
+
+`new_mod.py` 会生成：`descriptor.mod`、同级 `.mod`（path 指向目标目录）、`localisation/{english,simp_chinese}`（BOM）、1 个理念、`events/` 1 个可触发事件、可选国策树；并自动跑一次 lint。
+
+## 5. 排错：从 error.log 反推
+
+先确认「只启用原版 + 你的 Mod」，再 grep 自己的文件/ID：
+
+| error.log 关键字 | 常见原因 | 修法 |
+|---|---|---|
+| `Invalid Scope, supported: Country, provided: None` | effect/trigger 用错 scope | 查效果文档的 `Supported Scopes`；用 `every_country`/`GER = { }` 切 scope |
+| `Unknown effect-type: xxx` | 关键字拼错/版本没有/不在该 scope | `grep xxx reference/effects.json`；对照 1.19 官方文档 |
+| `Unknown trigger-type` / `Not a valid value` | trigger 名或参数值错误 | 查 `reference/triggers.json`；值看文档枚举 |
+| `Unknown modifier: xxx` | 修正名拼错（静态修正/动态修正都会） | `grep xxx reference/modifiers.json` |
+| `Unexpected token` | 括号/引号不平衡；`.mod` 字段拼错（如 `thumbnail`） | 跑 lint；检查 `picture=`/`path=` |
+| `Tried to get dynamic token` / `dynamic token ... OOS` | 本地化/脚本拼接 key 未注册 | 改用普通 loc key 或 `synchronized_dynamic_tokens` |
+| 图标空白/黑块 | GFX 未注册、texturefile 不存在、DDS 头不对 | `dds_helper.py check`；确认 sprite 在 `interface/*.gfx` |
+| 中文方框 | GUI 用了没有中文 `bitmapfont_override` 的字体名 | 换有中文覆盖的字体（见知识库 `05_presentation/chinese_fonts.md`） |
+| 国策树不显示 | 原版树分数更高；或树 id/坐标错误 | 按 §4 规则选「无专属树国家」或覆盖原树 |
+
+游戏内调试：`-debug_mode` 启动，控制台（`~`/`^`）常用 `event hho.1`、`focus.autocomplete`、`debug_events`、`tag SWE`、`pp 500`；完整命令见 `reference/CHEATSHEET_console.md`（若已生成）。
+
+## 6. 验收清单
+
+- [ ] `hoi4_lint.py` 0 error（warning 尽量清零）。
+- [ ] 所有新增 ID 有 en + zh 本地化，`.yml` 带 BOM。
+- [ ] 所有 `GFX_` 引用真实存在；自绘 DDS 尺寸/格式正确。
+- [ ] 没有覆盖原版整文件（除非有意）；`.mod` path 为 ASCII。
+- [ ] 干净 playset 进游戏：新开档、触发全部内容、`error.log` 无自己文件的报错。
+- [ ] 发布信息（name/supported_version/tags/picture/README/依赖 DLC）齐全；联机 checksum 一致。
+
+## 7. 深度资料
+
+本机知识库（若存在，优先读具体主题文档）：
+
+```
+C:\Users\17876\Desktop\DeepseekHarness\钢铁雄心4\
+├─ PLAYBOOK.md                 # 14 个任务配方（最常用）
+├─ knowledge/00_environment.md # 两个根目录、加载顺序、覆盖语义、日志、性能
+├─ knowledge/01_script/        # scope / effect/trigger / 变量 / 动态变量 / on_actions
+├─ knowledge/02_content/       # 国策/事件/决议/理念/角色/科技/MIO/特殊项目…
+├─ knowledge/03_military/、04_world_map/、05_presentation/、06_workflow/
+├─ reference/                  # 自动生成的 effects/triggers/modifiers/console 数据
+└─ example_mods/               # 两个可运行示例（hello_hoi4 / advanced_systems）
+```
+
+不在本机时：用 `references/cheatsheet.md` + 游戏自带 `documentation/*.md`（官方字段参考，但注意它**不是全集**：`unit_modifiers`、`is_fighting_in_strategic_region`、`is_deployed` 等 1.19 可用写法未收录，冲突时以游戏文件为准）。
+
+## 8. 跨平台与共享
+
+本技能是标准 Agent Skills 目录（`SKILL.md` + 可选 `scripts/`、`references/`），复制即可迁移：
+
+| 平台 | 安装位置 |
+|---|---|
+| DeepSeek Harness | `~/.agents/skills/hoi4-modding/` |
+| Claude Code | `~/.claude/skills/hoi4-modding/` 或项目内 `.claude/skills/hoi4-modding/` |
+| 其他兼容客户端 | 其 Skills 设置/目录；zip 根目录必须是 `hoi4-modding/` |
+
+- 游戏/玩家目录会**自动探测**；探测失败时设 `HOI4_GAME` / `HOI4_USER_DIR`（Linux Proton 必须设 `HOI4_USER_DIR`）。
+- 依赖：Python 3.10+（标准库；DDS 需 Pillow）+ 本机 HOI4 1.19.3。
+- 共享边界：不含游戏本体资源，只有原创笔记/脚本；不依赖本机知识库也能运行（`references/cheatsheet.md` 自足）。
+- 详细安装/自检/更新说明见同目录 `INSTALL.md`。