WorkshopOnAndroid

一个面向 Android 的 Steam 创意工坊模组下载器项目

支持浏览支持创意工坊的游戏、查看模组详情；公开条目可匿名下载，支持登录 Steam 账号。

核心特性 • 快速开始 • 构建说明 • 发布自动化 • 自动化调试 • 仓库结构 • 当前限制

Important

支持在设置页通过 Steam 协议登录账号，并把同一套账号同时用于工坊浏览和下载。公开条目仍可匿名下载；需要登录态的条目会在任务入队时冻结绑定当前账号，并在下载时携带对应的 Steam Cookie / CM 会话。当前仍不支持 Collection 下载和二维码登录。

核心特性

方向	说明
游戏发现	支持预置热门工坊游戏、搜索 Steam 游戏、或直接输入 AppID 加入本地游戏库。
工坊浏览	基于 Steam Community 页面抓取创意工坊列表，支持搜索、分页和模组详情查看。
调试自动化	提供基于 adb 的 Gradle 任务，可跳过 UI 直接触发下载并拉回日志。

Note

:steam-protocol 负责 Steam CM 连接、账号认证、内容服务器发现和 CDN 授权，:workshop-core 负责 manifest、chunk、校验、解压和最终文件组装。

快速开始

1. 准备环境

• JDK 17+，当前项目使用 JDK 21 构建
• Android Studio / Android SDK
• Android 12+ 设备
• 能访问 Steam Store、Steam Community 和 Steam Web API 的网络环境
• 如需自动化调试，请确保 adb 可用且设备已连接

2. 构建 Debug APK

.\gradlew.bat :app:assembleDebug

3. 安装到设备

.\gradlew.bat :app:installDebug

4. 应用内使用

1. 启动应用后进入游戏库页面。
2. 点击右上角 +，打开添加游戏页。
3. 通过热门游戏、关键字搜索或直接输入 AppID 把支持创意工坊的游戏加入库。
4. 进入游戏对应的创意工坊页，搜索并查看模组详情。
5. 点击模组卡片上的 下载，将任务加入下载中心。
6. 在下载中心查看状态、进度和日志，或执行暂停、继续、删除操作；已下载文件统一在模组库里管理。

5. 下载结果位置

• 应用私有缓存目录：/data/user/0/top.apricityx.workshop/files/workshop/<AppID>/<PublishedFileId>/
• 用户可访问导出目录：/sdcard/Download/workshop/<游戏名字>/<模组名字>/<版本>/

如果模组是单文件，并且 Steam 元数据里带有更可读的标题或文件名，导出阶段会优先使用它们生成文件名。相同版本会覆盖同版本目录，不同版本会在各自版本目录下共存。

构建说明

模块	职责
:app	Compose UI、页面流转、游戏库、本地设置、下载中心和文件导出
:workshop-core	创意工坊元数据解析、file_url 下载、UGC manifest/chunk 下载、校验和文件组装
:steam-protocol	Steam CM WebSocket 连接、账号认证、目录服务、内容服务器请求、manifest request code、CDN token 和 depot key 获取

构建目标：

• minSdk 31
• targetSdk 36
• compileSdk 36
• Java / Kotlin 字节码目标：17

运行时设置：

• 下载线程数可在应用设置页调整，范围 1..8
• 同时下载任务数可在应用设置页调整，范围 1..3
• 主题模式支持跟随系统、浅色和深色
• 可在应用设置页保存多个 Steam 账号，切换当前浏览账号，并把下载任务绑定到入队时的账号；下载时会按绑定账号携带 Steam 登录态

发布自动化

仓库已补充与参考项目一致的标签发布策略：

• .github/workflows/release.yml 会在推送 v* 标签时构建签名版 release APK
• 构建产物会先上传到 Actions artifact
• 如果当前引用是标签，工作流会同步创建或更新 GitHub Release
• 若存在 docs/release/note/v<version>.md，该文件会被用作 Release 正文

签名信息通过 GitHub Environment release-signing 注入，详细配置步骤见：

• docs/release-automation/README.md

本地准备 release note、打 tag 并推送，建议直接运行：

scripts\prepare-release.bat

自动化调试

仓库内置了面向真机调试和回归验证的 adb 自动化任务，适合跳过 UI 直接验证某个 AppID + PublishedFileId 的下载链路。

workshopDownloadAndPullLogs 会自动完成：

• 构建并安装最新 Debug APK
• 强制停止应用并清理目标条目的旧缓存
• 通过 adb 发送 top.apricityx.workshop.action.DOWNLOAD
• 等待下载成功、失败或超时
• 拉回 download.log、logcat.txt、metadata.json 和 result.txt

常用命令：

.\gradlew.bat :app:workshopStartDownload -PworkshopAppId=646570 -PpublishedFileId=3677098410 -PdeviceSerial=<adb-serial>
.\gradlew.bat :app:workshopPullLogs -PworkshopAppId=646570 -PpublishedFileId=3677098410 -PdeviceSerial=<adb-serial>
.\gradlew.bat :app:workshopDownloadAndPullLogs -PworkshopAppId=646570 -PpublishedFileId=3677098410 -PdeviceSerial=<adb-serial> -PdownloadTimeoutSeconds=180 --console=plain

可选参数：

• -PdeviceSerial=<adb-serial>
• -PdownloadTimeoutSeconds=<seconds>
• -PpollIntervalMillis=<milliseconds>
• -PlogsDir=<path>

默认日志导出目录：

build/workshop-adb/app-<AppID>-file-<PublishedFileId>-<timestamp>/

仓库结构

路径	用途
app/	Android 主应用、Compose 页面、下载中心、公共目录导出
workshop-core/	下载引擎、元数据解析、chunk 处理、校验与组装
steam-protocol/	Steam 协议访问、WebSocket 会话和内容服务器客户端
gradle/workshop-adb.gradle.kts	adb 调试自动化任务

当前限制

• 公开条目可匿名下载；登录后，下载任务会按入队时绑定的账号携带 Steam 登录态，请求需要认证的元数据、Steam CM 和 CDN 资源。实际能否下载仍取决于该账号对条目的可见性与 Steam 上游鉴权结果。
• 暂不支持 Collection。
• 工坊列表和详情依赖 Steam 页面结构与相关接口，若上游改版需要同步调整解析逻辑。
• 当网络无法稳定访问 Steam 时，游戏库、工坊列表和下载流程都可能失败或超时。