Skip to content

chore: 精简 agent skill 体系 + 手表(wearable)适配与示例 - #52

Open
YoloMao wants to merge 4 commits into
masterfrom
chore/streamline-agent-skills
Open

chore: 精简 agent skill 体系 + 手表(wearable)适配与示例#52
YoloMao wants to merge 4 commits into
masterfrom
chore/streamline-agent-skills

Conversation

@YoloMao

@YoloMao YoloMao commented Aug 12, 2026

Copy link
Copy Markdown
Collaborator

本 PR 含三块相对独立的变更,可分别 review。


一、精简 agent skill 体系为单会话工作流

现有 agent 体系依赖 subagent 编排:4 个编排类 skill + 3 个 .claude/agents 定义 + 一个 SessionStart hook。实际使用中维护成本高于收益:多层 subagent 转发丢上下文;"Planning Gate" 抽象散落在多个 skill 中互相引用,改一处要同步改四处;prompt 模板与 skill 正文大量重复。

变更 说明
删除 subagent 编排 skill sdk-code-review / subagent-driven-development / plan-document-review / receiving-code-review / using-growingio-sdk-skills
删除 agent 定义与 hook .claude/agents/*.md.claude/hooks/session-start.sh,并清理 settings.json
新增 docs/sdk-review-checklist.md 用自查清单替代 code-reviewer subagent
新增 docs/skills-overview.md 流程与 skill 清单,替代 docs/agents-skills-flow.md
精简保留的 skill 移除 "Planning Gate" 抽象,直接写明触发条件
索引更新 AGENTS.md / docs/sdk-engineering-guide.md

不涉及 SDK 源码。


二、声明 wearable 设备类型支持

问题

两个 HAR 的 deviceTypes 只声明了 default / tablet / 2in1module.json5deviceTypes 不可缺省,且各模块都必须包含将要安装的设备类型 —— 宿主手表 App 即使自己声明了 wearable,依赖 GrowingAnalytics 时仍会在打包/安装阶段被拦下。

能力核对

按 DevEco SDK 内 device-define/ 的权威 SysCap 定义核对(HarmonyOS 6.0.0 / API 20):

设备 SysCap 数量
phone 439
wearable 270
liteWearable 17

SDK 依赖的 21 项 SysCap 全部在 wearable 支持列表内Web.Webview.CoreRelationalStore.CorePreferences.CoreNetManager.Core / NetStackArkUI.ArkUI.FullCryptoFrameworkUtils.Lang 等)。手表缺失的 182 项集中在 AI、Camera、Payment、Stylus、AR 等方向,与数据采集无关。

注意区分:liteWearable(手环)仅 17 项能力,无 ArkUI.Full / RelationalStore / Webview。网上"鸿蒙手表不支持 WebView"的说法指的是 liteWearable,不在本次支持范围内。

验证

两个模块各跑 baseline / +wearable 的 --no-incremental 全量构建做差分:

模块 baseline syscap 警告 +wearable 新增警告 新增 ArkTS 错误
GrowingAnalytics 16 16 0 0
GrowingToolsKit 14 14 0 0

产物已验证:package/src/main/module.json -> ['default', 'tablet', '2in1', 'wearable']


三、新增 entry_wearable 手表示例(不采集无埋点)

新增 entry_wearable 模块(deviceTypes: ["wearable"]),演示在不采集无埋点的前提下接入 SDK。按官方多设备工程结构与 entry 拆开:UI 与交互层无法跨设备复用。

关掉无埋点的正确做法

SDK 有两道独立开关,本 demo 两道都关:

  1. config.autotrackEnabled = false —— 默认值,控制回调内部是否继续处理,但不阻止监听注册
  2. 不调用 GrowingAnalytics.onWindowStageCreate —— 决定性的一步

第 2 点是关键。该方法是 Autotrack.startObserver 的唯一调用方,内部挂 4 个 UIObserver 回调:willClicknavDestinationUpdatenavDestinationSwitchrouterPageUpdate仅设 autotrackEnabled = false 而仍然调用它,这 4 个回调依然会注册,每次点击与路由跳转都会进入 SDK 回调再被开关拦下 —— 白白付出唤醒成本。手表 CPU 与续航更紧张,不调用即零注册。

不调用不影响其余功能:手动埋点、会话、设备信息、事件入库与上报由 AnalyticsCore.setLifecycleCallback 内部注册,与 Autotrack 是两条独立链路。

其余手表端适配

配置 原因
hybridAutotrackEnabled false 手表无 WebView 场景
dataUploadInterval 60s(手机端 15s) 减少网络唤醒,照顾续航
GrowingToolsKit 插件 不挂载 悬浮窗形态,手表屏幕放不下
UI 中心竖列 + 放大点按区域 圆屏四角不放内容,避免误触

页面浏览用自定义事件承载

关闭无埋点后 SDK 不再产生 PAGE 事件,公开 API 中也没有手动页面上报接口(trackFlutterPage 仅供 Flutter 桥接)。

这是有意为之,不为手表端新增手动 PAGE 接口。 手表应用页面层级浅、停留短,PAGE 事件的分析价值不足以支撑一个新的公开 API。demo 以 page_view 自定义事件承载,字段命名(page_name / page_show_timestamp)与 PAGE 对齐便于后端归类。

验证

assembleHap 构建通过,产物 module.jsondeviceTypes["wearable"],本模块零 syscap 警告。


全 PR 未覆盖 / 待真机验证

  • deviceInfo.deviceType 实际返回值,以及后端埋点协议是否接受 wearable 枚举
  • 圆形屏幕下 display.getDefaultDisplaySync() 的返回值
  • 弱网 / 息屏场景下事件入库与补发行为
  • 全仓 canIUse 使用 0 次,官方要求的跨设备三步校验尚未引入

顺带发现(既有问题,非本 PR 引入)

两个 HAR 合计 30 处 syscap 警告全部指向 @hms.collaboration.rcpThe system capacity of this api 'rcp' is not supported on all devicesCollaboration.RemoteCommunication 在 default / tablet / 2in1 / phone 上都不在要求能力集内,即上报通道当前已依赖一个"并非所有设备都支持"的 API。建议单开 issue 跟进。

🤖 Generated with Claude Code

YoloMao and others added 2 commits August 12, 2026 14:11
原有的 agent 体系依赖 subagent 编排(sdk-code-review / subagent-driven-development /
plan-document-review / receiving-code-review 四个 skill + code-reviewer、spec-reviewer、
engineering-harmonyos-sdk-engineer 三个 agent 定义 + SessionStart hook),实际使用中
维护成本高于收益:多层 subagent 转发丢上下文,"Planning Gate" 这类抽象概念散落在多个
skill 里互相引用,改一处要同步改四处。

改为单会话工作流:

- 删除 subagent 编排相关 skill 与 .claude/agents 定义、session-start.sh hook
- 审查环节由 subagent 改为对照 docs/sdk-review-checklist.md 自查(新增)
- 流程与 skill 清单收敛到 docs/skills-overview.md(新增),替代 docs/agents-skills-flow.md
- 剩余 skill 中移除 "Planning Gate" 抽象,直接写明触发条件(改动 ≥3 文件或公开 API 变更)
- AGENTS.md / docs/sdk-engineering-guide.md 补充两份新文档的索引

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
两个 HAR 的 deviceTypes 此前只声明了 default/tablet/2in1。module.json5 的
deviceTypes 不可缺省,且各模块都必须包含将要安装的设备类型,因此宿主手表 App
即使自己声明了 wearable,依赖 GrowingAnalytics 时仍会在打包/安装阶段被拦下。

按 DevEco SDK 内 device-define/ 的权威 SysCap 定义核对(HarmonyOS 6.0.0/API 20):
wearable 支持 270 项能力,SDK 依赖的 21 项(Web.Webview.Core、
RelationalStore.Core、Preferences.Core、NetManager.Core/NetStack、ArkUI.Full、
CryptoFramework、Utils.Lang 等)全部在列,手表缺失的 182 项集中在 AI、Camera、
Payment、Stylus 等方向,与数据采集无关。

两个模块各跑了 baseline / +wearable 的全量构建做差分,新增 syscap 警告 0 条、
新增 ArkTS 错误 0 条,deviceTypes 正确落入 HAR 产物。

注意:liteWearable(手环,仅 17 项能力,无 ArkUI.Full / RelationalStore /
Webview)不在本次支持范围内。示例应用 entry 未加 wearable——按官方多设备工程
结构,手表应另开独立 entry module。运行时行为(无埋点 willClick/FrameNode、
deviceType 枚举上报、屏幕尺寸兜底)仍需真机验证。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@YoloMao YoloMao changed the title chore: 精简 agent skill 体系为单会话工作流 chore: 精简 agent skill 体系 + 声明 wearable 设备类型支持 Aug 12, 2026
新增手表端示例模块 entry_wearable(deviceTypes: ["wearable"]),演示在不采集
无埋点的前提下接入 GrowingAnalytics。按官方多设备工程结构与 entry 拆开:UI 与
交互层无法跨设备复用,手机端仍由 entry 承载。

关闭无埋点的正确做法是两道开关都关:

1. config.autotrackEnabled = false(默认值,此处显式写出表明有意为之)
2. 不调用 GrowingAnalytics.onWindowStageCreate —— 这才是决定性的一步

第 2 点是关键。该方法是无埋点 UI 监听的唯一注册入口(Autotrack.startObserver
的唯一调用方),内部挂 4 个 UIObserver 回调:willClick、navDestinationUpdate、
navDestinationSwitch、routerPageUpdate。仅设 autotrackEnabled = false 而仍调用
它,回调依然注册,每次点击与路由跳转都会进入 SDK 回调再被开关拦下。手表 CPU 与
续航更紧张,不调用即零注册。

不调用不影响其余功能:手动埋点、会话、设备信息、事件入库与上报由
AnalyticsCore.setLifecycleCallback 内部注册,与 Autotrack 是两条独立链路。

其余手表端适配:hybridAutotrackEnabled 关闭(无 WebView 场景)、
dataUploadInterval 放宽到 60s 减少网络唤醒、不挂载 GrowingToolsKit(悬浮窗形态
手表放不下)、圆屏 UI 内容集中在中心竖列并放大点按区域。

已知缺口:关闭无埋点后 SDK 不再产生 PAGE 事件,而公开 API 中没有手动页面上报
接口,demo 暂以 page_view 自定义事件承载,字段命名与 PAGE 对齐。若手表端确需
标准 PAGE 事件,需另行开放公开 API。

验证:assembleHap 构建通过,产物 module.json 的 deviceTypes 为 ["wearable"],
本模块零 syscap 警告。运行时行为(deviceType 实际取值、圆屏 display 返回值)
仍需真机确认。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@YoloMao YoloMao changed the title chore: 精简 agent skill 体系 + 声明 wearable 设备类型支持 chore: 精简 agent skill 体系 + 手表(wearable)适配与示例 Aug 12, 2026
原措辞把「无手动 PAGE 接口」写成待决策的缺口,暗示后续会补。实际决定是不为
手表端新增该接口:手表应用页面层级浅、停留短,PAGE 事件的分析价值不足以支撑
一个新的公开 API,页面维度用自定义事件承载即可。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant