agent-park/AGENTS.md

# PROJECT KNOWLEDGE BASE

**Generated:** 2026-02-01 | **Updated:** 2026-02-20
**Commit:** N/A (new generation)
**Branch:** main

## OVERVIEW

Next.js 15 multilingual AI project navigation website with App Router, TypeScript, Prisma ORM, and Tailwind CSS neo-brutalism design. Features automated project discovery, quarterly AI keyword cloud system, and AI Timeline historical events.

## STRUCTURE

```
agent_park/
├── src/
│   ├── app/                    # Next.js App Router (locale-prefixed routes)
│   │   ├── [locale]/         # Internationalized routes (zh/en)
│   │   │   ├── projects/     # Project listing and details
│   │   │   ├── keyword-cloud/ # Quarterly AI trends
│   │   │   └── layout.tsx   # Header/footer/Announcement
│   │   ├── api/               # API routes (no locale prefix)
│   │   │   ├── webhook/      # Project ingestion
│   │   │   ├── discovery/     # Automated exploration tasks
│   │   │   ├── search/       # AI-powered search
│   │   │   └── keyword-cloud/ # Keywords API
│   │   ├── components/         # React components (organized by domain)
│   │   ├── lib/              # Validation, utilities, Prisma client
│   │   ├── hooks/            # Server-side data fetching
│   │   └── i18n/             # next-intl configuration
│   └── layout.tsx            # Root layout (locale default: zh)
├── prisma/
│   └── schema.prisma          # Database models (multilingual support)
├── .claude/
│   ├── agents/                # Custom Claude agents
│   └── commands/              # Claude commands
├── scripts/                   # Seed/test scripts
├── public/                    # Static assets
└── CLAUDE.md                 # This file (existing)
```

## WHERE TO LOOK

| Task                | Location                 | Notes                                       |
| ------------------- | ------------------------ | ------------------------------------------- |
| Add new page        | `src/app/[locale]/`      | Follow locale routing pattern               |
| Create API endpoint | `src/app/api/`           | Use `crypto.timingSafeEqual()` for auth     |
| Add component       | `src/components/`        | Neo-brutalism: 0px radius, bold borders     |
| Database migration  | `prisma/schema.prisma`   | Run `pnpm prisma migrate dev` after changes |
| Add validation      | `src/lib/validations.ts` | Follow existing Zod schema patterns         |
| Fetch data          | `src/hooks/`             | Server functions, NOT React hooks           |
| Webhook             | `src/app/api/webhook/`   | Multi-level deduplication strategy          |
| Discovery task      | `src/app/api/discovery/` | Task management API                         |
| i18n messages       | `src/messages/`          | Update BOTH `zh.json` AND `en.json`         |

## CODE MAP

```
Main Entry Points:
├── src/app/[locale]/layout.tsx    → Root layout (header/footer)
├── src/app/[locale]/page.tsx       → Home page (ISR 5min)
├── src/app/layout.tsx              → Root layout (fonts, locale)
└── src/middleware.ts                → Locale detection (next-intl)

Data Layer:
├── src/hooks/useProjects.ts           → Projects/tags/search
├── src/hooks/useKeywordCloud.ts      → Keywords/quarters/rules
└── src/lib/prisma.ts                → Prisma client singleton

API Routes:
├── src/app/api/webhook/projects/route.ts      → Project ingestion
├── src/app/api/discovery/tasks/route.ts       → Task CRUD
├── src/app/api/search/ai/route.ts            → AI search
└── src/app/api/keyword-cloud/[...]/route.ts  → Keywords API

Complex Components:
├── src/components/project/MarkdownContent.tsx (269 lines) → Markdown renderer
├── src/app/api/discovery/lib/discovery-service.ts      → Deduplication logic
└── src/app/api/webhook/projects/route.ts      → Webhook handler
```

## CONVENTIONS

### Multilingual Architecture

- **Default locale**: Chinese (`zh`), not English
- **Route pattern**: `/{locale}/path` (locale prefix ALWAYS required)
- **Field naming**: Dual-language pairs (`name`/`nameEn`, `description`/`descriptionEn`)
- **Content selection**: `locale === 'en' && fieldEn ? fieldEn : field`
- **Translation files**: Update BOTH `src/messages/zh.json` AND `src/messages/en.json`

### Type Safety

