dcc-bridge

DCC Python 桥接核心包，提供 DCC 端 TCP 服务端、通用 TCP 客户端、dcc CLI、DCC 适配器、代码执行、模块热重载和调试集成。

安装

pip install dcc-bridge

安装后自动获得 dcc 全局命令。

开发模式：

uv tool install -e packages/dcc-bridge

快速开始

# 1. 注入自启动脚本并安装 debugpy（以 3ds Max 为例）
dcc setup 3dsmax

# 若网络较慢，可使用国内镜像源加速
dcc setup 3dsmax --pip-index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 2. 打开 DCC，服务自动启动（debugpy 已就绪）

# 3. 验证连接
dcc status
dcc ping

# 4. 执行代码
dcc run code "print('hello from DCC')"

dcc 命令详细用法

命令总览

dcc [--version] {run, setup, unsetup, status, ping, cleanup} ...

dcc run — 执行代码

在 DCC 中执行 Python 代码，支持三种输入方式。

语法

dcc run {file, code, stdin} [target] [选项]

子命令

选项

示例

# 执行文件
dcc run file /path/to/script.py

# 执行代码字符串
dcc run code "print('hello')"

# 从管道执行
echo "print('hello')" | dcc run stdin

# 执行前先重载模块
dcc run file ./my_tool.py --reload

# 指定端口和超时
dcc run code "import pymxs; print(pymxs.rt.maxOps())" --port 7002 --timeout 10

# 指定 DCC 类型（多实例同时运行时）
dcc run code "print('maya')" --dcc-name maya

# 纯文本输出（只打印 stdout 内容）
dcc run code "print(1 + 2)" --plain

输出格式

JSON 模式（默认）：

{
  "success": true,
  "output": ["hello from DCC"],
  "error": null,
  "traceback": null
}

纯文本模式（--plain）：

hello from DCC

执行出错时：

{
  "success": false,
  "output": [],
  "error": "NameError: name 'x' is not defined",
  "traceback": "Traceback (most recent call last):\n  ..."
}

退出码

dcc setup — 注入自启动脚本

在 DCC 的启动目录中写入 dcc_bridge_startup.py，DCC 打开后自动启动桥接服务。同时自动为每个 DCC 版本安装 debugpy 调试模块，安装失败仅输出警告，不影响脚本注入。

不指定 dcc_name 时，自动为 Maya、3ds Max、Substance Painter、Substance Designer、Houdini、Blender 全部执行注入。

语法

dcc setup [<dcc_name>] [--version <版本号>] [--pip-index-url <镜像源>]

参数

示例

# 注入所有已支持的 DCC（Maya + 3ds Max + SP + SD + Houdini + Blender），自动发现版本并安装 debugpy
dcc setup

# 使用国内镜像源加速所有 DCC 的 debugpy 安装
dcc setup --pip-index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 注入 3ds Max（自动发现所有已安装版本，并安装 debugpy）
dcc setup 3dsmax

# 使用国内镜像源加速
dcc setup 3dsmax --pip-index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 注入指定版本的 Maya
dcc setup maya --version 2024

# 注入所有已安装的 Maya
dcc setup maya

# 注入 Substance Painter / Substance Designer
dcc setup substance_painter
dcc setup substance_designer

# 注入 Houdini / Blender
dcc setup houdini
dcc setup blender

注入位置

主脚本统一写入自动加载目录下的 dcc_bridge/ 隔离子目录，自动加载根目录只放一个极小的 launcher 显式 exec 主脚本。这样可避免 DCC 递归自动执行整个自启动目录导致服务被启动两次（双启动）。

Launcher 内的主脚本路径为写死绝对路径，因为 Maya userSetup.py / Houdini uiready.py 等被 DCC 当作脚本 exec 进内置命名空间执行时并不提供 __file__ 变量。

版本发现机制

通过读取 Windows 注册表自动发现已安装版本：

dcc unsetup — 移除自启动脚本

移除 dcc setup 注入的脚本，恢复原始状态。

语法

dcc unsetup <dcc_name> [--version <版本号>]

示例

# 移除 3ds Max 自启动脚本
dcc unsetup 3dsmax

# 移除指定版本的 Maya
dcc unsetup maya --version 2024

# 移除 Substance Painter / Substance Designer 自启动脚本
dcc unsetup substance_painter
dcc unsetup substance_designer

# 移除 Houdini / Blender 自启动脚本
dcc unsetup houdini
dcc unsetup blender

dcc status — 查看桥接状态

扫描 ~/.dcc-bridge/instances/ 目录，列出所有正在运行的 DCC 桥接服务，并可对指定实例执行 ping 测试。

语法

dcc status [--port <端口>] [--dcc-name <类型>] [--version <版本号>] [--plain]

示例

# 查看所有实例状态
dcc status

# 对指定端口执行 ping
dcc status --port 7002

# 对指定 DCC 类型执行 ping
dcc status --dcc-name maya

# 对指定版本执行 ping
dcc status --dcc-name maya --version 2024

# 纯文本输出
dcc status --plain

输出格式

JSON 模式（默认）：

{
  "instances": [
    {
      "pid": 12345,
      "dcc_name": "3dsmax",
      "dcc_version": "2024",
      "host": "127.0.0.1",
      "port": 7002,
      "started_at": "2026-07-15T10:30:00",
      "python_path": "C:\\Program Files\\Autodesk\\3ds Max 2024\\python\\python.exe"
    }
  ],
  "count": 1,
  "ping": {
    "dcc_name": "3dsmax",
    "python_path": "C:\\Program Files\\Autodesk\\3ds Max 2024\\python\\python.exe"
  }
}

未指定 ping 目标时，ping 字段不出现；ping 失败时返回 ping_error。

