NGS算法可视化 · 技术说明文档NGS Algorithm Visualization · Technical Documentation

📋项目概述Project Overview

本项目是一个纯前端的交互式教学应用，将 Illumina 二代基因组测序（Next-Generation Sequencing, NGS）的完整生信分析流程拆解为 6个可视化步骤，每个步骤配有动画演示和原理讲解，支持手动逐帧浏览和自动播放。

This project is a pure front-end interactive educational application that breaks down the complete Illumina Next-Generation Sequencing (NGS) bioinformatics pipeline into 6 visualized steps, each with animated demonstrations and explanations, supporting both manual frame-by-frame browsing and auto-play.

设计目标Design Goals

• 教育性：以简化的 mock 数据集展示算法的核心逻辑，而非实际生产代码
• Educational: Uses simplified mock datasets to demonstrate core algorithm logic, rather than production code
• 交互性：每个步骤可独立播放、暂停、回退、重放，降低学习门槛
• Interactive: Each step can be independently played, paused, rewound, and replayed, lowering the learning barrier
• 零依赖：不依赖任何第三方库（无 React/Vue/D3.js），便于理解和二次修改
• Zero Dependencies: No third-party libraries (no React/Vue/D3.js), easy to understand and modify
• 可扩展：步骤以数组对象定义，新增步骤只需追加一个配置对象
• Extensible: Steps are defined as array objects; adding a new step only requires appending a configuration object

覆盖的NGS流程NGS Pipeline Coverage

技术选型Technology Stack

🏗️技术架构Architecture

目录结构Directory Structure

NGS可视化/
├── index.html          # 应用主入口，HTML 骨架
├── docs.html           # 本技术说明文档（独立页面）
├── css/
│   └── style.css       # 全局样式 + CSS 变量主题系统
└── js/
    ├── data.js         # Mock 基因组数据 + 数据生成函数
    └── app.js          # 主程序：SVG引擎 + 步骤渲染 + 动画控制

模块依赖关系Module Dependencies

/* 加载顺序（index.html script标签顺序） */
data.js   // ① 先加载：定义全局常量 BASE_COLOR, REF, READS 等
  ↓
app.js    // ② 后加载：依赖 data.js 的所有全局变量

渲染架构（快照模型）Rendering Architecture (Snapshot Model)

本项目采用 "快照帧" 渲染模式，而非连续动画帧（requestAnimationFrame）：

This project uses a "snapshot frame" rendering model, rather than continuous animation frames (requestAnimationFrame):

• 每个步骤定义若干离散的 substep（子步骤帧）
• Each step defines several discrete substeps (sub-step frames)
• 每次状态变化时，重新生成整个 SVG 内容字符串并写入 innerHTML
• On each state change, the entire SVG content string is regenerated and written to innerHTML
• 帧间切换由 setTimeout 驱动，间隔 2200ms（可调）
• Frame transitions are driven by setTimeout, with a 2200ms interval (configurable)
• 好处：逻辑简单，每帧状态完全独立，易于调试；代价是不支持连续过渡动画
• Advantage: simple logic, fully independent frame states, easy to debug; trade-off is no continuous transition animations

// 核心渲染循环（简化）
function render() {
  const step = STEPS[curStep];
  document.getElementById('main-svg').innerHTML
    = step.render(curSub);   // ← 调用对应步骤的渲染函数
  updateStepNav();
  updateSubstepDots();
  updateButtons();
}

状态模型State Model

应用仅维护4个顶层状态变量，所有 UI 都是这4个变量的纯函数：

The application maintains only 4 top-level state variables; all UI is a pure function of these 4 variables:

🔄数据流转Data Flow

从原始 mock 数据到屏幕像素，数据经过以下变换链：

From raw mock data to screen pixels, data goes through the following transformation chain:

data.js 定义
  REF (string)              // "ATCGAACGTTACGGATCGATCGATGAATCGATCGATCGA"
  READS (Array<ReadObj>)    // 9条Read对象
  SIGNAL_DATA (Array)       // 8个位置的荧光强度
        ↓
app.js 渲染函数 renderStepN(substep)
  → 布局计算（坐标、宽高）
  → 调用 SVG 工具函数 R/T/L/C/P
  → 拼接 SVG 字符串
        ↓
render() 函数
  → svg.innerHTML = svgString   // 写入 DOM
        ↓
浏览器解析 SVG → 光栅化 → 显示

📄文件：index.htmlFile: index.html

