@ybais/create-ybais-app 0.2.0

package/README.md

@@ -0,0 +1,21 @@
+# @ybais/create-ybais-app
+
+Scaffold a YBAIS React + Vite WebView app（基础设施依赖 `@ybais/*`）。
+
+```bash
+npx @ybais/create-ybais-app my-app
+# 等价：
+npm create @ybais/ybais-app my-app
+```
+
+Interactive prompts include:
+
+- Test / Prod API base URLs
+- **Enable vConsole?** (default no) — if yes, installs `vconsole` + `@ybais/vconsole`（仅 test；prod / master 杜绝）。If no, dependency and `@@vconsole` block are stripped.
+- Run `pnpm install` now?
+
+生成项目的 `@ybais/*` 依赖会写成 `^0.1.0`（需已发布到 npm）。Monorepo 内 template 使用 `workspace:*`。
+
+旧包名 `create-ybais-app`（个人账号下）已迁移为 **`@ybais/create-ybais-app`**；请改用带 scope 的命令。
+
+See the repository root README / [PUBLISH.md](../../PUBLISH.md) for development and publish instructions.

package/dist/index.js

@@ -0,0 +1,371 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import mri from "mri";
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = path.resolve(__dirname, "../template");
+const DEFAULT_TEST_API = "https://api-test.example.com";
+const DEFAULT_PROD_API = "https://api.example.com";
+function printHelp() {
+    console.log(`
+${pc.bold("@ybais/create-ybais-app")} — scaffold a YBAIS React + Vite app
+
+${pc.dim("Usage:")}
+  npx @ybais/create-ybais-app [project-name] [options]
+  # 或: npm create @ybais/ybais-app [project-name]
+
+${pc.dim("Options:")}
+  --overwrite    Overwrite non-empty target directory without prompting
+  -h, --help     Show help
+
+${pc.dim("Fixed:")}
+  package manager pnpm · git init · mise branch build · @vitejs/plugin-legacy
+
+${pc.dim("Optional:")}
+  pnpm install — asked during scaffold (default: no)
+  vConsole — asked during scaffold (default: no; test-only, never on master/prod)
+`);
+}
+function isValidPackageName(name) {
+    return /^(?:@[a-z0-9-*~][a-z0-9-*._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(name);
+}
+function toValidPackageName(name) {
+    return name
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, "-")
+        .replace(/^[._]/, "")
+        .replace(/[^a-z0-9-~]+/g, "-");
+}
+function emptyDir(dir) {
+    if (!fs.existsSync(dir))
+        return;
+    for (const file of fs.readdirSync(dir)) {
+        if (file === ".git")
+            continue;
+        fs.rmSync(path.join(dir, file), { recursive: true, force: true });
+    }
+}
+function isDirEmpty(dir) {
+    if (!fs.existsSync(dir))
+        return true;
+    const files = fs.readdirSync(dir).filter((f) => f !== ".git");
+    return files.length === 0;
+}
+function copyTemplate(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const name = entry.name;
+        if (name === "node_modules" ||
+            name === "dist" ||
+            name === ".git" ||
+            name === "pnpm-lock.yaml" ||
+            name.endsWith(".local")) {
+            continue;
+        }
+        const from = path.join(src, name);
+        const to = path.join(dest, name);
+        if (entry.isDirectory()) {
+            copyTemplate(from, to);
+        }
+        else {
+            fs.copyFileSync(from, to);
+        }
+    }
+}
+function writeEnvFiles(root, opts) {
+    fs.writeFileSync(path.join(root, ".env"), `# 所有模式共享的默认环境变量（可被 .env.[mode] 覆盖）\nVITE_APP_TITLE=${opts.title}\n`, "utf8");
+    fs.writeFileSync(path.join(root, ".env.test"), `VITE_APP_ENV=test\nVITE_API_BASE_URL=${opts.testApi}\n`, "utf8");
+    fs.writeFileSync(path.join(root, ".env.prod"), `VITE_APP_ENV=prod\nVITE_API_BASE_URL=${opts.prodApi}\n`, "utf8");
+}
+const YBAIS_PKG_VERSION = "^0.1.0";
+const VCONSOLE_DEP = "^3.15.1";
+function rewritePackageJson(root, packageName) {
+    const pkgPath = path.join(root, "package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    pkg.name = packageName;
+    pkg.version = "0.0.1";
+    pkg.dependencies ??= {};
+    // monorepo template 用 workspace:*；脚手架产出独立项目时改为 semver
+    for (const [dep, range] of Object.entries(pkg.dependencies)) {
+        if (dep.startsWith("@ybais/") && range.startsWith("workspace:")) {
+            pkg.dependencies[dep] = YBAIS_PKG_VERSION;
+        }
+    }
+    fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
+}
+/** 按脚手架选项保留或剥离 vConsole（依赖 / main 标记 / README 行） */
+function applyVConsoleOption(root, enabled) {
+    const pkgPath = path.join(root, "package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    pkg.dependencies ??= {};
+    if (enabled) {
+        pkg.dependencies.vconsole = VCONSOLE_DEP;
+        pkg.dependencies["@ybais/vconsole"] ??= YBAIS_PKG_VERSION;
+    }
+    else {
+        delete pkg.dependencies.vconsole;
+        delete pkg.dependencies["@ybais/vconsole"];
+    }
+    fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
+    const mainPath = path.join(root, "src/main.tsx");
+    let main = fs.readFileSync(mainPath, "utf8");
+    if (!enabled) {
+        main = main.replace(/\/\/ @@vconsole\n[\s\S]*?\/\/ @@\/vconsole\n/g, "");
+    }
+    fs.writeFileSync(mainPath, main, "utf8");
+    const libReadme = path.join(root, "src/lib/README.md");
+    if (fs.existsSync(libReadme)) {
+        let readme = fs.readFileSync(libReadme, "utf8");
+        if (enabled) {
+            if (!readme.includes("@ybais/vconsole")) {
+                readme = readme.replace("| VConsole | `@ybais/vconsole` |", "| VConsole | `@ybais/vconsole` |");
+            }
+        }
+        else {
+            readme = readme.replace(/\| VConsole \| `@ybais\/vconsole` \|\n/, "");
+        }
+        fs.writeFileSync(libReadme, readme, "utf8");
+    }
+}
+function rewriteIndexHtml(root, title) {
+    const htmlPath = path.join(root, "index.html");
+    let html = fs.readFileSync(htmlPath, "utf8");
+    html = html.replace(/<title>.*?<\/title>/, `<title>${title}</title>`);
+    fs.writeFileSync(htmlPath, html, "utf8");
+}
+function commandExists(cmd) {
+    const result = spawnSync(cmd, ["--version"], {
+        stdio: "ignore",
+        shell: process.platform === "win32",
+    });
+    return result.status === 0;
+}
+function run(cmd, args, cwd) {
+    const result = spawnSync(cmd, args, {
+        cwd,
+        stdio: "inherit",
+        shell: process.platform === "win32",
+    });
+    if (result.error) {
+        return { ok: false, error: result.error.message };
+    }
+    if (result.status !== 0) {
+        return { ok: false, error: `${cmd} exited with code ${result.status}` };
+    }
+    return { ok: true };
+}
+async function main() {
+    const argv = mri(process.argv.slice(2), {
+        boolean: ["overwrite", "help"],
+        alias: { h: "help" },
+    });
+    if (argv.help) {
+        printHelp();
+        return;
+    }
+    console.log();
+    p.intro(pc.bgCyan(pc.black(" @ybais/create-ybais-app ")));
+    let targetName = argv._[0]?.trim();
+    if (!targetName) {
+        const result = await p.text({
+            message: "Project name:",
+            placeholder: "my-ybais-app",
+            defaultValue: "my-ybais-app",
+            validate(value) {
+                if (!value.trim())
+                    return "Project name is required";
+            },
+        });
+        if (p.isCancel(result)) {
+            p.cancel("Cancelled.");
+            process.exit(1);
+        }
+        targetName = result.trim();
+    }
+    const targetDir = path.resolve(process.cwd(), targetName);
+    const dirName = path.basename(targetDir);
+    if (!isDirEmpty(targetDir)) {
+        let overwrite = argv.overwrite;
+        if (overwrite === undefined) {
+            const result = await p.select({
+                message: `Target directory ${pc.cyan(dirName)} is not empty. Overwrite?`,
+                options: [
+                    { value: "yes", label: "Yes, overwrite" },
+                    { value: "no", label: "No, cancel" },
+                ],
+            });
+            if (p.isCancel(result)) {
+                p.cancel("Cancelled.");
+                process.exit(1);
+            }
+            overwrite = result === "yes";
+        }
+        if (!overwrite) {
+            p.cancel("Cancelled — directory not empty.");
+            process.exit(1);
+        }
+        emptyDir(targetDir);
+    }
+    let packageName = toValidPackageName(dirName);
+    if (!isValidPackageName(packageName)) {
+        const result = await p.text({
+            message: "Package name (npm):",
+            placeholder: "my-ybais-app",
+            defaultValue: "my-ybais-app",
+            validate(value) {
+                if (!isValidPackageName(value)) {
+                    return "Invalid package name";
+                }
+            },
+        });
+        if (p.isCancel(result)) {
+            p.cancel("Cancelled.");
+            process.exit(1);
+        }
+        packageName = result.trim();
+    }
+    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    let testApiUrl = DEFAULT_TEST_API;
+    let prodApiUrl = DEFAULT_PROD_API;
+    let shouldInstall = false;
+    let enableVConsole = false;
+    if (interactive) {
+        const testApi = await p.text({
+            message: "Test API base URL (VITE_API_BASE_URL):",
+            placeholder: DEFAULT_TEST_API,
+            defaultValue: DEFAULT_TEST_API,
+        });
+        if (p.isCancel(testApi)) {
+            p.cancel("Cancelled.");
+            process.exit(1);
+        }
+        const prodApi = await p.text({
+            message: "Prod API base URL (VITE_API_BASE_URL):",
+            placeholder: DEFAULT_PROD_API,
+            defaultValue: DEFAULT_PROD_API,
+        });
+        if (p.isCancel(prodApi)) {
+            p.cancel("Cancelled.");
+            process.exit(1);
+        }
+        testApiUrl = String(testApi).trim() || DEFAULT_TEST_API;
+        prodApiUrl = String(prodApi).trim() || DEFAULT_PROD_API;
+        const vconsoleConfirm = await p.confirm({
+            message: "Enable vConsole for test builds? (never on prod / master; default off)",
+            initialValue: false,
+        });
+        if (p.isCancel(vconsoleConfirm)) {
+            p.cancel("Cancelled.");
+            process.exit(1);
+        }
+        enableVConsole = vconsoleConfirm === true;
+        const installConfirm = await p.confirm({
+            message: "Run pnpm install now?",
+            initialValue: false,
+        });
+        if (p.isCancel(installConfirm)) {
+            p.cancel("Cancelled.");
+            process.exit(1);
+        }
+        shouldInstall = installConfirm === true;
+    }
+    else {
+        p.log.info("Non-interactive mode — using default API URLs; skipping vConsole and pnpm install");
+    }
+    p.note([
+        `${pc.dim("package manager")}  pnpm (fixed)`,
+        `${pc.dim("vConsole")}         ${enableVConsole ? "yes (test only)" : "no"}`,
+        `${pc.dim("pnpm install")}     ${shouldInstall ? "yes" : "no"}`,
+        `${pc.dim("git init")}         yes (fixed)`,
+        `${pc.dim("mise build")}       yes (fixed)`,
+        `${pc.dim("plugin-legacy")}    yes (fixed)`,
+    ].join("\n"), "Scaffold options");
+    const s = p.spinner();
+    s.start("Copying template…");
+    if (!fs.existsSync(TEMPLATE_DIR)) {
+        s.stop("Template missing");
+        p.log.error(`Template not found at ${TEMPLATE_DIR}`);
+        process.exit(1);
+    }
+    fs.mkdirSync(targetDir, { recursive: true });
+    copyTemplate(TEMPLATE_DIR, targetDir);
+    rewritePackageJson(targetDir, packageName);
+    applyVConsoleOption(targetDir, enableVConsole);
+    writeEnvFiles(targetDir, {
+        title: dirName,
+        testApi: testApiUrl,
+        prodApi: prodApiUrl,
+    });
+    rewriteIndexHtml(targetDir, dirName);
+    s.stop("Template copied");
+    if (shouldInstall) {
+        if (!commandExists("pnpm")) {
+            p.log.error("pnpm is required but was not found. Install: https://pnpm.io/installation");
+            p.outro(pc.red("Scaffold files are ready — install pnpm, then run pnpm install in the project."));
+            process.exit(1);
+        }
+        s.start("Installing dependencies with pnpm…");
+        const install = run("pnpm", ["install"], targetDir);
+        if (!install.ok) {
+            s.stop("pnpm install failed");
+            p.log.error(install.error ?? "pnpm install failed");
+            process.exit(1);
+        }
+        s.stop("Dependencies installed");
+    }
+    else {
+        p.log.info("Skipped pnpm install");
+    }
+    if (commandExists("git")) {
+        s.start("Initializing git repository…");
+        const gitInit = run("git", ["init"], targetDir);
+        if (!gitInit.ok) {
+            s.stop("git init skipped");
+            p.log.warn(gitInit.error ?? "git init failed");
+        }
+        else {
+            run("git", ["add", "-A"], targetDir);
+            const commit = spawnSync("git", ["commit", "-m", "chore: initial commit from create-ybais-app"], {
+                cwd: targetDir,
+                stdio: "ignore",
+                shell: process.platform === "win32",
+                env: {
+                    ...process.env,
+                    GIT_AUTHOR_NAME: "create-ybais-app",
+                    GIT_AUTHOR_EMAIL: "create-ybais-app@local",
+                    GIT_COMMITTER_NAME: "create-ybais-app",
+                    GIT_COMMITTER_EMAIL: "create-ybais-app@local",
+                },
+            });
+            if (commit.status === 0) {
+                s.stop("Git repository initialized");
+            }
+            else {
+                s.stop("git commit skipped");
+                p.log.warn("git commit failed (repo still initialized)");
+            }
+        }
+    }
+    else {
+        p.log.warn("git not found — skipped git init");
+    }
+    const relativeRaw = path.relative(process.cwd(), targetDir) || ".";
+    const relative = path.isAbsolute(relativeRaw) || relativeRaw.startsWith("..")
+        ? targetDir
+        : relativeRaw;
+    const nextSteps = [pc.green("Done!"), "", `  ${pc.cyan("cd")} ${relative}`];
+    if (!shouldInstall) {
+        nextSteps.push(`  ${pc.cyan("pnpm")} install`);
+    }
+    nextSteps.push(`  ${pc.cyan("pnpm")} dev`, `  ${pc.cyan("pnpm")} build`, "", pc.dim("build 会自动处理 mise（trust + 按分支选环境），无需改配置"), pc.dim("若未安装 mise：curl https://mise.run | sh"));
+    p.outro(nextSteps.join("\n"));
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@ybais/create-ybais-app",
+  "version": "0.2.0",
+  "description": "Scaffold a YBAIS React + Vite app (pnpm, mise, legacy WebView)",
+  "type": "module",
+  "bin": {
+    "create-ybais-app": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "engines": {
+    "node": ">=26.4.0",
+    "pnpm": ">=11.9.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "mri": "^1.2.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.30",
+    "typescript": "~5.8.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "pnpm build && node ./dist/index.js",
+    "dev": "tsc -p tsconfig.json --watch"
+  }
+}

package/template/.cursor/rules/ybais-app.mdc

@@ -0,0 +1,21 @@
+---
+description: YBAIS App WebView 脚手架硬性约定（路由、@ybais 包、pnpm、环境变量、提交 dist、WebView 最低兼容）
+alwaysApply: true
+---
+
+# YBAIS App 约定
+
+- 运行环境：**App 内嵌在线 WebView**（非独立现代浏览器站）。
+- WebView 最低兼容（与 `vite.config.ts` legacy `targets` / `cssTarget` 对齐）：**iOS ≥ 12、Android ≥ 7、Chrome ≥ 55、Safari ≥ 12**，CSS 按 **chrome55**。保留 `@vitejs/plugin-legacy`；勿手写冲突的 `build.target`；图片默认勿强制 webp。改底线须同步改配置与 Skill/README。
+- 包管理：pnpm（>=11.9.0）；Node >=26.4.0（见 `package.json` engines）。`mise.toml` 用 major 模糊版本（`26` / `11`）取最新满足 engines 的线。构建：`pnpm build`（自动 trust mise，master→prod，否则 test）。
+- 别名：`@/` → `src/`。基础设施用 `@ybais/*`（bridge / alova / qiniu-upload / updater / error-guard / clipboard / center-toast / crypto / vconsole）；应用装配见 `src/api/alova.ts`、`src/api/uploader.ts`；Bridge Hooks 用 `@ybais/bridge/react`。
+- 可恢复业务错误 / 接口失败走 `reportError` / `showApiError`（sonner error）；**调试向提示走 `reportDebug`**（sonner warning，永不全屏）。
+- **`showCenterToast` 仅用于面向用户的错误提示**（如「提交失败，请重试」）；禁止用于 Bridge 调试、成功态、复制成功、加载中、Agent 随手提示。开发/调试一律 `reportDebug` / sonner / `console`。
+- 错误分类见 `@ybais/error-guard`：`page` / `business` / `runtime` / `debug` / `chunk`。
+- **vConsole**（若脚手架启用）：仅 `VITE_APP_ENV=test` 且非 `master`；`?vconsole=1` / `enableVConsole()` 手动开；**prod / master 必须杜绝**。未启用则无 `vconsole` / `@ybais/vconsole` 依赖。
+- 页面放 `src/routes/`，勿手改 `routeTree.gen.ts`。接口放 `src/api/`，经 `alovaInstance`。
+- 仅 `VITE_*` 进客户端；密钥用 `.env.*.local`。同步改 `src/vite-env.d.ts`。
+- 发版：构建后**提交并推送 `dist/`**（勿把 `dist` 写回 `.gitignore`）；整包替换含 `version.json`。
+- Native 通信用 bridge API，勿覆盖 `window` 上的命名回调代理；无 Bridge 时须 `.catch` / H5 回退。
+- 布局按移动端 WebView（安全区、小屏），勿按桌面宽屏默认。
+- 详细规范：阅读并遵循项目 Skill `.cursor/skills/ybais-app/SKILL.md`、`reference.md` 与根目录 `README.md`、`src/lib/README.md`。

package/template/.cursor/skills/ybais-app/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: ybais-app
+description: >-
+  Develop features in YBAIS App WebView scaffolds (create-ybais-app template):
+  React 18 + Vite + TanStack Router, JSBridge, Alova APIs, Qiniu upload, crypto
+  signing, production updater, and error-guard. Targets App-embedded WebView
+  with legacy floors ios>=12 / android>=7 / chrome>=55 / safari>=12. Use when
+  editing this project, adding routes or APIs, calling Native, uploading files,
+  changing env/build, handling page errors, WebView compatibility, or when the
+  user mentions bridge, alova, uploader, error-guard, @ybais, or create-ybais-app.
+---
+
+# YBAIS App 开发规范
+
+App 内嵌 **在线 WebView** H5（非独立浏览器 SPA 心智）。改代码前先遵循下列约定；细节读对应 README / `@ybais/*` 包文档，勿凭通用 React / 现代浏览器习惯覆盖本项目模式。
+
+## WebView 最低兼容（与构建配置对齐）
+
+权威来源：根目录 [`vite.config.ts`](../../../vite.config.ts) 中 `@vitejs/plugin-legacy` 的 `targets` 与 `build.cssTarget`。**改兼容底线时必须同步改该文件与本文档，勿只改一端。**
+
+| 平台 / 引擎 | 最低版本 |
+|-------------|----------|
+| iOS（WKWebView / Safari） | **≥ 12** |
+| Android（系统 WebView） | **≥ 7** |
+| Chrome | **≥ 55** |
+| Safari | **≥ 12** |
+| CSS 压缩目标 | **`chrome55`**（禁止生成旧 Safari 吃不下的新 CSS 语法） |
+
+构建侧已启用：`regenerator-runtime`、`abortcontroller-polyfill`（legacy + modern）、`web.queue-microtask` / `es.promise.all-settled` / `es.string.replace-all`（legacy + modern 显式）、`modernPolyfills`、`renderLegacyChunks`、Terser `ascii_only: true`。JS 的 `build.target` **不要**再手写，交给 legacy 插件接管。全局 CSS 补丁见 `src/styles/webview-compat.css`。
+
+### 写代码时必须遵守
+
+1. **保留** `@vitejs/plugin-legacy` 与上表 targets；禁止「为了包体积 / 现代语法」删掉或抬高底线，除非产品明确改 App 最低系统版本并同步改 `vite.config.ts`。
+2. **图片**：上传 / 展示默认 **不要强制 webp**（七牛 imageView2 亦同）；旧 WebView 对 webp 支持参差。
+3. **API / 语法**：ES 语言特性可由 legacy + core-js 兜底；**Web API**（如 `AbortController`）不在 usage 自动检测内，须走 `vite.config` 的 `additionalLegacyPolyfills` / `additionalModernPolyfills`。新增依赖若使用未 polyfill 的 DOM API，须同步补配置并重建验证。避免依赖仅很新 Chromium 才有、且无降级的 API / CSS。
+4. **布局**：按移动端 WebView 做安全区（`env(safe-area-inset-*)`）、触控与视口；勿按桌面宽屏默认设计。
+5. **Bridge**：真实能力在 App 注入的 WebView；浏览器调试无 Bridge 时封装方法会 **reject**（`BridgeUnavailableError`，经 `configureBridge({ onUnavailable })` → `reportDebug`，**非**全屏阻断），须 `.catch` H5 回退。勿用 `showCenterToast` 做 Bridge 调试提示。
+6. **相对路径**：`base: "./"`，静态资源与 `version.json` 按相对路径理解；部署须整包替换 `dist/`。
+
+更多决策细节见 [reference.md](reference.md)「WebView 兼容」一节。
+
+## 必读文档（按需打开）
+
+| 场景 | 文档 |
+|------|------|
+| 工程总览 / 脚本 / 环境变量 | [README.md](../../../README.md) |
+| `@ybais` 装配索引 | [src/lib/README.md](../../../src/lib/README.md) |
+| 扩展清单 | [reference.md](reference.md) |
+
+共享实现在 monorepo 的 `packages/@ybais/*`（或已发布的 `@ybais/*` npm 包）。
+
+## 硬性约定
+
+1. **包管理器只用 pnpm（>=11.9.0）**；Node `>=26.4.0`（见 `package.json` engines；`mise.toml` 用 `node = "26"` / `pnpm = "11"` 取最新 major 线）。构建用 `pnpm build`（脚本自动 trust mise，按分支选 test/prod），用户无需手改 mise 配置。
+2. **发版提交 `dist/`**：`pnpm build`（或 `build:prod`）后将整包 `dist/` 提交并推送；WebView / 静态托管以仓库中的产物为准。勿把 `dist` 写回 `.gitignore`。
+3. 路径别名 **`@/` → `src/`**；基础设施用 **`@ybais/<pkg>`** 按需导入；应用装配（env / goLogin）留在 `src/api/`；禁止平行再造一套 request/bridge/upload。
+4. **仅 `VITE_` 环境变量**可进客户端；密钥用 `.env.*.local`，勿写入可提交的 `.env`。
+5. **WebView 底线**：iOS ≥ 12 / Android ≥ 7 / Chrome ≥ 55 / Safari ≥ 12（见上文）；勿去掉 legacy、勿手写冲突的 `build.target`、勿强制 webp。
+6. `base: "./"`：静态资源与 `version.json` 按相对路径理解，部署须整包替换 `dist/`。
+
+## 放哪里
+
+| 需求 | 位置 |
+|------|------|
+| 页面 | `src/routes/*.tsx`（TanStack 文件路由，勿手改 `routeTree.gen.ts`） |
+| 接口封装 | `src/api/`，内部用 `alovaInstance`（`src/api/alova.ts`） |
+| 上传单例 | `src/api/uploader.ts`（`createUploader` + env） |
+| 纯工具 | `src/utils/<name>.ts`（如 `cn`）；`import { cn } from "@/utils/cn"` |
+| 环境类型 | `src/vite-env.d.ts`（新增 `VITE_*` 时同步） |
+| 样式 | Tailwind + `src/styles/`；center-toast 样式：`@ybais/center-toast/style.css` |
+
+## 模块用法速查
+
+### Bridge（H5 ↔ Native）
+
+- `import { callNative, goLogin, onNative, configureBridge } from "@ybais/bridge"`
+- 组件：`import { useNativeCall, useNativeCallback } from "@ybais/bridge/react"`
+- `main.tsx` 已 `configureBridge({ onUnavailable: … reportDebug })`
+- 浏览器无 Bridge 时会 **reject**，用 `.catch` 做 H5 回退
+
+### Alova（HTTP）
+
+- 实例在 `src/api/alova.ts`（`createYbaisAlova` + env + `onAuthFail`）
+- `alovaInstance.Get/Post/...`；业务接口写在 `src/api/`
+- Token / unwrap / businessCodeHandlers 从 `@ybais/alova` 或 `@/api/alova` 导入
+- test/prod **打包**一律用 `VITE_API_BASE_URL`；仅 **dev** 走 `/proxyApi`
+
+### Upload
+
+- `import { uploader } from "@/api/uploader"`
+- 或 `import { compressQiniuImageUrl } from "@ybais/qiniu-upload/image-process"`
+- 需配置 `VITE_QINIU_AES_KEY` / `VITE_QINIU_AES_IV`；Token 见 `src/api/qiniu.ts`
+
+### Clipboard
+
+- `import { copyText } from "@ybais/clipboard"`
+- `import { useCopyText } from "@ybais/clipboard/react"`
+- **不要**直接依赖 `navigator.clipboard`
+
+### Crypto
+
+- `import { requestCrypto, md5 } from "@ybais/crypto"`
+- key/secret 在 `src/api/alova.ts` 注入工厂
+
+### Updater
+
+- `main.tsx`：`startUpdater({ isProd: import.meta.env.PROD })`
+- 自定义提示用 `onUpdate` + `silentReloadForVersion`
+
+### Error-guard / Toast / 调试
+
+- `setupErrorGuard({ isDev })` + `ErrorGuardProvider`
+- 可恢复业务错误 → `reportError` / `showApiError`（**sonner error**）
+- **调试错误 → `reportDebug`**；勿用 `showCenterToast`
+- **`showCenterToast` 仅面向用户的错误文案**（`@ybais/center-toast`）
+- **vConsole**：`@ybais/vconsole`；仅 test 且非 master
+
+## 实现新功能时的检查清单
+
+```
+- [ ] 页面是否放在 src/routes，且未手改 routeTree.gen.ts
+- [ ] 接口是否经 alovaInstance，并落在 src/api
+- [ ] Native 调用是否用 @ybais/bridge API / Hooks
+- [ ] 新 VITE_* 是否写入 env 文件 + vite-env.d.ts
+- [ ] 是否从 @ybais/<pkg> 按需导入（未再建聚合 barrel）
+- [ ] 可恢复错误 → reportError / showApiError；调试 → reportDebug；用户向失败文案 → showCenterToast（仅此）
+- [ ] 发版是否已 pnpm build 并提交/推送最新 dist/
+- [ ] WebView：iOS 12 / Android 7 心智；无强制 webp；legacy / cssTarget: chrome55
+- [ ] 无 Bridge 时有 .catch 或 H5 回退
+```
+
+## 常见命令
+
+```bash
+pnpm install
+pnpm dev              # test + --host
+pnpm build            # master→prod，否则 test（需 mise）
+pnpm build:test|prod
+pnpm lint
+```