skycurtain
a9eaaa6023
- 新增品牌命名、商业化策略、SDK视觉噪音处理、可视化库设计和系统架构文档 - 更新开发规则，明确禁止主动修改项目源代码文件 - 所有文档均为中文编写，用于记录项目设计讨论和决策
54 lines
3.4 KiB
Markdown
54 lines
3.4 KiB
Markdown
# 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 处理**（变灰/折叠）。
|
||
|
||
这种策略既保留了代码的“可编程性”和“原生手感”，又解决了视觉干扰问题。
|