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

@@ -0,0 +1,85 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E473: Inject missing WebP::webpdemux imported target when libwebp CMakeDeps only exposes WebP::webp and upstream links both under OHOS cross-compile
+
+> **严重度**: 🔴 blocking | **分类**: cmake, cross-compile, conan, libwebp, sdl2 | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Target "SDL2_image" links to:.*WebP::webpdemux
+but the target was not found
+webp/decode.h not found
+Findwebp.*module
+```
+
+## 根因
+
+libwebp 配方 package_info() 仅暴露 WebP::webp（cmake_target_name=WebP::webp），但上游 SDL2_image 2.8.12 在 SDL2IMAGE_WEBP 启用、SDL2IMAGE_DEPS_SHARED=OFF 时 `target_link_libraries(SDL2_image PRIVATE WebP::webp WebP::webpdemux)` 同时链接两个 target；libwebpdemux.so 实际随 libwebp 包分发（lib/libwebpdemux.so.2.0.17），却未作为组件/独立 target 暴露。Conan 2 的 CMakeToolchain 默认 set(CMAKE_FIND_PACKAGE_PREFER_CONFIG ON)，使 find_package(webp) 命中 CMakeDeps 生成的 WebPConfig.cmake（仅定义 WebP::webp），而非上游 cmake/Findwebp.cmake 模块（该模块本会同时定义 WebP::webp 与 WebP::webpdemux 两个 IMPORTED target）→ 配置期报 Target "SDL2_image" links to: WebP::webpdemux but the target was not found。另：Findwebp.cmake 的 find_path(webp_INCLUDE_PATH NAMES webp/decode.h) 需要 include 根（含 webp/ 子目录），错误指到 include/webp 会报 webp/decode.h not found。
+
+## 验证命令
+
+```bash
+grep -nE 'WebP::webpdemux|webp_INCLUDE_PATH|cmake_build_modules' conanfile.py; grep -nE 'Target "SDL2_image" links to: WebP::webpdemux' reports/conan-create.log
+```
+
+## 解决方案
+
+**conan-recipe build-module imported-target injection (cmake_build_modules)**：在 conanfile.py generate() 中为 libwebp 依赖注入一个 build module（cmake_build_modules），其中定义缺失的 WebP::webpdemux UNKNOWN IMPORTED target，IMPORTED_LOCATION 指向 libwebp 包内 lib/libwebpdemux.so；同时把 webp_INCLUDE_PATH / webpdemux_INCLUDE_PATH 缓存变量指向 libwebp include 根（含 webp/ 子目录）。这样 find_package(webp) 命中 CMakeDeps WebPConfig 时 WebP::webpdemux 已存在，无需改 libwebp 配方或改上游源码。
+
+```bash
+def generate(self):
+    deps = CMakeDeps(self)
+    webp = self.dependencies["libwebp"]
+    if webp.package_folder:
+        module = os.path.join(self.generators_folder, "WebP-webpdemux.cmake")
+        with open(module, "w", encoding="utf-8") as fh:
+            fh.write("if(NOT TARGET WebP::webpdemux)\n")
+            fh.write("  add_library(WebP::webpdemux UNKNOWN IMPORTED)\n")
+            fh.write("  set_target_properties(WebP::webpdemux PROPERTIES\n")
+            fh.write("      IMPORTED_LOCATION \"%s\")\n" % os.path.join(webp.package_folder, "lib", "libwebpdemux.so"))
+            fh.write("endif()\n")
+        deps.set_property("libwebp", "cmake_build_modules", [module])
+    deps.generate()
+    tc = CMakeToolchain(self)
+    tc.cache_variables["webp_INCLUDE_PATH"] = os.path.join(webp.package_folder, "include")
+    tc.cache_variables["webpdemux_INCLUDE_PATH"] = os.path.join(webp.package_folder, "include")
+    tc.generate()
+```
+
+## 回退方案
+
+**disable WEBP backend**：若 libwebp 包/配方无法暴露 webpdemux 且无法注入 target，可将 SDL2IMAGE_WEBP=OFF 并同步 SDL_IMAGE_TEST_REQUIRE_LOAD_WEBP=0，放弃 WEBP 格式支持（功能裁剪，非首选）。
+
+```bash
+tc.variables["SDL2IMAGE_WEBP"] = "OFF"  # 且测试断言 REQUIRE_LOAD_WEBP=0
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`SDL2IMAGE_WEBP.*OFF.*掩盖缺失`
+- **原因**：若只是为过编译而关闭 WEBP，会丢掉本可用的格式支持，且无法说明 libwebpdemux 已随包存在。
+- **后果**：功能缺失，非根因修复。
+
+### 🚫 禁止 2
+
+- **模式**：`把 webp_INCLUDE_PATH 指向 include/webp`
+- **原因**：Findwebp.cmake 的 find_path 需含 webp/ 子目录的根，指到 include/webp 时 NAMES webp/decode.h 找不到。
+- **后果**：webp/decode.h not found（配置期失败）。
+
+### 🚫 禁止 3
+
+- **模式**：`修改已发布 libwebp 配方或动其他库归档来补 target`
+- **原因**：依赖已发布不可改；本方案在消费者侧注入，不改依赖/不动其他库。
+- **后果**：破坏依赖链或跨库污染。
+
+## 涉及软件
+
+消费 libwebp 且上游直接链接 WebP::webp 与 WebP::webpdemux 的 CMake 项目（SDL2_image 2.6.0+/2.8.x、SDL_image 系），在 OHOS/aarch64 交叉编译 + Conan 2 CMakeDeps（PREFER_CONFIG=ON）下构建的场景；libwebp 配方未暴露 webpdemux 组件时通用。
+
+---
+*条目 E473 · 更新 2026-08-29 · 知识库同步生成物*

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

