l1n6yun / delta-force-api

v1.0.0 2026-09-17 10:04 UTC

Requires

• php: >=8.0
• guzzlehttp/guzzle: ^8.2

Requires (Dev)

• phpunit/phpunit: ^13.3

MIT

• l1n6yun

• api
• sdk
• game
• deltaforce
• delta-force

Published on Packagist.org on 2026-09-18 01:14 UTC

README

三角洲行动（Delta Force）API SDK。

特性

• 统一异常：接口返回业务错误（ret != 0）、网络异常、参数缺失均抛出 DeltaForceException，调用方 try/catch 即可。
• 方法成功返回纯数据数组，不返回响应对象。
• 覆盖全部模块：游戏数据、微信/QQ/QQ安全/先锋/Wegame 登录鉴权、Steam 封禁查询、抽奖工具。

安装

composer require l1n6yun/delta-force-api

或直接把 src/ 目录放入你的项目并配置 PSR-4 自动加载：

{
  "autoload": {
    "psr-4": { "L1n6yun\\DeltaForceApi\\": "src/" }
  }
}

要求 PHP >= 8.0，Guzzle ^8.2。

快速开始

require 'vendor/autoload.php';

use L1n6yun\DeltaForceApi\Exception\DeltaForceException;
use L1n6yun\DeltaForceApi\Game;

try {
    $game = new Game();
    $player = $game->player($openid, $accessToken);
    print_r($player);
} catch (DeltaForceException $e) {
    // 鉴权过期 / 接口报错 / 网络异常
    echo $e->getMessage();
    if ($e->getRetCode() !== null) {
        echo ' (ret=' . $e->getRetCode() . ')';
    }
}

模块与方法

Game（游戏数据，L1n6yun\DeltaForceApi\Game）

方法	参数	说明
record(string $openid, string $accessToken, string $accessType = 'qc')	accessType: qc/wx	玩家全部战绩（枪械 + 干员，自动翻页）
player(string $openid, string $accessToken, string $accessType = 'qc')	accessType: qc/wx	战绩概览 / 货币 / 门票
config()	—	游戏配置列表
items(?string $type, ?string $subType, ?string $itemId)	—	物品列表
price(string $openid, string $accessToken, $ids, int $recent = 0, string $accessType = 'qc')	$ids 可为字符串或数组；accessType: qc/wx	物品价格（可选近期价格）
assets(string $openid, string $accessToken, string $accessType = 'qc')	accessType: qc/wx	玩家资产
recent(string $openid, string $accessToken, int $type, string $accessType = 'qc')	accessType: qc/wx	近期对局详情
achievement(string $openid, string $accessToken, int $type, string $accessType = 'qc')	accessType: qc/wx	成就数据
password(string $openid, string $accessToken, string $accessType = 'qc')	accessType: qc/wx	干员密码屋
manufacture(string $openid, string $accessToken, int $type, string $accessType = 'qc')	accessType: qc/wx	制造数据
guns(?string $gunId = null)	—	枪械详情（含弹药/配件映射，无需登录）
bind(string $openid, string $accessToken, string $accessType = 'qc')	accessType: qc/wx	绑定游戏角色
firearmModList(int $page = 1, int $pageSize = 10)	—	枪械改装方案列表
recommendation(string $place = 'tech')	—	推荐点位/装备
quartermaster(string $openid, string $accessToken, string $type = 'secret', string $accessType = 'qc')	type: secret/market；accessType: qc/wx	军需官兑换数据

除标注「无需登录」的接口外，均需 openid + accessToken。所有登录类接口额外接受 $accessType（qc=QQ，默认值；wx=微信）；微信账号必须传 'wx'，否则 cookie 会被按 QQ 处理导致鉴权失败。

player() 的容错说明：返回值额外包含 errors 数组。核心数据（player/game）来自 iChartId=317814；coin/tickets/money 是补充数据，来自另一个 iChartId=319386 接口——若该上游服务不可用，对应字段置为 0 并把服务端原始原因（如 服务不可用~）写入 errors，不会中断已获取的核心数据。

$player = $game->player($openid, $accessToken, 'wx');

echo $player['player']['charac_name']; // 角色名
echo $player['game']['rankpoint'];     // 排位分

// 补充接口异常时不会抛异常，降级为 0 并记录原因
if ($player['errors']) {
    print_r($player['errors']); // ['coin' => '服务不可用~', ...]
}

⚠️ 已知上游状况：iChartId=319386（转运自 clash 的资产/货币接口）目前服务端整体返回 服务不可用~，因此 record() 会返回空数组、player() 的 coin/tickets/money 为 0。这是官方接口侧的临时故障，与 openid/accessToken 无关——可用同一凭据调用 player() 的 player/game 字段确认鉴权是否正常。

Wechat（微信登录，L1n6yun\DeltaForceApi\Wechat）

方法	参数	说明
login()	—	获取二维码 qrCode 与 uuid
status(string $uuid)	—	轮询扫码状态，返回 ['code'=>..., 'message'=>..., 'wx_code'=>?]（不抛异常；code=3 时携带 wx_code）
getAccessToken(string $code)	微信授权 code	换取 access_token / openid 等
updateAccessToken(string $cookie, string $openid, string $accessToken)	—	刷新 access_token

