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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-recipe-qt-app/scripts/qt6-to-qt5-downgrade-patterns.json

@@ -0,0 +1,407 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Qt6→Qt5 / OHOS Symbol Downgrade Database",
+  "description": "Symbols that need downgrade/replacement when porting Qt6 apps to OHOS (Qt 5.15.17). Script detects symbols; auto-replace fixes are inline; everything else references a fix_doc with detailed multi-strategy instructions.",
+  "version": "4.0.0",
+  "target_qt_version": "5.15.17",
+  "target_platform": "OHOS",
+  "symbols": [
+    {
+      "symbol": "QLatin1StringView",
+      "severity": "build-blocker",
+      "fix_type": "auto-replace",
+      "fix": { "replace_with": "QLatin1String" }
+    },
+    {
+      "symbol": "constexpr QLatin1StringView",
+      "pattern": "constexpr\\s+QLatin1StringView",
+      "severity": "build-blocker",
+      "fix_type": "auto-replace",
+      "fix": { "replace_with": "const QLatin1String" }
+    },
+    {
+      "symbol": "QByteArrayView",
+      "severity": "build-blocker",
+      "fix_type": "ai-architectural",
+      "fix_doc": "fixes/qbytearrayview.md"
+    },
+    {
+      "symbol": "QCalendar",
+      "severity": "build-blocker",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/qcalendar.md"
+    },
+    {
+      "symbol": "QStyleOptionTabV4",
+      "severity": "build-blocker",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/qstyleoptiontab.md"
+    },
+    {
+      "symbol": "QDataStream << enum",
+      "pattern": "QDataStream\\s*(&\\w+|\\*\\w+)?\\s*<<\\s*\\(\\s*\\w+\\s*::\\s*\\w+",
+      "severity": "build-blocker",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/qdatastream-enum.md"
+    },
+    {
+      "symbol": "QDockWidget",
+      "severity": "ohos-only",
+      "fix_type": "ai-architectural",
+      "fix_doc": "fixes/qdockwidget.md"
+    },
+    {
+      "symbol": "addDockWidget",
+      "pattern": "\\baddDockWidget\\s*\\(",
+      "severity": "ohos-only",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/qdockwidget.md"
+    },
+    {
+      "symbol": "dockWidgetsCount()",
+      "pattern": "\\bdockWidgetsCount\\s*\\(\\s*\\)",
+      "severity": "build-blocker",
+      "fix_type": "auto-replace",
+      "fix": { "replace_with": "count()" },
+      "fix_doc": "fixes/qdockwidget.md"
+    },
+    {
+      "symbol": "dockWidget(i)->widget()",
+      "pattern": "\\bdockWidget\\s*\\(\\s*\\w+\\s*\\)\\s*->\\s*widget\\s*\\(\\s*\\)",
+      "severity": "build-blocker",
+      "fix_type": "auto-replace",
+      "fix": { "replace_with": "widget(i)" },
+      "fix_doc": "fixes/qdockwidget.md"
+    },
+    {
+      "symbol": "setCentralWidget",
+      "severity": "ohos-only",
+      "fix_type": "ai-architectural",
+      "fix_doc": "fixes/qdockwidget.md"
+    },
+    {
+      "symbol": "SingleApplication",
+      "severity": "ohos-only",
+      "fix_type": "ai-architectural",
+      "fix_doc": "fixes/singleapplication.md"
+    },
+    {
+      "symbol": "isRunningAsAdmin",
+      "severity": "build-blocker",
+      "fix_type": "ai-stub",
+      "fix_doc": "fixes/singleapplication.md"
+    },
+    {
+      "symbol": "instanceStarted",
+      "pattern": "SingleApplication\\s*::\\s*instanceStarted",
+      "severity": "ohos-only",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/singleapplication.md"
+    },
+    {
+      "symbol": "receivedMessage",
+      "pattern": "SingleApplication\\s*::\\s*receivedMessage",
+      "severity": "ohos-only",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/singleapplication.md"
+    },
+    {
+      "symbol": "QFileOpenEvent",
+      "severity": "build-blocker",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/singleapplication.md"
+    },
+    {
+      "symbol": "find_package(Qt6",
+      "pattern": "find_package\\s*\\(\\s*Qt6\\b",
+      "severity": "build-blocker",
+      "fix_type": "ai-cmake",
+      "fix_doc": "fixes/cmake-qt6-to-qt5.md"
+    },
+    {
+      "symbol": "Qt6::",
+      "pattern": "\\bQt6::",
+      "severity": "build-blocker",
+      "fix_type": "auto-replace",
+      "fix": { "replace_with": "Qt5::" },
+      "fix_doc": "fixes/cmake-qt6-to-qt5.md"
+    },
+    {
+      "symbol": "qt_add_executable",
+      "severity": "build-blocker",
+      "fix_type": "ai-cmake",
+      "fix_doc": "fixes/cmake-qt6-to-qt5.md"
+    },
+    {
+      "symbol": "qt_standard_project_setup",
+      "severity": "build-blocker",
+      "fix_type": "ai-cmake",
+      "fix_doc": "fixes/cmake-qt6-to-qt5.md"
+    },
+    {
+      "symbol": "qt_add_translations",
+      "severity": "build-blocker",
+      "fix_type": "ai-cmake",
+      "fix_doc": "fixes/cmake-qt6-to-qt5.md"
+    },
+    {
+      "symbol": "Core5Compat",
+      "severity": "build-blocker",
+      "fix_type": "auto-replace",
+      "fix": { "replace_with": "" },
+      "fix_doc": "fixes/cmake-qt6-to-qt5.md"
+    },
+    {
+      "symbol": "[=, this]",
+      "pattern": "\\[=\\s*,\\s*this\\s*\\]",
+      "severity": "build-blocker",
+      "fix_type": "auto-replace",
+      "fix": { "replace_with": "[=]" },
+      "fix_doc": "fixes/lambda-capture-this.md"
+    },
+    {
+      "symbol": "QDesktopServices::openUrl",
+      "pattern": "QDesktopServices\\s*::\\s*openUrl",
+      "severity": "ohos-only",
+      "fix_type": "ai-architectural",
+      "fix_doc": "fixes/qdesktopservices.md"
+    },
+    {
+      "symbol": "QSystemTrayIcon",
+      "severity": "ohos-only",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/qsystemtrayicon.md"
+    },
+    {
+      "symbol": "moveToTrash",
+      "severity": "ohos-only",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/movetotrash.md"
+    },
+    {
+      "symbol": "closeEvent",
+      "pattern": "\\bcloseEvent\\s*\\(\\s*QCloseEvent",
+      "severity": "ohos-only",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/closeevent.md"
+    },
+    {
+      "symbol": "showFullScreen",
+      "pattern": "\\bshowFullScreen\\s*\\(\\s*\\)",
+      "severity": "ohos-only",
+      "fix_type": "ai-architectural",
+      "fix_doc": "fixes/showfullscreen.md"
+    },
+    {
+      "symbol": "QShortcut",
+      "pattern": "new\\s+QShortcut\\s*\\([^)]*,\\s*[^)]*,\\s*[^)]*,\\s*[^)]*",
+      "severity": "build-blocker",
+      "fix_type": "ai-architectural",
+      "fix_doc": "fixes/qshortcut.md"
+    },
+    {
+      "symbol": "EditorConfigAppDecorator",
+      "severity": "ohos-only",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/editorconfig.md"
+    },
+    {
+      "symbol": "QFontDatabase::addApplicationFont",
+      "pattern": "QFontDatabase\\s*::\\s*addApplicationFont",
+      "severity": "ohos-only",
+      "fix_type": "ai-architectural",
+      "fix_doc": "fixes/add-application-font.md"
+    },
+    {
+      "symbol": "appendPlainText",
+      "pattern": "->\\s*appendPlainText\\s*\\(",
+      "severity": "runtime",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/appendplaintext.md"
+    },
+    {
+      "symbol": "QVector",
+      "severity": "runtime",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/qvector-qlist.md"
+    },
+    {
+      "symbol": "scoped enum",
+      "pattern": "\\b(QEvent|QStyle|QSizePolicy|Qt::AlignmentFlag|Qt::Orientation|Qt::DockWidgetArea|Qt::ToolBarArea|Qt::WindowType|Qt::ItemFlag|Qt::MatchFlag|Qt::ConnectionType|Qt::Key|Qt::KeyboardModifier|Qt::DropAction|Qt::ItemDataRole|Qt::CheckState|Qt::SortOrder|Qt::LayoutDirection|Qt::TextFlag|Qt::TextElideMode|Qt::ClipOperation|Qt::FillRule|Qt::PenStyle|Qt::BrushStyle|Qt::GlobalColor|Qt::WidgetAttribute|Qt::ApplicationAttribute|Qt::WindowState|Qt::FocusPolicy|Qt::ContextMenuPolicy|Qt::ScrollBarPolicy|Qt::SizePolicy|Qt::CursorShape)\\s*::\\s*[A-Z]\\w+\\s*::\\s*[A-Z]",
+      "severity": "runtime",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/enum-typing.md"
+    },
+    {
+      "symbol": "add_executable(",
+      "pattern": "\\badd_executable\\s*\\(",
+      "severity": "build-blocker",
+      "fix_type": "ai-cmake",
+      "fix_doc": "fixes/add-library-shared.md"
+    },
+    {
+      "symbol": "LEXILLA_STATIC",
+      "severity": "build-blocker",
+      "fix_type": "ai-cmake",
+      "fix_doc": "fixes/lexilla-static.md"
+    },
+    {
+      "symbol": "OhExtras",
+      "severity": "build-blocker",
+      "fix_type": "ai-cmake",
+      "fix_doc": "fixes/ohextras.md"
+    },
+    {
+      "symbol": "CMAKE_CXX_STANDARD 20",
+      "pattern": "CMAKE_CXX_STANDARD\\s*(20|2[1-9])|set\\s*\\(\\s*CMAKE_CXX_STANDARD\\s+(20|2[1-9])",
+      "severity": "build-blocker",
+      "fix_type": "ai-cmake",
+      "fix_doc": "fixes/cpp17-standard.md"
+    },
+    {
+      "symbol": "CPMAddPackage(",
+      "pattern": "\\bCPMAddPackage\\s*\\(",
+      "severity": "build-blocker",
+      "fix_type": "ai-cmake",
+      "fix_doc": "fixes/cpm-exclusion.md"
+    },
+    {
+      "symbol": "AUTOMOC",
+      "severity": "build-blocker",
+      "fix_type": "ai-cmake",
+      "fix_doc": "fixes/automoc-manual.md"
+    },
+    {
+      "symbol": "Packaging.cmake",
+      "pattern": "include\\s*\\(\\s*[^)]*Packaging[^)]*\\)",
+      "severity": "build-blocker",
+      "fix_type": "ai-cmake",
+      "fix_doc": "fixes/packaging-cmake.md"
+    },
+    {
+      "symbol": "WIN32 AND NOT OHOS",
+      "pattern": "if\\s*\\(\\s*WIN32\\s*\\)",
+      "severity": "build-blocker",
+      "fix_type": "ai-cmake",
+      "fix_doc": "fixes/win32-not-ohos.md"
+    },
+    {
+      "symbol": "cxx_std_17",
+      "pattern": "\\btarget_compile_features\\b",
+      "severity": "build-blocker",
+      "fix_type": "ai-cmake",
+      "fix_doc": "fixes/target-cxx17.md"
+    },
+    {
+      "symbol": "REMOVE_ITEM",
+      "pattern": "\\blist\\s*\\(\\s*REMOVE_ITEM\\b",
+      "severity": "ohos-only",
+      "fix_type": "ai-cmake",
+      "fix_doc": "fixes/remove-item-sources.md"
+    },
+    {
+      "symbol": "qWarning()/qInfo()/qDebug() without QDebug include",
+      "pattern": "\\bq(WARNING|INFO|DEBUG|Warning|Info|Debug|warning|info|debug)\\s*\\(\\s*\\)",
+      "severity": "build-blocker",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/qdebug-include.md"
+    },
+    {
+      "symbol": "constexpr QLatin1String",
+      "pattern": "constexpr\\s+QLatin1String\\s+\\w+",
+      "severity": "build-blocker",
+      "fix_type": "auto-replace",
+      "fix": { "replace_with": "QLatin1String" },
+      "note": "OHOS musl strlen is not constexpr; remove constexpr qualifier",
+      "fix_doc": "fixes/constexpr-qlatin1string.md"
+    },
+    {
+      "symbol": "QUrl used without include",
+      "pattern": "\\bQUrl\\s+\\w+\\s*[=;(]|\\bQUrl\\s*\\(\\s*[^)]*\\)",
+      "severity": "build-blocker",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/qdebug-include.md",
+      "note": "Qt6 transitively includes <QUrl> via QApplication/QGuiApplication, Qt5 does not. Add #include <QUrl> under #ifdef __OHOS__. See Strategy B."
+    },
+    {
+      "symbol": "QCloseEvent used without include",
+      "pattern": "\\bQCloseEvent\\s*\\*|\\bcloseEvent\\s*\\(\\s*QCloseEvent",
+      "severity": "build-blocker",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/qdebug-include.md",
+      "note": "Qt6 transitively includes <QCloseEvent> via QWidget, Qt5 only forward-declares it. Add #include <QCloseEvent> under #ifdef __OHOS__ when accessing event->accept()/ignore()"
+    },
+    {
+      "symbol": "QKeyEvent used without include",
+      "pattern": "\\bQKeyEvent\\s*\\*|\\bkeyPressEvent\\s*\\(\\s*QKeyEvent|\\bkeyReleaseEvent\\s*\\(\\s*QKeyEvent",
+      "severity": "build-blocker",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/qdebug-include.md",
+      "note": "Qt6 transitively includes <QKeyEvent> via QWidget, Qt5 only forward-declares it. Add #include <QKeyEvent> under #ifdef __OHOS__"
+    },
+    {
+      "symbol": "QMouseEvent used without include",
+      "pattern": "\\bQMouseEvent\\s*\\*|\\bmousePressEvent\\s*\\(\\s*QMouseEvent|\\bmouseReleaseEvent\\s*\\(\\s*QMouseEvent|\\bmouseMoveEvent\\s*\\(\\s*QMouseEvent",
+      "severity": "build-blocker",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/qdebug-include.md",
+      "note": "Qt6 transitively includes <QMouseEvent> via QWidget, Qt5 only forward-declares it. Add #include <QMouseEvent> under #ifdef __OHOS__"
+    },
+    {
+      "symbol": "QList::remove(row, count) - Qt6 only",
+      "pattern": "\\.remove\\s*\\(\\s*\\w+\\s*,\\s*\\w+\\s*\\)",
+      "severity": "build-blocker",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/qvector-qlist.md",
+      "note": "QList::remove(row, count) is Qt6-only (added after QVector/QList merge). In Qt5, use erase(begin()+row, begin()+row+count). See Strategy F."
+    },
+    {
+      "symbol": "QMap used with forward declaration only",
+      "pattern": "\\bQMap\\s*<",
+      "severity": "build-blocker",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/qmap-forward-decl.md",
+      "note": "Qt6 allows QMap<T,U> with only a forward declaration of T or U in a header, because template instantiation is deferred. Qt5 eagerly instantiates QMap internals (especially when used with Q_DECLARE_METATYPE or as a signal parameter), causing 'implicit instantiation of undefined template' errors. Fix: add #include <QMap> and ensure value types are fully defined (not just forward-declared) before the QMap usage."
+    },
+    {
+      "symbol": "QSet used with forward declaration only",
+      "pattern": "\\bQSet\\s*<",
+      "severity": "build-blocker",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/qmap-forward-decl.md",
+      "note": "Same as QMap: Qt5 QSet<T> with only a forward-declared T causes instantiation errors. Ensure T is fully defined. The fix_doc for QMap covers both QMap and QSet."
+    },
+    {
+      "symbol": "QList<T>(int) constructor",
+      "pattern": "QList\\s*<[^>]+>\\s*\\(\\s*\\w+\\s*\\)",
+      "severity": "build-blocker",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/qlist-int-constructor.md",
+      "note": "QList<T>(int count) constructor does not exist in Qt5. It was added in Qt6 after QVector/QList merge. In Qt5, create an empty QList and append/count elements in a loop, or use QList<T>() << val << val << ... for small lists."
+    },
+    {
+      "symbol": "QTranslator::load with missing .qm",
+      "pattern": "QTranslator\\s*::\\s*load\\s*\\(|->\\s*load\\s*\\(",
+      "severity": "runtime",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/qtranslator-missing-qm.md",
+      "note": "When LinguistTools is skipped in OHOS cross-compile, .qm translation files are not generated. QTranslator::load() will fail at runtime, often causing an error dialog. Fix: under #ifdef __OHOS__, either skip translation loading and fall back to English, or generate empty .qm files and deploy them with the HAP."
+    },
+    {
+      "symbol": "moc-excluded-source-only",
+      "pattern": "list\\s*\\(\\s*FILTER\\s+\\w+\\s+EXCLUDE\\s+REGEX\\s+\".*\\\\.cpp",
+      "severity": "build-blocker",
+      "fix_type": "ai-cmake",
+      "fix_doc": "fixes/moc-exclude-sync.md",
+      "note": "When excluding .cpp files from a CMake target via list(FILTER ... EXCLUDE REGEX ...cpp), the corresponding .h files must also be excluded from the headers list. Otherwise, AUTOMOC generates moc code for the .h, referencing symbols defined in the excluded .cpp, causing linker errors (undefined vtable, undefined destructor, etc.)."
+    },
+    {
+      "symbol": "Q_DECLARE_METATYPE with incomplete type",
+      "pattern": "Q_DECLARE_METATYPE\\s*\\(",
+      "severity": "build-blocker",
+      "fix_type": "ai-guard",
+      "fix_doc": "fixes/qdeclare-metatype-incomplete.md",
+      "note": "Q_DECLARE_METATYPE(T) requires T to be fully defined at the point of declaration in Qt5. If T is only forward-declared, Qt5's connect() template deduction chain fails with 'cannot initialize a parameter of type const QObject* with an lvalue of type const typename QtPrivate::FunctionPointer<...>::Object*'. Fix: move Q_DECLARE_METATYPE after the full class definition, or add the missing #include."
+    }
+  ]
+}

