鸿蒙三方库适配 / React Native

npm 包名 @hmos-library-adapter/rn，CLI 命令 hmos-library-adapter-rn。将 React Native 模块自动适配到 HarmonyOS（OpenHarmony）的多阶段 agent 流水线，可同时安装到 OpenCode 与 Claude Code 两个宿主。

系列：鸿蒙三方库适配（Flutter 等其它平台以 @hmos-library-adapter/<platform> 形式发布）。

功能

5 个串行阶段（analysis → planning → coding-library → testing → summary）+ 7 个子 agent（doc-search、coding-research、code-review、static-analysis、integration-test、lib-fixer、adapted-library），覆盖：

• 模块类型识别、TurboModule/Fabric 与依赖、权限分析
• 鸿蒙 API 映射方案制定（含 SDK 文档与已适配库检索）
• ETS/C++ 代码编写与编译修复
• Example 工程生成、HAP 编译与设备验证
• 适配总结报告 + 集成指南

安装

# 同时装到 OpenCode + ClaudeCode
bunx @hmos-library-adapter/rn install

# 仅装一个宿主
bunx @hmos-library-adapter/rn install --target opencode
bunx @hmos-library-adapter/rn install --target claudecode

# dry-run 预览
bunx @hmos-library-adapter/rn install --dry-run

# 验证安装状态
bunx @hmos-library-adapter/rn doctor

# 卸载
bunx @hmos-library-adapter/rn uninstall

安装后 CLI 命令名是 hmos-library-adapter-rn，可直接调用：hmos-library-adapter-rn doctor。

安装位置：

| 资源 | 位置 | |------|------| | 共享数据目录 | ~/.local/share/hmos-library-adapter-rn/ | | Skills（软链） | ~/.claude/skills/<name>（OpenCode 端 ~/.config/opencode/skills/）→ 包内 shared/skills/<name> | | OpenCode 入口 | symlink ~/.config/opencode/plugins/hmos-library-adapter-rn.js → 包内 dist/plugin.js，并 merge ~/.config/opencode/opencode.json 的 agent 字段 | | ClaudeCode 入口 | ~/.claude/agents/hmos-library-adapter-rn.md（对外）+ ~/.claude/agents/hmos-rn-*.md（12 个内部）+ ~/.claude/settings.json 自动注入 hooks |

触发

进入目标 React Native 模块根目录（必须含 package.json），分别在两个宿主中触发：

OpenCode

@hmos-library-adapter-rn 请把当前 RN 模块适配到 HarmonyOS

入口 agent 为 mode: all，既可用 @ 唤起，也可用 Tab 切换。调试单个阶段 agent 同理：@hmos-rn-01-analysis、@hmos-rn-03-coding-library 等。

Claude Code

@hmos-library-adapter-rn 请把当前 RN 模块适配到 HarmonyOS

入口 agent 会按门禁顺序串调 5 个阶段子 agent，产物写入 CWD/.rn-ohos-adaptation/：

.rn-ohos-adaptation/
├── 01-analysis.json + 01-analysis-report.md + 01-analysis-prd.md
├── 02-planning.json + 02-planning-report.md
├── 03-coding-library.json + 03-coding-library-report.md
├── 04-testing.json + 04-testing-report.md
├── 05-summary.json + 05-summary-report.md
└── INTEGRATION_GUIDE.md

仓库结构

hmos-library-adapter-rn/
├── shared/                        # 单一事实源
│   ├── prompts/                   # 阶段 prompt 模板（含 {{SKILLS_DIR}} 占位）
│   ├── skills/                    # 20 个 skill 资源目录
│   └── AGENTS.md                  # 全局规则
├── adapters/
│   ├── opencode/
│   │   └── opencode.template.json # 模板，agent 定义在 install 时注入
│   └── claudecode/
│       ├── agents/                # 唯一对外 subagent（hmos-library-adapter-rn）
│       └── agents-internal/       # 12 个内部 subagent（INTERNAL 标注）
├── src/
│   ├── cli/
│   │   ├── commands/              # install/uninstall/doctor/gate/advance/context/report/validate-on-write
│   │   ├── lib/                   # 模板渲染 / schema 校验 / hook 注入 / skill 软链
│   │   └── paths.ts               # 平台目录解析
│   ├── plugin/                    # OpenCode Plugin 入口
│   ├── prompt-builder/            # Prompt 构建逻辑
│   └── schemas/                   # 阶段产物 JSON Schema
└── dist/
    ├── plugin.js                  # OpenCode Plugin 入口（构建产物）
    └── hmos-library-adapter-rn.js # CLI 入口（构建产物）

设计要点

• 单一事实源：shared/ 同时驱动两个宿主，避免双份维护。Skills 通过 symlink 共享。
• 占位符渲染：prompt 模板中的 {{SKILLS_DIR}} 在 install 时被替换为绝对路径；OpenCode/ClaudeCode 看到的都是平台无关的资源访问方式。
• ClaudeCode 端最小暴露面：只对外 hmos-library-adapter-rn；其余 12 个 agent 在 description 中标注 INTERNAL，引导 ClaudeCode 不主动选用。
• 门禁驱动编排：orchestrator 通过 hmos-library-adapter-rn advance/gate 代码侧门禁判断，不靠 LLM 记忆或推理；任一阶段失败即停下，不自动重试、不污染后续产物。
• PostWrite 自动校验：通过 write/edit 写入阶段产物 JSON 时自动触发 schema 校验 + Markdown 报告生成。
• 冲突保护：install 默认拒绝覆盖宿主已存在的同名 agent；用 --force 强制覆盖。
• 干净卸载：通过 ~/.local/share/hmos-library-adapter-rn/install-manifest.json 精确回滚。

端到端验证

cd <你的 RN 模块根目录>      # 必须含 package.json
bunx @hmos-library-adapter/rn install
# 在 OpenCode 或 ClaudeCode 中触发 @hmos-library-adapter-rn
# 检查 .rn-ohos-adaptation/ 5 份阶段产物

开发调试

修改本插件源码时，无需全局安装，用 node 直接运行构建产物：

npm install && npm run build
node dist/hmos-library-adapter-rn.js doctor
node dist/hmos-library-adapter-rn.js install --target claudecode --force
node dist/hmos-library-adapter-rn.js uninstall --target both    # 清理调试环境
npm run typecheck       # TypeScript 类型检查
npm run lint:prompts    # Prompt lint 检查