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

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

@@ -0,0 +1,58 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E240: Split macOS CoreGraphics display tools into OHOS-supported read-only capability and explicit unsupported boundaries
+
+> **严重度**: 🟡 medium | **分类**: platform, api | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+ApplicationServices/ApplicationServices.h
+CoreGraphics
+CGDisplayCopyDisplayMode
+CGConfigureDisplayWithDisplayMode
+NativeDisplayManager
+```
+
+## 根因
+
+Some command-line display tools are built around Apple-only CoreGraphics display APIs. OHOS NativeDisplayManager public C APIs can query default-display width, height, and refresh rate, but they do not provide an equivalent physical display mode setter or a complete switchable mode enumeration in the API surface used by the port.
+
+## 验证命令
+
+```bash
+Run the OHOS package on a true device and require version/get to pass while list/set return non-zero with explicit unsupported diagnostics.
+```
+
+## 解决方案
+
+**capability-split-with-negative-tests**：Keep the real OHOS capability implemented through NativeDisplayManager for read-only display metrics. Do not fake list/set success; implement unsupported diagnostics and assert those commands fail in test_package.
+
+```bash
+Add an OHOS backend using OH_NativeDisplayManager_GetDefaultDisplayWidth/Height/RefreshRate, return success only for -version/get, and add negative tests for list/set.
+```
+
+## 回退方案
+
+**mark-platform-invalid**：If no public target API can provide even read-only display metrics, reject the platform in validate() instead of shipping a misleading CLI.
+
+```bash
+raise ConanInvalidConfiguration("no OHOS display backend available")
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`return\s+0;.*(list|set)|unsupported.*exit\s+0`
+- **原因**：Returning success for unimplemented mode listing or mode setting misrepresents the platform capability boundary.
+- **后果**：CI and downstream users can believe destructive display mode operations are supported when the OHOS backend only implements read-only metrics.
+
+## 涉及软件
+
+Small macOS display utilities that combine current-mode query, mode listing, and physical display mode mutation in one CLI, such as screenresolution 1.6.
+
+---
+*条目 E240 · 更新 2026-07-25 · 知识库同步生成物*

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

