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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-schemas/references/schemas/verify-verdict.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Independent acceptance verdict on stage-3 device evidence",
+  "description": "pc-03-dev-verify 对 pc-03 捕获的真实设备证据出具的独立裁决。它是整条链上权威最高的产物——能推翻移植模型的自评（03-adapt.json 的 status、04-summary.json 的 adaptation_status 自报成功都要它背书，见 acceptance-checks 的 verify-verdict-required）。此前它是唯一没有 schema 的状态型产物，字段形状只靠 pc-03-dev-verify.md 的散文约束：verified 写成字符串 \"true\" 时，readVerifyVerdict 的严格 !==true 判不过、而下游查表按字符串键判通过——同一份坏输入两端结论相反。",
+  "type": "object",
+  "required": ["verified", "confidence", "diagnosis", "evidence_examined"],
+  "properties": {
+    "verified": {
+      "type": "boolean",
+      "description": "目标是否确凿在设备上达成。必须是 JSON 布尔——字符串 \"true\"/\"false\" 一律不合法"
+    },
+    "confidence": {
+      "type": "string",
+      "enum": ["high", "medium", "low"],
+      "description": "本次裁决的把握程度"
+    },
+    "diagnosis": {
+      "type": "string",
+      "minLength": 1,
+      "description": "verified=true 时写「据哪份证据认定达成」；false 时写不过原因 + 具体改哪（供 pc-03 续修）"
+    },
+    "evidence_examined": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1,
+      "description": "实际展开核对过的证据文件相对路径。零证据的裁决不成立——pc-03-dev-verify 的立场是「只依据 WORKSPACE 内的真实捕获文件」，证据不全就该判 false 并说明缺哪份"
+    },
+    "state_fingerprint": {
+      "type": "object",
+      "description": "**指纹链存档 2**（可选字段，旧 verdict 不拒收）：本次验收通过时对 tests-generated/ 全文件重算的 sha256（key=相对路径，value=sha256 hex）。与 02-baseline.tests_generated_hashes（存档 1）组成指纹链：每轮 verify 固定核对「当前指纹 == 上一份 verdict.state_fingerprint」，不一致 → 逐文件 diff——有 failures 条目 + fixed-test + amendment 覆盖 → 合法进 amendment 内容审查；无申报 → 静默改动实锤判 false（verify-testcode-fingerprint 执法）。02-baseline 有 tests_generated_hashes 而本字段缺失 = 红。",
+      "additionalProperties": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+    },
+    "what_to_fix": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "判不过时的可执行改法清单"
+    }
+  },
+  "allOf": [
+    {
+      "description": "诊断要可执行：判不过必须说清改哪，否则 pc-03 拿不到续修方向、有界修复环空转一轮。执法 pc-03-dev-verify.md 的「别只说『未验证』」",
+      "if": {
+        "required": ["verified"],
+        "properties": { "verified": { "const": false } }
+      },
+      "then": {
+        "required": ["what_to_fix"],
+        "properties": {
+          "what_to_fix": { "minItems": 1 }
+        }
+      }
+    }
+  ]
+}

package/node_modules/@ohos-agent/pc-adapter/skills/pc-schemas/references/semantics/adaptation-report-mapping.md

