img2threejs

img2threejs — 将图像转换为程序化 Three.js

将参考图像中可见的对象重建为纯代码程序化 Three.js 模型，并通过分阶段雕刻流程和 AI 视觉自我纠正循环进行约束。这是通过代码进行重建，不是摄影测量、网格提取或下载美术资源包。此承诺约束模型的构建方式——并不限制模型之后可以导出为哪些文件格式；明确选择的输出目标（--target <kind>）是对已构建模型进行的终端式整体转换，并按其自身声明的范围进行验证，绝不是另一种构建方式。

与 Agent 无关：可用于 Claude Code、Codex 或 OpenCode。本文提到“Agent 视觉”或“Agent 浏览器工具”时，请使用宿主提供的任意功能——原生图像读取、浏览器 MCP（playwright/chrome-devtools）、项目预览，或用户提供的截图。

此文件是始终加载的路由文件：它以一行一条的形式列出操作顺序和所有硬性规则。每条规则背后的完整约定都在该规则指定的 grimoire/ 或 docs/ 文件中——到达相应阶段时再读取指定文件，不要提前读取。

规范共享检出目录

保留此仓库的一份检出目录，并让每个宿主通过符号链接进入其中，这样 Claude 和 Codex 执行的是同一份代码，不会逐渐偏离：

~/.claude/skills/img2threejs -> <your checkout>
~/.codex/skills/img2threejs  -> <your checkout>

适用场景

用户附上或指向一个对象图像，并希望获得程序化 Three.js 模型、重建／动画／破坏方案、雕刻规范或代码。也适用于材质研究、可用于动作的道具、游戏对象、植物／机械部件和风格化重建。

核心承诺

按顺序从照片进行雕刻——绝不一次性生成网格：

1. 每次开始、恢复以及每轮纠正迭代之前，先运行 python3 forge/next.py --state .img2threejs/state.json [<spec>]。该命令会报告有序清单、确切的下一条命令、证据状态和有界纠正循环状态；不会取代规范／阶段门槛。遵守硬性停止要求；绝不凭记忆继续。
2. 验证图像是否适合作为 3D 目标（grimoire/intake/validation_rubric.md）。
3. 评估对象类别和复杂度，然后在编写任何代码之前写好 qualityContract。
4. 制定规范：组件层级、材质、灯光、枢轴、插槽、动作锚点。
5. 逐阶段构建：从粗模 → 结构 → 形态 → 材质 → 灯光 → 交互 → 优化。
6. 验证每个阶段：截图并与参考图像进行对比；即使整体评分看起来不错，只要任何定义身份的特征有误，也判定该阶段不合格。

明确说明输出是否为近似风格化或低多边形。单张图像无法呈现隐藏面，也无法保证几何完全精确——应如实说明，不要假装有把握。

强制本地状态门禁

对话上下文可丢弃；.img2threejs/state.json 是本地检查清单的权威来源。 每次重建时初始化一次，然后通过它对每个步骤进行门禁检查：

python3 forge/state.py init --state .img2threejs/state.json --reference <img> --profile <generic|character|installed-domain> --spec object-sculpt-spec.json
python3 forge/next.py --state .img2threejs/state.json [object-sculpt-spec.json]
python3 forge/state.py mark <step-id> --state .img2threejs/state.json --evidence <path>

