AI DAILY / 2026-09-11

3dviz-pro-max:把创意转成 Three.js / Blender 场景的代理技能

viettranx/3dviz-pro-max

AI 编程实践GitHub · 2026-09-10

全文中文翻译 · AI 生成，仅供学习交流

viettranx/3dviz-pro-max

一个独立的智能体技能（skill），用于创意三维可视化：塑造世界、为它建立规则、让它可交互，并检查屏幕上实际呈现的内容。它内置一套十步工作流、一个可搜索的配方（recipes）与可复用知识目录、可直接运行的 Three.js 模板与套件（kits），以及一个截图辅助程序，使智能体能够去检查它渲染出来的帧，而不是凭空描述它们。事实陈述需要引用来源；动画装饰并不会因为在动就变成仿真。

先从一句话开始：用 3dviz-pro-max 搭建一座我可以走进去探索的奇幻小村。选定一个鲜明的艺术风格，加入几种会动的生物，然后检查最终结果。

你不必先选渲染器，也不用填好规格说明。智能体应直接复用现有项目栈，自行选择合适的表示方式，并依据观察到的结果来迭代场景。

它今天画出的东西

运行帧是在真实 GPU 上从该技能自带的套件、绑定（rigs）与配方中抓取得到的，共二十一张，宿主、等级（tiers）与哈希值都陈列在 showcase gallery（展示画廊）中。

整座岛屿在黄昏时分，从主摄像机看去的景象。

夜晚：灯笼的实用光（practical lights）是唯一的 key light（主光源）。

同一岛屿以桌面模型视角呈现，22° 镜头。

T3 等级的木屋，由 Blender 烘焙（bake）出的主角资产。

石桥横跨流动的水面。

一对 24/16 齿的直齿轮副，模数 10 mm，传动比 3:2。

村庄的帧来自已退役的试点版本（译注：pilot 指早期试验性版本，下同），跨混合等级；套件的帧则使用蓝图验证测试平台（blueprint proof harness）在标注的等级截取。所有帧均未裁剪或后期修饰，并且没有任何帧声称拥有其记录中标注为缺失的等级。

发布内容

截至 2026-09-10，依据 catalog-summary.json 与下文文档：计数说明（recipes）覆盖全部 24 个已注册方向，每个至少 6 条（knowledge records）18 个已填入的知识家族；其中 69 条带有作者给定的数值默认（kit blueprints）记录 + 模块 + 四张实机抓取，由 SHA-256 复验（style profiles）33 条带数值默认的外观档案，含五种命名风格（directions）见下方主题表（sources / evidence）事件 / 公开证据归档（example studies）五章，每章均可运行（examples）（showcase frames）无头 Chromium、GPU、1920×1080（gallery）（retrieval cases）通过的已知意图（known-intent）用例该落地页（landing page）在构建时从 skills/、docs/、evals/ 与 evidence/ 重新计算以上所有数字，因此任何数字都不会脱离它背后的数据。

24 个方向及其作者主题

