steam-base-command

v1.2.0

Published

8 days ago

Steam Base Command：统一的 sta CLI，覆盖 Steam 登录（OpenID / steamworks.js 静默）、用户资料、游戏与 Mod 详情、Workshop 搜索、新闻、价格（含 ITAD）、发现榜单、心愿单、特价、Workshop Mod 订阅与取消订阅、游戏安装/卸载/商店页与本机扫描。

Steam Base Command (`sta`)

一个用 Node.js 写的 Steam 一站式命令行工具，全部能力通过统一入口 sta 暴露，输出结构化 JSON，方便脚本 / Agent 消费。

覆盖能力：

认证与配置：.env 生成、Steam OpenID 登录、steamworks.js 静默登录
玩家数据：玩家资料 / 徽章 / 好友 / 成就 / 心愿单
游戏与 Mod 元数据：商店详情、Workshop Mod 详情、Workshop 搜索（QueryFiles）、新闻、发现榜单、特价、价格与历史
本地唤起与管理：安装 / 卸载游戏、打开商店页、通过 steamworks.js 订阅 / 取消订阅 Workshop Mod
本机扫描：已下载游戏、已下载 Workshop Mod、已订阅 Mod

Node.js 建议 >= 18。核心依赖：express、openid、steamworks.js。

目录结构

.
├── cli.js                       # sta 统一入口
├── auth/                        # OpenID 登录 & 静默登录 & .env 生成
│   ├── envsetting.js            #   生成/覆盖 .env
│   ├── index.js                 #   OpenID Express 服务器
│   ├── login.js                 #   一键登录（先写 .env，再登录，支持 --silent）
│   └── steam-id.json            #   登录成功后写入
│
├── userinfo/                    # 玩家资料采集（多 collector 并行）
├── gamedetail/                  # 商店详情（AppID / 游戏名）
├── moddetail/                   # Workshop Mod 详情（ModID）
├── modsearch/                   # Workshop 搜索（IPublishedFileService/QueryFiles）
├── gamenews/                    # 游戏新闻（AppID）
├── gameprice/                   # 价格 / ITAD 历史最低
├── wishlist/                    # 心愿单 + 当前价 + 史低
├── specialsgame/                # 特价游戏（翻页 / 拼接 / 指定数量）
├── gamediscovery/               # 发现榜单（4 分类 + 汇总入口）
│
├── gamemanager/                 # 游戏安装 / 卸载（Steam URI）
│   ├── install.js               #   steam://install/<appid>
│   └── uninstall.js             #   steam://uninstall/<appid>
├── gameadd/                     # 打开商店页（steam://store/<appid>）
│
├── modmanager/                  # Workshop Mod 订阅 / 取消订阅（steamworks.js）
│   ├── subscribe.js             #   订阅并触发下载（sta modinstall / sta modmanager）
│   └── unsubscribe.js           #   取消订阅（sta modunsub）
│
├── downloadgame/                # 扫描本机已下载游戏（steamapps/common）
├── downloadmods/                # 扫描本机已下载 Workshop Mod
│
├── skills/steam-base-command/   # Agent Skills 文档（SKILL.md + reference/）
├── package.json
└── README.md

快速开始

# 1) 安装依赖
npm install

# 2) 生成/覆盖 .env（可选，login 已内置该步骤）
sta envsetting

# 3a) 常规登录（打开浏览器 OpenID）
sta login

# 3b) 静默登录（不打开浏览器，直接从 Steam 客户端读取 SteamID）
sta login --silent

# 4) 玩家资料 / 商店详情 / Mod 详情 …
sta userinfo
sta gamedetail --appid=105600
sta moddetail  --modid=2619954303

# 5) 订阅并下载 Workshop Mod（自动触发下载，完成后进程退出）
sta modinstall --appid=1281930 --modid=2619954303

# 6) 取消订阅
sta modunsub   --appid=1281930 --modid=2619954303

命令总览

