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

@@ -0,0 +1,58 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E260: A fixed interpreter launcher must execute the validated file descriptor
+
+> **严重度**: 🔴 blocking | **分类**: java, security, launcher | **自动修复**: ❌ | **原则**: [P017](../principles.md#P017)
+
+---
+
+## 错误特征
+
+```
+native-image.*(126
+127)
+fixed Python launcher selected a shell wrapper
+not an ELF executable
+validated Python path was replaced before exec
+```
+
+## 根因
+
+A signed launcher that validates a fixed Python path but later executes the pathname separates the checked object from the executed object. An executable shell wrapper can pass stat plus X_OK, and a same-UID writer can atomically replace a real ELF after validation but before path-based exec.
+
+## 验证命令
+
+```bash
+Run the launcher with a shell wrapper followed by a real ELF candidate, then replace the selected path after validation; require wrapper rejection, deterministic all-negative failure, and execution of only the retained validated descriptor.
+```
+
+## 解决方案
+
+**descriptor-bound-elf-launch**：Keep the absolute allow-list, open each candidate read-only, bind path and open identities, require ELF magic, retain the descriptor through exec, and launch it with fexecve or an equivalent fd-bound API.
+
+```bash
+Add an open_elf_executable helper that returns a validated descriptor and pass that descriptor directly to fexecve.
+```
+
+## 回退方案
+
+**package-private-elf-interpreter**：Package a trusted ELF interpreter inside the same runtime closure when no stable fixed system interpreter exists.
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`execv\(python|execlp|execvp|system\(|popen\(|/bin/sh|PATH.*python`
+- **原因**：Shell fallback, PATH search, or path execution after validation defeats the fixed-interpreter trust boundary.
+- **后果**：The launcher can execute a different object from the one it validated or fail with opaque 126 or 127 status.
+
+## 涉及软件
+
+Signed C or C++ launchers that invoke a Python companion through fixed interpreter candidates on systems where PATH and shell fallback are outside the trusted execution boundary.
+
+## 相关模式
+
+- **相似模式**：[E083](E083.md)、[E232](E232.md)
+
+---
+*条目 E260 · 更新 2026-08-08 · 知识库同步生成物*

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

@@ -0,0 +1,57 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E261: Transaction rollback must retain the old output when the installed target is untrusted
+
+> **严重度**: 🔴 blocking | **分类**: java, runtime, security | **自动修复**: ❌ | **原则**: [P017](../principles.md#P017)
+
+---
+
+## 错误特征
+
+```
+installed Native Image output must not be a symlink
+Native Image output changed during install
+Native Image transaction rollback failed
+signed-output.*without.*recovery
+```
+
+## 根因
+
+After an exchange commit the backup path carries the previous user output. If rollback trusts only the path, catches only OSError, or cleans temporaries unconditionally, a concurrent symlink, non-regular object, identity error, or same-byte replacement can bypass recovery and cause the previous output to be deleted.
+
+## 验证命令
+
+```bash
+Replace the installed target after exchange with regular, symlink, and injected identity-error objects; require the concurrent target to remain untouched, exactly one verified old-output recovery file, and no path-only cleanup deletion.
+```
+
+## 解决方案
+
+**identity-bound-recovery-and-cleanup**：Verify both exchange sides, treat OS and domain identity errors as recovery conditions, move the old-output backup to a unique no-replace recovery path, revalidate it, and clean only identities recorded by the current invocation.
+
+```bash
+Add identity-bound recovery around installed-target checks and reopen the committed target with no-follow semantics after directory fsync.
+```
+
+## 回退方案
+
+**fail-closed-leave-backup**：When recovery identity cannot be proven, fail without deleting the backup path; a recoverable leftover is safer than losing the previous output.
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`except OSError.*identity|for temporary in temporaries:.*unlink`
+- **原因**：Identity checks can raise domain errors, and path-only cleanup is not bound to the object created by the current transaction.
+- **后果**：Rollback can delete the previous user output or a concurrently replaced object.
+
+## 涉及软件
+
+Signed finalizers and transactional packagers that exchange a staged artifact into a public target while retaining the previous target in a temporary backup until commit durability is proven.
+
+## 相关模式
+
+- **相似模式**：[E260](E260.md)
+
+---
+*条目 E261 · 更新 2026-08-08 · 知识库同步生成物*

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

@@ -0,0 +1,53 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E262: Reserved scratch aliases must be classified before strict parent resolution
+
+> **严重度**: 🔴 blocking | **分类**: runtime, filesystem, permissions, security, symlink | **自动修复**: ❌ | **原则**: [P017](../principles.md#P017)
+
+---
+
+## 错误特征
+
+```
+FileNotFoundError:.*\.t
+Native Image output directory is missing:.*scratch
+Native Image output must not use scratch path
+scratch-alias
+```
+
+## 根因
+
+An output path can traverse a symlink into a reserved scratch tree whose final parent does not yet exist. Strict resolution fails with FileNotFoundError before the safety policy classifies the alias, so a security rejection is misreported as an ordinary missing-directory error.
+
+## 验证命令
+
+```bash
+Create scratch-alias pointing to a missing .t directory and require the reserved-scratch error; use an unrelated missing parent as a control and require the ordinary missing-directory error.
+```
+
+## 解决方案
+
+**policy-first-nonstrict-resolution**：When strict parent resolution fails, walk components with a bounded non-strict policy resolver, follow links explicitly, detect loops, and classify whether the destination resolves into the reserved scratch tree before emitting the ordinary missing-parent error.
+
+```bash
+Resolve the candidate parent and cwd/.t with the policy-only resolver, then pass scratch aliases to the existing safe-destination gate.
+```
+
+## 回退方案
+
+**reject-unresolved-symlink-destinations**：If a bounded non-strict resolver is unavailable, fail closed on unresolved destinations containing symlink components rather than treating them as ordinary missing parents.
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`Path\(.*\)\.resolve\(strict=True\).*scratch|except FileNotFoundError:.*missing`
+- **原因**：Strict resolution before policy classification hides a reserved scratch alias behind a generic missing-directory error.
+- **后果**：Security tests exercise the wrong terminal class and callers cannot distinguish policy rejection from an absent directory.
+
+## 涉及软件
+
+Build wrappers and code generators that reserve a fixed scratch subtree, reject outputs inside it, and accept user-provided destinations that may traverse symbolic links.
+
+---
+*条目 E262 · 更新 2026-08-08 · 知识库同步生成物*

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

@@ -0,0 +1,52 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E263: Package tests must resolve runtime helpers from the installed layout contract
+
+> **严重度**: 🟡 medium | **分类**: python, java, packaging, testing | **自动修复**: ❌ | **原则**: [P010](../principles.md#P010)
+
+---
+
+## 错误特征
+
+```
+FileNotFoundError:.*native_image_finalizer\.py
+fake-java/bin/native_image_finalizer\.py
+installed wrapper.*finalizer.*missing
+```
+
+## 根因
+
+A test helper assumes the wrapper and its support module are source-tree siblings. The installed package deliberately places the public companion under bin and the support module under JAVA_HOME/libexec, so the test passes in the source tree but fails against the packaged artifact.
+
+## 验证命令
+
+```bash
+Run the same transaction test against both the source-tree wrapper and the installed bin companion; require finalizer resolution from the sibling path for source tests and JAVA_HOME/libexec for package tests.
+```
+
+## 解决方案
+
+**layout-aware-helper-resolution**：Resolve the source-tree sibling first, then derive the installed runtime root through the wrapper's own JAVA_HOME contract and search its libexec support directory; report every searched path on failure.
+
+```bash
+Use wrapper._java_home(wrapper_path) and append libexec/graalvm-ohos/native_image_finalizer.py after the sibling candidate.
+```
+
+## 回退方案
+
+**explicit-runtime-helper-parameter**：Accept an explicit helper path from the package test driver when the production wrapper cannot expose its runtime-root derivation.
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`wrapper\.parent.*/.*native_image_finalizer\.py|copy.*native_image_finalizer.*bin`
+- **原因**：A sibling-only lookup encodes the source tree, while copying support code into bin changes the installed runtime contract solely to satisfy a test.
+- **后果**：Source tests pass but packaged consumer tests fail or the package gains duplicate, divergent support modules.
+
+## 涉及软件
+
+Packages whose source layout and installed runtime layout place launcher companions or support modules in different directories, especially tests that dynamically load helpers by deriving sibling paths.
+
+---
+*条目 E263 · 更新 2026-08-08 · 知识库同步生成物*

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

@@ -0,0 +1,73 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E264: Bridge legacy *-config probes with a metadata-derived signed ELF adapter
+
+> **严重度**: 🟡 medium | **分类**: hmdfs, autotools, linking, conan, dependency | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+configure: error: .*config.*not found
+Permission denied.*-config
+cannot execute.*-config
+could not run.*-config
+```
+
+## 根因
+
+A legacy configure script may require an executable *-config helper even when the Conan dependency exposes only structured CMake or pkg-config metadata. A shell shim in the package cache is not a reliable executable contract on HMDFS, while hard-coded include and library paths bind the recipe to one cache layout.
+
+## 验证命令
+
+```bash
+Compare every supported helper query with the resolved Conan dependency metadata; reject missing metadata and unknown arguments; verify a target ELF with a valid signature; then run configure and a real consumer against the same exact dependency graph.
+```
+
+## 解决方案
+
+**metadata-derived-native-config-adapter**：Generate a minimal C helper in the build folder from the resolved dependency cpp_info values, compile it with the active Conan C compiler, sign the resulting target ELF when the executor requires signed binaries, and pass its absolute path through the upstream --with-<name>config option. Implement only the query surface actually consumed by upstream and fail closed for unsupported arguments or absent metadata.
+
+```bash
+dep = self.dependencies["<name>"].cpp_info
+# Fail if required include or library metadata is absent.
+# Escape values as C string literals, generate one small query program,
+# compile it with tools.build:compiler_executables, sign the final ELF,
+# and pass --with-<name>config=<absolute helper path> to configure.
+```
+
+## 回退方案
+
+**verified-provider-native-helper**：Use a provider-supplied native *-config executable only when it belongs to the exact resolved package revision and its outputs are verified against Conan metadata.
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`(storage/Users|\.conan2).*(-I|-L|includedir|libdir)|hard.?cod.*(include|lib).*-config`
+- **原因**：Hard-coded cache or device paths do not follow the resolved package revision and break in fresh Conan homes.
+- **后果**：Configure may bind to stale headers or libraries, or fail when the cache layout changes.
+
+### 🚫 禁止 2
+
+- **模式**：`write.*(\.sh|shell).*config|echo.*(-I|-L).*>.*-config`
+- **原因**：A generated shell shim still depends on direct script execution from a filesystem that may reject it.
+- **后果**：Dependency discovery remains blocked before compilation even though all metadata is present.
+
+### 🚫 禁止 3
+
+- **模式**：`unknown.*return 0|argc.*return 0|default.*success.*-config`
+- **原因**：Treating unknown queries as success silently weakens the upstream helper contract.
+- **后果**：Configure can accept incomplete flags and fail later with mismatched headers, unresolved symbols, or a wrong ABI.
+
+## 涉及软件
+
+Conan recipes for Autotools or custom configure consumers that must execute a legacy dependency-query helper although the packaged dependency exposes equivalent include, library, version, and link metadata through Conan.
+
+## 相关模式
+
+- **相似模式**：[E077](E077.md)
+
+---
+*条目 E264 · 更新 2026-08-08 · 知识库同步生成物*

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

@@ -0,0 +1,84 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E265: OHOS 上运行 Linux 文件系统镜像类上游测试的可写目录、shell、locale 和工具链差异处理方法
+
+> **严重度**: 🟡 medium | **分类**: compat, ohos, testing | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+upstream_test_fs_image_compatibility
+valgrind_not_available
+OHOS_no_valgrind
+```
+
+## 根因
+
+OHOS 的 /tmp 是 erofs 只读文件系统，上游测试硬编码 /tmp 路径导致 mkdir 失败；缺少 dosfstools/valgrind；grep 不支持 -oP；locale 排序规则与 Linux 不同；无 valgrind 时不能伪造 valgrind 测试通过
+
+## 验证命令
+
+```bash
+make -C <test_dir> SHELL=/data/service/hnp/bin/bash TMPDIR=<writable_dir> FS_IMG=<writable_dir>/fs.img FATSORT=<path_to_fatsort> LC_ALL=C
+```
+
+## 解决方案
+
+**1) 覆盖 SHELL/TMPDIR/FS_IMG 绕过 /tmp 只读限制；2) 用 sed -nE 替代 grep -oP；3) 无 valgrind 时用 clang ASan/UBSan（-fsanitize=address,undefined）替代内存检查，单独统计通过率，不能伪造 valgrind 通过；4) 设置 LC_ALL=C 匹配 OHOS locale；5) 在 OHOS 上重新生成 expected 输出文件**：OHOS 的 /tmp 是 erofs 只读文件系统，所有硬编码 /tmp 路径的上游测试需通过 TMPDIR/FS_IMG 覆盖到可写目录；
+SHELL 需覆盖为 OHOS 上存在的 bash 路径；grep -oP 需替换为 sed -nE；
+valgrind 专用测试（如 tc_pos_valgrind_*）在 OHOS 无可用 valgrind 时必须标记为 skip，禁止伪造通过；
+替代内存检查使用 clang 的 -fsanitize=address,undefined（ASan+UBSan），需按以下步骤验证：
+a) 确认 sanitizer runtime 存在：libclang_rt.asan.so / libclang_rt.asan.a、libclang_rt.ubsan_standalone.so / libclang_rt.ubsan_standalone.a
+b) 最小 ASan/UBSan 程序编译+运行通过
+c) fatsort 以 -fsanitize=address,undefined 构建成功
+d) 确认二进制包含 ASan/UBSan 符号（readelf -s | grep -i asan 等）
+e) fatsort -v / -h 运行通过
+f) 注意：该验证为编译+smoke 验证，未覆盖真实数据流；需单独统计，不能与上游测试通过率合并
+locale 需设置为 C 并重新生成 expected 输出
+
+```bash
+# 1. 验证 sanitizer runtime
+ls /data/service/hnp/ohos-sdk.org/ohos-sdk_26.0.0.18/ohos/native/llvm/lib/clang/15.0.4/libclang_rt.asan.*
+ls /data/service/hnp/ohos-sdk.org/ohos-sdk_26.0.0.18/ohos/native/llvm/lib/clang/15.0.4/libclang_rt.ubsan_standalone.*
+# 2. 最小 ASan/UBSan 程序
+echo 'int main() { int a[10]; a[20] = 42; return 0; }' | /data/service/hnp/bin/clang -x c - -fsanitize=address,undefined -o /storage/Users/currentUser/tmp/test_asan
+/storage/Users/currentUser/tmp/test_asan 2>&1 | grep -q 'heap-buffer-overflow' && echo 'ASan OK'
+# 3. 构建 fatsort with ASan/UBSan
+make -C src CC=/data/service/hnp/bin/clang LD=/data/service/hnp/bin/clang CFLAGS="-fPIC -O2 -D__LINUX__ -fsanitize=address,undefined" LDFLAGS="-fsanitize=address,undefined"
+# 4. 确认符号
+readelf -s src/fatsort | grep -i asan
+# 5. 运行验证
+src/fatsort -v
+src/fatsort -h
+# 6. 运行上游测试（除 valgrind 外）
+make tests SHELL=/data/service/hnp/bin/bash TMPDIR=/storage/Users/currentUser/tmp FS_IMG=/storage/Users/currentUser/tmp/fs.img FATSORT=../src/fatsort LC_ALL=C
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`valgrind.*通过|valgrind.*pass|valgrind.*PASS|tc_pos_valgrind.*PASS`
+- **原因**：OHOS 当前无可用 valgrind，禁止将 valgrind 专用测试（tc_pos_valgrind_*）标记为通过；必须标记为 skip 并如实记录
+- **后果**：欺骗审核，导致 CI 审计失败；PR 被拒绝并可能影响参赛资格
+
+### 🚫 禁止 2
+
+- **模式**：`125/125|100%通过.*(上游|upstream)|上游.*无测试`
+- **原因**：上游有 125 个测试，4 个 valgrind 专用测试因 OHOS 无 valgrind 跳过，实际通过率应为 121/125（96.8%），不能写 125/125 或 100%
+- **后果**：测试统计口径不真实，违反积分赛 PR 模板规则
+
+### 🚫 禁止 3
+
+- **模式**：`ASan.*取代.*valgrind|ASan.*替代.*valgrind.*通过|替代内存检查.*100%.*上游|替代内存检查.*1/1`
+- **原因**：ASan/UBSan 替代验证是单独的编译+镜像验证，需覆盖 4 个 FAT 文件系统镜像（exFAT/FAT12/FAT16/FAT32）并分别统计为 4/4，不能与上游测试通过率合并；旧统计口径 1/1 仅覆盖 -v/-h smoke，需升级为 4/4 覆盖真实数据流
+- **后果**：统计口径不完整，审核不通过
+
+## 涉及软件
+
+所有使用 testconfig.mk 且依赖 /tmp 可写、bash、valgrind、dosfstools、grep -oP 和 en_US.UTF-8 locale 的 Linux 文件系统镜像类上游测试
+
+---
+*条目 E265 · 更新 2026-07-20 · 知识库同步生成物*

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

@@ -0,0 +1,61 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E266: lld 链接器缺少 libxml2.so.16 依赖导致 clang 链接失败
+
+> **严重度**: 🔴 blocking | **分类**: linking, dependency | **自动修复**: ✅ add-fuse-ld-flag
+
+---
+
+## 错误特征
+
+```
+Error loading shared library libxml2.so.16.*needed by.*lld
+xmlFreeDoc: symbol not found
+clang.*error: unable to execute command: No such file or directory
+clang.*error: linker command failed due to signal
+```
+
+## 根因
+
+ohos-sdk 自带的 lld 链接器是动态链接的 ELF，运行时依赖 libxml2.so.16，但系统默认库搜索路径中找不到该库，导致 lld 无法启动，clang 链接阶段失败
+
+## 验证命令
+
+```bash
+/data/service/hnp/ohos-sdk.org/ohos-sdk_26.0.0.18/ohos/native/llvm/bin/lld --version 2>&1 | grep -q "libxml2" && echo "AFFECTED" || echo "OK"
+```
+
+## 解决方案
+
+**use-alternative-linker**：使用 -fuse-ld=/data/service/hnp/bin/ld 指定 GNU ld 2.45 替代有问题的 lld
+
+```bash
+clang -fuse-ld=/data/service/hnp/bin/ld -o output source.c $(CFLAGS) $(LDFLAGS) -lssl -lcrypto
+```
+
+## 回退方案
+
+**set-ld-library-path**：设置 LD_LIBRARY_PATH 包含 libxml2.so.16 所在目录（可能在某些环境下不生效）
+
+```bash
+export LD_LIBRARY_PATH=/storage/Users/currentUser/usr/local/lib:$LD_LIBRARY_PATH
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`ln -sf.*libxml2`
+- **原因**：不要用 ln -sf 创建软链接覆盖系统库路径（R5 铁律）
+- **后果**：HMDFS 软链接问题可能导致系统不稳定
+
+## 涉及软件
+
+所有使用 clang 默认 lld 链接器的编译任务
+
+## 相关模式
+
+- **相似模式**：[E002](E002.md)
+
+---
+*条目 E266 · 更新 2026-07-06 · 知识库同步生成物*

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

