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/api，opencode 的 settings.json 里只维护一份凭据就行。
先去控制台建 Key：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=opencode_img2threejs
建完在 API Keys 页面复制：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=opencode_img2threejs
注意：Key 只显示一次，复制后先存到密码管理器，别直接贴进会提交到 git 的文件里。
2.3 模型选择的关键点
img2threejs 的核心依赖是 Agent 的视觉能力——它要「看」参考图和渲染图的对比图来打分。所以你必须选一个具备视觉能力的多模态模型，比如 MiMmo-2.5、Kimi-3 这类。纯文本模型跑这个 Skill 会在第一步就卡住，因为它读不了图。
3. 可复制配置：opencode settings.json 骨架
opencode 的配置文件放在用户配置目录下，Windows 是%USERPROFILE%\.config\opencode\settings.json，macOS / 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，按文档给的写 |
apiKey | TaoToken 密钥 | 别带引号外的空格 |
vision | 是否具备视觉能力 | 跑 img2threejs 必须为 true |
globalDir | Skill 扫描目录 | 要和 2.1 的克隆路径一致 |
permissions | 权限策略 | 首次跑建议 ask，确认行为后再放宽 |
如果你更习惯用命令行管理长期编码任务，也可以了解下 Coding Plan 的额度方案：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=opencode_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.ts | TypeScript 模块，可导入任意 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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=opencode_img2threejs
6. 把这条链路固定下来
img2threejs 的价值不在于一次生成多完美，而在于它输出的是可维护、可审查、可动画化的 TypeScript 代码，而不是一个改不动的网格文件。配合 opencode 的 Skill 机制和 TaoToken 的统一通道，整条链路可以固化成：一张图 → 分阶段门控生成 → 浏览器预览 → 截图反馈迭代。
接入文档在这里，遇到 provider 配置细节可以对照：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=opencode_img2threejs
如果你用的是 Claude Code 而不是 opencode，Skill 加载方式略有差异，但 settings 里的 provider 段和模型选择逻辑是相通的，参考这份配置改路径即可：https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=opencode_img2threejs
最后给个实用建议：跑之前先把参考图裁成主体居中、背景干净的正方形，能明显减少隐藏面推断带来的偏差。生成后别急着改代码，先让 Agent 看对比图打分，把规格调对了再动 TypeScript，返工量会小很多。
