generator-mico-cli 0.2.31 → 0.2.32

package/generators/h5-react/templates/.cursor/skills/biz-app-analyzer/references/phase-4-module-mapping.md

@@ -0,0 +1,65 @@
+# Phase 4: Module Mapping
+
+The goal of this phase is to build a lookup index — when an AI needs to work on a specific page or module, it can check this index to immediately see what routes, APIs, stores, and components are involved.
+
+## Strategy: Breadth Over Depth
+
+Unlike Phase 3 which reads a few pages deeply, this phase scans many pages shallowly. For each page, you only need to extract its dependency fingerprint — not understand its business logic.
+
+## How to Scan Efficiently
+
+For each page file in the views/pages directory:
+
+1. **Read the `<script>` or `<script setup>` section only.** Skip the template and style — they don't contain dependency information that isn't already visible in the script.
+
+2. **Read import statements.** These reveal component, store, hook, and utility dependencies.
+
+3. **Scan for API calls.** Look for HTTP function invocations (axios calls, fetch calls, project-specific request helpers). Extract the URL/endpoint being called.
+
+4. **Check the route configuration.** Cross-reference with the route files from Phase 2 to find this page's route path.
+
+5. **Note any page-specific sub-components.** If the page directory contains additional `.vue`/`.tsx` files beyond the main page, note them as "local components" — they indicate the page is complex enough to warrant splitting.
+
+## What to Record Per Page
+
+For each page, capture:
+
+- **Route path:** The URL path this page responds to
+- **APIs:** The endpoint URLs or function calls the page makes
+- **Stores:** Which stores the page imports and uses
+- **Shared components:** Which project-level shared components are imported
+- **Local components:** Any sub-components defined alongside this page
+- **Hooks/composables:** Which shared hooks the page uses
+
+Keep the format compact. This is a reference index, not documentation.
+
+## Grouping
+
+Organize pages by **business module** — the top-level directory within views/pages. Each module gets its own section. Within a module, list pages in a logical order (typically matching the route/menu order, or alphabetically if no clear order exists).
+
+For each module, add a one-line summary of what business domain it covers, drawn from your Phase 2 and Phase 3 analysis.
+
+## Handling Scale
+
+For small projects (under 30 pages), map every page.
+
+For medium projects (30-80 pages), map every page but allow brief entries for simple pages (just route + API + key components).
+
+For large projects (80+ pages), map all modules but within each module, focus on the 3-5 most important pages. Add a note like "This module contains 12 additional pages following the standard CRUD pattern" to cover the rest.
+
+## Cross-Referencing
+
+This document becomes significantly more useful when it connects to the other documents:
+
+- When a page follows a pattern from `DEV_PATTERNS.md`, note it: "Follows Pattern A: CRUD Management"
+- When a page uses a shared component in a non-obvious way, reference the component's documentation in `PROJECT_CONTEXT.md`
+- When a page involves domain terms, use the terms defined in `GLOSSARY.md`
+
+## Phase 4 Output
+
+Fill in the `MODULE_MAP.md` template with:
+
+- One section per business module
+- Each section has a one-line module description
+- Each page within the module has its dependency fingerprint (route, APIs, stores, components, hooks)
+- Pattern references where applicable

package/generators/h5-react/templates/.cursor/skills/biz-app-analyzer/references/phase-5-glossary.md

