mcpField
U
underworld-overseer-save-mapper

underworld-overseer-save-mapper

github.com/akillness数据与数据库5353 次安装4 天前更新
代码仓库

关于 underworld-overseer-save-mapper

用于验证 Underworld Overseer JSON 存档并借助上游映射器生成交互式 HTML 地图的技能，适合检查用户自己的存档，不会修改游戏进度，并可核查坐标及渲染结果。

主要功能

  1. 01验证存档 JSON 结构
  2. 02检测重复地图坐标
  3. 03安装或检查上游映射器
  4. 04生成交互式 HTML 地牢地图
  5. 05核验地图边界和渲染控件
  6. 06保持存档文件不变

适用场景

  1. 01打开映射器前验证存档
  2. 02检查坐标范围和描述符
  3. 03生成本地交互式地牢地图
  4. 04排查缺失单元格或地图标签

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/akillness/jeo-skills --skill underworld-overseer-save-mapper

安装后在 Claude Code 中输入/underworld-overseer-save-mapper确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

evals/
evals.json
references/
upstream.md
scripts/
validate_save.py
setup.sh

详细介绍

Underworld Overseer 存档映射器

何时使用此技能

  • 在使用映射器打开 Underworld Overseer .json 存档之前进行验证。
  • 安装或更新上游映射器，而不复制游戏存档。
  • 生成交互式 HTML 地牢地图，或排查缺失的单元格、标签或输出。
  • 检查坐标边界、描述符数量或重复的地图坐标。

请勿将此技能用于无关的存档格式、存档编辑或受保护游戏数据的逆向工程。它用于可视化用户拥有的存档文件，不会修改游戏进度。

说明

步骤 1：保留源存档

请使用副本进行操作。需要确保可复现时，请记录输入路径和哈希值。切勿覆盖游戏当前使用的存档，也不要声称映射器是存档编辑器。

步骤 2：安装或启动任何内容之前，先验证 JSON

运行：

python3 .agent-skills/underworld-overseer-save-mapper/scripts/validate_save.py /path/to/save.json

所需结构为：顶层对象包含一个 Map 列表。每个地图单元格都必须包含整数坐标 X 和 Y，以及非空字符串 DescriptorID。请将重复的 (X, Y) 坐标视为不明确，因为上游渲染器会按坐标索引单元格。

步骤 3：选择最精简的运行模式
  1. 仅检查 — 使用 validate_save.py --json；无需安装映射器。
  2. 生成交互式地图 — 使用 scripts/setup.sh 安装或检查上游程序，然后在本地终端运行其 main.py。
  3. 修改映射器代码 — 克隆固定版本，检查 main.py 和 template.html，并使用已脱敏的测试样例进行测试。

不要仅仅为了解析存档就使用浏览器自动化。只有查看生成的 HTML 时才需要浏览器。

步骤 4：安装或检查上游映射器
bash .agent-skills/underworld-overseer-save-mapper/scripts/setup.sh --check
bash .agent-skills/underworld-overseer-save-mapper/scripts/setup.sh --install

安装程序会使用专用数据目录和虚拟环境。它会安装 pandas 和 matplotlib；pathlib 属于 Python 的一部分，不得从 PyPI 安装。

步骤 5：生成并验证地图

从已安装的仓库运行 main.py。当前上游界面是交互式的，并且会首先查找：

~/AppData/LocalLow/MyronSoftware/UnderworldOverseer/Saves

如果该目录不可用，当前程序会在提供自定义路径选项之前退出；请在受支持的 Windows 配置文件上运行，或进行经过审查的上游代码修改。请确认：

  • 输出 HTML 存在且非空；
  • 渲染的坐标边界与验证器输出一致；
  • 图例中显示了具有代表性的描述符；
  • 搜索、缩放／平移、颜色控件和深色模式均可在本地正常使用；
  • 未修改任何存档文件。
步骤 6：如实说明限制

仓库 README 将该项目描述为 Beta 版。其 README 声明使用 MIT 许可证，但检查过的上游提交中没有根目录下的 LICENSE 文件。请勿将上游代码或二进制文件当作已确认许可证的内容重新分发；请参阅 references/upstream.md。

示例

不渲染地图，仅进行验证
python3 .agent-skills/underworld-overseer-save-mapper/scripts/validate_save.py save.json --json
安装固定版本
REF=5f83b078682d86624941fa451641b01a632455fb \
  bash .agent-skills/underworld-overseer-save-mapper/scripts/setup.sh --install

最佳实践

  1. 备份存档，并在错误报告中使用已脱敏的测试样例。
  2. 在排查 HTML 问题之前，先验证结构和坐标唯一性。
  3. 将依赖项安装隔离在虚拟环境中。
  4. 固定上游提交，以确保输出可复现。
  5. 将生成的 HTML 视为本地数据，因为描述符和布局可能会暴露游戏进度。

参考资料

  • references/upstream.md — 已检查的提交、行为、依赖项和许可证注意事项。
  • 上游仓库

评论

支持 Markdown