@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/serial-port.md

@@ -0,0 +1,36 @@
+# 能力域：serial-port（串口通信）
+
+## 能力描述
+
+通过 UART/USB 转串口设备进行字节流通信：`termios`（`tcgetattr`/`tcsetattr`/`cfsetospeed`）配
+波特率/数据位/校验位，`open`/`read`/`write` 收发，外接调试探针（ST-Link / J-Link / Bus Pirate）
+这类 CLI 工具的底层链路。PC 上由 Win32 `\\.\COM*` / `/dev/tty*` + termios 提供。
+
+**典型触发**：源码里出现 `struct termios` / `tcgetattr` / `cfsetspeed`，或依赖 libserialport /
+wiringPi 等串口库。
+
+## 鸿蒙状态：available
+
+| 子能力 | 状态 | 说明 |
+|---|---|---|
+| termios API | available | NDK 提供完整 musl `termios.h`（`tcgetattr`/`tcsetattr`/`cfsetospeed` 等） |
+| USB 串口 DDK | available | NDK 提供 `usb_serial_api.h` 用于 USB 串口设备 |
+
+## 替换方案
+
+无需替换 API 面：termios 直接复用。
+
+## 可行性影响
+
+不降级。评估为 least_effort 类能力——命中本域不构成适配障碍。
+
+## 判定要点（scan 阶段）
+
+1. 命中本域 ⇒ `harmony_status: available`、`replacement: NDK musl termios 直接复用`、
+   `solution_source: builtin-asset`、`asset_ref: pc-capability-domains/serial-port.md`。
+2. 只编译不跑串口（CLI 的串口适配器作为一个可选 backend）⇒ 可先把该后端禁用/留空编译，
+   不影响主交付。
+
+## 典型库
+
+OpenOCD（Bus Pirate 适配器用 termios）、libserialport、minicom、ESP/STM32 烧录工具。

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

@@ -0,0 +1,79 @@
+# 能力域：subprocess-exec（子进程执行 + 多进程编排）
+
+## 能力描述
+
+CLI 工具或构建系统通过 `fork/execv` 调起外部子进程来完成工作，且依赖大量外部工具（bash、make、sed、awk、grep、tar、gzip、curl 等）的可用性。子进程链可能是层层嵌套的（如 `make` → `sh -c` → `gcc` → `as`/`ld`）。
+
+## 鸿蒙状态：partial（app 域限制 + 需全工具随包）
+
+| 部署形态 | 状态 | 说明 |
+|---------|------|------|
+| 仅 exec 自身 HNP 内二进制 | available | `fork/execv` 标准 POSIX API 可用，SELinux 放行 |
+| exec HNP 外系统二进制 | unavailable | SELinux 标签限制，仅可执行私有 HNP 内的 ELF |
+| exec 动态链接工具链（子进程再 exec 子子进程） | partial | 可行但所有嵌套工具也必须在 HNP 内 |
+| 跨进程通信（管道/信号） | available | `pipe()`、`dup2()`、`signal()`、`waitpid()` 标准 POSIX 可用 |
+
+**核心约束（实例实证）**：鸿蒙 app 域 `fork/execv` 可正常使用，但受 SELinux 约束，**仅可执行私有 HNP 内的二进制**。任何依赖系统 `/usr/bin/` 下工具的 CLI 工具，必须将所有依赖工具交叉编译为 aarch64-ohos ELF、ELF 自签（`.codesign` 段）、打进私有 HNP，成为 `hnp.json` 中 `bin/` 的一部分。
+
+## 判定方法
+
+| 步 | 做什么 | 证据形态 | 回答什么 |
+|---|---|---|---|
+| **E1 静态·符号面** | 对产物 `nm -D` 检查 `fork`/`execv`/`execve`/`popen`/`system` 等符号 | 符号清单 | 是否依赖子进程执行 |
+| **E2 路径·面** | 源码闭包搜索 `exec`、`system`、`popen`、`fork` 调用，收集所有被调用的外部命令名 | 命令清单 | 子进程需要哪些外部工具 |
+| **E3 行为·差分面** | 在设备上执行，确认 `execv` 返回 -1 则检查 errno | 设备日志 | 是否因 SELinux 或签名问题 exec 失败 |
+
+## 替换方案：全工具随包
+
+### 方案 1（推荐）：三层随包策略
+
+第 1 层——中心仓复用：从中心制品仓（cnb.cool OpenHarmonyPCDeveloper Conan）拉取预编译 aarch64-ohos 工具包，如 bash/coreutils/sed/gawk/curl/bzip2/xz/unzip/flex/bison/gettext/ncurses
+
+第 2 层——busybox-static 批量提供：busybox-static 以单二进制提供 95 个 applet（grep/tar/gzip/patch/diff/sort/wc/uniq/vi/less 等），大幅减少需单独编译的工具数。⚠️ **app 域 seccomp 对部分 applet 会 SIGSYS 击杀（rc=159）**——实证中招的既有文本处理管道组合（`set | grep -E`），也有网络下载 applet（`busybox wget` 直接 Bad system call）。busybox 单二进制的 syscall 组合更易踩出白名单，**验证链路上的关键 applet（下载/摘要/高频文本处理）必须用真 GNU ELF 替换**（wget→curl shim 模式见 `pc-knowledge-base/platform/鸿蒙PC-随包wrapper脚本shebang自指与busybox-seccomp.md`），busybox 只兜低频长尾。
+
+第 3 层——自编译关键工具：GNU make、python3 等无法通过 busybox 或中心仓覆盖的工具，走 autotools 交叉编译 + `-Wl,--code-sign` 重链
+
+所有 ELF 必须带 `.codesign` 段自签才能在 app 域 exec。
+
+### 方案 2：HNP 清单核对
+
+```
+HNP 内必须包含：
+bin/ 目录下全部被调工具（bash/make/sed/awk/grep/...）
+     ↓
+对 toolchain-bound 依赖：
+  1. 列出所有被 `exec`/`system`/`popen` 调用的命令名
+  2. 交叉编译为 aarch64-ohos ELF + 自签
+  3. 放进 `hnp.json` 的 `bin/` 条目
+  4. 打包后校验：unzip -l <库名>.hnp | grep 'bin/'
+```
+
+## 可行性影响
+
+- **工程量巨大但技术上可行**——依赖工具越多，随包工作量越大
+- 本域不直接降级 feasibility，但需在 PRD 中如实记录每个工具的随包方式（中心仓/自编译/scope_out）
+- 关键瓶颈：`glibc` 目标 libc 在 musl 宿主上不可构建（见 `pc-knowledge-base/case-studies.md`）
+
+## 判定要点（scan 阶段）
+
+1. 分析源码闭包中所有 `exec`/`system`/`popen` 调用的外部命令名
+2. 对每个外部命令，查 `pc-registry` 是否有已适配制品
+3. 对无品的命令，评估交叉编译难度（autotools/meson/cmake）
+4. 在 `library_closure` 中标记为 `toolchain-bound` 类型，`depends_on` 列出所有依赖工具
+5. 如果依赖工具数量 > 30 或包含 glibc 目标构建 → 标注 `is_bottleneck: true`
+
+## 验收要点（adapt 阶段）
+
+1. 所有被调工具在 HNP 内可执行（`hdc shell exec` 验证）
+2. 所有工具 ELF 签名验证通过（`readelf -S <binary> | grep codesign`）
+3. 子进程链端到端验证（如 `make` → `sh -c` → `sed` 三层调用）
+4. HNP 打包清单与预期工具清单一致（无遗漏）
+
+## 真机事实（实例实证）
+
+- 核心工具可从中心仓拉取预编译版本（bash/coreutils/sed/gawk/curl/bzip2/xz/unzip/flex/bison/gettext/ncurses/busybox-static/python3）
+- busybox-static 以单二进制提供 95+ 个 applet（grep/tar/gzip/patch/diff/sort/wc/uniq 等），大幅减少需单独编译的工具数；但 app 域 seccomp 对部分 applet SIGSYS（rc=159）——某交叉工具链工程 实证 `busybox wget` 下载链路直接被杀，wget/sha512sum 换 curl+coreutils 真 ELF 后全路径通过
+- GNU make 需自编译（autotools + `-Wl,--code-sign` 重链）
+- 全部 ELF 需带 `.codesign` 段自签才能在 app 域 exec
+- 设备验证：`execv` 成功（ELF 签名、SELinux 标签、动态链接全链路打通）
+- 核心旅程因需完整 GNU 工具链 + 网络 + 数小时编译而 scope_out（评估非阻塞）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/swing-jdk-gui.md

