一份让 Codex 构建出可上架 WebViewGold 应用的 AGENTS.md 模板

# AGENTS.md - [App name]

## What this project is
[One paragraph: what the app does, who uses it, main stack, e.g. Next.js + Supabase.]
Production URL: https://app.example.com
The same web app is published as native iOS and Android apps with WebViewGold.
The native apps load the production URL inside a WebView (WKWebView on iOS,
Android WebView on Android). There is no separate mobile codebase.

## Runtime context you must respect
- The page can run in three places: desktop browser, mobile browser, native app.
- The native app sends the user agent marker `MYAPPNATIVE` (set in Config.swift
  and Config.java). Detect it only through `isNativeApp()` in `src/lib/platform.ts`.
- OAuth popups do not behave like in a browser. Google/Facebook login is handled by
  the wrapper (Social Login Helper); Sign in with Apple is handled automatically.
  Do not add workarounds that open OAuth in new windows.
- window.open and target="_blank" are governed by the wrapper's URL handling rules.
  Use normal links for internal navigation.
- When `isNativeApp()` is true: no "Add to home screen" or "Download our app"
  banners, no service worker install prompts, no cookie banner unless legally required.

## WebViewGold JavaScript bridge
Native features are triggered by navigating to a URL scheme:
`window.location.href = "scheme://..."`. Results come back as global JavaScript
variables or callback functions, asynchronously. Only call schemes when
`isNativeApp()` is true and always keep a web fallback.
Full reference: https://www.webviewgold.com/llms-full.txt

| Feature | Call | Result |
| --- | --- | --- |
| Request push permission | `registerpush://` | native permission prompt |
| Check push permission | `checkNativePushPermissions://` | `nativePushEnabled` (true/false) |
| OneSignal subscription ID | `getonesignalplayerid://` | `onesignalplayerid` |
| Local scheduled notification | `sendlocalpushmsg://push.send?s=SECONDS=msg!MESSAGE&!#TITLE&!#URL` | - |
| Share sheet | `shareapp://message?=TEXT&url=URL` | - |
| Haptics | `lighthaptic://`, `successhaptic://`, `errorhaptic://` | - |
| Biometric check | `bioauth://` | iOS: `onBioAuthSuccess()`, `onBioAuthFailure(code, msg)`, `onBioAuthUnavailable()` |
| QR scanner | `qrcode://` | scanned URL is loaded in the WebView |
| Barcode scanner | `barcodescanner://` | `barcodescanresult` |
| In-app purchase (RevenueCat) | `revenuecat://purchase?external_id=USER_ID&product=PRODUCT_ID` | entitlement in RevenueCat; grant server-side via webhook |
| Restore purchases | `restoreinapppurchases://` | - |
| Manage subscription | `cancelinapppurchase://` | opens the store subscription page |
| App version | `getappversion://` | `versionNumber`, `bundleNumber` |
| Install ID | `get-uuid://` | `uuid` |
| Save image to gallery | `savethisimage://?url=IMAGE_URL` | - |
| Open system app settings (Android) | `settingsapp://` | - |

Injected variables arrive after a short delay: poll with a timeout, never read
them synchronously after the navigation.

## Store rules (every change must keep these true)
- /privacy and /terms are real routes, linked from the footer and from settings.
- Users who can sign up can delete their account in settings (server-side deletion)
  and via a public /delete-account page.
- If any third-party login exists, Sign in with Apple is offered as an equal option.
- Digital goods, subscriptions and credits are bought through the bridge
  (`revenuecat://purchase...`) when `isNativeApp()`; Stripe stays for browser users.
  Never show card forms or external payment links for digital goods in the native app.
  Physical goods and services may use Stripe everywhere.
- Layout works from 320px width, tap targets >= 44px, safe-area insets on fixed bars,
  inputs with font-size >= 16px.
- Every fetch has loading, empty, error and retry states. No blank screens.
- User-generated or AI-generated content has a report action; users can block others.
- No placeholder copy, no dead links, no mixed content.

## Commands
- Install: `npm install`
- Dev server: `npm run dev`
- Lint and typecheck: `npm run lint && npm run typecheck`
- Tests: `npm test`
Run lint and tests before you finish a task.

## Definition of done for any task
1. Works in a desktop browser and at 320px width.
2. Native-only code is behind `isNativeApp()` with a web fallback.
3. No new store-rule violations (see above).
4. Summarize what changed and what to test on a real device.