Maya Agent

v1.6.0 — 面向 Autodesk Maya 游戏开发管线 的 AI Agent：用自然语言驱动建模、UV、绑骨蒙皮、动画、材质、灯光与导出。内置 235 个工具 / 18 个类别，支持 15 家主流大模型（含视觉模型）与云端 AI 3D（Meshy / Tripo / 腾讯混元3D），并可通过 MCP 在 Cursor / VS Code / Claude Desktop 中调用同一套能力。

核心能力

版本：Maya 2020–2026（自动适配 PySide2 / PySide6）；Python 3.7+。

快速开始

方式 A：Windows 图形安装器（推荐，免系统 Python）

面向最终用户的商业安装包（Inno Setup）：

1. 运行 MayaAgent-Setup-1.6.0.exe（由 installer\build.bat 生成，见 installer/README.md）
2. 选择安装目录（默认 %LOCALAPPDATA%\MayaAgent）与要挂钩的 Maya 版本
3. 完全退出并重启 Maya → 菜单 Maya Agent / 工具架 MayaAgent

• 不需要本机安装系统 Python；安装引擎通过 mayapy 写挂钩并应用预置 vendor_cache → .vendor/cp37|cp39|cp311
• 不含 MCP / 代码签名 / 自动更新（MCP 仍见下文「MCP」）
• 构建者：先 python scripts/build_vendor_cache.py，再 installer\build.bat

方式 B：install.bat（源码 / TD，优先 mayapy）

1. 双击项目根目录 install.bat（可选：install.bat 2025 / install.bat all / install.bat force / install.bat uninstall）
2. 完全退出并重启 Maya
3. 菜单栏应出现 Maya Agent，工具架出现 MayaAgent 页签

install.bat / uninstall.bat 优先查找 mayapy，找不到再回退系统 Python；无 Python 时可改用图形安装器或拖入 mel。

版本与 mayapy 由 scripts/maya_discover.py 统一探测（Documents 用户目录、注册表、常见安装路径）。非标准安装可设置：

set MAYA_AGENT_MAYAPY_ROOTS=D:\LAS\LAD\Maya\Program\2025\Maya2025
install.bat

安装结束会打印 Install Report（每版本 hooks / deps / mayapy / load_path）。挂钩失败为错误；仅依赖失败时菜单通常仍可用。对话需 httpx，统计图表需 matplotlib（均在安装必检列表中）。

诊断（只读）：

python scripts/doctor.py
python scripts/doctor.py --maya-version 2025

卸载：双击 uninstall.bat，或 mayapy scripts/install_engine.py --uninstall。

方式 C：拖入式安装（当前会话立即生效）

1. 打开 Maya
2. 将 install_dragdrop.mel 拖进 视口（或工具架 / Script Editor）
3. 成功后菜单与工具架立刻可用，并写入自动加载（下次启动仍有效）；同时会尝试为当前 mayapy / .vendor 安装对话依赖

适合：install.bat 后插件列表已有 MayaAgent、但菜单/工具架未出现；或想跳过重启马上使用。

依赖（对话必需 httpx；图表必需 matplotlib）

install.bat / install_engine.py / 图形安装器会自动安装。失败时的加固路径（依次降级）：

1. 预置 vendor_cache/<abi>/ → 项目 .vendor/<abi>/（离线）
2. mayapy pip（PyPI → 清华 → 阿里 → 腾讯镜像，多镜像 + 代理/直连）
3. 逐包安装缺失模块
4. 可用 Python 下载 wheel → mayapy 离线安装
5. mayapy pip install --target .vendor/<abi>（启动时按解释器 ABI 注入）

手动：

python scripts/install_deps.py --maya-version 2025 --force
python scripts/install_deps.py --vendor-only --tags cp311
python scripts/build_vendor_cache.py --tags cp311

命令行安装

# 统一引擎（推荐；可用 mayapy 运行）
mayapy scripts/install_engine.py
mayapy scripts/install_engine.py --maya-version 2025
mayapy scripts/install_engine.py --force-deps
mayapy scripts/install_engine.py --uninstall

