feat: 新增 GraphTracer 并重构 ArrayTracer 的初始化方式

- 新增 GraphTracer 及其类型定义，支持图的创建和操作命令
- 重构 ArrayTracer 的 create 函数，使用 walker/commit 模式替代直接的 array 参数，提高灵活性
- 更新类型导出和命令联合类型以包含 GraphTracer
- 调整示例代码以使用新的初始化方式

tracers.ts/src/index.ts

@@ -9,7 +9,12 @@ const controlTracer = createControlTracer({ description: 'ControlTracer' });
 
 const arrayTracer = createArrayTracer({
   description: 'ArrayTracer',
-  array: [1, 2, 3],
+  // array: [1, 2, 3],
+  walker: (commit) => {
+    commit(1);
+    commit(2);
+    commit(3);
+  },
 });
 
 arrayTracer.patch(0, 100);

tracers.ts/src/tracers/array-tracer.ts

@@ -1,15 +1,32 @@
 import { getTracerContext } from '../context';
 import type { JsonValue } from '../types';
 
-interface ArrayTracerCreateOptions<T extends JsonValue[]> {
+interface BaseArrayTracerCreateOptions {
   description?: string;
-  array?: T;
 }
 
+interface ArrayTracerCreateOptionsFromArray<
+  T extends JsonValue[],
+> extends BaseArrayTracerCreateOptions {
+  array: T;
+  walker?: never;
+}
+
+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[]>(
   options: ArrayTracerCreateOptions<T>,
 ) => {
-  const { description, array } = options;
+  const { description, array, walker } = options;
   const tracer = crypto.randomUUID();
 
   // 优化：仅维护数组长度作为影子状态，这在 C++/Java 等强类型语言中也极易实现（仅需一个 int 变量）

tracers.ts/src/tracers/graph-tracer.ts

@@ -0,0 +1,33 @@
+import { getTracerContext } from '../context';
+import type { GraphTracerGraph } from '../types';
+
+interface GraphTracerCreateOptions {
+  description?: string;
+  graph?: GraphTracerGraph;
+}
+
+// 不要了，改为 walker/commit 方案
+// TODO: 后续我们会添加创建图的辅助函数
+// export const createGraphTracerHelper = () => {};
+
+export const createGraphTracer = (options: GraphTracerCreateOptions) => {
+  const { description, graph } = options;
+  const tracer = crypto.randomUUID();
+
+  const { command } = getTracerContext();
+
+  command({
+    type: 'GraphTracer',
+    tracer: tracer,
+    action: 'create',
+    params: {
+      description: description ?? 'GraphTracer',
+      graph: graph ?? {
+        directed: false,
+        weighted: false,
+        nodes: [],
+        edges: [],
+      },
+    },
+  });
+};

tracers.ts/src/tracers/index.ts

@@ -1,3 +1,4 @@
 export * from './array-tracer';
 export * from './control-tracer';
+export * from './graph-tracer';
 export * from './log-tracer';

tracers.ts/src/types/command.ts

@@ -1,8 +1,10 @@
 import type { ArrayTracerCommand } from './array-tracer';
 import type { ControlTracerCommand } from './control-tracer';
+import type { GraphTracerCommand } from './graph-tracer';
 import type { LogTracerCommand } from './log-tracer';
 
 export type TracerCommand =
-  | ArrayTracerCommand
   | LogTracerCommand
-  | ControlTracerCommand;
+  | ControlTracerCommand
+  | ArrayTracerCommand
+  | GraphTracerCommand;

tracers.ts/src/types/common.ts

@@ -6,7 +6,7 @@ export type JsonValue =
   | JsonValue[]
   | { [key: string]: JsonValue };
 
-export type TracerType = 'ArrayTracer' | 'LogTracer' | 'ControlTracer';
+export type TracerType = 'LogTracer' | 'ControlTracer' | 'ArrayTracer' | 'GraphTracer';
 
 export type TracerId = ReturnType<typeof crypto.randomUUID>;
 

tracers.ts/src/types/graph-tracer.ts

@@ -0,0 +1,94 @@
+import type { BaseTracerCommand, JsonValue } from './common';
+
+export type GraphTracerGraphNode = {
+  id: string;
+  value: JsonValue;
+};
+
+export type GraphTracerGraphEdge = {
+  source: string;
+  target: string;
+  weight: JsonValue;
+};
+
+export type GraphTracerGraph = {
+  directed: boolean;
+  weighted: boolean;
+  nodes: GraphTracerGraphNode[];
+  edges: GraphTracerGraphEdge[];
+};
+
+type BaseGraphTracerCommand = BaseTracerCommand & {
+  type: 'GraphTracer';
+};
+
+type GraphTracerCreateCommand = BaseGraphTracerCommand & {
+  action: 'create';
+  params: {
+    description: string;
+    graph: GraphTracerGraph;
+  };
+};
+
+type GraphTracerInsertCommand = BaseGraphTracerCommand & {
+  action: 'insert';
+  params: {};
+};
+
+type GraphTracerRemoveCommand = BaseGraphTracerCommand & {
+  action: 'remove';
+  params: {};
+};
+
+type GraphTracerUpdateCommand = BaseGraphTracerCommand & {
+  action: 'update';
+  params: {};
+};
+
+type GraphTracerConnectCommand = BaseGraphTracerCommand & {
+  action: 'connect';
+  params: {};
+};
+
+type GraphTracerDisconnectCommand = BaseGraphTracerCommand & {
+  action: 'disconnect';
+  params: {};
+};
+
+type GraphTracerWeightCommand = BaseGraphTracerCommand & {
+  action: 'weight';
+  params: {};
+};
+
+type GraphTracerVisitCommand = BaseGraphTracerCommand & {
+  action: 'visit';
+  params: {};
+};
+
+type GraphTracerLeaveCommand = BaseGraphTracerCommand & {
+  action: 'leave';
+  params: {};
+};
+
+type GraphTracerPickCommand = BaseGraphTracerCommand & {
+  action: 'pick';
+  params: {};
+};
+
+type GraphTracerDropCommand = BaseGraphTracerCommand & {
+  action: 'drop';
+  params: {};
+};
+
+export type GraphTracerCommand =
+  | GraphTracerCreateCommand
+  | GraphTracerInsertCommand
+  | GraphTracerRemoveCommand
+  | GraphTracerUpdateCommand
+  | GraphTracerConnectCommand
+  | GraphTracerDisconnectCommand
+  | GraphTracerWeightCommand
+  | GraphTracerVisitCommand
+  | GraphTracerLeaveCommand
+  | GraphTracerPickCommand
+  | GraphTracerDropCommand;

tracers.ts/src/types/index.ts

@@ -2,4 +2,5 @@ export * from './array-tracer';
 export * from './command';
 export * from './common';
 export * from './control-tracer';
+export * from './graph-tracer';
 export * from './log-tracer';