3dviz Pro Max

这是什么？适合谁？

3dviz Pro Max（官网 3dviz.dev，MIT，three.js 0.180）是一个面向编码 Agent 的创意 3D 可视化技能包（Agent Skill）：你给它一句话——

Use 3dviz-pro-max to build a small fantasy village I can explore. Choose a distinctive art direction, add a few moving creatures, and inspect the result.

Agent 会按 SKILL.md 定义的十步工作流走完：意图与视觉方向 → 对象推理 → 表示方式落地 → 构建路由（复用 kit / 改编 / 原创 / 外部素材）→ 首视图 → 有意义的行为 → 运行并截帧检查 → 按主题与证据精修 → 诚实报告”建了什么 vs 观察到什么”。核心哲学是 “Frames, not assurances”——配了 scripts/capture.py 让 Agent 真实截取渲染帧自查，而不是口头描述”我做好了”。

数据面很厚：223 条 recipe（覆盖 24 个方向）、440 条知识记录（18 个知识族，69 条带作者数值 defaults）、22 个经验证的 kit 蓝图、37 个 style profile、37 个可运行 example study、451 个来源与 3,599 条证据事件（公开 evidence archive）。官网的每个数字都是从仓库数据构建时重新计算的，“数字不可能和它背后的数据漂移”。

适合谁：用 Claude Code / Codex 做 3D 内容、教学可视化、产品展示场景的开发者与创作者；想研究”怎么把领域知识结构化成 Agent 可检索技能”的 Skill 工程师。

不适合谁：不会用编码 Agent 的纯设计师（它不是 Blender 插件）；期待渲染一条龙（它提供知识/模板/校验，渲染靠你的 Agent 与其工具链）。

使用前提：Claude Code 或 Codex 环境；跑 examples 需 pnpm；截帧检查需 pip install playwright（可选）；Blender 4.2 LTS+（可选，缺它 kit 封顶 T2）。

准备工作

1. 环境：编码 Agent（Claude Code 或 Codex）；Node.js/pnpm（跑 examples）；Python 3（辅助脚本）；可选 Playwright（截帧）、Blender 4.2 LTS+（T3 以上资产烘焙）
2. 获取：git clone https://github.com/viettranx/3dviz-pro-max.git
3. 成本：MIT 开源免费；第三方素材有各自许可（BodyParts3D 解剖网格 CC BY-SA 2.1 JP、捆绑字体 OFL 1.1、Harness Village 录像授权待确认）
4. 时间：安装 5-10 分钟；跑通第一个 examples study 10 分钟；用一句话生成自己的场景 30 分钟起
5. 前置知识：会用命令行与你的编码 Agent；懂 Three.js 有助于改模板，不懂也能让 Agent 生成
6. 替代方案：让 Agent 裸写 Three.js（无知识库、无截帧自查）；商业 3D 生成服务（SaaS 黑盒）

快速上手（3 步）

第一步：安装技能（二选一）

Claude Code 插件方式：

# 目录符号链接（适合自己在编辑的 checkout）
ln -s "$(pwd)/skills/3dviz-pro-max" ~/.claude/skills/3dviz-pro-max

# 或把仓库根作为插件加载
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。也可走 marketplace（/plugin marketplace add viettranx/3dviz-pro-max）——该路径官方标注 untested。

Codex 方式：把整个 skills/3dviz-pro-max/ 文件夹复制进你装的 Codex 版本认可的 skill 目录，刷新技能发现，在首个 prompt 里显式点名。

⚠️ 规范要点：技能的载体是整个 skills/3dviz-pro-max/ 文件夹（SKILL.md + data + references + templates + kits + scripts），绝不能只拷 SKILL.md 一个文件。

预期产出：Agent 能在技能列表里发现 3dviz-pro-max。

第二步：跑 37 个自带 examples 之一

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

examples 分五章：解剖与生理、数学、物理与机构、工艺世界与道具、光照研究。每个 study 自带生成 prompt、实际体现的技能规则、来源、控制项与限制说明。

预期产出：浏览器里看到可交互的 Three.js study（真实 GPU 渲染，非视频）。

第三步：一句话生成你的场景并自查

在装好技能的 Agent 里发出 README 的入门 prompt（上文”build a small fantasy village…”那句），然后检查 Agent 是否走了”截帧自查”环节。想要截帧能力：

pip install playwright
playwright install chromium

没有 Playwright 时 capture.py 以退出码 3 退出，Agent 必须如实报告”没有观察到任何帧”——这是该技能”诚实优先”设计的一部分。

预期产出：一个可打开的 3D 场景 + Agent 对”实际渲染结果 vs 声称”的报告。

常见踩坑（症状 → 原因 → 解决）

