From 8a2399e8906224894cbea2826f0395b71f883035 Mon Sep 17 00:00:00 2001
From: skycurtain <skycurtain@163.com>
Date: Mon, 23 Feb 2026 13:03:22 +0800
Subject: [PATCH] =?UTF-8?q?docs(tracer-context):=20=E6=B7=BB=E5=8A=A0?=
 =?UTF-8?q?=E8=AF=A6=E7=BB=86=E7=9A=84=E4=B8=AD=E6=96=87=E6=B3=A8=E9=87=8A?=
 =?UTF-8?q?=E8=AF=B4=E6=98=8Escope=E7=9A=84=E8=AE=BE=E8=AE=A1=E5=8E=9F?=
 =?UTF-8?q?=E7=90=86=E5=92=8C=E5=AE=9E=E7=8E=B0=E7=BB=86=E8=8A=82=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tracers.ts/src/context/tracer-context.ts | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/tracers.ts/src/context/tracer-context.ts b/tracers.ts/src/context/tracer-context.ts
index c4947a1..51ad4d6 100644
--- a/tracers.ts/src/context/tracer-context.ts
+++ b/tracers.ts/src/context/tracer-context.ts
@@ -56,6 +56,13 @@ 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 +74,23 @@ const createTracerContext = () => {
     // 如果routine是同步函数，那可能会抛出同步错误，所以需要用try-catch包裹
     try {
       const result = routine();
+      // 如果routine是异步函数，需要用catch捕获异步错误
       if (result instanceof Promise) {
         result
           .catch((error) => {
+            // 如果是ScopeError，需要抛出，否则会在嵌套调用scope时被外层scope捕获
             if (error instanceof ScopeError) {
               throw error;
             }
             scopeResult.exception.stack = (error as Error).stack;
           })
           .finally(() => {
+            // 无论是否有异常，都需要设置本次的scope状态
             scopeResult.state = SCOPE_STATE.SCOPED;
             flush();
           });
       } else {
+        // 如果routine是同步函数，执行完成后需要设置scope状态
         scopeResult.state = SCOPE_STATE.SCOPED;
         flush();
       }