关键 DOM 节点及职责Key DOM Nodes and Responsibilities

脚本加载顺序Script Loading Order

<!-- 放在 </body> 前，确保DOM已就绪 -->
<script src="js/data.js"></script>   <!-- 必须第一 -->
<script src="js/app.js"></script>    <!-- 必须第二 -->

采用同步加载（非 defer/async），顺序保证 data.js 的全局变量在 app.js 执行前就绪。实际触发渲染在 DOMContentLoaded 回调中。

Synchronous loading (no defer/async) is used to guarantee that data.js global variables are ready before app.js executes. Actual rendering is triggered in the DOMContentLoaded callback.

🎨文件：css/style.cssFile: css/style.css

CSS 变量系统（主题）CSS Variable System (Theming)

所有颜色通过 :root 中的 CSS 自定义属性（CSS Variables）统一管理，修改单一变量即可全局生效：

All colors are managed through CSS custom properties (CSS Variables) in :root; changing a single variable takes effect globally:

:root {
  /* 背景层次（3层深度）*/
  --bg:    #0d1117;   /* 最深层：页面背景 */
  --bg2:   #161b22;   /* 中层：面板、导航栏 */
  --bg3:   #1c2333;   /* 浅层：卡片、代码块 */

  /* 功能色 */
  --accent: #388bfd;  /* 主强调色（蓝）*/
  --green:  #3fb950;  /* 成功/完成 */
  --red:    #f85149;  /* 错误/错配 */
  --amber:  #d29922;  /* 警告/注意 */

  /* DNA碱基颜色（与 data.js BASE_COLOR 对应） */
  --A: #3fb950;  /* 腺嘌呤 Adenine → 绿 */
  --T: #f85149;  /* 胸腺嘧啶 Thymine → 红 */
  --C: #388bfd;  /* 胞嘧啶 Cytosine → 蓝 */
  --G: #d29922;  /* 鸟嘌呤 Guanine → 黄/琥珀 */
}

布局系统Layout System

整体采用三层 Flexbox 布局：

The overall layout uses a three-level Flexbox structure:

#app              /* flex-direction: column（垂直主轴）*/
  ├── header        /* flex-shrink: 0，固定高度 */
  ├── #step-bar     /* flex-shrink: 0，步骤导航 */
  ├── #content      /* flex: 1（水平Flex，占满剩余高度）*/
  │     ├── #vis-panel    /* flex: 1，自动填充 */
  │     └── #theory-panel /* width: 300px，固定宽度 */
  └── #controls-bar /* flex-shrink: 0，固定高度 */

关键属性：body { height: 100%; overflow: hidden; } 配合 #app { height: 100vh; }，使整个应用在视口内不滚动，内容区可独立滚动（#theory-panel 有 overflow-y: auto）。

Key properties: body { height: 100%; overflow: hidden; } combined with #app { height: 100vh; } keeps the entire app within the viewport without scrolling; the content area scrolls independently (#theory-panel has overflow-y: auto).

主要组件类Main Component Classes

🗄️文件：js/data.jsFile: js/data.js

全局常量一览Global Constants Overview

算法：genQual — 伪随机质量分生成Algorithm: genQual — Pseudo-random Quality Score Generation

function genQual(readId, pos) {
  const v = (readId * 17 + pos * 31 + 7) % 23;
  return 18 + v;   // 返回 Q18 ~ Q40
}

目的：生成视觉上有变化但可复现的质量分数，避免每次刷新随机值导致画面抖动。

Purpose: Generate visually varied but reproducible quality scores, avoiding frame jitter from random values on each refresh.

原理：线性同余公式 (readId×17 + pos×31 + 7) % 23 以 readId 和碱基位置 pos 为种子，产生 0~22 的确定性伪随机数，加上基础值 18 得到 Q18~Q40 的 Phred 分数范围。选用质数 17、31 是为了减少同余值的规律性重复。

Principle: The linear congruential formula (readId×17 + pos×31 + 7) % 23 uses readId and base position pos as seeds to produce deterministic pseudo-random numbers from 0 to 22, plus a base value of 18 to yield Phred scores in the Q18–Q40 range. Primes 17 and 31 are chosen to reduce periodic repetition in congruential values.

算法：makeRead — 读段对象构造Algorithm: makeRead — Read Object Construction