1. 只拷了 SKILL.md，Agent 找不到 recipe/知识库。症状：Agent 说技能存在但行为退化成裸写。原因：数据契约（catalog、知识记录、kit 蓝图）都在同文件夹的 data/ 里。解决：完整复制 skills/3dviz-pro-max/ 整个目录，README 加粗强调 “never SKILL.md alone”。
2. 以为 22 个 kit 都是 T4 品质。症状：对产出细节失望。原因：官方诚实分级——T2 在 18 个 kit 上验证（4 个例外有说明），T3 只有 2 个 Blender 烘焙（timber-cottage / watermill），T4 哪都没实现；hero-tier.py 在缺 Blender 时会如实报告而不是假装达标。解决：按 T0-T4 分级预期产出质量，想要 T3 就装 Blender 4.2 LTS。
3. 截帧环节直接被跳过。症状：Agent 只描述不检查。原因：没装 Playwright。解决：pip install playwright && playwright install chromium；装不了就让 Agent 明确报告”未观察到帧”，别让它含糊带过。
4. 把 knowledge records 当运行时观测。原因：README 明确知识记录是”source-checked, editorially reviewed authoring guidance — not runtime observations”，Blender/Three.js 知识批次没有跑过任何渲染器。解决：把知识当候选默认值（README：Candidates to adapt, not mandatory settings）。
5. 以为 223 条 recipe 都渲染验证过。原因：README 的 Honest limits 一节写明 “Recipes describe how to model and verify a subject; they do not imply that every recipe has been rendered”。解决：渲染验证以 21 张 showcase 帧（headless Chromium + GPU，1920×1080，带 host/tiers/hashes）与 kit 的”四次真实截帧”为准。
6. Marketplace 安装不生效。原因：该路径需要仓库先发布，且官方标注 untested。解决：优先用 --plugin-dir（本地 checkout 或打包 ZIP）或 skill 文件夹方式；2026-09-09 在 Claude Code 2.1.265/macOS 上验证通过的是这两种。

初级用法

• 从 examples 找近邻再改：37 个 study 覆盖五个领域，先找到与你目标最像的，把它的生成 prompt 抄来改一两处——比从零描述快得多。
• 用 prompt gallery 起手：docs/prompt-gallery.md 里有现成场景 prompt 模板，直接复制改主体。
• 小任务只走相关步骤：十步工作流支持”small edits use only the relevant steps”，改个材质不必走全流程。

高级玩法

• 检索驱动生成：技能带 249 个 authored known-intent 检索用例（scripts/check-retrieval.py），Agent 能按意图路由到对口 recipe/kit——研究”知识检索 + 生成”的人可以直接读它的 retrieval cases 设计。
• 贡献数据走全套门禁：仓库的 gates 链（validate.py、build-index.py --check、check-docs.py、check-retrieval.py、unittest、package.py）是 Skill 工程化的范本；给自己的技能抄这套质量门禁。
• evidence archive 做可信度审计：451 个来源 / 3,599 条证据事件全部公开（evidence/），可以做”这个技能的数据到底多可靠”的独立审计。
• 解剖类教学场景：基于 BodyParts3D（CC BY-SA 2.1 JP）的解剖 study 群（心脏切面、膝部层级、臂丛等），适合医学教学可视化改造——注意保 attribution。

小技巧

1. 先跑 pnpm dev 看 /heart/ 这类解剖 study，最快建立”模型驱动 + 可交互”的直觉。
2. 用 catalog-summary.json 查当前 recipe/知识/kit 计数，别信过时博客的数字——官网数字是构建时从仓库重算的。
3. capture.py 产物带 host/tiers/hashes，把帧存档当作交付证据链，方便回溯”当时到底渲染成什么样”。
4. T0-T4 分级标签是质量承诺的”合同”，评审产出时先看 Agent 报告的 tier，再看画面。
5. 双视角利用：一份知识给创意方向（style profiles 的 37 种），一份给事实核查（sources/evidence）——这是它区别于纯模板库的关键。

常见问题 FAQ

Q1: 它和”让 Claude 直接写 Three.js”有什么区别？

A: 三点：结构化知识（223 recipe + 440 知识记录带数值默认值，Agent 不用从零摸索）；路由决策（复用 kit / 改编 / 原创的分流）；截帧自查闭环（capture.py 让 Agent 看自己渲染的帧再修，而不是自夸完成）。README 的对照评估是 21 → 25/30（带技能四轮均值），样本 n=1 仅供方向参考。

Q2: 支持 Codex 吗？

A: 支持。官方把 Codex 列为第一评估目标，安装方式是把同一技能文件夹放进 Codex 认可的 skill 目录并在首 prompt 显式点名。

Q3: 需要装 Blender 吗？

A: 可选。推荐 Blender 4.2 LTS+，没有它所有脚本照跑，但 kit 品质封顶 T2；T3 的两个 Blender 烘焙资产拿不到，T4 目前无处可用。

Q4: 商用有什么许可风险？

A: 仓库自有代码/数据/媒体是 MIT；但第三方素材保留原条款——BodyParts3D 网格 CC BY-SA 2.1 JP（需保 attribution）、字体 OFL 1.1、Harness Village 录像授权待确认。商用前查 LICENSE 与 credits 一节。

Q5: 数字（223 recipe 等）可信吗？

A: 官网从仓库构建时重算每个计数，catalog-summary.json 是权威数据源；但 recipe≠已渲染验证，渲染验证看 21 帧 showcase 与 kit 截帧记录。

Q6: 适合做严肃仿真吗？

A: 不适合。README 明确定位”Visual inspiration, not a benchmark”与”animated decoration does not become a simulation just by moving”——物理真实性需要你另行验证，它是可视化与创意工作流，不是仿真引擎。

免责声明

本文基于公开资料整理（GitHub README 全文与仓库元数据，核验日期 2026-09-14），AI 辅助生成，未在本站环境实际生成场景验证 Agent 行为。before/after 评估为 n=1 的小样本，官方亦声明”not a demonstration”。仓库创建 2026-09-10（4 天），处于 0.1.x 早期阶段。

参考链接

• GitHub 仓库 viettranx/3dviz-pro-max
• 官网/落地页 3dviz.dev
• 安装文档 docs/installation.md
• SKILL.md 技能定义
• 示例集 examples/README.md
• 兼容性状态 docs/compatibility.md
• Prompt 画廊 docs/prompt-gallery.md