growingio · YoloMao · Jul 8, 2026 · Jul 8, 2026 · Jul 9, 2026 · Jul 9, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -20,3 +20,10 @@
 > - `docs/sdk-critical-rules.md` — 修改核心模块 **必读**（SDK 设计红线 + ArkTS 开发规范）
 > - `docs/sdk-doc-routing.md` — 按场景读取的模块文档索引表
 > - `docs/sdk-build-commands.md` — hvigor 构建命令速查
+
+## 注释纪律
+
+- **不写解释性注释**：协议依据、设计动机、"对齐 iOS xxx"等背景信息一律放 commit message，不放代码
+- 该规则**同样适用于 `docs/` 模块文档中的伪代码块**——文档会被读入上下文，冗余注释同样浪费 token
+- 允许保留的仅限：承载协议语义的短字段注释（如 `// 仅 NewSaaS`），且需遵循所在文件既有风格
+- 清理注释时核查范围 = 全分支 diff（源码 + 文档）：`git diff master...HEAD | grep -E '^\+.*//'`
diff --git a/GrowingAnalytics/src/main/ets/components/circle/Circle.ets b/GrowingAnalytics/src/main/ets/components/circle/Circle.ets
@@ -308,6 +308,8 @@ export default class Circle implements PluginsInterface, WebSocketCallbackInterf
   private _handleMessage(message: Message) {
     if (message.msgType == 'ready') {
       this._startCircling()
+    } else if (message.msgType == 'quit') {
+      this.stop('当前设备已与Web端断开连接，如需继续圈选请扫码重新连接')
     } else if (message.msgType == 'incompatible_version') {
       this._showIncompatibleVersion()
     }

diff --git a/GrowingAnalytics/src/main/ets/components/circle/CircleElement.ets b/GrowingAnalytics/src/main/ets/components/circle/CircleElement.ets
@@ -63,6 +63,8 @@ export default class CircleElement {
 
   static setPagesAndElementsForFlutter(screenshot: RefreshScreenshot, data: Map<string, Object>) {
     try {
+      let context = GrowingContext.getDefaultContext() as GrowingContext
+      let isCDP = context.config.mode == ConfigMode.CDP
       let width = data.get("width") as number | undefined
       let height = data.get("height") as number | undefined
       let scale = data.get("scale") as number | undefined
@@ -87,9 +89,13 @@ export default class CircleElement {
           let height = pageData.get("height") as number | undefined
           let path = pageData.get("path") as string | undefined
           let title = pageData.get("title") as string | undefined
+          let isIgnored = pageData.get("isIgnored") as boolean | undefined
 
           if (left != undefined && top != undefined && width != undefined && height != undefined && path != undefined) {
             let page = new _ScreenshotPage(left, top, width, height, path, title)
+            if (isIgnored != undefined) {
+              page.isIgnored = isIgnored
+            }
             pages.push(page)
           }
         }
@@ -117,8 +123,9 @@ export default class CircleElement {
           let height = elementData.get("height") as number | undefined
           let page = elementData.get("page") as string | undefined
 
-          if (nodeType != undefined && zLevel != undefined && xpath != undefined && xcontent != undefined) {
-            let element = new _ScreenshotElement(nodeType, domain ?? AppInfo.domain, zLevel, xpath, xcontent)
+          if (nodeType != undefined && zLevel != undefined && xpath != undefined && (isCDP || xcontent != undefined)) {
+            let element = new _ScreenshotElement(nodeType, domain ?? AppInfo.domain, zLevel, xpath,
+              isCDP ? undefined : xcontent)
             if (index != undefined) {
               element.index = index
             }
@@ -249,7 +256,7 @@ export default class CircleElement {
         domain,
         zLevel,
         xpath,
-        xcontent,
+        context.config.mode == ConfigMode.NewSaaS ? xcontent : undefined,
       )
       let rect = CircleElement._parseRectString(e.rect)
       element.left = rect.left
@@ -673,6 +680,7 @@ class _ScreenshotPage {
   height: number
   path: string
   title?: string
+  isIgnored?: boolean
 
   constructor(
     left: number,
@@ -696,7 +704,7 @@ class _ScreenshotElement {
   domain: string
   zLevel: number
   xpath: string
-  xcontent: string
+  xcontent?: string
   index?: number
   content?: string
   parentXPath?: string
@@ -715,7 +723,7 @@ class _ScreenshotElement {
     domain: string,
     zLevel: number,
     xpath: string,
-    xcontent: string,
+    xcontent?: string,
   ) {
     this.nodeType = nodeType
     this.domain = domain

diff --git a/GrowingAnalytics/src/main/ets/components/core/AnalyticsCore.ets b/GrowingAnalytics/src/main/ets/components/core/AnalyticsCore.ets
@@ -83,7 +83,7 @@ export default class AnalyticsCore implements GrowingAnalyticsInterface {
       // 仅支持 NewSaaS 和 CDP
       plugins.push(new MobileDebugger())
     }
-    if ((config.mode == ConfigMode.NewSaaS || config.mode == ConfigMode.SaaS) && config.autotrackEnabled) {
+    if (config.autotrackEnabled) {
       plugins.push(new Circle())
     }
     Plugins.registerPlugins(plugins)

diff --git a/docs/GrowingAnalytics/circle/Circle.md b/docs/GrowingAnalytics/circle/Circle.md
@@ -128,11 +128,11 @@ class _ScreenshotElement {
   domain: string                // 应用包名
   zLevel: number                // 层级
   xpath: string                 // XPath 路径
-  xcontent: string              // XContent 路径
+  xcontent?: string             // XContent 路径（仅 NewSaaS）
   index?: number                // 列表索引
   content?: string              // 文本内容
   parentXPath?: string          // 父 XPath
-  parentXContent?: string       // 父 XContent
+  parentXContent?: string       // 父 XContent（仅 NewSaaS）
   isContainer?: boolean         // 是否容器
   left/top/width/height: number // 位置尺寸
   page: string                  // 所属页面
@@ -144,6 +144,7 @@ class _ScreenshotPage {
   left/top/width/height: number // 页面位置尺寸
   path: string                  // 页面路径
   title?: string                // 页面标题
+  isIgnored?: boolean           // 页面是否被忽略
 }
 ```
 
@@ -961,6 +962,9 @@ static setPagesAndElementsForFlutter(
   screenshot: RefreshScreenshot, 
   data: Map<string, Object>
 ) {
+  let context = GrowingContext.getDefaultContext() as GrowingContext
+  let isCDP = context.config.mode == ConfigMode.CDP
+
   // 屏幕信息
   let width = data.get("width") as number
   let height = data.get("height") as number
@@ -995,7 +999,7 @@ static setPagesAndElementsForFlutter(
       elementData.get("domain") ?? AppInfo.domain,  // 优先用元素自带 domain
       elementData.get("zLevel"),
       elementData.get("xpath"),
-      elementData.get("xcontent")
+      isCDP ? undefined : elementData.get("xcontent")
     )
     // 设置其他属性...
     elements.push(element)
@@ -1083,6 +1087,7 @@ stop(error?: string) {
 |---------|---------|
 | WebSocket 连接失败 | 显示"服务器链接失败"对话框 |
 | WebSocket 断开 | 显示"设备已断开连接"提示 |
+| Web 端退出圈选（NewSaaS/CDP `quit`，SaaS `editor_quit`） | 停止圈选，显示"设备已断开连接"提示 |
 | 版本不兼容 | 显示升级 SDK 提示，自动断开连接 |
 | 窗口未就绪 | 延迟 300ms 重试连接 |
 | 滚动中 | 暂停截图，滚动结束后再刷新 |

diff --git a/docs/GrowingAnalytics/core/AnalyticsCore.md b/docs/GrowingAnalytics/core/AnalyticsCore.md
@@ -208,8 +208,8 @@ static startCore(context: Context, config: GrowingConfig) {
   if (config.mode != ConfigMode.SaaS) {
     plugins.push(new MobileDebugger())  // 仅 NewSaaS 和 CDP
   }
-  if ((config.mode == ConfigMode.NewSaaS || config.mode == ConfigMode.SaaS) && config.autotrackEnabled) {
-    plugins.push(new Circle())  // NewSaaS 或 SaaS 且开启无埋点
+  if (config.autotrackEnabled) {
+    plugins.push(new Circle())  // NewSaaS、SaaS、CDP 均支持，需开启无埋点
   }
 
   // 2. 注册插件
@@ -261,7 +261,7 @@ static startCore(context: Context, config: GrowingConfig) {
 | 模式 | MobileDebugger | Circle | 说明 |
 |------|---------------|--------|------|
 | NewSaaS | ✅ | ✅ (需 autotrack) | 支持圈选和调试器 |
-| CDP | ✅ | ❌ | 仅支持调试器 |
+| CDP | ✅ | ✅ (需 autotrack) | 支持圈选和调试器 |
 | SaaS | ❌ | ✅ (需 autotrack) | 自 v2.8.0 起支持圈选 |
 
 ### 初始化时序图