function makeRead(id, start, len, muts = []) {
  // 1. 从参考序列切片
  const bases = REF.slice(start, start + len).split('');

  // 2. 注入指定的突变/错误（相对位置）
  muts.forEach(([relPos, alt]) => { bases[relPos] = alt; });

  // 3. 生成每个位置的质量分数
  const seq  = bases.join('');
  const qual = bases.map((_, i) => genQual(id, i));

  return { id, start, seq, qual, len: seq.length, muts };
}

muts 参数格式：[ [relPos, altBase], ... ]，relPos 是相对于 read 起始位置的偏移量。

muts parameter format: [ [relPos, altBase], ... ], where relPos is the offset relative to the read start position.

SNP 注入逻辑：对于覆盖位置 24（SNP_POS）的 reads，将该位置的绝对坐标减去 start 得到相对位置，再将对应碱基改为 SNP_ALT ('A')：

SNP injection logic: For reads covering position 24 (SNP_POS), subtract start from the absolute coordinate to get the relative position, then change the corresponding base to SNP_ALT ('A'):

// 例：Read 6，start=19，SNP全局位置24，相对位置 = 24-19 = 5
makeRead(6, 19, 15, [[SNP_POS-19, SNP_ALT]])
//                      ↑ = [5, 'A'] → 第6个碱基 G→A

SIGNAL_DATA 生成逻辑SIGNAL_DATA Generation Logic

const SIGNAL_DATA = SBS_GROWING.slice(0, 8).map((base, pos) => {
  const noise = (pos * 7 + 3) % 15;
  const s = {
    A: 5 + noise % 8,        // 背景噪声：5~12
    T: 5 + (noise+3) % 8,
    C: 5 + (noise+5) % 8,
    G: 5 + (noise+2) % 8,
  };
  s[base] = 85 + (pos * 3) % 12;  // 正确碱基信号：85~96（远高于背景）
  return { base, signals: s };
});

模拟 Illumina 荧光检测的信噪比特征：正确碱基信号强度约为背景的 8~12 倍，这是实际测序中 Q30 以上碱基的典型信噪比水平。

Simulates the signal-to-noise ratio characteristics of Illumina fluorescence detection: the correct base signal intensity is approximately 8–12 times the background, which is the typical SNR level for bases with Q30 or above in actual sequencing.

⚙️文件：js/app.jsFile: js/app.js

代码组织（按行号）Code Organization (by Line Number)

🖼️核心算法：SVG 渲染引擎Core Algorithm: SVG Rendering Engine

所有图形通过字符串拼接生成 SVG 标记，写入 <svg> 的 innerHTML。引擎由 7 个基础原语函数 + 2 个高阶函数组成。

All graphics are generated as SVG markup via string concatenation and written to the innerHTML of <svg>. The engine consists of 7 primitive functions + 2 higher-order functions.

基础原语函数Drawing Primitives

R(x, y, w, h, fill, rx=0, extra='') → string

T(x, y, s, fill, size, anchor, weight, family, extra) → string

text-anchor 控制水平对齐：'start'（左对齐）、'middle'（居中）、'end'（右对齐）。注意 SVG 文本 y 坐标是基线（baseline）位置，而非顶部，因此文本居中需要 y + fontSize/2 的视觉补偿。

text-anchor controls horizontal alignment: 'start' (left), 'middle' (center), 'end' (right). Note that SVG text y-coordinate is the baseline position, not the top, so centering text requires a visual offset of y + fontSize/2.

L(x1,y1,x2,y2, stroke, w, extra) → string

生成 <line>。常用 extra='stroke-dasharray="4,3"' 绘制虚线（用于断点标记、连接线等）。

Generates <line>. Commonly uses extra='stroke-dasharray="4,3"' to draw dashed lines (for breakpoints, connectors, etc.).

C / P / G / anim

高阶函数：drawBase / drawSeqHigher-Order Functions: drawBase / drawSeq

drawBase(x, y, base, bw=17, bh=22, showLabel=true) → string

function drawBase(x, y, base, bw=17, bh=22, showLabel=true) {
  const c = BASE_COLOR[base] || '#555';   // 未知碱基降级为灰色
  let out = R(x, y, bw-1, bh, c, 2);         // 宽度 -1 制造间距

  if (showLabel) {
    // 字号根据方块高度自适应
    const fs = bh < 18 ? 8 : (bh < 24 ? 10 : 12);
    // 文字在方块中垂直居中（baseline补偿 = fs/2 - 1）
    out += T(x+bw/2-0.5, y+bh/2+fs/2-1, base, '#fff', fs, 'middle', 'bold');
  }
  return out;
}