@@ -0,0 +1,80 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E241: OHOS 上数据/规则清单型库的固定版本、hash 完整性、规则查询和精确输出比对方法
+
+> **严重度**: 🟡 medium | **分类**: packaging | **自动修复**: ❌ | **原则**: [P001](../principles.md#P001)
+
+---
+
+## 错误特征
+
+```
+data-only
+rule-list
+no-compile
+no test suite
+!check
+json data
+static data
+data package
+```
+
+## 根因
+
+OpenHarmony PC 适配中遇到没有 C/C++ 源码、不需要编译、没有传统测试套件的数据/规则清单型上游库。这类库的核心价值在于提供固定版本的权威数据（JSON/规则清单）和可编程查询接口。传统 CMake/Autotools 模板不适用，需要专门的数据包适配模式。
+
+## 验证命令
+
+```bash
+conan create 〈外部知识库归档〉 -tf=test_package
+```
+
+## 解决方案
+
+**data-package-pattern**：数据包核心模式：
+1. settings = None（不依赖编译器/架构）
+2. 不设置 package_type（避免触发 CLI 工具命令检查）
+3. source() 使用 get() 下载 tarball
+4. build() 中验证数据完整性（版本号、总数、hash）
+5. package() 复制数据到 res/ 目录
+6. test_package 使用独立 .py 脚本 + self.run() 调用
+7. test_package 输出固定 JSON 摘要供精确比对
+
+```bash
+# conanfile.py 关键配置:
+#   settings = None
+#   def build(): apply_conandata_patches(self); 数据校验...
+#   def package(): copy(self, "*", src=json_dir, dst=res_dir)
+#   def package_info(): self.cpp_info.resdirs = ["res"]
+#
+# test_package/conanfile.py:
+#   def test():
+#     dep = self.dependencies["pkg"]
+#     self.run(f"python3 test_pkg.py \"{dep.package_folder}/res\"",
+#              cwd=self.source_folder, env="conanrun")
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`package_type.*=.*"application"`
+- **原因**：数据包不应设置 package_type="application"，否则 CI 误判为 CLI 工具并要求 commands.json
+- **后果**：W3 CI 阻塞，需要额外创建 commands.json
+
+### 🚫 禁止 2
+
+- **模式**：`settings\s*=\s*["']?[^N]|settings\s*=\s*["']os["']`
+- **原因**：数据包不依赖编译器/架构，不应设置 os/compiler/arch 等 settings
+- **后果**：Conan 会要求为每种架构编译同一份数据
+
+## 涉及软件
+
+SPDX License List 数据包、IANA 协议/服务名数据、Unicode 字符数据库、时区数据（tzdata）、CA 证书列表、任何以 JSON/数据文件为主要产出的上游项目。
+
+## 相关模式
+
+- **相似模式**：[E221](E221.md)
+
+---
+*条目 E241 · 更新 2026-07-28 · 知识库同步生成物*

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

@@ -0,0 +1,65 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E242: Bind compiler-specific Fortran module files to Conan package identity and consumer CMake gates
+
+> **严重度**: 🟡 medium | **分类**: linking, fortran | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Cannot open module file
+module file was created by a different version
+Unexpected EOF in module file
+requires LLVMFlang
+```
+
+## 根因
+
+Fortran .mod files are compiler-specific binary interfaces, but a normal Conan library package ID and an imported CMake target do not automatically encode the compiler executable that produced them. A consumer can therefore resolve the archive while using an incompatible compiler ID or version, or use the Fortran target without explicitly accepting its compiler contract.
+
+## 验证命令
+
+```bash
+Verify Conan graph identity uses the exact Fortran tool package in full_mode, then configure positive and negative CMake consumers for matching compiler, missing component, disabled Fortran language, wrong compiler ID, and wrong compiler version.
+```
+
+## 解决方案
+
+**compiler-identity-package-and-component-gate**：Declare the exact Fortran compiler package as a tool requirement with
+package_id_mode=full_mode in both the producer and Fortran consumer. Export
+the Fortran archive and module files as a separate Conan component. Attach a
+CMake build module that requires an explicit Fortran component, verifies that
+the Fortran language is enabled, and checks the compiler ID and exact version
+before allowing the imported Fortran target to link. Keep the C-only
+component independent of this gate.
+
+```bash
+self.tool_requires("<fortran-tool>/<version>", package_id_mode="full_mode")
+# Package .mod files with the Fortran archive in a separate component.
+# Export a cmake_build_modules guard that checks COMPONENTS Fortran,
+# CMAKE_Fortran_COMPILER_LOADED, CMAKE_Fortran_COMPILER_ID, and
+# CMAKE_Fortran_COMPILER_VERSION before enabling the Fortran target.
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`package.*\.mod.*without.*(compiler|tool_requires|full_mode)`
+- **原因**：Shipping module files without compiler identity permits ABI-incompatible consumers to resolve the package.
+- **后果**：Downstream compilation can fail with unreadable module diagnostics or, for insufficiently checked formats, consume an incompatible interface.
+
+### 🚫 禁止 2
+
+- **模式**：`find_package\([^)]*\).*Libxc::xcf03|target_link_libraries\([^)]*xcf03`
+- **原因**：A Fortran target must not be usable without an explicit component contract and compiler checks.
+- **后果**：CMake target discovery appears successful even though the active Fortran compiler cannot consume the installed modules.
+
+## 涉及软件
+
+Conan packages that install precompiled Fortran .mod files, especially mixed C and Fortran libraries whose C component should remain usable without the Fortran toolchain.
+
+---
+*条目 E242 · 更新 2026-07-29 · 知识库同步生成物*

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

@@ -0,0 +1,58 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E243: Protocol-data packages need per-document generator tests
+
+> **严重度**: 🟡 medium | **分类**: packaging, testing, api | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+protocol generator validation failed
+installed XML, Python, or pkg-config metadata is incomplete or non-relocatable
+module output callback order is incorrect
+```
+
+## 根因
+
+A data-only protocol package can contain the expected file count and pass one schema command while still being unusable: imports may be missing, generator semantic resolution may fail, Python modules may be installed outside the exported search path, or pkg-config variables may point outside the package. File inventory, schema validity, generator behavior, and installed discovery are separate contracts.
+
+## 验证命令
+
+```bash
+conan create <recipe> -pr:h=<target-profile> -pr:b=<target-profile> --build='*'
+```
+
+## 解决方案
+
+**per-document-generator-plus-discovery-matrix**：Lock the upstream document and module inventories. Preserve the upstream schema test, but also run every installed protocol input through the real generator registration and semantic-resolution API in a separate process. Add unique fixtures for public semantic branches and verify that pkg-config and language search paths resolve inside the installed package.
+
+```bash
+conan create <recipe> -pr:h=<target-profile> -pr:b=<target-profile> --build='*'
+```
+
+## 回退方案
+
+**schema-and-installed-smoke**：If the generator cannot run on the target, execute the authoritative schema suite and an installed discovery smoke, then record generator execution as an explicit unresolved test gap rather than claiming full consumer coverage.
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`(count|glob|list).*(xml|schema).*(only|enough)|assert.*file.*exists.*return.*0`
+- **原因**：Inventory-only tests do not execute imports, expression handling, type resolution, or generator callbacks.
+- **后果**：The package looks complete but downstream code generation fails after publication.
+
+### 🚫 禁止 2
+
+- **模式**：`(schema|generator).*(shared|static|repeat).*(count|case)|assertion.*split.*test`
+- **原因**：Repeating the same input or splitting its assertions does not create an independent protocol workflow.
+- **后果**：Reported coverage is inflated without increasing semantic or input coverage.
+
+## 涉及软件
+
+Packages that distribute machine-readable protocol/schema documents together with Python or other language-independent parsers and generators instead of a linked library.
+
+---
+*条目 E243 · 更新 2026-07-20 · 知识库同步生成物*

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