@@ -0,0 +1,55 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E267: OpenHarmony toolchains do not use CMAKE_SYSTEM_NAME=Linux co…
+
+> **严重度**: 🟡 medium | **分类**: platform, detection, cmake | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+CMAKE_SYSTEM_NAME=OHOS
+CMAKE_SYSTEM_NAME=HarmonyOS
+CMAKE_SYSTEM_NAME:STRING=OHOS
+CMAKE_SYSTEM_NAME:STRING=HarmonyOS
+System is unknown to cmake
+OS_LINUX not defined
+```
+
+## 根因
+
+OpenHarmony toolchains do not use CMAKE_SYSTEM_NAME=Linux consistently: the official SDK uses OHOS while the adapted Conan toolchain may use HarmonyOS, so Linux-only or single-spelling platform guards silently miss one build path
+
+## 验证命令
+
+```bash
+grep -R -E 'CMAKE_SYSTEM_NAME.*(OHOS|HarmonyOS)' CMakeLists.txt cmake 2>/dev/null
+```
+
+## 解决方案
+
+**add-harmonyos-cmake-detection**：Match both official spellings with CMAKE_SYSTEM_NAME MATCHES "^(OHOS|HarmonyOS)$" for OpenHarmony-specific routing; when source behavior depends on that decision, inject a project-local PRIVATE feature macro into the target that actually compiles the source, including the underlying object-library target created by build helpers
+
+```bash
+grep -R -E 'CMAKE_SYSTEM_NAME.*(OHOS|HarmonyOS)|target_compile_definitions' CMakeLists.txt cmake 2>/dev/null
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`CMAKE_SYSTEM_NAME (STREQUAL|MATCHES) "?(OHOS|HarmonyOS)"?`
+- **原因**：Matching only one spelling makes local official-SDK validation and Conan CI take different platform branches
+- **后果**：Platform flags, target properties, dependency routing, or shared-library behavior can differ between local validation and CI without a configure error
+
+## 涉及软件
+
+CMake projects and reusable modules that route Unix behavior, shared-library metadata, feature checks, or platform macros by CMAKE_SYSTEM_NAME
+
+## 相关模式
+
+- **相似模式**：[E007](E007.md)、[E159](E159.md)
+
+---
+*条目 E267 · 更新 2026-07-20 · 知识库同步生成物*

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