@@ -0,0 +1,63 @@
+# Phase 5: Glossary Generation
+
+The goal of this phase is to extract and define the vocabulary that is specific to this project. Without this glossary, an AI encountering the term "guild" in a route path has no way to know it means "a group of livestream hosts organized under a manager" rather than its common English meaning.
+
+## What Belongs in the Glossary
+
+Include terms that meet **at least one** of these criteria:
+
+1. **Business domain terms** that a newcomer would not understand. These come from the industry or product domain — terms like "anchor" (meaning livestream host), "deco" (meaning virtual decoration), "settlement" (meaning payment processing for hosts).
+
+2. **Project-specific technical terms** that differ from their common meaning or are unique to this codebase. Examples: a function named `pruneVnode` that controls UI permission filtering, a parameter called `readParam` that drives auto-fetching in CustomTable, an API prefix like `proxy/maidocha_svr/` that routes through a backend gateway.
+
+3. **Abbreviations and acronyms** used in the codebase. `bizId`, `oid`, `opTypes` — these are meaningless without expansion.
+
+4. **PRD-to-code mappings** where the product team uses different vocabulary than the code. If PRDs say "streamer" but the code says "anchor", both terms need to be in the glossary with a cross-reference.
+
+## What Does NOT Belong
+
+Exclude terms that are:
+
+- **General programming concepts**: "component", "store", "router", "hook" — unless the project uses these words with a non-standard meaning
+- **Framework-standard vocabulary**: "defineProps", "reactive", "middleware" — unless the project has a custom implementation that changes expected behavior
+- **Self-explanatory names**: `userList`, `isLoading`, `handleSubmit` — these don't need definitions
+
+## Where to Find Terms
+
+Draw from all previous phases:
+
+- **Phase 1**: Directory names, dependency names, environment variable names
+- **Phase 2**: Store names and their data fields, API path segments, component names, permission-related terms
+- **Phase 3**: Pattern names, business module names discovered during page sampling
+- **Phase 4**: Route path segments, API endpoint segments, business module descriptions
+
+Also scan for:
+- **Enum files**: These often contain domain vocabulary (status names, type names, category names)
+- **Constant files**: Named constants often encode domain concepts
+- **i18n files**: Translation keys and values reveal how the product talks about its features
+
+## Structure
+
+Organize the glossary into two sections:
+
+### Business Terms
+
+These are terms from the product/business domain. For each term:
+- The term as it appears in code (e.g., `guild`)
+- Its meaning in the product context (e.g., "An organization of livestream hosts managed by a guild leader")
+- Alternative names if the PRD or users call it differently (e.g., "Also called 'agency' in some PRDs")
+
+### Technical Terms
+
+These are codebase-specific technical terms. For each term:
+- The term (e.g., `readParam`)
+- What it means/does (e.g., "The reactive parameter object that drives CustomTable's auto-fetch behavior. When any field in readParam changes, CustomTable re-fetches data from readURL.")
+- Where it's used (e.g., "Seen in every CRUD list page")
+
+## Quality Check
+
+A good glossary passes this test: take any term from it, imagine an AI encountering that term in the codebase for the first time, and ask — would the definition give enough context to use it correctly? If not, the definition needs more specificity.
+
+## Phase 5 Output
+
+Fill in the `GLOSSARY.md` template with the two sections above. Aim for 15-40 terms for a typical project — enough to cover the non-obvious vocabulary without becoming an exhaustive dictionary.

package/generators/h5-react/templates/.cursor/skills/biz-app-analyzer/references/templates/DEV_PATTERNS.tpl.md

