CS2 Config Formatter

安全、可审计、默认只检查的 Counter-Strike 2 .cfg 格式化器

Windows 版下载 · 源码运行 · 使用示例 · CLI 参考 · 开发指南

Important

cfgfmt 默认是 check 模式：只报告哪些文件需要格式化，不会修改文件。只有显式传入 --write 才会写入。

cfgfmt 只处理 CS2 可执行控制台脚本 *.cfg。它提供项目定义的统一 Canonical 风格，以及尽量保留作者表达的 Minimal 模式。

• ✅ 保持顶层命令、注释区块和参数顺序
• ✅ 保持命令名、alias、按键名和参数大小写
• ✅ 安全处理 bind/alias 分号链、注释列和中英文 echo 表格
• ✅ 支持文件、多个路径和目录递归批处理
• ✅ 支持 UTF-8 BOM、LF/CRLF、原子写入和可选单份备份
• ❌ 不处理 .vcfg、VDF、KeyValues 或 gamemodes*.txt
• ❌ 不判断命令在当前 CS2 版本中是否有效

Note

Valve 没有发布正式的 CFG formatter 或 style specification。Canonical 是本项目的格式约定，不代表 Valve 官方规范。

目录

• 快速开始
  • Windows x64 单文件版
  • Python 源码运行
• 常用操作
• Canonical 与 Minimal
• CLI 参考
• 输出与退出码
• 安全模型与文件边界
• 常见问题
• 开发与发布
• 许可证

快速开始

Windows x64 单文件版（推荐）

Windows 单文件版是便携式控制台程序：不需要安装 Python，也不需要安装依赖。建议使用 PowerShell 运行，不要直接双击 exe。

1. 下载两个文件

也可以打开 Releases，从同一个版本下载：

• cfgfmt-windows-x64.exe
• SHA256SUMS

把两个文件放进同一个目录，例如 C:\Tools\cfgfmt。

2. 打开 PowerShell

在资源管理器中打开该目录，点击地址栏输入 powershell 并回车；或者先打开 PowerShell，再进入目录：

cd C:\Tools\cfgfmt

3. 校验 SHA-256

$Expected = ((Get-Content .\SHA256SUMS -Raw).Trim() -split '\s+')[0].ToLowerInvariant()
$Actual = (Get-FileHash .\cfgfmt-windows-x64.exe -Algorithm SHA256).Hash.ToLowerInvariant()

if ($Actual -ne $Expected) {
    throw "SHA-256 校验失败，请不要运行该文件。"
}

"SHA-256 校验通过: $Actual"

Warning

当前 exe 尚未代码签名，Windows 可能显示 SmartScreen 提示。只应运行从本仓库 Release 下载且 SHA-256 校验通过的文件；来源或哈希不一致时请立即删除。

4. 确认程序可运行

.\cfgfmt-windows-x64.exe --version
.\cfgfmt-windows-x64.exe --help

5. 第一次检查 CFG

.\cfgfmt-windows-x64.exe "C:\path\to\autoexec.cfg"
$LASTEXITCODE

如果文件需要格式化，程序会显示 待修改 并返回退出码 1。这表示 check 正常发现差异，不是程序崩溃，文件此时没有被修改。

先查看具体差异：

.\cfgfmt-windows-x64.exe "C:\path\to\autoexec.cfg" --diff

确认无误后原子写入，并保留一份 autoexec.cfg.bak：

.\cfgfmt-windows-x64.exe "C:\path\to\autoexec.cfg" --write --backup

再次检查应返回 0：

.\cfgfmt-windows-x64.exe "C:\path\to\autoexec.cfg"
$LASTEXITCODE

可选：把文件名缩短为 cfgfmt.exe

Rename-Item .\cfgfmt-windows-x64.exe cfgfmt.exe
.\cfgfmt.exe --version

README 后续示例仍使用发行包原始文件名，改名不会影响程序功能。

Python 源码运行

Windows、macOS 和 Linux 都可以使用 Python 3.11 或更高版本直接运行。运行时只使用 Python 标准库，uv 不是普通用户的前置条件。

git clone https://github.com/MikuHello/cs2-config-formatter.git
cd cs2-config-formatter

python -m cfgfmt --version
python -m cfgfmt ./autoexec.cfg

也可以安装当前源码以获得较短的 cfgfmt 命令：

python -m pip install .
cfgfmt --version
cfgfmt ./autoexec.cfg

常用操作

以下示例使用源码入口；Windows 单文件版只需把 python -m cfgfmt 替换为 .\cfgfmt-windows-x64.exe。

检查但不写入（默认）

python -m cfgfmt ./autoexec.cfg

查看 unified diff

python -m cfgfmt ./autoexec.cfg --diff

原子写入

python -m cfgfmt ./autoexec.cfg --write

写入并生成单份备份

python -m cfgfmt ./autoexec.cfg --write --backup

备份文件固定为 <原文件名>.bak，例如 autoexec.cfg.bak。只有内容确实发生变化时才会写入并创建备份。

递归处理目录

python -m cfgfmt ./cfg

目录会递归查找 *.cfg，但不会跟随目录符号链接。

同时处理多个路径

python -m cfgfmt ./autoexec.cfg ./practice.cfg ./cfg

重叠输入会合并去重，并按规范化路径稳定排序。

排除文件或目录

