harmony-next

HarmonyOS NEXT Agent 指南

使用此技能，结合随附的离线参考资料回答 HarmonyOS NEXT 相关问题。控制上下文规模：先判断请求类型，然后仅打开回答问题或执行操作所需的特定 Markdown 文件。

references/... 和 scripts/... 这类路径均相对于此技能目录：即包含此 SKILL.md 的目录。将该目录解析一次并设为 HARMONY_NEXT_SKILL_DIR。不要假定当前仓库根目录下存在 harmony-next/。官方扫描位置包括 $REPO_ROOT/.agents/skills/harmony-next、$HOME/.agents/skills/harmony-next 和 /etc/codex/skills/harmony-next。

# Directory containing this SKILL.md (the file you loaded).
HARMONY_NEXT_SKILL_DIR="<skill-dir>"

无论当前工作目录是什么（包括普通应用仓库根目录），都应使用 $HARMONY_NEXT_SKILL_DIR。随附的操作手册必须在可执行路径中使用此变量；若操作手册中硬编码了仓库根目录下的技能路径前缀，则视为可移植性问题。

版本

当前本地技能版本：v1.3.37。

参考资料快照：随附的 references/ 是 HarmonyOS API 12-23 的离线快照，并非实时网页文档。HarmonyOS SDK 26.0.0（API 26.0.0）已于 2026-08-29 正式发布；API 26 声明页面已收录在 references/JsEtsAPIReference/api26/ 下；完整指南和示例仍在待补充中。

对于“最新”“当前”、新 API 或与在线文档的一致性等问题，请将此本地版本与 GitHub Releases 或 nightly 版本进行比较，并在需要精确性时通过华为在线文档核实 API 行为。

API 26 发布跟踪与适配说明：references/harmonyos-releases/api-26-release.md。

安装／更新入口：

• Vercel Labs skills CLI：npx skills add linhay/harmony-next.skills --skill harmony-next；如需以非交互方式全局安装 Claude Code，请添加 -a claude-code -g -y --copy；如需安装 Codex，请添加 -a codex -g -y --copy。
• Gemini CLI：gemini skills install https://github.com/linhay/harmony-next.skills --path harmony-next --scope user
• Claude Code：使用 npx skills add linhay/harmony-next.skills --skill harmony-next -a claude-code -g -y --copy；Claude.ai 仍可通过上传发布包 harmony-next.skill.zip 进行安装。
• Codex：使用 npx skills add linhay/harmony-next.skills --skill harmony-next -a codex -g -y --copy，或将 harmony-next/ 放入／符号链接到官方 Codex 扫描位置，例如 $REPO_ROOT/.agents/skills/harmony-next、$HOME/.agents/skills/harmony-next 或 /etc/codex/skills/harmony-next；如需可重复使用的可安装分发包，请将其打包为 Codex 插件。

路由

1. 对用户请求分类

   • API、组件、错误或代码示例：使用 KITS.md、TASK_MAP.md 和 INDEX.md；不要读取 DevEco 操作手册。
   • 最小项目样板、Empty Ability 脚手架、HDC/uitest 冒烟测试应用，或可复制的 HarmonyOS 测试项目：使用 references/quickStart/ets/minimal-project-scaffold.md 和 references/templates/empty-ability-app/。
   • DevEco Studio IDE、插件、本地服务、CodeGenie、MCP、LanceDB、devecostudio://、UxTestService，或离线 UI/UX 审查：阅读 IDE 操作手册。
   • HarmonyOS 命令行工具下载、压缩包安装、PATH 设置，或 codelinter -v 验证：阅读 references/ideGuides/独立命令行工具配置手册.md，并使用 scripts/commandline_tools_manager.py。
   • HarmonyOS 模拟器、HVD、hdc、uitest、aa、bm、hilog 或 hidumper 自动化：阅读模拟器操作手册。
   • ArkWeb/WebView DevTools 转发、CDP Runtime.evaluate，或 H5 桥接字段到达证明：阅读 references/ideGuides/ArkWeb WebView CDP调试与字段到达证明.md。
   • 未知领域：从 references/TASK_MAP.md 开始，然后通过 references/INDEX.md 进一步查找。