- **Strict mode**: Enabled with `noUncheckedIndexedAccess`, `noImplicitReturns`, `noFallthroughCasesInSwitch`
- **Path aliases**: `@/*` maps to `./src/*`
- **Validation**: All API inputs via Zod schemas in `src/lib/validations.ts`

### Database Patterns

- **Multi-level deduplication**: GitHub URL → Website URL → slug match (highest → lowest priority)
- **Cascade deletion**: `ExternalLink` and `ProjectTag` auto-delete on project delete
- **Composite indexes**: Optimized for frequent queries (`status+createdAt`, `type+url`)
- **Constraints**: `Project.slug` unique, `Tag.name` unique, `ExternalLink(projectId, url)` unique

### API Authentication

- **Method**: `crypto.timingSafeEqual()` for timing-safe comparison (prevents timing attacks)
- **Key location**: Request body (NOT headers)
- **Validation**: WEBHOOK_API_KEY (32+ chars)

### Design System (Neo-Brutalism)

- **Corners**: 0px radius (sharp)
- **Shadows**: 4px solid borders (`shadow-neo` class)
- **Colors**: Primary gold (#FFD700), secondary orange (#ff6f00)
- **Typography**: Space Mono (headings), Inter (body)
- **Dark mode**: Class-based with `dark:` prefix

### Git Commits

- **Format**: `<type>: <description>` (Chinese lowercase types)
- **Types**: `feat` (新功能), `fix` (修复), `refactor` (重构), `chore` (杂项)
- **Examples**:
  - `feat: 新增项目发现任务系统`
  - `fix: 修复 ESLint 错误`

## ANTI-PATTERNS (THIS PROJECT)

### Environment Variables

- **NEVER** use `vercel.json` for env vars (use Vercel Dashboard)
- **NEVER** commit `.env.local` files or environment variables
- **ALWAYS** verify API responses with `WEBHOOK_API_KEY` when testing endpoints

### Database Operations

- **NEVER** modify schema without running migrations
- **ALWAYS** run `pnpm prisma migrate dev --name <migration_name>` after schema changes
- **ALWAYS** run `pnpm prisma generate` after migrations

### Development Workflow

- **NEVER** skip pre-commit hooks (no `--no-verify`, `--no-gpg-sign` flags)
- **NEVER** commit unless explicitly requested by orchestrator
- **ALWAYS** run `pnpm build` before committing
- **MUST** use chrome-devtools-mcp to verify frontend changes

### Content Standards

- **NEVER** include dynamic data (star/fork counts) in project content
- **ALWAYS** use GitHub Badge for dynamic stats
- **NEVER** use mechanical translation - write naturally for each locale
- **ALWAYS** avoid marketing terminology in descriptions

### Security

- **NEVER** use string comparison for API keys (timing attacks)
- **ALWAYS** use `crypto.timingSafeEqual()` for authentication
- **ALWAYS** validate inputs with Zod schemas
- **NEVER** log raw API keys or sensitive data

## UNIQUE STYLES

### Project Discovery System

- **Architecture**: Dual-agent system (`content-explorer-agent` + `api-submitter-agent`)
- **Workflow**: URL input → PENDING tasks → batch processing → COMPLETED/FAILED
- **Deduplication**: Multi-level strategy (GitHub → Website → slug)
- **Retry logic**: Exponential backoff, max 3 attempts
- **Environment**: `WEBHOOK_API_KEY` required for submitter agent
- See: `src/app/AGENTS.md` for app-specific patterns

### Keyword Cloud System

- **Workflow**: n8n automation → API → PostgreSQL → Next.js
- **Data**: Quarterly snapshots with visual style rules
- **API**: Rate-limited, requires API key
- **Error logging**: `KeywordCloudErrorLog` table
- See: `src/app/AGENTS.md` for app-specific patterns

### Component System

- **Design**: Neo-brutalism with 0px corners, 4px solid borders, gold/orange theme
- **Organization**: layout/locale/project/search/ui (4 domains), project/ (11 files, highest)
- **Largest component**: `MarkdownContent.tsx` (269 lines) with complex react-markdown overrides
- **See**: `src/components/AGENTS.md` for component-specific patterns

### Data Access Layer

- **Validation**: Centralized Zod schemas in `src/lib/validations.ts`
- **Utilities**: Class merging (`cn()`), slug generation, Prisma client singleton
- **GitHub integration**: Badge-based approach, cached API stats (5min)
- **See**: `src/lib/AGENTS.md` for library patterns

### Server-Side Hooks

- **Purpose**: Server functions for data fetching, NOT React hooks
- **Query optimization**: N+1 prevention, selective loading, index utilization
- **ISR strategy**: 5-minute revalidation on project details
- **See**: `src/hooks/AGENTS.md` for data fetching patterns

## COMMANDS

```bash
pnpm dev          # Start dev server (Next.js 15)
pnpm build        # Production build
pnpm start        # Start production server
pnpm lint         # ESLint check
pnpm test         # Vitest unit tests
pnpm test:e2e     # Playwright E2E tests
pnpm prisma migrate dev   # Run migrations
pnpm prisma db seed       # Seed database
pnpm prisma studio        # Database inspector
```

## NOTES

### Project Discovery Gotchas

- Tag upsert follows: 1) Find by name, 2) Try upsert by slug, 3) Use existing if slug conflicts
- Webhook updates ALL project fields, replaces ALL tags/links (no partial updates)
- Deduplication logic in `src/app/api/discovery/lib/discovery-service.ts:16-80`