python -m cfgfmt ./cfg \
  --exclude "generated/**" \
  --exclude "private.cfg"

--exclude 可以重复使用。默认还会排除 .git、.venv、build、dist、常见缓存目录、node_modules 和备份文件。

使用 Minimal 模式

python -m cfgfmt ./autoexec.cfg --minimal --diff
python -m cfgfmt ./autoexec.cfg --minimal --write --backup

Caution

不建议对 Valve/Steam 管理的整个游戏配置目录递归执行 --write。请只传入自己维护的文件或独立目录，并先使用默认 check 或 --diff 审核结果。

Canonical 与 Minimal

行为	Canonical（默认）	Minimal（--minimal）
命令、参数、注释列	按逻辑区块对齐	保留原布局
已确认结构的引号	统一	不增删
行尾注释	统一为 // 正文 并对齐	不补空格、不对齐
echo 表格	整组确认后按中英文显示宽度对齐	展示文本不变
bind/alias 分号链	安全规范分号空白	安全规范分号空白
连续空行	最多两个	数量不变
换行	保留纯 LF/CRLF；混合时使用多数类型	每一行 LF/CRLF 原样保留
文件末尾换行	恰好一个	原样保留

Canonical 示例：

// 输入
sensitivity  1.25//Mouse Speed
bind "X" "slot10;buy molotov"
echo 名称|Value
echo 很长名称 | x

// 输出
sensitivity "1.25" // Mouse Speed
bind        "X"         "slot10; buy molotov"
echo 名称     | Value
echo 很长名称 | x

单行 echo、标题、ASCII Art 和无法确认的管道结构保持原样。超长 bind/alias 仍会执行安全格式化，但不会推高整个区块的列宽。

CLI 参考

cfgfmt PATH [PATH ...]

参数	作用
PATH...	一个或多个 .cfg 文件或目录；目录默认递归
--write	使用同目录临时文件原子写入
--diff	显示 unified diff，不写入
--minimal	使用 Minimal；默认是 Canonical
--backup	实际写入前生成单份 .bak；只能与 --write 同用
--exclude GLOB	排除匹配路径；可重复
--version	显示版本
--help	显示帮助

--write 与 --diff 互斥。没有发现任何 .cfg 时会给出明确提示并返回 0。

输出与退出码

状态	含义
正常	文件已经符合所选模式
待修改	check/diff 发现差异，但没有写入
已修改	--write 已成功写入
失败	参数、读取、解析、安全验证或写入失败

退出码	含义
0	全部符合规范，或 --write 成功完成
1	默认 check 或 --diff 发现需要格式化的文件
2	参数、发现、读取、UTF-8 解码、解析、安全验证或写入失败

批处理中，单个文件失败不会阻断其他文件；只要存在失败，最终退出码就是 2。失败文件整份保持不变，也不会生成备份。

安全模型与文件边界

• 只接受 UTF-8 与 UTF-8 BOM；原文件有 BOM 就保留，没有则不添加。
• 词法器区分引号、注释、顶层分号和命令 token。
• 遇到未闭合引号、不安全反斜杠/转义或无法稳定解析的结构时，整份文件失败。
• 格式化后会重新解析，并比较命令顺序、token 值、分号边界、注释正文、bind/alias 载荷和 echo 展示结构。
• --write 使用同目录临时文件与原子替换，只写入实际变化的文件，并尽可能保留权限和元数据。
• formatter 不访问网络，也不会自动寻找或修改 CS2 安装目录。

常见问题

为什么双击 exe 后窗口一闪而过？

这是控制台程序，不提供图形界面。请在 PowerShell 中进入 exe 所在目录，再用 .\cfgfmt-windows-x64.exe PATH 运行。

退出码 1 是失败吗？

不是。默认 check 和 --diff 在发现待格式化文件时返回 1，用于让 CI 或脚本识别差异。文件没有被修改。

为什么 Windows 显示 SmartScreen 提示？

当前 exe 尚未代码签名。请确认下载地址属于 github.com/MikuHello/cs2-config-formatter，并严格校验 SHA256SUMS。无法确认来源或哈希时不要运行。

如何升级 Windows 单文件版？

从 Latest Release 下载新的 exe 与 SHA256SUMS，重新校验后替换旧文件。程序不会自动更新。

可以格式化 .vcfg 或 gamemodes*.txt 吗？

不可以。本项目只接受可执行 .cfg，不会解析 .vcfg、VDF、KeyValues 或游戏模式配置。

为什么某个文件被整份拒绝？

安全策略是不猜测、不局部修复。错误信息会包含文件、行号和简洁原因；修正不安全结构后再运行即可。同一批次的其他文件仍会继续处理。

开发与发布

依赖由 uv.lock 锁定。开发质量门：

uv run --python 3.11 --frozen --extra dev pytest -q
uv run --python 3.11 --frozen --extra dev ruff check .
uv run --python 3.11 --frozen --extra dev mypy cfgfmt

• 普通 push 和 pull request：运行 pytest、Ruff、mypy。
• vX.Y.Z tag：校验版本、运行质量门、在 windows-latest 构建 x64 单文件、执行 smoke check、生成 SHA256SUMS，最后发布 GitHub Release。
• Windows x64 使用单文件 Release；其他平台使用 python -m cfgfmt。

详细架构、测试原则和发布流程见 DEV.md。

许可证

本项目使用 MIT License。