@@ -0,0 +1,49 @@
+# 能力域：swing-jdk-gui（Swing/JDK GUI 栈）
+
+## 能力描述
+
+基于 Java Swing / JavaFX / AWT 的 GUI 应用所需能力栈：JDK GUI 库（Swing 组件 / JavaFX / AWT 本地窗口）、Java2D 渲染、窗口系统后端对接（AWT 经 X11/Win32/Cocoa）、事件分发线程（EDT）。
+
+## 鸿蒙状态
+
+**unavailable**（JDK GUI 工具链未就绪）
+
+- 鸿蒙 PC 有 Java 运行时（可跑非 GUI Java），但 **Swing/JavaFX/AWT 的 GUI 栈未移植**——AWT 的本地窗口后端依赖 X11/Win32/Cocoa，鸿蒙无对应。
+- 没有鸿蒙版的 Swing/JavaFX 运行时可直接用。
+- 不像 Qt 有 QPA 抽象层可对接 ArkUI，Swing/JavaFX 缺这样的鸿蒙适配层。
+
+## 替换方案
+
+| 原能力 | 鸿蒙替换 | 状态 |
+|--------|---------|------|
+| Swing/JavaFX 组件 | 无直接替换；需迁移到 ArkUI/Qt 等鸿蒙化 GUI 框架重写 UI 层 | unavailable |
+| AWT 窗口后端 | 鸿蒙无 AWT 后端 | unavailable |
+| Java2D 渲染 | 可考虑经 XComponent+EGL 自绘，但非 Swing 标准路径 | partial（非标准） |
+| 纯 Java 逻辑层（非 GUI） | 鸿蒙 Java 运行时可跑 | available |
+
+## 可行性影响
+
+- **Swing/JavaFX GUI 应用**：`delivery_form=app-unsupported`，`capability_dependencies` 命中 `swing-jdk-gui=unavailable` → **feasibility: infeasible ~ hard**。GUI 层无鸿蒙运行时，需整体重写 UI 到 ArkUI/Qt。
+- scan 应判 `feasibility=infeasible`（或 `hard` 若允许 UI 层重写、逻辑层复用），`recommended_path` 给路线图：① 逻辑层（纯 Java）经鸿蒙 Java 运行时复用；② UI 层从 Swing/JavaFX 迁移到 ArkUI 或 Qt（需重写）；③ 在 `harmony-app/` 用新 UI 框架重建界面。
+- **不硬做**：不要试图交叉编译 Swing/JavaFX 字节码 + 找 AWT 后端——后端不存在，编出来也跑不起来。
+
+## 典型场景怎么接
+
+### Java+Swing 应用
+1. scan 判 `delivery_form=app-unsupported`、`capability_dependencies=[swing-jdk-gui:unavailable]`。
+2. feasibility=infeasible（UI 层无运行时）或 hard（若用户接受 UI 重写）。
+3. adapt 阶段**跳过**（infeasible 时编排器跳过 baseline+adapt，直接进 summary 沉淀路线图）。
+4. summary 给出路线图：逻辑层复用 + UI 迁移到 ArkUI/Qt 的改造方案，供后续人工/半自动迁移。
+
+### Java+JavaFX 应用
+- 同 Swing：JavaFX GUI 栈鸿蒙未移植。feasibility=infeasible/hard，路线图同上。
+
+### 含 Java 逻辑但非 GUI（如某 Java 命令行工具/库）
+- 不命中本能力域（无 GUI）。按纯运行时或 native-extension(JNI) 走对应交付形态，feasibility 不受本域影响。
+
+## scan 判定要点
+
+- 识别 Swing/JavaFX/AWT 使用：源码/构建里出现 `javax.swing`/`javafx`/`java.awt`/`JFrame`/`Application`（JavaFX）/ `EDT` 等。
+- **区分 GUI 应用 vs 含 Java 的非 GUI**：只有用到 Swing/JavaFX/AWT GUI 组件才命中本域；纯 Java 逻辑不命中。
+- 命中即 `delivery_form=app-unsupported`、feasibility 倾向 infeasible/hard。
+- evidence 来自生产代码的 GUI 组件使用处。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/system-file-icon.md

