外部 API - DLC Manager

本页说明 DLC 管理器当前已实现的外部 API。

API 同时支持：

客户端
服务端

启用 API

在 config.dc 或 config-server.dc 中配置 [api]：

[api]
apiEnabled = true
apiPort = 10086
apiToken = "your_token_here"

字段说明：

apiEnabled：是否启用 API 服务
apiPort：API 端口，默认 10086
apiToken：鉴权用 Bearer Token

鉴权

所有接口都需要：

Authorization: Bearer <apiToken>

如果 apiToken 为空，所有请求都会被拒绝。

通用规则

基础路径：/api
返回格式：

成功：

{
  "ok": true,
  "data": {}
}

失败：

{
  "ok": false,
  "error": {
    "code": "not_found",
    "message": "Unknown API route."
  }
}

支持 OPTIONS 预检
已启用 CORS，Access-Control-Allow-Origin: *

基础接口

`GET /api/ping`

健康检查。

返回字段：

service
running
mode

`GET /api/version`

返回 DLC/info/version.dc 的当前版本信息。

返回字段：

base
dlc
rollback_from
changelog_shown
label

`GET /api/state`

返回 API 与运行时状态摘要。

返回字段：

serverRunning
dedicatedServer
totalItems
enabledItems
counts

`GET /api/dlc/list`

返回按类型分组的 DLC 列表。

每个条目可能包含：

id
identifier
name
type
enabled
baselineEnabled
pending
hidden
configType
alarm
allowEnableByAll
appliedTarget
sourcePath
sourcePaths
displayNames
tips
dependencies
conflicts

`GET /api/dlc/pending`

返回当前待应用的 DLC 改动。

返回字段：

count
items
- id
- identifier
- name
- type
- enabled
- baselineEnabled
- pending

DLC 根目录 / 配置文件接口

`GET /api/dlc/root/list`

列出 DLC 根目录下可编辑的 .dc 文件。

当前可访问范围限制为：

<DLC>/info/**/*.dc
<DLC>/remote/**/*.dc
<DLC>/required/**/*.dc
<DLC>/preset/**/*.dc
<DLC>/update/**/*.dc
<DLC>/notice.dc

返回字段：

rootCount
roots
- rootIndex
- rootPath
- files
  - name
  - path
  - type
  - supported

`POST /api/dc/detect-type`

根据路径/文件名/内容识别配置类型。

请求体：

{
  "name": "example.dc",
  "path": "remote/example.dc",
  "content": "..."
}

返回字段：

type
supported

`POST /api/dc/validate`

校验 dc 配置内容。

请求体：

{
  "type": "remote",
  "content": "..."
}

返回字段：

type
supported
valid
issues

Issue 字段：

severity
source
field
message

`POST /api/dc/read`

从 DLC 工作区读取指定 dc 文件。

请求体：

{
  "path": "remote/example.dc",
  "rootIndex": 0
}

返回字段：

name
path
rootIndex
type
supported
content

`POST /api/dc/write`

向 DLC 工作区写入 dc 文件。

请求体：

{
  "path": "remote/example.dc",
  "rootIndex": 0,
  "type": "remote",
  "content": "..."
}

说明：

对当前支持的配置类型，写入前会先尝试解析。
工作区之外的路径会被拒绝。

返回字段：

name
path
rootIndex
type
supported
written

`POST /api/notice/content`

请求体：

{
  "url": "https://example.com/notice.md"
}

返回字段：

url
content

文件接口

`POST /api/file/add`

请求体：

{
  "path": "mods/example.jar",
  "content": "..."
}

或：

{
  "path": "config/example.txt",
  "contentBase64": "SGVsbG8="
}

或：

{
  "path": "mods/example.jar",
  "source": "downloads/example.jar"
}

创建目录：

{
  "path": "tmp/example",
  "directory": true
}

返回字段：

path
created
directory

`POST /api/file/del`

请求体：

{
  "path": "mods/example.jar"
}

返回字段：

path
deleted

`POST /api/file/mv`

请求体：

{
  "from": "mods/example.jar",
  "to": "mods/example-disabled.jar"
}

返回字段：

from
to
moved

`POST /api/file/rename`

请求体：

{
  "path": "mods/example.jar",
  "name": "example-disabled.jar"
}

