# 鸿蒙三方库适配 / Flutter

[![npm](https://img.shields.io/badge/npm-%40hmos--library--adapter%2Fflutter-cb3837)](https://www.npmjs.com/package/@hmos-library-adapter/flutter)

npm 包名 `@hmos-library-adapter/flutter`，CLI 命令 `hmos-library-adapter-flutter`。将 Flutter 插件自动适配到 HarmonyOS（OpenHarmony）的多阶段 agent 流水线，可同时安装到 [OpenCode](https://opencode.ai) 与 [Claude Code](https://claude.com/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 工程构建与视觉测试
- 适配总结报告 + 集成指南

## 安装

```bash
# 同时装到 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` 精确回滚。

## 端到端验证

```bash
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 份阶段产物
```
