DCC-MCP Creator

当您正在创建新的 DCC-MCP 适配器，或对现有适配器仓库进行现代化改造时，请使用此技能：服务组合（server composition）、宿主线程分发（host-thread dispatch）、边车/网关连接（sidecar/gateway wiring）、就绪性（readiness）、资源管理（resources）、项目状态（project state）、诊断（diagnostics）、安装生命周期（install lifecycle）或跨 DCC 验证（cross-DCC verification）。

如需处理单个技能包（SKILL.md、tools.yaml、脚本、技能分组及技能分类体系），请改用 dcc-mcp-skills-creator。

运行时术语表

• DCC 启动钩子（DCC startup hook）：在应用启动时于宿主进程中运行的适配器代码；它负责准备环境/实例数据，并在不阻塞 DCC UI/主线程的前提下启动服务路径。
• 每 DCC 服务（Per-DCC service）：为一个具体 DCC 实例注册的一条运行时记录；Python 的 DccServerBase 和 Rust 边车均以“每 DCC 服务”身份参与。
• 边车（Sidecar）：通过稳定命令 dcc-mcp-server sidecar 启动的 Rust dcc-mcp-sidecar 子进程；它桥接宿主 RPC 与 MCP/REST，并在被监控的 DCC 进程退出时随之终止。
• 网关守护进程（Gateway daemon）：整机范围内唯一的 dcc-mcp-server gateway 进程，负责路由、动态能力发现/描述/调用，以及 Gateway Admin 功能。
• 守护者（Guardian）：运行于守护进程支持型服务内部的一个轻量级循环，用于探测网关 /health 端点，并通过 gateway-launch.lock 文件重新确保守护进程存活；它并非独立进程。
• 服务心跳（Service heartbeat）：仅表示该服务记录在注册中心中的新鲜度。切勿将心跳描述为触发网关重启的机制。

快速工作流

1. 对宿主集成方式进行归类：
   • 嵌入式 Python 宿主：Blender、3ds Max Python、Houdini、Maya、Nuke。
   • 外部桥接宿主：ZBrush、Photoshop、Unity、自定义工具。
   • 混合 Python 或 C++ 桥接的游戏/编辑器宿主：Unreal、Unity。
2. 查阅相关参考文档：
   • ADAPTER_WORKFLOW.md：构建路径说明。
   • HOST_PATTERN_MATRIX.md：宿主特异性连接方式说明。
   • CORE_ESCALATION_CHECKLIST.md：在添加适配器本地胶水逻辑前必读。
   • TESTING_AND_RELEASE.md：验证或发布前必读。
   • docs/guide/adapter-release-checklist.md：符合发布流程规范的检查清单。
   • docs/guide/new-adapter-onboarding.md：新适配器脚手架指南。
   • docs/guide/adapter-compatibility-matrix.md：各 DCC 兼容性对照表。