• next.py 会打印当前步骤、通过次数、未完成的强制步骤、准确的下一条命令，以及 loop/max。退出代码 3 或 status=stopped 表示必须停止：报告原因并请求输入。 绝不能通过从聊天记录重建进度来绕过它。
• 每个已完成的步骤都必须有证据；只有使用 --reason，才能将不适用的步骤标记为 skipped — 不得静默省略。循环次数根据 reviewHistory 中的操作 （refine-spec/refine-code）计算，而不是依赖 Agent 记忆。默认值：每轮修正 3 次，总计 6 次。
• 领域配置的步骤、门禁和参考资料来自 注册表：仓库内模块（character）和已安装的插件（来自 plugin-character 的 cs2、animated-character）以相同方式注册，而 forge/state.py init 会列出可用项。配置会添加强制门禁，但不改变核心顺序 —— 领域插件通常要求在 AI 审核前提供权威分类、接收清单和机器可读的领域审核；character 要求角色契约和关键部位证据；animated-character（要求安装 plugin-character）会添加 character 的全部内容，以及九个阶段 R 步骤（grimoire/readiness/animation_contract.md）。只要骨架需要 MOVE，就应选择它 — 在 character 配置下，阶段 R 门禁不存在，构建会在从未执行这些步骤的情况下完成，这正是过去动画出错的原因。顺序至关重要：修复网格、冻结网格、以加法方式绑定，然后验证一致性。每个配置都会记录适用性、投影适用性和 材质证据适用性。状态文件是可恢复性索引，并非视觉证据： 渲染、规格、审核历史和确定性门禁仍是权威产物。

必需输入

• 一个图像路径 / 屏幕截图 / URL / 附加图像（如果缺失或无法读取，请询问）
• 预期用途：道具、游戏对象、主角渲染、可游玩 / 可破坏对象、动画骨架 （默认：具有交互性能的实时浏览器道具）
• 如果某个领域插件适用于该项目，则需提供其接收步骤要求的权威记录，或明确请求用户 / 视觉服务提供方提供记录；仅靠启发式检测不足以选择几何适配器

循环（脚本负责执行；Agent 视觉负责判断）

从技能根目录（forge/...）运行脚本。使用纯 Python 3.10+ 标准库，无需安装 pip 包。 完整标志：grimoire/scripts.md。绝不能让脚本为视觉效果 打分 — 这是 Agent 的工作。