字号自适应：方块高度 bh < 18 → 字号 8；18 ≤ bh < 24 → 字号 10；bh ≥ 24 → 字号 12。这使同一函数可用于小型 pileup 视图（bh=16）和大型演示视图（bh=30）。

Adaptive font size: block height bh < 18 → font 8; 18 ≤ bh < 24 → font 10; bh ≥ 24 → font 12. This allows the same function to be used for small pileup views (bh=16) and large demo views (bh=30).

drawSeq(x, y, seq, bw, bh, showLabels) → string

对序列字符串逐字符调用 drawBase，以 i*bw 的横向偏移排列，是一个纯粹的 map+join 操作。

Calls drawBase for each character in the sequence string, arranged with horizontal offset i*bw, a pure map+join operation.

qChar(q) → string

function qChar(q) { return String.fromCharCode(q + 33); }

实现 FASTQ Phred33 编码规范：Q值 + 33 = ASCII码。例如 Q30 → ASCII 63 → 字符 '?'；Q40 → ASCII 73 → 字符 'I'。

Implements the FASTQ Phred33 encoding standard: Q value + 33 = ASCII code. For example, Q30 → ASCII 63 → character '?'; Q40 → ASCII 73 → character 'I'.

1️⃣渲染算法：步骤1 DNA片段化Rendering Algorithm: Step 1 DNA Fragmentation

函数签名：renderStep1(substep: 0|1|2|3) → string

Function signature: renderStep1(substep: 0|1|2|3) → string

坐标系设计Coordinate System Design

// viewBox: 800×380，DNA居中绘制
const bpW = 15;                        // 每个碱基方块宽度
const totalW = REF.length * bpW;       // 总宽度 = 39×15 = 585px
const sx = (W - totalW) / 2;          // 水平居中起点 ≈ 107.5
const topY = H/2 - bpH - sGap;        // 正链 Y 坐标
const botY = H/2 + sGap;              // 互补链 Y 坐标

各帧逻辑Per-Frame Logic

2️⃣渲染算法：步骤2 文库构建Rendering Algorithm: Step 2 Library Prep

函数签名：renderStep2(substep: 0|1|2|3) → string

Function signature: renderStep2(substep: 0|1|2|3) → string

以参考序列前10bp（REF.slice(0,10)）为演示片段。互补链由 COMPLEMENT 映射计算。

Uses the first 10bp of the reference sequence (REF.slice(0,10)) as the demo fragment. The complementary strand is computed via the COMPLEMENT mapping.

3️⃣渲染算法：步骤3 SBS测序Rendering Algorithm: Step 3 SBS Sequencing

函数签名：renderStep3(substep: 0|1|2|3|4|5) → string

Function signature: renderStep3(substep: 0|1|2|3|4|5) → string

已合成碱基数量计算Synthesized Base Count Calculation

const numCycles = substep === 0
  ? 0
  : Math.min(substep * 2, 8);
// substep 1 → 2个循环
// substep 2 → 4个循环
// substep 3 → 6个循环
// substep 4 → 8个循环（上限）
// substep 5 → 8个循环（显示完整结果）

每个 substep 增加 2 个循环，使动画节奏适中（5帧展示8个碱基的合成过程）。

Each substep adds 2 cycles, keeping the animation pace moderate (5 frames to show the synthesis of 8 bases).

模板与合成链关系Template and Growing Chain Relationship

模板链（5'→3'）: A  T  C  G  A  A  C  G  T  T  A  C
互补链（3'→5'）: T  A  G  C  T  T  G  C  A  A  T  G
                 ↑每次掺入互补碱基，从左到右逐步显示

聚合酶位置逻辑Polymerase Position Logic

聚合酶（🧬 图标 + 半透明矩形）始终显示在合成链当前末端的下一个位置：px = startX + numCycles * bpW，当 numCycles === 8 时隐藏（合成完毕）。

The polymerase (🧬 icon + semi-transparent rectangle) is always shown at the next position after the current end of the growing chain: px = startX + numCycles * bpW, hidden when numCycles === 8 (synthesis complete).

信号条形图Signal Bar Chart

在合成链下方绘制已完成循环的信号条：每个位置取 SBS_GROWING[i] 对应的颜色，绘制一个高 24px 的彩色矩形，直观表示"相机检测到的颜色→碱基"的对应关系。