3. 从 DccServerBase + DccServerOptions.from_env(...) 开始构建。
4. 所有宿主 API 调用必须经由 HostExecutionBridge 路由；禁止自行实现第二套脚本执行器。
5. 保持 DCC 身份信息的数据驱动特性：包括 dcc_name、server_name、环境变量前缀、技能名称及网关元数据。
6. 在编写适配器本地封装逻辑前，优先使用核心辅助工具完成技能发现、MinimalModeConfig、项目工具、资源管理、诊断、上下文快照、安装生命周期和网关故障转移等任务。Python 中 DccServerBase.collect_skill_search_paths() 会自动将市场安装的技能（位于 ~/.dcc-mcp/marketplace/ 或 DCC_MCP_MARKETPLACE_INSTALL_ROOT/ 目录下，若该目录存在）纳入搜索路径；因此适配器不应再额外引入另一套市场路径约定。
7. 谨慎选择 dcc-mcp-server 的运行模式：
   • 无子命令、auto 和 serve：确保启动整机范围内的网关守护进程，将当前进程注册为后端，注册完成后维持一个轻量级守护者持续运行，并在服务记录中写入 gateway_runtime_mode 和 gateway_guardian_enabled 字段。
   • serve --no-auto-gateway：仅限单 DCC 场景，不启动网关守护进程。
   • auto --legacy-gateway-election：恢复旧版“内嵌式、先到先得”的网关选举策略。
   • gateway：仅运行整机范围的网关守护进程，不执行任何内联 DCC 执行逻辑。
   • dcc-mcp-server gateway --daemon（显式）：将当前可执行文件作为分离子进程重新启动，而非在异步运行时内进行 fork；若指定 --pidfile PATH，则隐含启用守护进程模式，记录分离子进程 PID，并在重启动失败或 PID 文件写入失败时快速报错退出。
   • 独立网关守护进程模式现支持空闲超时关闭：当最后一个非 __gateway__ 后端在配置的宽限期（默认 DCC_MCP_GATEWAY_IDLE_TIMEOUT_SECS=30）内持续缺席时，守护进程将自动关闭；对于必须长期保活且无本地后端的 Studio/无头部署场景，可设置 --gateway-persist / DCC_MCP_GATEWAY_PERSIST=1 或 --gateway-idle-timeout-secs 0。
   • GET /v1/readyz 接口返回实际生效的 gateway_lifecycle.persist 和 gateway_lifecycle.idle_timeout_secs 值，因此诊断逻辑必须读取该字段，而不得依据环境变量默认值推断策略。
   • Python DccServerBase 适配器、Rust dcc-mcp-server sidecar 进程（当 gateway_port > 0 时）以及已注册的 dcc-mcp-server translate 桥接器，在启动时均遵循相同的“守护进程优先”契约，并在守护进程支持模式下维持相同的守护者运行——这意味着任一存活的 DCC 或桥接器可在 /health 消失后重新确保守护进程存活。
   • 共享的 gateway-launch.lock 文件在启动器中途崩溃时，会在 DCC_MCP_GATEWAY_LAUNCH_LOCK_STALE_SECS 秒后被自动回收；因此适配器应共享 DCC_MCP_REGISTRY_DIR，且不得手动删除该锁文件。
   • dcc_diagnostics__gateway_failover 应报告 daemon-backed 或 embedded-fallback，以便运维人员区分当前运行模式。