@@ -0,0 +1,58 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E244: Capture handle operation errors before closing resources
+
+> **严重度**: 🟡 medium | **分类**: runtime, testing, api | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+operation returned failure but reported error is zero
+last operation error lost after close
+error reporting dereferences a closed handle
+```
+
+## 根因
+
+Some C libraries report open and close failures through an out-parameter but store errors from operations on an already-open resource inside the live handle. Reusing the open out-parameter for operation failures reports a stale success value. Closing first can overwrite the out-parameter and free the handle, making later error access invalid.
+
+## 验证命令
+
+```bash
+Run separate consumers that force an operation failure after a successful open and require the live handle error to be nonzero before close.
+```
+
+## 解决方案
+
+**operation-fault-injection-with-pre-close-error-snapshot**：Give open, operation, and close errors separate variables. After an operation returns failure, read or snapshot the documented handle error before closing. Use deterministic fault fixtures in separate consumer processes and verify that the open error remains success while the operation error is nonzero.
+
+```bash
+conan create <recipe> -pr:h=<target-profile> -pr:b=<target-profile> --build='*'
+```
+
+## 回退方案
+
+**documented-error-field-audit**：If deterministic target fault injection is unavailable, verify the installed public header and implementation contract, but record runtime error-lifetime coverage as pending.
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`operation.*failed.*open_error|close.*then.*handle.*error|free.*then.*error`
+- **原因**：The open out-parameter does not own later operation failures, and a closed handle may already be freed.
+- **后果**：Diagnostics report zero or the close result, or access freed memory, hiding the original failure.
+
+### 🚫 禁止 2
+
+- **模式**：`happy.path.*only|mock.*error.*without.*real.*public.api`
+- **原因**：A successful round trip does not execute the error ownership contract, and a mock cannot prove the library's real state transition.
+- **后果**：Error handling remains untested even though normal encoding or decoding passes.
+
+## 涉及软件
+
+Stateful C APIs whose open/close calls use error out-parameters while read, write, parse, encode, or decode calls store their last error in a live handle or context object.
+
+---
+*条目 E244 · 更新 2026-07-20 · 知识库同步生成物*

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

@@ -0,0 +1,75 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E245: OHOS libc 未导出 vhangup（声明缺失+符号缺失），但内核 syscall 存在
+
+> **严重度**: 🔴 blocking | **分类**: platform, limitation, api | **自动修复**: ❌ | **原则**: [P004](../principles.md#P004)、[P015](../principles.md#P015)
+
+---
+
+## 错误特征
+
+```
+call to undeclared function 'vhangup'
+ld.lld: error: undefined symbol: vhangup
+undefined symbol: vhangup
+```
+
+## 根因
+
+OHOS SDK ohos-sdk_26.0.0.18（clang 15.0.4，aarch64-unknown-linux-ohos）上，
+vhangup(2) 出现三层问题：
+1) 声明缺失：sysroot 头文件（unistd.h / sys/vt.h / sys/*.h）均无 vhangup 声明，
+   编译产生 implicit-function-declaration 警告；
+2) libc 符号缺失：libc.so（nm -D 核验）未导出 vhangup 符号，链接报
+   ld.lld: error: undefined symbol: vhangup；
+3) 内核 syscall 仍存在：aarch64 bits/syscall.h 定义 __NR_vhangup=58 / SYS_vhangup=58，
+   即内核能力存在但 libc 未封装，可通过 syscall(SYS_vhangup) 直调。
+agetty.c 在 F_HANGUP 路径（--hangup 选项）调用 vhangup()，触发上述问题。
+
+## 验证命令
+
+```bash
+grep SYS_vhangup $SYSROOT/usr/include/aarch64-linux-ohos/bits/syscall.h
+nm -D $SYSROOT/usr/lib/aarch64-linux-ohos/libc.so | grep vhangup
+```
+
+## 解决方案
+
+**ohos-syscall-shim**：仅 OHOS 条件下使用 AArch64 SYS_vhangup syscall 封装（shim），不伪造 libc API：
+  int vhangup(void) { return (int)syscall(SYS_vhangup); }
+实现位于 〈外部知识库归档〉（连同 utmpx no-op 降级一起，
+utmpx 部分归 E121 已覆盖，非本条目新贡献）。非 OHOS 平台不启用 shim，保持上游语义。
+
+```bash
+# 诊断流程：
+# 1) 最小复现：编译调用 vhangup() 的最小 C 程序，观察声明警告与链接失败；
+# 2) 核验 syscall 编号：grep SYS_vhangup $SYSROOT/.../bits/syscall.h
+# 3) 核验 libc 导出：nm -D $SYSROOT/.../libc.so | grep vhangup
+# 4) 仅当"无声明 + 无导出 + 内核 syscall 存在"时，才在 OHOS 条件启用 syscall shim。
+```
+
+## 回退方案
+
+**disable-vhangup-feature**：若 syscall 编号不存在或调用返回不支持/权限不足，移除或条件编译 vhangup 调用路径，
+保留失败并按上游/平台能力记录真实 errno/退出码。
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`return\s+0.*vhangup|伪造.*vhangup.*成功`
+- **原因**：不得伪造 vhangup 成功，应保留失败并按上游/平台能力记录真实 errno/退出码。
+- **后果**：真实 TTY/init/登录会话下的行为异常，难以排查。
+
+## 涉及软件
+
+在同一 SDK（ohos-sdk_26.0.0.18 / clang 15.0.4 / aarch64-unknown-linux-ohos）
+上调用 vhangup 或类似"libc 未导出但内核 syscall 存在"接口的库/工具（tty 挂断类、
+登录管理类）。
+
+## 相关模式
+
+- **相似模式**：[E121](E121.md)、[E014](E014.md)
+
+---
+*条目 E245 · 更新 2026-08-05 · 知识库同步生成物*

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

@@ -0,0 +1,92 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E246: HarmonyOS seccomp 拦截 Linux 私有 syscall（adjtimex 等），进程因 SIGSYS 终止
+
+> **严重度**: 🟡 medium | **分类**: compat, kernel, syscall, security | **自动修复**: ❌ | **原则**: [P004](../principles.md#P004)
+
+---
+
+## 错误特征
+
+```
+SIGSYS
+si_code.*SYS_SECCOMP
+si_syscall
+Signal 31
+exit 159
+adjtimex.*SIGSYS
+syscall 171
+seccomp blocked
+```
+
+## 根因
+
+HarmonyOS 沙箱/安全策略(seccomp 过滤器)直接拦截部分 Linux
+私有 syscall(如 adjtimex, aarch64 编号 171)。
+与 E051"未实现 syscall"不同: 被拦截调用通过 seccomp 返回
+SIGSYS, si_code=1(=SYS_SECCOMP), siginfo_t.si_syscall
+携带 syscall 号, 进程默认因 SIGSYS 终止(core dump, exit 159)。
+
+## 验证命令
+
+```bash
+adjtimex --print; echo "exit=$?"
+# 预期: Signal 31 (SIGSYS) core dumped
+# 或 C 程序: syscall(SYS_adjtimex, &tx) 触发 SIGSYS
+# siginfo_t: si_signo=31, si_code=1(SYS_SECCOMP), si_syscall=171
+```
+
+## 解决方案
+
+**graceful-degradation**：无应用层恢复手段(seccomp 策略不可被应用层修改)。
+适配策略: 检测 SIGSYS(可捕获时)后降级/跳过受限功能,
+或仅保留不触发受限 syscall 的功能子集。
+对 CLI 工具: smoke test 使用不触发受限 syscall 的路径
+(如 --version), 核心功能在鸿蒙上标记为不可用
+
+```bash
+# 信号处理中读取 si_syscall 判断:
+#   struct sigaction sa; sa.sa_sigaction = on_sigsys;
+#   sa.sa_flags = SA_SIGINFO; sigaction(SIGSYS, &sa, NULL);
+#   void on_sigsys(int sig, siginfo_t *si, void *uc) {
+#       printf("si_signo=%d si_code=%d syscall=%d\n",
+#              si->si_signo, si->si_code, si->si_syscall);
+#   }
+```
+
+## 回退方案
+
+**feature-subset**：仅保留不触发受限 syscall 的功能子集(如 --version),
+核心功能在 PR 正文与测试报告中如实标注不可用
+
+```bash
+# 对 adjtimex: smoke test 用 `adjtimex --version`(exit 0),
+# --print/调时功能标注"鸿蒙 seccomp 限制不可用"
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`在鸿蒙沙箱中依赖被拦截 syscall 完成核心功能且不做降级`
+- **原因**：seccomp 策略不可被应用层修改, 调用必然 SIGSYS 终止进程
+- **后果**：进程 core dump(exit 159), 工具完全不可用
+
+### 🚫 禁止 2
+
+- **模式**：`仅用 timeout 包裹绕过(如 timeout 10 adjtimex --print)`
+- **原因**：不解决根因, 进程仍被 SIGSYS 终止, 功能实际不可用
+- **后果**：smoke test 假通过, 核心功能静默不可用
+
+## 涉及软件
+
+所有调用 Linux 私有 syscall 且鸿蒙无等价安全许可的工具类库
+(时间调整、资源控制、命名空间等), 如 adjtimex、ntp 客户端、
+部分系统管理工具
+
+## 相关模式
+
+- **相似模式**：[E051](E051.md)、[E164](E164.md)
+
+---
+*条目 E246 · 更新 2026-08-04 · 知识库同步生成物*

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

