架构设计

DCC-MCP-Core 是一个 Rust workspace，通过 PyO3 提供 Python 绑定。当前架构是 gateway-first：MCP 客户端、CLI 用户、ClawHub/OpenClaw skills、CI 和自定义 HTTP 客户端都汇聚到一套小型发现/调度控制面，而不是把所有后端工具塞进 tools/list。

零运行时第三方依赖 — Rust 核心无第三方运行时依赖
可选 Python 绑定 — 通过 PyO3 实现 DCC 集成
41 个 workspace 包（40 个功能包 + workspace-hack）— 以根目录 Cargo.toml 为准，按需选择性依赖

当前 Gateway-first 栈

+--------------------------------------------------------------------------------+
| Agent / operator surfaces                                                       |
| - MCP clients: search_tools -> describe_tool -> call_tool                       |
| - CLI users: dcc-mcp-cli list/search/describe/call                              |
| - ClawHub/OpenClaw skills: dcc-cli-gateway or dcc-rest-gateway                  |
| - CI and custom clients: REST /v1/*                                             |
+----------------------------------------+---------------------------------------+
                                         |
                       MCP Streamable HTTP + REST /v1/*
                                         |
+----------------------------------------v---------------------------------------+
| Elected gateway (Rust HTTP control plane)                                       |
| - Minimal MCP tools/list: discovery and dispatch primitives only                |
| - Dynamic capability search, schema describe, single/batch call routing         |
| - Instance registry, TCP liveness probes, version-aware election, failover      |
| - Admin UI, OpenAPI, audit logs, traces, metrics, jobs, workflows, artefacts    |
+----------------------------------------+---------------------------------------+
                                         |
                    Gateway-routed calls to owning per-DCC server
                                         |
        +-------------------------------+-------------------------------+
        |                               |                               |
+-------v--------+              +-------v--------+              +-------v--------+
| Maya adapter   |              | Blender adapter|              | Custom host    |
| MCP + REST     |              | MCP + REST     |              | MCP + REST     |
| Skills catalog |              | Skills catalog |              | Skills catalog |
+-------+--------+              +-------+--------+              +-------+--------+
        |                               |                               |
  Host bridge / UI-thread pump    Host bridge / add-on           Host RPC / IPC

Crate 结构

dcc-mcp-core (workspace 根目录)
├── dcc-mcp-models       # ToolResult, SkillMetadata, DCC 类型
├── dcc-mcp-actions      # ToolRegistry, EventBus, ToolDispatcher, Pipeline
├── dcc-mcp-skills       # SkillScanner, SkillCatalog, SkillWatcher, Resolver
├── dcc-mcp-protocols    # MCP 类型: ToolDefinition, ResourceDefinition, Prompt, BridgeKind
├── dcc-mcp-jsonrpc      # MCP 2025-03-26 JSON-RPC 线协议类型
├── dcc-mcp-wire         # MCP/REST call envelope 规范化
├── dcc-mcp-job          # 异步 job 追踪和可选持久化
├── dcc-mcp-skill-rest   # Per-DCC /v1/* REST Skill API
├── dcc-mcp-gateway-core # 纯 gateway 领域/search/ranking 类型
├── dcc-mcp-gateway-search # 能力搜索/排序引擎
├── dcc-mcp-gateway      # Multi-DCC 网关应用层和动态 wrappers
├── dcc-mcp-http-types   # 纯 HTTP 线协议/配置/值类型、McpHttpConfig
├── dcc-mcp-http-server  # 可复用 HTTP runtime 支撑层
├── dcc-mcp-http-py      # HTTP API 的 PyO3 绑定边界
├── dcc-mcp-transport    # IPC (ipckit), DccLinkFrame, IpcChannelAdapter, SocketServerAdapter
├── dcc-mcp-process      # PyDccLauncher, ProcessMonitor, ProcessWatcher, CrashRecovery
├── dcc-mcp-telemetry    # Tracing/recording: ToolRecorder, TelemetryConfig
├── dcc-mcp-sandbox      # Security: SandboxPolicy, SandboxContext, AuditLog
├── dcc-mcp-shm          # Shared memory: PySharedBuffer, PyBufferPool
├── dcc-mcp-capture      # Screen capture: Capturer, CaptureFrame
├── dcc-mcp-usd          # USD scene description: UsdStage, SdfPath, VtValue
├── dcc-mcp-workflow     # YAML 工作流与恢复
├── dcc-mcp-scheduler    # cron/webhook 调度
├── dcc-mcp-artefact     # FileRef 与内容寻址交接
├── dcc-mcp-http         # Embedded MCP HTTP facade + 兼容 re-export
├── dcc-mcp-cli          # 客户端控制面 CLI
├── dcc-mcp-server       # 二进制入口点: dcc-mcp-server, gateway runner
├── dcc-mcp-logging      # 滚动文件日志
├── dcc-mcp-paths        # 平台路径辅助
├── dcc-mcp-pybridge*    # PyO3 helper crates
├── dcc-mcp-host         # Host execution bridge 契约
├── dcc-mcp-tunnel-*     # Remote MCP tunnel protocol、relay、agent
├── dcc-mcp-catalog      # 公开适配器目录 search/describe
└── workspace-hack       # cargo-hakari feature 统一

依赖关系图

dcc-mcp-models (基础类型)
       ↓
dcc-mcp-actions ← dcc-mcp-models
       ↓
dcc-mcp-skills ← dcc-mcp-actions, dcc-mcp-models
       ↓
dcc-mcp-protocols ← dcc-mcp-models
       ↓
dcc-mcp-wire ← dcc-mcp-jsonrpc, serde_json（规范化 MCP/REST call envelope）
       ↓
dcc-mcp-transport ← dcc-mcp-protocols
       ↓
dcc-mcp-gateway-core ← 纯 gateway 领域/search/ranking 类型
       ↓
dcc-mcp-gateway-search ← 可复用能力搜索/排序引擎
       ↓
dcc-mcp-gateway ← dcc-mcp-gateway-core, dcc-mcp-gateway-search, dcc-mcp-wire, dcc-mcp-transport
       ↓
dcc-mcp-http-types ← 纯 HTTP 线协议/配置/值类型
       ↓
dcc-mcp-http-server ← dcc-mcp-http-types, dcc-mcp-jsonrpc, dcc-mcp-job, dcc-mcp-host
       ↓
dcc-mcp-http ← dcc-mcp-http-types, dcc-mcp-http-server, dcc-mcp-gateway, dcc-mcp-skill-rest
       ↓
dcc-mcp-server ← dcc-mcp-http

dcc-mcp-cli ← dcc-mcp-catalog + gateway REST contract

各 Crate 职责

dcc-mcp-models

职责：核心数据模型和类型定义，所有 crate 共享。

关键类型：

ToolResult — 统一的动作执行结果类型
SkillMetadata — 解析后的技能包元数据
SceneInfo、SceneStatistics — DCC 场景信息
DccInfo、DccCapabilities、DccError — DCC 适配器类型
ScriptResult、CaptureResult — 操作结果

依赖：无（基础 crate）

dcc-mcp-actions

职责：集中式动作注册、验证、调度和中间件管线系统。

关键组件：

ToolRegistry — 线程安全注册表：register/get/search/list/unregister actions
ToolDispatcher — 带验证的调度，路由到已注册的 Python 可调用对象
ToolValidator — 基于 JSON Schema 的参数验证
ToolPipeline — 中间件管线（日志、计时、审计、限流）
EventBus — DCC 生命周期事件的发布/订阅系统
VersionedRegistry — 多版本动作注册表，支持 SemVer 约束解析

关键特征：动作是普通的 Python 可调用对象，通过 ToolDispatcher.register_handler() 注册

依赖：dcc-mcp-models

dcc-mcp-skills

职责：零代码技能包发现、加载和文件系统热重载。

关键组件：

SkillScanner — 基于 mtime 缓存的目录扫描器，发现 SKILL.md 包
SkillCatalog — 渐进式技能发现与加载管理（推荐 API）
SkillWatcher — 平台原生文件系统监听器（inotify/FSEvents/ReadDirectoryChangesW）
SkillMetadata — 从 agentskills.io SKILL.md 以及 metadata.dcc-mcp.* 指向的同级文件解析的元数据
依赖解析：resolve_dependencies、expand_transitive_dependencies、validate_dependencies

技能包格式：SKILL.md 使用 agentskills.io frontmatter（name、description、可选 license / compatibility / allowed-tools），dcc-mcp-core 扩展放在 metadata.dcc-mcp.* 下，并指向同级文件（例如 tools.yaml、groups.yaml、workflow、prompt、resource 和外部依赖声明）。严格 loader 会拒绝旧的顶层 dcc-mcp 扩展键。

依赖：dcc-mcp-actions、dcc-mcp-models

dcc-mcp-protocols

职责：MCP（Model Context Protocol）类型定义，遵循 2025-03-26 规范。

关键类型：

ToolDefinition、ToolAnnotations — MCP 工具模式及行为提示
ResourceDefinition、ResourceTemplateDefinition、ResourceAnnotations — MCP 资源模式
PromptDefinition、PromptArgument — MCP 提示词模式
DccAdapter — DCC 适配器能力描述符
BridgeKind — 桥接类型枚举（Http、WebSocket、NamedPipe、Custom）

依赖：dcc-mcp-models

dcc-mcp-transport

职责：IPC 和网络传输层，基于 ipckit 提供帧级通信。

传输类型：

IPC：Unix sockets (Linux/macOS) / Windows 命名管道 — 亚毫秒延迟，PID 唯一
TCP：网络套接字 — 跨机器或降级使用

关键组件：

IpcChannelAdapter — 基于 ipckit 的客户端/服务端 IPC 适配器，使用 DccLink 帧
SocketServerAdapter — 多客户端 TCP/UDS 监听器，用于服务端 IPC
DccLinkFrame — DccLink 线协议二进制帧类型（msg_type, seq, body）
TransportAddress — 协议无关端点（TCP、命名管道、Unix Socket）
FileRegistry — 基于文件的服务发现（Gateway 使用）

线协议：MessagePack，4 字节大端长度前缀

依赖：dcc-mcp-protocols、tokio

dcc-mcp-process

职责：跨平台 DCC 进程生命周期管理和崩溃恢复。

关键组件：

PyDccLauncher — 异步 spawn/terminate/kill DCC 进程
PyProcessMonitor — 通过 sysinfo 进行 CPU/内存监控
PyProcessWatcher — 后台事件轮询监听器，含心跳/状态追踪
PyCrashRecoveryPolicy — 指数/固定退避重启策略

依赖：tokio、sysinfo

dcc-mcp-telemetry

职责：分布式追踪和指标收集。

关键组件：

ToolRecorder / RecordingGuard — RAII 计时守卫，用于动作执行
ToolMetrics — 每个动作指标的只读快照（计数、成功率、P95/P99 延迟）
TelemetryConfig — 全局遥测 provider 构建器（stdout/JSON 导出器）

依赖：tracing、metrics

dcc-mcp-sandbox

职责：安全策略执行、审计日志和输入验证。

关键组件：

SandboxPolicy — API 白名单、路径允许列表、执行约束（超时、最大动作数、只读）
SandboxContext — 每会话执行上下文，捆绑策略 + 审计日志
AuditLog / AuditEntry — 每次动作调用的结构化审计追踪
InputValidator — 基于 Schema 的验证，含注入防护模式匹配

依赖：无

dcc-mcp-shm

职责：零拷贝共享内存缓冲区，用于高频 DCC ↔ Agent 数据交换。

关键组件：

PySharedBuffer — 命名内存映射文件缓冲区，支持跨进程传递
PyBufferPool — 固定容量的可复用缓冲池（在 30fps 下摊销 mmap 开销）
PySharedSceneBuffer — 高级包装器，含内联 vs 分块存储（>256 MiB 分割）

压缩：写入时可选 LZ4；读取时自动解压

依赖：lz4

dcc-mcp-capture

职责：GPU 帧缓冲截图和 DCC 应用视口捕获。

后端：

Windows：DXGI Desktop Duplication API — GPU 直接访问，<16ms 每帧
Linux：X11 XShmGetImage
降级：Mock 合成后端（CI / headless）

关键组件：

Capturer — 自动后端选择入口点（new_auto() / new_mock()）
CaptureFrame — 捕获的图像数据，含 PNG/JPEG/raw BGRA 编码

依赖：平台特定（windows-capture、x11grab 等）

dcc-mcp-usd

职责：USD 场景描述数据模型和序列化（纯 Rust，无 OpenUSD C++ 依赖）。

关键组件：

UsdStage — 主 Stage 容器，含 prim 管理和元数据
UsdPrim — Prim，含属性 get/set 和 API Schema 检查
SdfPath — 场景图路径，含绝对/相对解析
VtValue — 变体值容器（bool、int、float、string、vec3f、asset、token）

序列化：USDA（可读）和 JSON（紧凑，用于 IPC）

桥接函数：scene_info_json_to_stage、stage_to_scene_info_json、units_to_mpu、mpu_to_units

依赖：pxr-usd（薄包装，无 C++ 运行时）

dcc-mcp-gateway-core

职责：纯 gateway 领域层，包含 capability record、slug helper、search query/page/hit 和 ranking/scoring。它不依赖 HTTP、async runtime、FileRegistry 或 dcc-mcp-gateway。

关键组件：

PendingCall — gateway 到 backend 的取消关联值对象
CapabilityRecord — 紧凑的每工具 search/dispatch record
SearchQuery、SearchHit、SearchPage、SearchMode — 面向 agent 的低 token 搜索契约
ExactScorer、FuzzyScorer、SubstringScorer、StrategyScorer — 可组合 ranking 策略

dcc-mcp-gateway

职责：Multi-DCC gateway 应用/基础设施层，负责 registry probe、动态 MCP wrappers、/v1/* REST facade、路由、诊断和 admin 表面。

关键组件：

CapabilityIndex + refresh tasks — 从活跃 per-DCC 实例构建 capability records，并剔除 stale 实例
search_tools、describe_tool、call_tool — 固定 gateway MCP wrappers，覆盖动态 capability index
Gateway REST facade — POST /v1/search、/v1/describe、/v1/call 以及 diagnostics/resources/prompts 聚合
Admin/dashboard — /admin/api/* 只读检查 instances、tools、calls、traces、stats、workers、logs、health

dcc-mcp-http-types

职责：从 dcc-mcp-http 迁出的纯 HTTP 线协议/配置/值类型，无 axum、tower、tokio runtime、reqwest 或 PyO3 依赖。

关键类型：

HttpError / HttpResult — 共享 HTTP 错误分类
JobConfig、WorkflowConfig、TelemetryConfig、FeatureFlags、InstanceConfig — server 配置值对象
PromptSpec、ProducerContent、OutputEntry、SessionLogMessage — prompt/resource/output/session 线协议值
TruncationEnvelope、SseChunkFrame — response size 与 SSE chunking helpers

dcc-mcp-http-server

职责：可复用的 embedded MCP HTTP server runtime 支撑层，无 axum 或 PyO3 依赖。

关键组件：

build_core_tools — 构造固定 core MCP tool descriptors
DccExecutorHandle、DeferredExecutor — host/main-thread execution bridge
McpSession、SessionManager、ToolListSnapshot — session 状态和 connection-scoped tools/list cache
InFlightRequests、CancelToken、ProgressReporter — cancellation/progress routing
JobNotifier、WorkflowUpdate、WorkspaceRoots — job/workflow notifications 和 root resolution

dcc-mcp-http

职责：MCP Streamable HTTP facade（2025-03-26 规范），拥有 axum routing、server startup、McpHttpConfig aggregate、Python bindings、prompt/resource registries，并从拆分 crate 兼容重导出历史路径。

关键组件：

McpHttpServer — 后台线程 HTTP 服务器（axum/Tokio）
McpHttpConfig — queue/gateway/session/telemetry/features/instance 子配置的 thin aggregate
McpServerHandle — URL 获取、is_gateway 标记和优雅关机
ResourceRegistry / PromptRegistry — MCP resources/* 和 prompts/* 实现
Gateway bootstrap — 将动态 gateway 行为委托给 dcc-mcp-gateway

依赖：axum、tokio、reqwest、socket2、dcc-mcp-http-types、dcc-mcp-http-server、dcc-mcp-gateway、dcc-mcp-skill-rest、dcc-mcp-transport、dcc-mcp-protocols、dcc-mcp-actions、dcc-mcp-skills

dcc-mcp-server

职责：独立的二进制入口点，提供完整的 MCP 服务器。

关键组件：

dcc-mcp-server CLI — 解析命令行参数，启动 Gateway + MCP HTTP 服务器
使用 GatewayRunner 库 API 进行端口竞争和实例注册

依赖：dcc-mcp-http

基础设施 crate

旧的 dcc-mcp-utils 已拆分并删除。新增基础设施能力应放到有明确职责的 crate：dcc-mcp-logging（文件日志）、dcc-mcp-paths（平台路径）、dcc-mcp-pybridge（PyO3/JSON/YAML 桥接），或对应领域 crate，避免重新引入通用 utils。

Skills-First 架构

推荐通过 create_skill_server 以 Skills-First 模式将 DCC 工具暴露到 MCP。一次调用即可串联完整的技术栈：

create_skill_server("maya")
        │
        ├─ ToolRegistry   （线程安全 Action 注册表）
        ├─ ToolDispatcher （将调用路由到 Python 处理函数）
        ├─ SkillCatalog     （发现 + 加载 SKILL.md 技能包）
        │       └─ 扫描 DCC_MCP_MAYA_SKILL_PATHS + DCC_MCP_SKILL_PATHS
        └─ McpHttpServer    （返回可立即启动的 HTTP 服务器）

python

import os
os.environ["DCC_MCP_MAYA_SKILL_PATHS"] = "/studio/maya-skills"

from dcc_mcp_core import create_skill_server, McpHttpConfig

server = create_skill_server("maya", McpHttpConfig(port=8765))
handle = server.start()
print(f"Maya MCP server: {handle.mcp_url()}")
# 完成后调用 handle.shutdown()

技能路径解析顺序（先找到的优先）：

DCC_MCP_{APP}_SKILL_PATHS — 应用专属环境变量（如 DCC_MCP_MAYA_SKILL_PATHS）
DCC_MCP_SKILL_PATHS — 全局降级
平台数据目录：~/.local/share/dcc-mcp/skills/{app}/
extra_paths 参数

手动组装

如果需要自定义中间件或更精细的控制，可手动组装： ToolRegistry → ToolDispatcher → SkillCatalog → McpHttpServer。

Python 绑定

workspace 通过 maturin 构建为单一 PyO3 原生扩展（dcc_mcp_core._core）；启用哪些可选功能以 pyproject.toml 和根目录 justfile 为准。

toml

# pyproject.toml
[project]
requires-python = ">=3.7"
dependencies = []  # 零运行时依赖

Python 包结构

python/dcc_mcp_core/
├── __init__.py     # 顶层公开重导出
├── skill.py        # 纯 Python Skill 脚本辅助（无 _core 依赖）
├── result_envelope.py # Typed ToolResult helpers
└── py.typed        # PEP 561 标记

# _core.pyi 是 stub-gen/dev 构建后的生成产物，不是手写源码

设计决策

1. 零运行时 Python 依赖

原生扩展捆绑所有 Rust 代码 — 无需 pip install PyO3、tokio 等。这确保了：

与 DCC 内嵌 Python 无版本冲突
在 Maya/Blender/Houdini/3ds Max 中行为可预测
最小导入延迟

2. PyO3 0.28+ / Maturin

使用 PyO3，特性：

multiple-pymethods — 每个 struct 多个 #[pymethods]
abi3-py38 — Python 3.8+ 稳定 ABI（CI 测试 3.7–3.13）
extension-module — 允许从任意 Python 路径加载

3. Rust Edition 2024, MSRV 1.95

4. Tokio 异步运行时

Rust 异步的事实标准，Windows 命名管道支持出色。

5. MessagePack 线协议

紧凑二进制格式，4 字节大端长度前缀 — 语言无关。

6. `parking_lot` Mutex

比 std::sync::Mutex 更快，且不会在 panic 时中毒。

线程安全

所有内部状态使用：

parking_lot::Mutex 用于短期临界区
parking_lot::RwLock 用于读写模式
不使用 std::sync::Mutex 或 RwLock

错误处理

使用 thiserror 处理错误类型，通过 #[from] 实现自动转换。

测试策略

单元测试：每个 crate 有内联 #[cfg(test)] 模块
集成测试：tests/ 目录包含 Python + Rust 测试（通过 cargo test 和 pytest）
覆盖率追踪：cargo-llvm-cov + pytest --cov

构建命令

命令	工具	用途
`cargo check`	cargo	快速语法/类型检查
`cargo clippy`	clippy	使用 `-D warnings` 静态分析
`cargo fmt --check`	rustfmt	格式检查
`maturin develop`	maturin	以开发模式安装 wheel
`cargo test --workspace`	cargo	运行所有 Rust 测试
`pytest tests/`	pytest	运行 Python 集成测试

架构设计 ​

当前 Gateway-first 栈 ​

Crate 结构 ​

依赖关系图 ​

各 Crate 职责 ​

dcc-mcp-models ​

dcc-mcp-actions ​

dcc-mcp-skills ​

dcc-mcp-protocols ​

dcc-mcp-transport ​

dcc-mcp-process ​

dcc-mcp-telemetry ​

dcc-mcp-sandbox ​

dcc-mcp-shm ​

dcc-mcp-capture ​

dcc-mcp-usd ​

dcc-mcp-gateway-core ​

dcc-mcp-gateway ​

dcc-mcp-http-types ​

dcc-mcp-http-server ​

dcc-mcp-http ​

dcc-mcp-server ​

基础设施 crate ​

Skills-First 架构 ​

Python 绑定 ​

Python 包结构 ​

设计决策 ​

1. 零运行时 Python 依赖 ​

2. PyO3 0.28+ / Maturin ​

3. Rust Edition 2024, MSRV 1.95 ​

4. Tokio 异步运行时 ​

5. MessagePack 线协议 ​

6. parking_lot Mutex ​

线程安全 ​

错误处理 ​

测试策略 ​

构建命令 ​

架构设计

当前 Gateway-first 栈

Crate 结构

依赖关系图

各 Crate 职责

dcc-mcp-models

dcc-mcp-actions

dcc-mcp-skills

dcc-mcp-protocols

dcc-mcp-transport

dcc-mcp-process

dcc-mcp-telemetry

dcc-mcp-sandbox

dcc-mcp-shm

dcc-mcp-capture

dcc-mcp-usd

dcc-mcp-gateway-core

dcc-mcp-gateway

dcc-mcp-http-types

dcc-mcp-http-server

dcc-mcp-http

dcc-mcp-server

基础设施 crate

Skills-First 架构

Python 绑定

Python 包结构

设计决策

1. 零运行时 Python 依赖

2. PyO3 0.28+ / Maturin

3. Rust Edition 2024, MSRV 1.95

4. Tokio 异步运行时

5. MessagePack 线协议

6. `parking_lot` Mutex

线程安全

错误处理

测试策略

构建命令