| 方向 | 作者主题 |
| --- | --- |
| 环境（Environments） | 奇幻村庄、地形岛屿、历史证据分层；洞穴网络、夜市、漂浮群岛；灌溉预算、博物馆路线与分支故事书 |
| 角色与动作艺术（Characters and motion art） | 木偶表演、生物巡游、丝带雕塑；带翼飞行、表情/注视绑定、次级运动链；分支故事书场景 |
| 产品与装配（Products and assemblies） | 音箱零件、折叠灯、摄影机绑定；自行车传动比、注塑斜度、平板包装装配 |
| 建筑与室内（Architecture and interiors） | 房屋剖面、家具布局、服务层；楼梯几何、净空研究、日照/遮阴；施工顺序回放、博物馆路线与房间模式 |
| 运营与物流（Operations and logistics） | 包裹分拣、拣货路径、码头调度；车间作业回放、AGV 调度、托盘装载；封闭车道交通与施工排序 |
| 解剖学（Anatomy） | 心脏剖面、膝盖分层、骨骼层级；臂丛神经走向、肝门静脉系统、椎骨序列；牙齿运动与已提供的脑部图谱 |
| 生理与生物力学（Physiology and biomechanics） | 肌节、通气时相、血管阻力；心瓣时相、肌杠杆、经典毛细血管交换；动铰链下颌图示 |
| 分子与材料（Molecules and materials） | 分子几何、晶胞、氢键；蛋白质二级结构、手性、晶体滑移面；已沉积的结合位点与轨道等值面 |
| 立体几何（Solid geometry） | 圆锥曲线、折纸展开图、回转体；凸包、Delaunay 单元、Minkowski 净空 |
| 线性代数（Linear algebra） | 基映射、行列式/体积、叉积；特征向量、SVD、正交投影；单量子比特 Bloch 球、双量子比特 Bell 关联、注意力聚合与小网络激活 |
| 微积分与场论（Calculus and fields） | 方向导数、二重积分、散度/通量；场积分、旋度/环量、Hessian 临界点；有限 Fourier 综合、复数互易映射、Mandelbrot 与二次 Julia 逃逸轨道、线性相图；捕食者-被捕食者相时间与损失切片 |
| 概率与统计（Probability and statistics） | 二项试验、正态密度、抽样均值；协方差椭球、Markov 链、Monte Carlo 体积 |
| 拓扑与对称（Topology and symmetry） | Möbius 带、环面胞元、正方形对称；三叶结图、基于公差的对称、网格可定向性；Riemann 球面互易映射 |
| 逻辑与电路（Logic and circuits） | 布尔门、全加器、有限状态机；关键路径、建立/保持时序、流水线吞吐；有界自然演绎、SAT 反例与线性算术 SMT |
| 算法与数据结构（Algorithms and data structures） | BFS、Dijkstra、稳定的归并排序；二叉堆、递归栈、并查集/MST；KMP 首次匹配 DFA |
| 旋转拼图（Twisty puzzles） | 面旋转、直接操作、置换循环；换位子、魔方不变量、宽幅旋转 |
| 空间拼图（Spatial puzzles） | 体素拼装、滑块、分层迷宫；河内塔界、精确覆盖拼装、鲁班锁拆解 |
| 刚体力学（Rigid mechanics） | 单摆、抛体/接触、齿轮运动学；陀螺进动、滚动惯性、碰撞动量 |
| 软体/流体/热学模型（Soft/fluid/thermal models） | 热扩散、喷嘴连续性、静水压；质点弹簧布料、CFD 场回放、浮力平衡 |
| 波动、光学与场（Waves, optics and fields） | 驻波、折射、点电荷场；偏振、干涉/衍射、电流环场；有限 Fourier 综合、首次反射与刚体房间模态声学、地震平面波、量子比特态与轨道等值面 |
| 机器人与控制（Robotics and control） | 正运动学、逆运动学、里程计；工作空间奇异点、轨迹时序、关节 PID |
| 地球与环境（Earth and environment） | 等高线、四季、发散山脊；地图投影、流域累积、预报回放；捕食者-被捕食者动力学、根区灌溉与各向同性地震平面波 |
| 天文学与空间（Astronomy and space） | Kepler 轨道、月相、视差；轨道坐标系/根数、日食阴影锥 |
| 抽象系统（Abstract systems） | 智能体运行框架、服务图、嵌入投影；复制日志、构建依赖、对账循环；加权 P/T 网、等待死锁、RAG 出处、注意力、神经网络激活、损失切片、Julia 集与 Bell 关联 |同一配方可能挂在多个方向下。覆盖缺口在手册对比（handbook comparison）、覆盖核算（coverage accounting）与路线图（roadmap）中追踪。

工作原理

graph LR
    A[意图与<br/>视觉方向] --> B[推演<br/>物体]
    B --> C[路线：复用套件 /<br/>改造 / 创作 / 查证]
    C --> D[搭建<br/>第一版视图]
    D --> E[运行并抓取<br/>真实帧]
    E --> F[依据主体与证据<br/>迭代]
    F --> G[报告实际构建<br/>与观察结果]
    F -.-> C

工作流，而非说教。

SKILL.md 中的十步

意图、物体推演、表示的接地、构建路线、质量目标与工具发现、第一版视图、有意义的行为、运行与检查、迭代、诚实汇报。小幅编辑只走相关步骤。