@@ -0,0 +1,60 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E474: Separate auxiliary observers from the native consumer terminal contract
+
+> **严重度**: 🟡 medium | **分类**: consumer-observer-separation | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+native consumer stages are present but an auxiliary snapshot or management acknowledgement is missing; a loose validator changes the four-consumer result
+```
+
+## 根因
+
+A surface snapshot and a management acknowledgement are observation or transaction-control contracts, while core, invalid-input, audio, and video are product consumers. Treating an observer as a fifth consumer, or accepting locally printed stage fields without an authoritative terminal receipt, makes a missing observer look like a consumer failure or a consumer success.
+
+## 验证命令
+
+```bash
+Run the host contract with four ordered consumer stages; require an explicit snapshot policy; inspect the authoritative terminal schema and reject a count derived from an observer timeout; retain upstream and target denominators separately.
+```
+
+## 解决方案
+
+**typed-consumer-and-observer-receipts**：Define the exact consumer set and denominator first. Emit each stage only after the production native operation, record optional observers as NOT_REQUIRED or NOT_RUN, and accept consumers_passed/consumers_total only from a terminal receipt bound to the same run identity and input snapshot.
+
+```bash
+validate source contract; compile and run a host fixture; verify ordered core_pass invalid_pass audio_pass video_pass markers; assert snapshot=NOT_REQUIRED or a separate required receipt; preserve upstream=0/0 NOT_RUN for a consumer-only run
+```
+
+## 回退方案
+
+**fail-closed-reconciliation**：If observer policy or terminal authority is unavailable, leave the run nonterminal and keep the consumer count unproven; do not promote local output or historical upstream evidence.
+
+```bash
+read only the existing receipts and classify NOT_RUN or FAIL; create a new run identity for any code repair
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`snapshot.*fifth.*consumer|observer.*timeout.*consumers_passed|version.*smoke.*native.backend`
+- **原因**：A screenshot or control-channel event does not exercise the native video or audio path and cannot alter the declared consumer denominator.
+- **后果**：False failures, false passes, and an unreviewable test denominator.
+
+### 🚫 禁止 2
+
+- **模式**：`local.*stage.*fields.*terminal.*PASS|history.*upstream.*consumer-only`
+- **原因**：Stage text without a bound terminal receipt and historical upstream runs belong to different evidence scopes.
+- **后果**：An incomplete target transaction can be reported as a completed current run.
+
+## 涉及软件
+
+API-level UI test hosts, multimedia or graphics adapters, and any target runner that combines native capability checks with an optional screenshot or external management channel.
+
+---
+*条目 E474 · 更新 2026-08-28 · 知识库同步生成物*

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

