shader-extract

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shader Extract

Shader提取

Capture one GPU-rendered surface and rebuild it as a verified, runnable local effect module. The governing principle — inherited from the vendored engine this skill wraps — is evidence before implementation: capture what the page's GPU pipeline actually does (shaders, uniforms, pass order, textures, timing) and match it, rather than eyeballing the visual and hand-tuning a lookalike. A lookalike drifts; a capture-matched baseline is faithful and honest about its gaps.

捕获单个GPU渲染的内容，并将其重建为经过验证的可运行本地效果模块。本技能遵循的核心原则——继承自其封装的第三方引擎——是先取证再实现：捕获页面GPU管线实际执行的操作（着色器、uniform变量、渲染顺序、纹理、时序）并精准匹配，而非仅凭视觉观察手动调整出相似效果。相似效果会逐渐偏离原效果，而基于捕获匹配的基准则能忠实还原，且对自身存在的局限保持坦诚。

This skill = intake adapter + a vendored evidence-gated engine

本技能 = 输入适配层 + 封装的取证驱动引擎

The heavy machinery lives in vendor/web-shader-extractor/
— an evidence-gated state machine (surface lock → source/runtime trace → capture → verified baseline → projectize) by lixiaolin94 (MIT; see

ATTRIBUTION.md

). Do not reimplement it. This wrapper does two things the vendored engine assumes were done elsewhere:

Intake — accept a pre-locked surface from the clone-site coordinator so you skip straight to capture instead of re-scouting the whole page.
Capture backends — make the concrete, research-verified capture tools explicit (
```
references/capture-backends.md
```
): Spector.js for WebGL1/2 and WebGPU Inspector for WebGPU. These are what actually recover a frame; the vendored policy files describe the discipline, these describe the tools.

核心功能位于**

vendor/web-shader-extractor/

**目录中——这是由lixiaolin94开发的取证驱动状态机（流程为：锁定渲染内容 → 追踪源码/运行时 → 捕获 → 验证基准 → 项目化），采用MIT许可证（详见

ATTRIBUTION.md

）。请勿重新实现该引擎。本封装器仅完成两项第三方引擎未涵盖的工作：

输入处理 —— 接收来自clone-site协调器的已锁定渲染内容（包含选择器、边界框、推测的驱动库：three.js / unicorn-studio / spline / regl / 原生WebGL），以及输出目录（如
```
output/<host>/effects/<surface-id>/
```
）。由于该渲染内容已完成属性标记，可跳过页面探查步骤，直接进入捕获流程。
捕获后端 —— 明确指定经过研究验证的捕获工具（详见
```
references/capture-backends.md
```
）：Spector.js用于WebGL1/2，WebGPU Inspector用于WebGPU。这些工具是实际恢复帧数据的核心，第三方引擎的策略文件定义了操作规范，而这些工具则是具体的实现载体。

Router: how you were invoked

调用路由：触发方式

Driven by clone-site (common): you receive a locked surface — selector, bounding box, guessed driver (three.js / unicorn-studio / spline / regl / raw WebGL), and an output dir like

output/<host>/effects/<surface-id>/

. The surface is already attributed, so skip scouting. Go straight to:

Read
```
vendor/web-shader-extractor/SKILL.md
```
and its
```
references/replay-policy.md
```
— that is the operating manual for capture → baseline → projectize.
Pick the capture backend by surface type (
```
references/capture-backends.md
```
): WEBGL1/2 → Spector.js; WEBGPU → WebGPU Inspector.
Run the vendored state flow from
```
CAPTURE_MINIMUM_TRUTH
```
onward, writing evidence and the baseline into the given output dir.
Return a mount-contract module (see below) plus the honesty label.

Standalone (user hands you a URL): you must lock the surface first. Run the full vendored flow from

INTAKE

(read

vendor/web-shader-extractor/SKILL.md

). The

clone-site

script

scripts/surface-map.js

is a fast way to enumerate and classify canvases if you want a head start, but the vendored

TARGET_LOCK

gate is authoritative.

由clone-site驱动（常见场景）：你会收到一个已锁定的渲染内容，包含选择器、边界框、推测的驱动库，以及输出目录。由于该内容已完成属性标记，可跳过探查步骤，直接执行以下操作：

阅读
```
vendor/web-shader-extractor/SKILL.md
```
及其
```
references/replay-policy.md
```
——这是捕获→基准→项目化流程的操作手册。
根据渲染内容类型选择捕获后端（详见
```
references/capture-backends.md
```
）：WEBGL1/2 → Spector.js；WEBGPU → WebGPU Inspector。
从
```
CAPTURE_MINIMUM_TRUTH
```
阶段开始执行第三方引擎的状态流程，将取证数据和基准内容写入指定输出目录。
返回一个挂载契约模块（详见下文）以及真实性标签。