2. 选择最精简的索引

   • Kit 导航：references/KITS.md
   • 任务导向：references/TASK_MAP.md

3. 查找目标文件

   • 全库路径清单：references/INDEX.md
   • JS/ETS API 分类清单：references/JsEtsAPIReference/INDEX.md

4. 仅打开目标参考资料 references/JsEtsAPIReference/ 目前主要包含 modules/、topics/、types/、errors/、guides/。

   • guides/ 包含离线指南页面，可替代常见的官方在线指南链接。

查找命令

从此 SKILL.md 中解析出 HARMONY_NEXT_SKILL_DIR 后：

• 先按关键词匹配路径：rg -n "UIAbility|AbilityStage|Want" "$HARMONY_NEXT_SKILL_DIR/references/INDEX.md" | head
• 查找某个 @ohos.* 模块：rg -n "@ohos\\.app\\.ability\\.|@ohos\\.ability\\." "$HARMONY_NEXT_SKILL_DIR/references/INDEX.md" | rg "JsEtsAPIReference/" | head
• 查找 NDK/C API 头文件：rg -n "JsEtsAPIReference/topics/.*/.*\\.h\\.md$" "$HARMONY_NEXT_SKILL_DIR/references/INDEX.md" | rg "(napi|arkui|window|ability)" | head

工具脚本技能

在手动编写 DevEco 设置命令之前，先使用这些由脚本提供的技能条目。它们是针对不稳定本地工具的精简封装；当环境缺失时，应返回结构化状态。

用户意图	脚本技能	Agent 首条命令	用户交接
下载、安装、配置或验证 HarmonyOS Command Line Tools	commandline_tools_manager.py	python3 "$HARMONY_NEXT_SKILL_DIR/scripts/commandline_tools_manager.py" doctor --tools-root <dir> --json	如果用户提供华为下载中心页面 URL，返回脚本的受阻结果，并请用户登录、复制归档文件的直接 URL，或提供本地归档文件。
列出、克隆、删除、诊断或启动本地 DevEco HVD 实例	hvd_manager.py	python3 "$HARMONY_NEXT_SKILL_DIR/scripts/hvd_manager.py" doctor --json	如果缺少 HVD 根目录、Emulator、SDK/镜像根目录或跟踪启动数据，请报告 issues、recommendations 和 missingConfig 字段，并请用户传入 --root、--emulator、--sdk-root / --image-root 或匹配的环境变量。
收集有限范围的 HDC 设备证据，或诊断 WebView DevTools 转发	device_evidence_bundle.py	python3 "$HARMONY_NEXT_SKILL_DIR/scripts/device_evidence_bundle.py" doctor --deveco-app <DevEco-Studio.app> --json	仅当可以在本地存储原始本地屏幕截图、布局树、应用状态和有限范围的日志时，才使用 capture ... --artifact-dir <dir>。使用 webview-devtools ... --artifact-dir <dir> 对套接字/fport/HTTP 发现结果进行分类。
执行一次有限范围的 UI 操作，并提供操作前后的证据	device_ui_action.py	python3 "$HARMONY_NEXT_SKILL_DIR/scripts/device_ui_action.py" tap --deveco-app <DevEco-Studio.app> --target <target> --artifact-dir .hvigor/outputs/<run> --text "<visible-text>" --json	必须且只能指定一个目标选择器或原始设备坐标。将返回的屏幕截图尺寸视为坐标空间；绝不要重复使用缩放预览坐标。
捕获正在运行的 HarmonyOS 页面，并运行离线 UI/UX 审计报告	ux_audit_pipeline.py	python3 "$HARMONY_NEXT_SKILL_DIR/scripts/ux_audit_pipeline.py" doctor --deveco-app <DevEco-Studio.app> --python <python-with-ux-deps> --json	对于单步执行路径，使用 python3 "$HARMONY_NEXT_SKILL_DIR/scripts/ux_audit_pipeline.py" capture-audit --deveco-app <DevEco-Studio.app> --python <python-with-ux-deps> --target <target> --artifact-dir .hvigor/outputs/<run> --json。如果缺少 Python 图像处理模块，请报告 missingConfig=["uxPythonDependencies"]，不要将 UxTestService 视为已损坏。
将离线 DevEco Profiler 跟踪文件转换为 SQLite 证据摘要	profiler_trace_audit.py	python3 "$HARMONY_NEXT_SKILL_DIR/scripts/profiler_trace_audit.py" doctor --deveco-app <DevEco-Studio.app> --json	如果缺少 trace_streamer 或输入跟踪文件，请报告机器可读的 blocked 负载。仅对现有的 .ftrace / .htrace / bytrace / rawtrace 文件使用 audit --input <trace> --output-dir .hvigor/outputs/<run> --json。

