@hmos-library-adapter/fast 0.0.17-beta.0 → 0.0.17-beta.2

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/app-permissions-lists.json

@@ -0,0 +1,217 @@
+{
+  "$comment": "鸿蒙 PC 应用权限三分类机读清单（vendor 自 ohos-migration-analysis src/services/reportlint.mjs，蒸馏自官方三份权限列表文档，2026-09-20 版）。三集合零重叠是断言不是假设；三表之外的权限名按未知处理（核对拼写或确认是否企业/MDM 类权限），不做推断。NOTIFICATION_CONTROLLER 是系统内置权限、不开放给应用申请（通知走运行时三件套），故不在 user_grant 清单。同步纪律：reportlint 清单变更时本文件同步。",
+  "distilled_from": "官方《受限开放权限-应用权限列表》(97) /《开放权限（用户授权）》(19) /《开放权限（系统授权）》(60)，2026-09-09 存档版",
+  "acl": [
+    "ACCESS_DDK_DRIVERS",
+    "ACCESS_DDK_HID",
+    "ACCESS_DDK_SCSI_PERIPHERAL",
+    "ACCESS_DDK_USB",
+    "ACCESS_DDK_USB_SERIAL",
+    "ACCESS_DIGITAL_IDENTITY",
+    "ACCESS_DISK_PHY_INFO",
+    "ACCESS_DLP_SERVICE",
+    "ACCESS_FIDO2_ONLINEAUTH",
+    "ACCESS_GAME_BUDDY_SERVICE",
+    "ACCESS_NET_TRACE_INFO",
+    "ACCESS_SE_KEY",
+    "ACCESS_USER_FULL_DISK",
+    "ACCESS_VIRTUAL_SCREEN",
+    "ALLOW_ACCESSORY_ACCESS",
+    "ALLOW_EXTERNAL_NATIVE_CODE",
+    "ALLOW_USE_BM",
+    "AUTO_RESTORE_MAIN_WINDOW",
+    "CAPTURE_PLAYBACK_DOWNLINK",
+    "CHECK_CALL_LOG",
+    "CONTROL_DEVICE",
+    "CRYPTO_EXTENSION_REGISTER",
+    "CUSTOMIZE_SAVE_BUTTON",
+    "CUSTOM_SANDBOX",
+    "CUSTOM_SCREEN_RECORDING",
+    "DETECT_DEVICE",
+    "DLP_GET_HIDE_STATUS",
+    "FILE_ACCESS_PERSIST",
+    "FLOAT_VIEW",
+    "GET_ABILITY_INFO",
+    "GET_CALL_TRANSFER_INFO",
+    "GET_ETHERNET_LOCAL_MAC",
+    "GET_IP_MAC_INFO",
+    "GET_NETWORK_STATS",
+    "GET_WIFI_LOCAL_MAC",
+    "GET_WIFI_PEERS_MAC",
+    "HOOK_KEY_EVENT",
+    "INPUT_DEVICE_CONFIGURATOR",
+    "INPUT_MONITORING",
+    "INTERCEPT_INPUT_EVENT",
+    "KEEP_BACKGROUND_RUNNING_SPECIAL_SCENARIO",
+    "KEEP_BACKGROUND_RUNNING_SYSTEM",
+    "KNOCK_COLLABORATION",
+    "LINKTURBO",
+    "MANAGE_APN_SETTING",
+    "MANAGE_BLUETOOTH_ADVERTISER_NAME",
+    "MANAGE_CALL_FOR_DEVICES",
+    "MANAGE_MEDIA_RESOURCES_FOR_PUBLIC",
+    "MANAGE_PASTEBOARD_APP_SHARE_OPTION",
+    "MANAGE_RECENT_SNAPSHOT",
+    "MANAGE_SANDBOX_BUNDLE",
+    "MANAGE_SCREEN_TIME_GUARD",
+    "MANAGE_SKILL",
+    "MANAGE_UDMF_APP_SHARE_OPTION",
+    "PERSISTENT_BLUETOOTH_PEERS_MAC",
+    "PERSONAL_MANAGE_RESTRICTIONS",
+    "PRELOAD_FILE",
+    "PRINTER_DRIVER",
+    "READ_AUDIO",
+    "READ_CONTACTS",
+    "READ_IMAGEVIDEO",
+    "READ_LOCAL_DEVICE_NAME",
+    "READ_PASTEBOARD",
+    "READ_WHOLE_CALENDAR",
+    "READ_WRITE_DESKTOP_DIRECTORY",
+    "READ_WRITE_USB_DEV",
+    "READ_WRITE_USER_FILE",
+    "REGISTER_OBJECTEDITOR_EXTENSION",
+    "SET_PAC_URL",
+    "SET_SYSTEMSHARE_APPLAUNCHTRUSTLIST",
+    "SET_TELEPHONY_ESIM_STATE_OPEN",
+    "SET_WINDOW_ALPHA",
+    "SET_WINDOW_TOUCH_AREAS",
+    "SHORT_TERM_WRITE_IMAGEVIDEO",
+    "START_PROVISIONING_MESSAGE",
+    "SUBSCRIBE_NOTIFICATION",
+    "SYSTEM_FLOAT_WINDOW",
+    "USE_FLOAT_BALL",
+    "USE_FRAUD_APP_PICKER",
+    "USE_FRAUD_CALL_LOG_PICKER",
+    "USE_FRAUD_MESSAGES_PICKER",
+    "WEB_NATIVE_MESSAGING",
+    "WRITE_AUDIO",
+    "WRITE_CONTACTS",
+    "WRITE_IMAGEVIDEO",
+    "WRITE_WHOLE_CALENDAR",
+    "atomicService.MANAGE_AGING",
+    "atomicService.MANAGE_STORAGE",
+    "kernel.ALLOW_EXECUTABLE_FORT_MEMORY",
+    "kernel.ALLOW_USE_JITFORT_INTERFACE",
+    "kernel.ALLOW_WRITABLE_CODE_MEMORY",
+    "kernel.AS_LDK_DRIVER",
+    "kernel.DISABLE_CODE_MEMORY_PROTECTION",
+    "kernel.DISABLE_GOTPLT_RO_PROTECTION",
+    "kernel.LOAD_INDEPENDENT_LIBRARY",
+    "kernel.SUPPORT_LOCAL_PLUGIN",
+    "kernel.SUPPORT_PLUGIN"
+  ],
+  "user_grant": [
+    "ACCESS_BLUETOOTH",
+    "ACCESS_NEARLINK",
+    "ACTIVITY_MOTION",
+    "APPROXIMATELY_LOCATION",
+    "APP_TRACKING_CONSENT",
+    "CAMERA",
+    "CUSTOM_SCREEN_CAPTURE",
+    "DISTRIBUTED_DATASYNC",
+    "LOCATION",
+    "LOCATION_IN_BACKGROUND",
+    "MEDIA_LOCATION",
+    "MICROPHONE",
+    "READ_CALENDAR",
+    "READ_HEALTH_DATA",
+    "READ_MEDIA",
+    "READ_WRITE_DOCUMENTS_DIRECTORY",
+    "READ_WRITE_DOWNLOAD_DIRECTORY",
+    "WRITE_CALENDAR",
+    "WRITE_MEDIA"
+  ],
+  "system_grant": [
+    "ACCELEROMETER",
+    "ACCESS_BIOMETRIC",
+    "ACCESS_CAR_AUDIO",
+    "ACCESS_CAR_DISTRIBUTED_ENGINE",
+    "ACCESS_CERT_MANAGER",
+    "ACCESS_EXTENSIONAL_DEVICE_DRIVER",
+    "ACCESS_NOTIFICATION_POLICY",
+    "ACCESS_SERVICE_NAVIGATION_INFO",
+    "ALLOW_COREDUMP",
+    "BACKGROUND_MANAGER_POWER_SAVE_MODE",
+    "CLEAN_BACKGROUND_PROCESSES",
+    "COMMONEVENT_STICKY",
+    "CONNECT_OBJECTEDITOR_EXTENSION",
+    "CUSTOMIZE_MENU_ICON",
+    "DCAS_RUN_MODEL",
+    "DETECT_GESTURE",
+    "DISCOVER_BLUETOOTH",
+    "GET_BUNDLE_INFO",
+    "GET_DONOTDISTURB_STATE",
+    "GET_ENTERPRISE_CONFIG",
+    "GET_FILE_ICON",
+    "GET_NETWORK_INFO",
+    "GET_WIFI_INFO",
+    "GYROSCOPE",
+    "HDR_BRIGHTNESS",
+    "INHERIT_PARENT_PERMISSION",
+    "INPUT_KEYBOARD_CONTROLLER",
+    "INTERNET",
+    "KEEP_BACKGROUND_RUNNING",
+    "LOCK_WINDOW_CURSOR",
+    "MANAGE_INPUT_INFRARED_EMITTER",
+    "NDK_START_SELF_UI_ABILITY",
+    "NFC_CARD_EMULATION",
+    "NFC_TAG",
+    "PREPARE_APP_TERMINATE",
+    "PRINT",
+    "PRIVACY_WINDOW",
+    "PROTECT_SCREEN_LOCK_DATA",
+    "PUBLISH_AGENT_REMINDER",
+    "QUERY_VOLUME_ENCRYPTION_STATUS",
+    "READ_ACCOUNT_LOGIN_STATE",
+    "READ_CLOUD_SYNC_CONFIG",
+    "RUNNING_LOCK",
+    "RUN_DYN_CODE",
+    "SET_ABILITY_INSTANCE_INFO",
+    "SET_NETWORK_INFO",
+    "SET_WIFI_INFO",
+    "SET_WINDOW_TRANSPARENT",
+    "START_WINDOW_BELOW_LOCK_SCREEN",
+    "STORE_PERSISTENT_DATA",
+    "STYLUS_FRAME_BOOST",
+    "TIMEOUT_SCREENOFF_DISABLE_LOCK",
+    "USE_BLUETOOTH",
+    "VIBRATE",
+    "WINDOW_TOPMOST",
+    "kernel.ALLOW_DEBUG",
+    "kernel.DEBUGGER",
+    "kernel.EXEMPT_ANONYMOUS_EXECUTABLE_MEMORY",
+    "kernel.IGNORE_LIBRARY_VALIDATION",
+    "kernel.NET_RAW"
+  ],
+  "template_declared": [
+    "ACCELEROMETER",
+    "ACCESS_BIOMETRIC",
+    "ACCESS_BLUETOOTH",
+    "ACCESS_CERT_MANAGER",
+    "APPROXIMATELY_LOCATION",
+    "CAMERA",
+    "CUSTOM_SCREEN_CAPTURE",
+    "DISTRIBUTED_DATASYNC",
+    "FILE_ACCESS_PERSIST",
+    "GET_FILE_ICON",
+    "GET_NETWORK_INFO",
+    "GYROSCOPE",
+    "INTERNET",
+    "LOCATION",
+    "LOCATION_IN_BACKGROUND",
+    "MICROPHONE",
+    "PREPARE_APP_TERMINATE",
+    "PRINT",
+    "PRIVACY_WINDOW",
+    "READ_PASTEBOARD",
+    "READ_WRITE_DESKTOP_DIRECTORY",
+    "READ_WRITE_DOCUMENTS_DIRECTORY",
+    "READ_WRITE_DOWNLOAD_DIRECTORY",
+    "RUNNING_LOCK",
+    "SET_WINDOW_TRANSPARENT",
+    "SYSTEM_FLOAT_WINDOW",
+    "WEB_NATIVE_MESSAGING",
+    "WINDOW_TOPMOST",
+    "kernel.ALLOW_WRITABLE_CODE_MEMORY"
+  ]
+}

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/app-permissions.md

