Skip to content
Back to search

mc-modpack-master

Minecraft 整合包诊断与治理:证据化审计模组冲突、材质链、动画栈与性能瓶颈

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/3579828593--mc-modpack-master/badge.svg)](/listings/3579828593--mc-modpack-master)

HTML

<a href="/listings/3579828593--mc-modpack-master"><img src="/api/listings/3579828593--mc-modpack-master/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 165 lines
  1. # mc-modpack-master
  2. **Minecraft 整合包诊断与治理** —— 只管「为什么不生效 / 为什么崩 / 为什么糊 / 为什么卡」,以及改之前怎么证明该改。
  3. 一个给 AI Agent 用的技能(Agent Skill)+ 一个专家包(Expert Package)。核心是一条纪律:
  4. **每条结论必须能指到具体文件、日志行或数字;指不出来就不说。**
  5. ```
  6. 定位实例 → 只读审计 → 症状归因 → 最小介入修复 → 实测验证 → 五段式结论
  7. ```
  8. ---
  9. ## 它解决什么
  10. | 现象 | 常见误判 | 本项目的做法 |
  11. |---|---|---|
  12. | 第一人称动作全没了 | 以为模组坏了 | 先查动画**资源包**是否启用——模组本体在 ≠ 动画数据在 |
  13. | 手持火把不照亮 | 以为配置写错 | 先查有没有动态光源模组——功能不存在,不是参数问题 |
  14. | 方块透明 / 紫黑 | 以为材质包太旧 | `blockstate → model → parent` 全链路解析,定位到具体缺失文件 |
  15. | 画面整体发糊 | 调画质参数 | 查非 2 次幂贴图导致的 mipmap 塌陷(48×48 是常见元凶) |
  16. | 升级模组后启动崩 | 以为版本号不对 | 下载候选 jar 读 `depends` 区间比对本地已装版本 |
  17. ## 它不做什么
  18. - 不写模组代码、不反编译、不改模组 jar
  19. - 不替用户决定存档取舍(删世界 / 回滚进度)
  20. - 不承诺"必然提升 N 帧",只给实测数字
  21. - **不做整合包制作与分发** —— 用 [packwiz](https://github.com/packwiz/packwiz)
  22. - **不做服务端搭建** —— 用 [aiden 的 minecraft-modpack-server](https://github.com/taracodlabs/aiden)
  23. - **不做模组开发** —— 用 [langyo/minecraft-mod-mcp](https://github.com/langyo/minecraft-mod-mcp)
  24. 详见 [`skill/mc-modpack-master/references/ecosystem.md`](skill/mc-modpack-master/references/ecosystem.md),
  25. 里面有每个外部方案的实测星数、最后推送日期与 HTTP 可达性。
  26. ---
  27. ## 快速开始
  28. 要求 **Python 3.9+**,零第三方依赖(仅标准库)。
  29. ```bash
  30. # 1. 验证判定规则正常
  31. python skill/mc-modpack-master/scripts/selftest.py
  32. # 2. 审计一个整合包实例(只读,不改任何游戏文件)
  33. python skill/mc-modpack-master/scripts/mc_audit.py --instance "<你的实例目录>" --html
  34. # 3. 升级前校验:这个模组的新版会不会把包搞崩
  35. python skill/mc-modpack-master/scripts/mc_version_check.py \
  36. --instance "<你的实例目录>" --mod <modrinth-slug>
  37. ```
  38. 输出分级结论(`critical` / `warn` / `info`)+ JSON/HTML 报告,写到 `<实例>/mc_audit/`。
  39. ### 作为 Agent Skill 安装
  40. 把 `skill/mc-modpack-master/` 整个目录放进你的技能目录,例如:
  41. - WorkBuddy / CodeBuddy:`~/.workbuddy/skills/mc-modpack-master/`
  42. - Claude Code:`~/.claude/skills/mc-modpack-master/`
  43. 重启会话后,技能描述会参与匹配;用户说「整合包崩了」「画面发糊」「动作不显示」时自动触发。
  44. ### 作为专家包安装
  45. `doubao/ 豆包 / 扣子交付包(人设 + 知识库 + 校验清单)
  46. ├── 01-人设提示词.md
  47. ├── 02-知识库/ 5 份可直接上传的文档
  48. ├── 03-示例对话.md
  49. ├── 04-工具包/scripts/ 给用户本地执行
  50. └── 05-验收清单.md
  51. expert/mc-modpack-expert/` 是 WorkBuddy 专家包格式(含 `plugin.json`、Agent MD、头像、随包技能)。
  52. ```bash
  53. # 放到专家市场目录后注册
  54. mkdir -p ~/.workbuddy/plugins/marketplaces/my-experts/plugins
  55. cp -r expert/mc-modpack-expert ~/.workbuddy/plugins/marketplaces/my-experts/plugins/
  56. python <expert-manager>/scripts/register_expert.py \
  57. ~/.workbuddy/plugins/marketplaces/my-experts/plugins/mc-modpack-expert
  58. ```
  59. ---
  60. ## 四层测试
  61. | 层 | 命令 | 判据 |
  62. |---|---|---|
  63. | 规则 | `python skill/mc-modpack-master/scripts/selftest.py` | 27 条固定用例(贴图尺寸 / 版本约束 / 版本比较 / 路径归一化)全过 |
  64. | 审计 | `mc_audit.py --instance …` | 对已知故障实例能复现同一结论,换实例不误报 |
  65. | 契约 | `python expert/mc-modpack-expert/tools/verify_capability.py expert/mc-modpack-expert` | 8 项(结构 / agents / skills / 预加载 / 注册 / 头像 / 脚本 / 占位符)全 PASS |
  66. | 端到端 | 改完重启进游戏 | F3 的 FPS / GPU% / ms tick 三项、逐帧差分对照区为 0、目标错误归零 |
  67. **为什么规则层必须存在**:所有审计结论都压在 `mip_safe` / `satisfies` / `cmp_ver` 这几个纯函数上。
  68. 写错一个,报告会整篇误报,而且"看起来很专业"。用固定用例钉死,改代码先跑它。
  69. ---
  70. ## 目录结构
  71. ```
  72. skill/mc-modpack-master/
  73. ├── SKILL.md 作业规程:铁律 / 流程 / 症状表 / 接入规范
  74. ├── references/
  75. │ ├── pitfalls.md 14 条实测故障判据(症状 / 判据 / 验证 / 修复)
  76. │ ├── decisions.md 路线取舍表(渲染栈 / 光影 / 光源 / 动画 / 材质 / 家具)
  77. │ └── ecosystem.md 外部方案实测与可信度分级
  78. └── scripts/
  79. ├── mc_audit.py 八类只读审计
  80. ├── mc_version_check.py 升级前置校验
  81. ├── mc_pack.py 材质链 / 非 2 次幂扫描 / 覆盖包构建
  82. ├── PotScale.java 贴图补 2 的幂
  83. └── selftest.py 规则断言
  84. expert/mc-modpack-expert/
  85. ├── .codebuddy-plugin/plugin.json
  86. ├── agents/mc-modpack-expert.md 人格 + 能力边界 + SOP + 自检清单
  87. ├── avatars/expert.jpg
  88. ├── skills/mc-modpack-master/ 与 skill/ 下的副本完全一致(CI 会校验)
  89. └── tools/verify_capability.py 8 项契约验收
  90. ```
  91. > 两份技能副本必须一致——`expert/` 要能独立分发,所以不能做成引用。CI 里有专门的 `diff` 任务。
  92. ---
  93. ## 审计覆盖的八类问题
  94. 1. 重复模组 id(同名 jar 会互相覆盖注册表)
  95. 2. 已知冲突组合(Voxy × Iris、Continuity × 1×1 贴图)
  96. 3. 材质包链:条目是否存在、`pack_format`、修复包是否置顶
  97. 4. 贴图 mipmap:区分「真异常」「合法动画条」「已被覆盖」
  98. 5. 动画栈:EMF / ETF / FreshAnimations 包 / Punchy 包启用状态
  99. 6. 资源链完整性:`blockstate → model → parent`(含原版 jar 索引)
  100. 7. 模型字段损坏:`faces` 缺 texture、`textures` 非对象
  101. 8. 配置越界(如 `simulationDistance` 写 3/4 会被静默忽略)与日志归因
  102. ---
  103. ## 已知限制
  104. | 项 | 现状 |
  105. |---|---|
  106. | Forge / NeoForge 深度依赖校验 | 未实现,仅 Fabric 完整 |
  107. | 服务端 / 多人同步问题 | 未覆盖 |
  108. | 存档损坏(region / NBT 级) | 未覆盖 |
  109. | 光影源码解析 | 仅读 `iris.properties` 开关 |
  110. | 运行时 profiler | 只能从日志迹象推断 |
  111. **待验证**:`mctools` 的检测项、HMCL / PrismLauncher 的冲突诊断能力、部分社区资料对
  112. Faster Random / Noisium 归档状态的描述。这些都没有一手证据,不要在 issue 里当作既定事实。
  113. ---
  114. ## 贡献
  115. 见 [CONTRIBUTING.md](CONTRIBUTING.md)。最重要的两条:
  116. - 新增判据必须有**可复现的验证命令**,没实测过的写「待验证」,不许混进已验证区。
  117. - 新增检查项必须补 `selftest.py` 用例,并在两个不同实例上各跑一次确认不误报。
  118. ## 许可
  119. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.