package/node_modules/@ohos-agent/pc-adapter/skills/pc-registry/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: pc-registry
+description: 依赖复用判定与已适配制品获取:本地个人登记(须验真)优先 → 中心制品仓(端点权威见 references/central-registry.md)次之 → 未命中现场适配。触发词:已适配库、依赖复用、registry、登记、中心仓、制品库、harmony_adapted、adapted-libs。
+---
+
+# pc-registry:依赖复用判定与制品获取
+
+## 判定顺序(scan 阶段,对 native 类闭包节点)
+
+1. **个人登记 + 验真(优先级第一)**:读个人库 `<知识库根>/registry/<ecosystem>.json`
+   - 命中、条目带 `artifact_path`、且产物**真实存在**才算数:
+     ```bash
+     test -n "$(ls -A "<知识库根>/<artifact_path>" 2>/dev/null)" && echo local-hit
+     ```
+   - 验真通过 → 节点 `status=reuse`、`reuse_source=local-registry`、`harmony_adapted=true`
+   - 登记在但产物缺失/无 `artifact_path` → **视同未命中**(status=partial 的条目同理只作参考),`meta.warnings` 记一条「登记失效:<name>」
+2. **中心制品仓探测**:按 `references/central-registry.md` 的探测判读表打端点(⚠️ HTTP 200 ≠ 命中,必须按表判读内容,阴性结论先跑阳性对照)
+   - hit → `status=reuse`、`reuse_source=central-registry`、`harmony_adapted=true`,并写 `central_artifact{status,url,available_version}`
+   - 有包但精确 pin 版本缺 → `central_artifact.status=version-mismatch`,status 按原生性现状规则
+   - 不可达/超时 → 视同 miss,降级规则见 central-registry.md(一条 warning、同域短路、不阻塞)
+3. 均未命中 → fresh-adapt / recipe-build(原生性分层现状规则)
+
+知识库根:环境变量 `PC_ADAPT_KNOWLEDGE_ROOT`;未设置时默认 `~/.local/share/ohos-agent-pc-adapter/knowledge`(Windows:`C:\Users\<username>\.local\share\ohos-agent-pc-adapter\knowledge`)。
+
+## 获取顺序(adapt 阶段)
+
+1. 同轮已编:`deps/<dep>/dist/`(本工作区)
+2. 个人库产物拷回:`cp -R "<知识库根>/<artifact_path>/." deps/<dep>/dist/`
+3. 中心仓拉取:安装/构建配置见 `references/central-registry.md`
+4. 自编(recipe 现状流程)
+
+逐级失败降级,并在 03-adapt.json 的 deps_built[].notes 记明实际来源。
+
+## 制品树对账(防清单盲区)
+
+**「制品树里有」≠「登记了」**——下游按声明取用,清单外文件在流程上等于不存在。
+
+- **登记/物化侧**:制品树含 `registry-staging.json` 时,其 `key_artifacts` **必须覆盖全部可交付
+  文件**——`bin/` 下可执行物、`lib/pkgconfig/` 一并声明。只声明库文件的清单对 CLI 型库
+  (libidn2/idn2、libpsl/psl、libcurl/curl 同构)必然制造盲区:libidn2 实证——staging 树里
+  40KB 的 `idn2` CLI(aarch64 musl PIE、与真跑全过的测试 ELF 同构)因未进 key_artifacts,
+  下一轮判「CLI 无法获得、不可解」误停 partial。`ohpt knowledge -p` 与 hook 自动登记时
+  会对账并**告警未声明的 ELF 可执行物**。
+- **消费侧**:判「某组件无法编译/无法获得」写进 remaining_blockers 之前,**递归 ls 登记产物
+  树的完整目录**(`<知识库根>/<artifact_path>/`,不只读登记 json 与 key_artifacts)——发现
+  未声明可执行物先真机验真(cli-hnp-runner 装机跑通即合法制品,soname 别名按 E131),再下结论。
+- **登记即配方**:成功轮次的构建方法(树内/树外、make 还是直链、绕行点)必须随 memory 候选
+  沉淀——「编不出」的误判多半源于上一轮成功配方零留痕(libidn2 两轮间隔 12 天,第二轮对
+  第一轮同机成功一无所知,重走弯路后误判宿主不可构建)。
+
+## 修复失效律(防制品固化缺陷)
+
+**本轮的源码补丁使已登记的复用制品过期**——补丁打在源码上,对已编译的制品无效。
+- **判定**:主库在 `deps_built[]` 里是 `status=reuse`(拷回个人库制品)而本轮
+  `patches_applied[]` 非空 → 复用必错:制品不含修复,对应 FAIL 原样复现(验收规则
+  `reuse-patch-conflict` 机器执法)。libbsd 9/9 实证:reuse 9/1 旧制品 → closefrom/funopen
+  FAIL 复现 → partial → 不满足自动入库条件(success+独立验收背书)→ 制品库永不更新——
+  **负循环:reuse 固化缺陷,缺陷阻止制品更新**。
+- **破法(修复轮不走 reuse)**:对本库降级 fresh-adapt 自编(源码+patches → 新产物),收敛
+  built-and-verified 后由 04 收尾自动 `promoteRegistry` 物化**覆盖**个人库同 `artifact_path`
+  ——之后任何干净工作区 reuse 拿到的才是含修复的版本。制品级修复必须先于下次重跑完成入库,
+  时序不可颠倒(scan 的复用判定只看库里实物)。
+
+## 个人登记数据格式
+
+`<知识库根>/registry/<ecosystem>.json`:
+
+```json
+{
+  "<lib-name>": {
+    "status": "adapted",
+    "version": "3.0.0",
+    "artifact_path": "artifacts/nodejs/classic-level/3.0.0",
+    "reference_url": null
+  }
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| status | `adapted`=已成功适配;`partial`=部分适配(仅参考,不 reuse) |
+| version | 适配时的库版本;依赖声明与之不符时按 partial 对待 |
+| artifact_path | **个人库根内相对路径**,指向 promote 时物化拷贝的产物;无此字段或目录为空 = 该登记不参与 reuse 判定 |
+| reference_url | 参考方案链接,可为 null |
+
+登记入库两轨(agent 都不手写登记文件):**success + 独立验收背书**的轮次由 PostWrite hook 在 04-summary 落盘时**自动**登记并物化产物(机器背书);其余(历史工作区/partial/无背书)由用户 `ohpt knowledge -p [--registry-only]` 手动共享(用户背书)。
+
+## 中心制品仓
+
+端点总表、探测判读命令、安装配置、降级规则的**唯一权威** → `references/central-registry.md`。其他 skill/agent 只引用本 skill,不复制端点细节。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-registry/references/central-registry.md

@@ -0,0 +1,142 @@
+# 中心制品仓(nodejs=@ohos-ports;其余生态=cnb.cool/OpenHarmonyPCDeveloper)
+
+**nodejs 生态**:已鸿蒙化的 npm 包统一发布在 npm registry 的 `@ohos-ports` scope——查询页 `https://ohos-ports.github.io/ohos-ports/`(数据源为 npm Registry API),探测/安装直接走宿主机 npm。本插件**只拉取,不回传**;适配产物发布上中心仓是社区侧运营流程,不在插件职责内。
+
+**其余生态(C/C++/Python/Rust/Java)**:CNB 组织制品库,列表 `https://cnb.cool/OpenHarmonyPCDeveloper/-/registries`。公开制品库**匿名可拉、无需登录**(CNB 平台语义:公开库「任何人都可以拉取,无需登录鉴权」)。本插件只拉取,不回传;发布是组织侧运营流程。
+
+端点模式(非 nodejs):`https://<type>.cnb.cool/OpenHarmonyPCDeveloper/<库名>/-/packages/...`
+
+## 生态端点总表
+
+| 生态 | 制品库 | base URL | 规模(2026-07) |
+|------|--------|----------|----------------|
+| nodejs | @ohos-ports(npm registry scope) | 查询页 `https://ohos-ports.github.io/ohos-ports/`;探测走 `npm view @ohos-ports/<pkg>`(registry.npmjs.org) | 持续扩充(sqlite3/better-sqlite3/sharp 等原生扩展) |
+| python | PyPI | `https://pypi.cnb.cool/OpenHarmonyPCDeveloper/pypi/-/packages/simple/` | 375 包(ohos_aarch64 wheel) |
+| cpp | Conan | `https://conan.cnb.cool/OpenHarmonyPCDeveloper/Conan/-/packages/` | 120 包(C/C++ 库 + CLI bin 工具) |
+| rust | Cargo | `sparse+https://cargo.cnb.cool/OpenHarmonyPCDeveloper/Cargo/-/packages/` | hilog 等鸿蒙 crate |
+| java | Maven | `https://maven.cnb.cool/OpenHarmonyPCDeveloper/Maven/-/packages/` | 构件清单以 Web 页为准 |
+
+> ohpm:CNB 平台支持 ohpm 类型制品库(`ohpm.cnb.cool`),该组织暂未建库——扩展位,建库后在本表加一行即可。
+
+## 探测与判读(scan 阶段用)
+
+⚠️ **铁律:HTTP 200 ≠ 有适配版**。nodejs 的命中对象是 `@ohos-ports/<pkg>` scope 包(不存在 → npm E404,退出码 1),但**版本号要判读**(`-beta.*` 后缀是正常适配版);cargo index 对任意路径都 200(catch-all)——必须按下表**判读内容**。每个「无命中」结论,先拿本表的已知阳性包跑同一命令做对照,对照非空才可信。
+
+⚠️ **补充铁律:404 ≠ 永久无此包（IfcOpenShell 实证,2026-09）**。pypi 仓**非代理**、404 语义是「当前无此包」,但**镜像同步/网络状态有时效性**——numpy-2.2.6/shapely-2.1.2 的 ohos_aarch64 wheel 前轮探测 404 被记为不可得,本轮重新探测**同一资源恢复可达**并成功装机。跨轮次判定「中心仓不可得」并准备转向替代路线(从设备提取、源码自产 wheel、pip install 源码编译)之前,**必须先跨轮/跨时段重探测一轮**;阶段内同一轮的重探测无意义(短时抖动),要隔开足够时间。为已就绪的制品白做替代路线是真实发生过浪费。
+
+统一超时 `--max-time 10`;`curl -fsS` 退出码:0=响应正常、22=HTTP 4xx(无此包)、其他=网络不可达(走降级规则)。
+
+| 生态 | 探测命令 | hit 判据 | 已知阳性对照 |
+|------|----------|----------|---------------|
+| nodejs | `npm view @ohos-ports/<pkg> versions --json`(无此包 → npm E404,退出码 1;走宿主机 npm 配置/代理) | 退出码 0 且 `versions[]` 非空(= 有适配版)。`-beta.*` 后缀是正常适配版形态,照常命中;安装时显式指定该版本 | `@ohos-ports/sqlite3` → `5.1.7-beta.0`;`@ohos-ports/better-sqlite3` → `13.0.3` |
+| python | `curl -fsS <base>/<规范名小写>/ \| grep -c 'ohos_aarch64'` | HTTP 200(非代理,404=无此包)且计数 >0(有 ohos wheel);200 但计数 0 = 仅源码/通用包,按 partial 参考 | `frozenlist` → 1 |
+| cpp | `curl -fsS "<base>/v2/conans/search?q=<name>*"`(通配符 `*` 必带——精确名查询恒返回空 results,是索引语义不是无包) | `results[]` 非空,且**版本列表直接可见**;按名+版精确探测用 `GET <base>/v2/conans/<name>/<version>/_/_/revisions` → 200/404 | `pcre2*` → `["pcre2/10.40","pcre2/10.45"]` |
+| rust | `curl -fsS <base>/<index路径> \| head -1 \| python3 -c "import json,sys;d=json.loads(sys.stdin.readline());print(d['name'],d['vers'])"` | 能解析出有效 index 行(**200 不可信**,假名也 200 但解析失败) | `hi/lo/hilog` → `hilog 0.1.0` |
+| java | `curl -fsSL <base>/<group路径>/<artifact>/maven-metadata.xml` | 200 且含 `<version>`;groupId 以组织 Web 页构件清单为准 | 仓当前为空(2026-07),暂无阳性对照——java 探测「无命中」结论在拿到已知构件坐标做对照前不可全信 |
+
+cargo sparse index 路径规则:1 字母 crate → `1/<name>`;2 字母 → `2/<name>`;3 字母 → `3/<首字母>/<name>`;≥4 字母 → `<前两字母>/<第3-4字母>/<name>`。
+
+## 版本判读
+
+- 探测只判「存在 + 可用版本列表」。依赖声明是 range(如 `^1.2`)且中心仓任一版本满足 → `hit`;精确 pin 且中心仓缺该版本 → `version-mismatch`(把中心仓最近版本记进 `available_version`,是否可用交 adapt 阶段判断)。
+- conan 的通配 search 一步返回 `name/version` 全列表(如 `pcre2*` → 10.40/10.45),版本判读无需二次探测;npm 看 packument 的 versions/dist-tags;pypi 看 simple 页 wheel 文件名。
+- nodejs 适配版是 `@ohos-ports` scope 下的独立包——包名与上游同名(如 `@ohos-ports/sqlite3` ↔ `sqlite3`),版本号多镜像上游并带 `-beta.*` 后缀(如 sqlite3 5.1.7 → 5.1.7-beta.0),也有与上游同号的稳定版(如 better-sqlite3 13.0.3)。**安装时显式指定适配版**(npm alias 保持 require 名不变),装裸包名会拿到上游未适配版。
+
+## 依赖树验证：hit ≠ 可安装（某图像库 实证，2026-09）
+
+**⚠️ 中心仓命中（hit）只证明「这个包在仓里有」，不证明「装得上」**。conan 生态尤其如此：
+单包 search 命中后，实际 `conan install` 还要解析**整棵依赖树**，不同可选库可能要求同一
+依赖的不同版本而互斥。
+
+**实证**：某图像库 适配时 libpng 依赖 zlib/1.3.2、libtiff 依赖 zlib/1.3.1.1，两库 search 均
+hit，但无法同时安装 → libpng/libjpeg/libtiff/fftw/libcurl 全部 skipped，仅保留 zlib/1.3.1.1。
+
+**规则**：
+1. scan/adapt 判定 conan 复用命中后，加一步 `conan graph info`（或 `conan install --dry-run`）
+   验证依赖树可解析——把冲突暴露在阶段 1/2（用例设计之前），而非阶段 3 构建期。
+2. 冲突依赖的库若为**可选依赖**（find_package 非 REQUIRED），跳过并**同步裁剪对应验证用例**
+   （某图像库用例全用 BMP 原生 I/O），避免断言不存在的功能。
+3. 若为必选依赖：`override` 统一版本（如 `conan install ... -o zlib/*:shared=False` 或
+   `conf` 覆盖）或现场编译该依赖。
+
+### CONAN_HOME 纪律：必须指向工作区内
+
+跑 conan 客户端命令前，先把 `CONAN_HOME` 指到 `<workspace>/.ohos-adaptation-pc/conan-home/`。
+**禁用默认 `~/.conan2`**：它在工作区外，触发权限层自动拒绝并杀死 task；
+工作区级 home 同时避免污染全局环境。
+
+## 已验证可用制品清单（生产实证）
+
+> 探测判读回答「在不在」，本清单回答「用起来行不行」——下列制品经**交叉编译链接 + 设备装机 + import/运行冒烟**三重验证（IfcOpenShell 0.9.0 BIM 几何栈适配，2026-09）。命中同类需求时可直接按版本取用，版本仅供参考（仓内可能已有更新）。
+
+### Conan（C++ 几何/基础栈 + CPython 运行时）
+
+| 包/版本 | 内容要点 | 用途 |
+|---------|----------|------|
+| `opencascade/7.9.2` | 47 个 `TK*.so`（全模块共享库） | CAD/几何内核 |
+| `cgal/6.2` | 含 `libgmp.a`/`libmpfr.a` 静态库——**高模板库不必再自编 GMP/MPFR** | 计算几何；GMP/MPFR 依赖直取 |
+| `boost/1.90.0` | 全量（含 `boost/python`） | C++ 基础库 |
+| `libxml2/2.15.3`、`eigen/3.4.0`、`nlohmann_json/3.12.0` | nlohmann_json 为 header-only | 常规依赖 |
+| **`python/3.12.9`** | **完整 OHOS aarch64 CPython 运行时**：`bin/python3.12` + `libpython3.12.so` + `include/python3.12/Python.h` + 全标准库 | **Python native-extension 的运行时供给来源**——无设备/离线编译时当 `PYINC`/`PYLIB` 用（SWIG/Cython 扩展链接 `-lpython3.12`），也可整包随 HNP 装机 |
+
+### PyPI（ohos_aarch64 wheel）
+
+| 包/版本 | 要点 |
+|---------|------|
+| `numpy-2.2.6` | `cp312-cp312-ohos_aarch64` wheel，`.so` 带 `.codesign` 段 |
+| `shapely-2.1.2` | 同上（几何运算，依赖 libgeos 已在 wheel 内） |
+| `pytest-8.4.2` 全家桶 | iniconfig/pluggy/packaging/`psutil-6.0.0`（psutil 含 `.codesign` `.so`）——**设备侧跑测试套件的依赖底座** |
+
+## 安装/构建配置(adapt 阶段用)
+
+### nodejs(@ohos-ports scope:npm alias 保持 require 名不变)
+
+```bash
+# npm alias:依赖名不变,指向 @ohos-ports 的适配版(版本显式指定)
+npm install sqlite3@npm:@ohos-ports/sqlite3@5.1.7-beta.0
+# 或直接写进 package.json:
+#   "dependencies": { "sqlite3": "npm:@ohos-ports/sqlite3@^5.1.7-beta.0" }
+# 查询已入库的适配包:https://ohos-ports.github.io/ohos-ports/
+```
+
+### python(非代理:仓内只有已适配包,官方源兜底)
+
+```bash
+pip3 install <pkg> \
+  --index-url https://pypi.cnb.cool/OpenHarmonyPCDeveloper/pypi/-/packages/simple \
+  --extra-index-url https://pypi.org/simple
+```
+
+备选社区源(网络受限时替换 index-url):`https://artifacts-cn-beijing.volces.com/repository/pypi.ohpcd/simple`(火山引擎镜像,非官方,`--trusted-host artifacts-cn-beijing.volces.com`)。
+
+### cpp / Conan（Conan 2.x 直接可用,已实测）
+
+```bash
+conan remote add ohpcd https://conan.cnb.cool/OpenHarmonyPCDeveloper/Conan/-/packages/ --index 0   # 优先级第一,miss 自然落 conancenter
+conan list "<name>/*" -r ohpcd   # 匿名即可。实测(conan 2.29):Connecting anonymously → Found 2 recipes(pcre2/10.40、10.45)
+```
+
+服务端为 Conan 2 协议:握手端点 `v1/ping` 返回 200 且带 `x-conan-server-capabilities: revisions`(Conan 2 必需能力),CNB 官方文档亦明示主要支持 2.x。公开库拉取匿名;conan 1.x 的限制仅在**推送**侧(需 `CONAN_REVISIONS_ENABLED`),与拉取无关。Web 页人工查包:`https://cnb.cool/OpenHarmonyPCDeveloper/Conan`。
+
+### rust / Cargo
+
+```toml
+# ~/.cargo/config.toml
+[registries.ohpcd]
+index = "sparse+https://cargo.cnb.cool/OpenHarmonyPCDeveloper/Cargo/-/packages/"
+```
+
+按包使用:`cargo add <crate> --registry ohpcd`。**不做全局 replace-with**(index 是 catch-all,整体代理行为未完全确认)。
+⚠️ `config.json` 声明 `auth-required: true`:index 文件匿名可读已实测;若 cargo 客户端索要凭据,配 CNB 访问令牌(scope: registry-package 读)。
+
+### java / Maven
+
+pom.xml / settings.xml 追加 `<repository>`（URL 用上表 base,多仓声明天然 fallback;Gradle 在 repositories 加 `maven { url "<base>" }`）。构件 GET 走标准 maven layout：`<base>/<groupId按/拆分>/<artifactId>/<version>/<artifactId>-<version>.jar|pom`；base 根路径 302 跳 Web UI 属正常,不影响构件路径直连。
+
+> 现状（2026-07）：组织 Maven 仓 Web 页未见任何构件（疑为空仓）——java 依赖现阶段不会命中中心仓,判定自然走 fresh-adapt；构件发布后本配置即生效,无需改动。构件清单/groupId 以组织 Web 页为准（包清单 API `api.cnb.cool/<org>/<repo>/-/packages` 需 token,不接入判定流程,保持匿名原则）。
+
+## 降级规则(中心仓不可达时)
+
+- 单包探测超时/网络错(curl 退出码非 0 非 22;nodejs 的 npm view 非 E404 退出码)→ 该节点**视同未命中**,走现状 fresh-adapt/recipe-build。
+- 全 scan 只在 `meta.warnings` 记**一条**「中心制品仓不可达,复用判定仅剩本地登记」;同域后续探测直接短路跳过,不逐包重试。
+- 绝不因中心仓不可达阻塞流程、不降级 feasibility——离线行为与不存在中心仓时完全一致。