@@ -0,0 +1,60 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E475: Reinitialize Conan source trees before ordered patch replay
+
+> **严重度**: 🟡 medium | **分类**: conan, source-cache-replay | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+a later conan create re-applies a patch to a source cache left in a postimage state and reports hunk mismatch
+```
+
+## 根因
+
+Conan retries can invoke source() against the same recipe cache directory after an earlier run applied patches and failed later; reapplying the ordered patch set then sees postimage bytes instead of the official preimage. Strict patch_ng also requires exact hunk offsets and explicit blank-line records.
+
+## 验证命令
+
+```bash
+replay the corrected patch with patch_ng 1.19.1 strip=0 fuzz=False on a clean official source; compare the postimage SHA; run GNU patch --dry-run --forward and the outer git diff check; verify a second call cannot change the postimage hash
+```
+
+## 解决方案
+
+**fresh-source-and-exact-hunks**：Bind every patch to the exact official preimage, use standard blank-line context, and use a new recipe revision or explicit source reset so a retry cannot treat a previous postimage as its preimage; do not rely on patch_ng.apply()'s boolean to detect replay.
+
+```bash
+patch_ng.fromfile(patch).apply(strip=0, root=clean_source_root, fuzz=False); compare postimage SHA256; invoke a second call and assert the postimage hash is unchanged; patch --dry-run --forward -p1; git diff --check
+```
+
+## 回退方案
+
+**fail-closed-cache-rebuild**：If source provenance or preimage bytes are uncertain, preserve the failed cache and rebuild from a new source root; do not reverse or reuse a partially patched tree.
+
+```bash
+retain failed Conan home; create a new recipe revision or isolated source root; replay all patches in declared order
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`retry.*same.*patched.*source|ignore.*hunk.*mismatch|fuzz.*true.*as.*proof`
+- **原因**：A retry against a postimage can silently skip or misapply an ordered patch and does not prove the official source was transformed correctly.
+- **后果**：Non-reproducible CI results and binaries built from an unproven source state.
+
+### 🚫 禁止 2
+
+- **模式**：`blank.*context.*space|remove.*patch.*because.*cache`
+- **原因**：A marker-less or whitespace-tainted blank record changes patch grammar or fails the repository whitespace gate.
+- **后果**：Local replay may pass while Conan patch_ng rejects the patch or CI cannot reproduce it.
+
+## 涉及软件
+
+Conan recipes that apply ordered patch sets in a reusable source cache, especially when CI retries share a Conan home
+
+---
+*条目 E475 · 更新 2026-08-29 · 知识库同步生成物*

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