1. 先分析图像（在运行任何脚本之前，使用 Agent 视觉）：遵循 grimoire/intake/image_analysis.md 中的分层观察协议——识别并分类，按宏观→中观→微观进行拆解，梳理部件关系，用 PBR 术语描述材质，列出定义身份的特征，并标明单一视角无法呈现的内容。先观察，再推断；使用受控的 3D 词汇；以 3D 物体空间而非 2D 图像空间为准。然后探查本地图像： forge/stage1_intake/probe_image.py <image>（仅检查元数据，不做视觉检查）。 1a. 本地规格搜索——图像分析后、编写或完善规格之前，先提取本地域证据（解剖结构/PBR/磨损/几何/运行时/物理），不要凭空编造： python3 forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <img> --out assessment.json （自动对 core_3d 集合运行 BM25，或对已声明领域贡献的集合运行；绝不会根据目标名称猜测集合——生成的 localSpecSearch 包会由 new_sculpt_spec.py --assessment 带入规格）。完整的查询扩展方案（双语术语、聚焦的 search_specs.py 检索、缓存规则）： grimoire/intake/local_spec_search.md。重试不完整或特定领域查询前，必须阅读该文件。 1b. 领域接入——当领域插件适用于该项目时，须在编写预规格前完成其接入步骤（准入、启发式信号、分类、族/路由解析）。创建清单或运行预规格评估之前，必须完整阅读其步骤中指定的合约。 1c. 可选保真度证据适配器——仅在能改善已观察到的弱点时使用；标准库核心仍是权威依据。薄壁/复杂遮罩 → 本地 SAM2；角色面部/姿势 → MediaPipe；正面/背面线索较弱 → Depth Anything V2 （forge/stage1_intake/run_vision_adapter.py <segment|landmarks|depth> ...；每个适配器都会输出来源信息；单目深度仅表示相对深度）。仅通过 MCP 修改场景不算作实现——将已验证的变更写回规格或 TypeScript，重新构建并重新捕获。完整的适配器与 MCP 路由及权威边界： docs/integrations/reference_fidelity_tooling.md。
2. 预规格评估关卡——分类、评估复杂度并编写质量合约： forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <img> --complexity <simple|moderate|complex|ultra-complex> --out assessment.json。规则见：grimoire/intake/quality_contract.md。 设置 objectClass.primaryDomain（object | character | hybrid），并填写预置的 detailInventory（其 targetMinDetails 会根据复杂度调整）。领域插件可以通过其扩展提高这些下限——合并时会进行钳制，因此插件绝不能降低下限 （皮肤的表面效果/磨损/五金件就是物品本身，因此此类领域须达到最高保真度标准。编写程序化几何体，但要通过第 2c 步的投影路径处理表面效果——对于带图案的皮肤（Doppler/Gamma/Marble/Fade），程序化表面效果与参考图相比会明显失真。领域插件会提供自己的表面效果规则手册和纹理采集指南；请阅读其检查清单步骤指定的内容）。 2b. 细节清单（细节丰富的对象不可跳过）——扫描各区域并列出每个定义身份的小细节（光泽、倒角、紧固件、线条、轮廓、污渍）： forge/stage1_intake/build_detail_inventory.py <image> --mode grid-3x3 --out-dir <dir> --out di.json。 每个细节都必须映射到一个 component.localFeatures 或 material.localOverrides 条目中——不得仅以文字描述。分类体系与 3D 术语方案：grimoire/intake/detail_inventory.md。 2c. 投影优先的保真度处理（角色及与参考图匹配的表面——喷涂皮肤、贴花、绘制图案）——当目标是匹配特定参考图的表面时，应将照片本身的像素贴到网格上，而不是通过程序化方式近似。这是提升保真度最有效的方法；对有图案的表面使用程序化材质是重建失败的头号原因。方案见（grimoire/character/likeness_maximization.md——其中的两个关键方法也适用于角色以外的对象）：求解相机参数（stage1_intake/solve_camera_pose.py → referenceCamera），对参考图进行去光照处理（stage1_intake/delight_albedo.py，硬性要求——去光照是确保投影安全的关键），然后投影去光照后的裁剪图并烘焙到 UV 中（stage3_build/bake_projected_texture.py --mesh-id <id>）。对于喷涂皮肤，投影后的去光照裁剪图就是表面效果——不要使用程序化 Doppler 材质。对于角色，先捕获地标（stage1_intake/extract_landmarks.py --out anatomy.json），填写 preSpecAssessment.anatomy，并采用 grimoire/character/reconstruction.md 中的流程。单一视角无法呈现被遮挡的侧面——报告各区域的置信度，并在必要时请求更多视角。 角色子流程，按顺序执行——先确定有哪些部件，再塑造各部件；先塑造头部，再塑造位于头部上的头发：
   • 部件——grimoire/character/structure_decomposition.md
   • 头部——grimoire/character/head_construction.md（相似度关卡会据此进行比对）
   • 头发——grimoire/character/stylized_hair_threejs.md + 参数合约见 grimoire/character/threejs_hair_parameter_contract.json。只有在轮廓评审通过后才能锁定拓扑：材质调整无法修复错误的发束拓扑。 2d. 无参考图的人形对象——通用人物没有参考图可供测量，因此应依据公开的人体比例规范填写解剖数据： forge/stage2_spec/humanoid_proportions.py <spec> --style-heads 8 --in-place。它会写入 anatomy.source: "canon-table"，确保规范数据绝不会被误认为测量数据；当规格中指定了参考图时会拒绝运行，并会指出语料库未提供的数据，而不会对其进行插值。