@@ -0,0 +1,57 @@
+# 能力域：应用权限体系（app-permissions）
+
+> **跨域能力**（非单域）：鸿蒙 PC 应用（交付形态 `app`——Electron/Qt）的权限三层分类、代码特征→权限映射、运行时授权链路。scan 阶段 2 轴判定与配方 Phase 3.2/4 消费。
+> vendor 自 ohos-migration-analysis `knowledge/electron/kits/permission.md`（2026-09-20 蒸馏版）。
+> **机读清单**：同目录 `app-permissions-lists.json`（ACL 97 / user_grant 19 / system_grant 60 / 模板预声明 29——三集合零重叠是断言不是假设）。
+
+## 能力现状：三层分类（与栈无关）
+
+| 分类 | 数量 | 生效方式 | 高频项 |
+|---|---|---|---|
+| **system_grant**（系统授权） | 60 | `module.json5` 声明即生效 | INTERNET、GET_NETWORK_INFO、WINDOW_TOPMOST、RUNNING_LOCK、PREPARE_APP_TERMINATE |
+| **user_grant**（用户授权） | 19 | 声明（name/reason/usedScene）+ **运行时弹窗授权**；系统弹窗**仅一次**，拒绝后只能 设置→隐私和安全 手动改（`openApplicationInfoEntry()` 可跳转） | READ_WRITE_DOCUMENTS_DIRECTORY、READ_WRITE_DOWNLOAD_DIRECTORY、CUSTOM_SCREEN_CAPTURE、CAMERA、MICROPHONE、ACCESS_BLUETOOTH |
+| **ACL / 受限开放** | 97 | **AGC（AppGallery Connect）在线申请审核 → 写入 Profile**；本地调试证书链无法授予（装机拒 code:9568289，joplin 案例的 `kernel.ALLOW_WRITABLE_CODE_MEMORY` 即此边界） | READ_PASTEBOARD、SYSTEM_FLOAT_WINDOW、READ_WRITE_DESKTOP_DIRECTORY、FILE_ACCESS_PERSIST、kernel.ALLOW_WRITABLE_CODE_MEMORY |
+
+**三条硬事实**：
+- `READ_WRITE_DOCUMENTS_DIRECTORY` / `READ_WRITE_DOWNLOAD_DIRECTORY` 是**对所有应用开放的 user_grant，不是 ACL**（常见误判——它们要的是运行时弹窗，不是 AGC 申请）。
+- `NOTIFICATION_CONTROLLER` 是系统内置权限、不开放给应用申请——`Notification.show` **无需权限声明**，通知走运行时三件套。
+- 三张清单之外的权限名按**未知**处理（核对拼写或确认是否企业/MDM 类权限），不做推断。
+
+## 代码特征 → 权限映射（扫描命中即要申报）
+
+| 代码特征 | 所需权限 | 分类 | 运行时动作 |
+|---|---|---|---|
+| `clipboard.read*/write*`、`navigator.clipboard` | READ_PASTEBOARD | **ACL** | `requestSystemPermission('pasteboard')` |
+| 网络请求（fetch/axios/XMLHttpRequest） | INTERNET + GET_NETWORK_INFO | system_grant | —（模板已含） |
+| `will-download` / `downloadURL` / `showSaveDialog` | READ_WRITE_DOWNLOAD_DIRECTORY | user_grant | `requestDirectoryPermission()` |
+| 写公共目录 Documents/Download | READ_WRITE_DOCUMENTS_DIRECTORY（+ DOWNLOAD） | user_grant | `requestDirectoryPermission()`；**Desktop 目录是 READ_WRITE_DESKTOP_DIRECTORY（ACL）** |
+| `desktopCapturer` / `getDisplayMedia` | CUSTOM_SCREEN_CAPTURE | user_grant | `requestSystemPermission('screen-capture')`，且仅整屏源 |
+| `alwaysOnTop` / 悬浮窗 | SYSTEM_FLOAT_WINDOW（**ACL**）+ WINDOW_TOPMOST | — | — |
+| `getUserMedia` | CAMERA + MICROPHONE | user_grant | `requestSystemPermission('camera'/'microphone')` |
+| 蓝牙（`setBluetoothPairingHandler` 等） | ACCESS_BLUETOOTH | user_grant | — |
+| `utilityProcess.fork` / WebAssembly 编译 | kernel.ALLOW_WRITABLE_CODE_MEMORY | **ACL** | —（jitless 模式可绕开，见配方硬性约束 #4） |
+| `Notification.show` | **无需声明** | — | 通知运行时三件套 |
+
+机读版（正则 + ACL 标记 + 授予动作）内置于 `ohpt-agent scan-electron` 的 **permissions 面**。
+
+## 流水线接线（谁在哪个阶段消费）
+
+1. **阶段 1（scan）**：`ohpt-agent scan-electron` permissions 面扫 `source/` → 命中落 `01-scan.json` 的 `harmony_adaptation.permission_dependencies[]`（feature / permissions / grant_mode / runtime_action / source_refs）——**扫到必落**，不凭记忆手写。
+2. **阶段 3 工程定制（声明分轨，见 pc-delivery-forms forms/app.md）**：按 `grant_mode` 分轨——system_grant 声明即生效；user_grant 声明（reason+usedScene）+ EntryAbility 编排 `requestPermissionsFromUser`/`requestDirectoryPermission`（三层编排：声明 → 运行时弹窗 → 授权范围外回落 picker，细节见下方已知坑）；ACL 声明可保留 + `remaining_blockers` 如实记「AGC 在线申请不可免」。对照模板预声明 29 项（electron 模板在 `web_engine/src/main/module.json5`）标 `declared_by_template`、缺的补声明。
+3. **运行测试阶段（授予态取证）**：装机后 `bm dump -n <bundle>` 采集 `reqPermissionStates` 落证；user_grant 未授予 → `remaining_todos` 记「待人工授权」+ `openApplicationInfoEntry` 引导——**弹窗授权是人工动作，机器不代授**（auto 模式的边界如实记录）。
+4. **验收**：`permissions-reconciled` 规则对账（module.json5 声明集 ⊇ scan 需求集；user_grant 授予态有证据或「待人工」交代）。
+
+## 已知坑
+
+- 弹窗仅一次 + 拒绝后只能设置页改 → 首启按「功能首次使用前申请」节奏集中编排 + 申请失败的降级 UI。**user_grant 只能 app 弹窗**（hdc 无 `pm grant`；EntryAbility `onCreate` 经 `abilityAccessCtrl.createAtManager().requestPermissionsFromUser` 编排）。
+- **picker 授权仅会话级**：会话恢复类功能（记录「上次打开的文件」并在启动时恢复——编辑器/IDE/播放列表类）跨重启必挂，必须 DIRECTORY 权限声明——这条权限链是恢复功能能否跨重启工作的决定项（marktext 真机实证：声明+弹窗后 `authResults=[0,0]`、force-stop 重启授权持久）。
+- **剪贴板读写不对称**：本地调试链下写可用、读不可用（READ_PASTEBOARD 是 ACL）——调用保留不崩溃，可静默降级（joplin 实证）；最终授予态装机后 `bm dump` 取证。
+- **本地调试 profile 的 `acls.allowed-acls` 实测无法解锁 READ_PASTEBOARD**（sign-profile 成功但装机仍拒）——文档上的机制在本机证书链上不生效，勿再试；kernel 级 ACL 同理（9568289，见 forms/app.md 签名档位矩阵）。
+- 上架前核对权限只放 `pc_entry` 或 `web_engine` 之一（2in1/pad 双端上架规则）。
+- ACL 权限信息需写入 Profile：创建 Profile **前**完成 AGC 申请；Profile 已创建后 ACL 变化需重建。
+
+## 验证状态与版本锚
+
+- 三清单蒸馏自官方三份权限文档（2026-09-09 存档、2026-09-20 蒸馏）；同步义务：ohos-migration-analysis 侧 reportlint 清单变更时 `app-permissions-lists.json` 与本文件同步。
+- 三层链路逐权限走通（pasteboard/目录/通知）、拒绝后二次引导 `openApplicationInfoEntry`、AGC 审核通过后 Profile 写入与签名包安装——**未验证**（继承源知识包标注，照实带入）。
+- marktext-0.20.0 实证（2026-09-22）：DIRECTORY 两权限已声明未授予（`reqPermissionStates=[-1,-1]`）→ 保存链路不可用——判定由 verify 的 bm dump 对账抓出，本域文件与流水线接线即为此类缺口的系统性修复。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/app-self-update.md

