# flutter_rn_quality_harden

**Repository Path**: simplelove520/flutter_rn_quality_harden

## Basic Information

- **Project Name**: flutter_rn_quality_harden
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-04
- **Last Updated**: 2026-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QR Flutter Auto

Reusable automation kit for Flutter **and React Native/OpenHarmony** third-party library quality reinforcement.

It combines:

- A Codex skill for judgment-heavy work: demo generation, report interpretation, and safe fix boundaries.
- A CLI for deterministic work: clone, state tracking, build logs, review API task tracking, report download, baseline resolution, and guard checks.
- An adapter boundary (`flutter` and `rn`) so language-specific work is isolated behind a common protocol.

## Quick Start

```bash
./install.sh
cp config/repos.example.yaml config/repos.local.yaml
./qr_flutter_auto.sh doctor --config config/repos.local.yaml
./qr_flutter_auto.sh run --config config/repos.local.yaml
```

## React Native / OpenHarmony

RN support uses a separate source and Demo/test checkout, TypeScript AST interface extraction, and a four-dimension coverage preflight (`callableRuntime`, `typeSurface`, `nativeRuntime`, `testRootPresence`). The RN stop gate normally requires six remote reports: 稳定性、一致性、内存泄露、用例覆盖度、文档质量、已知问题检视. If `stopPolicy.requiredReports.knownIssue: 0` and the remote task has produced a numeric overall score, the run explicitly uses the other five reports; this is an auditable exemption, not a claim that known issues are clean.

The tracked `config/rn-repos.example.yaml` is a safe, read-only template. Copy
it to the ignored `config/rn-repos.local.yaml`, add your Git identity and explicitly enable
`mutationPolicy.remoteWrite/remoteFork/remotePush` plus per-repository
`allowPush` there when remote Fork/Push is authorized. Add `--no-remote-write`
to any command for a read-only run. The repository name used below is only an
example; replace it with the selected `repos[].name`.
The CLI defaults to `--allow-fork`; `--no-remote-write` always overrides it for
a read-only invocation.
If a confirmed stale repository lock blocks a stateful command, use `--break-lock --yes-i-know`; never use it for a live lock.

```bash
CONFIG=config/rn-repos.local.yaml
cp config/rn-repos.example.yaml "$CONFIG"
./qr_flutter_auto.sh doctor --config "$CONFIG"
./qr_flutter_auto.sh prepare-forks --config "$CONFIG" --repo <repoName>
./qr_flutter_auto.sh run --config "$CONFIG" --repo <repoName>
./qr_flutter_auto.sh analyze-coverage --config "$CONFIG" --repo <repoName>
./qr_flutter_auto.sh rn-fix-plan --config "$CONFIG" --repo <repoName>
./qr_flutter_auto.sh verify --config "$CONFIG" --repo <repoName>
./qr_flutter_auto.sh review-only --config "$CONFIG" --repo <repoName> --round 1
./qr_flutter_auto.sh rn-gate --config "$CONFIG" --repo <repoName>
```

See [docs/RN质量加固自动化方案与使用步骤.md](docs/RN质量加固自动化方案与使用步骤.md) for the full RN workflow.

### Why `Cookies.key` and `fetchCookie` are reported separately

`Cookies.key` is an **index signature** (type surface): coverage = bracket/property access in Demo/test. `fetchCookie` is a **native-dependent function** (native runtime): coverage = integration/device evidence, not a unit-test mock. Reporting them in separate dimensions prevents false full coverage and false zero results.

## Key Rules

- Remote review tasks are matched only by the `taskId` returned by the configured review endpoint. RN supports two protocols selected via `repos[].review.protocol`:
  - `legacy` (default): `POST /api/rnlibrarycheck` — single-endpoint submit, poll, and report download.
  - `orchestrator`: `POST /api/orchestrator/load` + `POST /api/orchestrator/start` for seven-step task submission, `GET /api/orchestrator/progress?taskId=...` for polling, and `GET /api/flexrunner/steps?taskId=...` + `GET /api/flexrunner/file?path=...` for report resolution and download. The orchestrator adapter submits exactly seven steps (interface analysis + six review dimensions), uses a deterministic `rncheck_{safeName}_{sha256_suffix}` taskId for idempotency, and binds every report to the exact source/Demo revisions checked out locally.
  - Flutter uses `POST /api/flutterlibrarycheck`.