3. 根据评估结果编写规格： forge/stage2_spec/new_sculpt_spec.py "Name" --image <img> --assessment assessment.json --augmentation spec-augmentation.json --domain <profile> --out object-sculpt-spec.json（检查清单步骤会携带已解析的标志）。 将通用初始 featureReviewTargets 替换为对象真正的身份标识系统（每轮最多 5 个关键项、最多 3 个重要项）；角色需添加 anatomy-proportion、face-landmark-placement、pose-silhouette、outfit-and-palette。仅使用 3D 图形术语（grimoire/glossary/3d_vocabulary.md），切勿使用“好看/平滑/闪亮”等词。选择 primitive 之前，须根据 grimoire/intake/surface_topology.md 对每个部件的 topologyClass/topologyRationale 进行分类——这可以避免将连续有机形体选成方块。
4. 当材质保真度很重要且存在源图像时，分析每种材质的表面效果，然后提取参考 PBR 证据；均须按裁剪图分别处理（确认裁剪图确实来自预期部件）：
   • forge/stage1_intake/analyze_texture.py <crop> --spec spec.json --material-id <id> --in-place 用于分类表面效果、提取渐变调色板，并根据文档资料将 MeshPhysicalMaterial 标量写入材质。方案及 Three.js 纹理/PBR 规则： grimoire/build/threejs_texture_reference.md。经验法则：纯色涂装使用纯色反照率，带图案的表面效果使用真实参考裁剪图。
   • forge/stage1_intake/extract_pbr_evidence.py <crop> --out-dir <dir> --material-id <id> --target-threshold 0.7。 置信度 < 0.7 表示应停止并完善输入，不代表通过。这是推断，不是逆向渲染。
   • 对多个命名区域：forge/stage1_intake/material_region_analysis.py --manifest regions.json --out-dir material-evidence --out material-analysis.json， 根据 docs/materials/material-reference.json 解析每个分配，再通过 forge/stage2_spec/apply_material_analysis.py 接入。
   • 输出受控的材质相机/裁剪图合约（forge/stage4_review/material_views.py），比较可见覆盖范围内的裁剪图（material_comparator.py），仅应用受限于材质范围的修正（material_feedback.py），并记录阻断结果（material_gate.py）。