@@ -0,0 +1,116 @@
+---
+name: system-file-icon
+description: 系统文件图标能力域。鸿蒙 partial——有官方 API fileManagerService.getFileIconSync（按文件类型 UTD-ID 取图标，权限 normal 声明即得），但只按类型不按文件；纯 native 无解。真机 9/9 实证
+metadata:
+  type: capability-domain
+  source: 实际适配案例（2026-07-31 真机验证）
+---
+
+# 能力域：system-file-icon（系统文件图标）
+
+**鸿蒙状态：`partial`** —— 能力有、且普通应用够得着；但语义比 Win/mac 窄一档（按**类型**不按**文件**），且**只在 ArkTS 侧**。
+
+> 典型触发：`SHGetFileInfoW` / `SHGetImageList` / `IImageList::GetIcon`（Win）、`NSWorkspace iconForFile:`（mac）、
+> Electron `app.getFileIcon`、文件管理器/下载列表要显示文件图标的库。
+
+## 一、替换方案（本体）
+
+```typescript
+import { fileManagerService } from '@kit.FileManagerServiceKit';
+import { uniformTypeDescriptor } from '@kit.ArkData';
+import { resourceManager } from '@kit.LocalizationKit';
+
+// 后缀 → UTD-ID → 系统图标
+const typeId: string = uniformTypeDescriptor.getUniformDataTypeByFilenameExtension('.txt'); // 'general.plain-text'
+const icon: ResourceStr = fileManagerService.getFileIconSync(typeId);                        // Resource
+// 直接上屏：Image(icon)  —— 这是最省的用法，ArkUI 自己解析
+```
+
+`module.json5` 声明 `ohos.permission.GET_FILE_ICON` 即可。**该权限是 open / system_grant / normal**——
+安装即授予，**不需要** `requestPermissionsFromUser`，不需要 ACL，不弹窗。
+
+**要原始字节**（对应上游原库那种返回 Buffer 的 API）：
+
+```typescript
+// 返回的 Resource 是 id=-1 + params=['sys.media.ic_grid_txt'] 形态，
+// 用 app 自己的 resourceManager 取会失败（9001002 / 9001003）——必须走系统资源管理器，
+// 且资源名要去掉 'sys.media.' 前缀。
+const r = icon as Resource;
+const name = r.params![0].replace('sys.media.', '');            // 'ic_grid_txt'
+const bytes = resourceManager.getSystemResourceManager().getMediaByNameSync(name);
+// bytes 是 **SVG**（336×336 矢量），不是 PNG
+```
+
+要 PNG 再走 Image Kit：`image.createImageSource(bytes.buffer)` → `createPixelMap({desiredSize})` →
+`ImagePacker.packing(pm, {format:'image/png'})`。原库的 `size: 16|32|64|256` 参数正好由 `desiredSize` 承接，
+**矢量源任意缩放不失真**，这一点比原库强。
+
+## 二、两处必须如实记的降级
+
+| 维度 | Win/mac 原语义 | 鸿蒙 | 影响 |
+|---|---|---|---|
+| 粒度 | 按**文件**（`.exe` 自带图标、单文件自定义图标、文件夹缩略图） | 按**文件类型 UTD-ID** | 同类型文件图标相同；拿不到 exe 自带图标 |
+| 关联应用图标 | 返回关联应用的图标 | 够不着 | 见下 |
+
+**「按关联应用取图标」这条路普通应用走不通**：`bundleManager.getAbilityInfo(uri, abilityFlags)`（API 20，
+仅 PC/2in1）能按 URI/文件类型查关联 Ability，但权限 `ohos.permission.GET_ABILITY_INFO` 是
+**restricted / system_basic** —— 需 ACL，普通应用申不到。所以按类型取图标是唯一可行路径。
+
+## 三、纯 native 无解（否定性结论，已取证）
+
+NDK **有**半条路：`database/udmf/utd.h`（`libudmf.so`，API 12+，设备 `/system/lib64/ndk/libudmf.so` 在盘）
+
+- `OH_Utd_GetTypesByFilenameExtension(".txt", &n)` → `general.plain-text` ✓ 可用
+- `OH_Utd_GetIconFile(utd)` → **返回资源名不是文件路径**
+
+真机实测（NDK 交叉编译的小 C 程序，`stat()` 判定）：
+
+```
+ext=.txt   typeId=general.plain-text   icon=sys.media.ohos_ic_normal_white_grid_txt   stat=ENOENT
+ext=.docx  typeId=org.openxmlformats…  icon=<空串>
+```
+
+`/system/etc/utd/conf/uniform_data_types.json` 全表**只有 50 条**带 `iconFile`，其余为空。
+资源名要落成像素必须过资源管理器，而 NDK 的资源管理器需要 ArkTS 上下文 → **native 拿不到图标像素**。
+同型先例：`pc-knowledge-base/platform/鸿蒙PC-窗口几何控制无native只ArkTS.md`（能力在 ArkTS 侧，native 只能反向桥）。
+
+## 四、可行性影响 / 怎么判
+
+**不要判 `infeasible`。** 能力存在，判死是错的（初代案例首轮就这么错的）。
+
+| 场景 | 判定 |
+|---|---|
+| 交付形态本就是 ArkTS/HAP | `feasible`，直接用上面的方案 |
+| 上游是 N-API/`.node`（Node 侧扩展） | `feasible_with_effort` + **交付形态迁移到 ArkTS 侧**——`.node` 跑在设备 Node 进程里，够不着 `fileManagerService`。要保 Node 形态只能反向桥（宿主是 ArkUI 应用内嵌 Node 时用 `napi_threadsafe_function` 回调 ArkTS） |
+| 只要「有个图标就行」 | `feasible`，未知后缀有 `ic_grid_unknown` 问号兜底 |
+
+**`infeasible` 的语义是「换任何交付形态都做不到」**，而不是「原形态做不到」——见 `pc-schemas/semantics/enum-semantics.md`。
+
+## 五、真机实证（可调试鸿蒙 PC，OpenHarmony 6.1.0.115 / API 23）
+
+最小 HAP（声明 `GET_FILE_ICON`，`aboutToAppear` 自动跑），9 个后缀 **9/9 取到图标并真实上屏**：
+
+| 后缀 | UTD-ID | 图标资源 | 字节 |
+|---|---|---|---|
+| `.txt` | `general.plain-text` | `ic_grid_txt` | SVG 5839B |
+| `.pdf` | `com.adobe.pdf` | `ic_grid_pdf` | SVG 10771B |
+| `.png` | `general.png` | `ic_grid_image` | SVG 4327B |
+| `.zip` | `general.zip-archive` | `ic_grid_zip` | SVG 5200B |
+| `.mp4` | `general.mpeg-4` | `ic_grid_video` | SVG 3996B |
+| `.docx` / `.md` | …`wordprocessingml.document` / `general.markdown` | 同为 `ic_grid_doc` | SVG 5200B |
+| `.hap` | `openharmony.hap` | `ic_grid_applications` | SVG 4514B |
+| `.zzzz`（构造的未知后缀） | `flex.zh45depjopj5hu6q` | `ic_grid_unknown` | SVG 4860B |
+
+两条坑，都是实测撞出来的：
+
+- **未知后缀不会 miss**：UTD 会给它自动生成 `flex.*` 类型（不是抛错、不是空），图标是问号兜底。
+  想识别「未知类型」得判 `typeId.startsWith('flex.')`，不能指望异常。
+- **`.md` 与 `.docx` 同图标**：按类型归组的直接后果，同组文件图标完全一致（连字节数都相同）。
+
+映射表本体在设备 `/system/etc/file_manager_service/utd_ids.json`（UTD-ID → `sys.media.ic_grid_*`），
+后缀→UTD-ID 全表见官方《图标格式说明》。
+
+## 相关
+
+- `pc-knowledge-base/platform/鸿蒙PC-能力存在性以SDK声明为准.md` —— 本域当初被误判为 unavailable 的根因与探测程序
+- `pc-knowledge-base/platform/鸿蒙PC-窗口几何控制无native只ArkTS.md` —— 「能力只在 ArkTS 侧」的同型先例

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

