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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/errors/E323.md

@@ -0,0 +1,52 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E323: Qt6DBus 不可消费修复：FEATURE_dbus 开启 + dbus/1.14.10 依赖 + Qt6::DBus 组件（qtbase 6.11.1 案例）
+
+> **严重度**: 🟡 medium | **分类**: build-system, cmake, conan, qt6 | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+find_package\(Qt6DBus.*REQUIRED.*NO_MODULE.*not found
+Failed to find required Qt component "DBus"
+Qt6DBusConfig\.cmake.*does NOT exist
+Qt6_FOUND.*FALSE.*DBus
+Qt6DBus\.so.*No such file
+```
+
+## 根因
+
+qtbase/6.11.1 配方 generate() 硬编码 "FEATURE_dbus": "OFF"，Qt6DBus
+模块未参与构建，已发布制品包无 libQt6DBus.so、无 lib/cmake/Qt6DBus/
+Qt6DBusConfig.cmake、package_info 无 dbus 组件；依赖 Qt6DBus 的下游
+find_package(Qt6DBus 6.9.0 REQUIRED NO_MODULE) 必然失败（Qt6_FOUND 被
+Qt6Config.cmake 置 FALSE："Failed to find required Qt component 'DBus'"）。
+并非 dbus 未发布，而是 qtbase 自身功能开关关闭导致的不可消费。
+
+## 验证命令
+
+```bash
+conan create 〈外部知识库归档〉 -pr:h=〈外部知识库流水线〉 -pr:b=〈外部知识库流水线〉 --build=missing; test_package: find_package(Qt6 6.9.0 REQUIRED COMPONENTS DBus NO_MODULE)
+```
+
+## 解决方案
+
+**(1) requirements() 新增 self.requires("dbus/1.14.10")；(2) generate() 将
+FEATURE_dbus 改为 ON，并把 dbus package_folder 追加进 CMAKE_PREFIX_PATH
+使 find_package(DBus1) 命中；(3) package_info() 补 dbus 组件
+(libs=["Qt6DBus"], requires=["core"], cmake_target_name="Qt6::DBus")；
+(4) conan create 复验 libQt6DBus.so 与 Qt6DBusConfig.cmake 产出后下游
+find_package(Qt6DBus REQUIRED NO_MODULE) 可消费。**：通用模式：Qt 组件缺失不可消费时，定位首错（缺失组件 Config 文件）→
+检查配方 generate() 中对应 FEATURE_ 开关与依赖声明 → 开启开关 + 补齐
+Conan 依赖并暴露给 CMake 探测 + package_info 补组件元数据。
+
+## 涉及软件
+
+任何 qtbase/Qt6 配方因 FEATURE_* 功能开关硬编码 OFF 导致组件库缺失、
+下游 find_package(Qt6 COMPONENTS X) 不可消费的场景（qtbase 6.11.1
+DBus 案例，OHOS aarch64 + Conan 2 制品消费链）。
+
+---
+*条目 E323 · 更新 2026-08-31 · 知识库同步生成物*

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/errors/E324.md

@@ -0,0 +1,58 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E324: 监控型程序在 OHOS 上应把单项指标失败降级为部分数据
+
+> **严重度**: 🟡 medium | **分类**: portability, runtime, system-monitoring | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+collect_cpu_usage.*return -1
+collect_memory.*return -1
+sysinfo.*return -1
+getloadavg.*return -1
+fatal.*metrics
+```
+
+## 根因
+
+这类系统监控程序往往把 CPU、内存、hostname、kernel、
+loadavg、根分区信息视为同一条成功路径；但在 OHOS 上，
+个别 /proc、sysinfo、getloadavg 或磁盘探测可能失败。
+若任一探针直接返回错误，就会把可用的其余指标一起丢掉。
+
+## 验证命令
+
+```bash
+在 OHOS 上运行包内二进制或 test_package，模拟部分探针失败后
+仍能输出其余指标且退出码为 0。
+```
+
+## 解决方案
+
+**best-effort-metric-aggregation**：将每个指标探针拆成独立的失败边界，初始化结果为 0 或空值；
+单项失败只跳过对应字段，不要把局部失败升级成整体 fatal。
+
+```bash
+在聚合函数中把 collect_* 改为 void 或返回局部状态；主路径只在
+真正无法启动时才报错。
+```
+
+## 回退方案
+
+**skip-unavailable-metrics**：如果某个指标在目标平台永远不可用，就在包层面显式标记为未实现
+或以 0 占位，但继续验证可用指标和主命令输出。
+
+## 涉及软件
+
+读取多个系统指标的监控、状态栏、诊断和 CLI 统计工具，
+尤其是把一组探针串成单个 fatal 返回值的实现。
+
+## 相关模式
+
+- **相似模式**：[E031](E031.md)
+
+---
+*条目 E324 · 更新 2026-08-29 · 知识库同步生成物*

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/errors/E325.md

@@ -0,0 +1,55 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E325: Conan test_package 在 OHOS 上应先解析可用 shell 再跑脚本
+
+> **严重度**: 🟡 medium | **分类**: portability, testing, shell, tmpdir | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+sh: bash: inaccessible or not found
+Read-only file system
+mktemp:.*Read-only file system
+```
+
+## 根因
+
+目标机的 OHOS shell 环境可能没有把 bash 放进默认 PATH，
+而 test_package 若直接执行 `bash test.sh` 就会在真正验证前
+失败；同时 `mktemp` 默认落到 `/tmp`，在只读环境里也会失败。
+
+## 验证命令
+
+```bash
+通过 `CONFIG_SHELL`、PATH bash 和 HNP bash 逐级回退后执行
+test.sh，并确认临时文件落在可写目录。
+```
+
+## 解决方案
+
+**shell-discovery-and-writable-tmpdir**：先尊重 `CONFIG_SHELL`，再尝试 PATH 中的 bash，最后回退到
+`/data/service/hnp/bin/bash`；临时文件统一放到 `$HOME/tmp`
+或 `TMPDIR`，不要依赖 `/tmp` 默认值。
+
+```bash
+TMPDIR=$HOME/tmp CONFIG_SHELL=/data/service/hnp/bin/bash /data/service/hnp/bin/bash test.sh
+```
+
+## 回退方案
+
+**plain-sh-and-home-tmp**：如果 bash 仍不可用，就退回到 POSIX `sh`，并把所有临时文件
+约束到可写的 home 目录。
+
+## 涉及软件
+
+所有依赖 shell 脚本的 Conan test_package 包装器，以及需要
+在 OHOS 上复用 bash 的安装后验证流程。
+
+## 相关模式
+
+- **相似模式**：[E002](E002.md)、[E165](E165.md)、[E221](E221.md)
+
+---
+*条目 E325 · 更新 2026-08-29 · 知识库同步生成物*

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/errors/E326.md

@@ -0,0 +1,50 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E326: Shadow CI 只看 git archive HEAD 快照，dirty worktree 不会自动进入验证
+
+> **严重度**: 🟡 medium | **分类**: git, workflow | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+No packages to build
+Path in CI_PACKAGES has no conanfile.py
+shadow.*exit_code=1
+```
+
+## 根因
+
+Shadow CI 运行脚本会先执行 `git archive --format=tar HEAD`，
+再在远端解包成干净源码树。未提交的 worktree 改动不会进入
+这个快照，因此本地看起来已改好的包，远端可能还是旧版本。
+
+## 验证命令
+
+```bash
+在存在未提交改动时对比 `git status --short` 与 `git archive HEAD`
+的内容，确认快照里是否真的包含目标包目录。
+```
+
+## 解决方案
+
+**snapshot-before-shadow-ci**：在跑 shadow CI 前，先把目标包改动提交到临时快照，或者复制成
+一个干净的临时仓库再验证；不要直接指望 dirty worktree 被自动带上。
+
+```bash
+git add 〈外部知识库归档〉 && git commit -m "shadow snapshot for ostra" && sh "$HOME/bin/run-ohos-shadow-ci.sh" 〈外部知识库归档〉
+```
+
+## 回退方案
+
+**clean-temp-repo**：如果不能提交，就把目标包目录复制到一个临时干净仓库，再按
+shadow CI 的入口脚本运行。
+
+## 涉及软件
+
+所有依赖 shadow CI 验证、且在独立 worktree 中准备包改动的
+HarmonyOS Conan 适配流程。
+
+---
+*条目 E326 · 更新 2026-08-29 · 知识库同步生成物*

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/errors/E327.md

@@ -0,0 +1,57 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E327: ostra 上游测试统计应按“测试相关文件 + 包内可执行入口”分层记录
+
+> **严重度**: 🟡 medium | **分类**: testing, evidence-boundary | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+upstream.*1/1
+test-related files.*23
+review.*underreported
+〈外部知识库路径〉
+```
+
+## 根因
+
+该仓库是 monorepo，control-plane、web/dashboard、infra 脚本和
+components/ostra-sysctl 处于不同运行边界；如果只把
+components/ostra-sysctl/tests/smoke-test.sh 写成上游总数，就会把
+其余 22 个测试相关文件漏掉，导致审查认为证据不足。
+
+## 验证命令
+
+```bash
+先盘点上游测试相关文件总数，再单列本 Conan 包实际可执行入口，
+最后把未执行项按 FastAPI / DB / web / infra / runtime 边界说明清楚。
+```
+
+## 解决方案
+
+**layered-test-evidence**：报告时区分三层口径：上游测试相关文件总数、包内实际执行的上游
+子集、HarmonyOS test_package；不要把 monorepo 其他目录的测试直接
+算进当前 Conan 包的通过率。
+
+```bash
+先统计 upstream test-related 文件，再执行 components/ostra-sysctl/tests/smoke-test.sh
+与 test_package，并在 PR 正文里写出包外 22 项的边界原因。
+```
+
+## 回退方案
+
+**explain-out-of-scope-tests**：如果无法运行全部上游测试，就把未运行项按目录和依赖原因写清楚，并保留可执行子集的真实通过率。
+
+## 涉及软件
+
+所有按子目录拆包的 monorepo Conan 适配，尤其是只暴露某个
+component 的包，但上游仓库还包含控制面、前端和基础设施测试。
+
+## 相关模式
+
+- **相似模式**：[E255](E255.md)、[E256](E256.md)
+
+---
+*条目 E327 · 更新 2026-08-30 · 知识库同步生成物*

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/errors/E328.md

@@ -0,0 +1,61 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E328: monorepo 包的 PR 说明应把包内 smoke-test 与 repo 级测试簇分开列出
+
+> **严重度**: 🟡 medium | **分类**: testing, evidence-boundary, review | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+underreported.*upstream.*tests
+test-related files.*23
+PR.*smoke-test
+review.*scope
+```
+
+## 根因
+
+单包 Conan 适配只拥有自己的可执行入口，但上游 monorepo 还包含控制面、
+前端和基础设施测试簇。若 PR 只写“执行了一个 smoke-test”，审查会把
+其余测试簇视为少报；若把仓库级脚本硬并入包内通过率，又会误导后续
+维护者。
+
+## 验证命令
+
+```bash
+先列出上游测试相关文件总数，再把包内可执行入口、repo 级测试簇和 helper
+文件分开写进 PR 正文，并逐条说明未执行原因。
+```
+
+## 解决方案
+
+**separated-test-clusters**：PR 正文里保留完整上游分母，再单列包内实际执行的 smoke-test 与新增的
+test_package；对 control-plane/tests、tests、web/dashboard/tests、
+infrastructure scripts 逐条说明依赖边界，避免把 monorepo 其他测试误算成
+当前 Conan 包通过率。
+
+```bash
+在 notes.md 和 PR body 中分别列出 23 个上游 test-related 文件、1 个包内
+smoke-test、1 个 test_package，并对未运行项写明 FastAPI / DB / Qt /
+Node / infra 边界。
+```
+
+## 回退方案
+
+**explain-unrun-clusters**：如果无法运行更多上游测试，就把未运行测试簇按目录和依赖原因写清楚，
+并明确声明它们不属于当前 Conan 包的执行面。
+
+## 涉及软件
+
+所有从 monorepo 中截取单个 component 的适配，尤其是 upstream tests
+分布在 control-plane、web/dashboard、infrastructure 和 runtime
+helper 目录中的项目。
+
+## 相关模式
+
+- **相似模式**：[E257](E257.md)
+
+---
+*条目 E328 · 更新 2026-08-30 · 知识库同步生成物*

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/errors/E329.md

@@ -0,0 +1,58 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E329: control-plane 纯逻辑测试的 ServiceAction 定义顺序问题可用 recipe patch 修复
+
+> **严重度**: 🟡 medium | **分类**: testing, import-order, review | **自动修复**: ✅ manual
+
+---
+
+## 错误特征
+
+```
+NameError: name 'ServiceAction' is not defined
+test_models.py
+models.py
+```
+
+## 根因
+
+`src/ostra_control_plane/models.py` 在定义 `ServiceStatus.allowed_actions`
+时引用了 `ServiceAction`，但 `ServiceAction = Literal[...]` 放在
+`ServiceStatus` 之后。Python 3.12 导入模块时会立刻求值类型注解，
+因而 `pytest tests/test_models.py` 在收集阶段直接报 `NameError`。
+
+## 验证命令
+
+```bash
+在 `services/control-plane` 目录下设置 `PYTHONPATH=src`，执行
+`python -m pytest tests/test_models.py tests/test_config.py -q`；
+修复后 5 个纯逻辑用例全部通过。
+```
+
+## 解决方案
+
+**reorder-service-action**：将 `ServiceAction = Literal[...]` 提前到 `ServiceStatus` 之前，或把
+`allowed_actions` 的注解改为字符串前向引用，再重跑 `test_models.py`
+与 `test_config.py`。
+
+```bash
+先修正 `models.py` 定义顺序，再执行 `PYTHONPATH=src python -m pytest
+tests/test_models.py tests/test_config.py -q` 复核纯逻辑子集。
+```
+
+## 回退方案
+
+**forward-reference-annotation**：若不希望移动声明块，可把 `allowed_actions` 改为字符串前向引用；仍需
+重跑 `test_models.py` 与 `test_config.py` 确认导入与模型约束行为。
+
+## 涉及软件
+
+任何需要导入 `ostra_control_plane.models` 的纯逻辑测试、Pydantic 模型
+自检和控制面轻量验证。
+
+## 相关模式
+
+- **相似模式**：[E257](E257.md)、[E258](E258.md)
+
+---
+*条目 E329 · 更新 2026-08-30 · 知识库同步生成物*

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/errors/E330.md

@@ -0,0 +1,62 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E330: Disable CMake versioned shared-library symlinks on OHOS paths
+
+> **严重度**: 🟡 medium | **分类**: ohos, cmake, linking, filesystem, shared-library | **自动修复**: ❌ | **原则**: [P010](../principles.md#P010)、[P012](../principles.md#P012)
+
+---
+
+## 错误特征
+
+```
+failed to create symbolic link .*\.so\.[0-9]+
+cmake_symlink_library: System Error: Permission denied
+DT_NEEDED.*\.conan2
+```
+
+## 根因
+
+CMake's Unix shared-library rules can create versioned .so names and symlinks. OHOS/HMDFS-backed build paths can reject symlink creation even when the compiled shared object is valid. Disabling SONAME entirely avoids symlink creation but can make downstream DT_NEEDED entries record an absolute Conan cache path.
+
+## 验证命令
+
+```bash
+Run clean conan create on HarmonyOS PC CI or target runner; require build/install to pass, llvm-readelf -d to show Library soname: [libexpat.so], and Conan test_package to dlopen and call real APIs.
+```
+
+## 解决方案
+
+**no-versioned-soname-keep-soname-flag**：Set CMAKE_PLATFORM_NO_VERSIONED_SONAME=ON while keeping CMAKE_SHARED_LIBRARY_SONAME_C_FLAG=-Wl,-soname, so CMake emits an unversioned real .so with a relocatable ELF SONAME and does not create versioned symlinks.
+
+```bash
+-DCMAKE_PLATFORM_NO_VERSIONED_SONAME=ON -DCMAKE_SHARED_LIBRARY_SONAME_C_FLAG=-Wl,-soname,
+```
+
+## 回退方案
+
+**package-unversioned-shared-library-with-explicit-runtime-validation**：If the project cannot use CMAKE_PLATFORM_NO_VERSIONED_SONAME, package an unversioned shared object through the upstream-supported install path and explicitly verify DT_NEEDED/SONAME and runtime loading on target.
+
+```bash
+llvm-readelf -d libfoo.so
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`CMAKE_SKIP_RPATH|CMAKE_NO_SONAME|NO_SONAME`
+- **原因**：Removing SONAME emission can make downstream DT_NEEDED entries capture a non-relocatable package-cache path.
+- **后果**：Consumers can work only while the exact Conan cache path exists and fail after cache cleanup, revision changes, or machine changes.
+
+### 🚫 禁止 2
+
+- **模式**：`rm .*lib.*\.so\.[0-9]+|unlink .*\.so\.[0-9]+`
+- **原因**：Deleting symlinks in package() cannot fix a build that already fails during CMake's build-time symlink creation.
+- **后果**：The recipe remains flaky or fails before package cleanup runs.
+
+## 涉及软件
+
+CMake packages that produce versioned shared libraries on HarmonyOS PC or OHOS/HMDFS paths, especially libraries consumed by downstream shared objects.
+
+---
+*条目 E330 · 更新 2026-08-11 · 知识库同步生成物*

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/errors/E331.md

@@ -0,0 +1,66 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E331: OHOS HMDFS 构建 CMake 版本化共享库时需避免符号链接链
+
+> **严重度**: 🔴 blocking | **分类**: hmdfs, cmake, linking, shared-library | **自动修复**: ❌ | **原则**: [P003](../principles.md#P003)、[P005](../principles.md#P005)
+
+---
+
+## 错误特征
+
+```
+Error creating symbolic link.*libopenjp2\.so
+Operation not permitted.*libopenjp2\.so
+cmake_symlink_library.*failed
+```
+
+## 根因
+
+CMake 为带 VERSION/SOVERSION 的共享库生成真实版本文件和未版本化符号链接；OHOS 真机的 HMDFS 工作目录拒绝创建这些符号链接，导致库已链接完成但构建在 cmake_symlink_library 阶段失败。
+
+## 验证命令
+
+```bash
+conan create 〈外部知识库归档〉; verify package/lib/libopenjp2.so is a regular file; run test_package and upstream BUILD_UNIT_TESTS programs
+```
+
+## 解决方案
+
+**ohos-only-unversioned-shared-library**：给上游 CMake 增加默认关闭的选项，仅在 OHOS 配方中跳过 VERSION/SOVERSION target properties，直接生成未版本化共享库；其他平台保持上游 SONAME 和符号链接布局。
+
+```bash
+cmake -DOPENJPEG_NO_VERSIONED_SONAME=ON ...
+```
+
+## 回退方案
+
+**build-on-symlink-capable-filesystem**：若 ABI 必须保留版本化 SONAME，则将构建目录迁移到支持符号链接的目标机文件系统，再把最终普通文件复制进包目录并核验 NEEDED/SONAME。
+
+```bash
+readelf -d libopenjp2.so | grep -E 'SONAME|NEEDED'
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`ln -s.*ignore|cmake.*Operation not permitted.*ignore|skip.*cmake_symlink_library`
+- **原因**：忽略符号链接失败会留下缺少消费者链接名或损坏的安装布局，构建成功状态不可信。
+- **后果**：Conan package 可能缺少 libopenjp2.so，导致下游链接失败。
+
+### 🚫 禁止 2
+
+- **模式**：`remove.*VERSION.*all platforms|patch.*SOVERSION.*unconditional`
+- **原因**：无条件移除 VERSION/SOVERSION 会改变 Linux 等支持符号链接平台的 ABI 和安装布局。
+- **后果**：非 OHOS 消费者可能失去预期 SONAME 或版本化兼容链接。
+
+## 涉及软件
+
+在 OHOS HMDFS 目录原生构建使用 CMake VERSION/SOVERSION 属性的共享库，尤其是只需要 Conan 包内未版本化链接名的核心库配方。
+
+## 相关模式
+
+- **相似模式**：[E087](E087.md)、[E129](E129.md)
+
+---
+*条目 E331 · 更新 2026-08-12 · 知识库同步生成物*

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/errors/E332.md

@@ -0,0 +1,58 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E332: Prefer an upstream native standalone runner before disabling or vendoring a test framework
+
+> **严重度**: 🟡 medium | **分类**: network, build-system, cmake, conan, testing | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+BUILD_TESTING.*googletest
+GoogleTest.*download
+gtest_discover_tests
+```
+
+## 根因
+
+Some upstream projects provide a GTest-compatible native runner but leave it disabled by default, so a normal test configuration tries to bootstrap or link GoogleTest unnecessarily.
+
+## 验证命令
+
+```bash
+cmake -DBUILD_TESTING=ON -DHWY_ENABLE_TESTS=ON -DHWY_ENABLE_CONTRIB=ON -DHWY_TEST_STANDALONE=ON <source>; ctest --output-on-failure --no-tests=error
+```
+
+## 解决方案
+
+**enable-native-standalone-test-runner**：Enable the maintained upstream standalone runner together with its test and CTest switches. Run it only on a runnable target and report its result independently from the consumer test.
+
+```bash
+CMakeToolchain(self).variables['HWY_TEST_STANDALONE'] = 'ON'; CMake(self).test(cli_args=['--output-on-failure', '--no-tests=error'])
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`HWY_TEST_STANDALONE=ON.*(passed|100%)`
+- **原因**：Enabling a runner is configuration evidence, not execution evidence.
+- **后果**：The PR can falsely claim target-side coverage.
+
+### 🚫 禁止 2
+
+- **模式**：`BUILD_TESTING=OFF.*(complete|full).*test`
+- **原因**：Disabling an upstream suite cannot demonstrate its execution.
+- **后果**：The package loses upstream validation while overstating coverage.
+
+## 涉及软件
+
+CMake packages whose upstream runner implements the test-discovery command-line contract used by gtest_discover_tests.
+
+## 相关模式
+
+- **相似模式**：[E017](E017.md)、[E217](E217.md)、[E221](E221.md)、[E224](E224.md)
+
+---
+*条目 E332 · 更新 2026-08-14 · 知识库同步生成物*

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/errors/E333.md

@@ -0,0 +1,63 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E333: 〈外部知识库流水线〉 的 pre-download 脚本用正则 [^\s"'-]+ 提取
+
+> **严重度**: 🟡 medium | **分类**: python, ci-script, package, url-truncation | **自动修复**: ✅ manual
+
+---
+
+## 错误特征
+
+```
+FileNotFoundError: \[Errno 2\] No such file or directory: '.*predl_cache.*\.tar\.gz'
+conan create failed
+NoSuchKey
+```
+
+## 根因
+
+〈外部知识库流水线〉 的 pre-download 脚本用正则 [^\s"'-]+ 提取 conandata.yml 源码 URL，
+该字符类排除连字符 '-'，导致 PyPI 文件名含连字符的 sdist URL（aiven_client-4.16.0.tar.gz）被截断为
+.../aiven_client。若截断 URL 返回 >100 字节 body（PyPI 哈希目录 URL 返回 359 字节 NoSuchKey XML），
+CI 误判"下载成功"并改写 conandata.yml 为 file://.../predl_cache/{hash}_{截断名}-版本.tar.gz
+（指向不存在的文件）→ conan create FileNotFoundError。若截断 URL 返回 0 字节
+（/packages/source/ 形式 URL），CI 判定失败、不改写 conandata.yml，conan 用官方 URL 直接下载成功。
+
+## 验证命令
+
+```bash
+curl -sL -o /dev/null -w '%{http_code}:%{size_download}' '<截断后的URL>'；对比返回值：
+/packages/db/29/.../aiven_client → http:404 size:359（误判成功）
+/packages/source/a/aiven-client/aiven_client → http:404 size:0（判定失败，走官方下载）
+```
+
+## 解决方案
+
+**url_form（conandata.yml 改用 /packages/source/ 官方 URL，sha256 与哈希目录 sdist 完全一致）**：将 conandata.yml 源码 URL 改用 PyPI 官方 /packages/source/ 形式 URL，规避 CI pre-download 正则对连字符文件名的截断误判
+
+```bash
+https://files.pythonhosted.org/packages/source/{letter}/{name}/{name}-{version}.tar.gz
+```
+
+## 回退方案
+
+**predl_cache 预置（手工复制正确 sdist 到 .build-cache/predl_cache/{url_hash}_{filename} 使 CI [cached] 命中）**
+
+```bash
+cp <correct-sdist> .build-cache/predl_cache/<url_hash>_<filename>
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`packages/[a-f0-9]{2}/[a-f0-9]{2}/.*-[0-9.]+\.tar\.gz`
+- **原因**：PyPI 哈希目录 URL 的截断 URL 返回 359 字节 NoSuchKey body（>100 阈值）→ CI 误判下载成功并改写 conandata.yml 为错误 file:// 路径
+- **后果**：finish W3 阻塞门禁失败（conan create FileNotFoundError），无法提交 PR
+
+## 涉及软件
+
+所有使用 PyPI sdist 且文件名含连字符的纯 Python 包（files.pythonhosted.org 哈希目录 URL 形式）
+
+---
+*条目 E333 · 更新 2026-08-31 · 知识库同步生成物*