5. 先验证，再在生成代码前进行严格验证： forge/stage2_spec/validate_sculpt_spec.py object-sculpt-spec.json 然后运行 --strict-quality。 严格检查会阻止浅层规格（复杂对象只有一个根节点、没有重复系统、没有局部覆盖项、没有微观组时，即使 JSON 验证通过，也不具备实现条件）。
6. 锁定的构建阶段——仅修改当前已解锁的阶段： forge/stage3_build/orchestrate_passes.py status object-sculpt-spec.json forge/stage3_build/generate_threejs_factory.py object-sculpt-spec.json --out src/createObjectModel.ts 生成器采用失败关闭机制：在写入任何工厂代码前，必须通过 strict-quality；未来阶段的 --pass-id 在之前的阶段经过评审并判定为 continue 前会失败。如果受阻，保留 BLOCKED 产物并完善对象专属规格；不要用通用模板替代。本地状态仅在新阶段或 refine-spec 时添加 --force；refine-code 会修改当前产物，而不重新生成。覆盖前，将有效的手动优化内容写回规格；重建决策不能只保留在生成的代码中。 6a. 达到三角形预算上限。 performanceBudget.targetTriangles 会为每种带分段数的基元选择细分等级（低 ≤6k，标准 ≤60k，否则为高精度），并限制隐式曲面的采样网格。若某个等级不够精确，可为该部件添加 geometryDescriptor.decimate: {"targetRatio": 0.4}——在生成的工厂中执行二次坍缩，且先于蒙皮绑定运行，以便基于保留的顶点计算权重。它仅保留 position（重新计算法线），因此当使用作者编写/展开的 uvStrategy 时会拒绝执行。离线 LOD 等级： forge/stage3_build/decimate.py <mesh.json> --ratio <r> --json。
7. 在浏览器/预览中渲染当前阶段，并在评审视角下截取屏幕截图。 7a. 离轴与放置关卡——单一评审视角不能证明模型的实际情况。 应捕获转台视图，而非单帧，并运行以下全部三项；每项都会检测旧关卡必然漏过的一类缺陷（贯穿头骨的孔洞、位于臀部高度的帽子、悬浮的吊饰都曾在 8 轮仅从正面进行的评审中漏检）： forge/stage4_review/turntable_gate.py --capture 0=front.png --capture 90=right.png --capture 180=rear.png --capture 270=left.png --json node runtime/scripts/export_mesh_geometry.mjs --url <preview> --out meshes.json 然后运行 forge/stage4_review/self_intersection.py meshes.json --json forge/stage4_review/attachment_anchor.py object-sculpt-spec.json --measured measured.json --json 三项检查的退出码均为 0 表示通过，1 表示关卡失败，2 表示错误。即使全局保真度评分通过，任何失败都会阻止 continue。在相信通过结果前，请先查看 sampledVertexCount / unmeasuredAttachments / missingAzimuths：每项都会指出关卡未检查的内容。
8. **先运行确定性关卡，再使用 AI 视觉。**必须完整阅读 grimoire/review/gates_reference.md 和 grimoire/review/self_correction.md。运行 forge/stage4_review/diagnose_render.py，并使用 --spec object-sculpt-spec.json --pass-id <pass> --in-place 记录 Tier 1 通过结果；对于非平面形体，还要运行 forge/stage4_review/diagnose_render_multi_angle.py，使用固定视角和至少两个有意义的环绕视角。然后运行 forge/stage3_build/orchestrate_passes.py check object-sculpt-spec.json --pass-id <pass>。
9. 制作一张并排对比图，然后使用 Agent 视觉进行检查： forge/stage4_review/make_comparison_sheet.py --reference <img> --render <shot> --out cmp.png --json。
10. 记录评审（总体评分、各层评分、各特征评分和决定）： forge/stage4_review/append_review.py object-sculpt-spec.json --pass-id <pass> --fidelity <0-1> --action <continue|refine-spec|refine-code|request-input|stop> --summary "..." --render-screenshot <shot> --comparison-image cmp.png --ai-vision-score <0-1> --layer-scores-json '{...}' --feature-reviews-json <f.json> --in-place。 当领域插件提供评审关卡时，先使用该插件评审步骤指定的命令生成其带版本号的报告，再通过 --domain-review-json <report>.json --review-scene-json <the plugin's scene fixture> 附加报告。检查清单步骤会携带已解析的路径。 即使全局评分通过，族、喷涂区域、投影覆盖、关键细节或环绕视角关卡中的任何一项失败，都会阻止 continue。请参阅插件自身的评审关卡文档。
11. 手动修改评审结果后同步流水线状态，记录检查清单证据，然后在进行下一次修正或开始下一阶段前重新运行本地状态关卡： forge/stage3_build/orchestrate_passes.py sync object-sculpt-spec.json --in-place python3 forge/next.py --state .img2threejs/state.json object-sculpt-spec.json。
12. 声明完成前，运行 forge/stage4_review/check_part_coverage.py --spec object-sculpt-spec.json --manifest parts.json 并验证层级结构已可供操作。只有提供证据时，才标记 part-coverage 和 action-ready。

GLB 中介的 v2 渲染保真度流程（1.5 alpha）

当用户提供 GLB 作为中间参考时，浏览器渲染的 GLB 是独立编写的程序化工厂的结构与视觉基准。原始 GLB 绝不能作为像素证据，其拓扑和材质也绝不能复制到工厂中。在修改工厂之前——完整约定见 grimoire/build/python_threejs_render_bridge.md，机器可读的架构见 docs/specs/render-profile.v2.schema.json（另附示例；验证失败时拒绝继续）：

1. 首先运行 forge/stage1_intake/probe_glb.py。合并为单节点／单网格的资源对于语义标签来说属于 insufficient；在声称可精确识别区域之前，先请求多部件 GLB，或执行浏览器语义 ID 流程。
2. 编写一个供 GLB 路径和程序化路径共用的 render-profile.v2（forge/stage4_review/validate_render_profile.py）。区域 ID 因对象而异，绝不能沿用示例配置；在 extensions.requiredSemanticRegions 中声明必需区域集，确保缺少区域会导致硬性验证错误。
3. 每个获准视图捕获六种通道（beauty、alpha-silhouette、semantic-id、depth、normal、roughness-material-id）；使用 forge/stage4_review/compare_region_passes.py 评分。缺少语义 ID 数据会阻止计算逐区域置信度，而不是退回到整图评分。
4. 使用区域专属的连续几何——当区域轮廓需要连续表面时，绝不能用悬浮的基本体替代面部／头部体积、布料外壳或尾巴。
5. 每轮按顺序只运行一组修正：camera → silhouette → face → clothing → accessory → materials → lighting；每组修正后重新捕获完整通道集，并记录变更组、哈希和评分。诊断改进时绝不能合并多组修正。

