mcpField
O
octocode-mannequin

octocode-mannequin

github.com/bgauryy创意与媒体9569 次安装9 周前更新
代码仓库

关于 octocode-mannequin

用于创建和验证人形角色关键帧姿势与动画的技能，采用解剖学命名且受关节活动范围约束的骨架。包含 Node 命令行工具、Three.js 查看器，以及供 Agent 实时驱动的 WebMCP 控制。

主要功能

  1. 01查看骨架、关节与动作方案
  2. 02编写并验证受约束姿势
  3. 03验证动画帧序列
  4. 04生成并交互使用 Three.js 查看器
  5. 05通过 WebMCP 工具驱动骨架

适用场景

  1. 01制作受约束的人形姿势
  2. 02检查关节动作是否被限制
  3. 03预览关键帧动画
  4. 04通过 Agent 工具调用移动骨架

MCP 相关

查看器提供 11 个 WebMCP 工具供 Agent 实时控制，包括 reach 和 look_at。Agent 可发现并调用工具，再验证姿势结果。

安装

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

$npx skills add https://github.com/bgauryy/octocode --skill octocode-mannequin

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

包含的文件

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

README.md
assets/
backflip.json
dance.json
idle.json
run-cycle.json
viewer.template.html
references/
anatomy-scheme.md
joint-constraints.md
movement-protocol.md
references.md
rom-table.md
viewer-guide.md
webmcp-agent.md
scripts/
skeleton.mjs

详细介绍

Octocode Mannequin

按解剖学命名的 22 骨骼人形骨架（手臂自然下垂、中线两侧镜像），以及一套运动协议，可将每个关节限制在真实活动范围内；另有根节点 6 自由度通道（平移／俯仰／偏航／翻滚），用于移动、转向、跳跃和后空翻 — 提供 Node CLI、自包含的 Three.js 查看器（贴地、平滑的 Catmull-Rom 动画），以及由 Agent 实时驱动的 WebMCP 工具。流程：SCHEME → COMMAND → CLAMP+FK → RENDER → DRIVE。

硬性规则

  1. scripts/skeleton.mjs 是骨骼／关节／ROM／动作的唯一事实来源；参考文档和查看器均以此为准。查看器会重新实现限幅／sideSign／FK 数学运算 — 任何更改都必须同时修改这两个文件，并重新验证（它们必须保持一致）。
  2. 动作命令必须使用适用于相应关节的解剖学名称，不能使用带符号的原始角度，也不能使用关节允许列表之外的动作 — 编写命令前请先阅读 references/movement-protocol.md；CLI 和工具会拒绝此类命令。
  3. ROM 数值是骨架的默认值，并非医学事实 — 引用限值前请先阅读 references/rom-table.md。

操作门槛

写入查看器文件（viewer --out <file>.html）会覆盖指定路径；由 Agent 驱动需要在新端口上启动一个全新的非无头 Chrome：首次写入或启动浏览器前，请确认输出路径并征得用户同意。

工作流

  1. 先运行 node scripts/skeleton.mjs scheme，检查骨骼以及关节的 DOF／ROM／动作；要查看层级结构，请阅读 references/anatomy-scheme.md；要了解约束模型，请阅读 references/joint-constraints.md；要查看精确角度，请阅读 references/rom-table.md。
  2. 按照 references/movement-protocol.md 编写姿势命令，运行 node scripts/skeleton.mjs pose --cmd '...'，查看 warnings／clamped；然后运行 skeleton.mjs sequence --file frames.json 验证动画。
  3. 要渲染，请运行 node scripts/skeleton.mjs viewer --out <file>.html [--pose pose.json]，打开文件，拖动滑块，或在控制台中调用 window.applyPose／window.playSequence — 可用动画位于 assets/（run-cycle.json、backflip.json、dance.json、idle.json，用于呈现呼吸／摇摆）；要了解查看器的运作机制，请阅读 references/viewer-guide.md。
  4. 要实时驱动 Agent，请加载 references/webmcp-agent.md，并通过 CDP 提供查看器的 WebMCP 工具 — 共 11 个工具，包括任务空间 reach（将手／脚放置在世界坐标中的某一点）和 look_at；get_scheme.guide 规定了坐标系／单位约定。发现、调用后，通过 get_pose 或截图进行验证。

满足以下任一情况时停止：通过 get_pose 或截图验证了姿势；clamped:true 表示关节已达到 ROM 限值（这就是答案 — 不要超出限值）；某个动作因不适用于该关节而遭拒（使用报告的允许列表重试，绝不要使用原始角度）；reach 返回 reached:false 并附带残余距离（目标超出范围 — 重新设定目标，不要原样再次调用）；工具发现返回 WEBMCP_NO_TOOLS 或工具数量少于 11 个（改用通过 Runtime.evaluate 调用 window.applyPose）；截图为空白（Chrome 处于无头模式 — 重新以非无头模式启动）；或请求需要物理模拟、IK 脚部锁定或 mocap（超出范围，请明确说明）。

不适用此技能的场景

通用 3D 场景设置，或物理／布娃娃模拟、IK 脚部锁定、平衡、碰撞或 mocap（BVH/glTF）导入。动作采用关键帧运动学 — 后空翻由人工编排，而非模拟生成；有关选择此范围的原因，请阅读 references/references.md。

渐进式参考

参考文件适用场景
references/anatomy-scheme.md构建／说明骨骼层级
references/joint-constraints.md自由度／约束模型，以及各关节经过验证的旋转方向
references/rom-table.md各动作的精确角度限制
references/movement-protocol.md编写／验证姿势命令
references/viewer-guide.md生成／驱动 Three.js 查看器
references/webmcp-agent.md通过 WebMCP + CDP 驱动人偶的 Agent
references/references.md来源／设计选择的原因

脚本

  • 运行 node scripts/skeleton.mjs 可使用 scheme / pose / sequence / viewer 子命令（--help）；无需安装 npm。WebMCP CDP 机制交由 octocode-chrome-devtools 技能处理。

评论

支持 Markdown