Unity CI Kit

用途

一款即插即用的 Unity 项目 CI 工具包，支持构建–测试–验证全流程的完全自动化。 Python 代理（ci_agent.py）负责调用 Unity 的 batchmode 模式并解析执行结果； C# 运行器（CiRunner.cs）则在 Unity 编辑器内部提供可复用的步骤化执行框架。 二者协同工作，可在开发迭代过程中彻底消除对 Unity 编辑器的手动交互需求。

适用场景

当出现以下任一情况时，应触发本技能：

• 用户提出“为 Unity 设置 CI”或“自动化 Unity 构建”等需求
• 用户希望从命令行运行 Unity batchmode 编译
• 用户需要将硬编码的 CI 脚本迁移为可复用、配置驱动的工具包
• 用户在 Unity 自动化上下文中提及 ci_agent.py、ci_config.json 或 CiRunner.cs
• 用户正在初始化一个新 Unity 项目，并希望从第一天起就采用经过验证的 CI 流水线

请勿将本技能用于非 Unity 项目，或仅需简单一次性 shell 脚本、无需可复用框架的场景。

工作流程

步骤 1：初始化项目

在 Unity 项目根目录下运行 ci_agent.py init。该命令将生成含默认值的 ci_config.json。 请编辑该配置文件，设置以下字段：

• unity_version — 例如 "2022.3.62f3c1"（需与 ProjectVersion.txt 中版本一致）
• unity_path — 留空可启用自动发现；也可手动指定 Unity 可执行文件的绝对路径
• execute_method — 指定要调用的 Unity 静态方法，例如 "StarVanguard.Editor.AutoCI.RunCI" 或 "UnityCI.Editor.CiRunner.RunCI"

步骤 2：安装 Unity 端运行器

将本技能 templates/ 目录下的 templates/CiRunner.cs 复制到项目中的 Assets/Editor/（或 Assets/_Project/Scripts/Editor/）目录。

编辑 RunPipeline() 方法，插入项目专属的构建步骤。每个步骤均使用 Step(string name, Func action) 辅助函数：

private static bool RunPipeline()
{
    bool ok = true;
    ok &= Step("Create Assets",  () => { AssetBuilder.Run();   return true; });
    ok &= Step("Run Validation", () => { TestRunner.RunAll();   return testsPassed; });
    ok &= Step("Apply Font",     () => { FontSetup.Apply();     return true; });
    AssetDatabase.SaveAssets();
    return ok;
}

该辅助函数会自动为每个步骤添加 try-catch 包裹，并输出形如 [AutoCI] STEP: name => OK/FAIL 的日志。 Python 代理将解析这些日志行，生成结构化的 JSON 输出。

步骤 3：验证环境

运行 python ci_agent.py check 以验证以下各项：

• Python 版本兼容
• ci_config.json 文件存在且格式有效
• Unity 可执行文件已在配置路径中找到，或已通过自动发现机制定位
• 项目包含 Assets/ 目录

步骤 4：运行 CI

python ci_agent.py build     # 全流程执行（batchmode + executeMethod + 解析）
python ci_agent.py compile   # 仅编译（快速检查）
python ci_agent.py status    # 读取上一次构建结果 JSON

build 命令执行以下操作：

1. 以 batch mode 启动 Unity（参数：-batchmode -quit -nographics）
2. 执行配置中指定的 execute_method
3. 读取 ci_output.log 并解析 C# 编译错误与警告
4. 将结构化 JSON 写入 ci_result.json
5. 向标准输出打印摘要信息

步骤 5：集成至 AI 工作流

ci_result.json 输出的结构化 JSON 专为 AI 消费设计：

{
  "timestamp": "2026-06-30T08:30:00",
  "build_ok": true,
  "errors": [],
  "error_count": 0,
  "warnings": [...],
  "warning_count": 3,
  "ci_pass": true,
  "log_file": "ci_output.log"
}

AI 代理可执行如下操作：

1. 编写代码变更
2. 运行 python ci_agent.py compile 验证编译是否通过
3. 若存在错误，则解析 ci_result.json → 修复 → 循环重试
4. 确认无错误后，运行 python ci_agent.py build 执行完整验证
5. 全部通过后提交并推送变更

文件布局

project-root/
├── ci_config.json          # 由 `ci_agent.py init` 创建
├── ci_output.log           # Unity batchmode 生成
├── ci_result.json          # `ci_agent.py build` 生成
├── ci_agent.py             # 从本技能的 scripts/ 目录复制
└── Assets/
    └── Editor/
        └── CiRunner.cs     # 从本技能的 templates/ 目录复制

配套资源

scripts/ci_agent.py

主 Python CLI 脚本。请将其复制至项目根目录。运行 python ci_agent.py 查看帮助信息。 支持命令：init、check、build、compile、status。

templates/ci_config.json

最小化配置模板。字段包括：unity_version、unity_path、execute_method、timeout_seconds、log_file、result_file。

templates/CiRunner.cs

通用 Unity 编辑器脚本。提供 Step() 执行框架及 RunCI() 入口方法。 命名空间：UnityCI.Editor；方法签名：public static void RunCI()。

references/setup_guide.md

面向新项目的分步搭建指南。