门槛（不得跳过）

在进行任何视觉审查或决定是否 continue 之前，必须完整阅读 grimoire/review/gates_reference.md 中逐项说明的门槛约定（Divine Eye、VLM 救援、多角度、内部差异、左右手性、毛发、领域审查、有界修正、Divine Eye 拟合、截图反馈、组装、附件、材质、细节清单、绑定载荷、角色轨迹）。简而言之：

• 首先验证参考资料（grimoire/intake/validation_rubric.md、check_reference_admission.py）。
• divine_eye.py 采用确定性优先；VLM（vlm_gate.py）是受门控的最后一层，硬性门槛失败时绝不调用。
• 非平面形体必须从 ≥2 个角度都成立（diagnose_render_multi_angle.py）。
• 每次视觉检查都要测量轮廓内部（interior_difference.py）。轮廓 IoU 只读取约 11% 的图形单元：删掉面部的模型与面部完整的成品得分相同，均为 0.8803。
• 每一对 -l/-r 都是镜像，而非旋转——必须在规格阶段严格落实（validate_chirality）。一对部件即使两侧都以同样的方式出错，也仍会通过；需要对照参考检查 medial_lateral_bias。
• 毛发主题：scalp_exposure.py 是硬性门槛，会在任何渲染前基于几何运行；hair_gate.py 是软性门槛，优先级低于前者。覆盖不足绝不意味着可以扩大毛发体块。
• 带有清晰边界的平涂色块区域（额前白斑／胸前白斑／袜套、涂装条纹、绘制标记）属于身份特征，因此其边界必须通过几何门槛检查：vertex_region_gate.py。绝不能使用纹理——此流水线输出代码；形状谓词位于 _shared/vertex_paint.py。
• 曲线特征（“弯成钩状，而非直锥”）需要通过 swept_arc_gate.py：轮廓 IoU 会让占据大致正确单元的直锥通过。
• 角色构建必须在绑定 THREE.Skeleton 前验证绑定载荷（stage5_rig/validate_rig_payload.py）；这只能证明载荷完整性，绝不能证明姿势受力表现或相似度。
• 必须运动的绑定还需运行动画门槛（grimoire/readiness/animation_contract.md；检查清单步骤和门槛来自已安装的 plugin-character——本仓库中的 stage5_rig/ 仍是生成器的库，而非检查清单的权威来源）。片段存在不代表片段能播放：只有 G1（maxSampledBindingDelta <= 2^-23）能区分二者；输入缺失的门槛应报告 unevaluated，绝不能算作通过。在附着模式下以 IDENTITY 绑定，显示偏移量仅根据网格边界确定；循环播放由 poseReturn 判断，绝不根据位移判断。
• 领域插件的审查门槛也要针对其带版本的场景夹具运行。
• 默认情况下，本地状态每轮最多允许修正 3 次、总计最多允许修正 6 次；达到任一上限都必须立即停止。correction_loop.py 可能因缺陷重复、振荡或停滞而更早停止。
• continue 必须满足：有渲染图、对比图表，且 AI 视觉评分达到阈值；每项关键特征也必须达到各自的阈值（grimoire/feedback/render_capture.md）。
• 每个模型都必须可拆解且可点击——这是结构门槛，不是像素要求（check_part_coverage.py、grimoire/build/geometry_patterns.md）。
• 动作就绪、附件、材质／光照、细节清单和角色轨迹要求：grimoire/readiness/action_rigging.md、grimoire/readiness/joint_attachment.md、grimoire/feedback/shading_realism.md、grimoire/intake/quality_contract.md、grimoire/intake/validation_rubric.md。

