Prefab Sentinel

用于安全检查和编辑 Unity / VRChat 项目的 Prefab / Scene / Asset 的 MCP 服务器。

通过结构化响应诊断 Variant 的 override 冲突、Broken PPtr / missing fileID、Udon / ClientSim 运行时异常，并绕过手工 YAML 编辑进行修复。面向 AI 代理设计。

基于 YAML 的只读路径（validate_refs / validate_materials / inspect_wiring / inspect_variant / inspect_hierarchy / find_referencing_assets 等）无需启动 Unity 即可完成。inspect_serialized_surface / inspect_with_profile / validate_inspector_profile 通过常驻 Editor Bridge 获取 last-saved SerializedObject surface。写入路径（patch_apply / set_property / editor_* 等）通过 file-IPC 与常驻 Editor Bridge 协作，缺少 confirm=True + 非空 change_reason 审计对的调用将以 CHANGE_REASON_REQUIRED 被拒绝。

公开的 MCP 边界仅提供 Tools capability。stdio 支持 modern 2026-07-28 以及两个 legacy revision（2025-11-25 / 2025-06-18），任意 HTTP 路径仅在本地 loopback 的 /mcp 上提供 modern 2026-07-28。这不是 full conformance 的合格声明，protocol error 的优先级和 stdio transport 例外以 docs/api-reference.md 为准，严格 CI gate 的覆盖范围以 TESTING.md 为准，process-state 的已知偏差以 ARCHITECTURE.md 为准。对应的 request method 和 transport 请参阅 docs/tool-conventions.md、docs/execution-reference.md。

本 README 是各专业文档的入口（参见文档地图）。规范的正本为专业文档群，运维规则的正本为 AGENTS.md。

做 / 不做

做

• 提供 Unity SerializedObject 级别的安全编辑基础，使 Prefab Base / Variant / Scene 实例的有效值可追踪

• 将引用解析（GUID + fileID）和一致性验证 API 化

• 将运行时验证（UdonSharp compile / ClientSim smoke / 日志分类）流水线化

• 使用确定性的 synthetic workload 和固定 budget 检测主要 inspection path 的 latency regression

• 明确区分需要人工判断的更改和可机械执行的更改

• 内置 ModularAvatar / liltoon / VRCFury 等 VRChat 生态系统工具的领域知识，作为 AI 代理的判断依据

• 将运维流程标准化为 Skills（支持 Claude Code / Codex CLI 两种宿主）

不做

• 不将 YAML 字符串的直接替换作为标准手段

• 不通过推测补全 Unity 内部引用

• 不进行无变更依据的自动优化

• 不使用真实项目作为 timing gate，也不从 weekly benchmark 自动更新 baseline

• 不擅自应用需要用户判断的规格变更

• 不公开 legacy HTTP、早于 2025-06-18 的 legacy protocol version、remote / shared HTTP server

Related MCP server: unity-asset-reference-mcp

Quickstart

作为插件引入。根据宿主（Claude Code / Codex CLI）有两条路径，均从 marketplace 获取。

Claude Code（在 Claude Code 内输入的斜杠命令）:

/plugin marketplace add tyunta/prefab-sentinel
/plugin install prefab-sentinel@tyunta-prefab-sentinel

Codex CLI（在 shell 中注册 marketplace → 在 Codex CLI 内的 /plugins TUI 中启用）:

codex plugin marketplace add tyunta/prefab-sentinel

注册后，在 Codex CLI 内打开 /plugins，从列表中选择 prefab-sentinel 并 Install（不存在 codex plugin install 这样的 shell 命令）。

引入后的使用方法以 guide 技能（/prefab-sentinel:guide）为入口 — 汇总了 MCP 工具列表和调用方法、补丁模式、Editor Bridge 的设置、生态系统知识指南。实际调用 MCP 工具的是 AI 代理一侧，因此让代理参考此 guide 即可开始使用。

各路径的详细信息请参阅设置，面向从仓库直接启动 MCP 服务器的开发者的步骤请参阅 CONTRIBUTING.md。

设置

前提条件

• Python 3.11 以上

• uv（包管理器）— 安装步骤请参阅 uv 官方指南（Windows / macOS / Linux 各不相同）

• Unity 2022.3 + VRChat SDK 3.x（Worlds / Avatars）— 通过 Editor Bridge 的写入和运行时验证路径需要