@@ -0,0 +1,217 @@
+---
+name: app-self-update
+description: 应用自更新/自分发能力域。鸿蒙 partial——分发由 App Gallery 垄断，应用自带的更新器即使跑通也无处落地；替换方案是 @kit.StoreKit 的 updateManager（仅 ArkTS、仅 HAP 形态），且「有新版本」分支在上架前不可验。含 11 个实际端口的检测表与六种现场状态
+metadata:
+  type: capability-domain
+  source: 实际适配案例（vlc 真机跑通后判死并改接 App Gallery；另 10 个端口源码实测对照）
+---
+
+# 能力域：app-self-update（应用自更新 / 自分发）
+
+**鸿蒙状态：`partial`** —— 平台**有**更新能力（App Gallery + `@kit.StoreKit`），但三道收窄：
+只对 **HAP 交付形态**存在、只在 **ArkTS 侧**够得着、**「有新版本」分支在应用上架前无法验证**。
+应用**自带**的更新器（下载安装包并自行安装）在零售机上**一律无效**。
+
+> 典型触发：`Help ▸ Check for Updates` 菜单项、启动期自动查更新、`QSimpleUpdater`/`QNetworkAccessManager`
+> 拉版本号、`maven-metadata.xml`/`version.txt`/`status` 探测、插件/扩展安装器、崩溃上报器自行拉取组件、
+> NetBeans `autoupdate`、Jenkins Update Center、`update.enabled` 之类默认开启的偏好项。
+
+## 零、怎么检出——`app` 形态**逐个必查**，不要等症状
+
+更新器是**功能**不是平台符号，`native_api` / `capability_profile` 那条符号驱动的路子**看不见它**，
+所以它不靠"命中"而靠**例行检查**：凡 `delivery_form` 判为 `app` 的端口，本域一律过一遍。
+
+```bash
+grep -rlaiE "check.?for.?updates|checkForUpdate|QSimpleUpdater|autoupdate|UpdateCenter|maven-metadata|updateManager|LatestRelease" source/
+```
+
+`-a` 不能省：实测 ohos-notepadnext 的 `MainWindow.cpp` 被 `file(1)` 判成 `data`（内含二进制字节），
+不加 `-a` 时 grep **静默跳过整个文件**、既不报错也不计数——正是藏着更新器的那个文件。
+
+实测 11 个端口：7 个有更新器的全部命中，3 个确实没有的（jmeter / gitlfs / gitlabrunner）干净返回 0。
+
+**一处必须知道的假阴性**：ohos-jenkins 返回 0，而它**有** Update Center——该端口根本没有 `source/` 目录，
+它重新打包上游的 `jenkins-*.war`。**更新器在交付物里、不在源码里。** 所以这步要问两遍：
+"源码里有没有"，以及"**交付的二进制/jar/war 自带不自带**"。只跑 grep 会把这一类记成 N/A。
+
+## 一、先把问题拆成两半——这是本域最容易犯的错
+
+**更新的「来源」必须换成应用市场；用户的「入口」不该消失。** 两件事分开判，合在一起判一定出错。
+
+vlc 第 16 轮把 `Help ▸ Check for Updates` 菜单项**连同**更新器一起删了，第 17 轮不得不回滚菜单项：
+需求是"商店成为更新**源**"，不是"用户失去主动查询的能力"。这一来一回带着 8 条用例
+PASS→NA、又把 3 条改回 PASS。
+
+| 半边 | 判法 |
+|---|---|
+| **来源**（下载谁、安装谁） | 必须废掉。零售鸿蒙 PC 只认 AGC 签名包经 App Gallery 安装，自己下的东西落在沙箱里，用户够不着 |
+| **入口**（菜单项、设置开关） | 保留在上游原位，动作改指商店。删掉它等于这台机器上再没有任何可见的更新途径 |
+
+## 二、替换方案（本体）
+
+`@kit.StoreKit` 的 `updateManager`（底层 `@hms.core.appgalleryservice.updateManager`），**API 12+，不需要任何权限**：
+
+```typescript
+import { updateManager } from '@kit.StoreKit';
+import { promptAction } from '@kit.ArkUI';
+
+async checkStoreUpdate(): Promise<void> {
+  try {
+    const res = await updateManager.checkAppUpdate(this.context);
+    if (res.updateAvailable === updateManager.UpdateAvailableCode.LATER_VERSION_EXIST) {
+      // 往下由 App Gallery 自己弹窗，应用不要自绘更新 UI
+      await updateManager.showUpdateDialog(this.context);
+    } else {
+      // 没有新版本时商店**不弹任何东西**——必须自己给个反馈，
+      // 否则恢复出来的菜单项在用户看来是死的
+      promptAction.showToast({ message: '已是最新版本', duration: 2500 });
+    }
+  } catch (e) {
+    // 上架前这里是常态，不能让它影响启动或报错给用户
+  }
+}
+```
+
+`CheckUpdateResult` 带 `updateAvailable`（`LATER_VERSION_EXIST=1` / `LATER_VERSION_NOT_EXIST=0`）、
+`versionName`、`versionCode`。
+
+**三条实测结论**（vlc，零售机 MateBook，OpenHarmony-7.0.0.105 / API 24）：
+
+1. **调试签名、侧载、未上架的包也能正常调**——返回 `LATER_VERSION_NOT_EXIST`，不抛异常。
+   所以接线和冒烟**不需要**先上架。
+2. **`showUpdateDialog()` 够得着但商店会拒**——强行走"有新版本"分支，调用返回真实结果，
+   但 App Gallery 以 `SHOW_DIALOG_FAILURE` + `checkResultBundleName ... fail` 拒绝：
+   商店不会为自己不分发的包渲染弹窗。
+3. 因此**「有新版本」分支本地不可验**，要验只能上 AGC 封闭/内部测试轨道 + 设备装一个更低的 `versionCode`。
+   这条必须写进报告（见第八节），否则就是把"接通了"说成"验过了"。
+
+## 三、怎么关掉上游的更新器——优先动构建开关，不动源码
+
+**先查上游有没有现成的 configure/CMake 开关**，有就从构建行里去掉，没有才打补丁。
+
+vlc 的例子：从 `vlc-configure.sh` 去掉 `--enable-update-check` 就够了——上游默认本来就是关，
+于是 `src/misc/update.c`、`update_crypto.c` 不参与编译，**菜单项、更新对话框、"启用更新通知"偏好项
+一起消失，零源码改动、零补丁维护**。
+
+反向的坑同样真实：早先一轮为了让菜单项出现而**加上** `--enable-update-check`，连带拖进 libgcrypt，
+还得清掉 120 个 `libdir='//lib'` 的 Conan `.la`、11 个被污染的构建树 `.la` 和一个过期的 `help.moc.cpp`——
+这些工作后来整体作废。**先判该不该有，再去让它编得出来。**
+
+## 四、原生 UI 怎么够得着这个 ArkTS-only 的 API
+
+kit 系 API（StoreKit/账号/推送/分享）**只有 ArkTS 入口**。SDK 的 native 头里只有
+`StoreKit/module_install.h`，管的是**动态特性模块安装**，不是应用更新——先翻一眼 native 头目录，
+能最快settle"有没有 C 入口"这个问题。
+
+| 被移植应用 | 怎么跨到 ArkTS |
+|---|---|
+| **链接 Qt 的**（Qt Widgets/Quick 应用） | **用 kit 自带的**：`QtCore/qopenharmony.h` 导出 `QtOh::runOnJsUIThreadNoWait/AndWait`、`uiEnv()`，`qohjsmodule.h`/`qohjsobject.h` 导出 `QOhJsModule` / `QOhJsObject::call` ——C++ 直接调 ArkTS 模块函数并自动落到 JS 线程 |
+| **不链接 Qt 的** | 自写 NAPI 桥：ArkTS 启动期 `registerXxx(cb)` 注册一次，模块把 `cb` 存成 `napi_threadsafe_function`，原生侧 `dlopen` 后调导出的纯 C 符号 |
+
+> vlc 走了第二条（119 行 `ohos-bridge.c` + 构建脚本 + 一个 `.so` + `dlopen` 兜底），
+> **而它本来就链接着导出第一条能力的 Qt 库**——`grep runOnJsUIThread` 在它的 Qt 源码里零命中，
+> 即从没考虑过。同工作区的 ohos-cppcheck 在同一个边界上用的是 kit 助手。
+> **链接 Qt 就别自己写桥。**
+
+自写桥时四个细节各挡掉一个真问题：`max_queue_size 1`（连点两次不会叠弹窗，`napi_queue_full` 当"已接受"
+而非错误）、`napi_unref_threadsafe_function`（别把 ArkTS 事件循环吊住导致退不出）、`dlopen` 而非链接依赖
+（桥缺失时降级成一条提示，不是整个原生插件加载失败）、以及"桥不在/没注册"时的原生兜底（入口永不变成死的）。
+
+**两条路都必须切到 ArkTS UI 线程**——不切就是进程 abort，见第六节。
+
+## 五、判定分支（交付形态 × 更新器性质）
+
+**`app-self-update` 命中后不要直接写"改接 App Gallery"**，先过这张表：
+
+| 交付形态 / 性质 | 商店路线可用？ | 判定 |
+|---|---|---|
+| `app`（HAP）+ 自更新整个应用 | ✅ | 废掉自带来源，入口改指 `checkAppUpdate()` |
+| `cli` / `pure-runtime` / `cpp-lib` | ❌ **根本没有商店条目** | 只能在"关掉"和"保留"之间选；别写成"待改接商店" |
+| 更新的是**插件/扩展**不是应用包 | ❌ 商店不是替代品 | 可以如实保留。ohos-jenkins 的插件安装经 Update Center 真机验证通过 |
+| 更新器会拉来**上游预构建产物** | ❌ 拉来的东西没被移植过 | **必须关掉**，理由与分发无关，见 5.1 |
+| **只提示不自装**（拉个版本号提示一句） | ⚠️ 没什么可"转换"的 | 判的是"启动期这次网络请求能不能接受"，不是改接商店。ohos-gatling 属此类 |
+| 上游**本就平台条件编译**（只 Windows 有） | — | 最危险的一档，见下 |
+
+### 5.1 第二条判死理由：更新器拉来的是**没被移植过的**上游产物
+
+第一条理由是分发（自己下的包装不上、落在沙箱里）。**第二条和分发无关，而且更隐蔽：
+下载会成功、安装会成功，装上来的却是一个从没在鸿蒙上编译过的构建。**
+
+凡交付物是**自己打过补丁重新构建**的上游产物，自更新就是一条把补丁冲掉的路。
+ohos-jenkins 是现成的例子：交付的 `jenkins-*-harmony.war` 是打过补丁的核心重建——
+`core/src/main/java/hudson/util/ProcessTree.java` 被改成把 `os.name = "HarmonyOS"` 认作 procfs 平台，
+否则 `ProcessTree.get()` 的五个精确等值分支全不命中、回落到空实现，`ProcessTreeKiller` 变成 no-op、
+构建残留子进程清不掉。一次「升级 Jenkins 核心」会从官方站拉回 **stock war** 覆盖它：
+**服务照样起得来，进程树处理却静默回退成 no-op。** 比装不上难查得多。
+
+判法：问一句「更新器拉来的产物，是我们构建的那一个吗？」答案是否 → 关掉，并在报告里写明关的理由是
+**产物未经移植**，不是「平台不允许」。区分这两条很重要——前者在任何交付形态上都成立（包括 `cli`，
+它根本没有商店条目可谈），后者只对 HAP 形态成立。
+
+**同一个端口的两件事要分开判。** Jenkins 的 Update Center 同时管插件安装和核心升级：
+插件侧留着是对的（真机验证通过），核心升级侧必须关。把它整体记成「刻意保留」会漏掉后者。
+
+**「因继承而失效」必须转成一次明确决定。** 上游把实现整个塞进 `#ifdef Q_OS_WIN`、或 Java 侧回落到
+provider stub，于是功能在鸿蒙上"正好不工作"——**没人决定过它**，一次重构就可能把它复活，
+而且 scan 阶段极易把它记成"无此能力"。这一档要在 `01-scan.json` 里如实落成一条决定，不是略过。
+
+## 六、11 个端口的现场状态（源码实测，2026-10-07）
+
+同一问题在一个工作区里出现六种状态——这正是本域要存在的理由。
+
+| 端口 | 形态 | 上游更新器 | 调用点 / 证据 | 现场状态 |
+|---|---|---|---|---|
+| vlc | app | `Help ▸ Check for Updates`，`misc/update.c` | `dialogs_provider.cpp` → `libvlcbridge.so` → ArkTS | **已改接商店**（全工作区仅此一处出现 `StoreKit`） |
+| ohos-cppcheck | app | GUI 可选拉 `version.txt`（默认关） | `source/gui/mainwindow.cpp:488-517` | **主动关掉**，且刻意不构造 `QNetworkAccessManager` |
+| ohos-avidemux | app | 启动期 `ADM_checkForUpdate()` | `Q_gui2.cpp:3204`，只有 `#ifndef _MSC_VER` 这道门；偏好 `update.enabled` 默认 `"1"`（`prefs2_pref.h:51`）；`ADM_update/` 下零 `__OHOS__` | **仍在联网且无人决定**——唯一还在启动期访问非 AGC 更新服务器的端口 |
+| ohos-notepadnext | app | `QSimpleUpdater`，上游仅 Windows | `MainWindow.cpp:2115`；非 Win 分支 `setDisabled(true)`+`setVisible(false)`（:2179-2180）；`QSimpleUpdater` 仍无条件链接（`src/CMakeLists.txt:233`） | **因继承而失效**（该端口已有 `Q_OS_HARMONY` 分支惯例，可就地接商店） |
+| ohos-soapui | app | `Help ▸ Check for Updates` + `AUTO_CHECK_VERSION_UPDATE` | `SoapUI.java:578,779-780`，Java 侧零 OHOS 标记 → provider 回落 stub | **因继承而失效** |
+| ohos-visualvm | app | NetBeans Platform `autoupdate` | 随 UI 重写一并弃用 | **已移除** |
+| ohos-jenkins | cli | Jenkins Update Center（插件安装 + 核心升级两件事） | 交付物是打过补丁的 `jenkins-*-harmony.war`（`patches/0001` 改 `ProcessTree.java`）；启动日志仍有 `check updates server successfully`；树内无任何关闭开关 | **插件侧刻意保留并验证通过；核心升级侧仍开着且无保护**——一次核心升级会用 stock war 覆盖补丁，见 5.1 |
+| ohos-gatling | app | 轮询 Maven Central 仅提示 | `GatlingVersion.scala:68`，1s 超时 | **仅提示，无可转换** |
+| ohos-jmeter / ohos-gitlfs / ohos-gitlabrunner | app / cli / cli | 无 | —（`git lfs update` 只改 Git 钩子，不动二进制） | **N/A** |
+
+## 七、连带风险：Qt5 上启动期的网络对象 = 进程 abort
+
+**只要是 Qt5**：构造 `QNetworkAccessManager` 会建出 `QNetworkConfigurationManager`，它加载
+`libplugins_bearer_qohbearer.so`，而该插件经 `napi_call_function` 回调 ArkTS ability。
+Qt 应用跑在 QPA 创建的工作线程上、不是 ability 的 JS 线程，于是 ArkCompiler 的线程守卫直接
+abort：**`ecma_vm cannot run in multi-thread!` → SIGABRT**（ohos-cppcheck 真机撞到并在源码里挡掉）。
+
+危险的是**没撞到的那种**：ohos-avidemux 启动期那条无保护的更新检查持有 `QNetworkAccessManager` 成员，
+今天不崩**只因为它的 HAP 里没打进 bearer 插件**——而 Qt5 OHOS kit 是**带**这个插件的。
+哪天有人"为了完整"把整套插件打进包，一个已交付端口的启动就变成 abort，而触发它的改动在三个仓库之外。
+
+| 条件 | 结论 |
+|---|---|
+| Qt5 + 启动期能走到网络对象 + bearer 插件进了包 | 启动 SIGABRT |
+| Qt5 + 同上但插件没进包 | 侥幸不崩（**不是安全，是没打包**） |
+| Qt6 | 无此机制（Qt6 已删除 bearer management） |
+
+**规则：移植应用里任何启动期够得着的 Qt 网络对象都要有 `__OHOS__` 保护或经
+`QtOh::runOnJsUIThread` 切线程，不管它当下崩不崩；并且更新偏好项要在鸿蒙上强制置否，
+而不是沿用上游默认——更新器是最常见的"用户还没动手就先联网"的东西。**
+按集合（而非按名单）打 Qt 插件的端口尤其要查这一条。
+
+## 八、可行性影响 / 怎么判
+
+**不要因为这个域判 `infeasible`。** 它基本不影响可行性，影响的是**范围与报告的诚实度**。
+
+| 场景 | 判定 |
+|---|---|
+| `app` 形态，自带更新器 | `feasible`——废来源、留入口、改接商店；工作量 S |
+| 需要从原生 UI 调起 | `feasible`；链接 Qt 则工作量 S（用 kit），否则 S-M（自写桥） |
+| `cli` 等无商店条目的形态 | `feasible`；判的是关还是留，别许诺一个不存在的商店路线 |
+
+**必须一并处理测试用例**（漏掉这步会让一次产品决定看起来像一堆回归）：
+
+- 断言被废掉的 UI 的用例 → 按产品决定改判 NA，**把理由一起写上**；
+- **当心位置断言**：删掉一个菜单项会静默弄坏所有"把存活项钉在第 N 位"的用例；
+- 「有新版本」分支的用例 → 标成**上架前不可执行**，别记成 pass 也别记成缺陷
+  （现有枚举里没有这一档，这是已登记的 schema 欠账）。
+
+## 相关
+
+- `pc-delivery-forms` —— 第五节那张表的另一个轴；`cli`/`pure-runtime` 没有商店条目这件事由交付形态决定
+- `pc-recipe-qt-app` —— Qt 端口跨到 ArkTS 用 kit 自带的 `QtOh::runOnJsUIThread`，别自写 NAPI 桥
+- `pc-knowledge-base/platform/鸿蒙PC-能力存在性以SDK声明为准.md` —— 判"没有 native 入口"前先翻 native 头目录

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/audio.md