@@ -0,0 +1,62 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E476: OHOS 小对象默认分配未满足 foonathan/memory 的最大对齐契约
+
+> **严重度**: 🟡 medium | **分类**: platform, portability, libc, musl, memory | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+REQUIRE\(detail::is_aligned.*\)
+heap_allocator.*is_aligned
+malloc_allocator.*is_aligned
+new_allocator.*is_aligned
+alignment.*16
+```
+
+## 根因
+
+OpenHarmony 的 musl 系运行时对小尺寸 malloc 和 operator new 返回的地址可能只有 8 字节对齐，而 foonathan/memory 的默认、malloc 和 new 分配器在 hosted 实现中要求 detail::max_alignment（本机为 16 字节）；size 为 0 时还必须按至少 1 字节请求对齐分配。
+
+## 验证命令
+
+```bash
+cmake -S . -B build -DCMAKE_SYSTEM_NAME=HarmonyOS -DFOONATHAN_MEMORY_BUILD_TESTS=ON -DFOONATHAN_MEMORY_BUILD_TOOLS=ON && cmake --build build --parallel 1 && ctest --test-dir build --output-on-failure
+```
+
+## 解决方案
+
+**source-code-patch**：在 POSIX hosted 路径（标准 __unix__ 守卫）以 posix_memalign(detail::max_alignment, size ? size : 1) 分配，并以 std::free 释放；Windows 路径保留原有行为。
+
+```bash
+grep -R -n -E 'malloc\(|operator new|is_aligned' include src test && ctest --test-dir build --output-on-failure
+```
+
+## 回退方案
+
+**runtime-probe**：先用最小程序测量目标运行时不同分配 API 的实际地址对齐；若平台实现已满足契约，再区分测试配置或其他分配路径。
+
+```bash
+./build/test/foonathan_memory_test "[default_allocator]"
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`skip.*alignment|disable.*aligned|reinterpret_cast.*align|malloc\(.*\).*assume.*alignment`
+- **原因**：跳过对齐测试或仅靠指针转换不能修复分配器返回地址的 ABI 契约，可能让容器在真实 OHOS 运行时产生未对齐访问。
+- **后果**：上游测试被掩盖，过对齐类型和默认分配器仍可能在设备上崩溃或触发未定义行为。
+
+## 涉及软件
+
+在 OHOS、HarmonyOS 或 OpenHarmony 上使用 hosted foonathan/memory 默认分配器、malloc_allocator 或 new_allocator 的 C/C++ 构建与运行测试。
+
+## 相关模式
+
+- **相似模式**：[E267](E267.md)、[E140](E140.md)
+
+---
+*条目 E476 · 更新 2026-08-29 · 知识库同步生成物*

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

@@ -0,0 +1,73 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E477: CNB Conan 制品仓对不存在/未发布包返回 "system acceleration policy not enabled"，CI L0i 误判为网络异常而非依赖未发布 (R36)
+
+> **严重度**: 🟡 medium | **分类**: detection, network, conan | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+system acceleration policy not enabled
+registry unreachable for:
+registry_unreachable
+Connecting to remote 'ohpcd' anonymously ERROR
+conan could not reach/query the remote
+```
+
+## 根因
+
+CNB (cnb.cool) Conan 制品仓对"匿名下载不存在/未发布的 recipe"返回的错误文本是 "ERROR: error:system acceleration policy not enabled"，而不是标准 "not found/404"。
+〈外部知识库流水线〉 的 L0i 门禁用 conan download -r=ohpcd --only-recipe 探测依赖，
+仅把 "unable to find|does not exist|not found|404" 识别为"真未发布 (R36)"，
+该 CNB 特有文本落入"网络/认证异常 (registry_unreachable)"分支，导致诊断误导
+（提示"修复 worker 网络"，实际是依赖尚未发布）。
+
+## 验证命令
+
+```bash
+conan list "<dep>/<ver>" -r=ohpcd; conan download "<dep>/<ver>" -r=ohpcd --only-recipe; conan download "nonexistent-xyz/9.9.9" -r=ohpcd --only-recipe  # 后者复现同一错误文本
+```
+
+## 解决方案
+
+**verify-registry-with-conan-list**：用 conan list -r=ohpcd 核实依赖是否已发布；若未发布先合入/发布该依赖 (R36)，再 /rebuild 触发 PR CI；不要误判为网络故障
+
+```bash
+conan list "<dep>/<ver>" -r=ohpcd && conan download "<dep>/<ver>" -r=ohpcd --only-recipe
+```
+
+## 回退方案
+
+**retry-rebuild-after-publish**：若确认依赖已发布仍失败（瞬时网络抖动），在 PR 评论 /rebuild 重试；L0i 对瞬时错误已内置 3 次重试
+
+```bash
+python3 scripts/gitcode_pr.py trigger-ci --repo OpenHarmonyPCDeveloper/〈外部知识库仓〉 --number <PR_NUMBER>
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`看到 registry_unreachable 就把 L0i 失败当基础设施故障，不核实依赖是否已发布`
+- **原因**：CNB 对未发布包返回的是同一错误文本，跳过核实会掩盖 R36 依赖未发布问题
+- **后果**：反复 /rebuild 无法通过；或误判为 worker 网络问题，延误修复
+
+### 🚫 禁止 2
+
+- **模式**：`在依赖未发布时直接把依赖 recipes 手工塞入 conandata/本地缓存以绕过 L0i`
+- **原因**：L0i 探测的是远端制品仓，本地缓存绕过属于欺骗性修复
+- **后果**：PR 合入后依赖在干净 worker 上仍无法解析，CI 挂掉
+
+## 涉及软件
+
+所有依赖链中引用尚未发布到 ohpcd 制品仓的 conan 包的三方库 PR；
+表现为 PR CI 在 L0i 门禁失败且诊断类别为"未知/网络异常"
+
+## 相关模式
+
+- **相似模式**：[E017](E017.md)
+
+---
+*条目 E477 · 更新 2026-08-27 · 知识库同步生成物*

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