独立调用（用户提供URL）：你必须先锁定渲染内容。从

INTAKE

阶段开始执行完整的第三方引擎流程（阅读

vendor/web-shader-extractor/SKILL.md

）。如果你想快速上手，clone-site脚本

scripts/surface-map.js

可用于快速枚举和分类Canvas元素，但第三方引擎的

TARGET_LOCK

阶段是权威的锁定流程。

Non-negotiables (carried from the vendored engine)

不可协商规则（继承自第三方引擎）

Honest labels. Every implementation-critical fact is
```
SOURCE
```
,
```
PARTIAL
```
, or
```
GUESS
```
; unlabeled =
```
GUESS
```
. The final module carries a fidelity verdict. Never quietly upgrade a
```
BEHAVIOR_REBUILD
```
(lookalike) to sound like a source replay.
No compensation tuning. Don't nudge brightness, speed, offsets, noise scale, or color to mask missing pipeline evidence. A visible gap gets recorded in
```
known-gaps.md
```
, not fudged away.
Baseline before projectize. Get a faithful, verified capture-baseline running first; only then refactor it into an editable module. Don't overwrite a verified baseline for cleanup.
Cross-origin honesty. If the canvas is cross-origin/tainted and pixel or shader readback is blocked, say so and fall back to a captured poster frame — don't invent a shader you couldn't read.

真实性标签：每个对实现至关重要的事实都标记为
```
SOURCE
```
（源数据）、
```
PARTIAL
```
（部分数据）或
```
GUESS
```
（推测数据）；未标记的默认视为
```
GUESS
```
。最终模块需附带保真度判定结果。绝不能将
```
BEHAVIOR_REBUILD
```
（相似效果）伪装成源数据回放。
禁止补偿调整：不得通过调整亮度、速度、偏移量、噪声比例或颜色来掩盖缺失的管线取证数据。可见的缺失需记录在
```
known-gaps.md
```
中，而非伪造数据掩盖。
先基准后项目化：先确保基于捕获的忠实基准可运行，再将其重构为可编辑模块。不得为了代码清理而覆盖已验证的基准内容。
跨域真实性：如果Canvas存在跨域/污染问题，导致像素或着色器读取被阻止，需如实说明并退回到捕获的海报帧——不得编造无法读取的着色器。

Output contract (so clone-site can mount it)

输出契约（供clone-site挂载使用）

Beyond the vendored

output/

layout (capture-baseline, editable-project, qa-report, known-gaps), expose the effect through the mount lifecycle the coordinator composites against:

export function mount(canvasEl, opts) { /* start renderer + rAF loop */ return handle }
export function unmount(handle)        { /* cancel rAF, loseContext, free GPU */ }
export function resize(handle, w, h, dpr) { /* resize drawing buffer + viewport */ }

Also emit a poster frame (a captured still) as a fallback for reduced-motion and for the case where reconstruction only reached poster fidelity. Report the fidelity label so the coordinator carries it into the final clone report unchanged.

除了第三方引擎定义的

output/

目录结构（捕获基准、可编辑项目、QA报告、已知局限），还需通过协调器组合使用的挂载生命周期暴露效果：

export function mount(canvasEl, opts) { /* 启动渲染器 + rAF循环 */ return handle }
export function unmount(handle)        { /* 取消rAF，释放上下文，释放GPU资源 */ }
export function resize(handle, w, h, dpr) { /* 调整绘制缓冲区 + 视口 */ }

同时需生成一张海报帧（捕获的静态图像），作为减少动画场景下的 fallback，以及当重构仅达到海报保真度时的备选方案。需上报保真度标签，以便协调器将其原封不动地带入最终的克隆报告。

Where to read next

后续阅读指引

```
references/capture-backends.md
```
— Spector.js (WebGL) and WebGPU Inspector (WebGPU): what each captures, how to drive it, what's reliable vs guesswork.
```
vendor/web-shader-extractor/SKILL.md
```
— the full state machine + reference router (surface discovery, target lock, evidence policy, replay policy, QA, Three.js/TSL reconstruction, Unicorn Studio / shaders.com adapters).
```
ATTRIBUTION.md
```
— upstream authorship and MIT license.

```
references/capture-backends.md
```
—— 介绍Spector.js（WebGL）和WebGPU Inspector（WebGPU）：各自的捕获内容、使用方式、可靠数据与推测数据的区别。
```
vendor/web-shader-extractor/SKILL.md
```
—— 完整的状态机 + 参考路由（渲染内容发现、目标锁定、取证规则、回放规则、QA、Three.js/TSL重构、Unicorn Studio / shaders.com适配）。
```
ATTRIBUTION.md
```
—— 上游作者信息与MIT许可证说明。