纯文本模式（--plain）：

Running DCC instances: 1
  3dsmax:7002 v2024
Ping: OK - {'dcc_name': '3dsmax', 'python_path': '...'}

dcc ping — 测试连接

向 DCC 桥接服务发送 ping 请求，验证服务是否可达并获取基础信息。

语法

dcc ping [--port <端口>] [--dcc-name <类型>] [--version <版本号>] [--plain]

示例

# 自动发现并 ping
dcc ping

# 指定端口
dcc ping --port 7002

# 指定 DCC 类型
dcc ping --dcc-name maya

# 指定版本
dcc ping --dcc-name maya --version 2024

# 纯文本输出
dcc ping --plain

输出格式

JSON（默认）：

{
  "success": true,
  "dcc_name": "3dsmax",
  "python_path": "C:\\Program Files\\Autodesk\\3ds Max 2024\\python\\python.exe"
}

纯文本（--plain）：

DCC bridge server is reachable.
DCC type: 3dsmax
Python path: C:\Program Files\Autodesk\3ds Max 2024\python\python.exe

dcc cleanup — 清理数据与脚本

卸载 dcc-bridge 前使用，执行两项清理操作：

1. 删除 ~/.dcc-bridge 用户数据目录（包含所有发现文件）
2. 对所有已安装的 DCC 执行 unsetup，移除自启动脚本

语法

dcc cleanup [--yes]

参数

示例

# 交互式清理（会显示确认提示）
dcc cleanup

# 跳过确认，直接清理
dcc cleanup --yes

目标解析机制

当不指定 --port 时，CLI 通过 ~/.dcc-bridge/instances/ 下的发现文件自动解析目标：

1. 若指定 --dcc-name，只匹配该类型的实例
2. 若指定 --version，进一步按版本筛选
3. 若只找到一个实例，自动连接
4. 若找到多个实例，报错并提示用 --port 或 --dcc-name 指定
5. 若未找到任何实例，报错并提示先启动 DCC

服务发现与端口分配

DCC 端 TCP 服务启动后会自动在 ~/.dcc-bridge/instances/{dcc_name}-{pid}.json 写入发现文件，CLI 与 VS Code 插件通过读取这些文件零配置发现运行中的实例。

• 发现文件命名：{dcc_name}-{pid}.json
• 默认起始端口：7002，多实例时自动递增，避免端口冲突
• 惰性清理：list_instances 会检查 PID 是否存活，已退出的 DCC 进程对应文件会被自动删除

在 DCC 中手动启动服务

正常情况下 dcc setup 后 DCC 打开即自动启动服务。如需手动启动：

from dcc_bridge.start import start_server
start_server(port=7002)

服务启动后会自动在 ~/.dcc-bridge/instances/ 写入发现文件，供 CLI 与 VS Code 插件识别。

作为 Python 包使用

from dcc_bridge import DCCClient

# 直连指定端口
with DCCClient(port=7002) as client:
    result = client.execute_code("print('hello from DCC')")
    print(result.to_dict())

# 自动发现实例
from dcc_bridge.client import resolve_client
with resolve_client(dcc_name="maya") as client:
    client.execute_file("/path/to/script.py")

支持的 DCC

Python 2.7 与自启动注入机制

Python 2.7 DCC 支持

本工具同时支持自带 Python 2.7 的旧版 DCC（如 Maya ≤ 2020、3ds Max ≤ 2020）与 Python 3.x 的新版 DCC。

• 代码执行、模块热重载、服务发现对 py2/py3 DCC 均可用。
• debugpy 不支持 Python 2.x，因此 dcc setup 在检测到目标 DCC 的 Python 为 2.x 时，仅注入自启动脚本、不安装 debugpy；dcc unsetup 同样跳过 debugpy 卸载。
• 在 py2 宿主中运行前，服务会自动把 stdout/stderr 替换为自适应转码包装流（dcc_bridge.compat._Py2UnicodeWriter），避免 print 含非 ASCII 字节时直接崩溃。

自启动注入如何避免双启动

DCC 在启动时会递归自动执行其自启动目录下的所有脚本。如果主脚本直接放在自启动根目录，再加上一个 launcher，服务会被启动两次。为规避此问题：

• 主脚本固定写入自动加载目录下的 dcc_bridge/ 隔离子目录（如 Maya 的 scripts/dcc_bridge/、Max 的 scripts/dcc_bridge/），该子目录不会被 DCC 当作自启动入口递归执行。
• 自动加载根目录只放一个极小的 launcher，显式 exec 隔离子目录中的主脚本。
• launcher 内主脚本路径采用写死绝对路径（由 dcc setup 计算后嵌入），因为 Maya userSetup.py、Houdini uiready.py 等被 DCC 当脚本 exec 进内置命名空间执行时不提供 __file__ 变量，不能用 __file__ 做相对定位。

调试集成说明

dcc_bridge.debug.start_debugpy_server 在启动 debugpy 服务前会调用当前 DCC 适配器的 configure_debugpy(python_path) 方法，完成针对各 DCC 的解释器配置。

SubstanceDesignerAdapter 在条用 debugpy.configure 之前增加了 os.environ["PYDEVD_DISABLE_FILE_VALIDATION"] = "1"，以避免debugpy无法启动侦听模式，因为 SD 内置 Python 是打包冻结版（frozen modules），debugpy 默认校验源码文件一致性，冻结内置库会触发断点失效警告， 有两种解决思路：关闭冻结模块 / 跳过文件校验。 这里选择在脚本最顶部添加环境变量，提前关闭校验，从而屏蔽警告。

许可证

本项目采用 PolyForm Noncommercial License 1.0.0 授权，仅供非商业用途使用。详见根目录 LICENSE 文件。