Signal bars for completed cycles are drawn below the growing chain: each position uses the color corresponding to SBS_GROWING[i], drawing a 24px-tall colored rectangle that visually represents the "camera-detected color → base" correspondence.

4️⃣渲染算法：步骤4 碱基识别与质控Rendering Algorithm: Step 4 Base Calling & QC

函数签名：renderStep4(substep: 0|1|2|3) → string

Function signature: renderStep4(substep: 0|1|2|3) → string

5️⃣渲染算法：步骤5 序列比对Rendering Algorithm: Step 5 Alignment

函数签名：renderStep5(substep: 0|1|2|3|4) → string

Function signature: renderStep5(substep: 0|1|2|3|4) → string

可见reads计算Visible Reads Calculation

const visibleReads =
  substep === 0 ? 0 :
  substep === 1 ? 3 :
  substep === 2 ? 6 : 9;   // substep 3和4都显示全部9条

每帧递增显示 3 条 reads，模拟比对算法逐步将 reads 定位到参考上的过程。

Each frame incrementally displays 3 reads, simulating the alignment algorithm gradually mapping reads to the reference.

错配检测与高亮Mismatch Detection and Highlighting

for (let j = 0; j < read.len; j++) {
  const globalPos = read.start + j;
  const base      = read.seq[j];
  const refBase   = REF[globalPos];
  const isMismatch = (base !== refBase);

  // 错配碱基：降低透明度 + 红色边框
  R(x, ry2, bpW-1, bpH, BASE_COLOR[base] + (isMismatch ? '' : '77'), 2,
    isMismatch ? 'stroke="#f85149" stroke-width="1.2"' : '');
}

正常碱基颜色加 '77' 十六进制透明度（约47%）降低视觉权重，错配碱基保持全色并添加红色边框，引导注意力。

Normal bases have '77' hex transparency (about 47%) added to reduce visual weight, while mismatched bases retain full color and get a red border to draw attention.

SNP 位置高亮（substep 4）SNP Position Highlighting (substep 4)

在 substep 4 额外绘制一个纵向半透明矩形覆盖 SNP 列（从参考序列到所有 reads），颜色为 rgba(248,81,73,0.08)（极低透明度红色），配合虚线边框形成视觉焦点，并在底部显示等位基因统计数。

In substep 4, an additional vertical semi-transparent rectangle is drawn covering the SNP column (from reference to all reads), colored rgba(248,81,73,0.08) (very low transparency red), with a dashed border to create visual focus, and allele counts displayed at the bottom.

6️⃣渲染算法：步骤6 变异识别Rendering Algorithm: Step 6 Variant Calling

函数签名：renderStep6(substep: 0|1|2|3) → string

Function signature: renderStep6(substep: 0|1|2|3) → string

SNP 位点数据汇总（所有帧共用）SNP Site Data Summary (Shared Across All Frames)

const snpBases = [];
READS.forEach(r => {
  // 判断 read 是否覆盖 SNP 位置
  if (r.start <= SNP_POS && SNP_POS < r.start + r.len) {
    snpBases.push({
      readId: r.id,
      base:   r.seq[SNP_POS - r.start]  // 绝对坐标 → 相对坐标
    });
  }
});
// 结果：5条reads覆盖，其中G=2，A=3

▶️核心算法：动画状态机Core Algorithm: Animation State Machine

播放系统是一个基于 setTimeout 递归调用的简单状态机：

The playback system is a simple state machine based on recursive setTimeout calls:

function advanceFrame() {
  if (!isPlaying) return;              // 守卫：已暂停则退出

  const maxSub = STEPS[curStep].substepLabels.length - 1;

  if (curSub < maxSub) {
    // 同一步骤内前进一帧
    curSub++;
    render();
    playTimer = setTimeout(advanceFrame, PLAY_INTERVAL);  // 2200ms后继续

  } else if (curStep < STEPS.length - 1) {
    // 当前步骤最后一帧 → 跳到下一步骤第一帧
    curStep++; curSub = 0;
    render();
    playTimer = setTimeout(advanceFrame, PLAY_INTERVAL);

  } else {
    // 所有步骤全部播放完毕 → 自然停止
    pausePlay();
  }
}

pausePlay 的重要性Importance of pausePlay

function pausePlay() {
  isPlaying = false;
  clearTimeout(playTimer);   // ← 关键：取消待执行的回调
  updateButtons();
}

