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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-workspace-layout/scripts/workspace-init.mjs

@@ -0,0 +1,514 @@
+#!/usr/bin/env node
+/**
+ * workspace-init.mjs — 初始化适配工作区（自包含 node 脚本，不依赖 TS 编译链）。
+ *
+ * 用法：node workspace-init.mjs <input> <lib> [version] [--source-ref <branch-or-tag>] [--repos-root <path>] [--json]
+ *   input: git url / 本地路径
+ *
+ * 逻辑（从 src/lib/workspace.ts 迁来）：
+ *   解析输入三态（git-url / local-repo / local-snapshot）→ 创建工作区骨架
+ *   → source 落位（clone 或拷贝）→ 写 manifest.json。
+ *
+ * 编排器 agent 通过 pc-workspace-layout skill 调用本脚本（不放 CLI，CLI 是用户面向的）。
+ * 符合 pc-device-verify skill 自带 scripts/ 的先例。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { execFileSync, execSync } from 'node:child_process'
+import { parseArgs } from 'node:util'
+import versionDetector from './version-detector.cjs'
+
+const { detectProjectVersion, normalizeVersion } = versionDetector
+
+const ADAPT_DIR_NAME = '.ohos-adaptation-pc'
+const MANIFEST_FILE = 'manifest.json'
+
+// workspace-init 只建 .ohos-adaptation-pc/（放 manifest）+ source/（clone/copy 创建）。
+// 其余产物目录（patches/build/dist/deps/harmony-demo/harmony-app/tests-generated）不预建——
+// agent 写产物时按需 mkdir -p（呼应"没必要初始化空目录"）。
+const INIT_DIRS = [ADAPT_DIR_NAME]
+
+const BUILD_ENTRY_FILES = [
+  'CMakeLists.txt', 'package.json', 'pyproject.toml', 'setup.py', 'Cargo.toml',
+  'go.mod', 'pom.xml', 'build.gradle', 'build.gradle.kts', 'meson.build',
+  'Makefile', 'configure',
+]
+
+// 嵌套探测用（根级清单 + 只在子目录常见的入口形态）：不少上游把构建入口放一两层子目录——
+// 7zip 的 CPP/7zip/{makefile,*.mak}（实证：根级启发式两度误报「不是源码根」，人工核实两遍）；
+// Windows 工程的 *.sln/*.vcxproj；autotools 源码树里常见 configure.ac（configure 是生成物）。
+const NESTED_ENTRY_FILES = [
+  ...BUILD_ENTRY_FILES,
+  'makefile', 'configure.ac', 'autogen.sh',
+  '*.mak', '*.sln', '*.vcxproj',
+]
+// 嵌套扫描跳过的目录：隐藏目录（.git 等）、构建产物目录、纯文档/示例目录（防误报——
+// docs/ 里的示例 CMakeLists 不构成「这是源码根」的证据）。
+const NESTED_SKIP_DIRS = new Set([
+  '.git', 'node_modules', '.hvigor', 'build', 'dist', 'bin', 'obj', 'out', 'target',
+  'doc', 'docs', 'example', 'examples', 'demo', 'demos',
+])
+
+function isBuildEntry(name, list) {
+  return list.some((p) => (p.endsWith('*') ? name.endsWith(p.slice(1)) : name === p))
+}
+
+/** 根级探测（原 looksLikeSourceRoot 语义）。 */
+function rootBuildEntry(dir) {
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return null
+  const entries = fs.readdirSync(dir)
+  const hit = entries.find((e) => isBuildEntry(e, BUILD_ENTRY_FILES))
+  return hit ? { entry: hit, depth: 0 } : null
+}
+
+/**
+ * 嵌套构建入口探测（深度 ≤2，跳过 NESTED_SKIP_DIRS 与隐藏目录）。
+ * 返回首个命中的相对路径（POSIX 分隔，如 'CPP/7zip/makefile'），未命中返回 null。
+ * 这是启发式的「证据充分即放行」：docs 示例工程这类弱证据被跳过；真源码根几乎总能
+ * 在两级内命中至少一个构建入口文件。
+ */
+function nestedBuildEntry(dir) {
+  let level1
+  try { level1 = fs.readdirSync(dir, { withFileTypes: true }) } catch { return null }
+  for (const d1 of level1) {
+    if (!d1.isDirectory() || d1.name.startsWith('.') || NESTED_SKIP_DIRS.has(d1.name.toLowerCase())) continue
+    const p1 = path.join(dir, d1.name)
+    try {
+      const hit1 = fs.readdirSync(p1).find((e) => isBuildEntry(e, NESTED_ENTRY_FILES))
+      if (hit1) return path.relative(dir, path.join(p1, hit1)).replace(/\\/g, '/')
+    } catch { /* 不可读子目录直接跳过 */ }
+    // 深度 2
+    let level2
+    try { level2 = fs.readdirSync(p1, { withFileTypes: true }) } catch { continue }
+    for (const d2 of level2) {
+      if (!d2.isDirectory() || d2.name.startsWith('.') || NESTED_SKIP_DIRS.has(d2.name.toLowerCase())) continue
+      const p2 = path.join(p1, d2.name)
+      try {
+        const hit2 = fs.readdirSync(p2).find((e) => isBuildEntry(e, NESTED_ENTRY_FILES))
+        if (hit2) return path.relative(dir, path.join(p2, hit2)).replace(/\\/g, '/')
+      } catch { /* 跳过 */ }
+    }
+  }
+  return null
+}
+
+/**
+ * 综合探测：根级优先，根级没有再扫嵌套（深度 ≤2）。返回入口相对路径（POSIX 分隔）或 null。
+ * manifest 记 `build_entry`——续跑会话与 scan agent 直接消费，不再重复人工核实。
+ */
+function findBuildEntry(dir) {
+  return rootBuildEntry(dir)?.entry ?? nestedBuildEntry(dir)
+}
+
+function looksLikeSourceRoot(dir) {
+  return findBuildEntry(dir) !== null
+}
+
+function isGitRepo(dir) {
+  return fs.existsSync(path.join(dir, '.git'))
+}
+
+function gitRemoteUrl(dir) {
+  try {
+    const out = execSync(`git -C "${dir}" remote`, { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' })
+    const first = out.split(/\s+/).filter(Boolean)[0]
+    if (!first) return null
+    return execSync(`git -C "${dir}" remote get-url "${first}"`, { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' }).trim()
+  } catch { return null }
+}
+
+function gitHeadCommit(dir) {
+  try {
+    return execSync(`git -C "${dir}" rev-parse HEAD`, { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' }).trim() || null
+  } catch { return null }
+}
+
+function resolveInput(input) {
+  const trimmed = input.trim()
+  if (/^https?:\/\//.test(trimmed) || /^git@/.test(trimmed) || trimmed.endsWith('.git')) {
+    return { origin: 'git-url', upstreamUrl: trimmed, upstreamCommit: null, sourceRef: trimmed }
+  }
+  const abs = path.resolve(trimmed)
+  if (fs.existsSync(abs)) {
+    if (isGitRepo(abs)) {
+      return { origin: 'local-repo', upstreamUrl: gitRemoteUrl(abs), upstreamCommit: gitHeadCommit(abs), sourceRef: abs }
+    }
+    return { origin: 'local-snapshot', upstreamUrl: null, upstreamCommit: null, sourceRef: abs }
+  }
+  throw new Error(`输入既不是 git url 也不是存在的本地路径: ${input}`)
+}
+
+function slug(s) {
+  return String(s || '').trim().replace(/[\\/:*?"<>|]+/g, '-')
+}
+
+function createSkeleton(workspaceDir) {
+  // 只建 .ohos-adaptation-pc/（放 manifest）。source/ 由 clone/copy 创建，其余产物目录 agent 按需建。
+  for (const d of INIT_DIRS) fs.mkdirSync(path.join(workspaceDir, d), { recursive: true })
+}
+
+/** 克隆重试参数：上游多为国外主机（github/savannah/freedesktop 等），直连/代理抖动会瞬态失败——
+ * 实测同一命令 21s connect 超时后立刻重跑即成功，重试间隔隔开抖动窗口、避免三次连打全灭。 */
+const CLONE_MAX_ATTEMPTS = 3
+const CLONE_RETRY_DELAY_MS = 2000
+
+/** 同步 sleep：本脚本全程同步（execFileSync 链路），用 Atomics.wait 阻塞主线程，不引入子进程。 */
+function syncSleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+}
+
+function cloneToSource(gitUrl, sourceDir, sourceRef = null) {
+  const args = ['clone', '--depth', '1']
+  if (sourceRef) args.push('--branch', sourceRef)
+  args.push(gitUrl, sourceDir)
+  let lastErr = null
+  for (let attempt = 1; attempt <= CLONE_MAX_ATTEMPTS; attempt++) {
+    try {
+      execFileSync('git', args, { stdio: 'inherit' })
+      return { commit: gitHeadCommit(sourceDir) }
+    } catch (e) {
+      lastErr = e
+      if (attempt === CLONE_MAX_ATTEMPTS) break
+      // 防御性清理半成品：git clone 失败可能留下不完整 sourceDir（staging 或工作区 source 均可安全删）
+      try { fs.rmSync(sourceDir, { recursive: true, force: true }) } catch { /* 半成品可能不存在 */ }
+      syncSleep(CLONE_RETRY_DELAY_MS)
+    }
+  }
+  throw new Error(`克隆失败（已重试 ${CLONE_MAX_ATTEMPTS} 次）: ${String(lastErr?.message || lastErr)}。` +
+    `上游 ${gitUrl} 不可达多为网络/代理/SSL 受限：先确认直连可达（curl -sI ${gitUrl}），或检查代理节点/为 git 配置可达镜像`)
+}
+
+function copyToSource(srcDir, destDir) {
+  // 源已经就位于目标位（input 直接指向 <workspace>/source）→ 无搬运可做，直接收敛。
+  // 不加这条守卫时，`cp -R X/. X/` 报 "are identical" 非 0 退出，整个 init 失败；
+  // 而它后面串着 `&& rm -rf "<dest>/.git"`——一旦哪个平台的 cp 对自拷贝返 0，
+  // 被删的就是源码自己的 .git。守卫同时关闭「二次 init」「软链同指」等同类形态。
+  if (path.resolve(srcDir) === path.resolve(destDir)) {
+    // 只有「源确实还在目标位」才是无操作。--force 先 rmSync 掉整个工作区后路径依旧相等、
+    // 而源已不存在，静默 return 会留下一个没有 source/ 的空工作区却报 ok:true。
+    if (fs.existsSync(destDir)) return
+    throw new Error(`输入源位于被重建的工作区内且已被清除: ${destDir}（--force 请改用工作区外的输入路径）`)
+  }
+  fs.mkdirSync(destDir, { recursive: true })
+  if (process.platform === 'win32') {
+    // robocopy 退出码 0-7 均成功（1=有复制/2=有额外/3=两者），>7 才是真失败
+    try {
+      execSync(`robocopy "${srcDir}" "${destDir}" /E /XD .git .ohos-adaptation-pc /NFL /NDL /NJH /NJS`, { stdio: 'ignore' })
+    } catch (e) {
+      const code = e?.status ?? 1
+      if (code > 7) throw new Error(`robocopy 失败，退出码 ${code}`)
+    }
+  } else {
+    execSync(`cp -R "${srcDir}/." "${destDir}/" && rm -rf "${destDir}/.git" "${destDir}/.ohos-adaptation-pc"`, { stdio: 'inherit' })
+  }
+}
+
+function writeInitialManifest(adaptDir, seed) {
+  const manifestPath = path.join(adaptDir, MANIFEST_FILE)
+  const manifest = {
+    schema_version: '1.0',
+    lib: seed.lib,
+    version: seed.version || null,
+    version_source: seed.versionSource || null,
+    source: {
+      origin: seed.sourceOrigin,
+      upstream_url: seed.upstreamUrl,
+      upstream_commit: seed.upstreamCommit,
+      ref: seed.sourceRef || null,
+    },
+    // 构建入口（相对 source/ 的路径，如 'CPP/7zip/makefile'；根级就是文件名）。
+    // 根级+嵌套两级启发式的结论持久化在此——续跑直接放行，不再每会话人工核实一遍。
+    build_entry: seed.buildEntry ?? null,
+    delivery_form: null,
+    capability_domains: [],
+    library_closure: [],
+    stage_outputs: { scan: '01-scan.json', baseline: '02-baseline.json', adapt: '03-adapt.json', summary: '04-summary.json' },
+    created_at: new Date().toISOString(),
+  }
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8')
+  return manifestPath
+}
+
+function slugName(lib, version) {
+  return version ? `${slug(lib)}-${slug(version)}` : slug(lib)
+}
+
+/**
+ * 续跑探针：找该 (库, ref) 已存在的工作区。恰 1 个可复用（免克隆）。
+ *
+ * **已注册工作区一律按 manifest 认领，不看目录名**——目录名只是首次建区时的一次性派生，
+ * 带不带版本后缀、后来改没改名都不该影响寻址。按名字正则 `^<lib>(-.+)?$` 匹配还会串库：
+ * 库 `libdwarf` 会命中另一个库的 `libdwarf-code-2.3.3`。
+ *
+ * requireManifest=false 用于**自愈探测**（目录在、manifest 缺）。这种目录只能靠名字认领，
+ * 而名字是弱证据：只认「库名本身」与「库名 + 版本后缀」这两种形态（上游各下载器的全部产物），
+ * 后缀不像版本号的一律不认——同样是为了不把 `libdwarf-code` 认成 `libdwarf`。
+ */
+function findExistingWorkspaces(reposRoot, lib, sourceRef = null, requireManifest = true) {
+  if (!fs.existsSync(reposRoot)) return []
+  const libSlug = slug(lib)
+  const out = []
+  for (const name of fs.readdirSync(reposRoot)) {
+    const workspaceDir = path.join(reposRoot, name)
+    try { if (!fs.statSync(workspaceDir).isDirectory()) continue } catch { continue }
+    const manifestPath = path.join(workspaceDir, ADAPT_DIR_NAME, MANIFEST_FILE)
+    if (!fs.existsSync(manifestPath)) {
+      if (requireManifest) continue
+      const suffix = name.startsWith(`${libSlug}-`) ? name.slice(libSlug.length + 1) : null
+      if (name !== libSlug && !(suffix && normalizeVersion(suffix))) continue
+      out.push({ name, workspaceDir, needsHeal: true })
+      continue
+    }
+    try {
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+      if (manifest.lib !== lib) continue
+      if ((manifest.source?.ref || null) !== (sourceRef || null)) continue
+    } catch { continue }
+    out.push({ name, workspaceDir })
+  }
+  return out
+}
+
+/**
+ * ══ 不变量：**幂等自愈** ══════════════════════════════════════════════════════
+ * 本脚本对任何**部分初始化**状态都应收敛到完整状态，且零破坏、零重复克隆；
+ * `--force` 是唯一的破坏性路径。
+ *
+ * 原先「adaptDir 在、manifest 缺」是个**跑多少次都出不去**的状态：续跑探针要求 manifest 才认，
+ * 认不出就走 staging 克隆，而 `alreadyExists` 又让写 manifest 那段整个跳过。
+ *
+ * 自愈只做「缺什么补什么」：source/ 在且像源码根 → 从它的 .git 反推 upstream 补写 manifest；
+ * 补不出（source/ 不在或不像源码根）→ 不猜，照常走正常克隆路径。
+ * ════════════════════════════════════════════════════════════════════════════
+ */
+function healWorkspace(workspaceDir, { lib, sourceRef, detectVersionEnabled }) {
+  const sourceDir = path.join(workspaceDir, 'source')
+  if (!looksLikeSourceRoot(sourceDir)) return null    // 补不出就不补，交回正常路径
+  const adaptDir = path.join(workspaceDir, ADAPT_DIR_NAME)
+  fs.mkdirSync(adaptDir, { recursive: true })
+  const detected = detectVersionEnabled ? detectProjectVersion(sourceDir) : null
+  writeInitialManifest(adaptDir, {
+    lib,
+    version: detected?.value || null,
+    versionSource: detected?.source || null,
+    sourceRef,
+    sourceOrigin: isGitRepo(sourceDir) ? 'git-url' : 'local-snapshot',
+    upstreamUrl: gitRemoteUrl(sourceDir),
+    upstreamCommit: gitHeadCommit(sourceDir),
+    buildEntry: findBuildEntry(sourceDir),
+  })
+  return reuseResult(workspaceDir)
+}
+
+function reuseResult(workspaceDir) {
+  const sourceDir = path.join(workspaceDir, 'source')
+  const adaptDir = path.join(workspaceDir, ADAPT_DIR_NAME)
+  const manifestPath = path.join(adaptDir, MANIFEST_FILE)
+  let manifest = {}
+  try { manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) } catch { /* 无/坏 manifest，字段留空 */ }
+  const src = manifest.source || {}
+  const detected = detectProjectVersion(sourceDir)
+  const detectedVersion = detected?.value || null
+  const versionSource = detected?.source || null
+  let dirty = false
+  if (manifest.version !== detectedVersion || manifest.version_source !== versionSource) {
+    manifest.version = detectedVersion
+    manifest.version_source = versionSource
+    dirty = true
+  }
+  // build_entry 刷新：老工作区 manifest 没有这个字段——补上，续跑会话不再人工核实源码根
+  const entry = findBuildEntry(sourceDir)
+  if (entry && manifest.build_entry !== entry) {
+    manifest.build_entry = entry
+    dirty = true
+  }
+  if (dirty) {
+    try { fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8') } catch { /* 只影响元数据刷新 */ }
+  }
+  return {
+    workspaceDir, sourceDir, adaptDir, manifestPath,
+    buildEntry: manifest.build_entry ?? entry,
+    sourceOrigin: src.origin ?? null, upstreamUrl: src.upstream_url ?? null,
+    upstreamCommit: src.upstream_commit ?? null,
+    sourceRef: src.ref ?? null,
+    alreadyExists: true, detectedVersion,
+    versionSource,
+  }
+}
+
+function initWorkspace({ input, lib, version, sourceRef, reposRoot, force, detectVersionEnabled }) {
+  const resolved = resolveInput(input)
+  let finalVersion = version           // 显式版本优先
+  let versionSource = finalVersion ? 'explicit' : null
+  let stagingSource = null             // git-url 需先克隆才能探测版本时，暂存于此
+
+  // ══ 不变量：**工作区身份由磁盘 manifest 决定，不由本次版本探测决定** ════════
+  // 版本探测只参与【首次命名】，不参与【再次寻址】。续跑探针因此与输入形态无关——
+  // 它曾只挂在 git-url 分支上，于是本地路径输入（上游工具的常态）每次都拿「当前源码
+  // 探出来的版本」重算目录名：探测一飘（.git 被剥、tag 归一化、适配改了构建文件、
+  // 探测规则升级…）就换个目录重建，阶段产物与会话指针留在旧目录、流水线从头再来。
+  // 两个逃生口：显式 version 位置参数（确定性命名）与 --force（唯一破坏性路径）。
+  // ═════════════════════════════════════════════════════════
+  if (!finalVersion && !force) {
+    const candidates = findExistingWorkspaces(reposRoot, lib, sourceRef)
+    if (candidates.length === 1) return reuseResult(candidates[0].workspaceDir)
+    if (candidates.length > 1) {
+      const err = new Error(`存在多个候选工作区，请显式传入版本号消歧：${candidates.map((c) => c.name).join(', ')}`)
+      err.exitCode = 2
+      throw err
+    }
+    // 自愈探测**必须在克隆之前**：放到克隆后再判，一整个仓已经白克隆了。
+    const partial = findExistingWorkspaces(reposRoot, lib, sourceRef, false).filter((c) => c.needsHeal)
+    if (partial.length === 1) {
+      const healed = healWorkspace(partial[0].workspaceDir, { lib, sourceRef, detectVersionEnabled })
+      if (healed) return healed
+    }
+  }
+
+  if (!finalVersion && detectVersionEnabled) {
+    if (resolved.origin === 'git-url') {
+      fs.mkdirSync(reposRoot, { recursive: true })   // 克隆一次到 staging（须在 reposRoot 下，renameSync 免 EXDEV）
+      stagingSource = path.join(reposRoot, `.staging-${process.pid}-${Date.now()}`, 'source')
+      fs.mkdirSync(path.dirname(stagingSource), { recursive: true })
+      try {
+        resolved.upstreamCommit = cloneToSource(resolved.sourceRef, stagingSource, sourceRef).commit
+      } catch (e) {
+        // 探测用的 staging clone 失败也要清场：重试 3 次仍失败说明上游不可达，
+        // 不留 `.staging-*` 垃圾目录（下方 finally 只覆盖建区分支，覆盖不到这里）。
+        fs.rmSync(path.dirname(stagingSource), { recursive: true, force: true })
+        throw e
+      }
+      const detected = detectProjectVersion(stagingSource)
+      finalVersion = detected?.value || null
+      versionSource = detected?.source || null
+    } else {
+      const detected = detectProjectVersion(resolved.sourceRef)   // 本地源码已在盘，直接探测
+      finalVersion = detected?.value || null
+      versionSource = detected?.source || null
+    }
+  }
+
+  const workspaceDir = path.join(reposRoot, slugName(lib, finalVersion))
+  const sourceDir = path.join(workspaceDir, 'source')
+  const adaptDir = path.join(workspaceDir, ADAPT_DIR_NAME)
+  const manifestPath = path.join(adaptDir, MANIFEST_FILE)
+
+  const alreadyExists = fs.existsSync(adaptDir)
+  try {
+    if (force && fs.existsSync(workspaceDir)) fs.rmSync(workspaceDir, { recursive: true, force: true })
+    if (!alreadyExists || force) {
+      fs.mkdirSync(workspaceDir, { recursive: true })
+      createSkeleton(workspaceDir)
+      if (stagingSource) {
+        fs.renameSync(stagingSource, sourceDir)      // 把预克隆的 source 移入（同文件系统，无 EXDEV）
+      } else if (resolved.origin === 'git-url') {
+        resolved.upstreamCommit = cloneToSource(resolved.sourceRef, sourceDir, sourceRef).commit
+      } else {
+        copyToSource(resolved.sourceRef, sourceDir)
+      }
+      writeInitialManifest(adaptDir, {
+        lib, version: finalVersion, versionSource, sourceRef, sourceOrigin: resolved.origin,
+        upstreamUrl: resolved.upstreamUrl, upstreamCommit: resolved.upstreamCommit,
+        buildEntry: findBuildEntry(sourceDir),
+      })
+    } else if (!fs.existsSync(manifestPath)) {
+      // 幂等自愈的第二个入口：显式版本 / 本地输入不走上面的探针，同样可能撞上
+      // 「adaptDir 在、manifest 缺」——缺什么补什么，不重建也不重克隆。
+      const healed = healWorkspace(workspaceDir, { lib, sourceRef, detectVersionEnabled })
+      if (!healed) {
+        writeInitialManifest(adaptDir, {
+          lib, version: finalVersion, versionSource, sourceRef, sourceOrigin: resolved.origin,
+          upstreamUrl: resolved.upstreamUrl, upstreamCommit: resolved.upstreamCommit,
+        })
+      }
+    }
+  } finally {
+    if (stagingSource) fs.rmSync(path.dirname(stagingSource), { recursive: true, force: true })
+  }
+
+  return {
+    workspaceDir, sourceDir, adaptDir, manifestPath,
+    buildEntry: findBuildEntry(sourceDir),
+    sourceOrigin: resolved.origin, upstreamUrl: resolved.upstreamUrl,
+    upstreamCommit: resolved.upstreamCommit, sourceRef: sourceRef || null,
+    alreadyExists: alreadyExists && !force, detectedVersion: finalVersion,
+    versionSource,
+  }
+}
+
+// ---- CLI 入口 ----
+const { values, positionals } = parseArgs({
+  args: process.argv.slice(2),
+  allowPositionals: true,
+  options: {
+    'repos-root': { type: 'string' },
+    json: { type: 'boolean' },
+    force: { type: 'boolean' },
+    'source-ref': { type: 'string' },
+    'no-detect-version': { type: 'boolean' },
+  },
+})
+
+const input = positionals[0]
+const lib = positionals[1]
+const version = positionals[2]
+const sourceRef = values['source-ref'] || null
+const reposRoot = values['repos-root'] ? path.resolve(values['repos-root']) : path.resolve(process.cwd(), 'repos-pc')
+const json = Boolean(values.json)
+// 省略版本位置参数时默认探测；--no-detect-version 为逃生口。显式给了 version 则直接用、不探测。
+const detectVersionEnabled = !values['no-detect-version']
+
+/**
+ * 排干 stdout/stderr 后退出。**不要直接调 process.exit()。**
+ *
+ * POSIX 上 Node 的 stdout 只有 TTY / 重定向到文件时才是同步的；被管道接走时是异步的，
+ * process.exit() 会丢掉尚未 flush 的排队数据（macOS 实测同步写窗口仅 8192 字节），
+ * 而且退出码仍是 0——调用方拿到半截 JSON 却以为命令成功了。本脚本一律经编排器的
+ * Bash 工具调用，stdout 永远是管道，所以这条不是理论风险。
+ *
+ * 注意：本函数**会返回**，真正的退出发生在 flush 回调里，调用点之后要自己 return。
+ * （此处是独立复制而非 import：本脚本随 skill 发布，运行时拿不到插件 src/。）
+ */
+function exitWith(code) {
+  process.exitCode = code
+  let pending = 2
+  const done = () => { if (--pending === 0) process.exit(code) }
+  for (const s of [process.stdout, process.stderr]) {
+    if (s.writableLength === 0) done()
+    else s.write('', done)
+  }
+}
+
+/** 只返回退出码、绝不自己退出——退出收在下面唯一的 exitWith 出口。 */
+function runCli() {
+  if (!input || !lib) {
+    console.error('用法: node workspace-init.mjs <input> <lib> [version] [--source-ref <branch-or-tag>] [--repos-root <path>] [--force] [--no-detect-version] [--json]')
+    return 2
+  }
+
+  try {
+    const info = initWorkspace({ input, lib, version, sourceRef, reposRoot, force: Boolean(values.force), detectVersionEnabled })
+    const buildEntry = findBuildEntry(info.sourceDir)
+    const looksLikeRoot = buildEntry !== null
+    if (json) {
+      console.log(JSON.stringify({ ok: true, alreadyExists: info.alreadyExists, looksLikeSourceRoot: looksLikeRoot, buildEntry, ...info }, null, 2))
+      return 0
+    }
+    console.log(`✓ 工作区已创建: ${info.workspaceDir}`)
+    console.log(`  source_origin: ${info.sourceOrigin}`)
+    if (info.upstreamUrl) console.log(`  upstream_url:  ${info.upstreamUrl}`)
+    if (info.upstreamCommit) console.log(`  upstream_commit: ${info.upstreamCommit}`)
+    console.log(`  manifest:      ${info.manifestPath}`)
+    if (buildEntry) console.log(`  build_entry:   ${buildEntry}`)
+    if (!looksLikeRoot) {
+      console.log(`  ⚠ source/ 根级与两级子目录均未检出构建入口文件，请确认输入指向正确的源码根目录`)
+      return 2
+    }
+    return 0
+  } catch (e) {
+    console.error(`Error: ${e.message}`)
+    return e.exitCode || 1
+  }
+}
+
+exitWith(runCli())

package/node_modules/@ohos-agent/pc-adapter/templates/build-tools/check-payload-paths.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * check-payload-paths.mjs — Electron-OH 载荷相对引用完整性校验（fail-fast 门禁）
+ *
+ * 用途：打包脚本（assemble-payload / sync-payload）组装完 HAP 载荷（resources/app）后，
+ *      扫描载荷内全部 js/html/css 的相对引用（require / import / <script src> / url(..)），
+ *      逐一从所在文件目录解析验证目标是否存在。目标不存在或「../」逃逸出载荷根即 FAIL。
+ *
+ * 背景（pc-error-atlas L059）：重打包改布局（拍平 app/ 等）会改变相对引用解析基准，
+ * 引用字符串未同步则真机启动即 "Cannot find module '../xxx'"——此类运行期错误在
+ * 无设备/无签阶段只能靠本校验在打包当场拦截，不能依赖设备验证当最后一道。
+ *
+ * 用法：node check-payload-paths.mjs --payload <payload根目录> [--quiet]
+ * 退出码：0 = 全部引用可解析；1 = 存在断裂引用（fail-fast，构建链应中止）
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ARGS = process.argv.slice(2);
+const idxPayload = ARGS.indexOf('--payload');
+const payloadRoot = idxPayload >= 0 ? ARGS[idxPayload + 1] : null;
+const quiet = ARGS.includes('--quiet');
+if (!payloadRoot) {
+  console.error('[check-payload-paths] 用法: node check-payload-paths.mjs --payload <payload根目录> [--quiet]');
+  process.exit(2);
+}
+const ROOT = path.resolve(payloadRoot);
+if (!fs.existsSync(ROOT)) {
+  console.error(`[check-payload-paths] payload 根不存在: ${ROOT}`);
+  process.exit(2);
+}
+
+// ---- 收集载荷内所有可引用源文件 ----
+const FILES = [];
+(function walk(d) {
+  for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+    const p = path.join(d, e.name);
+    if (e.isDirectory()) {
+      if (e.name === 'node_modules') continue; // node_modules 走标准解析，不在此校验范围
+      walk(p);
+    } else if (/\.(js|mjs|cjs|html|css)$/.test(e.name)) {
+      FILES.push(p);
+    }
+  }
+})(ROOT);
+
+// ---- 提取相对引用（单文件多行扫描） ----
+const RE_JS = /require\(\s*['"](\.\.?\/[^'"]+)['"]|from\s*['"](\.\.?\/[^'"]+)['"]|import\(\s*['"](\.\.?\/[^'"]+)['"]/g;
+const RE_HTML = /(?:src|href)\s*=\s*["'](\.\.?\/[^"']+)["']/g;
+const RE_CSS = /url\(\s*['"]?(\.\.?\/[^'")\s]+)['"]?\s*\)/g;
+
+// 无扩展名容错解析：目标为目录则试 index.*，否则试常见扩展
+function resolveTarget(fromDir, rel) {
+  const base = path.resolve(fromDir, rel);
+  if (fs.existsSync(base)) return base;
+  const tryExt = ['.js', '.mjs', '.cjs', '.json', '.node'];
+  for (const ext of tryExt) {
+    if (fs.existsSync(base + ext)) return base + ext;
+  }
+  if (fs.existsSync(base) && fs.statSync(base).isDirectory()) {
+    for (const ext of tryExt) {
+      const idx = path.join(base, 'index' + ext);
+      if (fs.existsSync(idx)) return idx;
+    }
+  }
+  return null;
+}
+
+const problems = [];
+let refCount = 0;
+
+for (const f of FILES) {
+  const src = fs.readFileSync(f, 'utf8');
+  const dir = path.dirname(f);
+  const relFile = path.relative(ROOT, f).replace(/\\/g, '/');
+  const patterns = f.endsWith('.html') ? [RE_HTML] : f.endsWith('.css') ? [RE_CSS] : [RE_JS];
+  for (const re of patterns) {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(src)) !== null) {
+      const rel = m[1] || m[2] || m[3];
+      refCount++;
+      const resolved = resolveTarget(dir, rel);
+      const escaped = !path.resolve(dir, rel).startsWith(ROOT + path.sep); // ../ 逃逸出载荷根
+      if (!resolved || escaped) {
+        const line = src.slice(0, m.index).split('\n').length;
+        problems.push({
+          file: relFile,
+          line,
+          ref: rel,
+          target: path.resolve(dir, rel).replace(/\\/g, '/'),
+          reason: !resolved ? '目标不存在' : '../ 逃逸出载荷根（HAP 内不可达）',
+        });
+      }
+    }
+  }
+}
+
+// ---- 报告 ----
+if (problems.length > 0) {
+  console.error(`[check-payload-paths] FAIL: ${problems.length} 处相对引用不可解析（载荷根 ${ROOT}）`);
+  for (const p of problems) {
+    console.error(`  ${p.file}:${p.line}  ${p.ref}  →  ${p.target}  [${p.reason}]`);
+    console.error(`      改法：同级引用用 ./，引用载荷根内兄弟目录用 ../（保持上游目录结构则引用零改动）`);
+  }
+  console.error('[check-payload-paths] 构建链应中止（fail-fast）——此错误装机后真机启动必报 Cannot find module');
+  process.exit(1);
+}
+if (!quiet) {
+  console.log(`[check-payload-paths] OK: ${FILES.length} 文件 / ${refCount} 相对引用全部可解析（载荷根 ${ROOT}）`);
+}
+process.exit(0);

package/node_modules/@ohos-agent/pc-adapter/templates/build-tools/electron-napi-library/README.md

@@ -0,0 +1,43 @@
+# electron-napi-library（vendored）
+
+Electron-OH addon 的 **N-API 垫片**：把 `napi_*`/`uv_*` 调用在运行时转发给宿主的 `libelectron.so`。
+
+| | |
+|---|---|
+| 出处 | Electron 鸿蒙化指导文档随附的 `electron-loading-addon-guide/electron-napi-library/` |
+| 许可 | MIT（Electron contributors / GitHub Inc.） |
+| 大小 | 348 KB（`include/` 292 KB + `lib/libshim.a` 50 KB） |
+| 覆盖 | `$ELECTRON_NAPI_LIBRARY` 指向别处即用别处（跟随 Electron 版本升级） |
+
+## 三条使用要点（原 readme 的全部内容）
+
+```
+头文件路径：./include/electron_node/src/node_api.h
+库文件路径：./lib/libshim.a
+添加宏定义：HIDE_NAPI_AND_UV
+```
+
+## 它到底做了什么（实测，别照抄传闻）
+
+`lib/libshim.a` 只有一个成员 `shim.c.o`（aarch64，编译自 `OHOS (dev) clang version 15.0.4`）。
+当前归档提供 **161 个全局函数定义**（145 个 `napi_*` + 7 个 `node_api_*` + 9 个 `uv_*`），而**唯二未定义
+符号是 `dlopen`/`dlsym`**——内含 `ensure_electron_symbols_resolved` 与 `g_electronSymbolTable`，
+以及字符串字面量 `libelectron.so`。也就是说：它是一张**惰性 dlopen + dlsym 跳板表**，首次调用时
+打开宿主的 `libelectron.so` 再取真实函数地址。目标宿主的导出数量与接口按发行版实测，不沿用历史计数。
+
+`HIDE_NAPI_AND_UV` 只在两处生效——`include/electron_node/src/js_native_api.h` 与
+`include/electron_node/deps/uv/include/uv.h`，把 `NAPI_EXTERN`/`UV_EXTERN` 从
+`visibility("default")` 翻成 `hidden`。
+
+`HIDE_NAPI_AND_UV` 使缺少定义的引用在链接期失败；未使用该宏且链接允许未定义符号时，
+漏链才可能延迟到装载时失败。不能通过去掉该宏掩盖缺失接口。
+
+## libuv 覆盖边界
+
+只有上述 9 个 uv 函数，不是完整 libuv 转发库。`napi_get_uv_event_loop` 计入 napi，
+不能算作第十个 uv 函数。使用 `llvm-nm --defined-only --extern-only lib/libshim.a` 核对普通符号表，
+不要对静态归档使用 `-D`。内部辅助函数和变量不计入全局 API 数量。
+
+直接调用 uv 的 addon 须比对所需符号、当前 shim 和目标宿主导出；具体覆盖清单、线程安全的
+补充转发源码示例、初始化失败处理及远程目录限制见
+[addon-build.md](../../../skills/pc-knowledge-base/electron/addon-build.md#libuv-补充转发)。补充源码由插件维护，未修改此厂商预编译归档。