diff --git a/assets/hyper3d-rodin/icon.jpg b/assets/hyper3d-rodin/icon.jpg new file mode 100644 index 0000000..797ad67 Binary files /dev/null and b/assets/hyper3d-rodin/icon.jpg differ diff --git a/marketplace.json b/marketplace.json index b988fe5..d701fea 100644 --- a/marketplace.json +++ b/marketplace.json @@ -740,6 +740,38 @@ "visualization" ], "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/obsidian/icon.png" + }, + { + "name": "hyper3d-rodin", + "displayName": "Hyper3D Rodin", + "displayName_i18n": { + "en": "Hyper3D Rodin", + "zh-CN": "Hyper3D Rodin" + }, + "description": "Generate 3D models from text or reference images with Hyper3D Rodin Gen-2.5, split completed models with BANG, and retrieve results.", + "description_i18n": { + "en": "Generate 3D models from text or reference images with Hyper3D Rodin Gen-2.5, split completed models with BANG, and retrieve results.", + "zh-CN": "通过文字或参考图片生成 Hyper3D Rodin Gen-2.5 三维模型,使用 BANG 拆分已完成模型,并获取生成结果。" + }, + "version": "0.1.0", + "author": { + "name": "Deemos", + "url": "https://hyper3d.ai" + }, + "homepage": "https://hyper3d.ai", + "license": "MIT", + "keywords": [ + "hyper3d", + "rodin", + "3d", + "text-to-3d", + "image-to-3d", + "bang", + "mcp" + ], + "source": "./plugins/hyper3d-rodin", + "category": "developer-tools", + "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/hyper3d-rodin/icon.jpg" } ] } diff --git a/plugins/hyper3d-rodin/.mcp.json b/plugins/hyper3d-rodin/.mcp.json new file mode 100644 index 0000000..06704e6 --- /dev/null +++ b/plugins/hyper3d-rodin/.mcp.json @@ -0,0 +1,9 @@ +{ + "mcpServers": { + "hyper3d-rodin": { + "type": "http", + "url": "https://api.hyper3d.com/api/mcp", + "timeoutMs": 60000 + } + } +} diff --git a/plugins/hyper3d-rodin/.zcode-plugin/plugin.json b/plugins/hyper3d-rodin/.zcode-plugin/plugin.json new file mode 100644 index 0000000..700e74d --- /dev/null +++ b/plugins/hyper3d-rodin/.zcode-plugin/plugin.json @@ -0,0 +1,31 @@ +{ + "name": "hyper3d-rodin", + "displayName": "Hyper3D Rodin", + "displayName_i18n": { + "en": "Hyper3D Rodin", + "zh-CN": "Hyper3D Rodin" + }, + "description": "Generate 3D models from text or reference images with Hyper3D Rodin Gen-2.5, split completed models with BANG, and retrieve results.", + "description_i18n": { + "en": "Generate 3D models from text or reference images with Hyper3D Rodin Gen-2.5, split completed models with BANG, and retrieve results.", + "zh-CN": "通过文字或参考图片生成 Hyper3D Rodin Gen-2.5 三维模型,使用 BANG 拆分已完成模型,并获取生成结果。" + }, + "version": "0.1.0", + "author": { + "name": "Deemos", + "url": "https://hyper3d.ai" + }, + "homepage": "https://hyper3d.ai", + "license": "MIT", + "keywords": [ + "hyper3d", + "rodin", + "3d", + "text-to-3d", + "image-to-3d", + "bang", + "mcp" + ], + "skills": "./skills", + "mcpServers": "./.mcp.json" +} diff --git a/plugins/hyper3d-rodin/LICENSE b/plugins/hyper3d-rodin/LICENSE new file mode 100644 index 0000000..d0f4657 --- /dev/null +++ b/plugins/hyper3d-rodin/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Deemos + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/plugins/hyper3d-rodin/README.md b/plugins/hyper3d-rodin/README.md new file mode 100644 index 0000000..0f62071 --- /dev/null +++ b/plugins/hyper3d-rodin/README.md @@ -0,0 +1,107 @@ +# Hyper3D Rodin + +[简体中文](./README_CN.md) + +Generate 3D models from text or reference images with Hyper3D Rodin Gen-2.5, +split completed models into parts with BANG, follow progress, and retrieve +result pages or requested model files in ZCode. + +This plugin contains one remote HTTP MCP declaration and one Skill. A Hyper3D +account is required; generation and BANG consume credits from the personal or +group workspace selected during OAuth authorization. + +## Install and connect + +1. After publication, install and enable **Hyper3D Rodin** in ZCode's plugin + manager. +2. Use ZCode's MCP authentication controls to sign in to Hyper3D in the browser. + Review the requesting client, select the billing workspace, and authorize + access. Select the MCP scope used by your active project; authorization in + one scope does not mean another scope is connected. No API key, password, + cookie, or session token belongs in chat or in + this plugin's configuration. +3. Verify that the Hyper3D tools are available in the session. Tool discovery + alone does not prove that OAuth or authenticated calls work. If the host has + no authorization control or login fails, retain the redacted error for + troubleshooting; do not work around it by pasting credentials into chat. + +The MCP endpoint is `https://api.hyper3d.com/api/mcp`. ZCode namespaces the +server as `plugin:hyper3d-rodin:hyper3d-rodin`. The Skill maps the logical tool +names below to the actual tools exposed by the current session; this plugin +does not define slash commands. + +The service advertises `rodin:generate` for uploads and generation and +`rodin:read` for status and results. OAuth metadata advertises authorization-code +flow with PKCE S256, dynamic client registration, and refresh-token support. +The actual login and refresh flow depends on ZCode's client implementation. +Reconnect to change the authorized account or billing workspace. + +## Use + +- “Use Hyper3D to generate a cartoon astronaut as a GLB model.” +- “Generate a 3D model from this reference image.” +- “Check my Rodin task with generation ID … and show its result page when done.” +- “Split my completed Rodin model with generation ID … into parts using BANG.” +- “Download the completed model into this project's assets directory.” + +The Skill guides text/image submission, spaced status checks, and result +retrieval. Uploads accept 1–5 supported images, each at most 20 MiB. ZCode must +read the actual files, request upload URLs, and perform successful HTTP PUTs +before starting an image-based generation. If uploading is unavailable, the +agent reports that limitation and points to [Hyper3D](https://hyper3d.ai); it +does not silently omit the images. + +| Tool | Purpose | +| --- | --- | +| `rodin_create_uploads` | Obtain temporary upload URLs for reference images | +| `rodin_generate` | Submit a Rodin generation; consumes credits | +| `rodin_generate_bang` | Split an owned, completed Rodin generation; consumes credits | +| `rodin_get_status` | Read a task's status and stage | +| `rodin_wait` | Server-side wait; prefer status checks in ZCode | +| `rodin_get_result` | Retrieve the result page and temporary file URLs | + +The server also advertises `rodin_import_images`, which is for ChatGPT Chat +attachments only. The Skill instructs ZCode not to use it. There are no account +balance or generation-history tools. Available parameters and formats follow +the live tool schemas; current model formats are GLB, USDZ, FBX, OBJ, and STL. + +## Dependencies, permissions, and side effects + +- **Services and network:** ZCode provides the conversational model. Hyper3D + provides the hosted Rodin/BANG service. MCP traffic goes to + `api.hyper3d.com`; browser sign-in and result pages use Hyper3D's web service + at `hyper3d.ai` and the endpoints advertised by OAuth metadata. Image uploads + and requested file downloads also access the storage/CDN hosts in the signed + URLs returned by Hyper3D. These URLs are temporary; avoid printing or sharing them. MCP responses and + upload/download tool cards may retain signed URLs in ZCode history; this + plugin cannot guarantee host-side redaction. Redact them before sharing logs + or screenshots, and use host secret-redaction features when available. +- **Data:** Prompts, selected reference images, generation settings, and task + identifiers are sent to Hyper3D as needed. The plugin does not request a + repository upload. Status/result access is limited to the authorized user's + generations; group billing does not grant access to other members' models. +- **Charges and recovery:** Generation and BANG consume Hyper3D credits and + create remote tasks. The Skill explains the credit use before the first paid + submission and does not generate merely to test a connection. These calls + are not idempotent: after a timeout or connection error, check the known task + or ask the user to inspect Hyper3D Mine before deciding on a new submission. + Insufficient balance or entitlement is reported without silently changing + the workspace or requested settings. +- **Local execution and files:** The package has no local MCP server, bundled + executables, install scripts, commands, or hooks, and requires no additional + Node.js/Python runtime or model API key. ZCode manages installation and OAuth + state. The agent may use host file/network tools or shell commands to inspect + the selected images and upload them. Downloading models writes local files + only when requested by the user. Shell arguments must be safely quoted and + signed URLs must not be exposed in shared output. Importing into Blender, + Unreal, or another DCC is outside this plugin's scope. +- **Results:** Show the permanent `display_url` after completion. Temporary + `files[].url` values are for requested downloads, not user-facing links. + +## License + +The plugin configuration, Skill, and documentation are licensed under the +[MIT License](./LICENSE). The remote MCP service is operated by Deemos; +its server implementation and generated assets are outside this license and +remain subject to Hyper3D's applicable terms. The Hyper3D icon identifies the +service and does not grant trademark rights. diff --git a/plugins/hyper3d-rodin/README_CN.md b/plugins/hyper3d-rodin/README_CN.md new file mode 100644 index 0000000..57370b8 --- /dev/null +++ b/plugins/hyper3d-rodin/README_CN.md @@ -0,0 +1,83 @@ +# Hyper3D Rodin + +[English](./README.md) + +在 ZCode 中使用文字或参考图片生成 Hyper3D Rodin Gen-2.5 三维模型, +使用 BANG 将已完成模型拆分为部件,跟踪进度,并获取结果页面或按需下载模型文件。 + +插件包含一个远程 HTTP MCP 声明和一个 Skill。需要 Hyper3D 账号;生成模型和 +BANG 拆件会消耗 OAuth 授权时选择的个人或团队工作空间额度。 + +## 安装与连接 + +1. 正式发布后,在 ZCode 插件管理器中安装并启用 **Hyper3D Rodin**。 +2. 通过 ZCode 的 MCP 认证入口在浏览器中登录 Hyper3D,核对请求授权的客户端, + 选择计费工作空间并授权。请选择当前项目实际使用的 MCP 作用域;某个作用域授权 + 不代表其他作用域也已连接。不要把 API Key、密码、Cookie 或会话 Token + 放入聊天或本插件配置。 +3. 确认当前会话能发现 Hyper3D 工具。仅能发现工具不代表 OAuth 或授权后的调用 + 已经成功。如果客户端没有授权入口或登录失败,保留脱敏后的错误以便排查, + 不要通过在聊天中粘贴凭据来绕过问题。 + +MCP 地址为 `https://api.hyper3d.com/api/mcp`。ZCode 的服务命名空间为 +`plugin:hyper3d-rodin:hyper3d-rodin`。Skill 会把下文的逻辑工具名对应到 +当前会话实际提供的工具;本插件不定义斜杠命令。 + +服务声明的权限为 `rodin:generate`(上传及生成)和 `rodin:read`(状态及结果)。 +OAuth 元数据声明支持 PKCE S256 授权码流程、动态客户端注册和刷新令牌; +实际登录与刷新行为取决于 ZCode 客户端实现。更换授权账号或计费工作空间需要重新连接。 + +## 使用 + +- 「用 Hyper3D 生成一个卡通宇航员,输出 GLB 模型。」 +- 「根据这张参考图片生成一个三维模型。」 +- 「查询我的 Rodin 任务,生成 ID 为……,完成后给我结果页面。」 +- 「使用 BANG 拆分我已完成的 Rodin 模型,生成 ID 为……。」 +- 「把已完成的模型下载到这个项目的 assets 目录。」 + +Skill 指导文字或图片生成、间隔查询进度和结果获取。参考图支持 1–5 张,每张不超过 +20 MiB,格式以工具支持范围为准。ZCode 必须读取实际文件、申请上传地址并成功完成 +HTTP PUT,再提交图片生成。如果无法上传,Agent 会说明限制并引导前往 +[Hyper3D](https://hyper3d.ai),不会悄悄忽略参考图片。 + +| 工具 | 用途 | +| --- | --- | +| `rodin_create_uploads` | 获取参考图片的临时上传地址 | +| `rodin_generate` | 提交 Rodin 生成任务,消耗额度 | +| `rodin_generate_bang` | 拆分当前授权用户拥有的已完成 Rodin 模型,消耗额度 | +| `rodin_get_status` | 查询任务状态和阶段 | +| `rodin_wait` | 服务端等待;ZCode 优先使用状态查询 | +| `rodin_get_result` | 获取结果页面和临时文件地址 | + +服务还会声明 `rodin_import_images`,但它仅用于 ChatGPT Chat 附件,Skill 明确要求 +ZCode 不调用它。当前没有账户余额或生成历史列表工具。可用参数及格式以实时工具 +Schema 为准;目前模型格式包括 GLB、USDZ、FBX、OBJ 和 STL。 + +## 依赖、权限与副作用 + +- **服务与网络:** 对话模型由 ZCode 提供,Rodin/BANG 在线服务由 Hyper3D 提供。 + MCP 请求发送到 `api.hyper3d.com`;浏览器登录和结果页面使用 `hyper3d.ai` + 及 OAuth 元数据声明的端点。图片上传和按需文件下载还会访问 Hyper3D 返回的 + 签名 URL 中的存储/CDN 域名。这些 URL 是临时地址,应避免打印或分享。 + MCP 响应及上传/下载工具卡片可能在 ZCode 历史中保留签名 URL;本插件无法保证 + 宿主自动脱敏。分享日志或截图前应移除它们;宿主支持时使用其敏感信息脱敏功能。 +- **数据:** 按需将提示词、选定的参考图片、生成参数和任务标识发送到 Hyper3D。 + 插件不要求上传代码仓库。状态和结果仅能访问当前授权用户的生成任务; + 团队计费授权不代表可以访问其他成员的模型。 +- **计费与恢复:** 生成及 BANG 会消耗 Hyper3D 额度并创建远程任务。Skill 会在 + 首次收费提交前说明额度消耗,不会仅为测试连接而生成模型。这些调用不具备幂等性: + 超时或连接异常后应查询已知任务,或让用户在 Hyper3D Mine 检查后再决定是否重新提交。 + 额度不足或缺少权益时会报告错误,不会擅自更换工作空间或修改用户要求的参数。 +- **本地执行与文件:** 插件不包含本地 MCP 服务端、可执行程序、安装脚本、命令组件 + 或 Hooks,也不需要额外的 Node.js/Python 运行时或模型 API Key。ZCode 管理安装及 + OAuth 状态。Agent 可能使用宿主的文件/网络工具或 shell 命令检查选定图片并上传。 + 仅在用户要求下载模型时写入本地文件;shell 参数需安全引用,签名 URL 不应出现在 + 共享输出中。导入 Blender、Unreal 或其他 DCC 不在本插件范围内。 +- **结果:** 任务完成后展示永久 `display_url`。临时 `files[].url` 仅用于用户要求的 + 文件下载,不作为面向用户的结果链接。 + +## 许可证 + +插件配置、Skill 和文档采用 [MIT License](./LICENSE)。远端 MCP 服务由 Deemos +运营;其服务端实现及生成资产不在该许可证范围内,仍受 Hyper3D 适用条款约束。 +Hyper3D 图标用于标识服务,不授予商标权。 diff --git a/plugins/hyper3d-rodin/skills/hyper3d-rodin/SKILL.md b/plugins/hyper3d-rodin/skills/hyper3d-rodin/SKILL.md new file mode 100644 index 0000000..d64e761 --- /dev/null +++ b/plugins/hyper3d-rodin/skills/hyper3d-rodin/SKILL.md @@ -0,0 +1,81 @@ +--- +name: hyper3d-rodin +description: Generate Hyper3D Rodin Gen-2.5 models from text or images, split completed models with BANG, track progress, and retrieve result pages or requested model files. +--- + +# Hyper3D Rodin + +Use the tools discovered from the `hyper3d-rodin` MCP server in ZCode. Match +logical names below to the actual session tools; do not construct tool prefixes. +Use live tool descriptions and schemas for parameters, limits, and defaults. +Leave optional settings unset unless needed for the user's request. For highly +reflective reference images, consider recommending `texture_delight`. + +Connect through ZCode's MCP OAuth flow. If authorization is missing, use the +host's login/reconnect flow; never request credentials in chat. Billing uses +the workspace selected during OAuth. Generation and BANG consume credits: +explain this before the first paid submission and submit only for a requested +generation or split. Connection tests and status checks do not authorize one. + +## Generate and retrieve + +1. For image input, complete the upload workflow below first. Call + `rodin_generate` once with the user's prompt, uploaded references, or both. + For image-only generation, omit `prompt` rather than sending an empty string. +2. Save the returned `generation_id`. Monitor it with `rodin_get_status`, + leaving a reasonable interval between checks rather than busy-polling. + Keep the user informed; stage counts are not percentages or time estimates. +3. A monitoring timeout does not mean generation failed. Check the same ID. + If reads keep failing, report the last known state and ID. On a failed task, + report the error; do not automatically generate again or fetch its results. +4. On completion, call `rodin_get_result` and present its permanent + `display_url`. Use temporary file URLs only for user-requested downloads. + Select the requested model files and any required textures or sidecars, + then return the downloaded local artifacts. + +## Reference images + +Use actual files from the user's paths or attachments. Do not use +`rodin_import_images` in ZCode; that tool is for ChatGPT Chat attachments. + +1. Inspect the files and check them against the live upload schema. Derive + MIME types and byte sizes from the actual files. +2. Call `rodin_create_uploads`. PUT each matching file to its returned + `upload_url`, using the supplied method and headers before `expires_at`. + Confirm every upload succeeds before submitting generation. +3. Pass the returned `upload_id` values as `reference_upload_ids` in the + original image order. These IDs are consumed by a successful submission; + prepare fresh uploads for a new generation, never to retry an uncertain one. + +If the host requires network permission for PUT, use its permission flow. +If uploading remains unavailable, report the limitation and direct the user +to https://hyper3d.ai. Do not silently omit images or switch to text-only. + +## BANG part splitting + +Use a completed Rodin generation owned by the authorized user. Pass its +`generation_id` as `asset_id` to `rodin_generate_bang`, not a file URL or upload +ID. Arbitrary local model uploads are not supported by this workflow. + +Supply `instruction` when the user names parts to separate; otherwise leave it +unset for automatic planning. Treat `strength` as guidance, not a guaranteed +part count. Leave other options to the live schema and the user's request. + +Submit once, save the new `generation_id`, and follow the same status/result +workflow as generation. + +## Recovery and handling + +- Generation and BANG are not idempotent. Never automatically retry a paid + submission after a timeout or connection error. Query the known ID; if none + was returned, ask the user to inspect Hyper3D Mine before submitting again. +- Report insufficient-credit or entitlement errors without changing the + billing workspace or downgrading requested settings. Reconnect through OAuth + to change accounts or workspaces. Do not infer balance or price from this MCP. +- Read only the authorized user's tasks; group billing does not grant access + to other members' models. +- Do not echo signed URLs or sensitive headers. They may remain in host tool + history, so exclude them from shared logs and use host redaction when available. + Safely quote shell arguments when uploading or downloading files. +- This Skill covers generation and retrieval; DCC integration requires its own + tools or workflow.