🗺️核心算法：导航系统Core Algorithm: Navigation System

步骤间导航与跨步骤子帧导航Inter-Step Navigation and Cross-Step Sub-Frame Navigation

导航系统实现了连续的线性遍历——subNext() 在当前步骤的最后一帧时，会自动跳到下一步骤的第一帧，形成流畅的全流程浏览体验：

The navigation system implements continuous linear traversal — subNext() automatically jumps to the first frame of the next step when at the last frame of the current step, creating a smooth full-pipeline browsing experience:

function subNext() {
  pausePlay();
  const maxSub = STEPS[curStep].substepLabels.length - 1;

  if (curSub < maxSub) {
    curSub++;                    // 步骤内前进
    render();
  } else if (curStep < STEPS.length - 1) {
    curStep++; curSub = 0;       // 跨步骤前进
    render();
  }
  // 否则：已在最后一帧，不操作
}

步骤导航栏动态生成Dynamic Step Navigation Bar Generation

function updateStepNav() {
  STEPS.forEach((s, i) => {
    const div = document.createElement('div');
    // CSS类：active（当前）/ done（已完成）/ 无类（未访问）
    div.className = 'step-item' +
      (i === curStep ? ' active' : i < curStep ? ' done' : '');
    div.addEventListener('click', () => goToStep(i));
    inner.appendChild(div);
  });
}

每次 render() 都重新生成导航栏（清空后重建），确保状态与 curStep 完全同步，无需维护复杂的差量更新逻辑。

Each render() call regenerates the navigation bar (clear and rebuild), ensuring state is fully in sync with curStep, eliminating the need for complex differential update logic.

键盘快捷键Keyboard Shortcuts

e.preventDefault() 阻止空格键滚动页面的默认行为。

e.preventDefault() prevents the default page-scrolling behavior of the spacebar.

📐数据结构速查Data Structure Reference

ReadObj（读段对象）ReadObj (Read Object)

StepObj（步骤配置对象）StepObj (Step Configuration Object)

SignalDataObj（荧光信号对象）SignalDataObj (Fluorescence Signal Object)

应用状态（全局变量）Application State (Global Variables)

⌨️键盘快捷键Keyboard Shortcuts

🔧扩展指南Extension Guide

新增一个可视化步骤Adding a New Visualization Step

只需在 js/app.js 的 STEPS 数组中追加一个配置对象：

Simply append a configuration object to the STEPS array in js/app.js:

// 在 STEPS 数组末尾添加：
{
  title: '步骤 7：基因注释（Gene Annotation）',
  desc:  '将识别到的变异与基因功能数据库比对',
  substepLabels: [
    '加载基因组注释数据库',
    '变异位点落入基因区域',
    '功能预测完成'
  ],
  theory: `<div class="tsec"><h4>...</h4><p>...</p></div>`,
  render: renderStep7   // 新建对应渲染函数
}

然后实现 renderStep7(substep) 函数，返回 SVG 字符串即可。无需修改任何其他代码，导航系统自动适配。

Then implement the renderStep7(substep) function to return an SVG string. No other code changes needed; the navigation system adapts automatically.

修改播放速度Changing Playback Speed

// app.js 顶部的常量：
const PLAY_INTERVAL = 2200;  // 改为 1000 可加快，3000 可放慢（单位ms）

修改 Mock 数据Modifying Mock Data

添加连续动画Adding Continuous Animations

当前系统使用离散帧模型，如需在两帧之间添加 CSS 过渡动画：

The current system uses a discrete frame model. To add CSS transition animations between frames:

/* 在 style.css 中为 SVG 容器添加 */
#vis-area svg {
  transition: opacity 0.3s ease;
}
/* 在 app.js render() 中触发：*/
svg.style.opacity = '0';
setTimeout(() => {
  svg.innerHTML = step.render(curSub);
  svg.style.opacity = '1';
}, 150);

添加数据说明文档链接（本文档的集成方式）Adding Documentation Link (How This Document Is Integrated)

本文档通过在 index.html 的 header 区域添加 <a> 标签链接实现集成，无需任何路由框架：

This document is integrated by adding an <a> tag link in the header area of index.html, without any routing framework:

<!-- index.html header 内 -->
<a href="docs.html" class="doc-btn">📄 技术文档</a>

docs.html 作为独立页面，不依赖 app.js，可独立访问和打印。

docs.html is a standalone page, independent of app.js, and can be accessed and printed independently.