mcpField
A
animato

animato

github.com/akillness创意与媒体5349 次安装4 天前更新
代码仓库

关于 animato

Animato 技能通过本地服务和脚本门控，让用户用文本请求为已绑定骨骼的 FBX 或 glTF 角色生成动画。它保存提示词与生成脚本，并在执行前检查脚本；源模型会被导出覆盖。

主要功能

  1. 01通过文本描述请求角色动画
  2. 02检查本地服务与密钥状态
  3. 03执行前静态校验 bpy 脚本
  4. 04保存提示词和生成脚本
  5. 05验证动画导出结果

适用场景

  1. 01为 FBX 角色生成挥手动作
  2. 02以 dry-run 检查生成脚本
  3. 03诊断本地 Animato 服务

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/akillness/jeo-skills --skill animato

安装后在 Claude Code 中输入/animato确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

evals/
evals.json
references/
agent-loop.md
bpy-script-contract.md
example-bpy-script.py
upstream.md
scripts/
animato_agent.py
selftest.py
validate_bpy_script.py

详细介绍

Animato

何时使用此技能

  • 无需打开 Blender，即可根据文本请求为绑定好的 .fbx / .gltf 角色制作动画。
  • 使用密钥（ANIMATO_API_KEY / GEMINI_API_KEY / OPENAI_API_KEY）自动运行动画循环，而不是将提示词复制粘贴到聊天窗口。
  • 在服务器执行 LLM 编写的 bpy 脚本前，对其进行审查或检查。
  • 运行、调试或检查本地 Animato 服务及其 /api/* 端点的运行状况。

如果任务是创建绑定或重定向动作捕捉数据，请改用 Blender；如果是制作实时游戏特效，请改用 game-vfx；如果是要在浏览器中播放最终片段，请改用 threejs-animation、threejs-loaders。

说明

步骤 1：记录一份动画信息

调用前记录：模型文件及其格式、是否已上传、用一句话描述的动作请求、要使用的提供商/模型/密钥，以及源文件是否可以丢弃。生成的脚本会原位覆盖已上传的模型——如果源文件不可替代，请先复制，再上传。.obj 没有骨架，无法制作动画。

步骤 2：确认服务器和密钥
uv run fastapi run main.py   # in the Animato checkout, serves UI + API on :8000
python3 .agent-skills/animato/scripts/animato_agent.py doctor

doctor 会检查服务器是否可访问、密钥是否存在（绝不打印密钥值），以及门禁脚本。使用 ANIMATO_SERVER、ANIMATO_PROVIDER（gemini | openai）、ANIMATO_LLM_ENDPOINT 和 ANIMATO_MODEL 进行配置；参见 references/agent-loop.md。

步骤 3：运行带门禁的循环，而不是直接调用端点
export ANIMATO_API_KEY=...   # free-tier key is enough; one inference per animation
python3 .agent-skills/animato/scripts/animato_agent.py animate \
  --file "./X Bot.fbx" --message "wave hello with the right arm, 2 seconds"

--mode local（默认）会依次执行上传 → /api/prompt → 一次 LLM 调用 → 静态检查 → /api/run，并将提示词和生成的脚本写入 --out-dir（默认 animato-out/），以便将失败结果作为可审查的产物。使用 --dry-run 可在执行前停止；只有在接受 /api/chat 会在门禁运行前执行脚本的情况下，才使用 --mode server。

步骤 4：重新提交提示词前，先阅读门禁输出

脚本被拒绝，意味着请求或模型选择有误，而不是应该重试循环。

python3 .agent-skills/animato/scripts/validate_bpy_script.py animato-out/X-Bot.generated.py \
  --model-path public/upload/X-Bot.fbx

门禁会拒绝过时的 Blender API、缺少关键帧、缺少帧范围、缺少导出、遗漏 export_animations=True / bake_anim=True、格式不匹配，以及 subprocess / os.system / eval 等主机端调用。完整列表见：references/bpy-script-contract.md。

步骤 5：验证动画文件，而不仅仅是 HTTP 状态

/api/run 即使脚本执行失败也会返回 HTTP 200——请根据 ok 分支处理，然后确认 output_url 能够加载并且确实包含片段（gltf.animations / FBX .animations 非空，且每帧都会调用 mixer.update(delta)）。如果片段不正确，请重新发起请求；如果片段有问题，请确定性地删除：

python3 .agent-skills/animato/scripts/animato_agent.py remove --filename X-Bot.fbx --name wave
步骤 6：保持循环可靠

将 /api/run 和 /api/chat 视为本地远程代码执行入口：只在可信机器上使用，未经沙箱保护，绝不要公开。自动运行时，每个动画最多进行一次推理；仅凭门禁通过，绝不能声称动画可用——门禁只做静态检查。

示例

离线验证完整循环（无需密钥或 Blender）
python3 .agent-skills/animato/scripts/selftest.py

使用模拟 Animato 服务器和模拟 LLM 运行六种情况：正常流程、门禁拒绝并阻止执行、--dry-run、/api/chat 模式、缺少密钥导致失败，以及 doctor。

使用兼容 OpenAI 的提供商，为已上传的模型制作动画
ANIMATO_PROVIDER=openai ANIMATO_LLM_ENDPOINT=https://api.example.com/v1 ANIMATO_MODEL=my-model \
python3 .agent-skills/animato/scripts/animato_agent.py animate \
  --filename X-Bot.fbx --message "idle breathing loop, 3 seconds" --dry-run
检查服务器生成的提示词
python3 .agent-skills/animato/scripts/animato_agent.py prompt \
  --filename X-Bot.fbx --message "wave hello" --out prompt.txt

最佳实践

  1. 上传前复制源模型——动画导出会原位替换源模型。
  2. 优先使用 --mode local：在执行前检查脚本，而不是执行后再检查。
  3. 每个动画只进行一次推理；请修正请求或提示词，不要让模型循环运行。
  4. 骨骼名称、坐标轴和单位均以 /api/prompt 输出为准，切勿照搬示例脚本。
  5. 将保存的提示词和生成的脚本放在一起，方便诊断不良结果。
  6. 保持服务器处于本地且可信的环境中；密钥应保存在环境变量中，不得出现在日志或产物里。
  7. 报告成功前，先确认导出的文件能够播放。

参考资料

  • references/agent-loop.md — 端点、模式、环境变量、故障路由。
  • references/bpy-script-contract.md — 门控规则和已移除 API 表。
  • references/example-bpy-script.py — 符合门控要求的脚本结构。
  • references/upstream.md — 来源、要求、安全边界。
  • otdnnc/Animato

评论

支持 Markdown