@@ -0,0 +1,51 @@
+# 能力域：sysv-ipc
+
+> 状态：**已设备验证**（2026-09 某 C++ 框架库适配轮次沉淀，匿名化）
+> 本文件提供 SysV IPC（信号量/共享内存命名模式）在鸿蒙 app 域的行为判定与替换方案。
+
+## 能力描述
+
+SysV IPC 三件套（`ftok`/`semget`/`semop` 信号量 + `shmget`/`shmat`/`shmdt` 共享内存）与
+POSIX 命名共享内存（`shm_open`/`mmap(MAP_SHARED)`），用于跨进程互斥（命名互斥锁/命名事件）
+与共享内存数据交换。
+
+## 鸿蒙状态
+
+**unavailable（app 域）**，具体两个独立失效机制（均已真机验证）：
+
+1. **SysV 信号量 → seccomp SIGSYS 秒退**：`ftok`+`semget`+`semop` 在 app 域被 seccomp
+   拦截为非法系统调用，进程收到 SIGSYS 直接死亡。**在静态全局构造阶段即触发**——不等
+   main() 开始、没有机会 try-catch，表现为「启动即崩溃、零输出」。
+2. **`shm_open` 命名共享内存 → mmap 死锁**：`shm_open("/dev/shm/...")` + `mmap(MAP_SHARED)`
+   在 app 域 mount namespace 下**永久挂起**（worker 线程不可恢复死锁，两轮复现）。根因是
+   app 域 mount namespace 对 `/dev/shm`（tmpfs）的隔离或 MAP_SHARED 在该命名空间的行为异常。
+
+注意区分：**普通文件 + `mmap(MAP_SHARED)` 是可用**的（见替换方案），死的只是 `shm_open`
+命名对象路径。
+
+## 替换方案
+
+| 失效面 | 替换 | 已验证 |
+|--------|------|--------|
+| NamedMutex/NamedEvent（SysV 信号量） | 切**上游 Android 桩后端**（条件编译 `#if defined(__OHOS__)` 引入）：构造空操作、`lock/set/wait` 抛 `NotImplementedException` | ✅ 设备侧桩用例通过 |
+| `shm_open` 命名共享内存 | **文件映射构造函数** `SharedMemory(File(path), mode)`：先 `write_file` 预创建文件，再 `open()`+`mmap(MAP_SHARED)` 普通文件 | ✅ 设备侧往返用例通过 |
+| 锁文件硬编码 `/tmp` | TMPDIR 环境变量分支（exec 前注入可写沙箱目录） | ✅ 设备侧通过 |
+
+## 可行性影响
+
+- 跨进程互斥/事件能力**降级为桩语义**：PRD 断言按「构造不崩溃 + 调用抛 NotImplementedException」重写，不再验证实际互斥行为。
+- 共享内存在**文件映射模式下可用**（写入→读回往返一致）；命名模式被判定为 unavailable。
+- 对单进程内功能（线程、文件、网络、数据库等）**零影响**——失效面仅在跨进程 IPC。
+
+## 典型库怎么接
+
+识别条件：编译产物或静态构造路径出现 `semget`/`semop`/`ftok`/`shmget`/`shmdt`/`shm_open`
+符号引用。出现即按上述替换方案处理，并注意：
+
+1. **静态构造秒退的杀伤力**：SysV 信号量若在静态/全局构造中被调用，库在 app 域连启动都
+   不可能——必须**编译时**切桩（`#if defined(__OHOS__)` 条件编译），不能指望运行时 try-catch。
+2. **PRD 断言随之改写**：桩语义下「命名互斥可用」的功能点需改为「桩不崩溃 + 调用抛异常」。
+3. **文件映射替代的细节**：`SharedMemory(File, mode)` 的 `_size = file.getSize()`，必须
+   预创建正确大小的文件（如 `write_file(path, string(4096, '\0'))`）再映射。
+4. **同型库参考**：任何使用 SysV IPC 或 `shm_open` 的 C/C++ 库（跨进程互斥、共享缓存、
+   多进程队列等）都适用本方案。

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