8. 当 DCC 启动钩子需在不导入原生核心模块的前提下启动每 DCC 边车时，请使用 dcc_mcp_core.install_lifecycle.build_sidecar_command(...) 或 launch_sidecar(...)；它们生成标准的 dcc-mcp-server sidecar 命令行参数，默认分离 stdio 流，注入共享注册中心/网关环境变量，并允许子进程在不阻塞 DCC 主进程的前提下确保守护进程运行（除非显式传入 no_ensure_gateway=True 或 legacy_gateway_election=True）。
   • build_sidecar_command() 还返回以下字段：readiness_selector、readiness_argv、readiness_command（尊重 DCC_MCP_PYTHON_EXECUTABLE）、dispatch_contract（含 uri_valid、validation_error、dispatch_ready_capable）以及 readiness_contract（含 ready_on_launch=false、direct_use_status）。
   • launch_sidecar(wait_ready_timeout_secs=..., probe_tool=...) 可在安装器、监管器或后台启动任务中调用，以获得相同有界范围的分发判定结果；但请勿在 DCC UI 线程上调用该函数并设置 wait_ready_timeout_secs。
   • 若未传入 wait_ready_timeout_secs，launch_sidecar() 将明确返回 ready=false、readiness_checked=false，且其 readiness 负载的状态为 not_checked（或针对仅诊断用途方案返回 dispatch_not_capable），因此“边车启动成功”绝不可视为“DCC 已打开、可直接使用”。
   • 当启动代码必须在遇到格式错误的真实宿主 RPC URI、stub:// 协议或不支持的宿主 RPC 方案时立即失败，应在调用前传入 require_dispatch_capable=True 或 CLI 参数 --require-dispatch-capable；仅在纯诊断用途的服务记录中才可设为 false。
   • Rust 实现在 dcc-mcp-sidecar 中；适配器仍应依赖生命周期辅助工具和稳定的 dcc-mcp-server sidecar CLI 接口，而非自行构造新的临时二进制命令。
   • 切勿仅凭一条 per-dcc-sidecar 注册记录即认定工具可调用：适配器必须向其 DCC 调度器/技能暴露受支持的宿主 RPC 桥接；启动代码或安装器应使用 sidecar_readiness_status(...) / wait_for_sidecar_ready(...) 获取一个有界、低导入开销的判定结果，再声明插件已就绪。
   • 如需按实例级别验证启动结果，请传入完整的 readiness_selector；若 instance_id 或 host_rpc 匹配多个活跃边车，则这些辅助函数将返回 status="ambiguous"，而非任意选择某一条记录。
   • 当适配器需要验证某真实 tools/call 是否能抵达宿主调度器时，请传入 probe_tool="_diagnostics__ping"（或 CLI --probe-tool）；探测失败将使判定结果保持“未就绪”，直至超时。
   • 运维人员应通过以下途径确认 dispatch_ready=True：上述辅助函数、query_runtime_state(...) 返回的嵌套 dispatch 对象、GET /admin/api/workers 接口，或 gateway://instances / GET /v1/instances 中嵌套的 dispatch 对象；网关的 GET /v1/readyz 接口亦提供每个实例的 dispatch 状态及“就绪”计数，便于启动器与管理面板区分“已列出的 DCC 进程”与“可调用的边车调度器”。
   • 守护进程支持型边车、Python DccServerBase 适配器、dcc-mcp-server 后端及已注册的 translate 桥接器均会发布以下字段：gateway_runtime_mode、gateway_guardian_enabled、gateway_recovery_driver 和 registration_refresh_mode；
     • gateway_recovery_driver="daemon_guardian" 表示恢复行为由守护者发起的 /health 探测驱动；
     • registration_refresh_mode="file_registry_heartbeat" 表示服务记录通过注册中心心跳维持新鲜度，重启后的网关将重新读取该记录，无需显式重新注册。
   • 网关的 GET /v1/readyz 接口亦镜像上述字段，包括每个实例的 gateway、gateway_recovery_driver_counts、registration_refresh_mode_counts、gateway_daemon_guardian_instance_count 和 gateway_daemon_guardian_ready，使得启动检查与管理面板可判断是否存在任一活跃 DCC 服务能重启守护进程。
   • 宿主 RPC 启动失败时仍将保留注册状态，但标记为 dispatch_ready=False、metadata.dispatch_status=unavailable，并附带 failure_stage / failure_reason 供诊断使用。
   • 失败的边车仍可能发布 metadata.mcp_url 作为诊断端点：此时 /v1/readyz 必须报告 dispatcher=false，且 tools/call 必须返回结构化的 transport-error；在 dispatch_status=ready 之前，禁止将网关流量路由至该端点。
   • 对于真实受支持的协议（commandport://、qtserver://、ws:// / wss://），边车将在父 DCC 进程存活期间持续尝试重连，并在宿主桥接器出现时提升同一服务记录；stub:// 仅用于测试，默认即使连接成功也始终为 dispatch_status=unavailable，因此绝不可将其用作适配器启动就绪性证明。
   • Maya commandport:// 边车在 dcc_mcp_maya 存在但其边车调度器缺失时，会返回结构化的 sidecar-dispatcher-unavailable 后端信封；应视其为适配器部分安装问题，而非网关路由失败。
   • 若已就绪的后端后续返回终端错误 host-died，网关将立即从能力索引及 FileRegistry 或 HTTP 注册记录中移除该实例；请勿围绕“等待终端宿主故障后的心跳清理”来设计适配器逻辑。