边界：

• commandline_tools_manager.py 只能下载直接指向归档文件的 URL；下载中心页面 URL 是需要登录的页面，并非归档文件。
• hvd_manager.py launch-preflight 会在外部跟踪辅助工具已就绪时，打印受保护的 Emulator 命令计划。
• hvd_manager.py launch 目前会创建启动跟踪套接字，分离 Emulator 和跟踪保持进程，使用 -t <trace-name> 启动 Emulator，并等待 HDC、启动和稳定状态，除非传入 --no-wait-target。
• device_evidence_bundle.py 用于采集证据，而非控制应用生命周期：它可以将真实的 UI、布局和日志工件保存到明确指定的工件目录，但不会安装、卸载、启动、停止或修改应用。
• device_evidence_bundle.py webview-devtools 可以创建一个范围受限的 fport；默认情况下，它只会移除本次运行创建的转发。它会输出套接字、过期转发、HTTP 重置／拒绝／超时以及无效 JSON 的失败代码。
• device_ui_action.py 会在操作前后采集布局、截图和范围受限的日志，并且只执行一次 uitest uiInput 点按、滑动或按键事件。坐标必须是来自布局边界的原始设备像素，或明确输入的设备空间坐标。
• ux_audit_pipeline.py 将 device_evidence_bundle.py 与 DevEco UxTestService 组合使用：它会在导入前将 tools/UxTestService 复制到工件目录，因此不会修改 DevEco .app 捆绑包。
• 如果任一封装脚本返回 blocked，Agent 应在放弃前尝试 HarmonyOS 官方 CLI 证据命令：hdc list targets -v、hdc -t <target> shell uitest dumpLayout ...、screenCap、file recv、bm dump、aa dump 和范围受限的 hilog。
• 如果封装脚本受阻、存在误导或缺少有用的工作流，请使用脚本 feedback JSON 字段或 ISSUE_GUIDE.md 中针对具体场景的 GitHub 问题表单；如果具备 GitHub 访问权限且上下文充分，请使用 gh 直接创建问题或发表评论，保留结构化字段并遵循脱敏规则。
• profiler_trace_audit.py 仅用于离线处理：它会运行 DevEco trace_streamer，在 DevEco .app 捆绑包之外写入 SQLite／JSON 工件，不会启动 DevEco Studio 或连接设备，也不会声称支持 GUI Profiler 无界面导入。
• 生命周期方向：未来的 CLI 工作应优先采用终端会话作用域内的前台启动模式，由前台运行器持有跟踪套接字、等待就绪，并在终端会话结束时调用 Emulator -stop <hvd-name> -path <hvd-root>；仅将分离模式保留为明确的兼容路径。
• hvd_manager.py download-image 会以机器可读的 blocked 状态报告 HVD 镜像下载；目前已验证的路径是 DevEco Studio SDK Manager UI，而非稳定的无界面 CLI。
• 为支持跨机器使用，回答和文档应优先采用 doctor --json 输出，而非硬编码 macOS 路径。

API 26 声明快照同步：运行 python3 "$HARMONY_NEXT_SKILL_DIR/scripts/sync_api26_snapshot.py" --deveco-app <DevEco-Studio.app>，然后运行 python3 "$HARMONY_NEXT_SKILL_DIR/scripts/reference_compat.py" generate 重建索引。

最小空 Ability 脚手架

当 Agent 需要一个可复制的 HarmonyOS NEXT 冒烟测试夹具，且不想打开 DevEco Studio 时使用：