@@ -0,0 +1,62 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E247: Static C API archive omits its C++ runtime from pkg-config metadata
+
+> **严重度**: 🟡 medium | **分类**: linking, pkg-config, static-library, api | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+undefined symbol: std::__n1
+undefined symbol: operator new
+undefined symbol: __cxa_begin_catch
+```
+
+## 根因
+
+A static archive contains C++ implementation objects behind a C API, but its installed pkg-config Libs.private field omits the C++ runtime, so pure C consumers use the C linker without required ABI libraries.
+
+## 验证命令
+
+```bash
+pkg-config --static --libs ${PACKAGE} && build and run an unchanged pure C consumer
+```
+
+## 解决方案
+
+**propagate-static-cxx-runtime-in-pkg-config**：Add the selected C++ runtime and other private system libraries to the installed .pc Libs.private field for static packages, while keeping Conan cpp_info.system_libs consistent.
+
+```bash
+validate pkg-config --static output, then compile and run a C consumer without manual C++ flags
+```
+
+## 回退方案
+
+**configure-upstream-pkg-config-generation**：If the upstream build exposes a supported input for private pkg-config libraries, pass the selected C++ runtime there so the generated build-tree and installed metadata agree without package-time rewriting.
+
+```bash
+configure the upstream private-library list and verify the generated .pc before installation
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`LINKER_LANGUAGE CXX|rename .*\.c .*\.cpp|manual .*\-lc\+\+`
+- **原因**：Changing the consumer linker language or injecting flags only in the test masks the installed package metadata defect.
+- **后果**：Real C pkg-config consumers continue to fail even though the package test passes.
+
+### 🚫 禁止 2
+
+- **模式**：`cpp_info\.system_libs.*only|Conan metadata only`
+- **原因**：Conan-generated metadata does not repair an upstream pkg-config file installed by the package.
+- **后果**：Conan CMake consumers may pass while direct pkg-config consumers still fail.
+
+## 涉及软件
+
+C/C++ libraries that expose a C API, compile C++ objects into a static archive, and install pkg-config metadata for downstream C consumers.
+
+---
+*条目 E247 · 更新 2026-08-01 · 知识库同步生成物*

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

