鸿蒙三方库适配 / Flutter

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

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

功能

5 个串行阶段（analysis → planning → coding-library → testing → summary）+ 3 个子 agent（doc-search、ohpm-api-verify、completeness-check），覆盖：

• 插件类型识别、Channel 与依赖分析
• 鸿蒙 API 映射方案制定（含 SDK 文档与生态合规检索）
• ETS 代码编写与编译修复
• Example 工程构建与视觉测试
• 适配总结报告 + 集成指南

安装

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

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

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

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

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

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

安装位置：

| 资源 | 位置 | |------|------| | 共享数据目录 | ~/.local/share/hmos-library-adapter-flutter/ | | Skills（软链） | ~/.local/share/hmos-library-adapter-flutter/skills/<name> → 包内 shared/skills/<name> | | 渲染后的 prompts | ~/.local/share/hmos-library-adapter-flutter/prompts/<name>.md | | 阶段 schema 文件 | ~/.local/share/hmos-library-adapter-flutter/schemas/<stage>.schema.json（从 CLI bundle 释放，供 agent Read） | | OpenCode 入口 | merge 到 ~/.config/opencode/opencode.json 的 agent 字段 | | ClaudeCode 入口 | ~/.claude/agents/hmos-library-adapter-flutter.md（对外）+ ~/.claude/agents/hmos-flutter-*.md（8 个内部）+ ~/.claude/settings.json 自动注入 PostToolUse hook |

触发

进入目标 Flutter 插件根目录（必须含 pubspec.yaml），分别在两个宿主中触发：

OpenCode

@hmos-library-adapter-flutter 请把当前 Flutter 插件适配到 HarmonyOS

Claude Code

@hmos-library-adapter-flutter 请把当前 Flutter 插件适配到 HarmonyOS

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

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

仓库结构

hmos-library-adapter-flutter/
├── shared/                        # 单一事实源
│   ├── prompts/                   # 9 个阶段 prompt 模板（含 {{SKILLS_DIR}} 占位）
│   ├── skills/                    # 10 个 skill 资源目录
│   └── AGENTS.md                  # 全局规则
├── adapters/
│   ├── opencode/
│   │   └── opencode.template.json # 模板，{{PROMPTS_DIR}} 在 install 时替换
│   └── claudecode/
│       ├── agents/                # 唯一对外 subagent（hmos-library-adapter-flutter）
│       └── agents-internal/       # 8 个内部 subagent（INTERNAL 标注）
├── src/cli/                       # 安装器
│   ├── index.mjs                  # 命令路由（install/uninstall/doctor）
│   ├── install.mjs                # 双宿主安装核心
│   ├── render.mjs                 # 模板渲染 + agent 名替换
│   ├── manifest.mjs               # 安装清单
│   ├── paths.mjs                  # 平台目录解析
│   └── targets/{opencode,claudecode}.mjs
└── bin/
    └── hmos-library-adapter-flutter.mjs     # CLI 入口

设计要点

• 单一事实源：shared/ 同时驱动两个宿主，避免双份维护。Skills 通过 symlink 共享。
• 占位符渲染：prompt 模板中的 {{SKILLS_DIR}} 在 install 时被替换为绝对路径；OpenCode/ClaudeCode 看到的都是平台无关的资源访问方式。
• ClaudeCode 端最小暴露面：只对外 hmos-library-adapter-flutter；其余 8 个 agent 在 description 中标注 INTERNAL，引导 ClaudeCode 不主动选用。
• 冲突保护：install 默认拒绝覆盖宿主已存在的同名 agent；用 --force 强制覆盖。
• 干净卸载：通过 ~/.local/share/hmos-library-adapter-flutter/install-manifest.json 精确回滚。

端到端验证

git clone https://github.com/matfire/bluetooth_classic /tmp/bluetooth_classic
cd /tmp/bluetooth_classic
bunx @hmos-library-adapter/flutter install
# 在 OpenCode 或 ClaudeCode 中触发 @hmos-library-adapter-flutter
# 检查 .ohos-adaptation/ 5 份阶段产物