• 脚手架指南：references/quickStart/ets/minimal-project-scaffold.md
• 可复制模板：references/templates/empty-ability-app/
• 默认值：bundleName com.example.emptyability、模块 entry、Ability EntryAbility、兼容 SDK 5.0.0(12)、目标 SDK 5.0.0(12)。
• 路由/组件拆分：pages/Index.ets 仅作为 @Entry 路由页面，并挂载 SmokeCounter()；components/SmokeCounter.ets 管理冒烟测试 UI 状态和节点 ID。
• 验证入口：ohpm install、hvigorw --mode module -p module=entry@default assembleHap、HDC 安装/启动、uitest dumpLayout 和 uitest screenCap。
• SDK 覆盖验证：对于 HarmonyOS 6.0.2 / API 22 等目标 SDK，将复制的夹具中的 compatibleSdkVersion 和 targetSdkVersion 设为 6.0.2(22)，并将 DEVECO_SDK_HOME 设为 SDK 根目录，例如 DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk，而不是 sdk/default。
• API 22 架构兼容性取决于应用和 Ability 图标：保留模板中的 AppScope/resources/base/media/app_icon.png、应用 icon、Ability icon 和 startWindowIcon。
• 稳定的冒烟测试 UI 信号：Harmony Smoke Ready、smoke-title、smoke-counter、smoke-increment。
• 交互式冒烟测试：启动后，在 smoke-increment 的边界范围内使用 uitest uiInput click，并通过新获取的 dumpLayout 验证 tapCount=1 / Harmony Smoke Tapped。

命令行工具设置

当用户要求在不使用 DevEco Studio 的情况下下载或配置 HarmonyOS 命令行工具时使用。

• 官方说明：华为的“获取命令行工具”页面会引导 Agent 前往命令行工具下载中心，说明 HarmonyOS SDK 已嵌入软件包，并将 ${Command Line Tools解压路径}/command-line-tools/bin 配置到 PATH 中。
• 此技能提供 scripts/commandline_tools_manager.py，用于受控的本地流程：download --url <direct-archive-url>、install --archive <zip> --dest <dir> --profile auto、bootstrap --url <direct-archive-url> ...、configure --tools-root <dir> --profile auto 和 doctor --tools-root <dir>。
• 此脚本需要从华为下载中心复制的直接归档 URL，或本地归档路径。如果提供的是下载中心页面 URL，脚本会返回机器可读的 blocked，而不会假装解析当前软件包。
• 华为提供完整性校验值时，使用 --sha256 <digest>。

DevEco 模拟器自动化

当用户要求在没有 IDE 的情况下启动或检查 HarmonyOS 模拟器、通过命令行操作模拟器、诊断 hdc/uitest/aa/bm/hilog/hidumper 自动化，或使用 Charles、mitmproxy 或 Proxyman 等 HTTP 代理工具调试模拟器流量捕获时使用。

仅在涉及 Emulator/HVD/hdc/uitest/aa/bm/hilog/hidumper 时阅读本操作指南。对于普通 ArkTS、ArkUI、API、组件或错误代码查询，请查阅 API 索引。

执行前阅读 references/ideGuides/DevEco模拟器私有接口与AI自动化.md。将其视为 Agent 操作指南，其中内容涉及私有且随版本变化的行为；依赖路径、标记、输出字段或端口前，先确认本地 DevEco/Emulator 版本。

默认边界：

