refactor(tracers): 统一命令字段名并重构数组追踪器创建逻辑

- 将所有命令的 `params` 字段重命名为 `payload`，以保持命名一致性 - 将 `ArrayTracerCreateOptions` 从联合类型简化为单一接口，移除 `array` 参数，新增 `initial` 和 `walker` 参数 - 引入 `buildInitial` 函数集中处理初始数组的构建逻辑 - 使用 `metadata` 对象管理数组长度状态，替代独立的 `arrayLength` 变量 - 更新错误消息格式，移除方括号前缀 - 调整泛型参数，使 `createArrayTracer` 更通用
docs: 优化开发规则与项目介绍文档的表述
2026-03-04 02:34:12 +08:00 · 2026-03-02 21:06:36 +08:00 · 2026-02-24 20:33:59 +08:00 · 2026-02-23 13:03:22 +08:00
6 changed files with 68 additions and 54 deletions
--- a/.trae/rules/development-rules.md
+++ b/.trae/rules/development-rules.md
@@ -1,7 +1,6 @@
 # 开发规则

- **严禁主动修改任何项目源代码文件（如 .ts, .js, .c, .h 等）。当前工作仅限于文档编写（.md）和方案讨论。所有代码示例仅能在对话中展示，不得写入文件。**
- 在考虑API的移植性时，需要特别考虑C语言，当然，各类主流的编程语言要需要纳入考虑范围，包括但不限于：
+- 在设计协议和API时，我们需要考虑API的移植性，尤其需要特别关注C语言，因为C语言的语法表达力不算强。当然，各类主流的编程语言都需要纳入考虑范围，包括但不限于：
  - C++
  - Java
  - C#
--- a/.trae/rules/project-introduction.md
+++ b/.trae/rules/project-introduction.md
@@ -6,10 +6,10 @@

 基于上述设想，我肯定无法接受从编译技术的角度去适配每一种编程语言(例如代码插桩甚至改造编译器)，因为这会导致平台的开发变得非常复杂，维护成本也会非常高。因此我的想法是设计一套语言无关的协议，用来描述各种数据结构的变化(跟踪器)，因此这套协议会定义需要支持的数据结构类型，以及每一种数据结构类型需要支持的操作指令，并且我倾向于将指令设计得更加“底层”一些，类似于“原语”的概念。

-> 例如针对顺序表结构，我可能会定义 pick(获取元素)、drop(取消获取)、patch(修改元素) 指令来替代 swap(交换元素) 操作，因为交换两个元素的本质就是 获取元素 + 修改元素，而我在其中添加 drop 指令的目的则是使可视化过程更加具体，例如 pick 指令会将其选定的元素高亮，那么 drop 指令就可以取消该元素的高亮行为。
+> 例如针对顺序表结构，我可能会定义pick(获取元素)、drop(取消获取)、patch(修改元素)指令来替代swap(交换元素)操作，因为交换两个元素的本质就是获取元素+修改元素，而我在其中添加rop指令的目的则是使可视化过程更加具体，例如pick指令会将其选定的元素高亮，那么drop指令就可以取消该元素的高亮行为。

-我们会先选取一种编程语言(例如 TypeScript)来实现这套协议，在实现的过程中，需要考虑到未来将添加其他编程语言的支持，因此需要考虑到不同编程语言之间的差异，例如语法/类型系统差异，进而反过来优化这套协议，以使其能够更好地支持不同的编程语言，这是一个双向的过程。
+我们会先选取一种编程语言(例如TypeScript)来实现这套协议，在实现的过程中，需要考虑到未来将添加其他编程语言的支持，因此需要考虑到不同编程语言之间的差异，例如语法/类型系统差异，进而反过来优化这套协议，以使其能够更好地支持不同的编程语言，这是一个双向的过程。

-当我们实现了这套协议后，就形成了一套 SDK，用户可以在平台中标记想要记录的数据结构(注册跟踪器)，并调用 SDK 提供的 API 来记录数据结构的变化，当代码被编译运行后，就能够自然地获取数据结构的变化过程(序列化为 JSON)。
+当我们实现了这套协议后，就形成了一套SDK，用户可以在平台中标记想要记录的数据结构(注册跟踪器)，并调用SDK提供的API来记录数据结构的变化，当代码被编译运行后，就能够自然地获取数据结构的变化过程(序列化为JSON)。

 所以本项目的最终目标就是设计这一套语言无关的协议，并在多个主流编程语言上实现该协议。
--- a/.trae/rules/tracer-type.md
+++ b/.trae/rules/tracer-type.md
@@ -1,6 +1,6 @@
 ## Tracer 是什么？

-Tracer 代表一个数据结构变化的跟踪器，用户可以通过调用 Tracer 提供的 API 来记录数据结构的变化。每当用户想要记录一个数据结构的变化时，就需要创建一个对应的 Tracer。这种将数据结构变化的记录留给用户的设计，使得用户可以在算法的实现中灵活地记录数据结构的变化，从而降低对原有算法代码逻辑的侵入性，同时也在一定程度上提高了可视化效果的灵活度，用户可以自由控制记录数据结构变化的时机。
+Tracer代表一个数据结构变化的跟踪器，用户可以通过调用Tracer提供的API来记录数据结构的变化。每当用户想要记录一个数据结构的变化时，就需要创建一个对应的Tracer。这种将数据结构变化的记录留给用户的设计，使得用户可以在算法的实现中灵活地记录数据结构的变化，从而降低对原有算法代码逻辑的侵入性，同时也在一定程度上提高了可视化效果的灵活度，用户可以自由控制记录数据结构变化的时机。

 ## Tracer 类型

@@ -12,8 +12,5 @@ Tracer 代表一个数据结构变化的跟踪器，用户可以通过调用 Tra
 - LinkTracer: 链表
 - TreeTracer: 树
 - GraphTracer: 图
-
---
-
 - LogTracer: 日志
 - ControlTracer: 控制
--- a/tracers.ts/src/context/tracer-context.ts
+++ b/tracers.ts/src/context/tracer-context.ts
@@ -56,6 +56,12 @@ const createTracerContext = () => {
    };
  };