@@ -0,0 +1,44 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E478: conan-verify 无法解析点号版本号的 package ID（G4/L2/L4/L5 跳过）
+
+> **严重度**: 🟡 medium | **分类**: conan | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+conan-verify.*无法找到程序包 ID
+Package ID not found.*dotted version
+G4.*package ID
+```
+
+## 根因
+
+conan_verify.py G2 用正则 (\w+/\w+@\w+/\w+):(\w+) 从 conan create 日志提取 package ID，\w+ 不匹配含点号的版本号（如 20160310.da66f51），导致 _package_id 为空，G4/L2/L4/L5 因拿不到 cache 路径而跳过
+
+## 验证命令
+
+```bash
+conan cache path asplib/20160310.da66f51@ohpcd/stable:4b977264131a1c74e82bd6bb51b63cc9aadc4cfa
+```
+
+## 解决方案
+
+**版本号含点号时 G4/L2/L4/L5 会被跳过但标记 PASS；需手动用 conan cache path '<ref>:<pkgid>' + readelf/sha256 验证产物完整性（或用 conan list 获取 package id）**：版本号含点号（或连字符）时 conan-verify 的 package ID 正则不匹配，G4/L2/L4/L5 被跳过但标记 PASS；需手动验证产物完整性
+
+```bash
+conan cache path asplib/20160310.da66f51@ohpcd/stable:4b977264131a1c74e82bd6bb51b63cc9aadc4cfa
+```
+
+## 回退方案
+
+**用 conan list '<ref>:*' 输出解析 package id 后手动执行 L4/L5**
+
+## 涉及软件
+
+所有带点号/连字符版本号的三方库配方验证
+
+---
+*条目 E478 · 更新 2026-08-27 · 知识库同步生成物*

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

@@ -0,0 +1,76 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E480: X11 客户端库的头文件级依赖在同轨可用时直接用 transitive_headers 消费，不必写桩 .pc 或 vendor 头
+
+> **严重度**: 🔴 blocking | **分类**: ohos, autotools, conan, pkg-config, transitive-headers | **自动修复**: ❌ | **原则**: [P013](../principles.md#P013)、[P014](../principles.md#P014)
+
+---
+
+## 错误特征
+
+```
+Package '.*', required by 'virtual:world', not found
+Xfixes.h: No such file or directory
+header dependency.*transitive_headers
+```
+
+## 根因
+
+X11 扩展客户端库的依赖可二分：链接依赖（NEEDED 含对应 .so）与
+头文件级依赖（仅编译期 include 消费类型/宏）。Xcomposite.h 第 49 行
+include <X11/extensions/Xfixes.h>，但 libXcomposite.so.1 只链接
+-lX11，NEEDED 无 libXfixes.so。configure 的 PKG_CHECK_MODULES(XFIXES, xfixes)
+只为拿 -I 头文件路径。当 libxfixes/6.1.0 已在 cmd-pkgs 同轨发布
+（pkg_config_name=xfixes、含 xfixes.pc）且与 libx11/6.4.0 兼容时，
+仅需 requires("libxfixes/6.1.0", transitive_headers=True)，由 Conan
+透传 include 目录，无需求桩或 vendor。跨轨（libxfixes/6.0.2 pin 在
+Track A/libx11/1.8.13）时才会同图双 libx11 版本冲突，才需 E338 方案。
+
+## 验证命令
+
+```bash
+conan create . -pr:h=ohos-aarch64 -pr:b=ohos-aarch64 2>&1 | grep -E "checking for|not found|error"
+```
+
+## 解决方案
+
+**same-track-transitive-headers**：头文件级依赖在同轨可用时，requirements 写 transitive_headers=True，
+generate() 设 {DEP}_CFLAGS 供 configure 找头、{DEP}_LIBS="" 不加链接 flag；
+package_info.requires 只列链接级依赖；不写桩 .pc、不 vendor 头、不打 patch。
+
+```bash
+CI_PACKAGES="〈外部知识库归档〉" zsh 〈外部知识库流水线〉
+```
+
+## 回退方案
+
+**cross-track-stub-vendor**：头文件级依赖被 pin 在另一轨道且拉入会形成同图双版本冲突时，才用 E338：
+构建期写桩 .pc + vendor 头，不进入安装产物。
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`write.*xfixes\.pc.*libxcomposite|vendor.*Xfixes\.h.*libxcomposite`
+- **原因**：同轨可用时桩 .pc + vendor 头是过度工程，制造维护负担与头文件符号分叉风险。
+- **后果**：版本升级时 vendor 头过期，消费者可能拿到与库版本不符的声明。
+
+### 🚫 禁止 2
+
+- **模式**：`package_info\.requires.*libxfixes.*xcomposite`
+- **原因**：头文件级依赖不应出现在链接级 requires，否则消费者会误链接 libXfixes。
+- **后果**：消费者产物 NEEDED 引入本不需要的 libXfixes.so，启动依赖膨胀。
+
+## 涉及软件
+
+X11 家族扩展客户端库（Xcomposite/Xdamage/Xinerama/Xrandr/Xcursor）在
+cmd-pkgs Track B 上的 OHOS 适配；以及一切 PKG_CHECK_MODULES 只消费
+头文件的同类库。libXcomposite 0.4.6 实证：Xcomposite.h include Xfixes.h，
+configure PKG_CHECK_MODULES(XCOMPOSITE,...) + (XFIXES, xfixes)。
+
+## 相关模式
+
+- **相似模式**：[E338](E338.md)、[E336](E336.md)
+
+---
+*条目 E480 · 更新 2026-08-26 · 知识库同步生成物*

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

@@ -0,0 +1,63 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E481: Adapt a zero-dependency Meson C library to OHOS with a shared-only toolchain, LLVM archive tools, and ELF signing
+
+> **严重度**: 🟡 medium | **分类**: ohos, meson, conan, relocatable, zero-dependency | **自动修复**: ❌ | **原则**: [P013](../principles.md#P013)、[P014](../principles.md#P014)
+
+---
+
+## 错误特征
+
+```
+Dependency .* not found
+Library m found: NO
+shared_library.*cannot be linked
+C compiler cannot create executables
+```
+
+## 根因
+
+A Meson library that declares no pkg-config dependencies still needs four OHOS-specific fixes: (1) the SDK profile often only names clang, so Meson cannot find ar/ranlib for the native file and fails the static or shared archive step; (2) the OHOS worker has no usable /tmp, so clang and ninja fail creating temporary files unless TMPDIR points inside the build folder; (3) math functions live in bionic libc, so the upstream optional cc.find_library('m', required:false) must not abort configure; (4) shared libraries installed by Meson are unsigned ELF and refuse to load on the device until binary-sign-tool stamps a .codesign section.
+
+## 验证命令
+
+```bash
+Run a single-package shadow CI build; require meson setup + ninja to finish, test_package to compile and run the consumer, and readelf -SW on the packaged libxcvt.so.0.1.3 to confirm exactly one .codesign section.
+```
+
+## 解决方案
+
+**shared-only-meson-toolchain-with-llvm-tools**：Build with MesonToolchain and default_library=shared, inject llvm-ar/ranlib full paths into conan_meson_native.ini when the profile only declares clang, pin TMPDIR/TMP/TEMP into the build folder, install meson via pip when absent, and ELF-sign every packaged .so (and bin/) with llvm-objcopy --remove-section .codesign then binary-sign-tool sign -selfSign 1.
+
+```bash
+CI_PACKAGES="〈外部知识库归档〉" zsh 〈外部知识库流水线〉
+```
+
+## 回退方案
+
+**system-tool-path-probing**：When llvm-ar is not co-located with clang, resolve ar/ranlib through PATH (llvm-ar, ar, llvm-ranlib, ranlib) and write them into the Meson native file; if even PATH lacks them, fall back to the SDK tool dirs the profile exposes.
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`strip.*\.codesign|sign.*\.so.*without.*objcopy`
+- **原因**：Re-signing without first removing the previous .codesign section leaves duplicate sections and an invalid signature that can still fail on device.
+- **后果**：The signed .so loads in the sandbox but is rejected on real hardware.
+
+### 🚫 禁止 2
+
+- **模式**：`hardcode.*/tmp|mktemp.*/tmp`
+- **原因**：The OHOS worker has no writable /tmp; a hard-coded /tmp TMPDIR fails for clang temp files.
+- **后果**：C compiler cannot create executables, even when the toolchain itself is healthy.
+
+## 涉及软件
+
+Small C libraries whose upstream Meson build only links optional system libs (e.g. libxcvt 0.1.3, which generates VESA CVT modelines) and that are packaged as shared libraries on an aarch64 OHOS worker.
+
+## 相关模式
+
+- **相似模式**：[E337](E337.md)
+
+---
+*条目 E481 · 更新 2026-08-27 · 知识库同步生成物*

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

@@ -0,0 +1,52 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E482: zsh heredoc 用 $TMPPREFIX（默认 /tmp/zsh）创建临时文件，/tmp 只读时失败
+
+> **严重度**: 🟡 medium | **分类**: environment | **自动修复**: ✅ set-env-var | **原则**: [P014](../principles.md#P014)
+
+---
+
+## 错误特征
+
+```
+can't create temp file for here document
+read-only file system
+here document
+```
+
+## 根因
+
+鸿蒙系统 /tmp 是只读，而 zsh 的 heredoc（<<'EOF'）临时文件目录由
+$TMPPREFIX 决定（默认 /tmp/zsh），**不随 $TMPDIR 变化**。
+只设 TMPDIR 无法解决 zsh heredoc 失败；症状是脚本静默退出
+（set -e 下），报 "can't create temp file for here document: read-only file system"。
+
+## 验证命令
+
+```bash
+在 zsh 里跑一段 heredoc；或检查 zsh -c 'echo $TMPPREFIX'
+```
+
+## 解决方案
+
+**set-env-var**：同时设置 TMPDIR 与 TMPPREFIX 指向可写目录
+
+```bash
+TMPDIR=$HOME/tmp TMPPREFIX=$HOME/tmp/zsh zsh build_and_test.sh
+```
+
+## 回退方案
+
+**env-var**：在脚本开头 export TMPPREFIX=/storage/Users/currentUser/tmp/zsh
+
+## 涉及软件
+
+所有用 zsh 脚本跑 heredoc 的构建/CI（如 build_and_test.sh 的 python3 heredoc）
+
+## 相关模式
+
+- **相似模式**：[E002](E002.md)
+- **根因条目（应先修它们）**：[E002](E002.md)
+
+---
+*条目 E482 · 更新 2026-08-20 · 知识库同步生成物*

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

@@ -0,0 +1,64 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E483: Conan get() 无法从无扩展名下载 URL 推断压缩格式，报 BadZipFile
+
+> **严重度**: 🟡 medium | **分类**: conan, packaging, codeload, source-download, url-extension | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+BadZipFile.*File is not a zip file
+NotADirectoryError.*zip
+conan.*get.*BadZipFile
+failed.*uncompress.*zip
+Uncompressing.*to.*\.\.\..*error
+```
+
+## 根因
+
+Conan tools.files.get() 通过 URL 末段文件名推断压缩格式。当下载 URL 末段是 tag/commit 名而非带扩展名的文件名（典型: GitHub codeload 形如 https://codeload.github.com/owner/repo/tar.gz/refs/tags/2.2.0，末段是 "2.2.0"），Conan 把文件存为 "2.2.0" 并默认按 zip 解压，导致 BadZipFile: File is not a zip file。conandata.yml 中虽声明了正确 URL，但 get() 不读 conandata 的 tar_format 字段做格式提示。
+
+## 验证命令
+
+```bash
+python3 scripts/ohc-run.py conan-verify <name> <ver> 2>&1 | grep -E "BadZipFile|File is not a zip file"
+```
+
+## 解决方案
+
+**explicit-filename-in-get**：在 source() 的 get() 调用中显式传 filename="软件名-版本.tar.gz"，使 Conan 通过扩展名正确识别压缩格式。get(self, **self.conan_data["sources"], strip_root=True, filename="emojify-2.2.0.tar.gz")。conandata.yml 的 URL 无需修改，仍保留 codeload URL（绕过 github.com 阻断）。
+
+```bash
+sed -i 's/get(self, \*\*self.conan_data\["sources"\], strip_root=True)/get(self, **self.conan_data["sources"], strip_root=True, filename="<name>-<ver>.tar.gz")/' 〈外部知识库归档〉
+```
+
+## 回退方案
+
+**rewrite-url-with-extension**：若不想改 get() 调用，可将 conandata.yml 的 URL 改为带扩展名末段的形式，但 codeload.github.com 的 URL 格式固定无法加扩展名，故此方案对 codeload 不适用。仅适用于可重写 URL 的场景。
+
+```bash
+true
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`get\(self,\s*\*\*self\.conan_data\[.sources.\],\s*strip_root=True\s*\)`
+- **原因**：当 conandata URL 末段无扩展名时，此写法必然触发 BadZipFile。
+- **后果**：conan create 在 source() 阶段失败，配方无法构建。
+
+### 🚫 禁止 2
+
+- **模式**：`tar_format:\s*zip`
+- **原因**：get() 不读取 conandata 的 tar_format 字段，声明 zip 不会改变 get() 的格式推断。
+- **后果**：误以为声明了格式就能解决，实际仍 BadZipFile。
+
+## 涉及软件
+
+所有 Conan 配方中 source() 用 get(self, **self.conan_data["sources"], strip_root=True) 下载、且 conandata.yml URL 末段无 .tar.gz/.tar.xz/.zip 扩展名的软件。GitHub codeload 镜像 URL（为绕过 github.com 阻断而使用）最常见此问题。
+
+---
+*条目 E483 · 更新 2026-08-31 · 知识库同步生成物*