企业官网建设流程全解析

当 AI 自动化工具驱动真实工程时，最可怕的不是报错，而是表面一片绿色。Unity-Skills 是面向 Unity 编辑器的 AI 自动化技能引擎，提供 805 个 REST 技能；为了让这些技能"从不静默失败"，项目内置了超过 1100 个测试用例与专门的静默降级审计。这篇文章带你走进仓库，看看这张安全网是如何层层织成的。

🕳️ 什么是"静默失败"？AI 自动化中最隐蔽的坑

AI Agent 调用技能后通常只看status: success。如果技能"成功"了、却悄悄丢弃了过滤条件、跳过了某次写入、或在备份缺失时照常恢复——调用方永远发现不了。

Unity-Skills 的开发者把"返回 success"当作头号嫌疑对象，而不是免罪金牌。

🏛️ 测试体系全景：从 98 个测试文件到 1131 个用例

测试代码集中在 SkillsForUnity/Tests/ 目录下，分为四层：

几个值得新手注意的设计：

• 每个用例都走真实入口。测试不是直接调函数，而是经由SkillRouter.Execute按技能名发真实 JSON 请求，完整覆盖路由、校验、执行链路。
• 可选依赖不"假装有"。AGENTS.md 规定：每个可选包模块在OptionalPackages/下有一个基于 OptionalPackageTestBase.cs 的实测套件，并在 CI 中设定"通过用例下限"（floor）——包在就真测，包不在就跳过，但底线不许倒退。
• 回归测试不许破坏工程本身。AGENTS.md 有一条硬规则：测试失败时绝不能给工程装包、编译脚本或进入 Play 模式，否则一次红测就会把开发工程弄脏。

🕵️ 静默降级审计：把"success"当被告

仓库里最有特色的是两轮专项审计：SilentDegradationRound6Tests.cs 与 SilentDegradationAuditTests.cs。它们的注释开门见山：

下面每一次调用，过去都报告成功（或抛出未处理异常），却丢弃、放宽或根本没执行调用方要求的事。

每条用例固定做两件事断言：① 请求必须被结构化拒绝（errorCode: SEMANTIC_INVALID且明确指出是哪个参数）；②什么都没被写入。真实修复过的"静默降级"案例包括：

• 拼错的组件名被当成"不过滤"：scene_spatial_query收到componentFilter: "MeshRendrer"时，旧实现直接落回"无过滤"，返回半径内全部物体；现在会明确拒绝。
• 保存失败被吞掉：scene_save/scene_unload/scene_create曾丢弃SaveScene的返回值一律报成功；现在不可写目录返回error，且带未保存改动的场景必须保持加载，绝不假装卸载成功。
• 备份缺失照样"恢复"：HybridCLR 文件集恢复在备份目录不存在时整个跳过并报 success；不可读的文件甚至会被当成"操作新增的"直接删除。现在缺失即失败、文件保留（示例用例）。
• 造了个空壳还报成功：ui_create_image给不存在的精灵路径时，旧实现照样创建 Canvas + 空 Image 并报成功；现在在创建任何对象之前就被拒绝（示例用例）。

审计还覆盖边界条件：负数图层索引的地形绘制（用例）、大小写敏感导致"查不到就当没有"的日志查询、无法哈希的文件必须出现在skipped报告里而不是被忽略（用例）。

📖 读回校验：别信返回值，信场景

另一族测试回答一个更根本的问题：写入真的生效了吗？

• DataWriteReadBackTests.cs：组件与预制体写入后，必须用编辑器当前真实持有值（解析后的名字、世界坐标、保存路径、重读的值）来回答，而不是复述输入参数。
• SceneWriteReadBackTests.cs：场景级写入同样读回验证，包括拒绝重父嵌套预制体子对象这类边界。
• SetterEchoAndDryRunTests.cs 覆盖两种相反的撒谎方式：写入的比声称的少（alpha 被悄悄丢弃、枚举值掉出 switch），或写入的比声称的多。它要求响应里带applied/skipped报告——比如给平行光设置range时该字段本就不存在，没有一条skipped记录，这个响应就与"设置成功"完全无法区分。

这里有一条写得很漂亮的原则（引自 SetterEchoAndDryRunTests.cs 的注释）：每次写入都对照活动对象验证，绝不从响应里反推——响应本身正是被测物，信它就会变成循环论证。

🔢 一致性守卫：连文档里的数字都不许错

805 这个数字不是写死的口号，而是被测试盯死的契约：

• SkillCountDocsTests.cs：README 徽章、分类表格、AGENTS.md、根 SKILL.md 中每一处引用的技能数、分类数、源文件数，都与运行中的注册表比对。设计上有个小而精的"金丝雀"测试：数字写错、句子被改写、表格行缺失，三种错误都必须各自被报告——改写句子不能让它悄悄逃过检查。
• SkillMetadataGuardTests.cs：ReadOnly、MutatesScene、TracksWorkflow、RiskLevel这些元数据不是文档，而是运行时真正执行的闸门（决定技能被不收回、能否撤销、要不要人工确认）。该套件把违规数钉死在零，谁提交的声明自相矛盾，谁的提交就是红。
• OutputsReturnContractTests.cs：抓"幽灵键"——曾有一个技能声明返回list，实际返回objects，batch 里的$ref会据此在真实执行时炸掉，而 dryRun 抓不到它。这个 1300 多行的套件保证"声明的输出键必须真实出现在返回结构中"。
• DocExampleValidationTests.cs：文档里每一处示例调用都必须按原文跑通——Agent 是逐字复制这些示例的，文档里一个不存在的参数名等于把UNKNOWN_PARAM错误亲手发给用户。

配合test_smoke_skills这类技能，整套体系甚至能让 AI 自己对 805 个技能做冒烟巡检。

🚀 新手如何上手

1. 先读 README.md 与 docs/SETUP_GUIDE_CN.md 完成安装，在 Unity 面板Window > UnitySkills中启动服务。
2. 用 AGENTS.md 作为开发手册入口：架构一图流（AI agent → unity_skills.py → HTTP → SkillsHttpServer → SkillRouter → 805 skills）、线程硬规则、技能元数据约定都在 前 20 行。
3. 动手前先看 SkillsForUnity/Tests/Editor/Core/ 里最接近你模块的测试套件，照着"走真实入口 + 读回验证"的模式写断言。
4. 新增技能后运行/skillcheck同步各处技能计数——让测试替你把数字守住。

📌 写在最后

Unity-Skills 的测试哲学可以浓缩成三句话："success"不是结论，读回才是；元数据不是注释，是闸门；文档里的每个字，测试都要认账。对于任何想让 AI 安全操作真实工程的项目来说，这套"静默降级审计 + 读回校验 + 文档一致性守卫"的组合拳，比单纯堆测试覆盖率更值得借鉴。