@@ -0,0 +1,40 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E268: patch-autotools-ohos.pl 对新版 config.sub 误判跳过 linux-ohos 内核校验补丁
+
+> **严重度**: 🟡 medium | **分类**: compat, autotools, patch | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Kernel 'linux' not known to work with OS 'ohos'
+config.sub.*ohos.*failed
+linux-ohos
+```
+
+## 根因
+
+patch-autotools-ohos.pl step 2.3 以 grep 全文 linux-ohos 判定是否已补丁；新版 config.sub(2024+) 的 basic_os 分支已含 linux-ohos(来自 ohos-linux triplet)，但内核-OS 校验列表 'case kernel-os-obj' 中 linux-uclibc*- 行仍缺 linux-ohos*-，导致 aarch64-unknown-linux-ohos 被拒绝
+
+## 验证命令
+
+```bash
+bash config.sub aarch64-unknown-linux-ohos && grep -c "linux-ohos\*" config.sub
+```
+
+## 解决方案
+
+**patch-source**：手动在 config.sub 内核-OS 校验列表 linux-uclibc*- 前追加 '| linux-ohos*-'，或改进补丁脚本检测该列表而非全文 grep
+
+```bash
+可选: 具体命令模板(${VAR}变量引用)
+```
+
+## 涉及软件
+
+所有 2024+ 版 config.sub 的 autotools 项目在 OHOS 上打 E205 补丁时
+
+---
+*条目 E268 · 更新 2026-08-08 · 知识库同步生成物*

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

@@ -0,0 +1,57 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E269: Python 2 测试 runner 在 OHOS Python 3 环境中无法执行
+
+> **严重度**: 🟡 medium | **分类**: testing | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+SyntaxError: Missing parentheses in call to print
+#!/usr/bin/env python2
+Python 2.*runner
+print .*SyntaxError
+```
+
+## 根因
+
+上游测试 runner 使用 Python 2 的 print 语句或其他仅 Python 2 支持的语法；HarmonyOS CI 仅提供 Python 3，导致语法检查或测试执行失败。
+
+## 验证命令
+
+```bash
+python3 -m py_compile <runner.py> && LD_LIBRARY_PATH=<build_folder> python3 <runner.py> && test <通过数> -eq <语料总数>
+```
+
+## 解决方案
+
+**port-python-script**：对于不依赖 Python 2 C 扩展或 Python 2 专有第三方包的测试 runner，保持测试语料和断言语义不变，将 shebang 改为 python3、print 语句改为函数调用，并将 subprocess.check_output 返回的 bytes 在展示错误时显式 decode。将迁移后的 runner 纳入构建或测试阶段，以目标二进制和完整上游语料执行验证。
+
+```bash
+python3 -m py_compile run_tests.py && LD_LIBRARY_PATH=<build_folder> python3 run_tests.py
+```
+
+## 回退方案
+
+**execute-targeted-tests**：当 runner 使用 Python 2 C 扩展、Python 2 专有第三方包或复杂 unicode/str 语义而无法安全迁移时，保留上游语料不变，选取可独立执行的核心目标测试；同时在适配报告中明确未执行范围和阻塞依赖。
+
+```bash
+LD_LIBRARY_PATH=<build_folder> <target-test-binary>
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`delete.*testcases|skip.*testcases|not run.*Python 2`
+- **原因**：不能通过删除、改写或标记跳过上游语料来规避 Python 2 runner 兼容问题。
+- **后果**：上游测试覆盖被削弱，测试通过率失真，无法证明迁移后的库行为与上游一致。
+
+## 涉及软件
+
+使用 Python 2 编写、通过 subprocess 调用已构建目标二进制并比对文本或 JSON 语料的 C/C++ 项目测试 runner；不适用于依赖 Python 2 C 扩展、urllib2、unicode/str 语义或 Python 2 专有第三方包的 runner。
+
+---
+*条目 E269 · 更新 2026-07-24 · 知识库同步生成物*

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

@@ -0,0 +1,69 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E270: CLOCK_SGI_CYCLE may be declared but unsupported at runtime
+
+> **严重度**: 🟡 medium | **分类**: platform, compat | **自动修复**: ❌ | **原则**: [P007](../principles.md#P007)、[P020](../principles.md#P020)
+
+---
+
+## 错误特征
+
+```
+clock_gettime\(CLOCK_SGI_CYCLE.*EINVAL
+bench -s.*timeout
+measure_execution_time.*start_over
+```
+
+## 根因
+
+Some libc headers expose CLOCK_SGI_CYCLE even though
+the kernel rejects clock_gettime(CLOCK_SGI_CYCLE, ...)
+with EINVAL. FFTW 3.3.10 selects this clock when the
+macro is defined and does not check the return code.
+Invalid timing samples can repeatedly restart planner
+measurement and prevent default FFTW_MEASURE planning
+from terminating.
+
+## 验证命令
+
+```bash
+Probe CLOCK_SGI_CYCLE and CLOCK_MONOTONIC return codes,
+rebuild, then run unchanged CTest entries 32x64 and ib256.
+```
+
+## 解决方案
+
+**source-patch**：Check clock_gettime(CLOCK_SGI_CYCLE, ...) at runtime and
+fall back to CLOCK_MONOTONIC only when it fails. Preserve
+the upstream clock on platforms where it is supported and
+leave the upstream test arguments unchanged.
+
+```bash
+Patch kernel/cycle.h to check the clock_gettime return value.
+```
+
+## 回退方案
+
+**monotonic-clock**：Use CLOCK_MONOTONIC unconditionally in the existing
+struct timespec timing branch when a runtime fallback is
+not suitable for the target environment.
+
+```bash
+Replace CLOCK_SGI_CYCLE with CLOCK_MONOTONIC in kernel/cycle.h.
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`-oestimate`
+- **原因**：Adding -oestimate changes the official benchmark planner mode.
+- **后果**：A fast diagnostic result would not prove the original upstream entry passed.
+
+## 涉及软件
+
+FFTW 3.3.10 and software that treats a declared
+CLOCK_SGI_CYCLE macro as proof of runtime support.
+
+---
+*条目 E270 · 更新 2026-07-24 · 知识库同步生成物*