@@ -0,0 +1,77 @@
+# 能力域：terminal-render（终端可见渲染）
+
+## 能力描述
+
+库的价值在**往终端屏幕画东西**：光标移动、颜色、行编辑回显、折行重绘、TUI 界面——
+产物运行时向终端发转义序列（CSI/SGR），屏幕上呈现什么，就是它的交付质量。
+这层真实存在且可观察，但与「链接成功」「用例全绿」完全解耦（渲染走静默降级不报错，
+readline 实测：降级状态下功能用例全过）。
+
+**典型触发**（判定判据，全程无库名）：产物运行时会**发序列**——三通道任一：
+
+| 通道 | 查什么 | 定位 |
+|---|---|---|
+| **A：控制序列字面量（主判据）** | 源码闭包出现 `"\x1b["` / `"\033["` / `\e[` 等 CSI/SGR 构造 | 纯字节码信号，零生态依赖 |
+| **B：终端能力库发射族（补充）** | `.dynsym`（含依赖 `.a` 的 nm）命中 `tputs`/`tgoto`/`waddch`/`wrefresh`/`mvadd*`/`refresh` | 专治通道 A 失明：经能力数据库渲染的库，序列内容在**数据文件**里，源码 grep 不到 |
+| **C：静态链入兜底** | 对依赖闭包 `.a` 逐个 `nm` 匹配发射族 | 静态链入时符号不落产物 `.dynsym`（readline 案例形态） |
+
+**T4（PRD 旁证）**：PRD 功能点文本含 折行/重绘/光标/多行/分页/redraw/wrap → 记入判定
+证据提升置信度；是旁证不是必要条件。
+
+> **两条发射事实（2026-09 某图像库 实测，纠正「无 TTY 不发射」的误判）**：
+> 1. **彩色/进度序列常走 stderr 而非 stdout**——库的 print/warn/error 写 fd2（如 `cimg::output()`
+>    即 stderr）或等价通道。demo 捕获只 `dup2` 重定向 stdout 会**捕不到任何序列**，遂误判「降级/不发射」。
+>    接线必须 stdout+stderr **双通道捕获**（`dup2(pipe_w, STDERR_FILENO)`），序列才落网。
+> 2. **VT100/彩色输出多是编译期宏、无运行时 isatty 检查**——`cimg_use_vt100` 之类在编译期决定
+>    是否内联彩色输出，运行时**不看** `isatty()`。因此「无 TTY 环境所以不发射」这个归因**不成立**
+>    （无 TTY 也照发序列）。blocked 不能挂在「缺 TTY」上：先核输出通道（stderr）、再核发射开关
+>    （编译宏），两者都排除了才轮到渲染宿主。
+
+## 判定纪律（三条，任何实现都不得违反）
+
+1. **判定路径零库名**——readline/ncurses 只做验证实例与案例溯源，库名只允许出现在
+   skill 触发词里
+2. **只收机制的公共接口**：发射族符号是「终端能力数据库输出」这一机制的公共 API 面
+   （无数无关的库都调）；单库私有 API（如 `rl_redisplay`）永不入表
+3. **查询 API 不算发射**：`tgetent`/`tgetstr`/`tiget*` 是数据读取族，归
+   `runtime-data-assets`（E130）——同库可双命中，但两域互不推导。getpass 型库
+   （只查能力+关 echo，从不画）在两域下都零告警
+
+## 鸿蒙状态：partial（termios/PTY 可用；渲染宿主需自备）
+
+- 终端子系统完整可用（见 `terminal-runtime.md`）——序列发得出去
+- **设备上没有系统终端 app**：零售机 HiShell 不可编程驱动，无人替库把序列画出来
+- 替换方案 = 上屏终端壳 demo（`cpp-terminal-demo`）：HAP 内嵌 PTY 宿主 + VT 渲染面，
+  库在真机上被真实驱动、渲染真落在设备屏幕上
+
+## 验证方案：三件套（语义级机判 + 可视存档）
+
+| 件 | 形态 | 职责 |
+|---|---|---|
+| ① 屏幕 buffer 断言 JSON | pyte 重放 PTY 落盘流 → 断言折行位置/光标落点/SIGWINCH 重排 | **机判 ground truth**——buffer 不对 = 渲染错 |
+| ② PTY 原始捕获 | `build/device-runs*/` 逐用例流文件 | ①的可重放依据（证据自洽） |
+| ③ demo 截图 | `verify-demo` | 可视存档（人工裁量/汇报） |
+
+- 断言锚定已知宽度：用例显式设 `stWinsize`/COLUMNS
+- pyte 跑在开发机（`pip install pyte`）；缺失时降级为「序列在场」机判 + 截图人工看
+- 操作方法：pc-device-verify「终端上屏验证」操作节
+
+**归因语义（防悬案）**：buffer 断言失败 → **第一嫌疑 E130**（terminfo 等运行时数据未随包
+→ 静默降级 → 没画出东西），补随包重测；数据随包+自举完备仍失败 → 才是渲染缺陷或
+scan 误判，分诊裁决。
+
+## 可行性影响
+
+- **不是「编不出」，是「编得出但画没画对没人知道」**——与 E130 同一陷阱形态：
+  链接期自包含 ≠ 渲染期正确，且降级静默、全绿共存
+- 有本条目时：三通道判定与三件套验证是机械步骤，feasibility 不降级；
+  漏判而硬交付 → 交付的是「渲染效果无人见过的库」，恰是 readline 两轮假绿的空白层
+
+## 关联
+
+- `terminal-runtime.md`（终端环境域——本域的环境前提，AND 正交）
+- `runtime-data-assets.md`（E130：终端能力**数据**的判定与随包方案——渲染失败的
+  第一嫌疑归属地）
+- E130（错误条目：数据缺失静默降级的完整复盘）
+- pc-device-verify「终端上屏验证」操作节（操作方法权威）
+- pc-test-design case-design-methods §6（三段式行为差分模板——本域 E3 是其语义化升级）

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

