Koikatu 多实例管理工具（Windows x64 · 非官方社区工具）。
管理多个 Koikatu / KoikatuVR 实例：实例发现与启动、运行监控、角色卡与资源索引、插件/MOD/ReShade 管理、Studio 急救、实例数据共享、数据整理，以及可回滚的文件操作。所有写操作统一走「备份 + SHA-256 校验 + 可回滚」流程。
- 到 Releases 下载
KoikatuManager-<版本>-win-x64.zip。 - 解压到一个全新文件夹（自包含，无需单独安装 .NET）。
- 运行
KoikatuManager.exe。 - 首次运行：在「启动与健康」页选择或自动发现你的游戏根目录（包含
Koikatu_Data的目录）。 - 通过左侧导航进入各功能页。
运行数据默认写入
%LOCALAPPDATA%\KoikatuManager\Data，不污染游戏目录，也不写入发布目录。
左侧导航共 12 个功能页。通用安全机制：几乎所有写操作都会先生成 OperationPlan——对原文件做备份并记录 SHA-256，执行前需确认，失败或误操作可到「备份与回滚」页回滚。
- 选择游戏实例、启动程序（Studio / Koikatu / VR）、分辨率、窗口模式、画质、显示器。
- 「只读扫描」体检：发现问题后勾选可修复项，点「应用所选修复」（需确认、先备份），再「体检并启动所选程序」。
- 同一「实例+程序」防重复启动；本体与工作室可并行启动。
- 添加 / 自动发现实例时要求游戏未运行。
- 防止 Studio 卡死丢进度：危险载入前建立独立检查点，记录心跳与异常退出证据。
- 「受控启用 Autosave」「安装/更新急救桥接」「立即检查点」「我已检查并确认」。
- 启用 Autosave 或装桥接前必须先关闭实例；「立即检查点」不会覆盖原场景，主线程会短暂停顿。
- 「确认事故」只消除告警、不删除证据。
- 每 2 秒采样进程、场景、ReShade 预设与渲染日志；安装内置桥接后可查看游戏内对象/材质/纹理统计。
- “形体物理联动”同时显示 Soma Dynamics 与 MMD DynamicBone Stabilizer 的安装版本、 当前加载/MMD 活动、最近插件事件，并提示仍启用的 BreastPhysicsController、 BPC Auto Default 或 DisableHipDynamicBones。
- 操作：
托管 GC、卸载未使用资源、自动清理阈值（GB，1–512），可选「自动清理（超过阈值时）」。 - 「强制关闭并标记为主动退出」：本次不再记为非正常事故，但未保存内容会丢失。
- GC/卸载需桥接在线，在主线程执行会短暂卡顿；自动清理每 10 分钟最多一次。
- 检测当前实例的 BepInEx 环境，一键安装或修复（官方核心 + IPA 兼容层 + KK 专用 patcher）。
- 「重新检测」「打开套件目录」「安装 / 修复 BepInEx」。
- 安装前要求关闭该实例；不会删除现有插件/配置/翻译/MOD；被替换文件先备份，失败自动回滚。
- 五个页签：
预设与效果、截图与对照、配置诊断、Add-on 插件、AI 分析。 - 预设操作：「启用此预设」（只改 ReShade.ini 的 PresetPath，游戏运行时禁止）、「便携化路径」、「复制到其他实例」、「定位预设」。
- 截图：
分析所选截图、Before/After 对照、分析当前 Before / After。 - 诊断：
恢复安全启动（效果加载模式异常时）、下次加载全部效果。 - Add-on：
可恢复停用（隔离 + 回滚，不删配置，仅识别 .addon/.addon32/.addon64）。 - AI 分析只发送截图与脱敏配置摘要，不修改文件。
- 按文件夹树管理女性/男性角色卡与 Studio 场景，支持搜索（文件名或相对路径）、翻页（每页 100 条）、
包含子文件夹。 - 操作：「重命名」「移动所选 / 勾选项」「复制到另一实例」「可恢复隔离」「重复分析」（按需计算 SHA-256，同尺寸候选多时安全限量）。
- 所有改动不覆盖目标、可回滚；有勾选时批量作用于勾选项，否则作用于当前选中项。
- 「扫描本地插件」读取真实 BepInEx 元数据与依赖；支持按名称/GUID/文件/作用/路径/官方仓库查询、安全状态筛选、翻页（每页 200 条）。
- 更新流程：「联网读取历史版本」→「下载并预检」→「安装所选版本（自动备份）」；替换前需兼容性预检通过且实例必须已关闭。
- 其他：「一键标记 GUID 重复（保留最新）」「可恢复隔离所选 / 勾选项」「前往回滚上次更新」。
- 联网只访问内置 GitHub 官方白名单；原 DLL 先 SHA-256 备份，可回滚。
- 四个页签：
本地 MOD 索引、场景缺失依赖、人物卡 MOD 依赖、官方白名单联网。 - 先「扫描 MOD」/「刷新索引」建立索引；
一键标记 GUID 重复、隔离所选 / 勾选项（损坏 / 冲突）。 - 场景/人物卡依赖：分析缺失依赖 →「从另一实例复制此依赖」或「联网搜索此依赖」（至少输入 2 个字符）。
- 官方白名单：搜索官方发布 → 查看发布页 →「下载、校验并受控安装」；大型 Modpack 官方建议用 KKManager。
- 跨实例共享 UserData 目录，自动识别已有 Junction/符号链接。
- 勾选内置目录或添加自定义目录 →「同步已勾选目录」；「恢复管理器创建的链接」可逆。
- 自定义目录只允许 UserData 相对路径（不接受盘符、
..或外部位置）；同步前原目录先移入隔离备份。
- 查看历史运行记录（时间/实例/程序/状态/RunId）；
本地规则归并→查看脱敏预览。 - 「AI 分析」把报告中标明
canApply的动作生成可回滚修复计划；执行所选计划前会做实例边界校验、备份 + SHA-256。 - AI 仅上传脱敏 JSON 与归并摘要；每个实例最多保留最近 200 条 AI 分析报告。
- 对已应用的修复记录执行「校验并回滚」。
- 回滚前同时校验当前文件与备份的 SHA-256：发现后来改动或备份损坏时拒绝覆盖。
- 只显示已实际应用过操作（AppliedCount > 0）的记录；回滚完成即从可回滚列表移除。
- 在已配置实例之间：迁移 MMD 播放列表、链接材质包/Overlay、同步 Stiletto 高跟数据、清理 ReShade 重复效果。
- 四组「检查 + 应用」：每组必须先「检查」生成 inspection 才能应用。
- MMD 迁移会改写目标
mmddirector.ini默认列表；Stiletto 按源版本复制/覆盖；全部修改可回滚。
插件、ReShade、运行记录、Studio 事故四个页面集成了 AI 分析，左侧「AI 分析后端」面板可切换三种后端：
| 后端 | 说明 | 要求 |
|---|---|---|
| Codex 桌面版 | 临时会话 + 只读沙箱 | 已安装并登录 Codex 桌面版 |
| DeepSeek API | 官方 chat/completions，JSON 输出模式 |
填写 API Key（可选模型） |
| opencode CLI | 非交互 run + 结构化输出 | 已安装 opencode CLI 并登录模型提供方 |
- 所有后端只发送脱敏提示词，只读分析、不自动改文件。
- opencode CLI 安装：
npm install -g opencode-ai或scoop install opencode；模型可选填，格式provider/model（留空用默认）；opencode 会在本机保留会话记录。 - 找不到 CLI 时，状态栏会给出安装提示。
需要 .NET 8 SDK、Windows PowerShell 5.1，以及一个仅用于编译桥接 DLL 的本地 Koikatu/BepInEx 环境：
$env:KOIKATU_BUILD_GAME_ROOT = '<你的游戏根目录>'
powershell -NoProfile -ExecutionPolicy Bypass -File .\Build-KoikatuManager.ps1输出到 dist\：win-x64 自包含包 + .zip + .sha256 与 -source.zip 源码包。构建全程执行契约测试、PowerShell 后端测试与公开发布审计。
- 公开发行包不携带
Data、用户配置、报告、日志、备份、隔离文件或游戏资源。 - 程序默认把运行数据写到
%LOCALAPPDATA%\KoikatuManager\Data。 - AI 分析只发送用户确认过的脱敏材料；Codex 只读沙箱，opencode 自动拒绝工具请求。
- 联网只访问内置官方白名单。
本项目是非官方社区工具，与游戏官方及发行商无关，不包含 Koikatu、HF Patch、插件、MOD 或用户数据。相关仓库：Soma Dynamics、MMD DynamicBone Stabilizer。