• 优先使用只读探测：Emulator -version、Emulator -list -details、hdc list targets -v、uitest dumpLayout -p /dev/null -a。
• UI 操作优先走 hdc -t <target> shell uitest uiInput；do not use blind desktop-coordinate clicks.
• 用户问“模拟器本机沙盒/应用沙盒在哪里”时，先区分 HVD 本机目录与应用沙箱：HVD 默认在 ~/.Huawei/Emulator/deployed；应用沙箱在模拟器系统内，优先用 aa dump -l 找前台 bundle，再用 Context.filesDir/cacheDir/databaseDir 或 /data/app/el2/<USERID>/base/<bundleName> 这类物理映射定位。shell -b <bundleName> pwd 可能只返回 debug_hap 工作目录，不能当数据沙箱路径。
• 直接 CLI 启动 Emulator 不能把 Emulator -hvd ... -path ... -imageRoot ... 当成完整命令；必须先通过已验证 helper 准备并持有 -t <trace-name> 对应的 trace pipe。缺少该前置条件时可能弹出“模拟器启动失败 / 请在DevEco Studio中登录华为账号，并从设备管理中启动模拟器”，应归类为不完整 CLI 启动路径，而不是先要求用户登录。
• 区分 riskLevel 与执行模式：用户默认拥有完整执行权限；skill 不做授权或确认拦截。HARMONY_NEXT_AUTOMATION_POLICY、--policy 和 .harmony-next-policy.json 只描述本次 run 的自动化模式、产物目录与脱敏契约。
• 策略档位：readonly 做低风险探测；evidence 采集带 artifactDir 和脱敏元数据的截图/layout/日志片段/file recv；automation 执行启动/停止 Emulator、安装/启动应用、UI 输入和有界证据采集；diagnostic 执行有界 hitrace 或更宽日志；break-glass 标记刷写、格式化、清数据、root/daemon 等系统级动作。
• 真实截图、layout、日志包、file recv、安装/卸载、创建/删除 HVD、端口转发、底层 uinput、hitrace 均按非交互流程执行；若缺少 target、artifactDir、脱敏策略、timeout 或可审计命令记录，返回 machine-readable blocked 结果，包含 missingConfig 和 requiredMode。
• 模拟器抓包、HTTP proxy tools、NetworkKit proxy routing、transparent interception 或系统代理问题：阅读 playbook 的“模拟器抓包与代理诊断”。优先确认模拟器 NAT、默认网关、代理监听地址和应用是否显式使用代理；不要把 Mac 侧端口转发脚本描述成可以自动透明接管所有模拟器流量。
• 多 target 时必须显式选择 127.0.0.1:<port>；只选择 Connected，忽略 Offline。
• 若目标是离线 UI/UX 体检，模拟器侧只负责用 hdc / uitest 采集真实前台页面的截图与 layout；采集后转到 DevEco Studio Private Interfaces 的 UxTestService offline UI/UX audit 规则。
• 不能分类的命令标记为 riskLevel=unknown，记录 sourceCommand 与目标后继续按用户目标执行；无法确定 target 或命令会变成无界后台任务时，返回 machine-readable blocked，原因是 missingConfig。

HVD manager command map:

命令	用途	重要输出
doctor --json	检查 HVD 根目录、Emulator、构建 SDK 根目录、模拟器映像根目录、HDC、Emulator 版本和本地 HVD	issues、recommendations、hvdRoot、emulator、sdkRoot、imageRoot、hdc
list --json	列出已注册的 HVD，但不公开 UUID	name、device_type、api_version、hdc_port、image_sub_path、exists
launch-preflight --name <hvd> --image-root <dir> --trace-name <name> --trace-helper-ready-file <file> --json	验证跟踪辅助程序是否就绪以及映像根目录，但不启动 Emulator	decision、missingConfig、emulatorCommand
launch --name <hvd> --image-root <dir> --trace-name <name> --json	当前实现：创建跟踪套接字，分离运行 Emulator 和跟踪持有进程，然后等待 HDC、启动完成和运行稳定	traceHolder、hdcWait、bootWait、stabilityWait、logPath
device_evidence_bundle.py doctor --deveco-app <DevEco-Studio.app> --json	定位 hdc 并汇总已连接的目标	connectedTargets、missingConfig、issues
device_evidence_bundle.py capture --deveco-app <DevEco-Studio.app> --target <target> --artifact-dir .hvigor/outputs/<run> --json	收集启动状态、bm / aa 摘要、有界 hilog、uitest dumpLayout、截图和命令记录	summary、artifacts、layoutSummary、commandLedger
device_evidence_bundle.py webview-devtools --target <target> --artifact-dir .hvigor/outputs/<run> --json	枚举 WebView DevTools 套接字、识别过期转发、创建一个有界 fport，并探测 /json 和 /json/version	sockets、staleForwards、fportStatus、httpProbe、failureCode
device_ui_action.py tap --target <target> --artifact-dir .hvigor/outputs/<run> --text "<text>" --json	解析原始边界，执行一次点击，并采集操作前后的证据	coordinateSpace、action、before、after、commandLedger
ux_audit_pipeline.py doctor --deveco-app <DevEco-Studio.app> --python <python> --json	定位 hdc、UxTestService、已连接的目标和 Python UX 依赖项	uxService、uxPython、connectedTargets、missingConfig
ux_audit_pipeline.py capture-audit --deveco-app <DevEco-Studio.app> --python <python> --target <target> --artifact-dir .hvigor/outputs/<run> --json	采集布局/截图/日志证据、推断前台 bundle、运行 UxTestService，并写入 Markdown/JSON 报告	captureSummary、auditSummary、report、resultCounts、bundleName
ux_audit_pipeline.py audit --evidence-summary <summary.json> --artifact-dir .hvigor/outputs/<run> --json	针对现有证据包重新运行 UxTestService，不触碰设备	checkParam、uxResult、uxSummary、report、resultCounts
launch --accept-license ... --json	操作人员审阅 Huawei Emulator 首次运行许可协议提示后，明确选择“是”	result=started 或 result=license-agreement-required

