diff --git a/AGENTS.md b/AGENTS.md index 310441a..7692c87 100644 --- 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 index 14df4ff..2986dba 100644 --- 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 index b5081e3..fd27ace 100644 --- 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) { 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 index e55ac89..e40687d 100644 --- 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 index d176c67..a0aee27 100644 --- 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 ) { + 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 index e106b04..622a4c8 100644 --- 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 起支持圈选 | ### 初始化时序图