| 命令 | 作用 | 需要 .env | 需要 SteamID64 | | --- | --- | :---: | :---: | | sta envsetting | 生成/覆盖 .env | ❌ | ❌ | | sta login [--silent] | OpenID 登录，或静默登录写 auth/steam-id.json | ❌ | ❌ | | sta userinfo [list\|schema\|help] | 玩家资料采集 | ✅ STEAM_WEB_API_KEY | ✅ | | sta wishlist | 心愿单 + 当前价 + 史低 | ⚠️ ITAD 可选 | ✅ | | sta gamedetail | 商店详情（AppID / 游戏名） | ❌ | ❌ | | sta moddetail | Workshop Mod 详情 | ❌ | ❌ | | sta modsearch | Workshop 搜索（QueryFiles） | ⚠️ 可选（API Key 提升额度） | ❌ | | sta gamenews | 游戏新闻 | ❌ | ❌ | | sta gameprice | 价格 / 史低（ITAD） | ⚠️ ITAD 凭据 | ❌ | | sta specialsgame / sta sale | 特价游戏列表 | ❌ | ❌ | | sta gamediscovery [sub] | 发现榜单（4 分类） | ❌ | ❌ | | sta gameinstall | 唤起 Steam 安装（steam://install/） | ❌ | ❌ | | sta gameuninstall | 唤起 Steam 卸载（steam://uninstall/） | ❌ | ❌ | | sta gameadd | 打开商店页（steam://store/） | ❌ | ❌ | | sta modinstall / sta modmanager | 通过 steamworks.js 订阅并下载 Mod | ❌ | ⚠️ Steam 客户端在线 | | sta modunsub / sta modunsubscribe | 通过 steamworks.js 取消订阅 | ❌ | ⚠️ Steam 客户端在线 | | sta downloadgame | 扫描本机已下载游戏 | ❌ | ❌ | | sta downloadmods | 扫描本机已下载 Workshop Mod | ❌ | ❌ |

通用参数（大多数子命令支持）：--help、--schema、--no-save、--no-print、--compact、--quiet。

环境变量（`.env`）

项目启动时会自动加载根目录 .env（内建加载器，无第三方依赖）：

STEAM_WEB_API_KEY=你的Key

# 可选：ITAD（价格/史低）
ITAD_API_KEY=...
ITAD_CLIENT_ID=...
ITAD_CLIENT_SECRET=...

# 可选：覆盖默认端口（OpenID 登录用）
# PORT=4050
# 可选：部署到公网时使用真实域名
# HOST=https://your-domain.com
# 可选：跳过 auth 步骤，直接指定 SteamID64 让 userinfo/wishlist 使用
# STEAM_ID64=76561198000000000

sta login 会先执行 envsetting 再登录，一次搞定；也可通过 sta login --steam-web-api-key=... --itad-api-key=... 一步到位。

认证：`sta login`

两种模式

浏览器 OpenID 模式（默认）：启动本地 Express 服务、打开浏览器 → Steam 授权 → 拿到 SteamID64 写入 auth/steam-id.json，服务自动关闭。
静默模式（--silent）：不启动服务、不打开浏览器，直接通过 steamworks.js 读取当前 Steam 客户端登录账号的 SteamID64，并写入同一份文件。

CLI 参数

sta login [options]

  --silent                       静默登录（用 steamworks.js 读取当前 SteamID）
  --silent-appid=<id>            静默模式下 steamworks.init 使用的 appid（默认 730）
  --steam-web-api-key=<key>      透传到 envsetting，写入 .env
  --itad-api-key=<key>           透传到 envsetting
  --itad-client-id=<id>          透传到 envsetting
  --itad-client-secret=<secret>  透传到 envsetting
  -h, --help                     显示帮助

auth/steam-id.json 结构（两种模式一致）：

{
  "steamId64": "76561198000000000",
  "claimedId": "https://steamcommunity.com/openid/id/76561198000000000",
  "profileUrl": "https://steamcommunity.com/profiles/76561198000000000",
  "loggedAt": "2026-07-09T08:00:00.000Z"
}

