structrail-design/.trae/documents/sdk-visual-noise-handling.md

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。
• 用户体验：

  // 用户只需在初始化时声明一次
  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 处理（变灰/折叠）。

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