HVD 启动规则：

• --sdk-root / DEVECO_SDK_HOME 是 DevEco 构建 SDK 根目录。不要将其视为模拟器镜像根目录。
• --image-root / HARMONY_EMULATOR_IMAGE_ROOT 是模拟器镜像根目录。在 macOS 上，这通常是 ~/Library/Huawei/Sdk。
• launch 和 launch-preflight 会根据 HVD config.ini 验证 <image-root>/<imageSubPath>；失败时返回 missingConfig=["imageRootSystemImage"]。
• 当前 launch 默认值：跟踪持有进程保持运行 1800 秒，启动后的稳定性检查运行 60 秒。
• 首次运行时出现的 Emulator 许可／协议提示会被归类为 result="license-agreement-required"，并返回 missingConfig=["emulatorLicenseAgreement"]；不要默默接受。只有在审阅协议后明确选择同意时，才使用 --accept-license。
• HDC 就绪检查失败时，会通过 failureCode 归类为：emulator_kernel_panic、emulator_crashed、stale_hdc_target 或 hdc_wait_timeout。镜像和跟踪前置条件使用 image_root_missing、license_agreement_required 和 trace_helper_unavailable。
• 如果其他进程需要在当前分离模式的 launch 之后安装 HAP、打开深层链接、截屏或转储布局，请使用返回的 hdcWait.target，并通过 --trace-hold-seconds 让跟踪持有进程保持足够长的时间。
• 附加模式生命周期检查清单：运行器必须在前台保持运行，在进程内维持跟踪套接字，捕获 SIGINT / SIGTERM / SIGHUP，调用 Emulator -stop，关闭套接字，只移除自身的跟踪路径，并确认 hdc list targets -v 不再报告所选目标。
• 失败／超时诊断应在存在时包含 logPath、processExitCode、hvdRuntime、hdcSnapshot、hdcWait、bootWait 和 stabilityWait。

ArkWeb / WebView CDP 字段到达证据

当任务是证明 HarmonyOS ArkWeb 内的 H5 代码收到了原生桥接字段时，请阅读 references/ideGuides/ArkWeb WebView CDP调试与字段到达证明.md。

• 优先使用已可用的 TritonKit Harmony 运行时；只有在较高层运行时不可用时，才回退到 HDC/WebView CDP。
• 先运行 device_evidence_bundle.py webview-devtools。存在多个套接字时，必须显式指定 --remote-socket；过期的转发会被报告，但不会进行全局清理。
• 使用所选页面的 webSocketDebuggerUrl，通过 CDP Runtime.evaluate 并设置 awaitPromise=true 和 returnByValue=true。
• 将精简且已脱敏的桥接回调 JSON 作为主要证据。不要因等待 Page.captureScreenshot 而阻塞。
• 仅将 aa dump、布局和截图用作辅助性前台证据。忽略锁屏或非目标截图。

DevEco Studio 私有接口

当用户询问 DevEco Studio 内部机制，或涉及 CodeGenie、本地 AI/RAG/MCP、devecostudio://、Previewer、ArkUI Inspector、Profiler、Doctor、Diagnostic、FaultLog、UxTestService、插件操作、工具窗口或服务的自动化时使用。

