npm - dsh-hoi4-modding - Versions diffs - 1.0.0 → 1.1.1 - Mend

dsh-hoi4-modding 1.0.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/CHANGELOG.md +32 -0
package/README.md +36 -0
package/package.json +4 -3
package/skills/hoi4-modding/SKILL.md +190 -167
package/skills/hoi4-modding/references/tech-tree-ui.md +257 -0
package/skills/hoi4-modding/scripts/errorlog_triage.py +129 -0
package/skills/hoi4-modding/scripts/item_sprite_check.py +232 -0
package/skills/hoi4-modding/scripts/tech_folder_available.py +176 -0
package/skills/hoi4-modding/scripts/tech_tree_audit.py +183 -0

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,32 @@
+# Changelog
+## 1.1.1
+- 文档同步补丁：README 增加「Publishing」小节（2026 年可用 granular token 直发；**2027-01 起该方式移除**，
+  改用 stage only + `npm stage publish` 或 GitHub Actions Trusted Publishing），CHANGELOG 记录同项。
+  1.1.0 已包含全部功能与脚本，本版仅同步文档，避免 npm 包与仓库不一致。
+## 1.1.0
+科技树 UI 专题（来自一次 2900 科技/多国科技页大型 Mod 的真实排障，全部结论经游戏内对照实验验证）：
+- **新增** `references/tech-tree-ui.md`
+  - `technology_folders.available` 必须用 `original_tag`：用 `has_country_flag` 时引擎建页画线阶段的
+    运行时二次求值失败，**整页连线被静默丢弃**（方框在、日志干净、旧存档正常而新开档必现）。
+  - 大框/小框混排三件套：`force_use_small_tech_layout` + `techtree_<folder>_small_item` 模板 +
+    `GFX_technology_<folder>_small_*_item_bg` **指向真正的小图**（模板 size 只管排版，贴图按像素绘制）。
+  - 拆页/合并页 6 步配方、网格原点统一规则、跨页 path 不画线的必然性。
+  - 三种调试手法：留痕法（改名 gridbox 判断页面是否被建）、对半分实验、对照探针。
+- **新增脚本**
+  - `tech_tree_audit.py`：科技页完整性审计（注册表 ↔ 页面/页签/item 模板/网格/科技/本地化）
+  - `tech_folder_available.py`：`has_country_flag` → `original_tag` 批量迁移（check/apply/revert）
+  - `item_sprite_check.py`：item 模板尺寸 vs 背景精灵实际像素（专治"小框显示成大框 + 偏位"）
+  - `errorlog_triage.py`：error.log 分诊（科技树/贴图/scope/未知字段/本地化），并给出"日志干净即静默跳过"的判语
+- **SKILL.md**：铁律新增 2 条（科技页可用性、大小框三件套）；排错表新增 3 行症状；验收清单新增 2 条；
+  工具与配方索引补充新内容。
+- README：脚本清单、更新记录（中英）。
+- README：补充 npm 发布方式说明（2027-01 起 granular token 直发被移除，改用 stage only / Trusted Publishing）。
+## 1.0.0
+- 首个版本：HOI4 1.19.3 Mod 全流程技能（骨架/国策/事件/决议/理念/角色/科技/州/MIO/特殊项目/GUI/本地化/DDS/校验/安装/排错/发布）。

package/README.md CHANGED Viewed

@@ -21,6 +21,8 @@ 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”.
+npm: https://www.npmjs.com/package/dsh-hoi4-modding
 ## What is inside
 | Path | Purpose |
@@ -34,6 +36,11 @@ for HOI4 modding, or explicitly “load hoi4-modding”.
 | `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 |
+| `skills/hoi4-modding/references/tech-tree-ui.md` | Tech tree UI: folder availability, connection lines, big/small item layouts, split/merge recipes, debugging recipes |
+| `skills/hoi4-modding/scripts/tech_tree_audit.py` | Audit a mod's tech pages: registry vs page/tab/item templates/gridboxes/techs/localisation |
+| `skills/hoi4-modding/scripts/tech_folder_available.py` | Migrate `technology_folders.available` from `has_country_flag` to `original_tag` (check/apply/revert) |
+| `skills/hoi4-modding/scripts/item_sprite_check.py` | Compare item template sizes with the actual item background sprite pixels ("small item looks big") |
+| `skills/hoi4-modding/scripts/errorlog_triage.py` | Triage `error.log`: tech tree / textures / scopes / unknown fields / localisation |
 ## Requirements
@@ -53,6 +60,24 @@ All commands are visible in the conversation before they run.
 ## License
+## Publishing
+- **Now – December 2026**: a granular access token with **Read and write (publish and stage)** and
+  **Bypass 2FA** enabled can publish directly with `npm publish --access public`.
+  npm deprecates this path in **January 2027**.
+- **From January 2027**: use a **stage only** token plus `npm stage publish`, or GitHub Actions
+  **Trusted Publishing** (the bundled `release.yml` already runs on `v*` tags).
+## Changelog
+- **1.1.0** — Tech tree UI knowledge from a real large-mod debugging session: `technology_folders.available`
+  must use `original_tag` (flag-based conditions silently drop every connection line on a page in new games),
+  big/small item mixing requires the small item background **sprites** to point at real small textures,
+  plus three debugging recipes (marker rename, half-split experiment, control probe) and four new scripts.
+- 1.0.0 — Initial release.
+## License
 MIT. The skill text and scripts are original; no Paradox game assets are included.
 ---
@@ -74,6 +99,17 @@ dsh plugin --profile web add github:a1249070611/dsh-hoi4-modding
 刷新/重启后，技能出现在技能目录；直接说「做个 HOI4 mod」「加个国策树」「mod 报错了」即可触发，
 也可以显式说「加载 hoi4-modding 技能」。
+### 本次新增（1.1.0）
+- `references/tech-tree-ui.md`：科技树页面可用性 / 连线 / 大小框混排 / 拆页合并 / 三种调试手法（留痕法、对半分、对照探针）
+- 4 个新脚本：`tech_tree_audit.py`（科技页完整性审计）、`tech_folder_available.py`（旗帜判定→国家标签，批量修复整页无连线）、
+  `item_sprite_check.py`（模板尺寸 vs 背景精灵像素，专治"小框显示成大框"）、`errorlog_triage.py`（error.log 分诊）
+### 发布方式（npm）
+- 2026 年内：Granular token 选 **Read and write (publish and stage)** 并勾选 **Bypass 2FA**，可 `npm publish --access public` 直发；
+  npm 已在页面上提示该方式将于 **2027 年 1 月**移除。
+- 2027 年起：改用 **stage only** token + `npm stage publish`，或 GitHub Actions **Trusted Publishing**
+  （仓库里的 `release.yml` 已在 `v*` 标签触发）。
 ### 依赖
 - DeepSeek Harness（含技能注册表，0.2.x）

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "1.1.1",
+  "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; plus tech tree UI diagnostics (page availability, connection lines, big/small item layouts).",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -15,7 +15,8 @@
     "skills/**/*",
     "README.md",
     "LICENSE",
-    "icon.svg"
+    "icon.svg",
+    "CHANGELOG.md"
   ],
   "dsh": {
     "bundle": {

package/skills/hoi4-modding/SKILL.md CHANGED Viewed

@@ -1,167 +1,190 @@
----
-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`。
+---
+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`。