ai-smart-customer-service-app
Template for creating AI smart customer service applications. ONLY trigger when user explicitly requests to CREATE/BUILD an AI customer service app (e.g., "创建智能客服应用", "做一个AI客服", "build an AI chatbot",
SKILL.md.codebuddy/skills/ai-smart-customer-service-app/SKILL.md
GitHubPrerequisites
- Initialize Project (if needed):
REPO_ROOT/.genie/scripts/bash/setup-project.sh web --sub-type ai-smart-customer-service
- Generate
docs/product/features.mdbefore writing any code — product overview, core features, user stories, page structure, data models, API endpoints.
Validation: If docs/product/features.md does not exist, STOP and create it first.
- Make a best design by SKILL:
ui-ux-pro-maxfor first time - Use SKILL
text-to-imagefor generating images, icons, or illustrations when needed. - Use the SKILL
*-integratorto fully realize the user's needs. - CRITICAL: Set up database tables using TCB
bash /workspace/.codebuddy/skills/genie-tcb-db-integrator/scripts/tcb-pg-migrate.sh --project-dir /workspace --sql "CREATE TABLE ..."
CRITICAL: On the first conversation, after initializing the project (REPO_ROOT/.genie/scripts/bash/setup-project.sh web --sub-type ai-smart-customer-service), end the current conversation turn immediately and inform the user that the project has been generated.
Best Practices
General Principles
- Perfect Architecture: Refactor when needed, eliminate duplication, maintain clean separation
- Parallel Tool Calls: Execute independent operations simultaneously
- Less is More: Quality over quantity unless enterprise landing page requested
- Leverage Existing Dependencies: Prefer existing libraries over new ones
- Animations: Use the ui-animation skill for all animation needs (MotionPrimitives for page transitions, ReactBits for creative effects)
SEO (Automatic for All Pages)
- Title tags under 60 chars with keyword
- Meta description max 160 chars
- Single H1 matching page intent
- Semantic HTML (
<header>,<nav>,<main>,<footer>,<article>,<section>) - Image alt attributes with keywords
- JSON-LD for products/articles/FAQs
- Lazy loading for images
- Canonical tags
Web Template Architecture
/
├── backend/ # Express.js + TypeScript
│ ├── package.json
│ ├── tsconfig.json
│ ├── jest.config.mjs
│ ├── eslint.config.js
│ ├── .env / .env.example
│ └── src/
│ ├── index.ts # Server entry point
│ ├── app.ts # Express configuration
│ ├── config/
│ │ ├── env.ts # Environment validation (Zod)
│ │ └── logger.ts # Pino logger factory
│ ├── lib/
│ │ └── hunyuan-chat.ts # Hunyuan AI chat integration
│ ├── modules/
│ │ ├── chat.ts # Chat API endpoints
│ │ └── system.ts # Health check endpoints
│ ├── types/
│ │ └── chat.types.ts # Chat type definitions
│ ├── middleware/
│ │ ├── errorHandler.ts
│ │ ├── logger.ts
│ │ └── validation.ts
│ └── __tests__/
│ ├── setup.ts
│ └── system.test.ts
│
├── frontend/ # React 19 + Vite
│ ├── package.json
│ ├── vite.config.ts
│ ├── tailwind.config.ts
│ ├── components.json # shadcn/ui config
│ ├── index.html
│ └── src/
│ ├── main.tsx # Entry point
│ ├── App.tsx # Root component with providers
│ ├── index.css # Global styles + Tailwind theme
│ ├── components/
│ │ ├── chat/ # Chat components
│ │ │ ├── ChatInput.tsx
│ │ │ ├── ChatMessage.tsx
│ │ │ ├── ChatWindow.tsx
│ │ │ └── ConversationList.tsx
│ │ └── ui/ # shadcn/ui components
│ ├── hooks/
│ │ ├── use-chat.ts
│ │ └── use-mobile.ts
│ ├── lib/
│ │ ├── api-client.ts # Axios with interceptors
│ │ └── utils.ts # cn utility
│ ├── pages/
│ │ ├── Index.tsx
│ │ └── NotFound.tsx
│ └── types/
│ └── chat.ts
│
└── docs/
├── project.json
├── pages.json
├── design/
│ └── default.style-guide.html
├── posters/
│ └── app/
│ └── app-poster.png
└── product/
└── features.md
Technical References
Detailed implementation patterns in references/:
- api-protocol.md: JSON-based API standard (CRITICAL - no URL parameters for data operations)
- frontend-patterns.md: Import management, React Router compatibility, WebSocket
- architecture.md: Complete monorepo structure, key files, commands
Quick Reference
Adding New Resources
Frontend:
- Define types in
src/types/[resource].ts - Create hooks in
src/hooks/use-[resources].ts - Build components using JSON-based API calls
Backend:
- Create types in
src/types/[resource].types.ts - Create module in
src/modules/[resource].ts - Register router in
src/app.ts
Key Commands
# Debugging
python3 "$PROJECT_ROOT/.genie/scripts/python/fetch_monitor_errors.py"
Critical Rules
- JSON Protocol: All data operations use POST with JSON body, not URL parameters
- BrowserRouter Only: No Data Router features (ScrollRestoration, useMatches, etc.)
- Import Everything: Every component/function used must be imported
- 53 shadcn/ui Components: Use existing, DO NOT create custom versions
- WebSocket: Must use
/apiprefix and dynamic protocol/host - oklch Color Format: ALL color CSS variables in
index.cssMUST useoklch()format. NEVER use bare HSL (220 14% 96%), hex, hsl(), or rgb().
Launch Configuration
.cloudstudio file defines startup - DO NOT modify. Always use unified process script.