自我修正

每轮之后，准确选择一项：continue | refine-spec | refine-code | request-input | stop。 refine-spec 用于修正错误、缺失或浅显的规范（重新验证，不要绕过规范去修补代码）； refine-code 用于修正与合理规范不符的几何、材质或照明。作出决定前，必须阅读 grimoire/review/self_correction.md 中的根因指南和保真度等级，记录决定，并重新运行本地状态门禁。

小型特征需要不同的检测工具。 Divine Eye 的 SSIM／色调／边缘信号基于 64×64 亮度网格运行，因此几像素宽的细节在任何比较开始前就已消失。当保真度取决于单独的泪滴、翼尖、獠牙或眼睛时，请使用四级显微检测流程： grimoire/review/divine_eye_microscope.md。其中两条经实证确立的规则：在组件的可见占用区域上测量保真度（完整画面减去隐藏该组件的画面），绝不能使用隔离渲染；对于凹面特征，绝不能进行颜色门控，因为暗部比例反映的是腔体阴影，而非材质。

透明度与流程调试

每轮都要提供证据（确切数值／坐标），说明发生了哪些变化；指出仍有哪些地方不匹配；如果只是“有所改善”，绝不要声称“已完成”。门禁通过并不能证明具有 3D 真实感。 完整规则和示例：grimoire/review/self_correction.md。

左与右

一对左右部件是镜像反射，绝不是旋转：只反转横向轴，不做其他改变， (x, y, z) → (-x, y, z)。在 forward: +Z、Y 朝上且坐标系为右手系时，角色自身的 左侧是 +X。此约定以代码形式保存在 forge/_shared/chirality.py （CHARACTER_LEFT_SIGN）中；针对因误用该约定而引入的两类缺陷，设有不同的门禁：validate_chirality 会在规范阶段捕捉将旋转误当作镜像反射的情况，而 medial_lateral_bias 会与参考进行比较，捕捉两侧以相同方式出错的成对部件。 镜像反射也会反转三角形绕序——在镜像侧将其翻转回来，否则 flatShading 会让肢体呈现出仿佛从背面受光的效果。完整说明及测得的缺陷： grimoire/scripts.md（“左与右”）。

头发

头发有自己的子系统，因为它存在其他门禁无法检测的失效模式。完整约定、 测量方法和非目标：docs/HAIR_PIPELINE.md。硬性规则如下：

• 发根以 (u, v) 绑定到头皮，绝不能使用绝对位置（硬性验证错误）。
• standProud 由生成器强制执行，并非建议项。
• scalp_exposure.py 是渲染前针对几何体的硬性门禁；覆盖不足本身绝不能成为加宽发块的理由。
• 默认表示层级为 shell，而非发束；由于此技能不会生成纹理，发丝质感来自分面效果和材质（hair.human.code-only）。
• 头发不接受 plane-card（需要此技能无法生成的 alpha 纹理）。
• 头发通过刚性父级关系绑定，绝不进行平滑蒙皮（测地场会穿过颅骨）。

领域插件

领域插件可以让本流程在其他情况下需要推断的部分实现精确化。它会提供自己的检查清单步骤和门禁，并发布一个 spec-augmentation.json，由本流程在 spec-authoring 阶段拉取。如果没有插件支持该项目，这里不会发生任何变化：像处理其他对象一样编写骨架，并根据参考推断形状。

• 插件提供的步骤会以各自的 ID 和解析后的路径显示在检查清单中。请阅读每个步骤指向的内容——插件会附带自己的约定，并由该约定管理其领域。
• 插件可以提高本流程的质量下限，绝不能降低；合并时会进行限制。
• 不支持某个项目的插件不会发布扩展规范。这不是错误，也不会阻止流程运行：流程会采用通用路径，通过推断继续重建。
• 本流程不指定领域。若某条规则与特定领域相关，则该规则由该领域的插件负责。

img2 工具链