@@ -0,0 +1,91 @@
+# 能力域：audio（音频播放 / 采集）
+
+## 能力描述
+
+进程直接出声或录音：OpenAL / PortAudio / SDL_audio / miniaudio / RtAudio / FMOD 类库，
+以及任何在 Linux 上走 ALSA / PulseAudio / PipeWire / OSS / SndIO 的音频栈。
+
+**典型触发**：依赖里出现 `libopenal` / `portaudio` / `SDL_audio` / `alsa-lib` / `pulse`，
+或源码里有 `snd_pcm_*` / `pa_stream_*` / `alcOpenDevice` / `AudioUnit` / `OpenSL ES` 调用。
+
+## 鸿蒙状态：partial（经 OHAudio 后端，零售机 NAPI 壳）
+
+| 子能力 | 状态 | 说明 |
+|---|---|---|
+| 播放（渲染） | **available** | OHAudio C API，**无需权限、无需应用身份**；零售机上经签名 HAP 的 NAPI 壳 `dlopen(libohaudio.so)`（LOAD 不 EXEC）拿到 renderer 真出声 |
+| 采集（录音） | 本资产未覆盖 | 需 `ohos.permission.MICROPHONE`（SDK 声明）；本资产只含播放链路 |
+| 设备枚举 / 热插拔 | partial | 只有一个默认设备；`ALC_EVENT_*` 类设备增删事件不支持 |
+| 低延迟 | 有档位 | `AUDIOSTREAM_LATENCY_MODE_NORMAL` 实测通过；SDK 另有 `_FAST` 档 |
+
+**关键事实：鸿蒙上没有 ALSA / PulseAudio / PipeWire / OSS / SndIO / OpenSL ES。**
+上游库的 Linux 后端一个都用不了，唯一原生出口是 OHAudio（NDK `<ohaudio/*>` + `libohaudio.so`）。
+
+## 替换方案
+
+**给宿主库新增一个 OHAudio 后端，并以签名 HAP 的 NAPI 壳承载**。方案本体（零售机实证的机制 +
+判据 + 实例）在 `../solutions/ohaudio-backend/`：
+
+- 机制：签名 HAP 原生模块内 `dlopen(libohaudio.so)`（16 个 `OH_Audio*` 符号）+ `dlopen(解码库)`
+  （如 `libxxx.so.0`），**LOAD 不 EXEC**——retail 机 exec 独立二进制被签名墙拒（EPERM/127），
+  NAPI 壳是唯一已实证通道。
+- 实例：`solutions/ohaudio-backend/` 下的实例目录（真实解码 → OHAudio renderer 全通过）；
+  其他库接入见 `PORTING_NOTES.md`。
+- **第二种接入形状**：若宿主库**自带输出后端/模块加载器**（如 out123 系解码库的
+  `xxx_module_t` · libao · SDL audio driver · gstreamer 元素），不必写"NAPI 壳 → 喂 OHAudio"的
+  手动 wiring——写**一个 OHAudio 输出模块**（`ohaudio.c` → `output_ohaudio.so`，单独 clang
+  直调编译，不走 CMake 目标），库运行时按模块目录环境变量自己 dlopen。模块源码常上游已
+  in-tree，零补丁。模板与编译命令见 `../solutions/ohaudio-backend/` 与 `PORTING_NOTES.md`。
+- **第三种接入形状（源码内后端，2026-09 实证）**：库源码内自带**编译期音频输出驱动注册表**
+  （无运行时模块 loader，输出后端是源码文件 + 注册表数组/特性开关）→ **直接给库写一个源码内
+  OHAudio 后端文件**，经构建系统特性开关（`find_library('ohaudio')`）编进库本体，CLI 二进制
+  直接链接 `libohaudio.so`，经**执行器 HAP（fork+execv，cli-hnp-runner）**真跑。实测 renderer
+  被音频系统接受、真写帧 > 0——无需 NAPI 壳 dlopen。后端骨架、构建接线与机器判据见
+  `../solutions/ohaudio-backend/PORTING_NOTES.md` §「自带输出后端注册表的库」。
+
+## 可行性影响
+
+- **不是「编不出」，是「编得出但不出声」**——这是本域最容易误判的地方。关掉全部后端（如
+  `-DALSOFT_BACKEND_*=OFF`）能顺利产出 `.so`，但 `alcOpenDevice(NULL)` 返回 `NULL`，依赖播放
+  设备的用例全线回归（把播放端裁掉不算适配）。更隐蔽的是**编得出、exec 却起不来**：零售机上
+  "带 OHAudio 后端的独立二进制"exec 被 EPERM/127，必须改成 NAPI 壳 dlopen 才算真接入。
+- 有本资产时工作量是「照抄 NAPI 壳 + 接线」，`feasibility` 不因音频降级；没有它而硬交付 →
+  只能 `partial`。
+
+## 判定要点（scan 阶段）
+
+1. 命中本域 ⇒ `harmony_status: partial`、`replacement` 指向 `solutions/ohaudio-backend/`、
+   `solution_source: builtin-asset`、`asset_ref: pc-capability-domains/audio.md`。
+2. 只用到播放 ⇒ 可行性不降级；用到**采集** ⇒ 如实标注需权限且本资产未覆盖，按现场判断处理。
+3. 涉及播放的交付，**按交付形态选接入形状**（见上三种）：`cli` 走源码内后端 + 执行器 HNP
+   （第三形状，勿再「禁用全部音频后端」——那会把播放用例整组判 blocked）；`app`/NAPI 形态走
+   壳内 dlopen。别把「本轮没集成」写进 `capability_gaps`——sysroot 里 `libohaudio.so` 在位时
+   它是集成工作，不是平台缺口（证伪程序见 `pc-device-verify` 的 failure-triage）。
+
+## 验收要点（adapt 阶段）
+
+命中本域的交付，验收档位是 `audio-output`（`DOMAIN_EVIDENCE` 表），**必须捕获 `build/audio-verify.json`**。
+零售机 NAPI 壳版本四证缺一不可（全部取自设备 hilog `hilog -x | grep <tag>` 后誊入）：
+
+1. `dlopen 16/16` —— `OHAUDIO_LOAD: OK (resolved 16/16 OH_Audio* symbols)`（后端真接通）
+2. `stream_id ≠ 0` —— `OHAUDIO_SETUP: ... stream_id=<非0> Start=0`（renderer 真被音频系统接受）
+3. **全量命中** —— `bytes_pushed == bytes_delivered`（解码的每个字节都被回调消费，非半截）
+4. **真写帧** —— `OHAUDIO_CLOSE: frames_written > 0`（renderer 真从设备管线写出帧）
+
+> ⚠️ **别只看"播放没报错"**：只要 `stream_id == 0` 或 `frames_written == 0`，说明 renderer 没被
+> 设备接受（或后端被裁成空壳）——判假绿。另加解码端一证：`frames_ok == 素材帧数 && crc_fail == 0`
+> （实例实证）。判据全表与对照见 `../solutions/ohaudio-backend/README.md`。
+
+## 真机事实
+
+- `libohaudio.so` 在 `/system/lib64/ndk/`；**不需要 `LD_LIBRARY_PATH`**，
+  `/etc/ld-musl-aarch64.path` 默认已含该目录。
+- **renderer 通道按设备/执行通道分档**（2026-09 修正）：旧零售机（6.0 级，实例实测）三路 exec
+  全拒，NAPI 壳 LOAD 不 EXEC 是唯一实证通道；**新一点的平台（6.1 级，同月实证）经执行器 HAP
+  fork+execv 跑的 CLI、直接链接 `libohaudio.so`（DT_NEEDED）即可拿到 renderer**——真写帧 > 0。
+  上设备前先看设备指纹与既有实证的差距，别拿旧结论直接裁新设备，也别说「平台不行」。
+- **必须经签名 HAP 的 App 域 dlopen 才能拿到 renderer**：裸进程 exec 自签二进制、HiShell 桌面
+  exec、私有 HNP exec 三路全被拒（EPERM/127，实例实测）；NAPI 壳（LOAD 不 EXEC）是真出声的唯一
+  已实证通道。
+- 播放**无需任何权限**（`ohos.permission` 无）；采集才需 `MICROPHONE`。
+- 设备侧 `audio_server` / `audio_host` 常驻。
+- 验证平台：鸿蒙 PC **零售不可调试机**（HAD-W24 6.0.0.130，uid2000，API22，2026-09-02 实证）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/clipboard.md

