支持 mac 平台功能；新增插件改造任务；

.gitignore

@@ -11,6 +11,8 @@
 .svn/
 .swiftpm/
 migrate_working_dir/
+.metadata
+.cursorrules
 
 # IntelliJ related
 *.iml

.pubignore

@@ -0,0 +1,11 @@
+AGENTS.md
+example/AGENTS.md
+ARCHITECTURE_REFACTOR_PLAN.yaml
+PLUGIN_QUALITY_ROADMAP.md
+workflow_context.md
+.cursorrules
+.idea/
+*.iml
+plan/
+scripts/
+integration/channel/contracts/macos_battery_evolution_plan.yaml

AGENTS.md

@@ -1,11 +1,12 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
-- `lib/`: Dart API; `flutter_battery.dart` exposes `FlutterBattery`, and the platform interface plus MethodChannel default live alongside it.
-- `android/`, `ios/`: Native implementations; keep channel names and payloads in sync with the Dart interface and avoid committing `build/`.
-- `example/`: Demo app for manual QA and showcasing notifications; run it on a device/emulator to validate flows.
-- `test/`: Unit tests (`*_test.dart`) covering public API and channel behavior.
-- `integration/channel/contracts/channel_contract.yaml`: Contract for method/event channels; edit together with Dart and native changes.
+- `lib/`: Dart API; `flutter_battery.dart` exposes `FlutterBattery` + typed models; `lib/src/` holds internal contracts (`battery_channel_contract.dart`) and platform capability models (`platform_capabilities.dart`). `flutter_battery_platform_interface.dart` and `flutter_battery_method_channel.dart` live alongside it.
+- `android/`: Native implementation. Channel names and payloads must stay in sync with `lib/src/battery_channel_contract.dart`. Avoid committing `build/`.
+- `macos/`: macOS native implementation. Explicitly returns unsupported capabilities via `getPlatformCapabilities` for notifications/BLE/peer sync.
+- `example/`: Demo app for manual QA and showcasing notifications. IoT demo (`iot/native`, `iot/stream`) is example-only (not part of plugin public API). Run it on a device/emulator to validate flows.
+- `test/`: Unit tests (`*_test.dart`) covering public API, channel behavior, and capability queries.
+- `integration/channel/contracts/channel_contract.yaml`: Single source of truth for method/event channel contracts; edit together with Dart and native changes.
 - `scripts/bootstrap_iot.sh`: Recreate integration scaffolding if a clean checkout is missing folders.
 
 ## Build, Test, and Development Commands
@@ -18,13 +19,13 @@
 ## Coding Style & Naming Conventions
 - Follow `flutter_lints` (`analysis_options.yaml` relaxes `constant_identifier_names` for platform constants).
 - Files use `snake_case.dart`; classes/enums `PascalCase`; members and locals `camelCase`.
-- Keep channel method/event names and payload keys aligned with `FlutterBatteryPlatform`.
-- Favor small, nullable-safe methods and concise comments only where intent is non-obvious.
+- Channel method/event names and payload keys must use `BatteryChannelNames`, `BatteryMethodNames`, `BatteryEventTypes`, `BatteryPayloadKeys` from `lib/src/battery_channel_contract.dart` — no raw string literals outside native registration.
+- Favor small, nullable-safe methods. Comments only where intent is non-obvious.
 
 ## Testing Guidelines
 - Place new cases beside the feature under test; use descriptive `feature_behavior_test.dart` names.
-- Mock the platform interface for unit coverage of MethodChannel and stream behaviors; avoid hardware dependencies.
-- For native changes, run the `example/` app once on Android (and iOS when available) to verify battery readings and event streams.
+- Mock the platform interface for unit coverage of MethodChannel, stream behaviors, and capability queries; avoid hardware dependencies.
+- For native changes, run the `example/` app on Android and macOS to verify battery readings, event streams, and capability-based feature gating.
 
 ## Commit & Pull Request Guidelines
 - Use history-aligned prefixes (`feat:`, `style:`, `fix:`, `docs:`) plus an imperative summary.
@@ -35,3 +36,12 @@
 - Exclude secrets, keystores, and generated `build/` artifacts.
 - Request only minimum permissions when editing manifests.
 - When releasing, bump `pubspec.yaml` version and update `CHANGELOG.md` together.
+
+## Key Architecture Decisions (post-refactor)
+- **Channel Contract Constants**: All channel names, method names, event types, and payload keys are centralized in `lib/src/battery_channel_contract.dart`. Raw string literals are banned from business logic.
+- **Platform Capabilities**: `BatteryFeature` enum + `BatteryPlatformCapabilities` value object. Query via `FlutterBattery.getPlatformCapabilities()` or `isFeatureSupported(BatteryFeature)`. macOS explicitly returns `false` for notifications/BLE/peer sync.
+- **Predictable Failure**: `MissingPluginException` for optional features is mapped to `UnsupportedBatteryFeatureException` so consumers never see raw `MissingPluginException`.
+- **Normalized Events**: Event stream payloads always include a `type` field (`BATTERY_LEVEL`, `BATTERY_INFO`, `BATTERY_HEALTH`, `BATTERY_UNAVAILABLE`). Both `level` and `batteryLevel` keys are present for backward compatibility.
+- **macOS Callback Bridge**: `BatteryMonitor` has callback setters wired through `FlutterBatteryPlugin` to invoke MethodChannel methods (`onBatteryLevelChanged`, `onBatteryInfoChanged`, `onBatteryHealthChanged`).
+- **No iOS**: iOS platform declaration removed from `pubspec.yaml` until a native implementation is added.
+- **Example IoT Isolation**: `iot/native` and `iot/stream` channels are example-only, not part of plugin public API. Documented in `channel_contract.yaml` under `example_only_android`.

CHANGELOG.md

@@ -1,3 +1,13 @@
+## Unreleased
+
+* 重构平台架构：集中通道常量、新增平台能力查询 API
+* 新增 `BatteryFeature`、`BatteryPlatformCapabilities`、`UnsupportedBatteryFeatureException`
+* macOS 支持事件规范化、回调桥接、显式声明不支持的通知/BLE/IoT 功能
+* 示例页面通过能力对象控制功能入口
+* 移除 iOS 声明（待未来实现）
+* 更新通道契约文档，覆盖所有方法/事件通道与平台支持矩阵
+* 更新 README、AGENTS.md、example/AGENTS.md
+
 ## 0.0.3
 
 * 新增高级整合API `configureBattery`，一次性配置所有电池监控功能