ModReleaser/docs/index.md

Mod Releaser

一个基于 Web 界面的本地工具，用于通过 API 向 Modrinth 和 CurseForge 一键发布 mod 新版本。

技术栈

• 框架：Next.js（前后端不分离，WebUI 作为本地界面）
• UI 库：Ant Design
• 图标库：@ant-design/icons
• 通信层：tRPC（避免手写 API Route，除了 [trpc]/route.ts 一个入口文件）
• 工具库：use-debounce（防抖）
• Markdown 编辑器：@uiw/react-md-editor（风格需调整为与 Ant Design 统一）
• 校验库：Zod（运行时校验 config 文件 + API 响应）
• 测试框架：Vitest
• 平台 API：Modrinth API、CurseForge API

项目结构

/
├── secrets.json              # API 密钥（curseforge / modrinth）
├── configs/
│   └── {config_name}.json   # 各 mod 的配置
├── public/                    # 静态资源（图标、图片等）
├── src/
│   ├── app/                   # Next.js App Router（页面、布局、tRPC Route Handler）
│   ├── components/            # 可复用 UI 组件
│   ├── lib/                   # 纯后端逻辑，无 React 依赖
│   ├── services/              # 业务编排层（Server Actions + tRPC Router）
│   └── types/                 # TypeScript 类型定义
├── docs/                      # 本文档
├── package.json
└── ...

开发规范

前后端通信

日常功能使用 Next.js Server Actions 或直接在 Server Component 中调用后端函数，不创建 API Route。前端通过 "use server" 指令的函数或 Server Component 的 async 逻辑直接调用 src/lib/ 中的后端代码，避免前后端分离的冗余 API 层。

仅发布功能使用 tRPC（需 subscription 推送实时进度），在 src/app/api/publish/[trpc]/route.ts 中定义唯一的 HTTP 入口，前端通过 tRPC Client 调用：

• 变更：trpc.publish.useMutation()
• 订阅：trpc.progress.useSubscription(...)

src/ 目录说明

目录	职责
app/	Next.js App Router 页面与布局，以及唯一的 tRPC Route Handler
components/	可复用的 Ant Design 组件
lib/	纯后端逻辑（平台 API 请求、模板解析、工具函数），无 React 依赖
services/	业务编排层，注入全局 client 单例，通过 Server Actions 暴露给前端或 tRPC Router 调用
types/	TypeScript 类型/接口定义，使用 Zod schema 统一校验并导出类型

代码质量

• 每个文件行数不宜过多，单一职责，低耦合高内聚
• 尽可能减少技术债，写出可维护性高的代码
• 组件拆分粒度合理，逻辑与 UI 分离

类型定义（src/types/）

src/types/
├── config.ts            # config.json + secrets.json 的 Zod schema 与类型
├── modrinth/            # Modrinth API 请求/响应的 Zod schema 与类型
│   └── ...
├── curseforge/          # CurseForge API 请求/响应的 Zod schema 与类型
│   └── ...
└── index.ts             # 统一导出

所有外部数据（配置文件、API 请求体、API 响应体）统一用 Zod schema 校验，同时导出 TypeScript 类型。

文档目录

• frontend.md — 前端页面与组件（WebUI）
• modrinth/ — Modrinth API 参考
• curseforge/ — CurseForge API 参考
• workflow.md — 整体发布流程、状态管理、错误处理

参考文档

编写代码时，应查阅框架或组件库文档，通过 fetch 工具按以下体系获取：

Modrinth API

参考 docs/modrinth/ 目录（忽略 openapi.yml）：

文件	说明
upload.md	新建版本 API（POST /version）
edit.md	修改版本 API（PATCH /version/{id}）
get.md	获取版本信息 API（列出项目版本、获取单个版本等）
get-meta.md	元数据查询 API（加载器列表、游戏版本列表等）

CurseForge API

参考 docs/curseforge/ 目录：

文件	说明
upload.md	上传文件 API（含 Game Version Types / Game Versions 查询）
get.md	获取文件列表 API（GET /mods/{modId}/files）
get-meta.md	元数据查询 API（获取 Minecraft 版本列表等）

前端框架与组件库

Next.js

• nextjs.org/docs/llms.txt — 目录索引（带描述）
• 每页 .md — 逐页获取正文

Ant Design

• ant.design/llms.txt — 目录索引（纯链接）
• ant.design/design.md — 设计语言上下文
• 每页 .md — 逐页获取正文
• 每组件 semantic.md — 单个组件语义结构

use-debounce

• https://www.npmjs.com/package/use-debounce — npm 页面
• https://raw.githubusercontent.com/xnimorz/use-debounce/refs/heads/master/README.md — README 原文

tRPC

• https://trpc.io/llms.txt — 目录索引（带描述）
• 每页逐页获取正文

Zod

• https://zod.dev/llms.txt — 目录索引（纯链接）
• https://raw.githubusercontent.com/colinhacks/zod/refs/heads/main/packages/zod/README.md — README 原文

Vitest

• https://vitest.dev/llms.txt — 目录索引

@uiw/react-md-editor

• https://github.com/uiwjs/react-md-editor/blob/master/core/README.md — README 原文