@harmonyos-arkts/d2h 0.0.0-stage → 0.1.0

package/skills/native-library-substitution/references/native-library-substitution.md

@@ -0,0 +1,163 @@
+# Native Library Substitution 单一映射表
+
+**数据版本**: 3.0.0
+**更新日期**: 2026-04-22
+
+## 数据概览
+
+| 统计项 | 数量 |
+|--------|------|
+| 总映射数 | 2678 |
+| 有安卓库的映射 | 1005 |
+| 鸿蒙原生库（无安卓库） | 1673 |
+| 唯一安卓库数 | 852 |
+| 唯一ohpm包数 | 2537 |
+
+## source_availability 分布
+
+| 状态 | 数量 | 说明 |
+|------|------|------|
+| COMMERCIAL_PUBLIC | 175 | 闭源商业SDK（来自工作簿） |
+| open_source | 2503 | 开源库 |
+| not_set | 0 | 未设置 |
+
+## source_type 分布
+
+| 来源类型 | 数量 | 说明 |
+|----------|------|------|
+| 鸿蒙原生库 | 1321 | 鸿蒙原生开发，无对应安卓库 |
+| TS/JS迁移库 | 790 | 从npm生态迁移 |
+| 安卓鸿蒙化库 | 432 | 直接从安卓库移植 |
+| C++/C鸿蒙化库 | 133 | 从C++生态迁移 |
+
+## category 分布
+
+| Category | 数量 | 说明 |
+|----------|------|------|
+| other | 1527 | 其他 |
+| ui | 370 | UI组件 |
+| utils | 213 | 工具类 |
+| network | 209 | 网络请求 |
+| media | 89 | 音视频 |
+| auth | 61 | 登录认证 |
+| notification | 60 | 推送通知 |
+| storage | 60 | 存储文件 |
+| location | 50 | 地图定位 |
+| analytics | 17 | 统计分析 |
+| payment | 16 | 支付 |
+| security | 4 | 安全加密 |
+| im | 1 | 即时通讯 |
+| social | 1 | 社交分享 |
+
+## 闭源库示例（COMMERCIAL_PUBLIC）
+
+| 安卓库 | 鸿蒙包 | install_command |
+|--------|--------|-----------------|
+| com.tencent.mm.opensdk:wechat-sdk-androi | @tencent/wechat_open_sdk | `ohpm install @tencent/wechat_open_sdk` |
+| com.sensorsdata.analytics.abtesting:Sens | @sensorsdata/analytics | `ohpm install @sensorsdata/analytics` |
+| cn.admobiletop.adsuyi.ad.adapter:tianmu | @admobile/tianmu | `ohpm install @admobile/tianmu` |
+| cn.admobiletop.adsuyi.ad:core | @admobile/tianmu | `ohpm install @admobile/tianmu` |
+| io.hyphenate:hyphenate-chat | @easemob/chatsdk | `ohpm install @easemob/chatsdk` |
+| com.aliyun.auikits.android:ARTCAICallKit | @aliyun_video_cloud/alivcsdk_artc | `ohpm install @aliyun_video_cloud/alivcsdk_artc` |
+| com.aliyun.iot.aep.sdk:push | @aliyun/push | `ohpm install @aliyun/push` |
+| com.aliyun.rum:alibabacloud-android-rum- | @alibabacloud_rum/harmony_sdk | `ohpm install @alibabacloud_rum/harmony_sdk` |
+| com.alibaba.mtl:app-monitor-sdk | @alibabacloud_rum/harmony_sdk | `ohpm install @alibabacloud_rum/harmony_sdk` |
+| com.aliyun.ams:alicloud-apm-crash-analys | @aliyun/apm | `ohpm install @aliyun/apm` |
+| com.aliyun.dpa:oss-android-sdk | @aliyun/oss | `ohpm install @aliyun/oss` |
+| afservicesdk | @cashier_alipay/cashiersdk | `ohpm install @cashier_alipay/cashiersdk` |
+| com.alipay.sdk:alipaysdk-android | @cashier_alipay/cashiersdk | `ohpm install @cashier_alipay/cashiersdk` |
+| io.github.yidun:livedetect | @yidun/alive | `ohpm install @yidun/alive` |
+| io.github.aliyun-sls:aliyun-log-android- | @aliyun/logger | `ohpm install @aliyun/logger` |
+| com.aliyun.ams:alicloud-android-push | @aliyun/push | `ohpm install @aliyun/push` |
+| com.aliyun.ams:alicloud-android-third-pu | @aliyun/push | `ohpm install @aliyun/push` |
+| com.aliyun.ams:alicloud-android-third-pu | @aliyun/push | `ohpm install @aliyun/push` |
+| com.amap.api:3dmap | @amap/amap_lbs_map3d | `ohpm install @amap/amap_lbs_map3d` |
+| com.amap.api:location | @amap/amap_lbs_location | `ohpm install @amap/amap_lbs_location` |
+| com.amap.api:search | @amap/amap_lbs_search | `ohpm install @amap/amap_lbs_search` |
+| com.amap.api:3dmap-location-search | @amap/amap_lbs_map3d | `ohpm install @amap/amap_lbs_map3d` |
+| com.amap.api:navi-3dmap | @amap/amap_lbs_map3d | `ohpm install @amap/amap_lbs_map3d` |
+| com.umeng.umsdk:analytics | @umeng/analytics | `ohpm install @umeng/analytics` |
+| com.umeng.umsdk:common | @umeng/common | `ohpm install @umeng/common` |
+| BaiduLBS_Android | @bdmap/navi_map | `ohpm install @bdmap/navi_map` |
+| com.baidubce.mediasdk:brtc | @baiduplayer/baidurtcsdk | `ohpm install @baiduplayer/baidurtcsdk` |
+| com.getui:gtsdk | @getui/push | `ohpm install @getui/push` |
+| com.bonree.sdk.jar | @bonree/agent | `ohpm install @bonree/agent` |
+| com.tencent.bugly:crashreport | bugly | `ohpm install bugly` |
+
+*共 175 条闭源库映射*
+
+## 高置信度映射示例（安卓鸿蒙化库）
+
+| 安卓库 | 鸿蒙包 | category | install_command |
+|--------|--------|----------|-----------------|
+| AJCaptcha 安卓实现版本 | @scca/verification | other | `ohpm install @scca/verification` |
+| ARouter | @ohos/arouteronactivityresult | other | `ohpm install @ohos/arouteronactivityresult` |
+| ARouter | hrouter | other | `ohpm install hrouter` |
+| Android Beacon Library (AltBea | @ohos/beacon-library | other | `ohpm install @ohos/beacon-library` |
+| Android BottomSheet | @hld/bottomsheet | other | `ohpm install @hld/bottomsheet` |
+| Android Jetpack Paging3 | @jackiehou/experimental-paging | other | `ohpm install @jackiehou/experimental-paging` |
+| Android Room | @hzzmkjyxgs/zmwlthmosdb | other | `ohpm install @hzzmkjyxgs/zmwlthmosdb` |
+| Android TabLayout（com.google.a | @zyc/tablayout | other | `ohpm install @zyc/tablayout` |
+| Android XLog | @ohos-port/xlog-ts | other | `ohpm install @ohos-port/xlog-ts` |
+| Android-Debug-Database | @hadss/debug-db | other | `ohpm install @hadss/debug-db` |
+| AndroidImageEditor | @zhongjh/image_edit | other | `ohpm install @zhongjh/image_edit` |
+| AndroidUtilCode | @android_x/utilcode | other | `ohpm install @android_x/utilcode` |
+| AndroidUtilCode | @ilye/utilcode | other | `ohpm install @ilye/utilcode` |
+| AndroidUtilCode | @ranran/utilcode | other | `ohpm install @ranran/utilcode` |
+| AndroidVideoCache | @changjing/drm | media | `ohpm install @changjing/drm` |
+| AndroidVideoCache (com.danikul | @ohos/video-cache | media | `ohpm install @ohos/video-cache` |
+| Apache Batik | @ohos/xmlgraphicsbatik | other | `ohpm install @ohos/xmlgraphicsbatik` |
+| Apache Cordova Android | @boc/cordova | other | `ohpm install @boc/cordova` |
+| AppCan Android Engine | @appcan/engine | other | `ohpm install @appcan/engine` |
+| DBFlow | @ohos/dataorm | other | `ohpm install @ohos/dataorm` |
+
+*共 340 条高置信度安卓鸿蒙化库映射*
+
+## 鸿蒙原生库示例（无安卓库）
+
+| 鸿蒙包 | 组织 | category | install_command |
+|--------|------|----------|-----------------|
+| @pura/harmony-utils | pura | notification | `ohpm install @pura/harmony-utils` |
+| @pura/harmony-dialog | pura | ui | `ohpm install @pura/harmony-dialog` |
+| @ibestservices/ibest-ui | ibestservices | ui | `ohpm install @ibestservices/ibest-ui` |
+| @abner/refresh | abner | ui | `ohpm install @abner/refresh` |
+| @hzw/zrouter | hzw | other | `ohpm install @hzw/zrouter` |
+| cjcalendar |  | ui | `ohpm install cjcalendar` |
+| @hadss/hmrouter | hadss | other | `ohpm install @hadss/hmrouter` |
+| @esky/barrage | esky | media | `ohpm install @esky/barrage` |
+| @ibestservices/ibest-ui-v2 | ibestservices | ui | `ohpm install @ibestservices/ibest-ui-v2` |
+| @ohos/pulltorefresh | ohos | ui | `ohpm install @ohos/pulltorefresh` |
+| @mcui/mccharts | mcui | utils | `ohpm install @mcui/mccharts` |
+| @maple/navigationbarview | maple | location | `ohpm install @maple/navigationbarview` |
+| @abner/dialog | abner | ui | `ohpm install @abner/dialog` |
+| @zyl/wxcommonlibhar | zyl | payment | `ohpm install @zyl/wxcommonlibhar` |
+| @ibestservices/ibest-orm | ibestservices | storage | `ohpm install @ibestservices/ibest-orm` |
+| @ohasasugar/hp-richtext | ohasasugar | ui | `ohpm install @ohasasugar/hp-richtext` |
+| @zyl/commonlibhar | zyl | media | `ohpm install @zyl/commonlibhar` |
+| @abner/datastore | abner | storage | `ohpm install @abner/datastore` |
+| @visactor/harmony-vchart | visactor | other | `ohpm install @visactor/harmony-vchart` |
+| @liushengyi/smartdb | liushengyi | storage | `ohpm install @liushengyi/smartdb` |
+
+*共 1673 条鸿蒙原生库*
+
+## 数据结构
+
+每条映射记录包含15个字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| android_lib | string/null | 安卓库标识符（鸿蒙原生库为null） |
+| android_platform | string | android / ios / ohos_native |
+| android_description | string/null | 安卓库功能描述 |
+| ohpm_package | string | 鸿蒙包名 |
+| ohpm_org | string | ohpm组织名 |
+| ohpm_description | string | 鸿蒙包功能描述 |
+| ohpm_keywords | array | 鸿蒙包关键词 |
+| ohpm_repo_url | string | 鸿蒙包源码仓库 |
+| ohpm_homepage | string | 鸿蒙包文档主页 |
+| source_type | string | 安卓鸿蒙化库/TS迁移库/鸿蒙原生库 |
+| source_availability | string | COMMERCIAL_PUBLIC/open_source |
+| confidence | string | high/medium/low |
+| install_command | string | ohpm install命令 |
+| category | string | media/network/notification等 |
+| inference_reason | string | 映射关系说明 |

package/skills/preparing-migration-workspace/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: preparing-migration-workspace
+description: 在 Android 转 HarmonyOS 迁移开始或恢复时，通过 droid2hmos 执行统一 Preflight，并依据 CLI 返回结果和报告决定是否进入事实扫描与实现。也用于配置、Git checkpoint、构建测试、AppGraph 分析和设备检查。
+---
+
+# 准备迁移工作区
+
+本 Skill 只编排 `droid2hmos` 和独立的 `appgraph` CLI，不直接调用 Node 脚本、Gradle、Hvigor、Hypium、ADB 或 HDC。不要在 `ohos/` 尚不存在时猜测 HarmonyOS 构建配置。
+
+迁移产物（`.migration/`）统一位于安卓工程父目录下的 `<工程名>-migration/.migration/`，由 CLI 自动创建和维护，不写入安卓工程内部。创建 `.migration/` 时 CLI 会自动在工作区根目录生成 `.gitignore`（内容 `.migration/`），防止迁移产物被上层 Git 仓库提交到远端。下文所有 `.migration/...` 路径均相对该工作区根目录。
+
+开始或恢复时先获取只读事实快照：
+
+```text
+droid2hmos status <ANDROID_PROJECT>
+```
+
+使用 `completion.unmet` 识别缺口，使用 `allowedActions` 选择当前可安全调用的命令。`phase` 只解释当前现场，不是必须手工推进的状态；不得创建或编辑 `.migration/state.json`。
+
+传入路径必须是 Android Gradle 工程根目录：根目录应有 Gradle 标记，并且应用模块中应有 `AndroidManifest.xml`。如果 `workspace.projectPresent=false` 且 `workspace.projectCandidates` 非空，说明传入的是包装目录；改用列出的明确候选工程，不得在包装目录初始化第二套 `.migration` 或 HarmonyOS 工程。
+
+## 首次执行
+
+运行统一门禁：
+
+```text
+droid2hmos preflight <ANDROID_PROJECT> [--sdk-path <PATH>] [--timeout-ms <MS>]
+```
+
+`preflight` 负责选择检查项、判定检查项是否阻塞，并生成完整结果，包括：
+
+- Android UI 技术栈支持性；
+- Git 仓库、分支、`HEAD` 和工作区干净状态；
+- Git、Node.js 20-24、npm、Python 3.10+、JDK、Android SDK 和 DevEco 工具链；
+- `appgraph --version` 及迁移分析能力健康检查；
+- `.migration/config.json` 初始化和校验；
+- Android 基线状态及设备检查；
+- 已有 HarmonyOS 工程复用，或在目标为空时创建可编译工程壳；
+- HarmonyOS SDK 探测、应用 HAP 基线构建和必须通过的 HDC 设备检查；
+- `.migration/preflight-report.json` 原子生成。
+
+已有 HarmonyOS 工程不得被覆盖。只想校验现有工程、不允许初始化工程壳时加 `--no-init-harmony`。命令失败后读取报告中的 `failedChecks`、`retry` 和对应日志；只有 `transient/bounded` 允许在给出的上限内原样重试，其余失败必须先改变输入或环境，不得绕过门禁继续事实扫描或实现。
+
+环境类门禁（`toolchain`、`devecocli-auth`、`appgraph`、`harmony-sdk`、`harmony-device`）只探测一次：它们依赖本机工具、华为账号授权或物理设备，原样重跑 `preflight` 不会自愈。这类失败会返回 `retry.kind=external` 且带 `remediation`；必须把 `remediation` 明确转述给用户、等待用户修改环境，不得在同一环境下连续重跑 `preflight`。其余（非环境类）失败在按 `retry` 指引改变输入后重跑。
+
+本 Skill 不单独定义或重算任何子检查门禁。命令成功且报告总体结果为 `passed` 时继续。
+
+## 语言资源基线清点
+
+Preflight 通过后、进入事实扫描与批次规划前，对 Android 工程做一次只读语言清点（文件枚举，不涉及构建）：列出各应用模块 `src/*/res/` 下带语言/地区限定符的 `values-<locale>` 目录（如 `values-zh`、`values-en-rUS`、`values-b+es+419`；排除 `night`、`land`、`v<N>`、`sw<N>dp` 等非语言限定符），记录语言清单与数量。该清点结果是规划的强制输入：
+
+- 语言数 > 1：实现批次必须包含 i18n 资源迁移批次，该批次开始前加载 `arkts-i18n` skill，按其目录规范迁移全部语言；
+- 语言数 = 1：也须在写入首个字符串资源前加载 `arkts-i18n` 确认资源组织方式；
+- 任何情况下不得把用户可见文案硬编码进页面代码来替代字符串资源迁移。
+
+## 配置与测试
+
+需要显式提供项目特有的 Android 命令时，先运行：
+
+```text
+droid2hmos config init <ANDROID_PROJECT> [--harmony-project <PATH>] [--android-build <COMMAND>] [--android-test <COMMAND>]
+droid2hmos config validate <ANDROID_PROJECT>
+```
+
+配置中只保存 Android 侧有限命令和能够确认的路径。不得保存或猜测 `harmonyBuild`、`harmonyTest`、module、product 或 target；HarmonyOS 参数由 CLI 从真实工程配置解析。
+
+`androidBuild` 默认为 null：迁移流程不编译 Android 工程，`analyze android` 是纯源码静态分析且不要求 APK。只有用户明确要求 Android/HarmonyOS 双端运行对照时，才通过 `--android-build` 显式配置构建命令；未配置时执行 `droid2hmos build android` 会返回引导提示而非自动探测。
+
+在首次 Preflight 之后需要针对性诊断或验证时使用：
+
+```text
+droid2hmos build <android|harmony|all> <ANDROID_PROJECT> [--timeout-ms <MS>]
+droid2hmos test android <ANDROID_PROJECT> [--task <TASK>] [--timeout-ms <MS>]
+droid2hmos test harmony <ANDROID_PROJECT> (--class <CLASS> [--case <CASE>] | --all) [--target <DEVICE>] [--case-timeout-ms <MS>] [--ref <REPORT_REF>...]
+```
+
+Android 测试只有在 `.migration/config.json` 已声明可执行的 `androidTest` 时运行。HarmonyOS 测试只有在已有 Hypium 测试资产时运行；没有测试资产时记录缺口，并在第一个可交互功能验收前建立。多个 HDC 目标可响应时必须显式传 `--target`，防止证据偶然落在另一台设备。`--case-timeout-ms` 控制单个 Hypium 用例超时，`--ref` 只声明该测试实际断言的报告项。CLI 会解析 Hypium 摘要：失败、错误、忽略、零执行或缺少摘要即使 HDC 退出码为零也视为失败。
+
+Hvigor 返回成功但没有刷新输出时，CLI 只复用不早于各自构建输入的既有应用/ohosTest HAP；应用源码变化只要求应用 HAP 更新，不会强制无关的 ohosTest HAP 重打。产物比对应源码或构建配置旧时必须失败并要求修复构建，而不是安装过期包。
+
+## 分析与设备诊断
+
+Android 和 HarmonyOS 分析统一使用：
+
+```text
+droid2hmos analyze <android|harmony|all> <ANDROID_PROJECT>
+```
+
+CLI 负责调用 PATH 中的 `appgraph`，HarmonyOS 分析自动读取配置里的 SDK 路径。只有统一命令失败且需要定位工具缺陷时，才直接运行 `appgraph --version` 或查看其帮助；不得自行拼接内部分析参数作为正常工作流。
+
+需要单独复查设备时使用：
+
+```text
+droid2hmos device check <android|harmony>
+```
+
+Android 设备缺失是可记录的增强项；HarmonyOS 设备必须可被发现且 Shell 可响应，否则停止需要设备证据的流程。
+
+## 恢复执行与 Git checkpoint
+
+恢复迁移时不得重新初始化已有 `ohos/`。先运行：
+
+```text
+droid2hmos status <ANDROID_PROJECT>
+droid2hmos checkpoint status <ANDROID_PROJECT>
+droid2hmos config validate <ANDROID_PROJECT>
+```
+
+然后只重跑快照显示为缺失或因源码指纹变化而失效的 `build`、`test`、`device check` 或 `analyze`。如果工具链、AppGraph、工程壳或基础环境可能变化，则重新运行完整 `preflight`。`.migration/` 运行态文件不会让重复 Preflight 自己判定工作区变脏；已有配置中尚未纳入 Git 的 HarmonyOS 目录可作为上次预检生成物忽略，但首次运行前就存在的未跟踪 `ohos/` 和该目录内已有的 tracked 变更仍然阻塞，不能借此隐藏用户改动。
+
+完成一个经验证的迁移单元后，只提交明确列出的文件：
+
+```text
+droid2hmos checkpoint create <ANDROID_PROJECT> --message <MESSAGE> --include <PATH> [--include <PATH>...]
+```
+
+仅在调用者明确要求纳入全部相关变更时使用 `--all`。即使使用 `--all`，`.migration/` 运行态和证据归档也不会进入提交。不得处理、覆盖或删除用户已有改动；生成的 AppGraph、命令日志和预检日志不进入检查点。显式路径暂存失败时命令会撤销本次新加入暂存区的文件，并保留调用前已经暂存的内容。
+
+## 继续条件
+
+- `droid2hmos preflight` 成功退出；
+- `.migration/preflight-report.json` 已生成且总体结果为 `passed`。
+
+各检查项的 `required`、`status` 和最终阻塞关系以本次 CLI 输出及报告为唯一依据，Skill 不重复推导通过条件。

package/skills/preparing-migration-workspace/toolchain.json

@@ -0,0 +1,43 @@
+{
+  "orchestrator": {
+    "command": "droid2hmos",
+    "preflight": ["preflight"],
+    "requiredCapabilities": [
+      "status",
+      "complete",
+      "config init",
+      "config validate",
+      "checkpoint status",
+      "checkpoint create",
+      "build android",
+      "build harmony",
+      "test android",
+      "test harmony",
+      "device check android",
+      "device check harmony",
+      "analyze android",
+      "analyze harmony",
+      "evidence capture",
+      "evidence flow",
+      "evidence compare",
+      "report init",
+      "report update",
+      "report validate",
+      "report render",
+      "mock init",
+      "service start",
+      "service status",
+      "service stop",
+      "logs list",
+      "logs show",
+      "logs failures",
+      "logs stats"
+    ]
+  },
+  "appgraph": {
+    "command": "appgraph",
+    "versionProbe": ["--version"],
+    "healthProbe": ["spec-analysis", "--help"],
+    "managedBy": "droid2hmos preflight"
+  }
+}

package/skills/reviewing-migration-process/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: reviewing-migration-process
+description: Review a completed or explicitly stopped Android-to-HarmonyOS migration and write concise, evidence-backed suggestions for humans who maintain the migration Agent, Skills, scripts, and workflow. Do not use for ordinary implementation progress or technical migration lessons.
+---
+
+# Review the migration process
+
+Create or update `<android-project>-migration/.migration/agent-feedback.md` (in the sibling migration workspace next to the Android project, not inside it) only when the migration has completed or the current run has explicitly stopped. The file is a human review input, not a migration gate and not an instruction source for later migration Agents.
+
+## Scope
+
+Record problems in the migration system itself:
+
+- workflow stalls, excessive latency, or avoidable human intervention;
+- repeated reads, builds, installs, tests, or reverted implementation attempts;
+- Agent decisions that violated task boundaries or diverged from Android evidence;
+- missing, unreliable, or unclear scripts and tool outputs;
+- inputs that were too large, duplicated, missing, or provided too late;
+- concrete changes that could improve an Agent prompt, Skill, script, input artifact, workflow, or gate.
+
+Do not repeat application implementation status or the migration report. Do not place reusable Android/HarmonyOS technical solutions here; verified technical migration knowledge belongs in `.migration/experience/lessons.md`. A single incident may produce both records only when their perspectives differ: this file describes how the migration system should improve, while the lesson describes a verified technical solution.
+
+## Evidence and judgment
+
+- Before writing the review, inspect the managed execution record with `droid2hmos logs stats <android-project>` and `droid2hmos logs failures <android-project>`. Use `droid2hmos logs list <android-project> [YYYY-MM-DD]` and `droid2hmos logs show <android-project> <run-id>` only for runs relevant to a finding.
+- Run `droid2hmos checkpoint status <android-project>` to record whether the run ended with explained changes or an unexpected dirty worktree.
+- Base every finding on an observed command, log, artifact, commit, rework, or user intervention from this run.
+- Separate observation from inferred root cause. Mark an uncertain cause as a hypothesis.
+- Do not write generic advice such as “be more careful”. Name the exact optimization target and proposed change.
+- Do not automatically modify the plugin based on this file. A human decides whether to accept each suggestion.
+- Merge duplicate symptoms into one finding. Keep at most the five highest-impact findings.
+- If there is no evidence-backed improvement, write `本次未发现需要提交给 Agent 维护者的优化建议。`
+
+## Output
+
+Use concise Chinese Markdown:
+
+```markdown
+# Agent 优化建议
+
+## 本次运行概况
+
+- 结果：完成 | 中止
+- 主要耗时或阻塞：
+- 人工介入：
+
+## 优先建议
+
+### AF-001：简短问题名称
+
+- 优先级：P0 | P1 | P2
+- 阶段：
+- 现象：
+- 证据：日志、命令、文件或提交路径
+- 影响：
+- 根因：已确认 | 假设，并说明原因
+- 优化位置：Agent | Skill | 脚本/工具 | 输入产物 | 流程 | 门禁
+- 建议：可执行的修改
+- 通用性：仅本项目 | 多项目通用
+```
+
+Use P0 only when the issue can block the whole workflow, corrupt work, or falsely declare migration success. Keep the overview factual; do not calculate metrics that were not captured by tools.

package/src/install-opencode.mjs

@@ -0,0 +1,108 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+function stat(file) {
+  try { return fs.lstatSync(file); } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function sameTree(source, destination) {
+  const left = stat(source);
+  const right = stat(destination);
+  if (!left || !right) return false;
+  if (left.isSymbolicLink() || right.isSymbolicLink()) {
+    if (!left.isSymbolicLink() || !right.isSymbolicLink()) return false;
+    return fs.readlinkSync(source) === fs.readlinkSync(destination);
+  }
+  if (left.isDirectory() && right.isDirectory()) {
+    const names = fs.readdirSync(source).sort();
+    const otherNames = fs.readdirSync(destination).sort();
+    return names.length === otherNames.length && names.every((name, index) =>
+      name === otherNames[index] && sameTree(path.join(source, name), path.join(destination, name)));
+  }
+  return left.isFile() && right.isFile() && fs.readFileSync(source).equals(fs.readFileSync(destination));
+}
+
+function contains(parent, child) {
+  const relative = path.relative(parent, child);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+// Resolve existing ancestors too, including a config directory beneath a junction.
+function resolvedLocation(directory) {
+  if (fs.existsSync(directory)) return fs.realpathSync(directory);
+  const parent = path.dirname(directory);
+  return parent === directory ? directory : path.join(resolvedLocation(parent), path.basename(directory));
+}
+
+export function installOpenCode({ sourceDir, configDir, link = false, force = false, dryRun = false, log = console.log }) {
+  if (!configDir || ['.', '..'].includes(configDir)) throw new Error(`refusing unsafe OpenCode config directory: ${configDir}`);
+  const sourceRoot = fs.realpathSync(path.resolve(sourceDir));
+  const configRoot = resolvedLocation(path.resolve(configDir));
+  if (configRoot === path.parse(configRoot).root || configRoot === fs.realpathSync(os.homedir()) ||
+      contains(sourceRoot, configRoot) || contains(configRoot, sourceRoot)) {
+    throw new Error(`refusing unsafe OpenCode config directory: ${configDir}`);
+  }
+  const entries = [];
+  for (const kind of ['skills', 'agents']) {
+    const source = path.join(sourceRoot, kind);
+    if (!fs.statSync(source).isDirectory()) throw new Error(`${kind} directory not found: ${source}`);
+    const destinationRoot = path.join(configRoot, kind);
+    if (stat(destinationRoot)?.isSymbolicLink()) throw new Error(`refusing linked installation directory: ${destinationRoot}`);
+    let count = 0;
+    for (const name of fs.readdirSync(source).sort()) {
+      const entrySource = path.join(source, name);
+      if (kind === 'skills' ? !fs.existsSync(path.join(entrySource, 'SKILL.md')) :
+          !name.endsWith('.md') || !fs.statSync(entrySource).isFile()) continue;
+      count++;
+      const destination = path.join(destinationRoot, name);
+      let unchanged = false;
+      if (link && stat(destination)?.isSymbolicLink()) {
+        unchanged = path.resolve(path.dirname(destination), fs.readlinkSync(destination)) === entrySource;
+      } else if (!link) {
+        unchanged = sameTree(entrySource, destination);
+      }
+      if (!unchanged && stat(destination) && !force) {
+        throw new Error(`${kind} '${name}' already exists at ${destination}; rerun with --force to replace it`);
+      }
+      entries.push({ kind, name, source: entrySource, destination, unchanged });
+    }
+    if (!count) throw new Error(`no ${kind} found under ${source}`);
+  }
+  for (const entry of entries) {
+    if (entry.unchanged) { log(`unchanged ${entry.kind}: ${entry.name}`); continue; }
+    if (dryRun) { log(`would install ${entry.kind}: ${entry.source} -> ${entry.destination} (${link ? 'link' : 'copy'})`); continue; }
+    const parent = path.dirname(entry.destination);
+    fs.mkdirSync(parent, { recursive: true });
+    if (!contains(configRoot, fs.realpathSync(parent))) throw new Error(`installation escaped config directory: ${parent}`);
+    const staging = fs.mkdtempSync(path.join(parent, '.migration-install-'));
+    const staged = path.join(staging, 'new');
+    const backup = path.join(staging, 'backup');
+    try {
+      if (link) fs.symlinkSync(entry.source, staged, process.platform === 'win32' && entry.kind === 'skills' ? 'junction' : undefined);
+      else fs.cpSync(entry.source, staged, { recursive: true });
+      if (stat(entry.destination)) fs.renameSync(entry.destination, backup);
+      try { fs.renameSync(staged, entry.destination); } catch (error) {
+        if (stat(backup)) fs.renameSync(backup, entry.destination);
+        throw error;
+      }
+    } finally {
+      // If restoring a replaced entry also failed, retain its backup for recovery.
+      if (stat(backup) && !stat(entry.destination)) {
+        log(`installation backup retained: ${backup}`);
+      } else {
+        fs.rmSync(staging, { recursive: true, force: true });
+      }
+    }
+    log(`installed ${entry.kind}: ${entry.destination}`);
+  }
+  const skills = entries.filter(entry => entry.kind === 'skills').length;
+  const agents = entries.filter(entry => entry.kind === 'agents').length;
+  log(`${dryRun ? 'OpenCode installation preview' : 'OpenCode installation complete'}: ${skills} skill(s), ${agents} agent(s).`);
+  log(`Config directory: ${configRoot}`);
+  if (!dryRun) log('Quit and restart OpenCode to load the installed definitions.');
+  return { skills, agents, configRoot };
+}