1. 一张照片变 3D 模型为什么我盯上了 img2threejs先说结论img2threejs 是一个跑在 AI Agent 环境里的 3D 建模 Skill你给它一张参考图它输出一段完全由 Three.js 原语拼装的 TypeScript 代码浏览器打开就能旋转缩放。它适合谁适合已经在用 opencode、Claude Code 这类编程 Agent、又需要快速拿到可交互 3D 展示模型的人。不适合谁不适合想要照片级写实网格、或者想脱离 Agent 单独跑脚本的人。传统路子有三条每条都硌脚。摄影测量要环绕拍几十张单张图直接没戏AI 网格生成吐出来的往往是黑盒文件想改一个倒角都得重新生成手工建模更别提一个产品展示模型够画一整天。img2threejs 换了个思路叫「代码重建」——没有导入的网格没有下载的美术资源包所有东西都是代码可 diff、可版本控制、可直接在浏览器里跑。它的工程特色很鲜明机械活全下沉到纯 Python 标准库脚本验证、门控、规格编写、对比图打包模型 Token 只花在「看图说像不像」这一件事上。生成过程分阶段推进粗模、结构、形体、材质、表面、光照、交互、优化每一步都要 Agent 对比参考图和渲染图打分过了才解锁下一步没过就自我修正。这篇我聚焦一件事在 opencode 里把 img2threejs 接上 TaoToken 的统一 Key/API 通道从 settings.json 骨架写到端到端验证让你跑通一次「一张照片生成 Three.js 可渲染 3D 模型」。配置片段可以直接复制。2. 前置准备Skill 目录、版本基线与 TaoToken 通道2.1 装 Skill 到全局目录img2threejs 以 Skill 形式被 Agent 加载先建全局 skills 目录。Windows 下mkdir %USERPROFILE%\.agents\skills\ cd %USERPROFILE%\.agents\skills\ git clone --branch v1.4.3 --depth 1 https://github.com/img2threejs/img2threejs.gitmacOS / Linux 把%USERPROFILE%换成$HOME即可。为什么锁 v1.4.3因为它是目前唯一的正式治理基线也就是经过完整验证流程、可作为生产依赖的版本。beta 版v1.5.0-beta.1、v1.4.4-beta.2属于预发布别拿来当生产依赖。克隆完打开文件管理器能看到 img2threejs 躺在全局 skills 目录里这一步就对了。2.2 为什么走 TaoToken 统一通道opencode 支持自定义模型提供方但如果你同时用多个模型一个负责视觉判断、一个负责代码生成逐个配 Key、逐个改 baseURL 会很碎。TaoToken 提供统一的 API 通道一个 Key 覆盖多模型baseURL 指向https://taotoken.net/apiopencode 的 settings.json 里只维护一份凭据就行。先去控制台建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopencode_img2threejs建完在 API Keys 页面复制https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopencode_img2threejs注意Key 只显示一次复制后先存到密码管理器别直接贴进会提交到 git 的文件里。2.3 模型选择的关键点img2threejs 的核心依赖是 Agent 的视觉能力——它要「看」参考图和渲染图的对比图来打分。所以你必须选一个具备视觉能力的多模态模型比如 MiMmo-2.5、Kimi-3 这类。纯文本模型跑这个 Skill 会在第一步就卡住因为它读不了图。3. 可复制配置opencode settings.json 骨架opencode 的配置文件放在用户配置目录下Windows 是%USERPROFILE%\.config\opencode\settings.jsonmacOS / Linux 是~/.config/opencode/settings.json。下面是一份可直接改用的骨架重点是 provider 段和模型段。{ provider: { taotoken: { type: openai-compatible, baseURL: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, models: { vlm-primary: { id: 你的多模态模型ID, vision: true, maxTokens: 8192 }, coder-secondary: { id: 你的代码模型ID, vision: false, maxTokens: 16384 } } } }, defaultModel: taotoken/vlm-primary, skills: { globalDir: ~/.agents/skills, enabled: [img2threejs] }, permissions: { fileRead: ask, shellExec: ask } }几个参数说明别填错字段作用常见坑baseURL统一 API 入口结尾不要多加/v1按文档给的写apiKeyTaoToken 密钥别带引号外的空格vision是否具备视觉能力跑 img2threejs 必须为 trueglobalDirSkill 扫描目录要和 2.1 的克隆路径一致permissions权限策略首次跑建议 ask确认行为后再放宽如果你更习惯用命令行管理长期编码任务也可以了解下 Coding Plan 的额度方案https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopencode_img2threejs配置写完后opencode 启动时会读取这份文件。如果 Skill 没被识别八成是globalDir路径写错或者克隆时目录名被改过。4. 端到端验证从 /skills 到浏览器里的 3D 模型4.1 确认 Skill 被加载终端执行opencode进入交互界面后输入/skills回车。列表里应该出现 img2threejs。用方向键选中它回车对话框里会出现/img2threejs前缀说明 Skill 已挂载。4.2 发起第一次生成准备一张测试图比如下载一张跨维智能机器人的产品图存到D:\test\robot.jpg。然后输入提示词/img2threejs 根据 D:\test\robot.jpg 这张图片建立 3D 模型执行过程中如果弹出权限框按回车选 Allow once或右箭头选 Allow always 再回车——它需要读取你指定的图片文件。4.3 切换视觉模型如果你当前默认模型没有视觉能力Agent 会提示读不了图。这时执行/model切到具备视觉能力的多模态模型MiMmo-2.5、Kimi-3 等然后告诉它继续执行。Agent 检测到本地有 Python 后会接着往下跑。有个细节值得知道这个 Skill 不直接读 jpg内部会转成 png 再处理不过 Agent 会自动完成你不用手动干预。4.4 看输出文件执行结束后 Agent 会告诉你模型文件的位置和说明。典型产物长这样文件用途index.html浏览器查看器直接打开即可看 3D 模型createXxx.tsTypeScript 模块可导入任意 Three.js 项目object-sculpt-spec.json完整雕刻规格部件层次、材质、光照assessment.json规格预评估复杂度、解剖结构、质量承诺4.5 起服务看效果进入生成目录两种起服务方式# 方式一node npx serve . # 方式二Python启动更快推荐 python -m http.server 3000浏览器访问http://localhost:3000鼠标拖拽旋转、滚轮缩放、右键平移。以机器人为例模型会被拆成几十个命名部件——躯干、头部、四肢各段、关节杆、地面等材质和光照都在 spec 里定义好了。4.6 迭代修正第一次结果大概率不完美。我实测下来机器人模型出现过腰部 45 度俯仰角双关节杆变成两根杆交叉、杆数量变 4、多余中间圆盘、手臂断开、手指异常等问题。处理方式是把渲染截图发给 Agent让它继续改。中间还踩过一个坑某次用了Object.assign给灯光设置位置在 Edge 里直接失败导致整个脚本崩溃页面一片黑——改成显式赋值就好了。5. 本篇常见错排查Skill 列表里没有 img2threejs。检查settings.json的skills.globalDir是否指向~/.agents/skills以及克隆出来的目录名是否就是img2threejs。改过目录名的话要么改回去要么同步改配置。Agent 说读不了图片。当前模型没有视觉能力。执行/model切到多模态模型再让它继续。这是最高频的一个卡点。Python 脚本报错找不到模块。img2threejs 是纯 Python 3.10 标准库实现零依赖不需要 pip 装任何东西。报模块缺失通常是 Python 版本低于 3.10升级解释器即可。浏览器打开一片黑。先看控制台报错。常见原因是灯光或相机初始化写法在部分浏览器不兼容比如前面提到的Object.assign给灯光设位置。让 Agent 改成显式属性赋值。模型看起来像别的动物。单张图无法揭示隐藏面卧姿、特殊角度的参考图尤其容易跑偏。把渲染截图反馈给 Agent明确说「关节错位」「嘴巴太长」「身体太长」这类具体问题比笼统说「不像」有效得多。端口被占用。python -m http.server 3000换成 3001 或其他空闲端口。想验证模型本身是否正常。除了本地起服务也可以在模型对话里贴渲染截图让模型帮你判断结构合理性https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopencode_img2threejs6. 把这条链路固定下来img2threejs 的价值不在于一次生成多完美而在于它输出的是可维护、可审查、可动画化的 TypeScript 代码而不是一个改不动的网格文件。配合 opencode 的 Skill 机制和 TaoToken 的统一通道整条链路可以固化成一张图 → 分阶段门控生成 → 浏览器预览 → 截图反馈迭代。接入文档在这里遇到 provider 配置细节可以对照https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopencode_img2threejs如果你用的是 Claude Code 而不是 opencodeSkill 加载方式略有差异但 settings 里的 provider 段和模型选择逻辑是相通的参考这份配置改路径即可https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopencode_img2threejs最后给个实用建议跑之前先把参考图裁成主体居中、背景干净的正方形能明显减少隐藏面推断带来的偏差。生成后别急着改代码先让 Agent 看对比图打分把规格调对了再动 TypeScript返工量会小很多。
