Trident.Net

<div align="center"> <h1>Trident.Net</h1> <p><strong>声明式 Minecraft 实例工具：核心库、模组包管道和命令行产品。</strong></p> <p> <a href="https://dotnet.microsoft.com/"><img alt=".NET 10" src="https://img.shields.io/badge/.NET-10.0-512BD4?style=for-the-badge&logo=dotnet&logoColor=white"></a> <a href="https://www.nuget.org/packages/TridentCore.Cli"><img alt="NuGet TridentCore.Cli" src="https://img.shields.io/nuget/v/TridentCore.Cli?style=for-the-badge&logo=nuget&logoColor=white&label=TridentCore.Cli"></a> <a href="docs/CLI.md"><img alt="CLI Docs" src="https://img.shields.io/badge/docs-CLI-2563EB?style=for-the-badge"></a> <img alt="Minecraft" src="https://img.shields.io/badge/Minecraft-instance_toolkit-62B47A?style=for-the-badge"> </p> <p> <a href="README.zh.md">简体中文</a> · <a href="#trident-as-a-library">库</a> · <a href="#trident-as-a-cli">命令行工具</a> · <a href="#repository-layout">仓库布局</a> · <a href="#ai-disclosure">AI 披露</a> </p> </div> Trident.Net 是 Trident 的 .NET 实现：一个 Minecraft 实例、模组包、软件包仓库和账户的核心库集，以及基于相同核心功能的 `trident` 命令行工具。 Trident 保持实例声明式、可重建、可导入、可导出，并对自动化友好。库定义了模型和执行引擎；命令行工具将这些功能作为产品化的入口点，用于本地游戏、模组包维护和 CI/CD 发布。 ## 一个模型，两个入口 Trident 的核心对象是 `profile.json`。它描述了游戏版本、加载器、软件包、规则和运行时覆盖。在部署期间，核心解析配置文件为可启动的 `.minecraft` 目录。命令行工具提供了创建、导入、构建、运行、导出和管理软件包的命令。 ```text TridentCore.Abstractions -> 文件模型、仓库接口、跟踪器、账户接口 TridentCore.Core -> 实例管理、部署/运行引擎、导入/导出、远程仓库、身份验证服务 TridentCore.Pref -> Trident 软件包 URL 解析和格式化 TridentCore.Cli -> 最终用户 trident 命令 ├── Operations/ -> 共享业务逻辑（由 Commands 和 Tools 使用） ├── Commands/ -> Spectre.Console.Cli 命令入口点 + 丰富输出格式化 ├── Tools/ -> MCP 工具入口点 + JSON 序列化 ``` ## Trident 作为库 本节适用于将 Trident 嵌入到启动器、桌面应用程序、服务器工具或自动化系统的开发人员。 ### 数据布局 Trident 仅在选定的主目录下管理数据。默认情况下，通过从当前目录向上遍历并查找 `.trident` 来解析主目录；如果未找到，则 Trident 默认为 `~/.trident`。主机应用程序可以在第一次使用之前覆盖 `PathDef.Default` 或 `PathDef.HomeLocatorDefault`。 ```text .trident/ ├── cache/ │ ├── assets/ # Minecraft 资源索引/对象 │ ├── libraries/ # Minecraft 库 │ ├── packages/ # 仓库软件包文件和元数据 │ └── runtimes/ # Java 运行时 ├── instances/ │ └── {key}/ │ ├── profile.json # 声明式实例元数据 │ ├── data.lock.json # 部署锁定数据 │ ├── data.pack.json # 软件包数据 │ ├── build/ # 投影的 .minecraft 输出 │ ├── import/ # 导入层，通常来自模组包或可导出文件 │ ├── live/ # 导入内容的运行时突变层 │ └── persist/ # 用户持久化数据，例如存档、截图、options.txt └── .trident.cli/ ├── accounts.json # 命令行工具私有的账户配置 ├── repositories.json # 命令行工具私有的仓库配置 └── settings.json # 命令行工具全局启动默认值和其他配置 ``` ### 核心概念 - 配置文件：声明式实例入口点，包括名称、Minecraft 版本、加载器、软件包首选项、规则和运行时覆盖。 - 部署：结合配置文件、远程元数据、缓存文件和本地层到 `build/`，然后写入 `data.lock.json`。 - 层：`import/` 存储模组包或可导出文件，`live/` 存储导入内容的运行时突变，`persist/` 存储用户数据。 - 投影：部署增量地将虚拟文件结构投影到 `build/`，通常通过创建符号链接关系和删除过时关系。 - 仓库：软件包源的统一接口，例如 Modrinth 和 CurseForge；软件包身份使用 Trident 首选项。 - 跟踪器：部署、安装、更新和运行操作通过跟踪器为 UI 和命令行工具订阅者公开状态、阶段和进度。 ### 功能 - 创建、扫描、更新和删除已管理的实例。 - 部署 vanilla Minecraft、加载器、运行时、依赖项和构建工件。 - 使用离线账户、Microsoft 账户、内存/窗口选项、Java 主目录和快速连接设置运行实例。 - 导入和导出 `trident`、`modrinth` 和 `curseforge` 模组包格式。 - 查询实例内的软件包、版本、依赖项和反向依赖项。 - 通过 PrismLauncher 元数据解析 Forge、NeoForge、Fabric 和 Quilt 加载器。 ### 集成 核心主要通过依赖注入集成。`src/TridentCore.Cli/Startup.cs` 是最完整的宿主示例，展示了如何注册 HTTP 客户端、缓存、导入器、导出器、远程服务和核心管理器。 ```csharp services.AddMemoryCache(); services.AddDistributedMemoryCache(); services .AddTransient<IProfileImporter, TridentImporter>() .AddTransient<IProfileImporter, CurseForgeImporter>() .AddTransient<IProfileImporter, ModrinthImporter>() .AddTransient<IProfileExporter, TridentExporter>() .AddTransient<IProfileExporter, CurseForgeExporter>() .AddTransient<IProfileExporter, ModrinthExporter>() .AddLifetimeRuntime() .AddPrismLauncher() .AddMojangLauncher() .AddMicrosoft() .AddXboxLive() .AddMinecraft() .AddMclogs() .AddSingleton<ProfileManager>() .AddSingleton<RepositoryAgent>() .AddSingleton<ImporterAgent>() .AddSingleton<ExporterAgent>() .AddSingleton<InstanceManager>(); ``` 在您自己的应用程序中，请优先使用这些管理器而不是直接的文件操作：`ProfileManager` 管理配置文件生命周期，`InstanceManager` 部署和运行实例，`RepositoryAgent` 查询仓库，`ImporterAgent` 和 `ExporterAgent` 转换模组包。 ## Trident 作为命令行工具 本节适用于模组包作者、服务器管理员和希望从终端管理 Minecraft 实例的用户。 `trident` 是 Trident 的产品化命令行入口点。它可以从头创建实例、导入现有的模组包、搜索和安装软件包、构建可启动的目录、登录账户、运行游戏，并将相同的实例导出为多个模组包格式。 ### 用例 - 维护一个本地可重建的 Minecraft 实例。 - 在 Git 中保留核心模组包元数据，然后从命令中构建和导出发布版本。 - 在 CI 中生成 Trident、Modrinth 或 CurseForge 工件。 - 使用 JSON 输出链接脚本，例如通过将软件包搜索结果输送到安装命令。 ### 安装 作为 NuGet 全局工具安装命令行工具： ```sh dotnet tool install --global TridentCore.Cli ``` 安装后，使用 `trident` 命令调用工具： ```sh trident --help ``` 使用以下命令更新或卸载它： ```sh dotnet tool update --global TridentCore.Cli dotnet tool uninstall --global TridentCore.Cli ``` 以下示例假设 `trident` 已在 PATH 中。如果新安装的工具在当前 shell 中未找到，请验证 .NET 全局工具目录是否已添加到 PATH。 ### 快速入门 ```sh trident create --identity cherry_picks --name "Cherry Picks" --version 1.21.1 --loader net.neoforged:21.1.200 trident add --instance cherry_picks modrinth:aC3cM3Vq@9I21YYxf trident build --instance cherry_picks trident run --instance cherry_picks --username Steve trident instance export --instance cherry_picks --format modrinth --type online --author d3ara1n --output ./releases/cherry-picks.mrpack ``` ### 全局选项 全局选项在命令调度之前进行预处理，可以出现在命令行中的任何位置。 | 选项 | 用途 | | --- | --- | | `--home <path>` / `--home=<path>` | 设置 Trident 主目录并覆盖自动 `.trident` 发现。 | | `--json` | 强制结构化 JSON 输出。 | | `--no-interactive` | 禁用提示、旋转器和进度 UI；破坏性命令也需要 `--yes`。 | | `--verbose` | 启用信息级日志。 | | `--debug` | 启用调试日志和完整异常；还启用详细输出。 | | `--mcp` | 启动 Trident 作为 MCP（模型上下文协议）服务器，覆盖 stdio。隐含 `--json` 和 `--no-interactive`。 | 当 stdout 被重定向时，命令行工具自动更喜欢 JSON 输出，用于管道和脚本场景。 ### 命令概述 | 场景 | 命令 | | --- | --- | | 实例 | `trident instance create/list/inspect/build/import/export/unlock/reset/delete/run` | | 快捷方式 | `trident create/import/build/run/list/inspect` | | 加载器 | `trident loader list/get/set`，`trident loader version list` | | 软件包 | `trident package list/search/add/inspect/enable/disable` | | 软件包关系 | `trident package dependency list`，`trident package dependent list` | | 软件包版本 | `trident package version list/set` | | 软件包快捷方式 | `trident search`，`trident add` | | 配置 | `trident config list/get/set/unset` | | 账户 | `trident account list/add/remove` | | 仓库 | `trident repository list/status/add/remove` | 需要实例上下文的命令按以下顺序解析它：`--instance <key>`，`--profile <path>`，然后是当前目录或其父目录中的托管 `profile.json`。常见的短选项包括 `-I|--instance`、`-R|--repository`、`-v|--version`、`-n|--name`、`-i|--id`、`-l|--loader`、`-y|--yes`、`-A|--account` 和 `-u|--username`。 ### 工作流示例 创建和构建实例： ```sh trident create --identity vanilla --name "Vanilla 1.21.1" --version 1.21.1 trident build --instance vanilla --full-check ``` 导入、运行和重置模组包： ```sh trident import --identity imported_pack --name "Imported Pack" ./modpack.zip trident config set --name java.max_memory --value 8192 trident config set --instance imported_pack --name behavior.command.wrapper --value "prime-run {command}" --type string trident run --instance imported_pack --username Steve --max-memory 6144 trident instance reset --instance imported_pack --yes ``` `trident config` 没有实例管理 CLI 全局默认值在 `<trident-home>/.trident.cli/settings.json`；`--instance <key>` 或 `--profile <path>` 管理该实例的 `profile.json` 覆盖。启动选项使用 `命令行选项 > 实例覆盖 > CLI 全局设置 > 内置默认值`。 搜索、安装和切换软件包版本： ```sh trident package search --repository modrinth --kind mod --version 1.21.1 --loader net.neoforged "Mouse Tweaks" trident package add --instance cherry_picks modrinth:aC3cM3Vq@9I21YYxf trident package version list --version 1.21.1 --loader net.neoforged modrinth:aC3cM3Vq trident package version set --instance cherry_picks modrinth:aC3cM3Vq@9I21YYxf ``` 将搜索结果输送到安装命令： ```sh trident --json package search --repository modrinth --kind mod "Mouse Tweaks" \ | trident --json --no-interactive package add --instance cherry_picks ``` 账户和仓库： ```sh trident account add --type offline --username Steve trident account add --type microsoft trident repository add --label modrinth-cn --driver modrinth --endpoint https://api.modrinth.com --user-agent "TridentCli" trident repository status --label modrinth-cn ``` ### MCP 服务器 Trident 可以作为 MCP（模型上下文协议）服务器，将其功能作为工具暴露给 AI 代理和 MCP 客户端： ```sh trident --mcp ``` 服务器通过 stdio 通信。在 MCP 客户端（例如 Claude Desktop、opencode）中配置： ```json { "mcpServers": { "trident": { "command": "trident", "args": ["--mcp"] } } } ``` 可用工具： | 工具 | 描述 | | --- | --- | | `List` (InstanceTools) | 列出所有 Trident 实例。 | | `Inspect` (InstanceTools) | 检查实例并预览软件包。 | | `List` (PackageTools) | 列出实例中安装的软件包。 | | `Search` (PackageTools) | 在远程仓库或实例内搜索软件包。 | | `Add` (PackageTools) | 通过 Pref 将软件包添加到实例中。 | | `Inspect` (PackageTools) | 通过 Pref 检查软件包。 | | `SetEnabled` (PackageTools) | 启用或禁用已安装的软件包。 | | `Get` / `Set` / `Unset` / `List` (ConfigTools) | 管理配置值。 | | `List` / `Status` (RepositoryTools) | 列出仓库并检查其状态。 | | `List` (AccountTools) | 列出已注册的账户。 | | `List` / `VersionList` (LoaderTools) | 列出支持的加载器并查询版本。 | 所有工具都返回 JSON。 `--home` 选项在 MCP 模式下也受尊重。 ### CI/CD 模组包发布 Trident CLI 可以将同一个实例导出为 GitHub Actions 中的多个发布格式。以下示例假设存储库包含由 CLI 管理的 `.trident` 主目录，或者工作流通过 `--home` 提供一个。 ```yaml name: Build and Publish Modpack on: push: tags: - v* jobs: build: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Install CLI run: dotnet tool install --global TridentCore.Cli - name: Export packs run: | trident instance export --format trident --type online --author d3ara1n --output Releases/trident.zip trident instance export --format curseforge --type online --author d3ara1n --output Releases/curseforge.zip trident instance export --format modrinth --type online --author d3ara1n --output Releases/modrinth.mrpack - name: Create Release uses: softprops/action-gh-release@v2 with: name: ${{ github.ref_name }} tag_name: ${{ github.ref_name }} files: Releases/* ``` ### 输出和限制 - 人类可读的输出使用 Spectre Console 表格、面板、状态消息和进度反馈。 - `--json` 或 stdout 重定向发出结构化 JSON；Microsoft 设备代码登录提示仍然写入 stderr。 - CLI 账户和仓库机密存储在 `<trident-home>/.trident.cli/*.json`；当前实现不使用系统密钥链加密它们。 - `package dependent list` 在实例内扫描本地反向依赖项；它不是针对远程仓库的全局反向依赖项查询。 - 参见 [`docs/CLI.md`](docs/CLI.md) 以获取更多 CLI 详细信息和验证说明。 ## 仓库布局 | 路径 | 描述 | | --- | --- | | `src/TridentCore.Abstractions/` | 共享模型、接口和实用程序。 | | `src/TridentCore.Core/` | 核心业务逻辑、部署/运行引擎、导入/导出和远程服务。 | | `src/TridentCore.Pref/` | Trident 软件包引用解析和格式化。 | | `src/TridentCore.Cli/` | `trident` 命令行产品（CLI + MCP 服务器）。 | | `docs/CLI.md` | 详细的 CLI 参考和验证说明。 | ## 开发 ```sh dotnet restore Trident.slnx dotnet build Trident.slnx dotnet pack src/TridentCore.Cli/TridentCore.Cli.csproj --configuration Release ``` ## AI 披露 | 项目 | AI 披露 | | --- | --- | | `TridentCore.Abstractions` | 人工编写 | | `TridentCore.Core` | 人工编写 | | `TridentCore.Pref` | 人工编写 | | `TridentCore.Cli` | Vibe-coded (GPT-5.5) | --- <div align="center" <strong>Trident.Net</strong> 保持 Minecraft 实例声明式、可重建并对自动化友好。 <br> 库优先。CLI 在 NuGet 上打包。包含模组包工作流。 </div>