@@ -0,0 +1,46 @@
+# 能力域：terminal-runtime（终端运行环境依赖）
+
+## 能力描述
+
+库**需要终端环境才有意义**：进入/恢复终端原始模式、按行/按字符读输入、感知屏幕尺寸——
+即依赖 POSIX 终端子系统（termios/PTY）。这类库不是 GUI 库（不往图形面画东西），
+但把它当纯计算库测也测不到点子上：**没有 PTY，它的输入路径根本走不通**。
+
+典型触发（判定判据，无库名）：
+
+- 源码闭包命中 termios/PTY **调用点**：`tcsetattr` / `tcgetattr` / `cfmakeraw` /
+  `forkpty` / `openpty` / `posix_openpt`（须有调用点，仅 include 头文件不算）
+- 或屏幕尺寸感知字面量：`TIOCGWINSZ` / `TIOCSWINSZ` / `COLUMNS` / `LINES`
+- 佐证（记入判定证据，非必要条件）：PRD 功能点文本含 输入/回显/行编辑/终端模式 类语义
+
+## 鸿蒙状态：available（termios/PTY 完整可用）
+
+POSIX-NDK 能力探针矩阵实测：termios（tcgetattr/tcsetattr）、PTY（posix_openpt/openpty/
+forkpty）、信号（sigaction/SIGWINCH）、select/pselect 均可用。终端运行环境**不缺**——
+缺的只是「谁给它一个终端」（见下）。
+
+## 载体指引
+
+- **CLI/PTY 是这类库的原生使用形态**——它们生来就在终端里被调用。因此本域命中的库
+  双载体时 CLI 侧不是硬造，是原生路径（私有 HNP 执行器内可用 PTY 驱动）
+- 需要「输入可编程的终端」时：宿主侧 forkpty + scripted 键序（设备上无系统终端 app 可用，
+  零售机 HiShell 不可编程驱动）
+- 只命中本域（**不**命中 terminal-render）的库：证据档位维持 device-log，不需要上屏 demo、
+  不需要截图——**「要终端环境」≠「要上屏验证」**，两域独立判定、互不推导
+
+## 与 terminal-render 的关系
+
+AND 正交、可叠加：readline 类库两域双中（既依赖终端环境，又产出可见渲染）；
+只管历史/键表不画的库只中本域。渲染效果的正确性判定归 terminal-render 管，
+本域只回答「得给它一个终端才能测」。
+
+## 可行性影响
+
+- 平台能力齐备，feasibility 不降级
+- 漏判的代价不是假绿而是测不到点：输入路径没被 PTY 驱动过的用例，覆盖度是虚的
+
+## 关联
+
+- `terminal-render.md`（渲染效果判定与上屏方案——与本域 AND 正交）
+- `runtime-data-assets.md`（终端能力数据族——terminfo 类读取的判定与随包方案）
+- pc-device-verify「终端上屏验证」操作节（PTY 捕获与 scripted 键序的操作方法）

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