静默模式前置条件

Steam 客户端已启动并已登录
--silent-appid 指向一个你拥有或曾运行过的 AppID（默认 730 = CS2）；若默认不稳定，可显式传入

玩家数据：`sta userinfo`

多个 collector 并行采集：summary / ownedGames / recentGames / level / badges / friends / achievements。

sta userinfo [list|schema|help] [options]

  --only=a,b        仅运行指定 collector
  --exclude=a,b     排除指定 collector
  --include-locked  成就同时列出未解锁项（默认开启）
  --only-unlocked   仅输出已解锁成就
  --no-save         不写入 output/*.json
  --no-print        不把 JSON 打印到 stdout
  --compact         紧凑 JSON
  --quiet           关闭 stderr 日志
  --schema          打印字段字典
  --list            列出全部 collector
  -h, --help        显示帮助

数据源速查：

| collector | 接口 | | --- | --- | | summary | ISteamUser/GetPlayerSummaries | | ownedGames | IPlayerService/GetOwnedGames | | recentGames | IPlayerService/GetRecentlyPlayedGames | | level | IPlayerService/GetSteamLevel | | badges | IPlayerService/GetBadges + 社区徽章页 | | friends | ISteamUser/GetFriendList (+ GetPlayerSummaries) | | achievements | GetPlayerAchievements + GetSchemaForGame + GetGlobalAchievementPercentagesForApp |

输出：userinfo/output/steam-userinfo-<collector>-<steamId64>.json（分文件落盘）。

achievements 默认对 最近游玩前 3 款 + 拥有时长前 3 款 采集（并集）。

商店与 Mod 元数据

`sta gamedetail` — 商店详情

sta gamedetail --appid=105600
sta gamedetail --appid=105600,730 --cc=US --lang=english
sta gamedetail --name=Terraria
sta gamedetail --appid=105600 --filters=basic,price_overview --compact --no-save

参数：--appid、--name、--cc（默认 CN）、--lang（默认 schinese）、--filters。落盘：gamedetail/output/steam-gamedetail-<appid>-<CC>-<lang>.json。

`sta moddetail` — Workshop Mod 详情

sta moddetail --modid=2619954303
sta moddetail --modid=2619954303,2669644269 --compact

接口：ISteamRemoteStorage/GetPublishedFileDetails/v1/。落盘：moddetail/output/steam-moddetail-<modid>.json。

`sta modsearch` — Workshop 搜索（QueryFiles）

sta modsearch --appid=1281930 --q="storage"
sta modsearch --appid=1281930 --tag=Building --exclude-tag=Cheat --numperpage=50
sta modsearch --appid=730 --sort=new --pages=3
sta modsearch --appid=431960 --sort=trend --days=7 --count=80
sta modsearch --appid=1281930 --q="storage" --ids-only --numperpage=100
sta modsearch --appid=1281930 --q="storage,warehouse,logistics" --concurrency=3
sta modsearch --appid=1281930 --q="storage" --q="warehouse" --q="logistics"

参数：--appid / --creator-appid / --q（可重复或逗号分隔，支持多查询词并发） / --concurrency / --tag / --exclude-tag / --match-all-tags / --sort=<trend|new|updated|vote|totalsubs|uniquesubs|text> 或 --query-type=<n> / --filetype / --language / --days / --numperpage（≤100） / --cursor / --pages / --count / --ids-only / --no-tags / --no-vote / --no-previews / --no-short-desc / --return-metadata / --return-details。

接口：IPublishedFileService/QueryFiles/v1/（匿名可用，.env 有 STEAM_WEB_API_KEY 时自动附带）。落盘：modsearch/output/steam-modsearch-<appid|any>-<slug|multi-N>-<queryType>.json。

`sta gamenews` — 游戏新闻

sta gamenews --appid=105600 --count=20
sta gamenews --appid=730   --limit=30

接口：ISteamNews/GetNewsForApp。落盘：gamenews/output/steam-gamenews-<appid>.json。

`sta gameprice` — 价格 / 历史最低（ITAD）

需要 .env 中的 ITAD_API_KEY 等 ITAD 凭据。

sta gameprice --appid=105600 --country=CN
sta gameprice --name="Cyberpunk 2077"

`sta wishlist` — 心愿单

sta wishlist                                     # 使用 auth/steam-id.json
sta wishlist --steamid=76561198000000000 --cc=US --lang=english
sta wishlist --no-itad --compact                 # 仅当前价，不查史低

`sta specialsgame` / `sta sale` — 特价列表

sta specialsgame --page=1 --cc=CN --lang=schinese
sta specialsgame --pages=3            # 连续 3 页
sta specialsgame --count=80           # 自动跨页凑够 80 条
sta specialsgame --tag=survival --hide-f2p

`sta gamediscovery [sub]` — 发现榜单

| 子命令 | 接口 | | --- | --- | | publicSpecials | /api/featuredcategories#specials | | publicTopSellers | /api/featuredcategories#top_sellers | | publicNewReleases | /api/featuredcategories#new_releases | | publicComingSoon | /api/featuredcategories#coming_soon |

sta gamediscovery                                       # 4 分类汇总（并行）
sta gamediscovery publicTopSellers --cc=US --lang=english
sta gamediscovery --only=publicSpecials,publicTopSellers

本地唤起：Steam URI

三个动作都跨平台（Windows / macOS）自动分支调用系统命令：

`sta gameinstall` / `sta gameuninstall` / `sta gameadd`

sta gameinstall   --appid=570
sta gameuninstall --appid=730 --dry-run
sta gameadd       --appid=570

install → steam://install/<appid>
uninstall → steam://uninstall/<appid>
gameadd → steam://store/<appid>

支持 --dry-run（只输出协议 URI，不真正唤起）。

Workshop Mod 订阅：`sta modinstall` / `sta modunsub`

与前几版不同，Mod 订阅 / 取消订阅通过 steamworks.js 直接与 Steam 客户端交互，不再打开浏览器。执行完成后进程会自动退出（watch 模式在下载完成时提前结束）。

订阅并下载

sta modinstall  --appid=1281930 --modid=2619954303
sta modmanager  --appid=1281930 --modid=2619954303              # 别名，等价
sta modinstall  --appid=1281930 --modid=A,B,C --watch           # 边跑边采样
sta modinstall  --appid=1281930 --modid=A --status-only         # 只查状态不订阅
sta modinstall  --appid=1281930 --modid=A --no-download         # 只订阅不触发下载

取消订阅

sta modunsub       --appid=1281930 --modid=2619954303
sta modunsubscribe --appid=1281930 --modid=A,B                  # 完整别名

关键参数

| 参数 | 说明 | | --- | --- | | --appid=<id> | 目标游戏 AppID（必填，需与 Mod 归属一致） | | --modid=<id[,id2...]> | 一个或多个 Workshop ModID（必填） | | --status-only | 不执行订阅/取消，仅采样当前状态 | | --download / --no-download | 订阅后是否触发下载（默认 --download） | | --high-priority | 下载走高优先级 | | --watch | 轮询采集下载状态，全部完成即提前退出 | | --watch-seconds=<n> | 轮询总时长秒（默认 15） | | --watch-interval-ms=<n> | 轮询间隔毫秒（默认 2000） |

报告字段（关键）

{
  "generatedAt": "2026-07-09T08:15:00.000Z",
  "appId": "1281930",
  "requestedCount": 1,
  "successCount": 1,
  "failedCount": 0,
  "mode": {
    "statusOnly": false,
    "download": true,
    "highPriority": false,
    "watch": true,
    "watchSeconds": 15,
    "watchIntervalMs": 2000
  },
  "items": [
    {
      "modId": "2619954303",
      "alreadySubscribed": false,
      "action": "subscribed",                    // subscribed / unsubscribed / status_only / noop_*
      "subscribeSuccess": true,                  // 订阅脚本字段
      "downloadTriggered": true,                 // 订阅脚本字段
      "status": {
        "state": { "value": 5, "flags": ["subscribed","installed"] },
        "installInfo": { "folder": "...", "sizeOnDisk": "12345", "timestamp": 1720000000 },
        "downloadInfo": { "current": "0", "total": "0", "progress": null }
      },
      "error": null,
      "hint": null                               // generic failure 时会给出可读提示
    }
  ],
  "watchStoppedReason": "all_items_settled",     // 或 "timeout"
  "watchSamples": [ /* ... */ ]
}