python scripts/install.py --maya-version 2025
python scripts/install.py --dry-run
python scripts/doctor.py

手动启动 / 热重载

Script Editor（Python）：

import maya_agent
maya_agent.launch()   # 打开面板
maya_agent.reload()   # 改代码后重装菜单并打开面板

未装到 Maya 路径时，先把项目根目录加入 sys.path。也可使用菜单 Maya Agent → 重新加载（若面板仍显示旧界面，先关闭面板再打开）。

配置 API

面板 → 模型 → LLM → 选服务商、填 API Key → 点「测试连接」（结果显示在按钮左侧，成功绿 / 失败红）。修改会自动保存；可用「恢复默认」重置参数（API Key 保留）。

也可设环境变量，例如 DEEPSEEK_API_KEY、OPENAI_API_KEY、XAI_API_KEY、ANTHROPIC_API_KEY、GOOGLE_API_KEY、DASHSCOPE_API_KEY、ZHIPU_API_KEY、MOONSHOT_API_KEY、ARK_API_KEY、SILICONFLOW_API_KEY、MESHY_API_KEY、TRIPO_API_KEY、TENCENTCLOUD_SECRET_ID、TENCENTCLOUD_SECRET_KEY。

• 本地模型：Ollama 默认 http://127.0.0.1:11434/v1；自定义 OpenAI 兼容接口填 Base URL + 模型名即可；Cursor 需先在本机启动 Cursor→OpenAI 代理（默认 http://127.0.0.1:4646/v1）。
• Tripo（开发者文档）：面板 → 模型 → Tripo → 填 API Key →「测试连接」。默认 Base URL 为国区 https://openapi.tripo3d.com/v3（国际站可在配置中改为 https://openapi.tripo3d.ai/v3）。
• 混元生3D（API 概览）：面板 → 模型 → 混元 → 填腾讯云 SecretId / SecretKey 与 Region →「测试连接」。默认接入点 ai3d.tencentcloudapi.com（国区 ap-guangzhou）。3D 后处理输入需公网 URL 或上游任务 JobId 串联，不支持本地网格直传。

界面

入口：菜单 Maya Agent → 打开面板，或工具架 Agent 按钮。停靠模式下默认停靠到「属性编辑器」标签组右侧。

使用示例

场景与建模

• 「创建一个立方体，命名为 SM_Crate，冻结变换并居中枢轴」
• 「查看当前场景信息，检查相机裁剪面是否覆盖所有物体」
• 「用圆柱和管道搭一个白盒，按 3 步细化并每步截图给我看」
• 「把选中的高模减面并合并，命名规范用 SM_ 前缀」

UV（游戏资产）

• 「给选中模型做游戏 UV」→ preflight_uv（可选预检）→ prepare_game_uv（默认 cut_mode=auto 自动切缝）→ capture_uv_layout 目视复核
• 「给这个角色统一 texel density 到 10.24 px/cm，并按 0–1 atlas 排布」

绑骨与蒙皮

• 「按 UE5 模板创建骨架并对齐到选中网格，再自动蒙皮」
• 「用 biped 模板一键绑骨，包含 FK/IK 控制器」
• 「给选中网格绑定到选中骨骼，最大影响数 4，然后分析并清理远端着色权重」
• 「把 Meshy 生成的骨架和网格对齐，并把权重迁移到原始分件上」

动画 / 材质 / 灯光 / 导出

• 「给选中物体第 1、24、48 帧打关键帧，并播放一遍预览」
• 「创建三点布光并瞄准选中物体」
• 「把当前选择导出 FBX 到桌面，嵌入贴图」
• 「保存场景并生成 LOD 分组」

云端 AI 3D

• 「用 Meshy 按这段描述生成一个石头怪模型，确认消耗后生成，完成后导入 Maya」
• 「用 Tripo 把这张参考图生成角色，并做一个奔跑动画」
• 「用混元把上一任务的模型贴图后转成 FBX」

数据与文件

• 「统计所有网格的顶点数并生成柱状图」
• 「列出临时目录里的对话截图，把第 2 张图片发给我」
• 「读取我拖入的这份规范文档，按它给模型命名」