@@ -0,0 +1,71 @@
+# 能力域：terminal-tui（交互式终端 UI）
+
+## 能力描述
+
+依赖 curses/ncurses 全屏界面的交互式终端应用（TUI），需要真实 TTY 分配才能正常工作。典型场景：`menuconfig`、`nconfig`、`htop`、`vim`、`less`、`nano`、`dialog` 等基于 curses 的全屏交互工具。
+
+## 鸿蒙状态：unavailable（HNP CLI 执行器无 TTY）
+
+| 部署形态 | 状态 | 说明 |
+|---------|------|------|
+| HNP CLI 执行器（cli-hnp-runner） | unavailable | fork/execv + 管道捕获输出，不分配真实 TTY。`isatty(0/1/2)` 返回 false，curses `initscr()` 失败 |
+| 纯终端环境（adb shell、SSH 等） | available | 标准 TTY 分配，交互式 TUI 可正常使用 |
+| 系统应用 HAP 内嵌终端 | partial | 可通过 `@ohos.multimedia.session` 或 ptty 模拟，但非标准路径 |
+
+**核心事实（实例实证）**：cli-hnp-runner 执行器通过 `fork/execv` 启动子进程，stdout/stderr 被管道捕获用于 TAP 日志。子进程的 `isatty(0/1/2)` 返回 false，curses 的 `initscr()` 因无法打开 `/dev/tty` 而失败。这是**执行器形态限制**，不是平台 API 缺失——OHOS 内核本身支持 ptty 分配。
+
+## 判定方法
+
+| 步 | 做什么 | 证据形态 | 回答什么 |
+|---|---|---|---|
+| **E1 静态·面** | 对产物 `nm -D` 检查 `initscr`/`newterm`/`setupterm`/`new_panel`/`new_menu` 等 curses 符号 | 符号清单 | 是否依赖 curses 全屏界面 |
+| **E2 路径·面** | 源码闭包搜索 `isatty`、`initscr`、`/dev/tty`、`TIOCGWINSZ` 等 TTY 相关调用 | 调用清单 | 是否依赖 TTY 分配 |
+| **E3 行为·差分面** | 在设备上执行，确认 `initscr()` 返回 NULL 或 `isatty(1)` 返回 false | 设备日志 | 功能是否真正退化 |
+
+## 替换方案：非交互流程替代
+
+### 方案 1（推荐）：非交互模式替代
+
+大多数 TUI 工具都提供非交互的命令行替代方案：
+
+| TUI 工具 | 非交互替代 |
+|----------|-----------|
+| `menuconfig` / `nconfig` | `conf --defconfig` / `--olddefconfig` / `--savedefconfig` |
+| `htop` | `ps` / `top -b -n1`（批处理模式） |
+| `vim` | `sed` / `awk` / `ed`（脚本化编辑） |
+| `dialog` | `printf` + 参数传递 |
+
+### 方案 2：TTY 模拟（不推荐，工程量大）
+
+在 cli-hnp-runner 中分配伪终端（ptty pair），通过 master 端写入输入、读取输出。这需要：
+- 在 native 代码中 `open("/dev/ptmx")` 或使用 `posix_openpt()`
+- 将子进程的 stdin/stdout/stderr 连接到 slave 端
+- 在 master 端实现输入注入和输出捕获
+
+**注意**：OHOS 的 `/dev/ptmx` 在 app 域可能受 SELinux 限制，需事先验证。
+
+## 可行性影响
+
+- **不是"编不出"，是"形态限制"**——TUI 二进制交叉编译完全可行（如 ncurses 可正常交叉编译），但运行时在 HNP CLI 执行器形态下因无 TTY 而功能退化
+- 交付前必须明确：**交互式 TUI 功能在 HNP CLI 形态不可用，以非交互流程替代**
+- 如果用户要求在 HNP CLI 形态下使用交互 TUI → 不可行，需改为 HAP 形态或系统应用形态
+
+## 判定要点（scan 阶段）
+
+1. 在依赖闭包分析中，如果发现 `ncurses`、`dialog`、`cdk` 等 TUI 库，或 `curses` 符号引用，标记 `capability_dependencies[]` 为 `terminal-tui`
+2. `solution_source` 为 `builtin-asset`，`asset_ref` 指向本文件
+3. 在 `feasibility` 判定中，terminal-tui 本身不降级 feasibility（是功能降级而非阻断），但需在 PRD 中明确标注替代方案
+
+## 验收要点（adapt 阶段）
+
+命中本域的交付，`03-adapt.json` 的 `remaining_blockers` 或 `test_run.roster.missing` 中必须：
+- 记录哪些 TUI 用例被替换/降级
+- 证明非交互替代流程在设备上正常工作
+- 在交付说明中置顶「交互式 TUI 不可用」的告知
+
+## 真机事实（实例实证）
+
+- `menuconfig`/`nconfig` 在 cli-hnp-runner 上不可用（`isatty` false → `initscr` 失败）
+- 替代方案：`conf --defconfig` / `--olddefconfig` / `--savedefconfig` 全套非交互流程正常
+- 非交互流程覆盖了配置管理模块的全部 P0/P1 功能点
+- 功能降级仅影响交互式 UX（P2 级功能点），核心能力未受损

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