返回字段：

from
to
renamed

`POST /api/file/upload`

向游戏工作区内目标路径上传原始二进制文件内容。

参数：

path：上传后的目标保存路径，位于游戏目录内，例如 mods/example.jar 或 config/example.txt

请求体：

原始二进制 body

支持的目标路径来源：

查询参数 path
请求头 X-Dlc-Path

返回字段：

path
uploaded
size

DLC 应用接口

`POST /api/dlc/enable`

请求体：

{
  "id": "mod:...|a.jar"
}

或：

{
  "ids": ["mod:...|a.jar", "unknown:...|b.zip"]
}

也支持直接传 identifier：

{
  "identifier": "example_mod"
}

{
  "identifiers": ["example_mod", "example_pack"]
}

返回字段：

enabled
changes
linkedChanges
unknownIds
unknownIdentifiers

`POST /api/dlc/disable`

请求体：

{
  "id": "mod:...|a.jar"
}

或：

{
  "ids": ["mod:...|a.jar", "unknown:...|b.zip"]
}

也支持直接传 identifier：

{
  "identifier": "example_mod"
}

{
  "identifiers": ["example_mod", "example_pack"]
}

返回字段：

enabled
changes
linkedChanges
unknownIds
unknownIdentifiers

`POST /api/dlc/apply`

只应用当前已经处于待应用状态的 DLC 改动。

请求体：

{
  "mode": "restart"
}

支持的 mode：

restart
reload

返回字段：

mode
changedCount
requiresRestart
hotReloaded
appliedChanges
messages

Remote 接口

`GET /api/remote/list`

返回当前缺失的 remote 条目。

可选请求头：

X-Dlc-Lang: zh_cn

`POST /api/remote/download`

立即下载当前所有缺失的 remote 条目。

返回字段：

success
downloaded
error

`POST /api/remote/download/start`

启动指定 key 的 remote 下载任务。

请求体：

{
  "keys": ["remote:key1", "remote:key2"],
  "lang": "zh_cn"
}

返回字段：

status

`GET /api/remote/download/status`

返回当前 remote 下载任务状态。

可选请求头：

X-Dlc-Lang: zh_cn

Required 接口

`GET /api/required/list`

返回 required 资源条目列表。

可选请求头：

X-Dlc-Lang: zh_cn

`POST /api/required/download/start`

启动指定 id 的 required 下载任务。

请求体：

{
  "ids": ["id_a", "id_b"],
  "lang": "zh_cn"
}

返回字段：

status

`GET /api/required/download/status`

返回当前 required 下载任务状态。

可选请求头：

X-Dlc-Lang: zh_cn

`POST /api/required/download/cancel`

取消当前 required 下载任务。

返回字段：

canceled

`POST /api/required/uninstall`

卸载指定 required 资源。

请求体：

{
  "ids": ["id_a", "id_b"]
}

返回字段：

removed

`POST /api/required/apply`

按 id 应用指定 required 资源。

请求体：

{
  "ids": ["id_a", "id_b"]
}

返回字段：

applied

Update 接口

`GET /api/update/state`

返回当前更新状态与回滚历史。

返回字段：

rollbackFrom
rolledBack
history

`GET /api/update/list`

返回当前可应用的更新包列表。

返回字段：

hasUpdates
updates

每个更新条目可能包含：

name
platform
base
base_new
dlc
dlc_new
hidden
changelog

`POST /api/update/apply`

应用更新。

若不传版本对，则默认应用当前检测到的整条更新链。

请求体：

{
  "baseOld": "1.0.0",
  "dlcOld": "1.0.0",
  "baseNew": "1.0.1",
  "dlcNew": "1.0.2"
}

返回字段：

success
missing
message
missingPaths
addedRequired
addedRemote

`POST /api/update/rollback`

回滚到目标版本。

请求体：

{
  "target": "1.0.0+1.0.0"
}

返回字段：

success
message
version

`POST /api/update/import`

从游戏目录内已有 zip 导入更新包。

请求体：

{
  "path": "downloads/example-update.zip"
}

返回字段：

success
path

`POST /api/update/import-url`

从 URL 下载更新包后再导入。

请求体：

{
  "url": "https://example.com/update.zip",
  "fileName": "update.zip"
}

返回字段：

success
message
downloadedPath