创意方向先于模板

剪影、比例、部件、连接与行为先定下来；套件用于加速合适的工作，其 T0–T4 流水线标签不限制艺术质量或事实保真度。

具体起步数值

69 条知识记录带有作者给定的默认值，风格档案（style profile）、氛围灯光绑定、套件蓝图、主角细节阶梯、相机与时段记录，每条都声明调色板、天空、雾、灯光绑定、色调映射与曝光、相机、材质、运动与后期。21 条配方带有数值默认与计算好的期望值。这些都是候选改造起点，而非强制设置。

可运行的起步点

templates/ 提供一份 Vite + Three.js 脚手架，包含色彩管理（color management）、色调映射（tone mapping）与查看器契约（viewer contract），五个绑定（环绕相机、太阳、夜间灯笼、棚拍、后期栈）、三份产物文档模板、两份检查清单，以及由 22 个已验证蓝图组成的套件库。

帧，而非承诺

scripts/capture.py 驱动一个已构建的场景走遍其命名视图并触发点击，随后写出 PNG 与控制台日志。行为始终绑定到权威状态；事实陈述在建模前先做调研，并与渲染结果交叉核对。

该技能提供指引、经过挑选的数据与起步文件；你的智能体则提供创建、运行并检查产物所需的工具。Python 辅助程序用于检索目录并驱动一个已在浏览器中构建好的场景；它们本身不渲染也不评判场景，截图功能依赖可选安装的 Playwright。

安装

规范的技能是整个 skills/3dviz-pro-max/ 文件夹，必须整体复制，绝不要只复制 SKILL.md。

Claude Code 以两种方式读取它；选其一，否则智能体可能加载的是旧副本。

# Skill 文件夹（个人或项目级），把你正在编辑的检出做一个符号链接
ln -s "$(pwd)/skills/3dviz-pro-max" ~/.claude/skills/3dviz-pro-max

# 或者将仓库根目录作为插件加载，既可来自检出，也可来自打包好的 ZIP
claude --plugin-dir /path/to/3dviz-pro-max
claude --plugin-dir 3dviz-pro-max-0.1.0-plugin.zip

插件形式的技能带有命名空间，因此菜单项呈现为 /3dviz-pro-max:3dviz-pro-max；文件夹路径则写作 /3dviz-pro-max。市场清单列出的就是仓库本身：

/plugin marketplace add viettranx/3dviz-pro-max
/plugin install 3dviz-pro-max@3dviz-pro-max

该路径要求仓库先发布，并且会克隆整个仓库，包括证据与展示媒体；它尚未经过测试（见下文）。

Codex 是首个评估目标：把同一文件夹安装到你所用 Codex 版本认可的技能位置，确认它出现在会话可用的技能列表里，并在首条提示中显式调用它。

手工技能文件夹路径，逐步操作

克隆仓库：

git clone https://github.com/viettranx/3dviz-pro-max.git

切到你想要尝试的修订版本。

定位你的智能体文档化的技能目录（项目级只对单个仓库生效，机器级为 ~/.claude/skills/）。

把整个 3dviz-pro-max 文件夹复制进去。不要只复制 SKILL.md。

刷新技能发现机制或开启新会话。

运行识别提示：

Find the installed 3dviz-pro-max skill. Tell me which local entrypoint you loaded and which pilot recipe fits a fantasy village. Do not generate the scene yet.

预期布局：

<your-agent-skill-directory>/
└── 3dviz-pro-max/
    ├── SKILL.md
    └── ... accompanying data and references

屏幕截图是可选的，并且未随包附带，运行 pip install playwright，再执行 playwright install chromium；若不安装，capture.py 会以退出码 3 退出，智能体必须报告未观察到任何帧。推荐（但非必需）使用 Blender 4.2 LTS 或更高版本：没有它，所有脚本仍可运行，但套件最高止步于 T2。完整细节、更新/卸载以及故障排查表见 installation 文档。

