# SDK 视觉噪音处理策略

## 1. 问题背景
在算法可视化场景中，为了记录数据结构变化，需要在用户算法代码中插入 SDK 调用（如 `tracer.patch()`, `tracer.pick()`）。过多的 SDK 调用代码会产生“视觉噪音”，破坏算法逻辑的连贯性，增加认知负担，与平台“低侵入性”和“原生体验”的设计目标冲突。

## 2. 核心原则
- **原生优先 (Native First)**：尽量利用编程语言特性实现隐式追踪，避免引入非标准的封装数据结构（如避免强制用户使用 `MyArray.set()` 替代 `arr[]`）。
- **显式降噪 (Explicit Reduction)**：在无法隐式追踪的场景下，通过 IDE 的视觉设计弱化 SDK 代码的存在感。
- **可编程性保留**：承认并保留显式调用 SDK 的必要性（用于精细控制动画或处理不支持的语言特性），将其视为“高级功能”而非“噪音”。

## 3. 分级解决方案

### 3.1 Level 1: 隐式追踪 (Implicit Tracing) —— 零侵入
利用现代编程语言的高级特性（代理、重载、魔术方法），拦截原生数据结构的读写操作，自动触发可视化事件。
- **适用场景**：
    - **JavaScript / TypeScript**: 使用 `Proxy` 对象拦截数组/对象操作。
    - **C++**: 使用运算符重载（`operator[]`, `operator=`）封装 `std::vector` 或自定义容器。
    - **Python**: 使用魔术方法（`__getitem__`, `__setitem__`）封装 `list`。
- **用户体验**：
    ```typescript
    // 用户只需在初始化时声明一次
    const tracer = new ArrayTracer().watch(arr); 
    // 后续全是原生代码，无感知
    arr[i] = arr[j]; 
    ```

### 3.2 Level 2: 显式调用 (Explicit Call) —— 精细控制
对于不支持隐式拦截的语言特性（如 Java 原生数组、C 语言指针），或者用户需要插入非数据结构操作的指令（如 `tracer.delay()`, `tracer.log()`），必须使用显式 SDK 调用。
- **适用场景**：
    - Java 原生数组 (`int[]`)。
    - C 语言指针操作。
    - 算法逻辑之外的控制指令（暂停、日志、自定义高亮）。
- **代码规范**：
    - 保持 SDK 调用独立成行，避免嵌套在复杂逻辑中。
    - 命名保持简洁（如 `tracer.patch` 而非 `Visualizer.getInstance().updateElement`）。

### 3.3 Level 3: IDE 视觉降噪 (Visual Noise Reduction)
在 Web IDE 层面通过 UI/UX 设计，将显式 SDK 调用代码“隐形”或“弱化”。
- **幽灵文本 (Ghost Text)**：将检测到的 SDK 调用行渲染为低对比度颜色（如浅灰色，opacity: 0.5），使视线自然聚焦于算法逻辑。
- **代码折叠 (Code Folding)**：
    - 提供“专注模式”开关，一键折叠所有 SDK 调用行。
    - 在行号区域标记 SDK 调用，鼠标悬停时才高亮显示。
- **分离视图 (Split View) [可选]**：
    - **算法视图**：仅显示纯算法逻辑（隐藏 SDK 调用）。
    - **完整视图**：显示包含 Tracer 调用的完整代码，供调试使用。

## 4. 结论
不应为了消除噪音而发明一套蹩脚的封装 API。正确的路径是：
1.  **能隐式则隐式**（JS/Py/C++ Proxy）。
2.  **不能隐式则显式**（Java/C 原生操作）。
3.  **显式噪音交给 IDE 处理**（变灰/折叠）。

这种策略既保留了代码的“可编程性”和“原生手感”，又解决了视觉干扰问题。