@mison/ag-kit-cn 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agent/.shared/ui-ux-pro-max/data/charts.csv +26 -0
- package/.agent/.shared/ui-ux-pro-max/data/colors.csv +97 -0
- package/.agent/.shared/ui-ux-pro-max/data/icons.csv +101 -0
- package/.agent/.shared/ui-ux-pro-max/data/landing.csv +31 -0
- package/.agent/.shared/ui-ux-pro-max/data/products.csv +97 -0
- package/.agent/.shared/ui-ux-pro-max/data/prompts.csv +24 -0
- package/.agent/.shared/ui-ux-pro-max/data/react-performance.csv +45 -0
- package/.agent/.shared/ui-ux-pro-max/data/stacks/flutter.csv +53 -0
- package/.agent/.shared/ui-ux-pro-max/data/stacks/html-tailwind.csv +56 -0
- package/.agent/.shared/ui-ux-pro-max/data/stacks/jetpack-compose.csv +53 -0
- package/.agent/.shared/ui-ux-pro-max/data/stacks/nextjs.csv +53 -0
- package/.agent/.shared/ui-ux-pro-max/data/stacks/nuxt-ui.csv +51 -0
- package/.agent/.shared/ui-ux-pro-max/data/stacks/nuxtjs.csv +59 -0
- package/.agent/.shared/ui-ux-pro-max/data/stacks/react-native.csv +52 -0
- package/.agent/.shared/ui-ux-pro-max/data/stacks/react.csv +54 -0
- package/.agent/.shared/ui-ux-pro-max/data/stacks/shadcn.csv +61 -0
- package/.agent/.shared/ui-ux-pro-max/data/stacks/svelte.csv +54 -0
- package/.agent/.shared/ui-ux-pro-max/data/stacks/swiftui.csv +51 -0
- package/.agent/.shared/ui-ux-pro-max/data/stacks/vue.csv +50 -0
- package/.agent/.shared/ui-ux-pro-max/data/styles.csv +59 -0
- package/.agent/.shared/ui-ux-pro-max/data/typography.csv +58 -0
- package/.agent/.shared/ui-ux-pro-max/data/ui-reasoning.csv +101 -0
- package/.agent/.shared/ui-ux-pro-max/data/ux-guidelines.csv +100 -0
- package/.agent/.shared/ui-ux-pro-max/data/web-interface.csv +31 -0
- package/.agent/.shared/ui-ux-pro-max/scripts/core.py +258 -0
- package/.agent/.shared/ui-ux-pro-max/scripts/design_system.py +1067 -0
- package/.agent/.shared/ui-ux-pro-max/scripts/search.py +106 -0
- package/.agent/ARCHITECTURE.md +285 -0
- package/.agent/agents/backend-specialist.md +268 -0
- package/.agent/agents/code-archaeologist.md +106 -0
- package/.agent/agents/database-architect.md +225 -0
- package/.agent/agents/debugger.md +225 -0
- package/.agent/agents/devops-engineer.md +242 -0
- package/.agent/agents/documentation-writer.md +104 -0
- package/.agent/agents/explorer-agent.md +73 -0
- package/.agent/agents/frontend-specialist.md +618 -0
- package/.agent/agents/game-developer.md +162 -0
- package/.agent/agents/mobile-developer.md +382 -0
- package/.agent/agents/orchestrator.md +438 -0
- package/.agent/agents/penetration-tester.md +188 -0
- package/.agent/agents/performance-optimizer.md +187 -0
- package/.agent/agents/product-manager.md +112 -0
- package/.agent/agents/product-owner.md +95 -0
- package/.agent/agents/project-planner.md +405 -0
- package/.agent/agents/qa-automation-engineer.md +103 -0
- package/.agent/agents/security-auditor.md +170 -0
- package/.agent/agents/seo-specialist.md +111 -0
- package/.agent/agents/test-engineer.md +158 -0
- package/.agent/mcp_config.json +12 -0
- package/.agent/rules/GEMINI.md +273 -0
- package/.agent/scripts/auto_preview.py +148 -0
- package/.agent/scripts/checklist.py +217 -0
- package/.agent/scripts/session_manager.py +120 -0
- package/.agent/scripts/verify_all.py +327 -0
- package/.agent/skills/api-patterns/SKILL.md +84 -0
- package/.agent/skills/api-patterns/api-style.md +42 -0
- package/.agent/skills/api-patterns/auth.md +24 -0
- package/.agent/skills/api-patterns/documentation.md +26 -0
- package/.agent/skills/api-patterns/graphql.md +41 -0
- package/.agent/skills/api-patterns/rate-limiting.md +31 -0
- package/.agent/skills/api-patterns/response.md +37 -0
- package/.agent/skills/api-patterns/rest.md +40 -0
- package/.agent/skills/api-patterns/scripts/api_validator.py +211 -0
- package/.agent/skills/api-patterns/security-testing.md +122 -0
- package/.agent/skills/api-patterns/trpc.md +41 -0
- package/.agent/skills/api-patterns/versioning.md +22 -0
- package/.agent/skills/app-builder/SKILL.md +75 -0
- package/.agent/skills/app-builder/agent-coordination.md +74 -0
- package/.agent/skills/app-builder/feature-building.md +53 -0
- package/.agent/skills/app-builder/project-detection.md +34 -0
- package/.agent/skills/app-builder/scaffolding.md +118 -0
- package/.agent/skills/app-builder/tech-stack.md +40 -0
- package/.agent/skills/app-builder/templates/SKILL.md +39 -0
- package/.agent/skills/app-builder/templates/astro-static/TEMPLATE.md +76 -0
- package/.agent/skills/app-builder/templates/chrome-extension/TEMPLATE.md +92 -0
- package/.agent/skills/app-builder/templates/cli-tool/TEMPLATE.md +88 -0
- package/.agent/skills/app-builder/templates/electron-desktop/TEMPLATE.md +88 -0
- package/.agent/skills/app-builder/templates/express-api/TEMPLATE.md +83 -0
- package/.agent/skills/app-builder/templates/flutter-app/TEMPLATE.md +90 -0
- package/.agent/skills/app-builder/templates/monorepo-turborepo/TEMPLATE.md +90 -0
- package/.agent/skills/app-builder/templates/nextjs-fullstack/TEMPLATE.md +122 -0
- package/.agent/skills/app-builder/templates/nextjs-saas/TEMPLATE.md +122 -0
- package/.agent/skills/app-builder/templates/nextjs-static/TEMPLATE.md +169 -0
- package/.agent/skills/app-builder/templates/nuxt-app/TEMPLATE.md +134 -0
- package/.agent/skills/app-builder/templates/python-fastapi/TEMPLATE.md +83 -0
- package/.agent/skills/app-builder/templates/react-native-app/TEMPLATE.md +119 -0
- package/.agent/skills/architecture/SKILL.md +57 -0
- package/.agent/skills/architecture/context-discovery.md +43 -0
- package/.agent/skills/architecture/examples.md +94 -0
- package/.agent/skills/architecture/pattern-selection.md +68 -0
- package/.agent/skills/architecture/patterns-reference.md +50 -0
- package/.agent/skills/architecture/trade-off-analysis.md +77 -0
- package/.agent/skills/bash-linux/SKILL.md +201 -0
- package/.agent/skills/behavioral-modes/SKILL.md +264 -0
- package/.agent/skills/brainstorming/SKILL.md +164 -0
- package/.agent/skills/brainstorming/dynamic-questioning.md +359 -0
- package/.agent/skills/clean-code/SKILL.md +200 -0
- package/.agent/skills/code-review-checklist/SKILL.md +125 -0
- package/.agent/skills/database-design/SKILL.md +54 -0
- package/.agent/skills/database-design/database-selection.md +43 -0
- package/.agent/skills/database-design/indexing.md +39 -0
- package/.agent/skills/database-design/migrations.md +50 -0
- package/.agent/skills/database-design/optimization.md +36 -0
- package/.agent/skills/database-design/orm-selection.md +30 -0
- package/.agent/skills/database-design/schema-design.md +56 -0
- package/.agent/skills/database-design/scripts/schema_validator.py +172 -0
- package/.agent/skills/deployment-procedures/SKILL.md +241 -0
- package/.agent/skills/doc.md +177 -0
- package/.agent/skills/documentation-templates/SKILL.md +194 -0
- package/.agent/skills/frontend-design/SKILL.md +418 -0
- package/.agent/skills/frontend-design/animation-guide.md +331 -0
- package/.agent/skills/frontend-design/color-system.md +307 -0
- package/.agent/skills/frontend-design/decision-trees.md +418 -0
- package/.agent/skills/frontend-design/motion-graphics.md +306 -0
- package/.agent/skills/frontend-design/scripts/accessibility_checker.py +183 -0
- package/.agent/skills/frontend-design/scripts/ux_audit.py +727 -0
- package/.agent/skills/frontend-design/typography-system.md +345 -0
- package/.agent/skills/frontend-design/ux-psychology.md +1118 -0
- package/.agent/skills/frontend-design/visual-effects.md +383 -0
- package/.agent/skills/game-development/2d-games/SKILL.md +119 -0
- package/.agent/skills/game-development/3d-games/SKILL.md +135 -0
- package/.agent/skills/game-development/SKILL.md +167 -0
- package/.agent/skills/game-development/game-art/SKILL.md +185 -0
- package/.agent/skills/game-development/game-audio/SKILL.md +190 -0
- package/.agent/skills/game-development/game-design/SKILL.md +129 -0
- package/.agent/skills/game-development/mobile-games/SKILL.md +108 -0
- package/.agent/skills/game-development/multiplayer/SKILL.md +132 -0
- package/.agent/skills/game-development/pc-games/SKILL.md +144 -0
- package/.agent/skills/game-development/vr-ar/SKILL.md +123 -0
- package/.agent/skills/game-development/web-games/SKILL.md +150 -0
- package/.agent/skills/geo-fundamentals/SKILL.md +155 -0
- package/.agent/skills/geo-fundamentals/scripts/geo_checker.py +289 -0
- package/.agent/skills/i18n-localization/SKILL.md +154 -0
- package/.agent/skills/i18n-localization/scripts/i18n_checker.py +241 -0
- package/.agent/skills/intelligent-routing/SKILL.md +335 -0
- package/.agent/skills/lint-and-validate/SKILL.md +44 -0
- package/.agent/skills/lint-and-validate/scripts/lint_runner.py +184 -0
- package/.agent/skills/lint-and-validate/scripts/type_coverage.py +173 -0
- package/.agent/skills/mcp-builder/SKILL.md +176 -0
- package/.agent/skills/mobile-design/SKILL.md +394 -0
- package/.agent/skills/mobile-design/decision-trees.md +516 -0
- package/.agent/skills/mobile-design/mobile-backend.md +491 -0
- package/.agent/skills/mobile-design/mobile-color-system.md +420 -0
- package/.agent/skills/mobile-design/mobile-debugging.md +122 -0
- package/.agent/skills/mobile-design/mobile-design-thinking.md +355 -0
- package/.agent/skills/mobile-design/mobile-navigation.md +458 -0
- package/.agent/skills/mobile-design/mobile-performance.md +767 -0
- package/.agent/skills/mobile-design/mobile-testing.md +356 -0
- package/.agent/skills/mobile-design/mobile-typography.md +432 -0
- package/.agent/skills/mobile-design/platform-android.md +666 -0
- package/.agent/skills/mobile-design/platform-ios.md +561 -0
- package/.agent/skills/mobile-design/scripts/mobile_audit.py +670 -0
- package/.agent/skills/mobile-design/touch-psychology.md +537 -0
- package/.agent/skills/nextjs-react-expert/1-async-eliminating-waterfalls.md +311 -0
- package/.agent/skills/nextjs-react-expert/2-bundle-bundle-size-optimization.md +241 -0
- package/.agent/skills/nextjs-react-expert/3-server-server-side-performance.md +489 -0
- package/.agent/skills/nextjs-react-expert/4-client-client-side-data-fetching.md +263 -0
- package/.agent/skills/nextjs-react-expert/5-rerender-re-render-optimization.md +581 -0
- package/.agent/skills/nextjs-react-expert/6-rendering-rendering-performance.md +431 -0
- package/.agent/skills/nextjs-react-expert/7-js-javascript-performance.md +683 -0
- package/.agent/skills/nextjs-react-expert/8-advanced-advanced-patterns.md +149 -0
- package/.agent/skills/nextjs-react-expert/SKILL.md +286 -0
- package/.agent/skills/nextjs-react-expert/scripts/convert_rules.py +222 -0
- package/.agent/skills/nextjs-react-expert/scripts/react_performance_checker.py +252 -0
- package/.agent/skills/nodejs-best-practices/SKILL.md +333 -0
- package/.agent/skills/parallel-agents/SKILL.md +194 -0
- package/.agent/skills/performance-profiling/SKILL.md +149 -0
- package/.agent/skills/performance-profiling/scripts/lighthouse_audit.py +76 -0
- package/.agent/skills/plan-writing/SKILL.md +152 -0
- package/.agent/skills/powershell-windows/SKILL.md +166 -0
- package/.agent/skills/python-patterns/SKILL.md +441 -0
- package/.agent/skills/red-team-tactics/SKILL.md +203 -0
- package/.agent/skills/rust-pro/SKILL.md +190 -0
- package/.agent/skills/seo-fundamentals/SKILL.md +135 -0
- package/.agent/skills/seo-fundamentals/scripts/seo_checker.py +215 -0
- package/.agent/skills/server-management/SKILL.md +161 -0
- package/.agent/skills/systematic-debugging/SKILL.md +114 -0
- package/.agent/skills/tailwind-patterns/SKILL.md +269 -0
- package/.agent/skills/tdd-workflow/SKILL.md +149 -0
- package/.agent/skills/testing-patterns/SKILL.md +178 -0
- package/.agent/skills/testing-patterns/scripts/test_runner.py +219 -0
- package/.agent/skills/vulnerability-scanner/SKILL.md +276 -0
- package/.agent/skills/vulnerability-scanner/checklists.md +131 -0
- package/.agent/skills/vulnerability-scanner/scripts/security_scan.py +459 -0
- package/.agent/skills/web-design-guidelines/SKILL.md +57 -0
- package/.agent/skills/webapp-testing/SKILL.md +187 -0
- package/.agent/skills/webapp-testing/scripts/playwright_runner.py +173 -0
- package/.agent/workflows/brainstorm.md +113 -0
- package/.agent/workflows/create.md +59 -0
- package/.agent/workflows/debug.md +103 -0
- package/.agent/workflows/deploy.md +176 -0
- package/.agent/workflows/enhance.md +63 -0
- package/.agent/workflows/orchestrate.md +242 -0
- package/.agent/workflows/plan.md +89 -0
- package/.agent/workflows/preview.md +80 -0
- package/.agent/workflows/restore-localize-compat.md +525 -0
- package/.agent/workflows/status.md +86 -0
- package/.agent/workflows/test.md +144 -0
- package/.agent/workflows/ui-ux-pro-max.md +295 -0
- package/AGENT_FLOW.md +609 -0
- package/CHANGELOG.md +68 -0
- package/LICENSE +21 -0
- package/README.md +260 -0
- package/bin/adapters/base.js +63 -0
- package/bin/adapters/codex.js +391 -0
- package/bin/adapters/gemini.js +137 -0
- package/bin/ag-kit.js +1336 -0
- package/bin/core/builder.js +80 -0
- package/bin/core/generator.js +59 -0
- package/bin/core/resource-loader.js +64 -0
- package/bin/core/transformer.js +208 -0
- package/bin/interactive.js +65 -0
- package/bin/utils/atomic-writer.js +97 -0
- package/bin/utils/git-helper.js +68 -0
- package/bin/utils/managed-block.js +65 -0
- package/bin/utils/manifest.js +241 -0
- package/bin/utils.js +82 -0
- package/docs/codex-rules-template.md +36 -0
- package/docs/mapping-spec.md +68 -0
- package/docs/multi-target-adapter.md +80 -0
- package/docs/official/README.md +53 -0
- package/docs/official/antigravity/agent-modes-settings.md +64 -0
- package/docs/official/antigravity/rules-workflows.md +96 -0
- package/docs/official/antigravity/skills.md +147 -0
- package/docs/official/codex/agents-md.md +119 -0
- package/docs/official/codex/config-advanced.md +358 -0
- package/docs/official/codex/config-basic.md +141 -0
- package/docs/official/codex/config-reference.md +223 -0
- package/docs/official/codex/config-sample.md +216 -0
- package/docs/official/codex/mcp.md +107 -0
- package/docs/official/codex/rules.md +79 -0
- package/docs/official/codex/skills.md +114 -0
- package/docs/official/sources-index.md +32 -0
- package/docs/operations.md +145 -0
- package/docs/terminology-style-guide.md +69 -0
- package/package.json +51 -0
- package/scripts/postinstall-check.js +112 -0
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: nextjs-static
|
|
3
|
+
description: Modern template for Next.js 16, React 19 & Tailwind v4(现代模板)。Optimized for Landing pages(落地页) and Portfolios(作品集)。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Next.js Static Site Template(Modern Edition,现代版)
|
|
7
|
+
|
|
8
|
+
## Tech Stack(技术栈)
|
|
9
|
+
|
|
10
|
+
| Component(组件) | Technology(技术) | Notes(说明) |
|
|
11
|
+
| --- | --- | --- |
|
|
12
|
+
| Framework(框架) | Next.js 16+ | App Router(应用路由)、Turbopack、Static Exports(静态导出) |
|
|
13
|
+
| Core(核心) | React 19 | Server Components(服务端组件)、New Hooks(新 Hooks)、Compiler(编译器) |
|
|
14
|
+
| Language(语言) | TypeScript | Strict Mode(严格模式) |
|
|
15
|
+
| Styling(样式) | Tailwind CSS v4 | CSS-first configuration(无 js 配置)、Oxide Engine |
|
|
16
|
+
| Animations(动画) | Framer Motion | 布局动画与手势 |
|
|
17
|
+
| Icons(图标) | Lucide React | 轻量 SVG 图标 |
|
|
18
|
+
| SEO | Metadata API | Native Next.js API(替代 next-seo) |
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## Directory Structure(目录结构)
|
|
23
|
+
|
|
24
|
+
Streamlined structure thanks to Tailwind v4(主题配置位于 CSS 内)。
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
project-name/
|
|
28
|
+
├── src/
|
|
29
|
+
│ ├── app/
|
|
30
|
+
│ │ ├── layout.tsx # Contains root SEO Metadata(根级 SEO 元数据)
|
|
31
|
+
│ │ ├── page.tsx # Landing Page(落地页)
|
|
32
|
+
│ │ ├── globals.css # Import Tailwind v4 & @theme config(导入 Tailwind v4 与 @theme 配置)
|
|
33
|
+
│ │ ├── not-found.tsx # Custom 404 page(自定义 404 页面)
|
|
34
|
+
│ │ └── (routes)/ # Route groups(路由组,about, contact...)
|
|
35
|
+
│ ├── components/
|
|
36
|
+
│ │ ├── layout/ # Header, Footer(页头、页脚)
|
|
37
|
+
│ │ ├── sections/ # Hero, Features, Pricing, CTA(主视觉、功能亮点、价格方案、CTA)
|
|
38
|
+
│ │ └── ui/ # Atomic components(Button, Card)
|
|
39
|
+
│ └── lib/
|
|
40
|
+
│ └── utils.ts # Helper functions(cn, formatters)
|
|
41
|
+
├── content/ # Markdown/MDX content(内容)
|
|
42
|
+
├── public/ # Static assets(images, fonts)
|
|
43
|
+
├── next.config.ts # Next.js Config(TypeScript)
|
|
44
|
+
└── package.json
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## Static Export Config(静态导出配置)
|
|
50
|
+
|
|
51
|
+
Using `next.config.ts` instead of `.js` for better type safety(更好的类型安全)。
|
|
52
|
+
|
|
53
|
+
```typescript
|
|
54
|
+
// next.config.ts
|
|
55
|
+
import type { NextConfig } from "next";
|
|
56
|
+
|
|
57
|
+
const nextConfig: NextConfig = {
|
|
58
|
+
output: 'export', // Required for Static Hosting(S3、GitHub Pages)
|
|
59
|
+
images: {
|
|
60
|
+
unoptimized: true // Required if not using Node.js server image optimization(不使用 Node.js 服务器图像优化时必需)
|
|
61
|
+
},
|
|
62
|
+
trailingSlash: true, // Recommended for SEO and fixing 404s on some hosts(推荐用于 SEO 并修复某些主机 404)
|
|
63
|
+
reactStrictMode: true,
|
|
64
|
+
};
|
|
65
|
+
|
|
66
|
+
export default nextConfig;
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## SEO Implementation(Metadata API)
|
|
72
|
+
|
|
73
|
+
Deprecated next-seo. Configure directly in layout.tsx or page.tsx(直接在 layout.tsx 或 page.tsx 中配置)。
|
|
74
|
+
|
|
75
|
+
```typescript
|
|
76
|
+
// src/app/layout.tsx
|
|
77
|
+
import type { Metadata } from 'next';
|
|
78
|
+
|
|
79
|
+
export const metadata: Metadata = {
|
|
80
|
+
title: {
|
|
81
|
+
template: '%s | Product Name',
|
|
82
|
+
default: 'Home - Product Name',
|
|
83
|
+
},
|
|
84
|
+
description: 'SEO optimized description for the landing page.',
|
|
85
|
+
openGraph: {
|
|
86
|
+
type: 'website',
|
|
87
|
+
locale: 'en_US',
|
|
88
|
+
url: 'https://mysite.com',
|
|
89
|
+
siteName: 'My Brand',
|
|
90
|
+
},
|
|
91
|
+
};
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## Landing Page Sections(落地页模块)
|
|
97
|
+
|
|
98
|
+
| Section(模块) | Purpose(作用) | Suggested Component(建议组件) |
|
|
99
|
+
| --- | --- | --- |
|
|
100
|
+
| Hero(主视觉) | First impression, H1 & Main CTA(第一印象、主 CTA) | `<HeroSection />` |
|
|
101
|
+
| Features(功能亮点) | Product benefits(Grid/Bento 布局) | `<FeaturesGrid />` |
|
|
102
|
+
| Social Proof(社会证明) | Partner logos, User numbers(合作伙伴 Logo、用户数量) | `<LogoCloud />` |
|
|
103
|
+
| Testimonials(客户评价) | Customer reviews(用户评价) | `<TestimonialCarousel />` |
|
|
104
|
+
| Pricing(价格方案) | Service plans(服务计划) | `<PricingCards />` |
|
|
105
|
+
| FAQ(常见问题) | Questions & Answers(利于 SEO) | `<Accordion />` |
|
|
106
|
+
| CTA(转化模块) | Final conversion(最终转化) | `<CallToAction />` |
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## Animation Patterns(Framer Motion)
|
|
111
|
+
|
|
112
|
+
| Pattern(模式) | Usage(用途) | Implementation(实现) |
|
|
113
|
+
| --- | --- | --- |
|
|
114
|
+
| Fade Up(淡入上移) | Headlines, paragraphs(标题、段落) | `initial={{ opacity: 0, y: 20 }} animate={{ opacity: 1, y: 0 }}` |
|
|
115
|
+
| Stagger(交错入场) | Lists of Features/Cards(功能/卡片列表) | Use variants with `staggerChildren`(使用 variants) |
|
|
116
|
+
| Parallax(视差) | Background images or floating elements(背景图像/浮动元素) | `useScroll` & `useTransform` |
|
|
117
|
+
| Micro-interactions(微交互) | Hover buttons, click effects(悬停/点击效果) | `whileHover={{ scale: 1.05 }} whileTap={{ scale: 0.95 }}` |
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## Setup Steps(设置步骤)
|
|
122
|
+
|
|
123
|
+
1. Initialize Project(初始化项目):
|
|
124
|
+
```bash
|
|
125
|
+
npx create-next-app@latest my-site --typescript --tailwind --eslint
|
|
126
|
+
# Select "Yes" for App Router(选择 Yes 以启用 App Router)
|
|
127
|
+
# Select "No" for default import alias(选择 No 以保持默认导入别名)
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
2. Install Auxiliary Libraries(安装辅助库):
|
|
131
|
+
```bash
|
|
132
|
+
npm install framer-motion lucide-react clsx tailwind-merge
|
|
133
|
+
# clsx and tailwind-merge help handle dynamic classes(更好处理动态 class)
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
3. Configure Tailwind v4(位于 `src/app/globals.css`):
|
|
137
|
+
```css
|
|
138
|
+
@import "tailwindcss";
|
|
139
|
+
|
|
140
|
+
@theme {
|
|
141
|
+
--color-primary: #3b82f6;
|
|
142
|
+
--font-sans: 'Inter', sans-serif;
|
|
143
|
+
}
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
4. Development(开发运行):
|
|
147
|
+
```bash
|
|
148
|
+
npm run dev --turbopack
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
## Deployment(部署)
|
|
154
|
+
|
|
155
|
+
| Platform(平台) | Method(方式) | Important Notes(重要说明) |
|
|
156
|
+
| --- | --- | --- |
|
|
157
|
+
| Vercel | Git Push(Git 推送) | Auto-detects Next.js. Best for performance(性能最佳) |
|
|
158
|
+
| GitHub Pages | GitHub Actions(工作流) | If not using a custom domain, set `basePath` in `next.config.ts` |
|
|
159
|
+
| AWS S3 / CloudFront | Upload out folder(上传 out 文件夹) | Ensure Error Document is configured to `404.html` |
|
|
160
|
+
| Netlify | Git Push(Git 推送) | Set build command to `npm run build` |
|
|
161
|
+
|
|
162
|
+
---
|
|
163
|
+
|
|
164
|
+
## Best Practices (Modern)(现代最佳实践)
|
|
165
|
+
|
|
166
|
+
- **React Server Components (RSC)**: Default all components to Server Components(服务端组件). Only add `'use client'` when you need state (`useState`) or event listeners (`onClick`).
|
|
167
|
+
- **Image Optimization(图片优化)**: Use the `<Image />` component but remember `unoptimized: true` for static export or use an external image CDN(Cloudinary/Imgix).
|
|
168
|
+
- **Font Optimization(字体优化)**: Use `next/font`(Google Fonts) to automatically host fonts and prevent layout shift.
|
|
169
|
+
- **Responsive(响应式)**: Mobile-first design using Tailwind prefixes like `sm:`, `md:`, `lg:`.
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: nuxt-app
|
|
3
|
+
description: Nuxt 4 Full-Stack template(全栈模板)。Vue 3(Vapor Mode,蒸汽模式)、Pinia、Tailwind v4、Prisma。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Nuxt 4 Full-Stack Template(全栈模板,2026 版)
|
|
7
|
+
|
|
8
|
+
Nuxt 4 的现代全栈模板,使用 Vapor Mode(蒸汽模式)与 Tailwind v4 优化性能。
|
|
9
|
+
|
|
10
|
+
## Tech Stack(技术栈)
|
|
11
|
+
|
|
12
|
+
| Component(组件) | Technology(技术) | Version / Notes(版本/说明) |
|
|
13
|
+
| --- | --- | --- |
|
|
14
|
+
| Framework(框架) | Nuxt | v4.0+(App Directory(应用目录)结构) |
|
|
15
|
+
| UI Engine(UI 引擎) | Vue | v3.6+(启用 Vapor Mode) |
|
|
16
|
+
| Language(语言) | TypeScript | v5+(Strict Mode,严格模式) |
|
|
17
|
+
| State(状态) | Pinia | v3+(Store syntax(Store 语法)) |
|
|
18
|
+
| Database(数据库) | PostgreSQL | Prisma ORM(对象关系映射) |
|
|
19
|
+
| Styling(样式) | Tailwind CSS | v4.0(Vite 插件,零配置) |
|
|
20
|
+
| UI Lib(组件库) | Nuxt UI | v3(Tailwind v4 原生) |
|
|
21
|
+
| Validation(校验) | Zod | Schema validation(模式校验) |
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## Directory Structure(Nuxt 4 标准)
|
|
26
|
+
|
|
27
|
+
使用 `app/` 结构保持根目录整洁。
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
project-name/
|
|
31
|
+
├── app/ # Application Source(应用源码)
|
|
32
|
+
│ ├── assets/
|
|
33
|
+
│ │ └── css/
|
|
34
|
+
│ │ └── main.css # Tailwind v4 导入
|
|
35
|
+
│ ├── components/ # Auto-imported components(自动导入组件)
|
|
36
|
+
│ ├── composables/ # Auto-imported logic(自动导入逻辑)
|
|
37
|
+
│ ├── layouts/
|
|
38
|
+
│ ├── pages/ # File-based routing(基于文件路由)
|
|
39
|
+
│ ├── app.vue # Root component(根组件)
|
|
40
|
+
│ └── router.options.ts
|
|
41
|
+
├── server/ # Nitro Server Engine(服务端引擎)
|
|
42
|
+
│ ├── api/ # API Routes(接口路由,例如 /api/users)
|
|
43
|
+
│ ├── routes/ # Server Routes(服务端路由)
|
|
44
|
+
│ └── utils/ # Server-only helpers(仅服务端辅助,Prisma)
|
|
45
|
+
├── prisma/
|
|
46
|
+
│ └── schema.prisma
|
|
47
|
+
├── public/
|
|
48
|
+
├── nuxt.config.ts # Main Config(主配置)
|
|
49
|
+
└── package.json
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## Key Concepts(2026)
|
|
55
|
+
|
|
56
|
+
| Concept(概念) | Description(说明) | Future Update(未来更新) |
|
|
57
|
+
| --- | --- | --- |
|
|
58
|
+
| **App Directory(应用目录)** | `app/` | 分离应用源码与根配置文件。 |
|
|
59
|
+
| **Vapor Mode(蒸汽模式)** | 性能优先 | 无需 Virtual DOM(虚拟 DOM,类似 SolidJS)。在 `nuxt.config` 中启用。 |
|
|
60
|
+
| **Server Functions(服务端函数)** | RPC 风格调用 | 从客户端直接调用服务端函数(逐步替代手写 API routes(API 路由))。 |
|
|
61
|
+
| **Tailwind v4** | CSS-first | 主题直接在 CSS 中配置,无需 `tailwind.config.js`。 |
|
|
62
|
+
| **Nuxt Islands(岛屿组件)** | Server Components(服务端组件) | 在服务端隔离渲染组件(`<NuxtIsland name="..." />`)。 |
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## Environment Variables(环境变量)
|
|
67
|
+
|
|
68
|
+
| Variable(变量) | Purpose(用途) |
|
|
69
|
+
| --- | --- |
|
|
70
|
+
| DATABASE_URL | Prisma connection string(PostgreSQL 连接字符串) |
|
|
71
|
+
| NUXT_PUBLIC_APP_URL | Canonical URL(规范 URL) |
|
|
72
|
+
| NUXT_SESSION_PASSWORD | Session encryption key(会话加密密钥) |
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## Setup Steps(设置步骤)
|
|
77
|
+
|
|
78
|
+
1. Initialize Project(初始化项目):
|
|
79
|
+
```bash
|
|
80
|
+
npx nuxi@latest init my-app
|
|
81
|
+
# 如有提示,选择 "Nuxt 4 structure"
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
2. Install Core Deps(安装核心依赖):
|
|
85
|
+
```bash
|
|
86
|
+
npm install @pinia/nuxt @prisma/client zod
|
|
87
|
+
npm install -D prisma
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
3. Setup Tailwind v4(设置 Tailwind v4):
|
|
91
|
+
安装 Vite 插件(新标准):
|
|
92
|
+
```bash
|
|
93
|
+
npm install tailwindcss @tailwindcss/vite
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
添加到 `nuxt.config.ts`:
|
|
97
|
+
```ts
|
|
98
|
+
import tailwindcss from '@tailwindcss/vite'
|
|
99
|
+
export default defineNuxtConfig({
|
|
100
|
+
vite: {
|
|
101
|
+
plugins: [tailwindcss()]
|
|
102
|
+
},
|
|
103
|
+
css: ['~/assets/css/main.css']
|
|
104
|
+
})
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
4. Configure CSS(配置 CSS):
|
|
108
|
+
在 `app/assets/css/main.css` 中:
|
|
109
|
+
```css
|
|
110
|
+
@import "tailwindcss";
|
|
111
|
+
@theme {
|
|
112
|
+
--color-primary: oklch(0.6 0.15 150);
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
5. 开发运行:
|
|
117
|
+
```bash
|
|
118
|
+
npm run dev
|
|
119
|
+
# 使用 Turbo/Vite 运行
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
## 最佳实践
|
|
125
|
+
|
|
126
|
+
- **Vapor Mode(Vapor 模式)**:为渲染密集型组件启用:
|
|
127
|
+
```ts
|
|
128
|
+
<script setup lang="ts" vapor>
|
|
129
|
+
// 此组件会编译为 Vapor 模式(无 VDOM)
|
|
130
|
+
</script>
|
|
131
|
+
```
|
|
132
|
+
- **Data Fetching(数据获取)**:对仅客户端任务使用 `useFetch` + `server: false`,或使用 Server Functions 获得更好的类型安全。
|
|
133
|
+
- **State(状态)**:使用 `defineStore`(Pinia)管理全局状态,Nuxt 的 `useState` 用于服务端/客户端共享的简单状态。
|
|
134
|
+
- **Type Safety(类型安全)**:为 API routes(API 路由)自动生成类型(`$fetch` 自动类型化)。
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: python-fastapi
|
|
3
|
+
description: FastAPI REST API template principles(API 模板原则)。SQLAlchemy、Pydantic、Alembic。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# FastAPI API Template(API 模板)
|
|
7
|
+
|
|
8
|
+
## Tech Stack(技术栈)
|
|
9
|
+
|
|
10
|
+
| Component(组件) | Technology(技术) |
|
|
11
|
+
| --- | --- |
|
|
12
|
+
| Framework(框架) | FastAPI |
|
|
13
|
+
| Language(语言) | Python 3.11+ |
|
|
14
|
+
| ORM | SQLAlchemy 2.0 |
|
|
15
|
+
| Validation(校验) | Pydantic v2 |
|
|
16
|
+
| Migrations(迁移) | Alembic |
|
|
17
|
+
| Auth(认证) | JWT + passlib(密码哈希) |
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Directory Structure(目录结构)
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
project-name/
|
|
25
|
+
├── alembic/ # Migrations(迁移)
|
|
26
|
+
├── app/
|
|
27
|
+
│ ├── main.py # FastAPI app(应用)
|
|
28
|
+
│ ├── config.py # Settings(配置)
|
|
29
|
+
│ ├── database.py # DB connection(数据库连接)
|
|
30
|
+
│ ├── models/ # SQLAlchemy models(模型)
|
|
31
|
+
│ ├── schemas/ # Pydantic schemas(模式)
|
|
32
|
+
│ ├── routers/ # API routes(路由)
|
|
33
|
+
│ ├── services/ # Business logic(业务逻辑)
|
|
34
|
+
│ ├── dependencies/ # Dependency Injection(依赖注入)
|
|
35
|
+
│ └── utils/
|
|
36
|
+
├── tests/
|
|
37
|
+
├── .env.example
|
|
38
|
+
└── requirements.txt
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## Key Concepts(关键概念)
|
|
44
|
+
|
|
45
|
+
| Concept(概念) | Description(说明) |
|
|
46
|
+
| --- | --- |
|
|
47
|
+
| Async(异步) | async/await throughout(全程 async/await) |
|
|
48
|
+
| Dependency Injection(依赖注入) | FastAPI Depends |
|
|
49
|
+
| Pydantic v2 | Validation + serialization(验证 + 序列化) |
|
|
50
|
+
| SQLAlchemy 2.0 | Async sessions(异步会话) |
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## API Structure(API 结构)
|
|
55
|
+
|
|
56
|
+
| Layer(层) | Responsibility(职责) |
|
|
57
|
+
| --- | --- |
|
|
58
|
+
| Routers(路由层) | HTTP handling(HTTP 处理) |
|
|
59
|
+
| Dependencies(依赖层) | Auth, validation(认证、校验) |
|
|
60
|
+
| Services(服务层) | Business logic(业务逻辑) |
|
|
61
|
+
| Models(模型层) | Database entities(数据库实体) |
|
|
62
|
+
| Schemas(模式层) | Request/response(请求/响应) |
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## Setup Steps(设置步骤)
|
|
67
|
+
|
|
68
|
+
1. `python -m venv venv`
|
|
69
|
+
2. `source venv/bin/activate`
|
|
70
|
+
3. `pip install fastapi uvicorn sqlalchemy alembic pydantic`
|
|
71
|
+
4. Create `.env`(创建)
|
|
72
|
+
5. `alembic upgrade head`
|
|
73
|
+
6. `uvicorn app.main:app --reload`
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## Best Practices(最佳实践)
|
|
78
|
+
|
|
79
|
+
- Use async everywhere(全程使用 async)
|
|
80
|
+
- Pydantic v2 for validation(用于验证)
|
|
81
|
+
- SQLAlchemy 2.0 async sessions(异步会话)
|
|
82
|
+
- Alembic for migrations(迁移)
|
|
83
|
+
- pytest-asyncio for tests(测试)
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: react-native-app
|
|
3
|
+
description: React Native mobile app template(移动应用模板)原则。Expo、TypeScript、导航。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# React Native App Template(应用模板,2026 版)
|
|
7
|
+
|
|
8
|
+
现代移动应用模板,针对 New Architecture(新架构)与 React 19 优化。
|
|
9
|
+
|
|
10
|
+
## Tech Stack(技术栈)
|
|
11
|
+
|
|
12
|
+
| Component(组件) | Technology(技术) | Version / Notes(版本/说明) |
|
|
13
|
+
| --- | --- | --- |
|
|
14
|
+
| Core(核心) | React Native + Expo | SDK 52+(启用新架构) |
|
|
15
|
+
| Language(语言) | TypeScript | v5+(Strict Mode,严格模式) |
|
|
16
|
+
| UI Logic(UI 逻辑) | React | v19(React Compiler(编译器),自动记忆化) |
|
|
17
|
+
| Navigation(导航) | Expo Router | v4+(File-based(基于文件)、Universal Links(通用链接)) |
|
|
18
|
+
| Styling(样式) | NativeWind | v4.0(Tailwind v4,CSS-first 配置) |
|
|
19
|
+
| State(状态) | Zustand + React Query | v5+(异步状态管理) |
|
|
20
|
+
| Storage(存储) | Expo SecureStore | 加密本地存储 |
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Directory Structure(目录结构)
|
|
25
|
+
|
|
26
|
+
Expo Router 与 NativeWind v4 的标准化结构。
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
project-name/
|
|
30
|
+
├── app/ # Expo Router(基于文件的路由)
|
|
31
|
+
│ ├── _layout.tsx # Root Layout(Stack/Tabs 配置)
|
|
32
|
+
│ ├── index.tsx # Main Screen(主屏幕)
|
|
33
|
+
│ ├── (tabs)/ # Tab Bar Route Group(标签栏路由组)
|
|
34
|
+
│ │ ├── _layout.tsx
|
|
35
|
+
│ │ ├── home.tsx
|
|
36
|
+
│ │ └── profile.tsx
|
|
37
|
+
│ ├── +not-found.tsx # 404 Page(404 页面)
|
|
38
|
+
│ └── [id].tsx # Dynamic Route(类型化)
|
|
39
|
+
├── components/
|
|
40
|
+
│ ├── ui/ # Primitive Components(Button, Text)
|
|
41
|
+
│ └── features/ # Complex Components(复杂组件)
|
|
42
|
+
├── hooks/ # Custom Hooks(自定义 hooks)
|
|
43
|
+
├── lib/
|
|
44
|
+
│ ├── api.ts # Axios/Fetch 客户端
|
|
45
|
+
│ └── storage.ts # SecureStore wrapper(封装)
|
|
46
|
+
├── store/ # Zustand store(状态仓库)
|
|
47
|
+
├── constants/ # 颜色、主题配置
|
|
48
|
+
├── assets/ # 字体、图片
|
|
49
|
+
├── global.css # NativeWind v4 entry(入口点)
|
|
50
|
+
├── tailwind.config.ts # Tailwind 配置(如需自定义主题)
|
|
51
|
+
├── babel.config.js # NativeWind Babel 插件
|
|
52
|
+
└── app.json # Expo 配置
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## Navigation Patterns(Expo Router)
|
|
58
|
+
|
|
59
|
+
| Pattern(模式) | Description(描述) | Implement(实现) |
|
|
60
|
+
| --- | --- | --- |
|
|
61
|
+
| Stack(堆栈) | 层级导航(Push/Pop) | `<Stack />` 在 `_layout.tsx` |
|
|
62
|
+
| Tabs(标签) | 底部导航栏 | `<Tabs />` 在 `(tabs)/_layout.tsx` |
|
|
63
|
+
| Drawer(抽屉) | 侧滑菜单 | `expo-router/drawer` |
|
|
64
|
+
| Modals(模态) | 覆盖屏幕 | Stack 页面中的 `presentation: 'modal'` |
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## Key Packages & Purpose(关键依赖与用途)
|
|
69
|
+
|
|
70
|
+
| Package(依赖) | Purpose(用途) |
|
|
71
|
+
| --- | --- |
|
|
72
|
+
| expo-router | 基于文件的路由(类似 Next.js) |
|
|
73
|
+
| nativewind | 在 React Native 中使用 Tailwind CSS 类 |
|
|
74
|
+
| react-native-reanimated | 平滑动画(在 UI(用户界面)线程上运行) |
|
|
75
|
+
| @tanstack/react-query | 服务端状态管理、缓存、预取 |
|
|
76
|
+
| zustand | 全局状态管理(比 Redux 更轻) |
|
|
77
|
+
| expo-image | 优化图像渲染以提升性能 |
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## Setup Steps(2026 标准)
|
|
82
|
+
|
|
83
|
+
1. Initialize Project(初始化项目):
|
|
84
|
+
```bash
|
|
85
|
+
npx create-expo-app@latest my-app --template default
|
|
86
|
+
cd my-app
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
2. Install Core Dependencies(安装核心依赖):
|
|
90
|
+
```bash
|
|
91
|
+
npx expo install expo-router react-native-safe-area-context react-native-screens expo-link expo-constants expo-status-bar
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
3. Install NativeWind v4(安装 NativeWind v4):
|
|
95
|
+
```bash
|
|
96
|
+
npm install nativewind tailwindcss react-native-reanimated
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
4. Configure NativeWind(Babel 与 CSS):
|
|
100
|
+
- 在 `babel.config.js` 添加插件:`plugins: ["nativewind/babel"]`。
|
|
101
|
+
- 创建 `global.css` 并包含:`@import "tailwindcss";`。
|
|
102
|
+
- 在 `app/_layout.tsx` 中导入 `global.css`。
|
|
103
|
+
|
|
104
|
+
5. Run Project(运行项目):
|
|
105
|
+
```bash
|
|
106
|
+
npx expo start -c
|
|
107
|
+
# 按 'i' 启动 iOS 模拟器或按 'a' 启动 Android 模拟器
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## Best Practices(更新)
|
|
113
|
+
|
|
114
|
+
- **New Architecture(新架构)**:确保 `app.json` 中 `newArchEnabled: true`,以利用 TurboModules 与 Fabric Renderer。
|
|
115
|
+
- **Typed Routes(类型化路由)**:使用 Expo Router 的 “Typed Routes” 特性实现类型安全路由(例如 `router.push('/path')`)。
|
|
116
|
+
- **React 19**:借助 React Compiler(编译器,如已启用)减少 `useMemo` 或 `useCallback` 的使用。
|
|
117
|
+
- **组件**:使用 NativeWind `className` 构建 UI(用户界面)原语(Box, Text),提高可复用性。
|
|
118
|
+
- **资产**:使用 `expo-image` 代替默认 `<Image />`,提升缓存与性能。
|
|
119
|
+
- **API(接口)**:使用 TanStack Query 包装 API 调用,避免在 `useEffect` 中直接调用。
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: architecture
|
|
3
|
+
description: Architectural decision-making framework(架构决策框架)。Requirements analysis(需求分析)、trade-off evaluation(权衡评估)、ADR documentation(架构决策记录)。Use when making architecture decisions or analyzing system design(用于架构决策与系统设计分析)。
|
|
4
|
+
allowed-tools: Read, Glob, Grep
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Architecture Decision Framework(架构决策框架)
|
|
8
|
+
|
|
9
|
+
> "Requirements drive architecture. Trade-offs inform decisions. ADRs capture rationale."(需求驱动架构,权衡决定结论,ADR 记录依据。)
|
|
10
|
+
|
|
11
|
+
## 🎯 Selective Reading Rule(选择性阅读规则)
|
|
12
|
+
|
|
13
|
+
**Read ONLY files relevant to the request(仅阅读与请求相关的文档)!** Check the content map, find what you need(查阅内容地图,找到所需信息)。
|
|
14
|
+
|
|
15
|
+
| File(文件) | Description(描述) | When to Read(阅读时机) |
|
|
16
|
+
| ---- | ---- | -------- |
|
|
17
|
+
| `context-discovery.md` | Questions to ask, project classification(提问列表、项目分类) | Starting architecture design(开始架构设计) |
|
|
18
|
+
| `trade-off-analysis.md` | ADR templates, trade-off framework(ADR 模板、权衡分析框架) | Documenting decisions(记录决策) |
|
|
19
|
+
| `pattern-selection.md` | Decision trees, anti-patterns(决策树、反模式) | Choosing patterns(选择模式) |
|
|
20
|
+
| `examples.md` | MVP, SaaS, Enterprise examples(示例) | Reference implementations(参考实现) |
|
|
21
|
+
| `patterns-reference.md` | Quick lookup for patterns(模式速查) | Pattern comparison(模式对比) |
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## 🔗 Related Skills(相关技能)
|
|
26
|
+
|
|
27
|
+
| Skill(技能) | Use For(用途) |
|
|
28
|
+
| ------------ | ---- |
|
|
29
|
+
| `@[skills/database-design]` | Database schema design(数据库模式设计) |
|
|
30
|
+
| `@[skills/api-patterns]` | API design patterns(API 设计模式) |
|
|
31
|
+
| `@[skills/deployment-procedures]` | Deployment architecture(部署架构) |
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Core Principle(核心原则)
|
|
36
|
+
|
|
37
|
+
**"Simplicity is the ultimate sophistication."(至简即至繁)**
|
|
38
|
+
|
|
39
|
+
- Start simple(从简单开始)。
|
|
40
|
+
- Add complexity ONLY when proven necessary(仅在必要时增加复杂性)。
|
|
41
|
+
- You can always add patterns later(随时可补充模式)。
|
|
42
|
+
- Removing complexity is MUCH harder than adding it(移除复杂性远比增加难)。
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## Validation Checklist(验证检查清单)
|
|
47
|
+
|
|
48
|
+
Before finalizing architecture(最终确定架构之前):
|
|
49
|
+
|
|
50
|
+
- [ ] **Requirements clearly understood(需求已清晰理解)。**
|
|
51
|
+
- [ ] **Constraints identified(约束条件已明确)。**
|
|
52
|
+
- [ ] **Each decision has trade-off analysis(每项决策有权衡分析)。**
|
|
53
|
+
- [ ] **Simpler alternatives considered(已考虑更简单替代方案)。**
|
|
54
|
+
- [ ] **ADRs written for significant decisions(重大决策已编写 ADR)。**
|
|
55
|
+
- [ ] **Team expertise matches chosen patterns(团队能力与模式匹配)。**
|
|
56
|
+
|
|
57
|
+
---
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# 上下文发现
|
|
2
|
+
|
|
3
|
+
> 在提出任何架构方案前,先收集上下文信息。
|
|
4
|
+
|
|
5
|
+
## 问题层级(先问用户)
|
|
6
|
+
|
|
7
|
+
1. **规模(Scale)**
|
|
8
|
+
- 用户量级是多少?(10、1K、100K、1M+)
|
|
9
|
+
- 数据规模是多少?(MB、GB、TB)
|
|
10
|
+
- 事务速率是多少?(每秒/每分钟)
|
|
11
|
+
|
|
12
|
+
2. **团队(Team)**
|
|
13
|
+
- 个人开发还是团队协作?
|
|
14
|
+
- 团队规模与能力结构?
|
|
15
|
+
- 是分布式团队还是同地办公?
|
|
16
|
+
|
|
17
|
+
3. **时间线(Timeline)**
|
|
18
|
+
- 是 MVP(最小可行产品)/原型,还是长期产品?
|
|
19
|
+
- 上线时效压力有多大?
|
|
20
|
+
|
|
21
|
+
4. **业务域(Domain)**
|
|
22
|
+
- 以 CRUD(增删改查)为主,还是业务逻辑复杂?
|
|
23
|
+
- 是否有实时性要求?
|
|
24
|
+
- 是否有合规/监管要求?
|
|
25
|
+
|
|
26
|
+
5. **约束条件(Constraints)**
|
|
27
|
+
- 是否有预算限制?
|
|
28
|
+
- 是否要集成遗留系统?
|
|
29
|
+
- 是否有技术栈偏好?
|
|
30
|
+
|
|
31
|
+
## 项目分类矩阵
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
MVP(最小可行产品) SaaS(软件即服务) Enterprise(企业级)
|
|
35
|
+
┌────────────────────────────────────────────────────────────────────────────┐
|
|
36
|
+
│ 规模 │ <1K │ 1K-100K │ 100K+ │
|
|
37
|
+
│ 团队 │ 单人 │ 2-10 │ 10+ │
|
|
38
|
+
│ 时间线 │ 快(周级) │ 中(月级) │ 长(年级) │
|
|
39
|
+
│ 架构 │ 简单架构 │ 模块化架构 │ 分布式架构 │
|
|
40
|
+
│ 模式 │ 最小模式集 │ 选择性模式 │ 全面模式体系 │
|
|
41
|
+
│ 示例 │ Next.js API(接口) │ NestJS │ Microservices(微服务)│
|
|
42
|
+
└────────────────────────────────────────────────────────────────────────────┘
|
|
43
|
+
```
|