在搜索 Unity 6.2 官方文档、Claude Code/AGENTS.md 现状、Gitea Actions 实践、game-ci 等关键来源后，下面是**基于事实而非推测**的修订建议。重点考虑你提到的 **Unity 6.2+** 和 **自建 Gitea** 这两个约束。 --- ## 一、需要立刻修正的事实性错误 ### 1. AGENTS.md 与 CLAUDE.md 的关系需要明确 我之前默认 AGENTS.md 等价于 CLAUDE.md，事实更复杂： - AGENTS.md 是 2025 年由 Sourcegraph、OpenAI、Google、Cursor 等合作推出，现由 Linux Foundation 旗下的 Agentic AI Foundation 维护，被 Claude Code、Cursor、GitHub Copilot、Gemini CLI、Windsurf、Aider、Zed、Warp、RooCode 等广泛支持。 - **但有一个关键例外**：Claude Code 截至 2026 年 4 月仍未原生读取 AGENTS.md，相关 GitHub issue 积累了数千 upvote 但 Anthropic 没给出时间表，标准变通方案是写 AGENTS.md 然后做 symlink：`ln -s AGENTS.md CLAUDE.md`。 **建议**：在你的 Unity 文档里明确写出这个 symlink 工作流，否则 Claude Code 用户拿到仓库后会读不到 AGENTS.md。 ### 2. AGENTS.md/CLAUDE.md 当前长度严重超标 这是我上一轮没指出的最大问题。当前 Unity 文档的 AGENTS.md + 附录 B 的所有 docs 加起来有几千行，但研究表明： - 前沿思考型 LLM 大约能可靠遵循 150–200 条指令；非思考型模型和小模型衰减得更快。 - Claude Code 的系统提示已用掉约 50 条指令——大约占 agent 能可靠遵循指令的三分之一，因此 CLAUDE.md 应包含尽量少的指令。 - 研究建议保持 CLAUDE.md 简洁，理想情况下不超过 300 行。 - 最常见的错误是把代码风格指南塞进 CLAUDE.md——**永远不要让 LLM 干 linter 的活**，LLM 又贵又慢，应当尽可能用确定性工具。 **这意味着你当前 AGENTS.md 的大部分内容应该删掉**，特别是： - 详细的 C# Style 规则（交给 `.editorconfig` + Roslyn Analyzer） - 大段 Unity Lifecycle Rules（交给 Microsoft.Unity.Analyzers） - 完整的反模式 ✗/✓ 对照表（如果 analyzer 能拦就用 analyzer 拦） 只保留**确定性工具无法表达的项目级约束**：模块依赖方向、入口脚本、`[FormerlySerializedAs]` 迁移要求、`-executeMethod` 入口、不可碰的资源目录等。 --- ## 二、Unity 6.2 特有的修正 ### 1. Build Profiles 已取代 Build Settings（Unity 6.0+） 文档里仍说 `File > Build Settings`，这是 2022.3 LTS 的旧术语。 - Unity 6 引入了 Build Profiles，帮助跨平台和环境定义并复用构建配置。 - 每个 Build Profile 是一组配置设置，通过 `File > Build Profiles` 访问。 - Unity 将每个 Build Profile 保存为 `.asset` 文件（例如 `Assets/Settings/Build Profiles/AndroidDevelopment.asset`），并应提交到版本控制。 **建议**： - `docs/build-and-release.md` 必须围绕 Build Profile `.asset` 文件设计，而不是过去的 BuildSettings.asset。 - 把 Build Profile 资产明确加入 AGENTS.md 的"不要随意修改"清单——它们直接决定 CI 产物。 - Unity 6.2 还为 Web、Android、iOS、macOS、Windows 提供了 每个 Build Profile 的 Diagnostics 设置覆盖，需要在 AGENTS.md 提一下"不要在没有 release owner 同意下开关 Diagnostics"。 ### 2. Unity Test Framework 已成为核心包 文档里写"Add or update EditMode tests"和"PlayMode tests"暗示两者必须分开。Unity 6.2 已经不需要： - Unity Test Framework 已成为核心包，其用户手册已整合到 Unity 核心手册。 - UTF 2.0 通过引入 `RequiresPlayModeAttribute` 移除了必须把 EditMode 和 PlayMode 测试放在不同 assembly 的要求；Editor-only 测试 assembly 现在可以包含会运行在 Play Mode 的测试（带 `[RequiresPlayMode]`），平台特定 assembly 也可用 `[RequiresPlayMode(False)]` 让测试不在 Play Mode 运行。 - UTF 2.0 还支持用 .NET Task 异步编程模型编写异步测试。 **建议**： - 简化目录结构——不必再强制 `Tests/EditMode/` 和 `Tests/PlayMode/` 两个 asmdef。可以保留一个 `Project.Tests` asmdef，用属性区分测试模式。 - AGENTS.md 里建议用 `[RequiresPlayMode]` 而不是机械地把测试塞到 PlayMode asmdef。 ### 3. 关于异步：Awaitable 已是官方推荐，但 UniTask 仍更完整 文档里只是泛泛地说"Prefer cancellation-aware async flows when using UniTask or Tasks"。Unity 6 的现实更具体： - Unity 6 引入了 awaitable 类型 `Awaitable`，可以认为是 UniTask 的子集，并且 Awaitable 的设计受 UniTask 影响。 - 在 Unity 2023.1 及更新版本中，`await UniTask.WaitForEndOfFrame()` 不再需要 MonoBehaviour，因为它使用 `UnityEngine.Awaitable.EndOfFrameAsync`。 - Unity 内置的 Awaitable 很方便（尤其对想避免外部依赖的库），但 UniTask 仍是更完整、面向生产的工具包：frame-aware delays、WhenAll/WhenAny、细粒度 PlayerLoopTiming、一等公民的 CancellationToken 支持；对应用/游戏，UniTask 仍是不错的默认选择。 **建议**：在 `docs/conventions.md` 给出明确指引： - 项目内部异步代码：用 `Awaitable`（零依赖、官方）。 - 高频/对 GC 敏感的代码、需要 WhenAll/WhenAny 的：用 UniTask。 - 不要让代理在同一代码路径混用 `Task` 和 `UniTask`，否则容易产生隐式同步上下文切换。 --- ## 三、关于 Gitea CI 的修正（最大改动） 我之前给的 GitHub Actions YAML 直接放到你的 Gitea 上会踩坑。事实是： ### 1. Gitea Actions 与 GitHub Actions 兼容但有限制 - Gitea Actions 直接在 Gitea UI 中提供 GitHub Actions 兼容的 CI/CD，但 GitHub Marketplace 的第三方 actions 不能直接用——`actions/checkout`、`actions/setup-python`、`actions/cache` 等流行 action 在 gitea.com 有镜像并可正常工作；act_runner 首次从互联网获取并本地缓存。 - Gitea Actions 基于 nektos/act，act_runner 通过 spawn act 实例运行 workflow；act 试图尽可能兼容 GitHub Actions，但并非完美匹配。 **这意味着**： - `game-ci/unity-test-runner@v4` 和 `game-ci/unity-builder@v4` **在 Gitea Actions 上不一定开箱即用**——它们依赖 GitHub Marketplace。 - `anthropics/claude-code-action@v1`（我上一轮推荐的）同样不能直接在 Gitea 跑。 ### 2. 自建 Gitea 推荐走 GameCI 的 GitLab 路线（Docker 镜像直接调用） GameCI 提供两套体系：GitHub Actions 和 GitLab CI。前者依赖 marketplace，后者依赖 Docker 镜像。**对自建 Gitea，应该参考 GitLab 路线**： - GameCI 的 unity3d-gitlab-ci-example 使用 game-ci 发布的 unity3d Docker 镜像。 - 典型调用方式：用 `unityci/editor:-base-` 镜像，传入 `UNITY_EMAIL`、`UNITY_PASSWORD`、`UNITY_SERIAL` 环境变量，然后通过 `xvfb-run` 调用 `unity-editor -batchmode -nographics`。 **建议的 Gitea Workflow 雏形**（`.gitea/workflows/unity-validate.yml`）： ```yaml name: Unity Validate on: pull_request: workflow_dispatch: jobs: test: runs-on: ubuntu-latest container: image: unityci/editor:6000.2.16f1-base-3 # Unity 6.2 LTS image options: --user root steps: - uses: actions/checkout@v4 with: lfs: true - name: Activate Unity license run: | mkdir -p /root/.cache/unity3d /root/.local/share/unity3d/Unity/ echo "$UNITY_LICENSE" | base64 -d > /root/.local/share/unity3d/Unity/Unity_lic.ulf env: UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }} - name: Run EditMode tests run: | xvfb-run --auto-servernum --server-args='-screen 0 640x480x24' \ unity-editor -batchmode -nographics -logFile /dev/stdout -quit \ -projectPath . -runTests -testPlatform EditMode \ -testResults Logs/editmode-results.xml - name: Run project validation run: | xvfb-run --auto-servernum --server-args='-screen 0 640x480x24' \ unity-editor -batchmode -nographics -logFile /dev/stdout -quit \ -projectPath . \ -executeMethod Project.Editor.Validation.ProjectValidationCommand.RunAll ``` 注意几点： - **不要**用 `game-ci/unity-test-runner@v4`——它会去 GitHub marketplace 拉。 - act_runner 要用 **DinD 或 Docker 模式**，而且要给 runner 配置足够大的镜像（Unity 镜像超 10GB）。Gitea act_runner 默认是 `ubuntu-22.04:docker://node:16-bullseye`，如果默认镜像不够用，可改为 `ubuntu-22.04:docker://<你需要的镜像>`。 - Unity 个人版/专业版的 license 流程不同：Unity Personal License 在 `.ulf` 中产生一个 serial token，需要先在本机 Unity Hub 激活然后定位 `.ulf` 文件。 ### 3. CI 缓存策略要本地化 `actions/cache@v4` 在 Gitea 上是默认禁用的：act_runner 配置文件里 `cache.enabled` 默认是 `false`，需要在配置中启用 cache server 才能使用 `actions/cache`。 - 在 act_runner 的 `config.yaml` 里把 `cache.enabled` 设为 `true`。 - 缓存 `Library/` 是 Unity CI 的关键——首次 import 一个中等项目就要 10–20 分钟，缓存命中后能降到 1–2 分钟。 ### 4. Claude Code 自动化在 Gitea 上的路径 我之前推荐的 `anthropics/claude-code-action` 是 GitHub Action。要在 Gitea 上做"垃圾回收"，更现实的方案是： - 在 act_runner 容器里直接安装 `claude` CLI（npm install @anthropic-ai/claude-code）。 - 用 cron 触发 workflow，workflow 里 shell 调用 `claude -p "..."`。 不要假设 `claude-code-action@v1` 可用，除非你愿意自己 fork 并镜像它的依赖。 --- ## 四、Roslyn Analyzer 落地的精确步骤 上一轮我笼统地建议"引入 Microsoft.Unity.Analyzers"。实际在 Unity 里安装方式与 .NET 项目**完全不同**： - Unity 不支持通过 NuGet 直接安装 Roslyn Analyzers。需要把 NuGet 包当作 `.zip` 下载、解压，找到 `.dll`。 - 把 `.dll` 拖入 Unity 后，需要在 Plugin Inspector 关闭 Any Platform、关闭 Editor 和 Standalone 平台，然后在 Asset Labels 创建并分配一个名为 `RoslynAnalyzer` 的标签（大小写必须完全匹配）。 - Unity 识别 `RoslynAnalyzer` 标签并把带此标签的资产作为 Roslyn Analyzer 或 source generator 处理。 - 从 Visual Studio Tools for Unity 4.3.2.0 起，Microsoft.Unity.Analyzers 会自动包含在 Unity 生成的所有 csproj 中——所以**在 VS/VS Code 里用 Game Development with Unity workload 时不需要手动装，但 CI 上跑 `dotnet format` 时要装**。 **建议补一份 SKILL**：`.agents/skills/unity-roslyn-analyzers/SKILL.md`，写清这套 "下载 → 拖入 → 关闭平台 → 加 `RoslynAnalyzer` 标签"的流程，避免代理用 `dotnet add package` 这种在 Unity 里无效的指令。 --- ## 五、.editorconfig 与 dotnet format 的实际限制 上一轮我说"加 `.editorconfig` 就能让代理统一格式"。实际有坑： - Unity 官方推荐用 `.editorconfig` 而不是 VS 设置导入导出，因为它跨 IDE 共享且能进版本控制。 - 在项目根目录创建 `.editorconfig` 文件并填入想要的配置——Unity 6 生成的 csproj 会自动应用。 - **但**：Unity 项目里每次新增/删除/重命名脚本都会重新生成 sln 和 csproj，覆盖手动改动。所以不能把 editorconfig 引用塞进 csproj 自定义部分，必须放在仓库根目录，让 Unity 重新生成时自动 pick up。 - `dotnet format` 在 Unity 项目上跑要先生成 sln/csproj，且 `dotnet format` 可能会 restore、编译并运行指定项目/方案中的 analyzer，只应在受信任的代码上调用。 **建议**的 pre-commit 调整： ```yaml - repo: local hooks: - id: dotnet-format-whitespace name: dotnet format whitespace # 使用 whitespace 子命令避免触发完整 analyzer 链 entry: bash -c 'dotnet format whitespace --verify-no-changes --include "$(git diff --cached --name-only --diff-filter=ACM | grep "\.cs$" | tr "\n" " ")" || true' language: system files: "\\.cs$" pass_filenames: false ``` 注意用 `dotnet format whitespace` 子命令而不是完整 `dotnet format`：`dotnet format whitespace` 只运行与空格格式化相关的规则，速度快、不依赖 analyzer 是否安装。 --- ## 六、UnityYAMLMerge 路径在 Unity 6 的实际位置 我之前给的路径是 `2022.3.0f1`。Unity 6.2 通过 Unity Hub 安装时的真实路径是： - Windows: `C:\Program Files\Unity\Hub\Editor\6000.2.xfx\Editor\Data\Tools\UnityYAMLMerge.exe` - macOS: `/Applications/Unity/Hub/Editor/6000.2.xfx/Unity.app/Contents/Tools/UnityYAMLMerge` Unity 6.0 官方文档的 SmartMerge 页面确认：要自定义 UnityYAMLMerge 合并行为，配置 `mergerules.txt` 文件，该文件在 Unity 安装的 Editor/Data/Tools 文件夹中。**这与文档里的写法一致**，但需要把示例版本号从 `2022.3.0f1` 换成 `6000.2.x`。 另外，官方推荐的 git 配置使用 `[mergetool "unityyamlmerge"] trustExitCode = false` 加上 `cmd = '' merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED"`——你文档里的写法是对的，无需改动。 --- ## 七、Skills 的当前标准 Skills 部分我上一轮没指出来： - Anthropic 已在 2025 年 12 月 18 日把 Agent Skills 发布为跨平台便携性的开放标准。 - Skill 最简形式是一个包含 SKILL.md 文件的目录；该文件必须以 YAML frontmatter 开头，包含必需的 name 和 description 元数据；启动时 agent 把每个 skill 的 name 和 description 预加载到系统提示，这是渐进披露的第一层。 - Agent Skills 在 Claude.ai、Claude Code、Claude Agent SDK 和 Claude Developer Platform 上都已支持。 你当前的 SKILL.md 模板**已经符合规范**（有 frontmatter、有 name/description）。但建议在 AGENTS.md 里把 skill 路径写清楚：Cursor 用 `.cursor/rules/`、Codex 用项目根的 AGENTS.md + 嵌套 AGENTS.md，**Skills 主要是 Claude Code 的能力**，不要假设其他工具能直接读 `.agents/skills/`。 --- ## 八、最终落地优先级（按 ROI 排序） 1. **砍掉 AGENTS.md 80% 的内容**——保留项目独有约束（asmdef 边界、`[FormerlySerializedAs]`、入口脚本、不可碰目录），其余下放到 `docs/` 让 agent 按需阅读，并新增 symlink `ln -s AGENTS.md CLAUDE.md`。 2. **重写 CI 章节为 Gitea 方案**：删除所有 `game-ci/*@v4` 与 `anthropics/claude-code-action`，改用 `unityci/editor` 容器 + 直接 shell 调用 + DinD runner。 3. **更新 Unity 6.2 术语**：Build Settings → Build Profiles；Tests asmdef 简化为单一 asmdef + `[RequiresPlayMode]`；UnityYAMLMerge 路径改为 Hub 路径。 4. **新增 .editorconfig + Roslyn Analyzer Skill**：用确定性工具替代 AGENTS.md 中的风格规则，写清楚 Unity 特有的"下载 dll + RoslynAnalyzer 标签"安装步骤。 5. **明确 Awaitable vs UniTask 选型规则**：在 `docs/conventions.md` 给出场景化建议，而非笼统提一句。 修订完后，整份 Unity 文档会从"看起来全面"变成"agent 在 Gitea + Unity 6.2 上能真的跑起来"。