Merge pull request #4 from lizy-coding/develop

update yaml and agent.md

Author: lizy-coding

README.md

@@ -1,91 +1,123 @@
 # FlutterGuard
 
-> **IoT Flutter project static analysis CLI — architecture enforcement, code quality, CI gating.**
+> IoT Flutter project static analysis CLI for architecture enforcement, code quality, and CI gating.
 
-FlutterGuard scans Flutter/Dart source code to detect architecture issues, security vulnerabilities, and anti-patterns specific to IoT device applications. Designed for CI integration and team-wide adoption.
+FlutterGuard scans Flutter/Dart source code and reports architecture boundary breaches, lifecycle/resource leaks, dependency cycles, and size-related code quality issues. The active path is `packages/flutterguard_cli/`; the legacy runtime-tracing packages are archived under `archive/`.
 
-## Installation
+## What It Is
 
-### Prerequisites
+- A CLI for static analysis of Flutter/Dart projects
+- A YAML-driven architecture enforcement tool
+- An IoT/smart-home aware rule set for Flutter codebases
+- A CI gate that can fail builds on severity thresholds or score thresholds
 
-- [Dart SDK](https://dart.dev/get-dart) >=3.3.0
+## What It Is Not
 
-### Option A: Global activation (cross-platform)
+- Not a runtime observability or APM SDK
+- Not a crash reporter
+- Not a general-purpose Dart linter
+- Not a web dashboard or Flutter widget library
+
+## Requirements
+
+- Dart SDK 3.3.0 or newer
+- `melos` for workspace bootstrap when running from source
+
+## Install
+
+### From source
 
 ```bash
-# Clone the repo
 git clone https://github.com/lizy-coding/flutterguard.git
 cd flutterguard
 
-# Install monorepo dependencies
 dart pub global activate melos
 melos bootstrap
 
-# Register flutterguard command globally
 dart pub global activate --source path packages/flutterguard_cli
-
-# Verify installation
 flutterguard --help
 ```
 
-> **Windows**: After activation, ensure `%USERPROFILE%\AppData\Local\Pub\Cache\bin` is in your `PATH`. Dart SDK installer usually adds it automatically. To verify: `where flutterguard`.
+> Windows users may need `%USERPROFILE%\AppData\Local\Pub\Cache\bin` on `PATH` after global activation.
 
-### Option B: Compile native binary
+### Compile a native binary
 
 ```bash
 git clone https://github.com/lizy-coding/flutterguard.git
 cd flutterguard
+dart pub global activate melos
 melos bootstrap
+dart pub get
 dart compile exe packages/flutterguard_cli/bin/flutterguard.dart -o flutterguard
 ```
 
-### Option C: Pre-compiled binary (macOS/Linux only)
+On Windows, compile with an `.exe` output name and run the local binary with
+`.\flutterguard.exe`:
 
-```bash
-curl -sL https://github.com/lizy-coding/flutterguard/releases/download/v0.1.0/flutterguard -o /usr/local/bin/flutterguard
-chmod +x /usr/local/bin/flutterguard
+```powershell
+dart pub get
+dart compile exe packages/flutterguard_cli/bin/flutterguard.dart -o flutterguard.exe
+.\flutterguard.exe scan -p D:\path\to\flutter_app
+```
+
+If `flutterguard scan` prints `API key required` or mentions uploading APKs, the
+shell is resolving an old globally installed binary instead of this repository's
+static-analysis CLI. Check it with `where flutterguard`, then either run
+`.\flutterguard.exe` from the repo directory or reinstall the local CLI:
+
+```powershell
+dart pub global deactivate flutterguard_cli
+dart pub global activate --source path packages\flutterguard_cli
 ```
 
 ## Quick Start
 
 ```bash
 # Scan a Flutter project
-flutterguard scan -p /path/to/your/project
+flutterguard scan -p /path/to/project
 
-# JSON output for CI
+# Write JSON report and fail on HIGH issues
 flutterguard scan -p . --format json --fail-on high
 
-# See all options
+# Show help
 flutterguard --help
 ```
 
-### Demo
+### Demo target
 
 ```bash
-# From the repo root, scan the demo project
 flutterguard scan -p examples/scan_demo
 ```
 
----
+## CLI
+
+Commands:
+
+- `flutterguard scan`
+- `flutterguard --help`
+- `flutterguard --version`
+
+Scan options:
 
-## Available Rules (6)
+| Flag | Meaning | Default |
+|------|---------|---------|
+| `-p`, `--path` | Project path to scan | `.` |
+| `-c`, `--config` | Config file path inside the project root | `flutterguard.yaml` |
+| `-f`, `--format` | Output format: `table` or `json` | `table` |
+| `-o`, `--output` | Output directory for generated reports | `.flutterguard` |
+| `-v`, `--verbose` | Show issue detail in terminal output | off |
+| `--fail-on` | CI gate threshold: `none`, `high`, `medium`, `low` | `none` |
+| `--min-score` | Minimum acceptable score, 0-100 | unset |
 
-| Rule ID | Level | Domain | What it detects |
-|---------|-------|--------|----------------|
-| `large_file` | LOW | standards | Files exceeding maxLines (default 500) |
-| `large_class` | LOW | standards | Classes exceeding maxLines (default 300) |
-| `large_build_method` | MEDIUM | performance | Widget build() exceeding maxLines (default 80) |
-| `lifecycle_resource_not_disposed` | MEDIUM | performance | StreamSubscription, Timer, AnimationController, MqttClient, BluetoothDevice, StreamController without matching cancel/dispose/close |
-| `layer_violation` | HIGH | architecture | Cross-layer import violations (YAML-configured) |
-| `module_violation` | HIGH | architecture | Cross-module import violations (YAML-configured) |
-| `circular_dependency` | MEDIUM | architecture | File-level import cycles |
-| `missing_const_constructor` | LOW | standards | StatelessWidget/StatefulWidget subclasses missing const constructor |
+Exit codes:
 
----
+- `0` success
+- `1` gate failed
+- `2` scan error or invalid input
 
 ## Configuration
 
-Create a `flutterguard.yaml` in your project root:
+Create `flutterguard.yaml` in the project root:
 
 ```yaml
 include:
@@ -113,7 +145,7 @@ rules:
     enabled: true
 
 architecture:
-  layers:                        # Layered architecture enforcement
+  layers:
     - name: presentation
       path: lib/presentation/**
       allowed_deps: [domain, core]
@@ -127,7 +159,7 @@ architecture:
       path: lib/core/**
       allowed_deps: []
 
-  modules:                       # Business module isolation
+  modules:
     - name: device_mqtt
       path: lib/device/mqtt/**
       allowed_deps: [domain, core]
@@ -142,76 +174,61 @@ architecture:
     enabled: true
 ```
 
----
+Notes:
 
-## Output Formats
+- If `flutterguard.yaml` is missing, defaults are used.
+- Architecture rules require explicit `layers` and `modules`; they do not auto-discover boundaries.
+- `layer_violation` and `module_violation` only work when the relevant declarations are present.
 
-### Table (default)
+## Checks
 
-```
- FlutterGuard Report  ─  scan_demo
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- 总评分:  98/100  优秀      文件总数: 2  问题总数: 2
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
- 代码规范  2 items  ▰  LOW
-────────────────────────────────────────────────────────────────
- LOW  P2 可选
-       类过大
-       lib/services/user_service.dart:3
-       类 "UserService" 49 行（阈值: 30 行）
-       修复: 建议将 "UserService" 的职责提取到更小的类中
-```
+FlutterGuard currently emits these issue IDs:
 
-### JSON
+| Rule ID | Level | Domain | Priority | What it checks |
+|---------|-------|--------|----------|----------------|
+| `large_file` | LOW | standards | P2 | File line count over `maxLines` |
+| `large_class` | LOW | standards | P2 | Class body line count over `maxLines` |
+| `large_build_method` | MEDIUM | performance | P1 | `build()` method line count over `maxLines` |
+| `lifecycle_resource_not_disposed` | MEDIUM | performance | P1 | Undisposed `StreamSubscription`, `Timer`, `AnimationController`, `TextEditingController`, `ScrollController`, `FocusNode`, `MqttClient`, `BluetoothDevice`, `StreamController` |
+| `layer_violation` | HIGH | architecture | P0 | Importing across forbidden architecture layers |
+| `module_violation` | HIGH | architecture | P0 | Importing across forbidden business modules |
+| `circular_dependency` | MEDIUM | architecture | P1 | File-level import cycles |
+| `missing_const_constructor` | LOW | standards | P2 | Widget classes missing a `const` constructor |
 
-```bash
-flutterguard scan -p . --format json
-```
+## Output
+
+### Terminal table
+
+Default output is a colored terminal report grouped by domain. It shows the overall score, file count, issue count, and per-issue detail.
 
-Output written to `.flutterguard/report.json`:
+### JSON report
+
+`--format json` writes `.flutterguard/report.json` under the output directory. The terminal summary is still printed to stdout.
+
+Example shape:
 
 ```json
 {
   "version": "1.0.0",
+  "generatedAt": "2026-05-20T00:00:00.000Z",
+  "projectPath": "/absolute/path",
   "score": 85,
   "summary": {
     "total": 3,
     "high": 1,
     "medium": 1,
     "low": 1,
     "byDomain": {
-      "architecture": { "high": 1, "medium": 0, "low": 0, "total": 1 },
-      "performance": { "high": 0, "medium": 1, "low": 0, "total": 1 },
-      "standards":   { "high": 0, "medium": 0, "low": 1, "total": 1 }
+      "architecture": { "high": 1, "medium": 0, "low": 0, "total": 1 }
     }
   },
-  "issues": [...]
+  "issues": []
 }
 ```
 
----
-
-## CI Integration
-
-```bash
-# Fail the build if any HIGH issues exist
-flutterguard scan -p . --format json --fail-on high
-
-# Enforce a minimum score of 80
-flutterguard scan -p . --format json --min-score 80
-
-# Accept only clean scans (no issues at any level)
-flutterguard scan -p . --fail-on low
-```
-
-**Exit codes**: `0` = pass, `1` = gate failed, `2` = error
-
----
-
 ## Scoring
 
-```
+```text
 score = max(0, 100 - high*10 - medium*4 - low*1)
 ```
 
@@ -221,28 +238,39 @@ score = max(0, 100 - high*10 - medium*4 - low*1)
 | 50-79 | 需关注 (Needs review) |
 | 0-49 | 需整改 (Needs action) |
 
----
+## CI Integration
+
+```bash
+flutterguard scan -p . --format json --fail-on high
+flutterguard scan -p . --format json --min-score 80
+flutterguard scan -p . --fail-on low
+```
+
+## Repository Layout
+
+```text
+flutterguard/
+├── packages/
+│   └── flutterguard_cli/   Active CLI implementation
+├── archive/                Frozen legacy runtime-tracing packages
+└── examples/
+    └── scan_demo/          Demo scan target
+```
 
 ## Development
 
 ```bash
-# Bootstrap monorepo
 git clone https://github.com/lizy-coding/flutterguard.git
 cd flutterguard
+dart pub global activate melos
 melos bootstrap
+dart pub get
 
-# Analyze
 dart run melos run analyze
-
-# Test (12 tests)
 dart run melos run test:cli
-
-# Compile CLI
 dart compile exe packages/flutterguard_cli/bin/flutterguard.dart -o flutterguard
 ```
 
----
-
 ## License
 
 MIT