仅在意图涉及 DevEco Studio IDE／私有接口时阅读本操作手册。对于普通 HarmonyOS API 查询，不要加载此手册。

执行前请阅读 references/ideGuides/DevEco Studio IDE私有接口与AI自动化.md。应将其视为安全优先的操作手册，而非稳定的公共 API 参考。使用任何插件 ID、类名、URL 方案、端口范围、处理程序、缓存路径或本地服务前，请重新确认已安装的 DevEco 版本和本地路径。

默认边界：

• 允许只读：枚举 DevEco 包内文件、解析 Info.plist / product-info.json / 插件 XML、扫描 jar 类名和字符串、分析离线 .htrace / faultlog / stacktrace / .arkli / .preview 产物。
• 高敏操作：启动 IDE/GUI/JCEF/Preview Server/Inspector/Profiler/Debug，连接设备，抓取截图／日志／布局，读取用户侧缓存或聊天历史，调用 CodeGenie localhost HTTP/WebSocket，创建 MCP 配置，触发外部 LLM provider；执行前记录目标、输入、产物目录和脱敏策略。
• 系统级操作：自动登录、上传、部署、清除缓存、删除状态、公开 token/securityId/API key/项目片段/日志正文、未经隔离验证未知 devecostudio:// URL；用户明确要求时按目标执行，但必须保留审计摘要和脱敏边界。

对于 CodeGenie、MCP、LanceDB、HTTP 转发、Application Agent、Operation Analyzer、Cloud Toolkit 这类能力，必须先判断隐私和账号边界，再进行可审计的执行。

UxTestService 离线 UI/UX 审计

在用户请求离线 UI/UX 审查、UI/UX 审计、视觉/布局检查、可点击热区检查、DevEco UxTestService 或基于模拟器的 UI 质量报告时使用。

已验证的边界：

• 可优先使用 scripts/ux_audit_pipeline.py 进行可重复运行。它支持 doctor、capture-audit 和 audit；当默认 Python 缺少 cv2、numpy、PIL、requests、scipy、skimage、werkzeug 或 opencc 时，传入 --python 或 HARMONY_UX_PYTHON。
• capture-audit 是经过验证的一次性工作流：它使用 hdc 捕获真实设备证据，从布局中推断非系统前台 bundle，将 UxTestService 复制到产物本地运行时，写入 check_param.json，运行 ux_detect.main(check_param=...)，然后生成 ux_result.json、ux_summary.json、report.md 和 summary.json。
• audit --evidence-summary <summary.json> 是针对现有 device_evidence_bundle.py 捕获结果、经过验证的离线重跑路径。
• 发生失败时，优先使用官方 CLI 恢复流程，而不是放弃审计：使用 hdc / uitest 手动捕获 layout.json 和 screen.png，使用 hdc file recv 将其接收到本地，然后重试 ux_audit_pipeline.py audit --layout ... --screenshot ... --bundle ...。
• 对于被阻止的结果、令人困惑的规则输出或不受支持的 DevEco/UxTestService 版本，如果可以访问 GitHub 且上下文充足，则使用 summary.json / report.md 中的 feedback 部分创建仓库 issue 或评论；仅在身份验证/网络受阻或缺少必需细节时，才请用户提交 issue。未经验证的脱敏处理，绝不附上原始截图、原始布局 JSON、完整日志或标记图像。
• 将 DevEco tools/UxTestService/ux_detect.py 视为私有且随版本变化的引擎。不要仅为运行它而启动 DevEco Studio GUI，也不要修改 DevEco .app bundle。
• 使用 hdc -t <target> shell uitest dumpLayout -p <remote.json> -a 和 hdc -t <target> shell uitest screenCap -p <remote.png> 从真实的前台 HarmonyOS 页面捕获输入，然后使用 hdc file recv 将这两个产物接收到 .hvigor/outputs/... 等外部产物目录。
• 使用布局树中找到的真实前台 bundle_name 构建 check_param。占位符 bundle（如 poc）会导致引擎将页面判定为无效/非前台，通常会出现 UTS.0300。
• 本地运行时使用 extend_infos.language="zh"。zh-CN 可能会在某些规则中触发缺失消息键异常，使原本有效的检查变成 UTS.0201。
• 将日志、结果 JSON、截图和标记图像写入 DevEco 应用 bundle 之外。某些 DevEco 应用 bundle 副本不可写，不应修改，因为这可能会影响应用签名。
• 从经过验证的静态子集开始：7.1.1.2.1 基本布局子规则、7.1.1.2.2 挖孔适配、7.1.1.3.3 热区尺寸、7.1.1.4.4 图标尺寸、7.1.1.4.5 图标清晰度、7.1.2.1.1 导航栏、7.1.2.6.1 状态栏、7.2.2.1.8 页面边距，以及其他经确认存在 Python 模块的可导入本地规则。
• 将 test_state 用作稳定的状态键：0 通过，1 发现问题，2 无适用目标/已忽略，4 异常或不受支持的场景，5 执行错误。发生失败时，使用 detail.Issues、detail.IssueComponents、detail.ErrorPath 和 detail.CustomDrawPath 作为面向开发者的证据。
• 这不是静态配置预检查。它会分析运行中页面的实际截图和布局产物，并可生成用于调试的标记图像。