工具开发

• 「帮我查 polyReduce 的参数，写一个可复用的 Maya 工具脚本，校验后保存到 scripts 目录，并在工具架创建按钮」

内置工具（235 个 / 18 类）

说明：工具会按可用性动态裁剪——未配置密钥的 Meshy/Tripo/混元工具、未安装的 ADV 工具、以及不支持视觉的模型下的截图/搜图工具不会出现在模型工具列表中；系统提示词中的对应章节也会同步隐藏。destructive 工具（删除、解包、打开场景、执行脚本等）在开启「危险操作前确认」时会先弹窗。

MCP

在 Cursor / VS Code / Claude Desktop 等支持 MCP 的 IDE 中控制当前 Maya 会话：工具列表与 MayaAgent 面板共用同一注册表、同一系统提示词与同一撤销语义。

步骤

1. Maya 内启动 MCP：菜单 Maya Agent → 启动 MCP（或「设置」页签中的 MCP Bridge 区块）
2. 系统 Python 安装 MCP 依赖（不要用 mayapy）：

pip install -r requirements-mcp.txt

1. 复制 MCP 配置：菜单 复制 MCP 配置，粘贴到 Cursor / VS Code 的 mcp.json，例如：

{
  "mcpServers": {
    "maya-agent": {
      "command": "python",
      "args": ["D:/path/to/MayaAgent/scripts/maya_mcp.py"]
    }
  }
}

将路径改成你的项目根目录；python 需能 import mcp / httpx。

1. 在 IDE 中确认 MCP 已连接，然后：
   • 调用 mayaagent_status 检查服务是否在线（含 tool_count）
   • 直接调用任意 Maya 工具（与面板相同的工具名）
   • 或调用 mayaagent_chat 走完整 MayaAgent 多轮循环
   • mayaagent_undo 回退上一轮 Agent 修改
   • mayaagent_system_prompt 获取/刷新系统提示词

本地 HTTP 桥

Maya 进程内运行 loopback HTTP 服务，MCP 代理只是无状态适配器：

• 仅监听 127.0.0.1，除 health 外均需 Authorization: Bearer <token>；token 每次启动随机生成。
• 发现文件：%APPDATA%/MayaAgent/bridge.json（含 host / port / token / pid）。重启 MCP 会刷新 token，IDE 需重连。
• 面板与 IDE 共享同一 Agent，同一时间只允许一个对话在跑；面板忙时 MCP 请求会等待或报 busy。

MCP 连接时会把与面板相同的系统提示词（resources/prompts/system_zh.md + 运行时环境）注入为 server instructions；修改该 md 后，面板与 IDE 两侧都会生效（IDE 侧需重连 MCP 或调 mayaagent_system_prompt 获取最新全文）。

架构速览

单进程、无 asyncio、无 LLM SDK 依赖：

菜单/工具架 ──► ui/main_window（Qt 面板，Maya 主线程）
                    │
                    ├─ AgentWorker（QThread）──► core/MayaAgent.chat() 生成器
                    │        │                      ├─► llm/*Provider（httpx，流式）
                    │        │                      ├─► core/ToolExecutor ──► tools/registry（235 个）
                    │        │                      │        └─ 危险确认 / undo chunk / 主线程 marshal
                    │        │                      └─► memory / session sidecar / undo / system_prompt
                    │        └─ 事件字典（text/thinking/tool_*/done/stopped/error）经 Qt Signal 回主线程
                    │
                    └─ bridge/http_server（127.0.0.1 + token）◄── scripts/maya_mcp.py ◄── Cursor/VS Code

• Agent 循环：MayaAgent.chat() 是同步生成器状态机，yield 事件驱动流式文本、工具轮、进度与结束；工具串行执行，取消为协作式（threading.Event + 检查点）。
• 线程模型：Maya 主线程（UI/场景操作）→ QThread（Agent 循环）→ 每工具 side thread（长网络任务可边跑边报进度）→ 需要 maya.cmds 时 executeInMainThreadWithResult 跳回主线程。
• 可逆性：一轮内首次工具调用时打开整轮 undo chunk，所有修改折叠为一次 Ctrl+Z；MCP 侧对应 mayaagent_undo。
• 能力降级：ADV 是否安装、云服务是否有密钥、模型是否支持视觉，会同时影响「工具列表 + 系统提示章节 + 运行环境说明」三处。
• 会话模型：memory（给模型看，按条数窗口裁剪）与 ui_blocks（给界面看）各存一份，统一写入场景 sidecar。

数据与配置目录

项目结构

MayaAgent/
├── VERSION                      # 唯一版本号源（发版改这里）
├── config/default_config.yaml   # 默认配置（人类可读）
├── config/default_config.json   # 运行时加载（无第三方依赖）
├── maya_agent/
│   ├── bridge/                  # 本地 HTTP 桥（工具 + 远程 Agent + 发现文件）
│   ├── core/                    # Agent 循环、记忆、执行器、Undo、会话、提示词
│   ├── llm/                     # 多厂商 LLM / 视觉适配（OpenAI 兼容 / Anthropic / Gemini / Cursor）
│   ├── tools/                   # 235 个 Maya 工具（建模/UV/绑定/蒙皮/动画/云 3D/文件/开发）
│   ├── ui/                      # Qt 面板（对话 / 模型 / 设置 / 工具 / 帮助）
│   ├── plugin/                  # 菜单、工具架、场景钩子
│   └── utils/                   # 配置、路径、日志、Maya / Qt / 线程兼容
├── resources/
│   ├── prompts/                 # 系统提示词（面板与 MCP 共用）
│   ├── locales/                 # 10 种界面语言
│   └── maya_plugin/             # 自动加载插件模板
├── scripts/
│   ├── maya_mcp.py              # MCP stdio 代理（系统 Python）
│   ├── install_engine.py        # 安装器/bat 统一引擎（mayapy 可跑）
│   ├── install.py               # 挂钩写入 + Install Report
│   ├── install_deps.py          # mayapy 依赖 / vendor_cache / .vendor/<abi>
│   ├── build_vendor_cache.py    # 构建离线 vendor_cache
│   ├── version_utils.py         # 读 VERSION / 同步各处副本
│   ├── sync_version.py / bump_version.py
│   ├── maya_abi.py              # Maya 版本 ↔ cp37/cp39/cp311
│   ├── maya_discover.py         # Maya 版本 / mayapy 统一探测
│   ├── doctor.py                # 安装健康检查（只读）
│   ├── drag_install.py          # 拖入式安装逻辑（含依赖加固）
│   └── test_*.py                # 离线/冒烟测试脚本
├── installer/                   # Inno Setup 商业安装器
│   ├── MayaAgent.iss
│   ├── build.bat
│   └── README.md
├── install.bat / uninstall.bat  # 优先 mayapy
├── install_dragdrop.mel         # 拖进视口安装
├── recover_tools_dragdrop.mel   # 工具注册表异常时急救
├── requirements.txt             # Maya 内依赖（httpx / PyYAML / matplotlib）
├── requirements-mcp.txt         # IDE MCP 代理依赖（系统 Python）
├── vendor_cache/                # 预置离线依赖（构建生成，已 gitignore）
├── dist/                        # Setup.exe 输出
└── .vendor/                     # 运行时 ABI 依赖树（自动生成，已 gitignore）

测试与诊断

故障排查

版本管理

唯一源文件：项目根目录 VERSION（当前内容即发布版本号）。

运行时 UI / About / Bridge / .mod 挂钩均读取该文件（经 maya_agent.__version__ 或 scripts/version_utils.py）。发版时同步副本：

# 只同步（改完 VERSION 之后）
python scripts/sync_version.py

# 或直接升版并同步
python scripts/bump_version.py 1.5.7
python scripts/bump_version.py --patch

会更新：pyproject.toml、installer/MayaAgent.iss、config/default_config.*、README / installer 文档中的 Setup 文件名。
installer\build.bat 打包前会自动执行 sync_version.py。

许可

MIT