@@ -0,0 +1,77 @@
+# {Project Name} — Development Patterns
+
+<!-- This document bridges understanding and action. An AI reading a PRD should be able to match the requirement to a pattern here and know exactly what to do. -->
+
+## New Page Checklist
+
+Every new page in this project requires the following steps, regardless of the page type:
+
+<!-- List all side-effects. Adapt this list based on what Phase 3 analysis discovers. -->
+
+1. **Create the page file:** {Where, naming convention}
+2. **Register the route:** {Which file, what fields are required}
+3. **Add i18n entries:** {Which language files, key naming convention}
+4. **Configure permissions:** {If applicable — where and how}
+5. **Add menu entry:** {If menu is separate from routes — where and how}
+6. {Any other project-specific setup steps}
+
+---
+
+## Pattern A: {Pattern Name}
+
+<!-- Most common pattern first. -->
+
+**When to use:** {PRD keywords or requirement characteristics that signal this pattern. Write in terms of product language, not code language.}
+
+**File structure:**
+```
+{directory}/{FeatureName}/
+├── {main file}
+└── {sub-components if applicable}
+```
+
+**Standard structure:**
+
+<!-- Describe the page's component composition and data flow in narrative form. Don't write code — describe the architecture. -->
+
+{Description of the page skeleton — what components form the layout, how they're connected, what drives data fetching, how user actions flow through the system.}
+
+**Data flow:**
+
+1. {Page mount → initial data loading}
+2. {User interaction → data fetch/mutation}
+3. {Submit/save → API call → refresh}
+
+**Reference page:** `{exact file path of a real page that exemplifies this pattern}`
+
+---
+
+## Pattern B: {Pattern Name}
+
+**When to use:** {trigger conditions}
+
+**File structure:**
+```
+{…}
+```
+
+**Standard structure:**
+
+{…}
+
+**Data flow:**
+
+1. {…}
+
+**Reference page:** `{path}`
+
+---
+
+<!-- Repeat for each identified pattern. Typical projects have 3-5 patterns. -->
+
+## Variations & Edge Cases
+
+<!-- Note any common deviations from the patterns above. -->
+
+- {Variation description, e.g., "Some CRUD pages use a drawer instead of a dialog for editing large forms"}
+- {…}

package/generators/h5-react/templates/.cursor/skills/biz-app-analyzer/references/templates/GLOSSARY.tpl.md

@@ -0,0 +1,17 @@
+# {Project Name} — Glossary
+
+<!-- Terms that a newcomer (human or AI) would not immediately understand when encountering them in this codebase. -->
+
+## Business Terms
+
+| Term | Meaning | Also Known As |
+|------|---------|---------------|
+| {term} | {definition in the product context} | {alternative names in PRDs or user-facing text, if any} |
+| {…} | {…} | |
+
+## Technical Terms
+
+| Term | Meaning | Where Used |
+|------|---------|-----------|
+| {term} | {what it means/does in this codebase} | {where you'll encounter it — e.g., "CRUD list pages", "route guards"} |
+| {…} | {…} | |

package/generators/h5-react/templates/.cursor/skills/biz-app-analyzer/references/templates/MODULE_MAP.tpl.md

@@ -0,0 +1,45 @@
+# {Project Name} — Module Map
+
+<!-- This is a lookup index. When an AI needs to work on a specific page, it checks here to see the full dependency picture. -->
+
+## {Module Name}
+
+{One-line description of what business domain this module covers.}
+
+### {PageName}
+
+- **Route:** `{/path/to/page}`
+- **Pattern:** {Pattern name from DEV_PATTERNS.md, if applicable}
+- **APIs:** {List of endpoint URLs or API function calls}
+- **Stores:** {List of stores used}
+- **Components:** {List of shared components imported}
+- **Hooks:** {List of hooks/composables used}
+- **Local sub-components:** {Any page-specific components, or "none"}
+
+### {PageName}
+
+- **Route:** `{/path}`
+- **Pattern:** {…}
+- **APIs:** {…}
+- **Stores:** {…}
+- **Components:** {…}
+- **Hooks:** {…}
+
+<!-- Repeat for each page in this module -->
+
+---
+
+## {Module Name}
+
+{One-line description.}
+
+### {PageName}
+
+- **Route:** `{/path}`
+- **Pattern:** {…}
+- **APIs:** {…}
+- **Stores:** {…}
+- **Components:** {…}
+- **Hooks:** {…}
+
+<!-- Repeat for each module -->

package/generators/h5-react/templates/.cursor/skills/biz-app-analyzer/references/templates/PROJECT_CONTEXT.tpl.md

@@ -0,0 +1,155 @@
+# {Project Name} — Project Context
+
+<!-- This is the core knowledge document. An AI reading only this file should understand 80% of what it needs to work effectively in this project. -->
+
+## Project Overview
+
+<!-- What the product does, who uses it, and why it exists. Write for someone who has never seen this codebase. -->
+
+**Product:** {One-sentence description of what the product is}
+
+**Users:** {Who uses this application — internal team? End users? Admins?}
+
+**Business domain:** {What industry/domain — e-commerce, social platform, fintech, SaaS, etc.}
+
+## Tech Stack
+
+| Layer | Technology | Version |
+|-------|-----------|---------|
+| Framework | {e.g., Vue} | {e.g., 3.5.13} |
+| Language | {e.g., TypeScript} | {e.g., 5.7} |
+| Build tool | {e.g., Vite} | {e.g., 6.x} |
+| UI library | {e.g., Element Plus} | {e.g., 2.8} |
+| State management | {e.g., Pinia} | |
+| Router | {e.g., Vue Router, hash mode} | |
+| HTTP client | {e.g., Axios} | |
+| i18n | {e.g., vue-i18n} | |
+| Other notable | {e.g., Sentry, echarts, etc.} | |
+
+## Environment Configuration
+
+| Variable | Purpose |
+|----------|---------|
+| {VITE_API_BASE_URL} | {Main API endpoint} |
+| {…} | {…} |
+
+**Dev proxy rules:**
+<!-- List dev server proxy paths and their targets -->
+
+## Directory Structure
+
+```
+src/
+├── {directory}/     # {role description}
+├── {directory}/     # {role description}
+└── ...
+```
+
+<!-- Annotate every top-level source directory with its role. -->
+
+**Path aliases:**
+- `{@/}` → `{src/}`
+- {…}
+
+## Request Mechanisms
+
+<!-- Describe each HTTP request pattern as a flow. Include: base URL strategy, auth injection, success/error handling, when to use this pattern. -->
+
+### {Pattern Name, e.g., "Main Business API"}
+
+{Narrative flow description — see Phase 2 instructions for the level of detail expected.}
+
+### {Pattern Name, e.g., "Activity API"}
+
+{If there are multiple request patterns, describe each one.}
+
+## Routing & Navigation
+
+**Mode:** {hash / history}
+
+**Layout structure:** {Describe the page shell — header, sidebar, content area, tabs, etc.}
+
+**Route organization:** {How routes are split — one file per module, etc.}
+
+**Navigation guard flow:**
+<!-- Describe the guard chain: what checks happen before a page renders -->
+
+1. {First check, e.g., "White-listed routes bypass all checks"}
+2. {Second check, e.g., "Fetch user info if not loaded"}
+3. {Third check, e.g., "Verify route is in user's permitted menu list"}
+4. {Fallback, e.g., "Redirect to 404 if not permitted"}
+
+## State Management
+
+<!-- For each store, describe its responsibility, key data, core methods, and how pages consume it. -->
+
+### {Store Name}
+
+**Responsibility:** {What domain this store owns}
+
+**Key state:**
+- `{field}`: {type and purpose}
+- {…}
+
+**Core methods:**
+- `{method}()`: {what it does}
+- {…}
+
+**Used by:** {Which modules/pages depend on this store}
+
+<!-- Repeat for each store -->
+
+## Auth & Permissions
+
+**Authentication:** {How users prove identity — token type, storage location, refresh mechanism}
+
+**Route-level control:** {How the system decides if a user can access a page}
+
+**In-page control:** {How the system controls actions within a page — button visibility, tab filtering, etc.}
+
+**Permission data source:** {Where permission data comes from and its structure}
+
+## Shared Components
+
+<!-- For each significant shared component, document its purpose, key interface, collaboration pattern, and gotchas. -->
+
+### {ComponentName}
+
+**Purpose:** {When to use this component}
+
+**Key Props:**
+- `{prop}` ({type}): {what it controls}
+- {…}
+
+**Key Events:**
+- `{event}`: {when it fires, what payload}
+- {…}
+
+**Collaboration:** {How this component works with other components, hooks, or APIs}
+
+<!-- Repeat for each shared component -->
+
+## Hooks / Composables
+
+<!-- For each shared hook, document what problem it solves, its interface, and typical usage. -->
+
+### {hookName}
+
+**Solves:** {What repetitive problem this hook eliminates}
+
+**Parameters:** {Key parameters and types}
+
+**Returns:** {Key return values and types}
+
+**Typical usage:** {One-sentence description of how pages use it}
+
+<!-- Repeat for each hook -->
+
+## Utility Functions
+
+<!-- Brief listing of key utility modules and their most-used functions. Only detail functions that are widely used or have non-obvious behavior. -->
+
+### {utils/fileName}
+
+- `{functionName}()`: {what it does}
+- {…}

package/generators/h5-react/templates/.cursor/skills/biz-app-analyzer/references/update-mode.md

@@ -0,0 +1,116 @@
+# Update Mode: Incremental Document Refresh
+
+Instead of re-analyzing the entire project, compare the current state against the last-known snapshot and update only what changed.
+
+## Step 1: Load the Baseline
+
+Read `.ai-docs-meta.json` from the project's `.ai-docs/` directory. This file was written during the last full generation or update. It contains:
+
+- `generated_at`: when the documents were last generated
+- `files_snapshot.views_modules`: the list of business modules (top-level dirs under views/)
+- `files_snapshot.pages`: all page file paths
+- `files_snapshot.components`: all shared component entries
+- `files_snapshot.hooks`: all hook/composable files
+- `files_snapshot.stores`: all store files
+- `files_snapshot.critical_files`: key mechanism files with their last-modified timestamps
+
+If `.ai-docs-meta.json` doesn't exist, the documents were generated by an older version of this skill. Suggest a full regeneration instead of incremental update.
+
+## Step 2: Scan Current State
+
+Collect the same information from the live project:
+
+1. List top-level directories under views/ (or pages/) → current modules
+2. List all `.vue`/`.tsx`/`.jsx` files under views/ → current pages
+3. List entries under components/ → current components
+4. List files under hooks/ (or composables/) → current hooks
+5. List files under store/ (or stores/) → current stores
+6. Stat the modification time of each file listed in `critical_files`
+
+This step should only use directory listing and file stat operations — no file content reading yet.
+
+## Step 3: Compute the Diff
+
+Compare current state against the baseline snapshot:
+
+**Module diff:**
+- `added_modules`: directories in current but not in snapshot
+- `removed_modules`: directories in snapshot but not in current
+
+**Page diff:**
+- `added_pages`: page files in current but not in snapshot
+- `removed_pages`: page files in snapshot but not in current
+
+**Shared capability diff:**
+- `added_components`: new entries in components/
+- `removed_components`: entries missing from components/
+- `added_hooks`: new files in hooks/
+- `removed_hooks`: files missing from hooks/
+- `added_stores`: new files in store/
+- `removed_stores`: files missing from store/
+
+**Critical file diff:**
+- `modified_critical_files`: files whose modification time is newer than the snapshot timestamp
+
+**Staleness:**
+- `days_since_generation`: days between now and `generated_at`
+
+## Step 4: Determine Response Tier
+
+Apply these rules in order:
+
+### Tier 3: Full Regeneration Recommended
+
+Trigger if **any** of these are true:
+- `added_modules` is non-empty (a whole new business domain appeared)
+- `modified_critical_files` is non-empty (architecture-level code changed)
+- `days_since_generation` exceeds 30
+- `package.json` modification time is newer than snapshot (dependencies may have changed)
+
+**Action:** Inform the user what changed and recommend running the full analysis. Example:
+
+> "Detected changes since the last analysis: new module 'liveRoom' added, router/index.ts modified, and it's been 45 days since generation. These changes likely affect architecture documentation. I recommend running a full project analysis to regenerate the knowledge base."
+
+If the user agrees, run the full five-phase flow from the main SKILL.md. If the user declines, proceed with Tier 2/1 updates for the non-critical changes, but add a warning note at the top of each updated document that architectural sections may be outdated.
+
+### Tier 2: Targeted Update
+
+Trigger if `added_components`, `added_hooks`, or `added_stores` are non-empty (and Tier 3 was not triggered).
+
+**Action for each new component/hook/store:**
+1. Read the file content
+2. Analyze its purpose, interface, and collaboration patterns (same approach as Phase 2, Mechanism E)
+3. Append a new entry to the corresponding section in `PROJECT_CONTEXT.md`
+
+**Action for removed components/hooks/stores:**
+1. Remove the corresponding entry from `PROJECT_CONTEXT.md`
+2. Check if any pattern in `DEV_PATTERNS.md` references the removed item — if so, flag it for the user
+
+After updates, show the user what was added/removed and ask for confirmation.
+
+### Tier 1: Auto-fixable
+
+Trigger if `added_pages` or `removed_pages` are non-empty (and neither Tier 3 nor Tier 2 was triggered, or as an additional step alongside Tier 2).
+
+**Action for each new page:**
+1. Read the `<script>` / `<script setup>` section of the page file
+2. Extract its dependency fingerprint: route path (from router config), API calls, store imports, component imports, hook usage
+3. Determine which module it belongs to based on its directory
+4. Append an entry to the corresponding module section in `MODULE_MAP.md`
+5. If the page follows a recognized pattern from `DEV_PATTERNS.md`, note the pattern reference
+
+**Action for each removed page:**
+1. Remove its entry from `MODULE_MAP.md`
+2. Check if it was the reference page for any pattern in `DEV_PATTERNS.md` — if so, suggest a replacement reference page from the same module
+
+## Step 5: Update the Meta File
+
+After all updates are complete, rewrite `.ai-docs-meta.json` with the current project state. This becomes the new baseline for the next update cycle.
+
+## Edge Cases
+
+**Multiple changes across tiers:** If the diff contains both Tier 1 and Tier 2 changes, process Tier 2 first (since it updates `PROJECT_CONTEXT.md` which provides context), then Tier 1 (which updates `MODULE_MAP.md`).
+
+**Renamed files:** A file appearing in both `removed` and `added` with similar names is likely a rename, not a delete+create. Note this to the user but process it as a removal and addition — the content may have changed along with the name.
+
+**Large batch of new pages:** If more than 10 pages were added since the last snapshot, it may be more efficient to re-run Phase 4 (Module Mapping) entirely rather than adding pages one by one.

package/generators/h5-react/templates/.env.development

@@ -0,0 +1,5 @@
+CHECK_TIMEOUT=10
+UMI_APP_API_BASE_URL=/api
+UMI_APP_CDN_BASE_URL=//cdn.micoplatform.com
+UMI_APP_LANG_BASE_URL=https://api-test.micoplatform.com/lang_server/pull
+UMI_APP_ENV=development

package/generators/h5-react/templates/.env.production

@@ -0,0 +1,5 @@
+CHECK_TIMEOUT=10
+UMI_APP_API_BASE_URL=https://api.micoplatform.com
+UMI_APP_CDN_BASE_URL=//cdn.micoplatform.com
+UMI_APP_LANG_BASE_URL=https://api.micoplatform.com/lang_server/pull
+UMI_APP_ENV=production

package/generators/h5-react/templates/.env.testing

@@ -0,0 +1,5 @@
+CHECK_TIMEOUT=10
+UMI_APP_API_BASE_URL=https://api-test.micoplatform.com
+UMI_APP_CDN_BASE_URL=//cdn.micoplatform.com
+UMI_APP_LANG_BASE_URL=https://api-test.micoplatform.com/lang_server/pull
+UMI_APP_ENV=testing

package/generators/h5-react/templates/.husky/commit-msg

@@ -0,0 +1,2 @@
+#!/usr/bin/env sh
+pnpm exec commitlint --edit "$1"

package/generators/h5-react/templates/.husky/pre-commit

@@ -0,0 +1,2 @@
+pnpm run lint-staged
+git add .

package/generators/h5-react/templates/.lintstagedrc.js

@@ -0,0 +1,8 @@
+/**
+ * @type {import('lint-staged').Configuration}
+ */
+module.exports = {
+  'apps/*/**/*.{js,jsx,ts,tsx}': 'eslint --flag v10_config_lookup_from_file --fix',
+  'apps/*/**/*.{css,less}': 'stylelint --fix',
+  'packages/!(eslint)/**/*.{js,jsx,ts,tsx}': 'eslint --flag v10_config_lookup_from_file --fix',
+};

package/generators/h5-react/templates/.prettierrc.json

@@ -0,0 +1,7 @@
+{
+  "printWidth": 80,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "proseWrap": "never",
+  "plugins": ["prettier-plugin-organize-imports", "prettier-plugin-packagejson"]
+}

package/generators/h5-react/templates/CICD/before_build.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+
+# 计算当前构建分支的 BASE_REF，并为 Turbo 增量构建准备 TURBO_FILTER
+# 该脚本会被其他脚本 source 调用，不要在这里直接 exit 1
+
+set -e
+
+# 获取项目根目录（如果调用方已设置 PROJECT_ROOT，则使用；否则使用当前工作目录）
+PROJECT_ROOT="${PROJECT_ROOT:-$(pwd)}"
+
+# 获取当前构建的分支（去掉 origin/ 前缀，用于比较）
+# 优先使用环境变量 CURRENT_BRANCH（Jenkins 传入，格式可能是 origin/main、origin/feat/xxx）
+# 其次使用 BRANCH_OR_TAG，最后从 git 获取
+if [ -n "${CURRENT_BRANCH}" ]; then
+  CURRENT_BRANCH_NAME="${CURRENT_BRANCH#origin/}"  # 去掉 origin/ 前缀
+elif [ -n "${BRANCH_OR_TAG}" ]; then
+  CURRENT_BRANCH_NAME="${BRANCH_OR_TAG#origin/}"  # 去掉 origin/ 前缀
+else
+  CURRENT_BRANCH_NAME="$(git rev-parse --abbrev-ref HEAD)"
+fi
+
+echo "[before_build] Current branch (without origin/): ${CURRENT_BRANCH_NAME}"
+
+# 比较当前分支和上次成功构建的分支是否一致
+# LAST_SUCCESS_BRANCH 由 Jenkins 在构建时设置（从上次构建的结果中获取，格式可能是 origin/main、origin/feat/xxx）
+if [ -n "${LAST_SUCCESS_BRANCH}" ]; then
+  # 去掉 LAST_SUCCESS_BRANCH 的 origin/ 前缀，用于比较
+  LAST_SUCCESS_BRANCH_NAME="${LAST_SUCCESS_BRANCH#origin/}"
+  echo "[before_build] Last success branch (without origin/): ${LAST_SUCCESS_BRANCH_NAME}"
+  
+  if [ "${CURRENT_BRANCH_NAME}" != "${LAST_SUCCESS_BRANCH_NAME}" ]; then
+    # 分支不一致，需要全量构建
+    echo "[before_build] Branch changed: ${LAST_SUCCESS_BRANCH_NAME} -> ${CURRENT_BRANCH_NAME}, will perform full build (no filter)"
+    unset TURBO_FILTER
+  else
+    # 分支一致，尝试使用 PREVIOUS_COMMIT 进行增量构建
+    echo "[before_build] Branch unchanged: ${CURRENT_BRANCH_NAME}, checking PREVIOUS_COMMIT for incremental build"
+    if [ -n "${PREVIOUS_COMMIT}" ]; then
+      # 验证 commit 是否存在且有效
+      if git rev-parse --verify "${PREVIOUS_COMMIT}" >/dev/null 2>&1; then
+        # 关键检查：验证 PREVIOUS_COMMIT 是否是当前 HEAD 的祖先
+        # 这可以避免以下问题：
+        # 1. Rebase/Force push：PREVIOUS_COMMIT 不再是当前分支的祖先
+        # 2. Tag 被其他分支更新：PREVIOUS_COMMIT 不是当前分支的祖先
+        CURRENT_HEAD="$(git rev-parse HEAD)"
+        if git merge-base --is-ancestor "${PREVIOUS_COMMIT}" "${CURRENT_HEAD}" 2>/dev/null; then
+          # PREVIOUS_COMMIT 是当前 HEAD 的祖先，可以安全使用
+          BASE_REF="${PREVIOUS_COMMIT}"
+          echo "[before_build] Use PREVIOUS_COMMIT as BASE_REF: ${BASE_REF} (ancestor check passed)"
+          # 为 turbo --filter 准备语法形如 ...[<BASE_REF>]
+          TURBO_FILTER="...[${BASE_REF}]"
+          export TURBO_FILTER
+          echo "[before_build] TURBO_FILTER=${TURBO_FILTER} (incremental build)"
+        else
+          # PREVIOUS_COMMIT 不是当前 HEAD 的祖先，降级为全量构建
+          echo "[before_build] Warning: PREVIOUS_COMMIT=${PREVIOUS_COMMIT} is not an ancestor of HEAD=${CURRENT_HEAD}"
+          echo "[before_build] Possible reasons: rebase/force-push, tag updated by another branch, or shallow clone issue"
+          echo "[before_build] Falling back to full build (no filter)"
+          unset TURBO_FILTER
+        fi
+      else
+        echo "[before_build] Warning: PREVIOUS_COMMIT=${PREVIOUS_COMMIT} is not a valid commit, will perform full build"
+        unset TURBO_FILTER
+      fi
+    else
+      # PREVIOUS_COMMIT 未设置，进行全量构建
+      echo "[before_build] PREVIOUS_COMMIT not set, will perform full build (no filter)"
+      unset TURBO_FILTER
+    fi
+  fi
+else
+  # LAST_SUCCESS_BRANCH 未设置，说明是第一次构建或 Jenkins 未配置该环境变量
+  echo "[before_build] LAST_SUCCESS_BRANCH not set, will perform full build (no filter)"
+  # 不设置 TURBO_FILTER，这样 package.json 中的 ${TURBO_FILTER:+--filter=${TURBO_FILTER}} 不会生效
+  unset TURBO_FILTER
+fi