@hmos-library-adapter/fast

HarmonyOS 三方库适配/修复/升级统一调度入口。一个 npm 包同时调度「适配」「修复」「升级」三个流程：适配/修复/升级编排器全部随包内嵌分发，用户只装这一个包。

架构

@hmos-library-adapter/fast         ← 用户只装这个（离线可装，依赖内置）
  ├─ depends on @hmos-library-adapter/executer (适配包：3 平台适配 + 升级编排 upgrade-fast + upgrade-{type} 平台编排器)
  └─ depends on @hmos-library/fix              (修复包)

用户只用 hmos-library-adapter-fast 一个 agent 入口，它会自动识别适配 / 修复 / 升级意图并路由分发。升级编排器（upgrade-fast → upgrade-flutter/rn/sdk-fast）随适配子包一起内嵌，由入口按 hmos.detected + .ohos-adaptation/ 产物（kind / upgraded）判断升级意图后路由；未鸿蒙化仓库发起升级时停下提示先适配。

安装方式

安装只注册本包一个插件（~/.config/opencode/plugins/hmos-library-adapter-fast.js，symlink 指向包内 src/plugin.js）。插件启动时自动把适配、修复两个子包的全部 agent（含平台编排器、阶段）一并注入，因此不需要单独再装子包插件。用户只面对 hmos-library-adapter-fast 一个入口。install 会自动把 opencode.json 的 subagent_depth 设为 3（OpenCode v1.18.2+ 默认 1，入口→编排器→阶段需要 3 层子 agent 嵌套；用户已配 >2 时保留用户值）。

DevEco Code（@deveco/deveco-code，OpenCode 同源宿主）同样支持：install 自动写 ~/.config/deveco/plugins/ 下的 file:// 再导出 shim（deveco 自动发现）并向 deveco.json 合并鸿蒙开发者知识 MCP；provider 等用户自有配置不动（deveco schema 不支持 subagent_depth，子代理嵌套深度用 deveco 默认，实测 task 嵌套正常）。

安装（推荐全局）

npm install -g @hmos-library-adapter/fast
hmos-library-adapter-fast install     # 等价别名：hmos-adapter install
hmos-library-adapter-fast doctor      # 等价别名：hmos-adapter doctor

装完重启 OpenCode（DevEco Code 同理，重启后生效）。

可选参数：

• install --target opencode|deveco|both（默认 both，两个宿主都装）；--dry-run 预演不落盘；--force 覆盖同名
• uninstall --target ...；--dry-run

hmos-adapter doctor 会校验裸命令 hmos-adapter / hmos-library-adapter-fast 是否在 PATH（✓ 裸命令在 PATH），缺失时路由器第 1 步会失败。

单包完整安装：只全局安装本包即可——适配子包（@hmos-library-adapter/executer）与修复子包（@hmos-library/fix）均为 bundle 依赖内嵌分发。因 npm 全局只链接根包 bin，本包额外注册了 bin 别名 hmos-library-adapter-executer（转发到本包 CLI，覆盖 hooks / 适配子入口 prompt 依赖的 detect / inject-skills / log-session 等裸命令），无需再单独安装子包。

使用

共同前提：先 cd 到目标库根目录（要适配/修复/升级的 Flutter 插件 / RN 模块 / Android SDK 仓库），再唤起本 agent。本 agent 会自动完成平台识别、意图判定与路由，不需要手动指定平台。

OpenCode

1. 在目标库根目录运行 OpenCode：cd <目标库> && opencode
2. 按 Tab（或在 /agents 中）调出 agent 列表选择 hmos-library-adapter-fast（装完需重启 OpenCode 才会出现在列表）
3. 发指令，示例同上（无需 @ 前缀）

适配这个库到鸿蒙
修复一个闪退问题
升级到 2.2.7（或升级到 https://github.com/x/y）
继续
只重跑某阶段

指令与意图对照