@@ -0,0 +1,80 @@
+# 适配点分析报告 → 阶段 1 产物映射（报告驱动模式）
+
+> **适用范围：仅 Electron 应用适配**（pc-01-analyze 的 Electron 路径）。
+> 前提：ohos-migration-analysis 已对目标 Electron 工程产出适配点分析报告，其运行目录
+> 被整体放入 `<workdir>/.ohos-adaptation-pc/adaptation-report/`（report.md + .data/）。
+> 报告在盘 ⇒ Phase 1 的盘点与改造点判定**直接从报告映射，不重扫源码**；报告缺失 ⇒ 回退
+> SKILL.md Phase 1 步骤 3 的 `ohpt-agent scan-electron` 常规扫描路径。
+
+## 输入与优先级
+
+- `report.md`：人读报告（类别一 API 差异表 / 类别二系统级差异 / 类别三 npm 依赖 / 工作量汇总）
+- `.data/findings*.json`：结构化数据层（status / tier / plan / evidence / apichecked），**存在时优先**
+- `.data/` 缺失 → 降级解析 `report.md` 表格，`01-scan.json` 的 `meta.warnings` 记
+  `report-md-only: .data 缺失，映射自 markdown 表格`
+- 只读输入：不修改 `adaptation-report/` 内任何文件
+
+## 逐维度映射（→ 01-scan.json）
+
+| 01-scan.json 字段 | 报告来源 | 映射规则 |
+|---|---|---|
+| `library` / `languages` / `build_system` | 报告概览 + package.json | 轻量读取工程清单（不算扫描） |
+| `api_dependencies.groups` | 类别一四表 | 不支持/不兼容/有差异 → `category=platform-specific`；需权限 → `system`。`apis[].name` 取 API 名、`purpose` 取「API功能」列、`evidence` 取「代码位置」列 file:line |
+| `harmony_adaptation.unadaptable_apis` | 类别一「无法适配」行 | api/reason/evidence 直取 |
+| `capability_dependencies[]` | 类别二差异项（窗口模型/托盘/子进程/权限/快捷键） | 差异项 → 能力域 domain（窗口→graphical-window、托盘→tray、子进程→subprocess-exec、权限→permission…；对照 pc-capability-domains 对号）；`harmony_status`：无法适配=unavailable / 有承接但有残余=partial / 承接完整=available；`replacement` 取报告适配方案要点 |
+| `runtime_dependencies` | 类别二「子进程与原生扩展」行 | spawn/exec 面（rg、ffmpeg、sidecar 等）逐条进 `subprocess[]`——它同时决定三关治理与私有 HNP 是否启用（SKILL.md 硬性约束 #2） |
+| `library_dependencies[]` | 类别三依赖表 | 「需要适配」库逐条；「依赖但未使用」小节也逐条（notes 标 unused）；纯 JS 只计数的库不逐条展开（计数记 `harmony_adaptation.notes`） |
+| `library_closure` | 类别三策略 | **不递归下钻**（`expanded=false` 是合法终态）。节点 = 需适配依赖 + 报告提到的原生 `.node`；`native_class`：原生模块 → native-extension，纯 JS → pure-runtime；`status` 按报告策略：reuse→reuse、replace→recipe-build、port→fresh-adapt、drop→fresh-adapt + `is_bottleneck=true`；`depends_on` 留空 |
+| `harmony_adaptation.delivery_form` | 栈判定 | Electron 应用 → `app`（固定） |
+| `harmony_adaptation.feasibility` | 推导 | 见下方推导表 |
+| `harmony_adaptation.effort.magnitude` | 工作量汇总人天合计 | ≤2 极低 / ≤5 低 / ≤15 中 / ≤40 高 / >40 极高 |
+| `harmony_adaptation.porting_class` | 推导 | 无适配点 → no_adaptation；仅工程/配置类 → recompile_only；有代码适配点 → needs_adaptation_partial / needs_adaptation_full（按是否覆盖核心流程） |
+| `harmony_adaptation.blockers` | 无法适配行 + 「待确认」项 | severity：无法适配=blocker、待确认=warning |
+| `prd` | 全报告归纳 | 见下方 PRD 节 |
+| `meta.input_mode` / `meta.source_report` | — | `"report"` / `"adaptation-report/report.md"` |
+
+## feasibility 推导表
+
+报告无可行性章节（其规则禁止可行性散文），由 blockers 推导：
+
+| 报告事实 | feasibility |
+|---|---|
+| 存在「无法适配」行且命中核心功能（无承接替代） | `infeasible` |
+| 存在「无法适配」行但有部分承接（含残余功能点） | `hard` |
+| 无「无法适配」行，但存在 required 的「待确认」项 | `feasible_with_effort` |
+| 其余 | `feasible`（工作量由 effort.magnitude 承载） |
+
+## PRD 归纳规则（从适配点反推功能点）
+
+- **素材**：报告每行的「API功能 / 差异点 / 三方库功能」描述（用户视角）+ 该行 file:line 所在
+  文件的功能归属。报告行是 API/差异项级，功能点是用户可感知级——**合并不硬拆**。
+- 同一用户可感知能力上的多行合并为一条功能点；API 名进 `covered_apis.source`，报告
+  file:line 进 `evidence`。
+- 模块按应用主流程划分（编辑器例：文档编辑 / 文件读写 / 导入导出 / 设置），编号遵守
+  `F-xx` / `F-xx-xx`，`features[].module` 必须命中 `modules[].code`（`prd-shape-sane` 执法）。
+- `checkpoint` 必须具体可判定（「设备上执行 X 后观察到 Y」），禁止「功能正常」类模糊描述。
+- 不产生功能点的行：平台守卫/天然规避行；「无法适配」行的受影响功能进 `prd.scope_out`。
+- 置信度：PRD 由适配点反推、覆盖以报告为界 → `meta.confidence_overall` 至多 `medium`，
+  meta.warnings 记 `prd-derived-from-report`。
+
+## 报告驱动下 Phase 1 仍须完成的动作
+
+报告覆盖不了的三件事（各一条命令/一次判定，不做全仓扫描）：
+
+1. **部署形态判定（A/B）**：报告不会判定 Electron-OH 直跑 vs sidecar——按 SKILL.md
+   「部署形态判定」表，用报告类别二的子进程/Node 版本信息 + 内置 Node（v34→20.18 / v37→22.16）
+   对照主进程依赖判定。
+2. **设备公共 Node 版本**：`hdc shell "node -v"`（决定私有 HNP 是否自带 node）。
+3. **spawn 面清单**：直接取报告类别二「子进程与原生扩展」行的调用点清单（不重新 grep）。
+
+产出照旧落 `<APP>-adaptation-plan.md`（形态结论 + 风险表 + 依赖清单 + 产物清单），
+其中改造点清单直接引自报告行（file:line 可追溯）。
+
+## 降级与禁止
+
+- 报告未覆盖的维度如实标 `unknown` / `pending` + meta.warnings；**禁止为补字段回头跑**
+  `ohpt-agent scan-electron` 全量扫描、pc-registry 三级探测——报告没有的就承认没有。
+- **抽查对照（唯一的源码接触面）**：至少抽 3 处报告引用的 file:line 核对与 `<APP>` 源码实际
+  相符；对不上的记 `evidence-mismatch` 并降置信。
+- Phase 3 消费：适配方案以报告行**逐条执行**（patches/ 改动对应报告 file:line）；报告未覆盖
+  的平台机制问题（三关/argv/scheme 等 SKILL.md 硬性约束）仍按本 skill 常规处理。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-schemas/references/semantics/enum-semantics.md