@@ -0,0 +1,43 @@
+# 能力域：tray
+
+> 来源：AFFiNE 适配实证（2026-09-29，Electron Tray + popUpContextMenu）+ yesplaymusic 托盘双退出消解（2026-09-18）。命中共存场景：应用关闭到托盘/托盘快捷菜单/托盘提示。
+
+## 能力描述
+
+PC 桌面语义的系统托盘：常驻图标 + 右键菜单（含程序化弹出 `popUpContextMenu`）+ tooltip + 点击行为。应用常把「关闭窗口 = 隐藏到托盘」作为核心交互。
+
+## 鸿蒙状态
+
+**partial（常驻菜单模式，无传统桌面托盘语义）**：
+
+| Electron API | Electron-OH 行为 |
+|---|---|
+| `new Tray(image)` | 支持（常驻菜单模式） |
+| `tray.setContextMenu(menu)` | 支持——菜单显隐交系统常驻菜单管理 |
+| `tray.setToolTip` | 部分支持 |
+| `tray.popUpContextMenu()` | **不支持**（无程序化弹出接口） |
+| 退出路径 | 托盘菜单由系统追加「退出」项，走系统协商终止（平台语义 §2/§3） |
+
+鸿蒙 PC 无传统桌面托盘语义：托盘交互降级为系统常驻菜单，属**非核心旅程的体验差异而非功能阻断**。
+
+## 替换方案
+
+1. **保留 `new Tray` + `setContextMenu`**，菜单项与图标用应用自身资源；
+2. **`popUpContextMenu()` 调用点包 `isOHOS()` 守卫跳过**（AFFiNE patches/0001 #3）——无需 IPC 改造；
+3. **应用侧「退出」菜单项移除**（isOHOS 门控）——系统已追加退出项，不删会双退出（yesplaymusic P16 实证，平台语义 §2）；
+4. 关闭到托盘类行为依赖窗口隐藏 + 托盘恢复的，参照 joplin §5 的 `onPrepareToTerminateAsync` 模式（隐藏 + 启动器恢复）。
+
+## 可行性影响
+
+不构成适配阻断；托盘「弹出式菜单」「tooltip」等体验差异记入 PRD 降级项。核心风险在**退出路径语义**（双退出/清理钩子被跳过），见平台语义 §2/§3。
+
+## 典型库怎么接
+
+- Electron 应用：按上表守卫差异点（跳 popUpContextMenu/setToolTip 差异、移除应用侧退出项）；
+- 应用托盘菜单弹层异常/点击无响应时——先确认是「常驻菜单模式」（显隐由系统管理）还是 API 未支持，别按桌面语义调程序化弹出。
+
+## 实证锚
+
+- AFFiNE：popUpContextMenu 包守卫跳过，setContextMenu 常驻菜单正常（03-adapt issues_resolved；04-summary sediment tray 条）
+- yesplaymusic：托盘双退出消解 + P16 托盘双退出回归（case-yesplaymusic §8）
+- 平台语义 §2/§3：托盘系统退出与退出语义三档