- Remote review submissions send a tree URL: `repos[].branch` when configured, otherwise the repository default branch, plus `repos[].subPath` when configured.
- In stability, consistency, code quality, and memory leak reports, issues involving `example/ohos/` are recorded but not fixed.
- Issues in library implementation files under `ohos/src/main/ets/**` are not ignored. Verify the report finding against local source, project SDK APIs, and Huawei official ArkTS/HarmonyOS documentation before fixing; do not invent APIs or apply advice that conflicts with the source.
- Dart-layer report issues must be compared against the original package source/version before fixing. Upstream-existing issues are recorded but not fixed.
- New hand-written Dart/ETS source files must start with the Huawei copyright header.
- Local OHOS debug signing may be injected for `flutter build hap`, but signing material and `example/ohos` changes must not be committed.
- `pubspec.yaml` and lock files may be changed only for controlled OHOS dependency adaptation, such as replacing a non-OHOS Flutter dependency with a confirmed OHOS-adapted one. Record the reason in `State/pubspec-dependency-adaptation.md` and verify with `flutter pub get` plus `flutter build hap`.
- Tool/build generated files do not need the header and must not be pushed to remote.
- Never use `git add .`; commits must use path allowlists.
- Re-running generation must be idempotent: overwrite controlled generated files, replace the unique quality reinforcement entry block, and never append duplicate FABs/imports/routes.
- Quality reinforcement report artifacts belong in `QualityReinforcementReports/` beside `Code/` and `CodeReviewReport/`; the legacy in-repo `quality_reinforcement_reports/` directory must be migrated.
- Force rerun is explicit and scoped: `reset-generated --yes-i-know` and `--force-regenerate` may only reset automation-owned generated demo files, while `--new-review-task` is required to create another remote review task for an existing round.

### RN Orchestrator Review Protocol

When `repos[].review.protocol: orchestrator` is set for an RN repository, the CLI routes review submission, polling, and report download through the Orchestrator/Flexrunner API instead of the legacy single-endpoint `/api/rnlibrarycheck`.

**Configuration:**

```yaml
repos:
  - name: react-native-image-sequence-2
    kind: rn
    harmonyRepo: {url: https://gitcode.com/CPF-RN/rntpc_react-native-image-sequence}
    communityRepo: {url: https://github.com/bwindsor/react-native-image-sequence}
    documentUrl: https://gitcode.com/CPF-RN/rntpc_react-native-image-sequence/blob/master/README.md
    demoUrl: https://gitcode.com/du-wenboboo/rnt_demo_release_61/tree/br_rnoh0.61/61tester/RNTester/examples/react-native-image-sequence-2
    review:
      protocol: orchestrator
      loadEndpoint: /api/orchestrator/load
      startEndpoint: /api/orchestrator/start
      progressEndpoint: /api/orchestrator/progress
      stepsEndpoint: /api/flexrunner/steps
      fileEndpoint: /api/flexrunner/file
      skillDirectory: ""
      outputDir: ""
      pollMaxMinutes: 60
      cliType: opencode
```

**Endpoint semantics:**
- `/api/orchestrator/load` and `/api/orchestrator/start` are mutating submission endpoints (called once per deterministic taskId).
- `/api/orchestrator/progress`, `/api/flexrunner/steps`, and `/api/flexrunner/file` are task-bound reads.
- `--no-remote-write` prevents load/start; polling and download remain allowed.

**Task lifecycle:**
- `review-only --round N` submits a seven-step task and polls until completion.
- `resume-review --round N` resumes polling an existing task by taskId without resubmitting.
- A deterministic taskId (`rncheck_{safeName}_{sha256_suffix}`) prevents duplicate tasks for the same round/snapshot. Use `--new-review-task` to force a fresh task.
- Reports are downloaded incrementally while polling. With `knownIssue: 0` plus a numeric remote overall score, the incremental/final report set is stability, consistency, memory leak, documentation, and test coverage; otherwise all six reports remain required.

**Migration and rollback:**
- A missing `reviewProtocol` in State is treated as `legacy` — old records work without changes.
- To roll back: set the target repo back to `protocol: legacy` (or remove the `protocol` field), preserve orchestrator State/reports for audit, verify the checkout revision, and use a new legacy round. Do not delete remote tasks or local evidence.

Set the review branch and package subdirectory in `config/repos.yaml`:

```yaml
repos:
  - name: flutter_blue_plus_ohos
    url: https://gitcode.com/openharmony-sig/fluttertpc_flutter_blue_plus.git
    branch: ohos-dev
    subPath: flutter_blue_plus_ohos
```

This submits `https://gitcode.com/openharmony-sig/fluttertpc_flutter_blue_plus/tree/ohos-dev/flutter_blue_plus_ohos` to remote review.

## Typical Commands

```bash
./qr_flutter_auto.sh status --config config/repos.yaml
./qr_flutter_auto.sh run --repo open_settings --config config/repos.yaml
./qr_flutter_auto.sh plan --from-stage analyze-reports --repo open_settings --round 1 --config config/repos.yaml
./qr_flutter_auto.sh run-from --stage analyze-reports --repo open_settings --round 1 --config config/repos.yaml
./qr_flutter_auto.sh guard-idempotency --repo open_settings --config config/repos.yaml
./qr_flutter_auto.sh migrate-quality-reports --repo open_settings --config config/repos.yaml
./qr_flutter_auto.sh resume --repo open_settings --config config/repos.yaml
./qr_flutter_auto.sh review-only --repo open_settings --config config/repos.yaml
./qr_flutter_auto.sh download-reports --repo open_settings --round 1 --config config/repos.yaml
./qr_flutter_auto.sh rerun-analysis --repo open_settings --round 1 --config config/repos.yaml
./qr_flutter_auto.sh resolve-baseline --repo open_settings --config config/repos.yaml
./qr_flutter_auto.sh quality-gate-v2 --repo open_settings --round 1 --config config/repos.yaml
./qr_flutter_auto.sh precheck --repo open_settings --config config/repos.yaml
./qr_flutter_auto.sh platform-knowledge --repo open_settings --config config/repos.yaml
./qr_flutter_auto.sh round-changes --repo open_settings --config config/repos.yaml
./qr_flutter_auto.sh issue-index --repo open_settings --config config/repos.yaml
./qr_flutter_auto.sh diff-attribution --repo open_settings --config config/repos.yaml
./qr_flutter_auto.sh convergence-decision --repo open_settings --config config/repos.yaml
./qr_flutter_auto.sh gate-status --repo open_settings --config config/repos.yaml
./qr_flutter_auto.sh fix-loop-brief --config config/repos.yaml
./qr_flutter_auto.sh fix-queue --config config/repos.yaml
./qr_flutter_auto.sh session-check --config config/repos.yaml
./qr_flutter_auto.sh pipeline --config config/repos.yaml
./qr_flutter_auto.sh run-until-gate --include-poll --config config/repos.yaml
./qr_flutter_auto.sh dashboard --config config/repos.yaml
./qr_flutter_auto.sh wait-reasons --config config/repos.yaml
./qr_flutter_auto.sh ready-tasks --config config/repos.yaml
```

Use `plan --from-stage ...` to preview what will run. Use `run-from --stage ...` to execute a single pipeline stage. Add `--to-stage ...` only when continuing across multiple CLI stages is intentional. The CLI refuses to cross agent-driven stages like `inspect-api`, `generate-demo-doc`, `generate-demo-code`, `integrate-example-entry`, and `fix-safe` unless `--allow-manual-gap` is set.

Use `rerun-analysis` or `run-from --stage analyze-reports` when reports are already downloaded and you want to restart from the step that analyzes stability, consistency, code quality, and memory leak deductions. It reuses the upstream baseline when available, resolves it only when missing, and does not clone, regenerate demos, commit, push, or submit a new remote review. Add `--refresh-baseline` only when the baseline itself must be refreshed.

Use `quality-gate-v2` and `dashboard` for Flutter, or `rn-gate` and `dashboard` for RN, after the corresponding report state exists. `rawScore` values in the generated dashboards come from the remote review task; `effectiveScore` is computed locally from verified exclusions and must not be described as a remote re-score. The gate has three layers: hard gate (framework-specific rawScore minimum thresholds + local verification), delivery warning gate, and excellence gate (rawScore 100 target). Safe-auto must not stop until all configured reports meet rawScore minimum thresholds and `stopAllowed=true`; Flutter uses four reports, RN uses six reports plus independent coverage/native evidence. Use `gate-status` to see gaps to minimum and to 100.

Use `gate-status` to inspect per-report rawScore gaps, `mustContinueFixLoop`, and `shouldPursueExcellence` before deciding whether to stop or launch another fix/review round.