QQ（L1n6yun\DeltaForceApi\QQ）

登录链路：getQrSig() → getAction($token,$qrSig,$loginSig,$cookieJson) → getAccessToken($cookieJson) → updateAccessToken($cookie,$openid,$accessToken)。

• getQrSig()：返回 qrSig / image(base64) / token / loginSig / cookie。
• getAction(...)：返回状态数组，status=0 时携带 qq 与 cookie。
• getAccessToken($cookie)：$cookie 为扫码后保存的 cookie 数组（JSON 字符串或数组），返回 access_token / openid 等。
• updateAccessToken($cookie, $openid, $accessToken)：刷新 token。

QQSafe（L1n6yun\DeltaForceApi\QQSafe）

与 QQ 登录链路一致（使用 appid=101944512），额外提供：

• bannedList(string $openid, string $accessToken, string $code)：封禁/处罚列表。
• report(string $openid, string $accessToken, string $userId)：举报玩家。

Pioneer（L1n6yun\DeltaForceApi\Pioneer）

登录链路同 QQ（使用 appid=101477677），额外提供：

• getGameTestList(?string $key = null, string $type = 'pc')：先锋测试列表（pc / mobile），传入 key 会拉取条目详情。
• 如需走代理：new Pioneer(['proxy' => 'http://127.0.0.1:9001'])。

Wegame（L1n6yun\DeltaForceApi\Wegame）

• getQrSig() / getAction(...) / getAccessToken($cookie)：QQ 扫码登录，返回 tgp_id / tgp_ticket。
• login() / status($uuid) / getWechatAccessToken($code)：微信扫码登录。
• card(string $id, string $ticket)：卡牌查询 / 抽取。
• gift(string $id, string $ticket)：保险箱礼包查询 / 领取。

Steam（L1n6yun\DeltaForceApi\Steam）

• vacBans(string $token)：传入 steamLoginSecure Cookie 字符串，返回 VAC 封禁游戏名数组。

Tools（L1n6yun\DeltaForceApi\Tools）

• getItems(string $type = 'props', string $subType = 'collection')：获取物品池（同时缓存供抽奖使用）。
• drawByGridAndGrade(int $times = 1, int $candidateCount = 3)：基于格子数 + 品阶的分步抽奖算法，返回中奖物品数组。

运行测试

项目使用 PHPUnit 作为开发依赖：

composer install            # 生产部署请使用 composer install --no-dev
composer test               # 运行全部测试
composer test:unit          # 仅运行离线单元测试
composer test:integration   # 仅运行真实联网集成测试

测试分两层：

• tests/Unit：纯逻辑单测（哈希算法、毫秒时间戳、Cookie 构造/转换、异常对象），完全离线、结果确定。
• tests/Integration：真实调用线上接口、不使用 mock，只断言返回类型与键结构，不依赖具体数值，避免上游数据波动导致误报。

集成测试需要外网可用；涉及鉴权的用例通过环境变量提供凭据，未提供时自动跳过（不会失败）：

环境变量	用途
DF_OPENID	游戏/QQ 账号 openid
DF_ACCESS_TOKEN	对应 access_token
DF_ACCESSTYPE	qc（默认）或 wx
DF_STEAM_TOKEN	Steam steamLoginSecure Cookie

# Windows PowerShell
$env:DF_OPENID = 'your-openid'
$env:DF_ACCESS_TOKEN = 'your-token'
composer test:integration

# Linux / macOS
DF_OPENID=xxx DF_ACCESS_TOKEN=yyy composer test:integration

PHPUnit 为 require-dev 依赖（要求 PHP 8.2+）；生产环境执行 composer install --no-dev 不会安装测试相关包。

异常处理

所有在 status/轮询类方法（仅表示状态，非错误）之外的接口，在以下情况会抛出 DeltaForceException：

• 接口返回业务错误（IDE 接口 ret != 0、微信/QQ iRet != 0 等）；
• 网络故障、请求超时；
• 缺少必要参数（如 uuid、code、token）。

异常提供 getRetCode(): ?int，即接口返回的业务错误码（网络/参数错误为 null）：

use L1n6yun\DeltaForceApi\Exception\DeltaForceException;

try {
    // ...
} catch (DeltaForceException $e) {
    echo $e->getMessage();        // 错误信息
    $e->getRetCode();             // 业务错误码（可能为 null）
}

目录结构

src/
├── Client.php                  # SDK 基类：Guzzle 封装、统一请求与异常
├── Exception/
│   └── DeltaForceException.php # 统一异常
├── Support/
│   └── Utils.php               # qrToken / gtk / cookie 等工具函数
├── Config/
│   ├── ammo.php                 # 弹药口径配置
│   └── accessory.php            # 配件位名称映射
├── Game.php / Wechat.php / QQ.php / QQSafe.php
├── Pioneer.php / Wegame.php / Steam.php / Tools.php
└── ...
tests/
├── Unit/                       # 离线单元测试
├── Integration/                # 真实联网集成测试
└── Support/RequiresCredentials.php  # 环境变量凭据读取（缺失即跳过）
phpunit.xml                     # 测试套件配置