dsh-hoi4-modding 1.1.1 → 1.2.0

package/skills/hoi4-modding/SKILL.md

@@ -1,190 +1,210 @@
----
-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. **脚本改动必须重启游戏**，没有完整热重载；静态校验不能替代进游戏。
-13. **科技页（`technology_folders`）的 `available` 只用 `original_tag`，不要用 `has_country_flag`**：
-    引擎建页画线时会对该触发器做二次运行时求值，旗帜判定失败时**整页连线被静默丢弃**（方框还在、日志干净、旧存档可能正常而新开档必现）。见 `references/tech-tree-ui.md` §3。
-14. **大框/小框混排是三件套**：科技加 `force_use_small_tech_layout = yes` + 页面有 `techtree_<folder>_small_item` 模板 +
-    `GFX_technology_<folder>_small_*_item_bg` 精灵**指向真正的小图**。模板 size 只管排版，背景贴图按自身像素绘制——精灵还指着 203×84 大图时，画面就是"小框模板 + 大框外观 + 整体偏位"。
-
-## 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 |
-| **科技树 UI：页面可用性 / 连线 / 大小框 / 拆页合并 / 调试手法** | `references/tech-tree-ui.md` |
-| 州、资源、建筑 | §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
-
-# 科技页完整性审计（注册表 <-> 页面/页签/item 模板/网格/科技/本地化）
-& python "$S/tech_tree_audit.py" "D:/mods/MyMod"
-
-# 科技页可用性：has_country_flag -> original_tag（--check 先看，--apply 写入并备份，--revert 回滚）
-& python "$S/tech_folder_available.py" "D:/mods/MyMod" --check
-& python "$S/tech_folder_available.py" "D:/mods/MyMod" --apply
-
-# item 模板尺寸 vs 背景精灵像素（专治"小框显示成大框"）
-& python "$S/item_sprite_check.py" "D:/mods/MyMod" --folder my_folder
-
-# error.log 分诊（科技树 / 贴图 / scope / 未知字段 / 本地化）
-& python "$S/errorlog_triage.py"
-```
-
-> 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 规则选「无专属树国家」或覆盖原树 |
-| 科技页**方框全在、连线一条没有**、日志干净 | `technology_folders.available` 用了 `has_country_flag`，建页画线阶段判定失败 → 整页 path 静默丢弃 | 改成 `original_tag = <TAG>`（`tech_folder_available.py`），**新开档**验证 |
-| 小框科技显示成大框且整体偏位 | 小框模板生效了，但 `GFX_technology_<folder>_small_*_item_bg` 指向 203×84 大图 | `item_sprite_check.py` 定位后把 textureFile 换成 72×72 小图 |
-| 某页永远不显示 | `available = { always = no  NOT = {...} }`（AND 关系恒 false） | 去掉 `always = no`，只留 `NOT = {...}` 或 `original_tag` |
-
-游戏内调试：`-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` 无自己文件的报错。
-- [ ] **新开档**逐个相关国家打开科技页确认连线（旧存档会掩盖 available 触发器的时机问题）。
-- [ ] `tech_tree_audit.py` 报告 0 问题；大小框混排页跑 `item_sprite_check.py` 无可疑项。
-- [ ] 发布信息（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`。
+---
+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, tank designer/module slots/2D icons/3D models), 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. **脚本改动必须重启游戏**，没有完整热重载；静态校验不能替代进游戏。
+13. **科技页（`technology_folders`）的 `available` 只用 `original_tag`，不要用 `has_country_flag`**：
+    引擎建页画线时会对该触发器做二次运行时求值，旗帜判定失败时**整页连线被静默丢弃**（方框还在、日志干净、旧存档可能正常而新开档必现）。见 `references/tech-tree-ui.md` §3。
+14. **大框/小框混排是三件套**：科技加 `force_use_small_tech_layout = yes` + 页面有 `techtree_<folder>_small_item` 模板 +
+    `GFX_technology_<folder>_small_*_item_bg` 精灵**指向真正的小图**。模板 size 只管排版，背景贴图按自身像素绘制——精灵还指着 203×84 大图时，画面就是"小框模板 + 大框外观 + 整体偏位"。
+15. **坦克设计器是全局 GUI**：改 `interface/tank_designer_view.gui` 会影响所有国家/底盘；窗口背景 `GFX_tank_designer_popup_bg` 是**固定 1092×553 贴图**，只加高窗口而不换背景 → 内容溢出到窗口外/地图上（见 `references/tank-designer.md` §4.3）。
+16. **槽位按钮位置 ≠ 槽位数据**：`pos_custom_module_slot_window_N` 决定按钮在界面上的位置，底盘 `module_slots` 的**书写顺序**决定第 N 个位置是哪一类槽；模块类别由模块的 `category =` 隐式创建（`references/tank-designer.md`）。
+
+## 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 |
+| **科技树 UI：页面可用性 / 连线 / 大小框 / 拆页合并 / 调试手法** | `references/tech-tree-ui.md` |
+| 州、资源、建筑 | §9 |
+| 动态变量 + 动态修正 | §10 |
+| scripted GUI 面板（4 文件挂载） | §11 |
+| MIO / 特殊项目 | §12 |
+| 贴图、DDS、GFX 注册 | §13 |
+| **坦克设计器：16 槽布局 / 加高窗口 / 隐藏升级区 / 模块类别** | `references/tank-designer.md` |
+| **坦克 3D 模型：复用原版实体 / 换贴图 / 自制 mesh** | `references/tank-models-3d.md` |
+| **科技/装备图标：照片→173×77 DDS、去背、安全区** | `references/icon-dds-pipeline.md` |
+| 调试命令与 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
+
+# 坦克设计器体检（窗口/槽位位置/槽位模板/模块类别/底盘槽数/背景尺寸）
+& python "$S	ank_designer_probe.py" --game $GAME
+
+# 生成坦克设计器槽位布局（默认 16 槽紧凑版，写 mod/interface/tank_designer_view.gui；不修改游戏目录）
+& python "$S	ank_designer_layout.py" --mod "D:\mods\MyMod" --dry-run
+& python "$S	ank_designer_layout.py" --mod "D:\mods\MyMod"
+
+# 科技卡图标：照片/矢量图 → 173×77 DDS（去背 + 安全区 + 183×84 卡片预览）
+& python "$S	ech_icon_import.py" "虎式E型.png" out/GER_tiger_e.dds --card-preview preview.png
+
+# 科技页完整性审计（注册表 <-> 页面/页签/item 模板/网格/科技/本地化）
+& python "$S/tech_tree_audit.py" "D:/mods/MyMod"
+
+# 科技页可用性：has_country_flag -> original_tag（--check 先看，--apply 写入并备份，--revert 回滚）
+& python "$S/tech_folder_available.py" "D:/mods/MyMod" --check
+& python "$S/tech_folder_available.py" "D:/mods/MyMod" --apply
+
+# item 模板尺寸 vs 背景精灵像素（专治"小框显示成大框"）
+& python "$S/item_sprite_check.py" "D:/mods/MyMod" --folder my_folder
+
+# error.log 分诊（科技树 / 贴图 / scope / 未知字段 / 本地化）
+& python "$S/errorlog_triage.py"
+```
+
+> 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` |
+| 坦克设计器内容溢出窗口/跑到地图上 | 窗口加高但背景贴图固定 1092×553 | 用 `tank_designer_layout.py` 生成紧凑布局，或按 `references/tank-designer.md` §4.3 做加高背景 sprite |
+| 坦克设计器槽位数/位置不对 | 界面位置数 与 底盘 `module_slots` 数量/顺序不一致 | `tank_designer_probe.py` 打印两者后对比 |
+| 设计器槽位互相叠压/挤出容器 | 槽位模板宽 76px > 列距/容器宽 | 列距 ≥76 或加宽 `equipment_modules`（原版 73 列距本身叠 3px） |
+| 中文方框 | GUI 用了没有中文 `bitmapfont_override` 的字体名 | 换有中文覆盖的字体（见知识库 `05_presentation/chinese_fonts.md`） |
+| 国策树不显示 | 原版树分数更高；或树 id/坐标错误 | 按 §4 规则选「无专属树国家」或覆盖原树 |
+| 科技页**方框全在、连线一条没有**、日志干净 | `technology_folders.available` 用了 `has_country_flag`，建页画线阶段判定失败 → 整页 path 静默丢弃 | 改成 `original_tag = <TAG>`（`tech_folder_available.py`），**新开档**验证 |
+| 小框科技显示成大框且整体偏位 | 小框模板生效了，但 `GFX_technology_<folder>_small_*_item_bg` 指向 203×84 大图 | `item_sprite_check.py` 定位后把 textureFile 换成 72×72 小图 |
+| 某页永远不显示 | `available = { always = no  NOT = {...} }`（AND 关系恒 false） | 去掉 `always = no`，只留 `NOT = {...}` 或 `original_tag` |
+
+游戏内调试：`-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` 无自己文件的报错。
+- [ ] **新开档**逐个相关国家打开科技页确认连线（旧存档会掩盖 available 触发器的时机问题）。
+- [ ] `tech_tree_audit.py` 报告 0 问题；大小框混排页跑 `item_sprite_check.py` 无可疑项。
+- [ ] 坦克设计器：窗口背景覆盖整个窗口；槽位位置数 = 底盘 `module_slots` 数；槽位不叠压、能选模块并保存设计。
+- [ ] 坦克 3D：`graphic_db` 的 `models` 实体存在，`.asset` 至少 `idle/move/attack` 三个 state，贴图齐全。
+- [ ] 发布信息（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`。

package/skills/hoi4-modding/references/cheatsheet.md

@@ -555,3 +555,60 @@ spriteTypes = {
 - **理念**：支持 `on_add`/`on_remove`（旧教程说没有是错的）。
 - **文档滞后**：官方 `documentation/*.md` 不是全集（`unit_modifiers`、`is_fighting_in_strategic_region`、`is_deployed` 等未收录），冲突以游戏文件为准。
 - **路径**：`.mod` 的 `path` 建议纯 ASCII；`-debug_mode` 不是 `-debug`。
+
+
+## 16. 坦克设计器 / 3D 模型 / 图标（速查）
+
+### 16.1 坦克设计器文件
+
+| 文件 | 作用 |
+|---|---|
+| `interface/tank_designer_view.gui` | 窗口、`equipment_modules`（槽位容器）、`pos_custom_module_slot_window_N`（每个槽的坐标） |
+| `interface/equipmentdesignerview.gui` | 通用控件；`equipment_designer_module_slot_entry` 槽位按钮模板 = **76×47** |
+| `interface/equipmentdesigner/tanks/*.gui` | 每类底盘蓝图（`equipment_designer_<底盘>` / archetype 回退） |
+| `common/units/equipment/tank_chassis.txt` | archetype 的 `module_slots`；普通底盘 `module_slots = inherit` |
+| `common/units/equipment/modules/*.txt` | 模块；`category =` 隐式建类别 |
+| `gfx/interface/equipmentdesigner/graphic_db/*.txt` | `graphic_db = { GFX_2d_icon models = { ENTITY } }` |
+
+原版 9 槽顺序（= 数据 `module_slots` 顺序）：炮塔/主武器/悬挂/装甲/引擎/特殊1–4；
+界面位置 `pos_0..8` 由原版 GUI 决定，改槽数 = 加 `pos_custom_module_slot_window_N` + 底盘多写槽。
+
+### 16.2 16 槽紧凑布局（不加高窗口）
+
+```pdx
+@fixed_btn_mod_col_0 = 0
+...
+@fixed_btn_mod_col_6 = 432
+@fixed_btn_mod_row_0 = 0     # 上排 7
+@fixed_btn_mod_row_1 = 50    # 第二排 2（通信左 / 工程右）
+@fixed_btn_mod_row_2 = 300   # 下排 7
+```
+
+- 窗口高 542 不用加高；蓝图保持 `position {x=3 y=50} size 508×248`；
+- 隐藏 `equipment_upgrade_0/1`、auto 按钮：把 position 改成 `-4000/-4000`；
+- 槽位宽 76、列距 72（原版就是 73）→ 相邻叠 4px，视觉连成一排；要严格不叠压需加宽容器。
+
+### 16.3 3D 模型四层
+
+```
+graphic_db models = { ENTITY }
+  → gfx/entities/*.asset  entity = { name pdxmesh = ... state = {idle/move/attack} }
+  → gfx/entities/*.gfx    pdxmesh = { name file = "gfx/models/units/tanks/x.mesh" }
+  → gfx/models/units/tanks/*.mesh + *.anim + *_diffuse/_normal/_specular.dds
+```
+
+复用原版：`GER_iw_armor_entity` / `GER_light_armor_entity` / `GER_medium_armor_entity` /
+`GER_heavy_armor_entity` / `GER_super_heavy_armor_entity`。
+
+### 16.4 科技卡图标 173×77
+
+```
+Icon 控件中心 x=74（卡宽 183）→ 内容右移 8px：左留 20 / 右留 4 / 上下 2，最大内容 149×73
+```
+
+- 透明 PNG 最好；白底/棋盘格需要去背；**白色涂装保护**：区域亮度≥235 且 relY<0.8 → 保留；
+- 输出 raw32 DDS 173×77，sprite 名 `GFX_<tech>_medium`；
+- 批量导入必须有别名表（文件名≠科技 id 时）。
+
+对应脚本：`tank_designer_probe.py` / `tank_designer_layout.py` / `tech_icon_import.py`，
+专题文档 `references/tank-designer.md`、`references/tank-models-3d.md`、`references/icon-dds-pipeline.md`。

package/skills/hoi4-modding/references/icon-dds-pipeline.md

@@ -0,0 +1,123 @@
+# 科技/装备 2D 图标流水线：照片 → 173×77 DDS（实战）
+
+> 适用：把坦克照片/矢量图做成 HOI4 科技卡图标、装备 2D 图标；处理白底/棋盘格/阴影、保护白色涂装、
+> 解决“图标出框 / 偏左 / 白边 / 涂装被挖空”。
+> 本文是 `hist_tech_trees`（30 辆德国坦克科技）全套照片图标的量产经验。
+
+## 0. 关键结论（先看这 4 条）
+
+1. **科技卡图标画布 173×77**；卡片背景 183×84，卡内 `Icon` 控件是 `position {x=74 y=50}` + `centerposition`，
+   所以 **173 宽的图在 183 卡里左右各出 5px**：内容必须留安全边距，否则炮管/履带会被卡片边框裁掉。
+2. 原版照片/渲染图多数是**白底或 8px 棋盘格（纯白+灰 130/192）**，必须去背景；透明 PNG 最省事，优先找。
+3. **白色涂装/白色编号会被“去白底”算法一起挖掉**：保护规则 = 区域平均亮度 ≥235 **且** 相对位置偏上（relY<0.8）→ 保留。
+4. 批量导入必须有 **别名表**：文件名 ≠ 科技中文名（如 `四号坦克F型.png` → `GER_pz4_f1`、`38(t)A型`、`35(t)`）。
+
+## 1. 卡片几何：为什么图标要“右移”
+
+```pdx
+# countrytechtreeview.gui 的 item 模板（原版）
+containerWindowType = { name = "techtree_GER_armor_item" size = { width = 183 height = 84 }
+	iconType = { name = "Icon" position = { x = 74 y = 50 } centerposition = yes }
+	instantTextBoxType = { name = "Name" position = { x = 6 y = -1 } }
+	background = { spriteType = "GFX_technology_unavailable_item_bg" }  # 286×109
+}
+```
+
+- 卡片可见内容区约 **183×84**；`Icon` 的中心在卡片 x=74，而卡片中心是 91.5 → 图标整体天然偏左 17.5px。
+- 因此 **173×77 的图标内容**建议：
+  - 水平：左边距 **20px**、右边距 **4px**（内容整体右移 8px，把炮管/车身放在视觉中心）；
+  - 垂直：上下各留 **2px**，最大内容 **149×73**。
+- 具体数值可按立绘方向微调（炮口朝左的图可反过来），但**右侧不能顶满**，否则车头/炮口出框。
+
+## 2. 输入类型与去背景
+
+| 输入 | 处理 |
+|---|---|
+| 透明 PNG/WebP（矢量导出） | 直接用 alpha，最省事；裁 bbox → 缩放 → 贴到安全区 |
+| 纯白底 | 从边界 flood fill 去白（容差 ~12），保留内部白色（高光/白涂装） |
+| 8px 棋盘格（白 + 灰 130/192） | 先识别两种背景色，按“边界连通 + 颜色接近任一背景色”泛洪；再做 1px 腐蚀+描边 |
+| 阴影/渐变背景 | 难；优先找透明版，或 PS 手动抠图 |
+| 白底带白色涂装 | 用第 3 条保护规则，否则涂装会被挖空 |
+
+推荐流程：
+
+```
+1) 转 RGBA
+2) 估计背景色：取四条边上的高频中性色（R≈G≈B），最多取 2 个峰
+3) 从边界 flood fill：颜色接近任一背景色 → 透明
+4) 保护：连通的“白色区域”若 平均亮度≥235 且 中心 relY<0.8 → 保留（白涂装/编号）
+5) 其他内部洞（履带缝、观察窗）：用前景色填充或按最近深色覆盖
+6) 腐蚀 1px（去掉白边），边缘轻微重着色
+7) 预乘 alpha 下采样（避免灰边）
+8) 裁 bbox → 按最大 149×73 等比缩放 → 贴到 173×77 画布的安全位置（左 20/右 4/上下 2）
+9) 输出 PNG + DDS（dds_helper raw32 173×77）
+10) 合成 183×84 卡片预览，检查不越框
+```
+
+## 3. 别名与匹配
+
+批量导入时用**文件名模糊匹配** + 显式别名表：
+
+```python
+ALIASES = {
+    "四号坦克F型": "GER_pz4_f1",      # 早期 F1（短管）与后期 F2 区分
+    "38(t)A型":  "GER_pz38t_ad",
+    "35(t)":     "GER_pz35t",
+}
+```
+
+匹配顺序：`big_zh/big_en` 精确 → 小名（small_zh）精确 → 小名首词 → 唯一子串包含 → 别名表。
+**不要用“任意包含”直接命中**：`四号坦克F型` 会同时匹配 F1/F2/G/H，必须最先用别名表消歧。
+
+## 4. 输出与注册
+
+```bash
+python "$S/dds_helper.py" make GER_pz4_f1.png \
+  gfx/interface/technologies/GER_armor/GER_pz4_f1.dds --width 173 --height 77
+python "$S/dds_helper.py" check gfx/interface/technologies/GER_armor/GER_pz4_f1.dds
+```
+
+```pdx
+# interface/NS_tech_icons.gfx
+spriteTypes = {
+	spriteType = { name = "GFX_GER_pz4_f1_medium" texturefile = "gfx/interface/technologies/GER_armor/GER_pz4_f1.dds" }
+}
+```
+
+- 科技卡模板里图标 sprite 名按原版约定：`GFX_<tech>_medium`（`<tech>_small` 用于小框）；
+- **每张图 173×77，raw32 未压缩**（原版 UI 同构；体积约 53KB/张，30 张 1.6MB，可接受）；
+- 共享占位图标时只注册一张 sprite，多个科技共用。
+
+## 5. 卡片预览自检（不越框）
+
+```python
+CARD = Image.open(GAME / "gfx/interface/techtree/technology_available_item_bg.dds").convert("RGBA")
+card = CARD.resize((183, 84), Image.LANCZOS)
+icon = Image.open("GER_pz4_f1.png").convert("RGBA")
+card.alpha_composite(icon, (74 - icon.width // 2, 50 - icon.height // 2))
+card.save("preview_card.png")
+```
+
+检查点：炮管/车头不出框；左右留白均衡（视觉重心略右）；与同排其他卡片的车体大小一致（缩放按“车长”统一，
+不要按图片 bbox 高度统一，否则炮塔高低不一）。
+
+## 6. 踩坑表
+
+| 症状 | 原因 / 修法 |
+|---|---|
+| 图标左侧被裁 | 内容顶满 173 宽；加大 left margin（本项目用 20px） |
+| 图标整体偏左 | 没考虑 Icon 控件中心 x=74；内容整体右移 8px |
+| 白边/灰边 | 未腐蚀边缘；缩放前未预乘 alpha |
+| 白色涂装/编号被挖空 | 缺少白涂装保护规则（亮度≥235 + relY<0.8） |
+| 棋盘格残留 | 只按单色去背；需检测两种背景色并联合泛洪 |
+| 各卡大小不一 | 缩放基准不一致（按车长/统一系数，而不是 bbox 高） |
+| 导入后图标不显示 | sprite 没注册 / 路径大小写 / DDS 尺寸不对（必须 173×77 或模板要求尺寸） |
+| 装备图标显示错位 | 装备 2D 图标尺寸不同（原版 81×37 等），不要拿科技卡 173×77 混用 |
+
+## 7. 配套脚本
+
+`scripts/tech_icon_import.py`（需 Pillow）：
+- 单张/批量（目录或 JSON 映射）输入 → 去背（transparent / white / checker / auto）→ 安全区 173×77 →
+  PNG + DDS（调用 `dds_helper.py`）；
+- `--card-preview` 输出 183×84 合成卡，直接目检是否出框；
+- `--alias alias.json` 传文件名→科技 id 映射，批量时用于消歧。