@@ -0,0 +1,389 @@
+# Enum 语义参考
+
+各阶段 JSON 产物 enum 值的语义说明与选择条件。Schema 定义了有哪些值，本文件说明每个值什么意思、什么条件选哪个。
+
+## porting_class（harmony_adaptation.porting_class）
+
+| 值 | 语义 | 适用条件 |
+|---|---|---|
+| no_adaptation | 纯语言，跑在已移植运行时，无原生扩展 | 闭包全 pure-runtime |
+| recompile_only | C/C++ 无平台特有 API，NDK 重编即可 | native-lib 但无平台特有 API |
+| needs_adaptation_full | 需源码修改但全部可适配 | 有平台特有 API 但可替换 |
+| needs_adaptation_partial | 部分 API 不可适配 | 有不可替换的平台特有 API |
+| infeasible | 核心功能不可移植 | GUI 无对应、硬件不可用 |
+
+## feasibility（harmony_adaptation.feasibility）
+
+| 值 | 语义 | 驱动因素 |
+|---|---|---|
+| feasible | 无硬阻塞 | 无 unavailable 能力域 + 无瓶颈节点 |
+| feasible_with_effort | 可行但需适配工作 | 有 partial 能力域 + 瓶颈可绕过 |
+| hard | 重大阻塞 | unavailable 能力域(非 required) + 瓶颈可换路径 |
+| infeasible | 核心功能无解 | unavailable 能力域(required) + 瓶颈编不过 |
+
+> **`infeasible` = 换任何交付形态都做不到**，不是「原交付形态做不到」。能力只在 ArkTS 侧、
+> 原生扩展够不着（窗口几何、系统文件图标等）属于**形态问题**：判 `feasible_with_effort`，
+> 在 `recommended_path` 写清迁移目标（ArkTS 侧实现 / 反向桥），不判死。
+> `unavailable` 本身也是待证命题——机器会拿 SDK 声明语料复核，见
+> `pc-knowledge-base/platform/鸿蒙PC-能力存在性以SDK声明为准.md`。
+
+feasibility 由**依赖库闭包瓶颈节点 + 依赖能力**驱动，不由顶层语言乐观判定：
+- capability-domain：依赖能力命中 unavailable 且 required → hard/infeasible
+- dependency-bottleneck：闭包瓶颈节点编不过 → 跟着降级
+- top-level-language：仅当无依赖能力命中且闭包无瓶颈时，才由顶层语言定
+- mixed：多因素混合
+
+### 附加判定程序：生态内容依赖
+
+适用对象：**软件价值依赖目标平台生态内容**的类型——包管理器、插件市场、内容/驱动分发工具等（其核心旅程 = 「从生态获取内容并在本机运行」）。
+
+判定步骤：
+1. 识别内容来源（频道/市场/registry）与内容形态（二进制包/脚本/资源）。
+2. 评估目标平台内容可用性：有无 ohos/aarch64-musl 变体？内容含二进制时，**glibc 构建的二进制在鸿蒙 musl 上无法执行**（缺 glibc 动态解释器），「能下载安装」≠「装完能用」。
+3. 核心旅程依赖缺失内容 → feasibility **至多 feasible_with_effort**，把「生态内容缺失」写入 `harmony_adaptation.blockers`（adaptability 如实标注），并要求阶段 4 在总结置顶说明「软件本体已移植，但生态内容未就绪前主旅程不可用」。
+
+> 实证（conda 案例）：conda 机器在鸿蒙 PC 全链路可跑（solve/下载/解压/链接），但 anaconda linux-aarch64 频道全为 glibc 包，装出的每个二进制都无法执行——该维度漏判会让「适配成功」严重高估可用性。
+
+## baseline_status（02-baseline.json）
+
+它问的不是「测试全绿吗」，而是：**必跑名册建成了吗、覆盖够不够？**
+
+阶段 2 产出的是**分母**——「阶段 3 必须在鸿蒙上跑通哪些用例」。它**不要求在宿主原平台跑通**：宿主预跑只填 `cases[].host_result` 给阶段 3 归因当参照，不参与任何判定。
+
+| 值 | 语义 | 判定条件（全部满足） |
+|---|---|---|
+| planned | **名册已固定，双锚覆盖无缺口** | `cases[]` 非空；`api_surface.uncovered` 与 `feature_coverage.uncovered` **均为空**；`run_command` 可复跑 |
+| partial | 名册成立，但覆盖有缺口 | `cases[]` 非空、`run_command` 可复跑；两个 `uncovered[]` 至少一个非空（缺口如实列出） |
+| blocked | 建不起名册 | 库本体无可测面 / 源码读不到 / `test_source=none`；或 scan 判 `infeasible` |
+
+三值**互斥**，由 schema `allOf/if-then` 强制。`api_surface.provenance=unavailable`（取不到公共导出面的概念）时符号面这一锚失效，故不得定稿 `planned`。
+
+**双锚**：`api_surface`（公共导出面）查「接口有没有被测到」，`feature_coverage`（PRD 功能点）查「用户可感知能力有没有被测到」。两者互不替代——libbsd 的 `sl_delete`「声明了没人测」是前者的洞，GLFW 的剪贴板/光标形状/拖放被 4 个粗能力域吞掉是后者的洞。
+
+**阶段 3 门禁只看名册产物在不在、合不合格**，三个取值都放行：`partial` 的缺口已如实列出，`blocked` 是「没有可用的上游用例」——那不该判死适配。真正的执法在下游：`03-adapt.schema.json` 要求 `test_run.roster.missing` 为空才写得出 `built-and-verified`，验收规则 `roster-accounting` 做跨文件现算对账。
+
+> **`platform_exclusive` 不是放水通道**：标了它就等于把用例移出分母，所以必须给 `exclusive_evidence` 指回 `source/` 下的 file:line（如 `tests/win32.c:88 #ifdef _WIN32`）或 CI 平台矩阵的排除项。判不出就**不标**——宁可让阶段 3 去碰，也不要凭猜缩小分母。
+
+
+## adaptation_status（04-summary.json）
+
+**最终适配结论**——阶段 4 沉淀时从阶段 3 产出归纳，是整个流水线的出口状态。
+
+| 值 | 语义 | 判定条件 |
+|---|---|---|
+| success | 全组件已验证、无回归 | 见下方展开 |
+| partial | 部分组件未验证/有未修复回归/覆盖不足 | 至少一个组件编译通过但未达全验证 |
+| failed | 编不出 | 核心组件编译失败 |
+| infeasible | scan 判定核心不可移植 | `harmony_adaptation.feasibility = "infeasible"` |
+| blocked | 前置阶段被门禁拦下、适配未实际进行 | 门禁未放行（≠ infeasible：库可能完全可适配） |
+
+### 多组件项目的判定规则
+
+**当项目同时提供 CLI 和 GUI（或任何多组件组合）时，所有组件都必须适配并验证**，否则不算 `success`。典型的：Qt 应用常有 CLI 后端 + GUI 前端（cppcheck、kepa 等都有 `BUILD_GUI=ON/OFF` 分支）——只做 CLI 或只做 GUI 都是不完整的适配。
+
+| 项目结构 | `success` 要求 | 示例 |
+|---------|---------------|------|
+| 仅 CLI | CLI 编译 + 设备验证通过 | ripgrep 鸿蒙版 |
+| 仅 GUI（库） | GUI 编译 + HAP 安装运行 + 存活验证 | 纯 Qt 应用 |
+| **CLI + GUI** | **两者都编译通过 + CLI 设备验证 + GUI HAP 运行验证** | cppcheck：CLI 静态分析 + GUI 前端 |
+| 多交付形态 | 每个交付形态都有验证证据 | 库同时提供 .so + CLI + demo app |
+
+**`partial` 不等于「失败」**：CLI 已验证但 GUI 仅编译未上设备 → `partial`（GUI 验证待补充）；CLI + GUI 都编译通过但 Help/PrintSupport 模块被排除 → `partial`（功能覆盖不完整）。只有当所有组件都在设备上验证通过、且功能覆盖无明显缺失时，才可标 `success`。
+
+**「平台差异如实交代」不算覆盖缺失**（libbsd 9/12 实证）：区分「未完成的工作」与「平台不适用已交代」——后者**允许 success**，前提是三条全满足：①API 功能本身已验证或有等价验证（换可用的参数/路径/fallback 路径实测过）；②失败行为干净（返回错误码，不崩溃不 UB）；③差异源于平台环境（沙箱无该路径/架构不适用/上游测试工具无鸿蒙版），上游源码原样拿来也一样，非适配引入。典型判例：pidfile 默认路径 `/var/run` 在 app 域不存在——传自定义路径的功能已验证 → 这是**可用性约束**不是功能缺失；closefrom 走 `/proc/self/fd` fallback（功能等价、性能略低）→ 降级可用。反之：某 API 鸿蒙上完全没有验证路径、也没有平台不适用的依据 → 才是覆盖缺失，计 `partial`。
+
+**反假成功**：schema 的 `allOf/if-then` 强制 `adaptation_status=success` 时 `baseline.regression_count=0` 且 `artifacts` 非空——有未通过用例或无产物证据的「成功」不合法，必须降级为 `partial`。
+
+## host_result（02-baseline.json 的 cases[].host_result）
+
+宿主预跑的结果。**不参与任何判定**——它唯一的用途是给阶段 3 归因当参照：同一条用例在鸿蒙上挂了，宿主也挂 → 多半是上游自身问题；宿主过、鸿蒙挂 → 适配引入的。
+
+`pass` / `fail` / `skip` / `not-run`。宿主编不了或跑不动就整体填 `not-run`，**不因此降级 `baseline_status`**。`fail` 的填 `host_evidence`（报错首行 + file:line）。
+
+> 阶段 3 的失败归因用的是另一套五值分类（`test_run.failures[].attribution`，见下文），与本字段无关。
+
+
+## runtime_provisioning.device_status（03-adapt.json）
+
+设备侧生态运行时（java/node/python）的**自带供给**结果。程序见 pc-knowledge-base 的
+`platform/鸿蒙PC-设备语言运行时探测与供给.md`。
+
+> **鸿蒙 PC 上没有「设备预装可直接用」这一档。** app 域只能 exec 自己私有 HNP 里的东西：
+> 公共 HNP 不存在、别的 App 私有 HNP 在人家沙箱里、`/data/app/el1` 对 hdc shell 是 Permission
+> denied。所以「设备上有没有」不影响判定——**要用就自带**。
+
+| 值 | 语义 | 前置证据 |
+|---|---|---|
+| bundled | 本轮随交付物自带：运行时打进私有 HNP、随执行器 HAP 装机 | method + evidence[]（schema 强制）：打包命令、产物路径、设备上真跑起来的输出 |
+| missing | 需要设备侧运行时，但本轮未能自带（无产物来源/体积超限/用户叫停） | 尝试过的获取路线与失败原因 |
+| not_required | 本库不需要设备侧运行时（cpp-lib 被 napi 壳 dlopen、静态链接的 cli 等） | — |
+
+**判定程序**（阶段 3 需要设备侧运行时时按序执行）：
+
+1. 本库到底要不要设备侧运行时？不要 → `not_required`（别为填字段硬造供给）。
+2. 要 → **默认自带**：宿主侧拿到 aarch64-ohos 的运行时产物（自行交叉编译，或从中心制品仓
+   `pc-registry` 拉），打进私有 HNP → `bundled`，继续设备回归。
+3. 确实拿不到运行时产物 → `missing`；此时 03 的 status 用 **built-pending-verification**
+   （产物+runbook 齐备待验证），**不是 partial**——供给缺失是待验证，不是部分失败。
+4. **任何情况下都不许**以「设备上没有 X」为由造 stub 顶替（git-lfs 实证：fake-git 撑出 7/7 假绿）。
+
+## test_run.carriers[].carrier（03-adapt.json）
+
+**验证载体**——库在设备上被使用的两种真实形式。同一个 `.so`，两条路的加载器、命名空间、
+依赖闭包都不同，**一条过不代表另一条过**。
+
+| 值 | 语义 | 载体实现 |
+|---|---|---|
+| hap | 库被 HAP 进程 dlopen / 进程内调用 | napi 壳（`cpp-lib-demo` / `python-app-embedded`），上屏库为 OWB 工程 |
+| cli | 库被链进 ELF，在 app 域子进程里 `fork`+`execv` 跑 | 私有 HNP 执行器（`cli-hnp-runner`）——**它本身也是一个 HAP** |
+
+**哪些载体必需**由「交付形态 × 能力域」算出，**`ohpt-agent state` 的 `verify_carriers`
+直接给出**（gate env 块同名信息同源——`verify-carriers.ts` 单一真源；gate 与 state 同为
+只读，查信息走哪个都免费）——照它做即可，不必在此背表。
+缺哪一半由验收 `dual-carrier-evidence` 点名；`evidence` 须真在盘且非空——`executed: true` 自报不算数。
+
+## target_path_covered（03-adapt.json）
+
+设备侧通过用例集对鸿蒙侧目标代码路径的覆盖度，设备自验证实际执行后才可填；`covered` 要求 `test_run.executed=true`（schema 强制）。阶段 4 判 success 用的就是这一处（**唯一来源**，阶段 2 停用后无宿主侧回退）。`n/a` = 无平台分叉路径，不因覆盖扣分。
+
+## test_run.failures[].attribution（03-adapt.json）
+
+FAIL/CRASH 的根因归属——五值分类学。**成功标准恒为零 FAIL/零 CRASH**：归因不是豁免，是决定「往哪修」的路由；`failures[]` 里任何条目都必须最终复测转 PASS（从表里消失）才算闭环。
+
+与 02-baseline 的 `attribution`（停用阶段保留资产）同构但轴向不同：02 判「原平台为什么失败」，本表判「**鸿蒙侧 FAIL/CRASH 是谁的错**」。
+
+| 值 | 语义 | 解决路由 |
+|---|---|---|
+| `product-defect` | 交叉编译产物自身缺陷（导出面缺口/补丁引入/编译配置错） | 修产物：patch + 重链 + 复测 |
+| `platform-divergence` | musl/BSD/鸿蒙与测试预期的固有语义分歧，产物无缺陷 | 修测试预期：以分歧证据（musl 源码/双方文档）为据修正平台特定字面量；API 契约级断言保持 |
+| `testenv-limited` | 测试前置在验证域不可满足，但测试方法可改 | 修测试方法：常量构造输入/沙箱内路径/产物自身当 fixture |
+| `harness-bug` | 测试壳/采集链自身缺陷（NAPI 壳崩溃、日志截断、解析丢行） | 修测试壳，修好后套件完整重跑 |
+| `testcase-defect` | **用例本身写错**（断言写反、预期值算错、API 用法错）——**仅对 02-baseline 名册里 `validation=unvalidated` 的补写用例开放** | 修用例 + 重跑。仍要求最终通过，不是豁免 |
+| `unknown` | 尚未溯源——**不得作为终态挂在 built-* 状态下** | 跑下面的分诊程序 |
+
+**分诊判定程序（按序执行，命中即停）：**
+
+1. FAIL 的断言对象是**平台特定字面量**（错误文案/字节序列/格式串）？→ diff 上游实现：实现与 musl 行为一致而预期来自其他平台（BSD/glibc）→ `platform-divergence`（evidence 引 musl 源码行或双方文档差异点）；实现有差异 → `product-defect`。
+2. FAIL 因**前置缺失**（文件/设备/权限/故障注入）？→ 问「测试方法能否换成不依赖该前置的等价构造」（mode_t 常量构造/沙箱可写路径/HAP 自带 .so 当真实 ELF）→ 能 = `testenv-limited`；不能则如实记 `testenv-limited` 并在 evidence 说明为何不可替代。
+3. 进程**异常终止**（result=crash）？→ 崩溃点在套件完成标记**之前** = 覆盖不完整，按崩溃栈归因 `harness-bug` 或 `product-defect`；在全部用例跑完**之后**（收尾/析构/atexit）→ `harness-bug` 嫌疑最大，但**不得豁免**——收尾崩溃在别的集成场景可能是真数据损坏，修壳后完整重跑。
+4. 该用例是**补写的且从未自证**（02-baseline 名册里 `validation=unvalidated`）、断言的预期既非来自上游也非平台事实，而是补写时的臆断？→ `testcase-defect`（evidence 指向源码/文档里的正确契约）。
+   > 前三档是为**上游用例**设计的——上游用例在原平台是绿的，不会「写错」。补写用例没有这个背书，所以需要这一档；但也**仅限**这一档：`upstream-backed` 与 `self-validated` 的断言都有背书（上游 CI / 宿主自证），判它们写错要指向上游 issue 或 musl 事实差异（后者属 `platform-divergence`）。验收规则 `test-fix-evidenced` 会核对用对了地方没有。
+5. 以上都不成立 → `unknown`。**保守默认**：查不动就标 `unknown`，不要猜一个良性归因蒙混（同 02 归因哲学）。
+
+**归因是可证伪的预测**：`platform-divergence` 会在知识库沉淀为 musl 语义分歧表（04-summary 沉淀通道），下一库写测试预期时先查表避开；`product-defect` 的修复进 patches/。借「平台差异」放水真缺陷是最顺手的后门——所以 evidence 必填且须指向分歧来源方（哪个 libc/哪个 BSD 变体的文档）。
+
+## test_run.failures[].resolution（03-adapt.json）
+
+| 值 | 语义 |
+|---|---|
+| `open` | 未解决——名字必在 regressions 里（两表零漂移，acceptance 核对） |
+| `fixed-product` | 已修产物（patch/重链/编译配置）——fix_ref 指向修复落点 |
+| `fixed-test` | 已修测试——**必须填 `amendment`**（改动类别 + 依据 + 改前改后） |
+| `fixed-harness` | 已修测试壳/采集链 |
+
+**不存在「豁免但仍然 FAIL」的终态**：`fixed-*` 只在复测转 PASS 后才连同条目从表里消失；修了还没复测 = `open`。
+
+### `amendment`：改评判标准的留痕（`fixed-test` 必填）
+
+改测试是**合法且高频**的处置——libbsd 实证里 72 个 FAIL 有六成是语义分歧与测试前置限制，本就该改预期。但它同时是「掩盖产物缺陷最顺手的后门」，所以这个动作要比改产物留下更多痕迹：
+
+| 字段 | 填什么 |
+|---|---|
+| `class` | `platform-literal`（断言的平台字面量按 musl 事实重写）/ `test-method`（测试方法改等价构造）/ `testcase-defect`（用例写错，仅限未自证的补写用例） |
+| `basis` | **指得回去的**依据：musl 源码行、语义分歧表条目、上游 issue 链接、沙箱前置不可满足的说明。「平台差异」「预期不符」这类空泛表述会被 `test-fix-evidenced` 点名 |
+| `before` / `after` | 改前改后的断言原文——供 `pc-03-dev-verify` 与人工复核「只动了平台字面量吗」 |
+
+**红线（机器判不了，靠独立验收与人工把关）**：**API 契约级断言（返回码语义、错误码枚举）一律保持**，只有平台特定字面量可改。产物真有缺陷时 `product-defect` + `fixed-test` 的组合已由 schema 直接拒绝——那是「改测试抹掉产物缺陷」的最短路径。
+
+改动会逐条渲染进 `03-adapt-report.md` 的「本轮修改的评判标准」，规模一眼可见。
+
+## test_run.completed（03-adapt.json）
+
+| 值 | 语义 |
+|---|---|
+| `true` | 套件跑到完成标记（SUMMARY 行/测试框架正常退出），计数可作全量证据 |
+| `false` | 输出中途终止（崩溃/日志截断），此前计数不是全量证据——total_cases/pass_rate 均不可作定稿依据 |
+
+测试壳必须输出完成标记，日志采集以标记为准——标记未见即 `completed=false`。libbsd 实证：第 1 轮真机日志断在 fparseln，靠人眼比对才发现套件没跑完；完成后标记缺失与「崩溃截断冒充全量结果」是同一类问题。
+
+## effort.magnitude（harmony_adaptation.effort.magnitude）
+
+| 值 | 典型 porting_class | 特征 |
+|---|---|---|
+| 极低 | no_adaptation | 纯脚本，零原生/平台耦合 |
+| 低 | recompile_only | 仅 NDK 重编 |
+| 中 | needs_adaptation_full | 全可适配，阻碍少 |
+| 高 | needs_adaptation_partial / needs_adaptation_full | 少量 unadaptable，或含 GUI/桌面集成 |
+| 极高 | infeasible | 核心依赖无解平台/硬件 API |
+
+## delivery_form（harmony_adaptation.delivery_form）
+
+| 值 | 语义 | 判定信号 | 工作区结构 |
+|---|---|---|---|
+| pure-runtime | 纯运行时库 | 纯 Python/JS/Java 库，闭包全 pure-runtime；**无 CLI 入口** | dist/lib/ |
+| native-extension | 带原生扩展的库 | 闭包含 native-extension；**无 CLI 入口** | dist/lib/ + deps/ |
+| cpp-lib | 纯 C/C++ 库 | 无脚本运行时依赖；**产物是 `.so` 而非可执行** | dist/lib/ + harmony-demo/ |
+| cli | 命令行工具 | 有 CLI 入口（被终端用户按工具名调起） | dist/lib/（可执行） |
+| app | GUI 应用（框架已鸿蒙化） | GUI 应用且框架已鸿蒙化 | harmony-app/ + dist/app/ |
+| app-unsupported | GUI 应用（框架未鸿蒙化） | GUI 应用但框架未鸿蒙化 | 仅 scan/summary |
+
+交付形态与能力域正交：GLFW = delivery_form `cpp-lib` × 命中 `graphical-window`(unavailable) → 编得出 .so 但功能不可用 → feasibility=hard。
+
+## host_runtime（harmony_adaptation.host_runtime，可选）
+
+**谁 dlopen 这个产物。** 只对带原生扩展的形态有意义，决定链接契约、工具链前置与验证载体。
+
+| 值 | 装载者 | 产物特征（机器可核） | 载体 |
+|---|---|---|---|
+| `hap-dlopen`（缺省） | HAP 进程 / app 域 ELF | 不挂 glibc-only soname；可执行不挂 glibc 加载器 | scaffold |
+| `device-node` | 设备端 Node（随私有 HNP 自带） | `napi_*` 留 UND；不链 `libace_napi.z.so` | scaffold（双载体） |
+| `electron-oh` | Electron-OH 内置 Node（`libelectron.so`） | `napi_*` **无 UND**（静态链入垫片）；不链 `libelectron.so` | 注入既有 Electron-OH 工程（单载体，知识指针 `pc-knowledge-base/electron/electron.md`） |
+
+**与 delivery_form 的本质区别：不要照抄它的判法。** 形态是库自身的属性，看源码能判；而一个通用
+Node addon 之所以成为「Electron addon」，是因为**使用者要把它放进 Electron**——`host_runtime`
+首先是任务意图，其次才是库信号（`package.json` devDependencies 含 `electron`、用
+`electron-rebuild` 之类只够当提示，不足以当判据）。**没有明确意图就别填**，读取侧会回落到今天的行为。
+
+填错不会静默：验收规则 `load-contract-consistent` 拿产物本体（`.dynsym` 的 UND 集 /
+`DT_NEEDED` / `PT_INTERP`）与声明对账，**两个方向都会被点名**。本轮生效的宿主与它派生的载体，问 `ohpt-agent state -w <ws> --json`（`host_runtime` / `verify_carriers`）或 `ohpt-agent gate --json` 的 `env` 块——两者只读、同源、随便问。
+
+## verdict（01-scan.json 的 api_dependencies.groups[].apis[]，Electron 形态）
+
+**Electron-OH API 判定**（来源：`ohpt-agent scan-electron` 的 api_verdicts join / 适配点报告类别一表名；矩阵 = `pc-knowledge-base/electron/data/api-verdicts.json`，34 基线）。报告按它分组出「类别一」表（不支持/部分支持/有差异/需权限），缺省 = 未判定（存量产物，报告回落按 category 归组）。
+
+| 值 | 语义 |
+|---|---|
+| `支持` | 34 矩阵直接可用（「支持的API」不逐条展开，报告只计数） |
+| `部分支持` | 可用但有条件（参数/行为子集受限） |
+| `有差异` | 行为/语义与桌面端不同，需适配 |
+| `需权限` | API 可用但触发鸿蒙权限（联动 `permission_dependencies`） |
+| `不支持` | 鸿蒙无对应能力——核心功能命中即进 `unadaptable_apis`/blockers |
+
+「❗34文档冲突」是矩阵历史残留（vendored 快照 3 条），就近归入 不支持/支持、不单列。37 线无公开逐 API 文档：差异化 API 的 verdict 以 34 为基线，真机核验义务记 blockers。
+
+### 01-scan 转写契约（Electron 的 verdict/plan 填法，pc-01-analyze 执行）
+
+`api_dependencies.groups[].apis[]` 的 verdict 枚举 = 支持/部分支持/有差异/需权限/不支持，来源 = `ohpt-agent scan-electron` 输出的 `api_verdicts.requires_attention` 复核后照抄（报告驱动 = 报告类别一表名直取；「支持的API」表 → verdict=支持）：
+
+- **plan 必须是具体适配方法**（改哪里/改成什么），禁止「阶段 3 落地」式占位：有固化方案的（`api-confirmed-plans.json`，scan 输出带 confirmed_plan 标记）**逐字采用**；无固化方案的按判定组写承接（需权限→申报哪项权限+运行时动作；有差异→OHOS 语义改写点；不支持→平台守卫/替代/砍除决策建议）。
+- 报告矩阵的「❗34文档冲突」是历史残留，就近归入不支持或支持、不单列；存量/未判定可不填，报告按 category 归组。
+
+## native_class（library_closure.nodes）
+
+| 值 | 语义 | 典型信号 |
+|---|---|---|
+| pure-runtime | 纯解释型/JIT，无原生代码 | 纯 .py/.js/.java |
+| native-extension | 带原生扩展的脚本库 | .pyx/node-gyp/JNI |
+| native-lib | 纯 C/C++ 库 | CMake/Makefile 无脚本运行时 |
+| toolchain-bound | 绑定特定工具链/平台 | 平台特有构建、GUI 框架绑定 |
+
+## status（library_closure.nodes）
+
+| 值 | 语义 |
+|---|---|
+| reuse | 复用命中：本地个人登记**验真**命中（产物真实存在）或中心制品仓命中。判定顺序与验真规则见 pc-registry skill |
+| recipe-build | 已鸿蒙化，有配方自编 |
+| fresh-adapt | 未鸿蒙化，全新适配 |
+| pending | 待下钻判定 |
+
+## reuse_source（library_closure.nodes / deps_built，status=reuse 时）
+
+| 值 | 语义 |
+|---|---|
+| local-registry | 个人登记验真命中（scan）/ 个人库产物拷回（adapt）。登记须带 artifact_path 且产物 stat 存在，否则不算命中 |
+| central-registry | 中心制品仓命中（scan）/ 拉取（adapt，deps_built 记 artifact_url）（端点权威见 pc-registry） |
+
+## central_artifact.status（library_closure.nodes，中心仓探测结果）
+
+| 值 | 语义 |
+|---|---|
+| hit | 有适配版且版本可满足（判读规则按生态不同，见 pc-registry 的 central-registry.md——HTTP 200 ≠ hit） |
+| version-mismatch | 有包但精确 pin 的版本缺，available_version 记中心仓最近版本 |
+| miss | 探测确认无此包/无适配版 |
+
+探测失败（超时/网络不可达）不写 central_artifact，只在 meta.warnings 记一条并同域短路——离线行为与无中心仓一致。
+
+## api_dependencies.category
+
+| 值 | 含义 | platform 倾向 |
+|---|---|---|
+| standard | 语言标准库/运行时 | portable |
+| platform-specific | OS 特定（Win32/POSIX-only/Cocoa/inotify） | 换 OS 就没 |
+| system | 内核/系统调用（syscall/ioctl//proc/注册表/WMI） | 需适配 |
+| ffi | ctypes/cffi/JNI/N-API | 桥接层 |
+| hardware | OpenGL/Vulkan/CUDA/SIMD | 看鸿蒙是否支持 |
+
+**动态加载库**（dlopen/LoadLibrary/ctypes.CDLL/System.loadLibrary 加载，不在包清单）单列到 `api_dependencies.dynamic_libraries`。
+
+## harmony_status（capability_dependencies）
+
+| 值 | 语义 |
+|---|---|
+| available | 鸿蒙已提供对应能力 |
+| partial | 鸿蒙部分提供，需适配 |
+| unavailable | 鸿蒙未提供 |
+| unknown | 不确定 |
+
+## target_assumptions 规则
+
+逐项核对鸿蒙 PC 状态并写入 `target_assumptions[]`：
+- available → 不计阻碍
+- partial → 必产 blocker(adaptability: partial)
+- unavailable → 必产 blocker(adaptability: unadaptable)
+- **unknown → 记假设；required 时 confidence 降至多 medium，禁止据 unknown 臆断 feasible**
+
+## 部署模型
+
+- **模型 A（默认，库/命令行）**：库跑在已移植运行时上，运行时不是阻碍。阻碍 = 原生扩展(NDK 重编)/C 依赖/平台特有 syscall。需检查 `api_dependencies.category` 判定阻碍类型。
+- **模型 B（ArkTS 沙箱 GUI）**：仅当目标确为 ArkTS 应用时用；Node 核心模块不可用，需 @ohos.* 平替。
+- **模型 C（整包桌面应用）**：终端用户启动的应用，按 GUI 工具包是否鸿蒙化 / 窗口桌面集成 / 启动器打包 / 运行期服务判阻碍。
+
+## severity（blockers）
+
+| 值 | 语义 |
+|---|---|
+| blocker | 硬阻塞，不解决则不可适配 |
+| warning | 软警告，可能影响部分功能 |
+
+## adaptability（blockers）
+
+| 值 | 语义 |
+|---|---|
+| adaptable | 可适配，需修改 |
+| partial | 部分可适配 |
+| unadaptable | 不可适配 |
+
+## library.kind
+
+| 值 | 语义 |
+|---|---|
+| library | 提供公共 API 的库 |
+| application | GUI/CLI 应用 |
+| framework | 框架 |
+| tool | 工具 |
+| cli | 命令行工具 |
+| service | 服务 |
+| plugin | 插件 |
+| other | 其他 |
+
+判定信号：有 main/启动器/GUI → application；有 public API → library。
+
+## library_dependencies.scope
+
+| 值 | 语义 |
+|---|---|
+| runtime | 运行时依赖 |
+| dev | 开发依赖 |
+| test | 测试依赖 |
+| build | 构建依赖 |
+| optional | 可选依赖 |
+| peer | 同级依赖 |
+
+## library_dependencies.locality
+
+| 值 | 语义 |
+|---|---|
+| local | 本地/项目内 |
+| remote | 远端/注册表下载 |
+| system | 系统级 |
+| runtime | 运行时自带 |

