Metadata-Version: 2.4
Name: modmgr
Version: 0.0.2
Summary: File mapping and backup rule engine for workshop mods
Project-URL: Homepage, https://github.com/Knighthana/modmanager
Project-URL: Repository, https://github.com/Knighthana/modmanager
Project-URL: Issues, https://github.com/Knighthana/modmanager/issues
Keywords: mod,manager,game,backup
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8
License-File: LICENSE
Requires-Dist: vdf>=0.4.0
Requires-Dist: jsonschema>=3.2.0
Requires-Dist: gitignore-parser>=0.1.0
Provides-Extra: web
Requires-Dist: fastapi>=0.100; extra == "web"
Requires-Dist: uvicorn[standard]>=0.23; extra == "web"
Dynamic: license-file

---
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（开发者 / 尝鲜用户）

```bash
# 安装核心包
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面板](127.0.0.1:8000)进行操作：

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

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

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

Knighthana

2026/05/22