+  // 由于JavaScript/TypeScript在语言层面缺乏统一的“程序退出钩子”机制，
+  // 所以我们无法在算法执行结束后自动地输出指令序列和异常信息，
+  // 尽管像Node.js这样的运行时提供了process.on('exit')，但是我们希望保持SDK的环境无关性，
+  // 所以为了不依赖于特定运行时的API，我们设计了scope方法来创建一个显式的生命周期，
+  // 算法逻辑将会被一个回调函数包裹，作为routine参数，
+  // 在routine执行完毕后，scope会向外输出指令序列和异常信息。
  const scope = (routine: () => void | Promise<void>) => {
    if (scopeResult.state === SCOPE_STATE.SCOPED) {
      throw new ScopeError('ScopeError: Detect multiple scope.');
@@ -67,19 +73,24 @@ const createTracerContext = () => {
    // 如果routine是同步函数，那可能会抛出同步错误，所以需要用try-catch包裹
    try {
      const result = routine();
+      // 如果routine是异步函数，需要用catch捕获异步错误
      if (result instanceof Promise) {
        result
+          .then(() => {
+            scopeResult.state = SCOPE_STATE.SCOPED;
+            flush();
+          })
          .catch((error) => {
+            // 如果是ScopeError，需要抛出，否则会在嵌套调用scope时被外层scope捕获
            if (error instanceof ScopeError) {
              throw error;
            }
            scopeResult.exception.stack = (error as Error).stack;
-          })
-          .finally(() => {
            scopeResult.state = SCOPE_STATE.SCOPED;
            flush();
          });
      } else {
+        // 如果routine是同步函数，执行完成后需要设置scope状态
        scopeResult.state = SCOPE_STATE.SCOPED;
        flush();
      }
--- a/tracers.ts/src/tracers/array-tracer.ts
+++ b/tracers.ts/src/tracers/array-tracer.ts
@@ -1,44 +1,51 @@
 import { getTracerContext } from '../context';
 import type { JsonValue } from '../types';

-interface BaseArrayTracerCreateOptions {
+interface ArrayTracerCreateOptions<T extends JsonValue> {
  description?: string;
+  initial?: T[];
+  walker?: (builder: { add: (item: T) => void }) => void;
 }

-interface ArrayTracerCreateOptionsFromArray<
-  T extends JsonValue[],
-> extends BaseArrayTracerCreateOptions {
-  array: T;
-  walker?: never;
-}
+type ArrayTracerMetadata = {
+  // initial: JsonValue[];
+  length: number;
+};

-interface ArrayTracerCreateOptionsFromWalker<
-  T extends JsonValue[],
-> extends BaseArrayTracerCreateOptions {
-  array?: never;
-  walker: (commit: (item: T[number]) => void) => void;
-}
-
-type ArrayTracerCreateOptions<T extends JsonValue[]> =
-  | ArrayTracerCreateOptionsFromArray<T>
-  | ArrayTracerCreateOptionsFromWalker<T>;
-
-export const createArrayTracer = <T extends JsonValue[]>(
+export const createArrayTracer = <T extends JsonValue = JsonValue>(
  options: ArrayTracerCreateOptions<T>,
 ) => {
-  const { description, array, walker } = options;
+  const { description, initial, walker } = options;
  const tracer = crypto.randomUUID();

-  // 优化：仅维护数组长度作为影子状态，这在 C++/Java 等强类型语言中也极易实现（仅需一个 int 变量）
-  // 这种“最小必要状态”策略既能实现越界校验，又避免了在强类型语言中处理泛型存储的复杂性，且内存开销极低。
-  let arrayLength = array ? array.length : 0;
+  const metadata: ArrayTracerMetadata = {
+    length: 0,
+  };
+
+  const buildInitial = () => {
+    if (!!initial) {
+      return [...initial];
+    }
+    if (!!walker) {
+      const initial: T[] = [];
+      walker({
+        add: (item) => {
+          initial.push(item);
+        },
+      });
+      return initial;
+    }
+    return [];
+  };
+
+  // console.log(_initial);

  const { command } = getTracerContext();

  const validateIndex = (index: number) => {
-    if (index < 0 || index >= arrayLength) {
+    if (index < 0 || index >= metadata.length) {
      throw new Error(
-        `[ArrayTracer] Index out of bounds: index ${index} is not within [0, ${arrayLength})`,
+        `ArrayTracer: Index out of bounds: index ${index} is not within [0, ${metadata.length})`,
      );
    }
  };
@@ -47,18 +54,18 @@ export const createArrayTracer = <T extends JsonValue[]>(
    type: 'ArrayTracer',
    tracer: tracer,
    action: 'create',
-    params: {
+    payload: {
      description: description ?? 'ArrayTracer',
-      array: array ?? [],
+      initial: buildInitial(),
    },
  });

  // size 为正时，数组长度增加；为负时，数组长度减少（但不能小于 0）
  const scale = (size: number) => {
-    arrayLength += size;
-    if (arrayLength < 0) {
+    metadata.length += size;
+    if (metadata.length < 0) {
      throw new Error(
-        `[ArrayTracer] Invalid size: ${size}, array length cannot be negative`,
+        `ArrayTracer: Invalid size: ${size}, array length cannot be negative`,
      );
    }

@@ -66,7 +73,7 @@ export const createArrayTracer = <T extends JsonValue[]>(
      type: 'ArrayTracer',
      tracer: tracer,
      action: 'scale',
-      params: {
+      payload: {
        size: size,
      },
    });
@@ -79,7 +86,7 @@ export const createArrayTracer = <T extends JsonValue[]>(
      type: 'ArrayTracer',
      tracer: tracer,
      action: 'pick',
-      params: {
+      payload: {
        index: index,
      },
    });
@@ -92,20 +99,20 @@ export const createArrayTracer = <T extends JsonValue[]>(
      type: 'ArrayTracer',
      tracer: tracer,
      action: 'drop',
-      params: {
+      payload: {
        index: index,
      },
    });
  };

-  const patch = (index: number, value: T[number]) => {
+  const patch = (index: number, value: T) => {
    validateIndex(index);

    command({
      type: 'ArrayTracer',
      tracer: tracer,
      action: 'patch',
-      params: {
+      payload: {
        index: index,
        value: value,
      },
@@ -119,7 +126,7 @@ export const createArrayTracer = <T extends JsonValue[]>(
      type: 'ArrayTracer',
      tracer: tracer,
      action: 'unset',
-      params: {
+      payload: {
        index: index,
      },
    });
--- a/tracers.ts/src/types/array-tracer.ts
+++ b/tracers.ts/src/types/array-tracer.ts
@@ -6,36 +6,36 @@ type BaseArrayTracerCommand = BaseTracerCommand & {

 type ArrayTracerCreateCommand = BaseArrayTracerCommand & {
  action: 'create';
-  params: {
+  payload: {
    description: string;
-    array: JsonValue[];
+    initial: JsonValue[];
  };
 };

 type ArrayTracerScaleCommand = BaseArrayTracerCommand & {
  action: 'scale';
-  params: {
+  payload: {
    size: number;
  };
 };

 type ArrayTracerPickCommand = BaseArrayTracerCommand & {
  action: 'pick';
-  params: {
+  payload: {
    index: number;
  };
 };

 type ArrayTracerDropCommand = BaseArrayTracerCommand & {
  action: 'drop';
-  params: {
+  payload: {
    index: number;
  };
 };

 type ArrayTracerPatchCommand = BaseArrayTracerCommand & {
  action: 'patch';
-  params: {
+  payload: {
    index: number;
    value: JsonValue;
  };
@@ -43,7 +43,7 @@ type ArrayTracerPatchCommand = BaseArrayTracerCommand & {

 type ArrayTracerUnsetCommand = BaseArrayTracerCommand & {
  action: 'unset';
-  params: {
+  payload: {
    index: number;
  };
 };
Author	SHA1	Message	Date
skycurtain	9aad52347b	refactor(tracers): 统一命令字段名并重构数组追踪器创建逻辑 - 将所有命令的 `params` 字段重命名为 `payload`，以保持命名一致性 - 将 `ArrayTracerCreateOptions` 从联合类型简化为单一接口，移除 `array` 参数，新增 `initial` 和 `walker` 参数 - 引入 `buildInitial` 函数集中处理初始数组的构建逻辑 - 使用 `metadata` 对象管理数组长度状态，替代独立的 `arrayLength` 变量 - 更新错误消息格式，移除方括号前缀 - 调整泛型参数，使 `createArrayTracer` 更通用	2026-03-04 02:34:12 +08:00
skycurtain	2dfc4ced67	docs: 优化开发规则与项目介绍文档的表述 - 移除关于禁止修改源代码的临时限制说明，该限制已不再适用 - 统一并优化多处中文标点与空格的格式，使文档更整洁 - 调整项目介绍中关于协议设计的表述，使其更清晰准确 - 合并`tracer-type.md`中的分隔线，使列表结构更紧凑	2026-03-02 21:06:36 +08:00
skycurtain	19d4b97669	fix(tracer): 修复异步scope中异常处理后的状态设置问题发生ScopeError时不执行flush，否则即便抛出异常也会执行flush	2026-02-24 20:33:59 +08:00
skycurtain	8a2399e890	docs(tracer-context): 添加详细的中文注释说明scope的设计原理和实现细节。	2026-02-23 13:03:22 +08:00