package/node_modules/@ohos-agent/pc-adapter/skills/pc-schemas/references/semantics/language-signals.md

@@ -0,0 +1,56 @@
+# 语言检测信号参考
+
+各语言的清单文件位置、原生扩展检测信号、扩展后缀、鸿蒙运行时状态。扫描阶段按此表识别语言生态与原生性。
+
+## Python
+
+- 清单文件：pyproject.toml / requirements.txt / setup.py / setup.cfg
+- 原生扩展信号：setup.py ext_modules / .pyx(Cython) / cffi / ctypes
+- 扩展后缀：.cpython-312.so（鸿蒙设备 EXT_SUFFIX）
+- 运行时：CPython 3.12（鸿蒙已移植，设备路径见 pc-knowledge-base）
+
+## Node.js / TypeScript
+
+- 清单文件：package.json
+- 原生扩展信号：binding.gyp / node-gyp / napi / node-addon-api
+- 扩展后缀：.node
+- 运行时：Node.js（鸿蒙已移植，HNP 部署；**具体设备是否在位需探测**——见 pc-knowledge-base「设备语言运行时探测与供给」，勿凭本行断言已装）
+
+## Java / Kotlin
+
+- 清单文件：pom.xml / build.gradle / build.gradle.kts
+- 原生扩展信号：JNI / JNA / native 方法
+- 扩展后缀：.so (JNI lib)
+- 运行时：JVM（鸿蒙已移植：BiSheng JDK，系统级常在 `/data/service/hnp/bishengjdk17*`；**具体设备是否在位需探测**——见 pc-knowledge-base「设备语言运行时探测与供给」，勿凭本行断言已装）
+
+## C / C++
+
+- 清单文件：CMakeLists.txt / Makefile / configure.ac / meson.build
+- 原生扩展信号：本身即原生
+- 扩展后缀：.so / .a
+- 运行时：无（编译型）
+
+## Rust
+
+- 清单文件：Cargo.toml
+- 原生扩展信号：本身即原生 / build.rs / cdylib crate type
+- 扩展后缀：.so
+- 运行时：无（编译型）
+
+## Go
+
+- 清单文件：go.mod
+- 原生扩展信号：cgo / import "C"
+- 扩展后缀：.so
+- 运行时：无（编译型）
+
+## .NET（待扩展）
+
+- 清单文件：.csproj / .fsproj / Directory.Build.props
+- 原生扩展信号：P/Invoke / C++/CLI
+- 扩展后缀：.dll / .so
+- 运行时：.NET Runtime（鸿蒙未移植）
+
+## 扩展方式
+
+新语言加一节即可：清单文件位置 + 原生扩展信号 + 扩展后缀 + 鸿蒙运行时状态。零架构改动。