Use `precheck` before a remote submission or before a repair round to run deterministic local ETS checks for common remote AI findings such as long classes/methods, timer cleanup, fire-and-forget detach cleanup, and unsupported SoundPool callback overloads.

Use `platform-knowledge` to apply the built-in OHOS platform limitation knowledge base. It records known SoundPool/CoreSpeechKit/Dart platform-detection limitations so repeated remote AI deductions are handled by evidence instead of repeated speculative fixes.

Use `round-changes`, `issue-index`, and `convergence-decision` after at least one report round exists. `round-changes` summarizes what was modified for each report round from `State/*fix-applied-round-N.md`; `issue-index` builds a conservative issue fingerprint lifecycle from the four key reports; `convergence-decision` explains whether remaining issues are resolved, documented exclusions, gate-passed deferred items, or still open. These commands help distinguish remote AI review drift from issues introduced by local fixes.

Use `diff-attribution` after `issue-index`. It maps adjacent review-round windows to git commits and classifies newly reported issues as possible fix-introduced, likely AI drift / previously missed, or unknown-needs-review. It is conservative: path overlap is evidence to inspect, not proof.

Use `fix-loop-brief` to generate per-repo next-action plans (`State/fix-loop-brief.md/json`). Agents must read this before ending a session when `stopAllowed=false`.

Use `fix-queue` to generate ordered repair lists (`State/fix-queue.md/json`): mandatory issues first, then below-minimum reports, then other open items.

Use `session-check` before ending an Agent or CI session. It runs `fix-loop-brief` + `fix-queue` and exits with code 1 when any repo is not ready to stop. This is the Layer-3 stop gate.

Use `pipeline` to run one automated CLI step per repo; use `run-until-gate --include-poll` to loop until all repos pass or agent-fix is required.

Use `wait-reasons` and `ready-tasks` to see why each repository is idle. When `mustContinueFixLoop=true` at stage `pushed`, wait reasons are blocking and recommend `review-only --round N`.

For a deliberate rebuild of automation-owned demo artifacts:

```bash
./qr_flutter_auto.sh reset-generated --repo open_settings --yes-i-know --config config/repos.yaml
./qr_flutter_auto.sh run-from --stage generate-demo-code --repo open_settings --force-regenerate --yes-i-know --config config/repos.yaml
```

This removes only `example/lib/quality_reinforcement/**` and `State/generated-demo-manifest.json`. It does not remove user code, `example/ohos/**`, `ohos/src/main/ets/**`, or previous remote review task records.

To intentionally create a new remote review task for a round that already has a task record:

```bash
./qr_flutter_auto.sh submit-review --repo open_settings --round 1 --new-review-task --config config/repos.yaml
```

For local OHOS signing, prefer environment variables instead of writing passwords into `repos.yaml`:

```bash
export OHOS_SIGNING_STORE_PASSWORD="<DevEco generated password>"
export OHOS_SIGNING_KEY_PASSWORD="<DevEco generated password>"
```

If `flutter build hap` fails only in the DevEco/Harmony debug signing stage, the CLI accepts it only when the log or artifact directory explicitly proves that an unsigned HAP was produced (`LOCAL_UNSIGNED_HAP_PASS`). A signing error without that evidence, or any Dart/ETS/dependency/package failure, remains blocked.

## Roadmap Direction

The recommended automation target is `safe-auto`, not immediate full automation. Current CLI support includes idempotency guards, staged resume, local precheck, platform limitation knowledge, report download, v2 quality gates, issue lifecycle indexing, round-change summaries, diff attribution, convergence decisions, per-repo dashboards, batch dashboard summaries, **fix-loop-brief**, **pipeline**, **run-until-gate**, wait-reason diagnostics, ready-task diagnostics, and repo locks (`State/.qr-auto.lock`). Planned improvements include broader static project inspection, risk assessment, demo validation, secret scanning, richer diff summaries, deeper structured issue attribution, and bounded multi-repository worker pools.

`full-auto` is intentionally postponed and must remain disabled until the safety gates, demo validation, state recovery, and dashboard are stable across enough repositories.

## Codex Usage

Install the bundled skill directory:

```text
skill/ohos-flutter-quality-reinforcement-auto
```

Then ask Codex:

```text
使用 ohos-flutter-quality-reinforcement-auto，对 repos.yaml 中的 Flutter 仓库执行质量加固。
```