插件由 img2 工具链安装和管理 （img2threejs/img2）。它是一个独立且无依赖的 CLI（Node 启动器，Python 核心）。本技能 本身绝不会安装任何内容：当 state.py init 将某个配置文件标记为不可用时，指出安装该配置文件的 img2 add 命令，然后停止操作——绝不要改为内置领域逻辑。

img2 add img2threejs/plugin-<id> --ref <tag>      # install a plugin at a tag (e.g. plugin-cs2)
img2 doctor                                       # what each host resolves: base-skill path + version, plugin gates
img2 capabilities --from-kind image --to-kind glb # which installed plugin serves an edge

设置说明和完整的 CLI 参考位于 README 快速入门和工具链仓库的文档中。

Forge 运行时契约

细分运行时测试会将生成的 TypeScript 编译到 showcase 检出目录中。将 IMG2THREEJS_SHOWCASE_ROOT 设置为该检出目录；若未设置，本地仅运行时测试会跳过并显示 可操作的提示，而静态契约仍会运行。CI 应设置 IMG2THREEJS_REQUIRE_SHOWCASE=1 将缺少 showcase 检出目录转为测试失败。

IMG2THREEJS_SHOWCASE_ROOT=/path/to/img2threejs-showcase python3 forge/tests/test_subdivision.py
IMG2THREEJS_SHOWCASE_ROOT=/path/to/img2threejs-showcase python3 -m unittest discover -s forge/tests
IMG2THREEJS_SHOWCASE_ROOT=/path/to/img2threejs-showcase python3 forge/tests/test_showcase_tsc_smoke.py

实现规则（简要）

使用 TypeScript + 纯 Three.js，除非项目采用了包装器。Group 工厂 createObjectNameModel(spec, options)，重建数据与渲染器对象分开存放，所有程序化噪声使用 确定性种子。优先使用基础几何体 / Shape 拉伸 / 曲线 + 管状体 / 实例化 / 位移 / 生成的画布纹理，然后才考虑外部美术资源。完整的几何体和材质方案，以及 经过实践总结的失败模式：grimoire/build/geometry_patterns.md。

可选的 Python ↔ Three.js 渲染桥接

需要使用 Python 渲染角色时，将其用作浏览器 Three.js 运行时外围的确定性作业 / 证据层：摄像机批次清单、源文件 / 输出哈希、就绪和稳定性检查、截图持久化、蒙版、诊断及对比打包。目标 Three.js 浏览器路由仍是渲染权威。不要悄悄用 Blender/VRM/GLB 输出替换程序化 TypeScript 工厂。完整的路由、清单字段和失败规则： grimoire/build/python_threejs_render_bridge.md。

标准角色流水线（合并 1.5 beta + alpha）

角色相关工作请使用 grimoire/readiness/standard_character_pipeline.md。Beta 负责严格的雕刻 / 构建 / 审查关卡；alpha 负责确定性摄像机清单、浏览器截图证据和符合 UniRig 形态的骨架验证。CharacterGen、Tripo、VRM 及其他神经网络 / 资源系统均为可选适配器，须记录来源、检查点、许可证、坐标转换和输出哈希。它们绝不会悄悄替换程序化 TypeScript 工厂。图像转网格系统会生成没有骨架的静态网格，因此无论外观多好，其输出都无法用于动画。可执行入口：forge/stage4_review/render_bridge.py 和 scripts/capture_threejs_playwright.py（init → browser capture → validate → diagnose；捕获必须通过真实的 showcase / 浏览器路由执行，并在工作区中留下可读的 PNG）。

输出

• 仅分析：适用性结论 + 评分、对象提取、宏观到微观的层级、几何体策略、材质 / 灯光方案、动画 / 破坏可行性、计划 + 风险。
• 实现：简要说明上述内容，然后编辑代码；通过类型检查 / 构建 + 截图进行验证。
• 不可行：指出阻碍，并要求提供更多视角 / 更清晰的图像 / 可接受的风格化方案 / 更小的目标。“仅凭这张图无法达到所要求的保真度”是合理的结论。