MCP 服务器在 Plugin 内部通过 uv / uvx 本地启动，因此 Plugin 引入路径也需要 Python / uv。宿主（Claude Code / Codex CLI）和本工具支持 Windows / macOS / Linux。

Claude Code Plugin

通过 Quickstart 中的 2 条命令引入。安装后 MCP 服务器、6 个技能、knowledge/ 目录会一并展开，可直接从 Claude Code 调用 /prefab-sentinel:guide 等技能。各技能内的命令通过 ${CLAUDE_PLUGIN_ROOT} 模板变量在本地执行。

Codex CLI Plugin

按 Quickstart 的步骤引入（在 shell 中执行 codex plugin marketplace add → 在 Codex CLI 内的 /plugins TUI 中 Install prefab-sentinel）。MCP 服务器从 Plugin 定义（.codex-plugin/plugin.json 的 mcpServers 指向的 .codex-plugin/mcp.json）注册，packaged MCP definition 也提供所需的 modern protocol marker。skill bundle 同时展开。Codex 的 MCP 服务器由 uvx 从 GitHub 获取本体后启动，因此启动时需要网络连接（Claude Code 路径从本地安装物启动）。更新 Plugin 后请重启 Codex CLI 会话。禁用和注销通过 /plugins TUI 进行。

技能

Unity Bridge

补丁实际应用、运行时验证等写入路径，以及处理 last-saved SerializedObject surface 的 Inspector profile 路径，通过 file-IPC 与常驻在 Unity Editor 内的 Editor Bridge 协作。Bridge 的设置步骤在 /prefab-sentinel:guide 技能中，指定 watch 目录的环境变量 UNITYTOOL_BRIDGE_WATCH_DIR 记载于 CONFIGURATION.md。未设置时调用写入类工具将以 BRIDGE_WATCH_DIR_MISSING、调用 Inspector profile 工具将以 INSPECTOR_SURFACE_UNAVAILABLE 进行 fail-fast 停止。基于 YAML 的只读检查不需要 Bridge 设置。

Python wheel 仅将 tools/unity/ 和 knowledge/ 的发布对象映射到 package 内，不包含 nested .serena 等 workspace-local metadata。

代表性 MCP 工具

所有 MCP 工具的规范目录为 docs/tools.md，响应信封（success / severity / code / message / data / diagnostics）和错误代码的规范为 docs/api-reference.md。下表仅列出代表性工具。

Routine CI / agent validation 使用 validate_runtime(profile="compile_only") 或 validate_runtime(profile="editor_console_only")。ClientSim 是面向 submission scene 的显式 opt-in，在 profile="clientsim" + audit pair 齐备且 requested scene 为 sole loaded active scene 时才执行。详细的 cleanup/restore/side-effect 契约以 docs/api-reference.md 和 docs/execution-reference.md 为准。

基于 YAML 的只读检查（validate_refs / validate_materials / inspect_wiring / inspect_variant / inspect_hierarchy / find_referencing_assets 等）无需 Unity。Inspector profile 的 3 个工具虽然是只读的，但以常驻 Editor Bridge 为前提，editor_* 系列和 patch_apply 的 confirm 应用也使用同一个 Bridge。

validate_refs / inspect_wiring / validate_all_wiring / validate_structure / validate_materials 读取项目根目录的 config/diagnostics_baseline.json，将 diagnostics 分类为 new / known / resolved。baseline 不会自动生成或隐式更新，只有显式的 update_diagnostics_baseline 负责 preview / audit-gated 写入。baseline 文件格式以 CONFIGURATION.md 为准，响应形状与 update 工具契约以 docs/api-reference.md 为准，公开工具列表以 docs/tools.md 为准。

推荐流程：用 validate_refs 早期检测引用损坏 → 用 inspect_variant 将 override 冲突作为实际生效值可视化 → patch_apply 的 dry-run → 应用时指定 confirm=True + change_reason；在 exactly one open Prefab transaction 中，还可指定 out_report 以带审计日志应用。

VRChat 生态系统知识

在 knowledge/ 目录中按 3 个级别（L1 概念 / L2 操作模式 / L3 SerializedProperty）积累 ModularAvatar / liltoon / VRCFury / AvatarOptimizer 等领域知识，并随插件一起分发。guide 技能引导查阅，AI 代理根据任务从 knowledge/ 读取相应知识。知识的调研与扩充通过 knowledge-acquisition 技能进行。编辑规范见 knowledge/STYLE_GUIDE.md。

文档地图

规格说明分散存放在专业文档中。按目的区分的入口如下表所示。