@@ -0,0 +1,63 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E248: patch 致 Makefile.in mtime 早于 Makefile.am，无 automake 时触发重生成崩溃
+
+> **严重度**: 🟡 medium | **分类**: build-system, autotools, patch, timestamp | **自动修复**: ❌ | **原则**: [P010](../principles.md#P010)、[P014](../principles.md#P014)
+
+---
+
+## 错误特征
+
+```
+automake-1\.[0-9]+: command not found
+WARNING.*automake.*is missing on your system
+Makefile:.*Makefile\.in\].*Error 127
+cd.*&&.*missing automake
+```
+
+## 根因
+
+当 Conan 的 apply_conandata_patches 按 patch 文件内 hunk 顺序应用时，若 Makefile.am 的 hunk 排在 Makefile.in 之后，应用后 Makefile.am 的 mtime 会晚于 Makefile.in。GNU make 的标准依赖规则 Makefile.in: Makefile.am $(am__configure_deps) 据此判定 Makefile.in 过期，调用 build-aux/missing automake-1.16 重生成；而鸿蒙 PC 的 /data/service/hnp/bin 仅有 autoconf 系列而无 automake/aclocal，重生成以 exit 127 失败，连带 make all / make check 崩溃。这与"automake 版本不匹配"(E041/E071)或"编译 automake 自身的循环依赖"(E069)不同：本条是普通 autotools 库在 patch 触及 Makefile.am/Makefile.in 时的 mtime 倒挂问题，设备根本不提供 automake。
+
+## 验证命令
+
+```bash
+ls /data/service/hnp/bin/ | grep -E "automake|aclocal"; 确认无输出；在 recipe build() apply_conandata_patches 后 stat -c "%Y %n" 源码 tests/Makefile.am tests/Makefile.in，确认 .in 的 mtime < .am
+```
+
+## 解决方案
+
+**fix-mtime-after-patch**：在 conanfile.py 的 build() 方法中，apply_conandata_patches(self) 之后立即用 os.utime 把 Makefile.in 的 mtime 对齐到 Makefile.am（atime=mtime=Makefile.am 的 mtime_ns），掐断 make 的重生成触发条件。零新增依赖、不碰源码逻辑、不跑 autoreconf，符合"发行包构建不应要求完整 autotool 链"的成熟做法。
+
+```bash
+os.utime(makefile_in, ns=(os.stat(makefile_am).st_mtime_ns,)*2)
+```
+
+## 回退方案
+
+**reorder-patch-hunks**：调整 patch 文件内 hunk 顺序，让 Makefile.am 在前、Makefile.in 在后，使 apply 时 .in 晚写。但这依赖 patch_ng 严格按文件内顺序应用，且后续任何 patch 编辑都可能再次倒挂，较脆弱，不推荐单独使用。
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`brew install automake|apt.*automake|yum.*automake`
+- **原因**：为单个库安装 automake 扩大了配方对构建工具的依赖面，违反"发行包构建不应要求完整 autotool 链"；且主办方 CI 环境不一定有 automake，会让 PR 在官方 CI 失败。
+- **后果**：依赖面扩散，CI 可移植性下降。
+
+### 🚫 禁止 2
+
+- **模式**：`autoreconf|--force`
+- **原因**：在无 automake 的设备上跑 autoreconf 同样会 exit 127；且对发布 tarball 跑 autoreconf 会破坏上游冻结的生成物一致性。
+- **后果**：构建不可复现，生成物漂移。
+
+## 涉及软件
+
+任何 autotools 库的 conan recipe 用 conandata patch 修改 tests/Makefile.am（或 src/Makefile.am）及其对应已发布 Makefile.in，且目标设备无 automake 的场景。仓内 discount/2.2.7、libmemcached/1.0.18 等已有"patch 已发布 Makefile.in"的先例，但未沉淀该 mtime 副作用。
+
+## 相关模式
+
+- **相似模式**：[E069](E069.md)
+
+---
+*条目 E248 · 更新 2026-08-06 · 知识库同步生成物*

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

@@ -0,0 +1,52 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E249: 未初始化所有权标志导致清理函数释放调用者栈对象
+
+> **严重度**: 🔴 blocking | **分类**: memory | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Signal 11 \(core dumped\)
+exit_code=139
+AddressSanitizer: attempting free on address which was not malloc\(\)-ed
+```
+
+## 根因
+
+构造函数把调用者持有的对象指针交给子对象却未初始化 shared/owned 标志；清理函数读取不确定值并可能按独占所有权关闭后 free 该指针，造成 invalid free/SIGSEGV
+
+## 验证命令
+
+```bash
+用 ASan 运行触发子对象非空的官方输入，确认 bad-free 栈指向清理函数及调用者栈对象
+```
+
+## 解决方案
+
+**initialize-borrowed-ownership**：在构造共享子对象时明确设置 shared/borrowed 标志，并保持调用者作为唯一释放方；添加能走到该清理分支的确定性回归测试
+
+```bash
+track-edit add ${SOFTWARE} ${VERSION} ${SOURCE_FILE} && refresh-patch --auto ${SOFTWARE} ${VERSION}
+```
+
+## 回退方案
+
+**zero-initialize-owner-struct**：若 API 约定允许，先整体零初始化结构体，再对借用指针显式设置 shared 标志
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`跳过核心转换|只测试.*help|忽略.*SIGSEGV`
+- **原因**：帮助路径不会触发对象所有权清理，无法证明核心转换可用
+- **后果**：包构建通过但官方数据转换仍在退出阶段崩溃
+
+## 涉及软件
+
+C/C++ 中以 shared/owned 标志决定嵌套对象所有权、且子对象或所有权字段未零初始化的运行时转换工具
+
+---
+*条目 E249 · 更新 2026-07-13 · 知识库同步生成物*