@@ -0,0 +1,42 @@
+# 能力域：clipboard
+
+> 来源：AFFiNE 适配实证（2026-09-29，Electron clipboard.writeImage + READ_PASTEBOARD ACL）。命中共存场景：应用写剪贴板图片/富文本。
+
+## 能力描述
+
+应用读取或写入系统剪贴板（文本/图片/富文本）。PC 桌面语义下剪贴板是系统能力、通常无需特殊权限（macOS/Windows 写入免权限）；鸿蒙按读写与数据类型分权限档。
+
+## 鸿蒙状态
+
+**partial（权限授予分档，降级不崩溃）**：
+
+| 操作 | 所需权限 | 档位 | 本地调试链实际表现 |
+|---|---|---|---|
+| 写文本 | 免声明 | — | 可用 |
+| 写图片（Electron `clipboard.writeImage` 等） | `ohos.permission.READ_PASTEBOARD` | **acl（system_basic）** | 声明可保留、装机可过，但本地调试证书链**授不了**（授予态 -1）——写图降级不可用 |
+| 读剪贴板 | `READ_PASTEBOARD` | acl | joplin 实证**读写不对称**：本地链剪裁 ACL 后写可用、读不可用；读需 AGC release 链 |
+
+AGC 在线申请该 ACL 后 release 签名可恢复；最终授予态装机后 `bm dump -n <bundle>` 的 reqPermissionStates 取证。
+
+**降级语义**：权限未授时调用不崩溃、不弹错——应用自身行为正常，属可静默降级能力。Electron-OH 的 clipboard API 调用保留原样即可，无需 IPC 改造。
+
+## 替换方案
+
+1. **按降级设计**：写图失败不弹错不崩溃，UI 呈现「已复制」但实际降级时仅文本通道生效（或提示功能受限）；
+2. **声明 + 取证**：module.json5 声明 `READ_PASTEBOARD` + profile allowed-acls 在位，装机后 `bm dump` 记录实际授予态；
+3. **恢复路径**：AGC 在线申请 ACL → release 签名装机。
+
+## 可行性影响
+
+不构成适配阻断（feasibility 不降档）；影响的是「剪贴板图片类功能」的真机验收口径——本地链只能验「调用不崩溃」，授予效果属 release 链/人工验收项。
+
+## 典型库怎么接
+
+- Electron 应用：`clipboard.writeImage/write` 调用保留，权限按上表声明，降级语义写入 PRD（scope_out 或降级项）；
+- 应用含「截图到剪贴板/复制图片」功能，鸿蒙上权限已声明但功能不生效时——先查授予态（`bm dump`），不是 API 缺失。
+
+## 实证锚
+
+- AFFiNE：`clipboard.writeImage` + READ_PASTEBOARD acl 本地链授不了，降级不崩溃（04-summary sediment；capabilityDependencies）
+- joplin：剪贴板读写不对称首次记录（case-joplin §7）
+- 权限三层分类与申请编排：`app-permissions.md`（同目录）