| 你说什么 | 你得到什么 | |---|---| | 适配 / 鸿蒙化（未鸿蒙化仓库）| 走适配流程，按平台 → 适配编排器 → 三阶段 | | 适配 / 鸿蒙化（已鸿蒙化仓库）| 停下询问（检测到已鸿蒙化/升级产物，避免覆盖现有鸿蒙工程）：确认 重新适配 / 升级 / 修复 后再路由 | | 重新适配 / 从头适配 / 重新完整适配 | 已鸿蒙化时明确重做意图 → 直接走适配流程 | | 修复 / 闪退 / 编译错误 / UI 异常 | 走修复流程（库需已鸿蒙化 → 分发修复编排器） | | 升级 / 升级到某版本 / 目标上游 URL（已鸿蒙化）| 走升级流程：upgrade-fast 导向 → 深度类型检测 → 注入 upgrade-{type} 技能 → 可行性判定 → 平台升级编排器两阶段 | | 升级（未鸿蒙化）| 停下提示（升级仅适用于已鸿蒙化库）：「请先完成鸿蒙适配」 | | 继续 | 读 .ohos-adaptation/ 已有产物，从断点继续 | | 「只跑阶段 X / 从阶段 X 开始 / 重新完整适配」 | 原样传参给适配编排器，由它决定起跑点 |

不要直接 @ 子包入口（hmos-library-adapter-executer / hmos-library-fix / upgrade-fast）——装了本包就用本包一个口，升级编排器也在包内自动注入。本包自身也只唤起入口 agent（hmos-library-adapter-executer / upgrade-fast / hmos-library-fix），不越级调平台编排器或阶段子 agent——平台编排器与阶段子 agent 只由入口 agent 按流程唤起。

CLI 命令

hmos-adapter install [--target opencode|both] [--dry-run] [--force]
hmos-adapter uninstall [--target opencode|both] [--dry-run]
hmos-adapter detect [--json]
hmos-adapter inject-skills <flutter|rn|sdk|upgrade-flutter|upgrade-rn|upgrade-sdk>
hmos-adapter fetch-upstream [--dir <CWD>] [--json]
hmos-adapter doctor
hmos-adapter version

fetch-upstream 读 .ohos-adaptation/upgrade-manifest.json 的 upstreamRepo 获取升级目标上游代码到 ../<库名>_upstream（git clone 优先，flutter 可 pub.dev 兜底，本地已有则复用；幂等）。inject-skills 的 upgrade-{type} 由升级编排器在深度类型检测后按需调用。

自动配置 MCP

install 会在 opencode.json（及 DevEco Code 的 deveco.json）自动写入 mcp.harmonyos_developer_knowledge（华为官方开发者知识服务：准实时官方文档检索，供修复/适配流程的外查；需网络）。用户已自定义同名配置则保留不动；uninstall 仅移除未被修改的本工具配置。不想要可手动设 "enabled": false。

安装产物

| 目标 | 产物 | | --- | --- | | OpenCode | ~/.config/opencode/plugins/hmos-library-adapter-fast.js（symlink 指向包内 src/plugin.js；插件运行时注入全部 agent——3 适配平台 + 4 升级编排器 + 修复，共 7 平台；并把子包 skills 注册进 config.skills.paths（15 个 skill）；opencode.json 只留 plugin 引用，不写子包 agent） |

与子包的关系

本包只做统一入口与调度聚合：识别意图后把工作分发给「适配」「修复」子包（升级编排器随适配子包内嵌分发），不参与业务实现。两个子包均未发布 npm，普通用户经本包 bundle 依赖内嵌分发使用；适配子包（@hmos-library-adapter/executer）保留完整单包安装能力（升级编排器同样可用，CLI 命令名为 hmos-library-adapter-executer），但仅限 monorepo 本地安装；修复子包（@hmos-library/fix）不支持单独安装。

卸载

hmos-adapter uninstall
npm rm -g @hmos-library-adapter/fast

然后重启 OpenCode。卸载按 Do No Harm 原则：只删本工具写过的内容（带 managed-by 标记的 agent、指向本包的 plugin symlink、opencode.json 里的 plugin 引用），不影响你自己写的配置。两个子包经本包安装时无独立安装痕迹，卸载本包即全部移除；仅当曾单独本地安装过适配子包（@hmos-library-adapter/executer）时，才需到该子包目录执行其 uninstall 清理独立安装痕迹（plugin / skill 链接）。