常见 generic failure 原因：--appid 与 Mod 实际归属 App 不一致；Mod 已被封禁 / 私有；Steam 客户端未启动或账号不一致。脚本会在此时自动填充 hint 字段辅助定位。

本机扫描

`sta downloadgame` — 已下载游戏

sta downloadgame
sta downloadgame --common="D:/SteamLibrary/steamapps/common"
sta downloadgame --library="D:/SteamLibrary,E:/SteamLibrary"

落盘：downloadgame/output/steam-downloaded-games.json。

`sta downloadmods` — 已下载 Workshop Mod

sta downloadmods
sta downloadmods --appid=431960,262060
sta downloadmods --workshop-content="D:/SteamLibrary/steamapps/workshop/content"

落盘：downloadmods/output/steam-downloaded-mods.json。

输出与失败约定

stdout：所有命令默认输出结构化 JSON（--no-print 关闭）
stderr：进度、日志与摘要（--quiet 关闭）
文件：需要落盘的命令写到该模块下的 output/ 目录（--no-save 关闭）
失败隔离：单条对象上出现 success: false + error，不影响其它条目
命令级致命错误（网络异常、参数缺失等）：非 0 退出码 + stderr 报错

常见问题（FAQ）

1. 成就返回 `Profile is not public` / HTTP 403

