modmgr 0.0.2

File mapping and backup rule engine for workshop mods

---

status: active concept: readme applicable-to: human update: 2026-05-20

The Knighthana's Mod Manager

项目仍然处于开发阶段，部分核心功能正在深度重构和优化，欢迎开发者加入讨论和贡献，但目前不建议一般用户直接用于生产环境

探索性开发已告一段落，因个人工作变动，项目短期内将进入低活跃维护状态，欢迎有兴趣的开发者参与。

This repository provides the full source tree, including the frontend and build tooling. For PyPI, the current release path is intentionally narrower: install the core package first, and use GitHub for the full web-enabled development experience.

如果你希望获得完整的 Web 界面和前端源码，请直接使用本仓库的 GitHub 版本。 如果你只是想先通过 PyPI 安装核心能力，目前发布物会优先保证 CLI / 后端逻辑可用。

简介

The Knighthana's Mod Manager(简称KMM)通过对"文件迁移过程"进行脱离具体环境的语义化定义和简单执行，实现对MOD->本体，MOD->MOD，还包括诸如MOD->MOD->MOD->本体这样嵌套方式的支持；

并且针对具体的替换规则，实现原文件的备份保护和按需还原；

作为“文件操作语义定义与管理”的雏形想法，这个项目初期在Steam游戏本体<->Steam创意工坊这样的环境上进行实践；

作为普通用户

(请普通用户在这段话被删掉之前，不要在生产环境中使用，现在项目还在深度重构中，所有底层改动不会向前兼容，不能对执行预期和稳定性做出任何保证。以下是预留给未来的说明，作为项目需求的一部分。)

Quickstart（开发者 / 尝鲜用户）

# 安装核心包
pip install modmgr

# 安装 Web 界面（可选）
pip install modmgr[web]

# 启动 Web 服务（需先安装 web 依赖）
modmgr-web          # → http://127.0.0.1:8000

# CLI 模式
modmgr-cli --help

首次启动会自动在平台默认位置创建 user_config.json（Linux: ~/.config/kmm/，Windows: %APPDATA%/kmm/，macOS: ~/Library/Preferences/kmm/）。

如果要作为普通用户使用这个项目，请前往release页面，下载符合自己系统平台的分发文件，遵守指引安装；

待程序运行之后，请打开浏览器在KMM面板进行操作：

1. 在“数据来源”点击“扫描Steam库”等待其完成，这一步是为了创建游戏-MOD数据库；
2. 在“设置面板”的“规则来源”下方，点击“➕ 添加来源”创建一个新的空行，将Modder交给你的kmmrule文件的路径填写在空行中，点击“保存”；
3. 务必点击下方的“保存设置”按钮，对设定进行保存；
4. 进入“工作区”页面，点击右上方的“新建工作区”，输入必要的信息来创建一个工作区，每个工作区各自保存了一种替换模式，尽可能为每类不同的任务创建不同的工作区；
5. 在面板中点击工作区条目的“进入”来进入一个工作区；
6. 在“发现的规则文件”勾选Modder提供给你的kmmrule文件前方的复选框，如果感兴趣可以点击右侧的“展开”以查看这个规则的详细信息；
7. 点击“进入计算准备”，系统会自动将你导航到“计算准备”页面；
8. 仅保留想要替换的库/游戏/MOD前方的复选框，之后点击“开始计算”或者“计算查看”；复选框用于确定实际影响的游戏/MOD，可见按钮仅仅用于调整视觉效果，不影响最终结果；
9. 自行点击或等待系统导航进入“森林可视”界面，可以放大映射图，检查这些映射是不是你所想要的；
10. 如果有必要，在“冲突裁决”页面进行手动裁决；
11. 进入“文件操作”页面，如果这是首次操作，必须先点击“备份”，如果心存疑虑，务必打开"dry run"开关进行模拟；"dry run"不会进行任何实际的文件操作；
12. “备份”完成后，可以点击“应用”进行文件替换，等待操作完成；
13. 如果您的游戏/MOD需要分时间使用多个不同的规则，那么下次请在“备份”前先点击“恢复”，然后再“备份”和“应用”；

注意事项

本项目采用“懒备份”和“蠢还原”两个原则进行文件管理，它不会也不应该推测当前目录中文件的来源，备份时永远假定当前状态是需要被记录的快照，还原时只对比外部文件与备份文件之间的相似度，因此：

• 仅在文件目录处于“被Steam验证后”的“原始状态”时，才使用“备份”功能；
• 若当前文件已经是“应用”之后的样子，务必在下一次切换规则前，使用“恢复”功能使目录恢复原状，才能开始下一次“备份”和“替换”作业；

本地文件的说明

默认情况下，项目各类文件的存储目录是：

用途	Linux	Windows	macOS
用户配置	~/.config/kmm/	%APPDATA%/kmm/	~/Library/Preferences/kmm/
默认数据库	~/.local/share/kmm/	%LOCALAPPDATA%/kmm/database/	~/Library/Application Support/kmm/
默认工作区	~/.cache/kmm/workspace/	%LOCALAPPDATA%/kmm/workspace/	%LOCALAPPDATA%/kmm/workspace/

这些值是硬编码的“默认值”，但目前也支持通过“设置面板”进行自定义；

作为Modder

如果想要快速上手，请参考description/kmm_rule_RWR-khn_CT-castears-z2414_Replace.json.example撰写自己的kmmrule规则文件；

如果有一定的软件开发基础，或者对产出有更高的要求，更加建议参考repo_spec/中的schema文件，或者具体的代码实现，撰写更加安全和灵活的kmmrule规则文件；

在分发Mod时，建议同时分发kmmrule文件和本项目的链接，指引用户通过kmmrule进行规则化的MOD安装；

作为开发者

欢迎为本项目贡献代码；

目前项目已经确定的未来方向是：

• 迁移到Tauri2，提供更加定制化的GUI方便使用；
• 完善“规则制定”页面，方便kmmrule文件的制定；
• 进行内部资源传递优化方案，初步便于readme和preview的展示，之后还可灵活应用于其它外部资源；
• 将项目脱离SteamWorks场景使用，用于其他游戏MOD文件的管理；
• 实现对任意类型目录任意文件的管理，或是应用于嵌入式设备中进行资源敏感场合的文件管理；
• 脱离“文件系统”场景，允许后端接驳Redis等广泛意义上的“资源provider”；

欢迎提出更多的想法，比如“我想用它管理Minecraft模组”，或者“我想用它管理我的本地音乐收藏”，或者“我有一个嵌入式设备中需要这样的管理器对规则集合进行管理”；

项目还在成长，接受各种想法；

Knighthana

2026/05/22