### i18n Gotchas

- Missing translation keys display as `missing_key_name` in UI
- All new UI text requires BOTH `zh.json` AND `en.json` updates
- Test both locales: `/{zh}/path` and `/{en}/path`

### Database Gotchas

- `Project.slug` globally unique - use existing project if slug conflicts
- `Tag.name` globally unique - upsert handles conflicts via slug fallback
- Run `pnpm prisma studio` to inspect state during development

### Performance Considerations

- **ISR**: Project detail pages revalidate every 5 minutes (`revalidate = 300`)
- **Indexes**: Composite on `(status, createdAt)`, `(type, url)` for optimized queries
- **N+1 prevention**: Batch tag queries in webhook (`useProjects.ts`)

### Missing CI/CD

- No GitHub Actions workflows (rely on Vercel deployment)
- No automated testing in CI pipeline
- Test frameworks configured (Vitest, Playwright) but not extensively used

### LSP Errors

- Missing Prisma models in `src/hooks/useKeywordCloud.ts` and `scripts/seed-keyword-cloud.ts`:
  - Run `pnpm prisma migrate dev` to generate keyword cloud tables
  - Models: `Quarter`, `Keyword`, `VisualStyleRule`, `keywordCloudErrorLog`

### Subdirectories

- **src/app/**: App Router architecture, locale routing, API structure (see `src/app/AGENTS.md`)
- **src/components/**: Neo-brutalism design system, component organization (see `src/components/AGENTS.md`)
- **src/lib/**: Validation layer, utilities, GitHub integration (see `src/lib/AGENTS.md`)
- **src/hooks/**: Server-side data fetching, query optimization (see `src/hooks/AGENTS.md`)

## N8N PRODUCTION WORKFLOWS

Production workflows tagged with "生产" in n8n instance:

| Workflow | Status | Nodes | Purpose |
|----------|--------|-------|---------|
| 项目描述向量化 | ✅ Active | 11 | Generate embeddings for project descriptions (RAG) |
| Github项目分析入库 | ⏸️ Inactive | 16 | Analyze GitHub repos and ingest into database |
| RAG项目搜索 | ✅ Active | 6 | AI-powered project search using vector similarity |
| 每日Github Trending项目计划新增 | ✅ Active | 17 | Daily trending repos → discovery tasks |
| Topic项目计划新增 | ⏸️ Inactive | 16 | Topic-based project discovery tasks |

### Workflow Data Flow

```
GitHub Trending/Topic → Discovery Tasks (PENDING)
                              ↓
                    Content Explorer Agent
                              ↓
                    Project Ingestion API
                              ↓
                    向量化 Workflow → Embeddings
                              ↓
                    RAG项目搜索 ← User Query
```

## AI TIMELINE SYSTEM

Historical AI events tracking system:

- **Model**: `AIEvent` in `prisma/schema.prisma`
- **Fields**: title/titleEn, eventDate, description/descriptionEn, imageUrl, sourceUrl
- **API**: `src/app/api/events/route.ts`
- **Frontend**: `src/app/[locale]/timeline/`
- **Index**: `eventDate` (descending) for chronological queries

<!-- MANUAL: Additional notes can be added below -->