Steam 游戏详情 (Game details) 隐私和 个人资料公开 是两个开关，两个都要设为公开，且 "始终将游戏时间保持为私密"取消勾选。设置页：https://steamcommunity.com/my/edit/settings。改完等 3~15 分钟（API 缓存）。

2. 成就返回 `Requested app has no stats` / HTTP 400

游戏本身未接入 Steam 成就系统，属于数据源不存在，跳过即可。

3. `sta modinstall` 返回 `generic failure`

十有八九是 --appid 传错：ModID 与你传入的 AppID 不一致。脚本会在 hint 字段告诉你 Mod 实际归属的 consumerAppId。

4. `sta login --silent` 报错

请检查：

Steam 客户端是否启动并处于登录状态
--silent-appid 指向的 AppID 是否本机可初始化（默认 730；不稳定时改为你拥有的任一游戏 AppID）

5. `STEAM_WEB_API_KEY` 泄露

去 https://steamcommunity.com/dev/apikey 点 Revoke My Steam Web API Key → Register 新 Key → 粘回 .env。

分发与安装

# 全局安装（发布后）
npm i -g steam-base-command

# 验证
sta --help

如果使用 scope 包名：npm i -g @yourname/steam-base-command。

Agent Skills 索引

给 Agent 使用的结构化文档在 skills/steam-base-command/：

入口：skills/steam-base-command/SKILL.md
各命令的详细参数 / 字段字典 / 示例：skills/steam-base-command/reference/

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Steam Base Command (sta)

目录结构

快速开始

命令总览

环境变量（.env）

认证：sta login

两种模式

CLI 参数

静默模式前置条件

玩家数据：sta userinfo

商店与 Mod 元数据

sta gamedetail — 商店详情

sta moddetail — Workshop Mod 详情

sta modsearch — Workshop 搜索（QueryFiles）

sta gamenews — 游戏新闻

sta gameprice — 价格 / 历史最低（ITAD）

sta wishlist — 心愿单

sta specialsgame / sta sale — 特价列表

sta gamediscovery [sub] — 发现榜单