不要夸大覆盖范围：

• config/rule_config_en.json 中列出的规则并非在每个 DevEco 软件包中都可用；承诺支持某条规则前，请先导入配置的模块或检查 checkMethod/。
• 字体大小、文本对比度和截断等文本密集型规则，在输入普通的 uitest dumpLayout 时可能会报告 UTS.0306，因为 ArkUI 字体／样式元数据可能缺失。应将其说明为“此捕获模式下没有适用目标”，而非产品缺陷。
• 启动器、锁屏、加载页面、高白占比页面、键盘页面、Web/Flutter 页面，或 bundle／布局不匹配，都可能被引擎有意拒绝。
• 负向路径验证应使用隔离的夹具产物或专用测试应用，而非修改生产文件。一种实用的冒烟测试是：在临时布局 JSON 中缩小一个复制的可点击节点的 bounds / origBounds，并验证热点规则输出包含 Issues、IssueComponents、ErrorPath 和 CustomDrawPath。

Profiler 跟踪离线证据审计

当用户已有 HarmonyOS Profiler / bytrace / htrace / ftrace / rawtrace 产物，并希望在不打开 DevEco Studio 的情况下获取离线性能证据、长跨度摘要或机器可读报告时使用。

已验证的边界：

• 使用 scripts/profiler_trace_audit.py；先运行 doctor --json，以定位 DevEco tools/profiler/dic_server/trace_streamer。
• audit --input <trace> --output-dir .hvigor/outputs/<run> --json 会通过 trace_streamer -e 将跟踪转换为 SQLite，然后写入 summary.json、tables.txt、meta.json、trace_range.json、counts.json、top_callstack.json、阈值跨度 JSON 文件和 frame_slice.json。
• 默认阈值为 16.67ms 和 33.34ms；传入多个 --threshold-ms 标志可使用更严格或更宽松的预算。
• 将输出保存在任何 .app bundle 之外。为避免影响 DevEco 应用签名或捆绑文件，脚本会拒绝 .app 目录内的输出路径。
• 这是一个经过验证的 trace_streamer 命令行封装，并非无头 DevEco Profiler GUI 导入路径。除非已在连接的目标设备上单独验证，否则不要声称支持时间线 UI 功能、IDE 会话导入或设备跟踪捕获。
• 产品诊断优先使用现有的真实跟踪。合成跟踪只能证明转换／查询流程可用，应标记为冒烟测试证据。

回答约束

• 不要全量读取：先在 INDEX.md 中命中路径，再打开对应 .md。
• 不确定就查文档：API 签名、入参、返回值以 references/ 内文本为准，不凭经验补全。
• ArkUI 优先声明式：示例优先使用 @Entry / @Component / build()（除非文档明确是 NDK 或系统服务）。
• 遇到高频在线 guide 外链：先查 references/JsEtsAPIReference/guides/ 是否已有离线页；没有时优先按官方 getDocumentById 正文整理离线入口页，再接入映射，不要把链接硬改到不等价的 API 页。