cwtools/cwtools-action

CWTools Action镜像说明

镜像概述

cwtools/cwtools-action是一个用于GitHub和GitLab CI/CD流程的Docker镜像，旨在对Paradox Development Studio游戏（如HOI4、***is等）的Mod代码（PDXScript）进行自动化分析。它能在构建过程中并行运行CWTools，检测代码中的错误、警告和建议，并在拉取请求（PR）中添加内联反馈，帮助开发者快速定位和修复问题。

核心功能

1. 代码分析: 检测Mod代码中的语法错误、逻辑问题及潜在风险；
2. PR内联反馈: 将检测结果直接添加到PR的"Files changed"标签页中，直观展示问题位置；
3. 多游戏支持: 兼容HOI4、***is、CK2、EU4等多款Paradox游戏；
4. 灵活配置: 支持自定义游戏类型、Mod路径、缓存文件、检查语言等参数；
5. 日志保存: 生成详细的分析日志（output.json），可通过artifact上传保存。

使用场景

• Paradox游戏Mod开发者在提交代码或创建PR时，自动进行代码质量检查；
• 团队协作中确保Mod代码符合规范，减少人工审查成本；
• 持续集成流程中集成代码检查，提升Mod开发效率和质量。

配置说明

以下是GitHub Actions中的配置示例及参数说明：

基础示例

在项目的.github/workflows目录下创建 workflow 文件（如cwtools-ci.yml）：

yml
name: CWTools CI
on: [pull_request, push]
jobs:
  cwtools_job:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v1
    - uses: cwtools/cwtools-action@v1.0.0
      with:
        game: hoi4
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

参数说明

game（必填）

指定目标游戏类型，支持的值：hoi4、ck2、eu4、ir、stellaris、vic2。 示例：

yml
with:
  game: stellaris

modPath（可选）

Mod文件夹在仓库根目录下的路径，默认值为空（即仓库根目录）。 示例：

yml
with:
  game: hoi4
  modPath: "my_mod_folder"

cache（可选）

缓存文件（.cwb.bz2）的路径，默认使用cwtools/cwtools-cache-files中的元数据缓存。 示例：

yml
with:
  game: hoi4
  cache: "cache/hoi4.cwb.bz2"

locLanguages（可选）

需要检查的本地化语言（空格分隔，小写），默认值为english。 示例：

yml
with:
  game: hoi4
  locLanguages: "english spanish russian"

vanillaMode（可选）

是否将项目视为 vanilla 游戏安装目录（不建议Mod开发者使用），默认值为False。 示例：

yml
with:
  game: hoi4
  vanillaMode: "1"

rules（可选）

指定规则仓库地址，默认使用https://github.com/cwtools/cwtools-$INPUT_GAME-config.git。 示例：

yml
with:
  game: hoi4
  rules: "https://github.com/Yard1/cwtools-hoi4-config.git"

rulesRef（可选）

规则仓库的分支或标签，默认值为master。 示例：

yml
with:
  game: hoi4
  rulesRef: "1.0.0"

changedFilesOnly（可选）

是否仅检查变更文件，默认值为True（设置为"0"则检查所有文件）。 示例：

yml
with:
  game: hoi4
  changedFilesOnly: "0"

suppressedOffenceCategories（可选）

抑制特定类别的错误/警告/通知（使用CWTools的 offence ID，如CW110）。 示例：

yml
with:
  game: hoi4
  suppressedOffenceCategories: '{"failure":["CW110", "CW210"], "warning":[], "notice":[]}'

CWToolsCLIVersion（可选）

指定CWTools.CLI的版本，默认使用最新稳定版。 示例：

yml
with:
  game: hoi4
  CWToolsCLIVersion: '0.0.7'

GitLab配置说明

由于GitLab限制，目前仅支持向master分支的合并请求提供反馈。需创建机器人账号并配置PAT：

1. 创建机器人账号并授予项目"Reporter"权限；
2. 生成具有"api" scope的PAT；
3. 在项目CI/CD变量中添加REVIEWDOG_GITLAB_API_TOKEN（值为PAT，设置为Masked）；
4. 在项目根目录创建.gitlab-ci.yml，内容参考GitLab_CWToolsCI.yml。

工作原理

该镜像基于CWTools（.NET库）和CWTools.CLI工具，通过以下方式实现代码分析：

1. 验证规则: 从指定仓库获取游戏对应的验证规则；
2. 缓存文件: 使用元数据缓存或完整缓存文件获取vanilla游戏的关键信息（如本地化、变量等）；
3. 自动化分析: 在CI流程中运行CWTools.CLI，生成分析结果并添加到PR中。

Credits

• 作者：Antoni Baum（Yard1）；
• 依赖工具：https://github.com/tboby/cwtools%EF%BC%9B
• 基于：https://github.com/gimenete/rubocop-action%E3%80%82