据实观察：2026-09-09 在 macOS 上用 Claude Code 2.1.265 时，claude plugin validate --strict 对两个清单均通过，并且一个无头会话通过 --plugin-dir 分别从检出与打包 ZIP 都成功加载了该技能。市场安装/更新/卸载、个人文件夹路径、Codex 应用安装以及 Claude 应用上传路径均未经测试，也未声称为已上架的公开市场条目。以上都不证明能够渲染，请跑一条场景提示并检查帧。完整状态见 compatibility。

运行示例

examples/ 收录 37 个可直接寻址的英文示例研究，分为五章，解剖与生理、数学、物理与机械、精造世界与道具、灯光研究。每个文件夹都附带生成提示、实际在产物中反映出的技能规则、来源、控件与限制。

cd examples
pnpm install
pnpm dev
# open /<id>/，例如 http://localhost:4180/heart/

落地页 site/ 构建项目的一页式站点：37 个示例研究作为演示卡片，带悬停预览与打开可运行示例的弹窗，上方的计数在构建时从仓库读取，"一句话如何变成一个场景"的循环，以及从 docs/installation.md 读取的安装说明。它在 /examples/<id>/ 提供已构建的示例。

pnpm --dir examples install --frozen-lockfile
bash site/scripts/bundle-examples.sh   # 将 examples/ 打包进 site/public/examples/
pnpm --dir site install --frozen-lockfile
pnpm --dir site build    # build-data → tsc --noEmit → vite build

该页面已上线 3dviz.dev（Cloudflare Pages；解剖几何由 R2 提供）。构建步骤、字节预算、测量得到的体积与注意事项见 docs/site.md。

仓库地图

skills/3dviz-pro-max/   规范技能：SKILL.md、数据、参考资料、模板、套件、脚本
examples/               37 个可运行的 Three.js 研究 + 共享运行时
site/                   React + Vite 落地页（构建时读取仓库）
docs/                   安装、兼容性、覆盖、路线图、示例与展示
evals/                  受控的技能行为评估与计分卡
evidence/               公开证据策略、数据集变更日志、退役的试点产物
schemas/                记录与清单的 JSON schema
scripts/                校验、索引构建、文档/检索检查、打包
tests/                  Python 单元测试

诚实的边界

配方描述如何建模并校验一个主体；它们并不意味着每个配方都已被渲染过。解剖学仍需经过核验的几何，理想化的运动学不同于接触动力学。

知识记录是经过来源核对、编辑审核的撰写指引，而非运行时观察。为 Blender/Three.js 的知识批次，没有运行 Blender 导出、解码器、求解器、浏览器或渲染器。

22 个套件蓝图中，T2（程序化纹理与顶点烘焙遮挡）在 18 个上得到验证，4 个例外说明了原因；T3 是两份 Blender 烘焙（timber-cottage-t3.glb、watermill-t3.glb）；T4 未发布。

hero-tier.py 在缺少 Blender 时如实报告其缺席，而不是伪造一个等级。

受控的前后对比运行中，四个带技能轮次的得分为 19 → 23 → 23 → 25（满分 30），基线为 21。方向是对的，幅度却很小；在每条件 n=1 的情况下，这不构成"该技能能做出更好场景"的证明。

提示画廊中的建议不是经过认证的产物。一次失败或被跳过的检查是有用的信息，必须保持可见。

贡献

贡献应带来有用的知识、清晰的来源与可复现的观察。创意选择需要理由，事实陈述需要证据。请先阅读 CONTRIBUTING.md 与数据贡献指南，然后在仓库根目录运行下列门禁：

python3 scripts/validate.py
python3 scripts/build-index.py --check
python3 scripts/check-docs.py
python3 scripts/check-retrieval.py
python3 -m unittest discover -s tests
python3 scripts/package.py

安全敏感的报告遵循 SECURITY.md。另见变更日志、公开证据策略与路线图。

许可证与致谢

随包附带的字体（Outfit、JetBrains Mono）采用 SIL Open Font License 1.1；详见 site/public/fonts/OFL.txt。

Harness Village 录像（docs/demos/harness-village.gif 以及 site/public/media/origin/ 下的转码副本）由作者从本技能出现之前的一个项目提供。其再分发权利尚待确认；它的存在并不构成对其中所展示资产的概括性许可。详见