9. 若适配器无法共享网关的 FileRegistry，请通过 POST /v1/instances/register 远程注册、通过 /heartbeat 刷新、并在关闭时主动注销；网关将在 gateway://instances / GET /v1/instances 中将其暴露为 source: "http" 类型记录，保留 instance_short 和 mcp_url 字段，并通过相同的 live_instances 协议进行路由。
10. 为便于同局域网（LAN）内便捷发现，请启用 mdns 构建，并在适配器侧配对 --advertise-mdns、网关侧配对 --discover-mdns；请仅将此视为多播发现提示，认证/TLS 策略必须显式声明，生产环境中涉及路由或跨子网的部署应优先采用 HTTP 注册或中继（relay）方式。
11. 对于 NAT 或跨子网路由部署，请使用稳定的 instance_id、capabilities_fingerprint、adapter_version 和 scene 元数据运行隧道代理（tunnel agent），然后在独立网关中配置 --relay-source ADMIN_URL=PUBLIC_BASE_URL；网关将在通过 /tunnel//mcp 探测 /v1/healthz 后，将活跃隧道暴露为 source: "relay" 类型记录，其中中继详情存于 source_meta 字段中。
12. 在添加适配器封装逻辑或管理/调试路由时，请保留网关调用方归属信息：让 MCP initialize.params.clientInfo、MCP _meta.agent_context、REST meta.agent_context、x-dcc-mcp-* 请求头以及安全的 User-Agent 回退机制穿透核心逻辑，而非记录原始提示词或本地机器数据。
13. 针对生命周期/内存/遥测策略，请使用以下钩子函数：register_lifecycle_hooks(...)、search_skills(..., session_id=...)、dispatch_session_start(...)、dispatch_before_tool_call(...)、dispatch_after_tool_call(...) 和 dispatch_session_end(...)；当适配器需要有界内存摘要、失败模式规避或会话压缩时，请将 MemoryRecorder(InMemoryMemoryStore()).install(hooks) 与上述钩子配对使用；对隐私敏感的部署场景，请禁用该记录器。
14. 仅当上述公开钩子无法表达适配器边界时，才应专门针对核心提出聚焦的问题（issue）或 RFC。
15. 添加一条可执行的冒烟测试路径：包含构造单元测试，以及以下任一组合：无头 DCC、模拟调度器的 MCP 调用、网关 REST 回放、mDNS 同 LAN 发现冒烟测试、中继源冒烟测试，或针对独立服务器空闲/回归检查的 just idle-memory-smoke。
16. 为提升网关/管理可观测性，请显式暴露状态，而非静默返回零值：流量面板应区分“已禁用”、“不可用”、“已被过滤”和“真实无流量”四种状态；技能面板应区分“已发现”、“已加载”、“已搜索”、“已选中”、“已调用”、“已失败”及“低采用率”技能；面向管理员的界面/路径应保持仅含元数据或别名形式，除非操作员显式配置私有原始数据接收端点。
17. 保持工作流可观测性：适配器调用应携带请求、父级、追踪、会话、DCC、传输及制品/验证元数据，以便 Admin 工作流图可清晰展示 “意图 → 发现 → 技能加载 → 工具调用 → 回退 → 制品 → 验证 → 报告” 全链路，无需阅读原始日志。
18. 保持有界 agent_context 的任务/会话/轮次元数据，以及对制品/验证友好的工具名称，以便 Admin 任务结果可对工作流、调用、交付物及检查项进行聚合分组，而无需解析原始负载或本地路径。

示例：新建 Nuke 适配器

当被要求创建 Nuke 的 MCP 适配器时，请首先梳理宿主生命周期：Python 如何加载、UI/主线程如何进入、是否支持无头模式、插件如何安装，以及哪些操作应打包为默认技能。随后围绕核心基元搭建适配器：

• 使用 DccServerBase 实现 MCP/HTTP 接口及技能目录行为。
• 使用 DccServerOptions.from_env("NUKE") 或适配器专属等效方式实现环境变量驱动的配置。
• 结合 HostExecutionBridge 与 Nuke 调度器，统一处理所有 Nuke API 调用。
• 在添加适配器本地胶水逻辑前，优先集成核心项目、就绪性、资源、诊断及网关辅助工具。
• 使用 dcc-mcp-skills-creator 创建首批 nuke-* 技能包。

不可协商项（Non-Negotiables）

• 禁止从 Tokio/HTTP 工作线程中调用任何 DCC API。
• 当核心已暴露类型化对象或目录 API 时，禁止在适配器运行时代码中解析或重写 SKILL.md、tools.yaml、groups.yaml 或提示词/工作流文件。
• 除非不存在对应公共核心 API，否则禁止访问 server._server；若确有必要，请先提交核心 issue，并保持适配器 shim 尽可能精简。
• 禁止在共享核心或适配器模板中创建 Maya 专用抽象。
• 当一个类型化技能即可覆盖某项任务时，禁止将原始脚本执行暴露为主要用户工作流。
• 禁止在公开 issue 或 PR 正文中发布本地路径、私有机器名或源归属标记。