chore: 移除 SpecKit 相关文件和配置
- 删除所有 SpecKit 命令文件(.claude/commands/speckit.*) - 删除 .specify 配置目录(templates, scripts, memory) - 删除 specs 文档目录 - 更新 CLAUDE.md:移除 SpecKit Skills 说明
This commit is contained in:
@@ -130,11 +130,86 @@ When updating an existing project, the webhook:
|
||||
### Next.js Configuration
|
||||
- **next.config.js**:
|
||||
- `next-intl` plugin wrapper for i18n
|
||||
- Image domains: localhost, *.anthropic.com
|
||||
- Image domains: localhost, *.anthropic.com, img.shields.io
|
||||
- Lucide-react package import optimization
|
||||
- **tsconfig.json**: ES2022 target, strict mode enabled
|
||||
- **tsconfig.json**: ES2017 target, strict mode enabled, noUncheckedIndexedAccess enabled
|
||||
- **Testing**: Vitest for unit tests, Playwright for E2E tests (configured but not extensively used yet)
|
||||
|
||||
### Project Discovery System
|
||||
项目发现系统是自动化探索和收录 AI 项目的核心功能,采用**双 Agent 协作架构**实现上下文隔离:
|
||||
|
||||
#### 架构组件
|
||||
1. **自定义 Agents** (`.claude/agents/`):
|
||||
- `content-explorer-agent`: 项目内容探索专家,批量探索项目并生成结构化数据
|
||||
- 使用 `agent-browser` 子任务并行探索 GitHub 项目
|
||||
- 应用严格的内容质量标准(客观描述、避免营销术语、不写入动态数据)
|
||||
- 生成符合 `ProjectInputSchema` 的 JSON 数据
|
||||
- `api-submitter-agent`: API 提交专家,处理探索结果的提交和状态更新
|
||||
- 批量标记任务为 IN_PROGRESS
|
||||
- 提交探索数据到完成 API
|
||||
- 自动重试失败的提交(指数退避,最多3次)
|
||||
|
||||
2. **Claude Commands** (`.claude/commands/`):
|
||||
- `/discover-projects`: 主命令,协调探索和提交流程
|
||||
- 参数解析(任务数量、批次大小)
|
||||
- 分批处理(默认每批3个任务)
|
||||
- Agent 调度和进度显示
|
||||
- 结果汇总和错误报告
|
||||
|
||||
3. **API Endpoints** (`src/app/api/discovery/`):
|
||||
- `POST /api/discovery/tasks`: 创建新的探索任务(支持批量)
|
||||
- `GET /api/discovery/tasks`: 获取待处理任务列表(支持 status/limit/offset 过滤)
|
||||
- `PATCH /api/discovery/tasks/{id}`: 更新任务状态
|
||||
- `POST /api/discovery/tasks/{id}/complete`: 完成任务并提交项目数据
|
||||
- `GET /api/webhook/check-duplicates`: 检查项目是否已存在(URL 去重)
|
||||
|
||||
4. **Database Model**:
|
||||
- `ProjectDiscoveryTask`: 任务追踪表
|
||||
- 状态: PENDING → IN_PROGRESS → COMPLETED/FAILED
|
||||
- 原始数据: `sourceUrl`, `sourceType`
|
||||
- 探索结果: `explorationData` (JSON), `explorationSummary`
|
||||
- 错误处理: `errorMessage`, `retryCount`, `lastRetryAt`
|
||||
- 索引: `idx_task_status_created`, `idx_task_source_url`, `idx_task_project_id`
|
||||
|
||||
#### 数据流转
|
||||
```
|
||||
用户输入 URL → 创建 PENDING 任务 → /discover-projects 命令
|
||||
↓
|
||||
分批获取任务(每批3个)
|
||||
↓
|
||||
Content Explorer Agent (并行探索) → 探索结果 JSON
|
||||
↓
|
||||
API Submitter Agent (提交到生产环境 API)
|
||||
↓
|
||||
更新任务状态 → COMPLETED/FAILED
|
||||
```
|
||||
|
||||
#### 质量标准
|
||||
- **数据模板**: `.claude/schemas/project-content-template.md`
|
||||
- **描述要求**: 清晰说明功能、突出价值、避免营销术语、10-500字
|
||||
- **内容要求**: 从 README 提取并重新组织、不机械翻译、符合中文表达习惯
|
||||
- **链接要求**: 必须包含 GITHUB 链接、所有链接可访问
|
||||
- **标签要求**: 1-10 个标签、技术/应用/状态分类
|
||||
- **动态数据处理**: Star/Fork 数量等动态数据不写入内容,使用 GitHub Badge 显示
|
||||
|
||||
#### 环境变量
|
||||
- `WEBHOOK_API_KEY`: 生产环境 API 密钥(必需,用于认证)
|
||||
|
||||
#### 使用示例
|
||||
```bash
|
||||
# 处理默认10个任务(每批3个)
|
||||
/discover-projects
|
||||
|
||||
# 处理指定数量的任务
|
||||
/discover-projects 5
|
||||
|
||||
# 自定义批次大小
|
||||
/discover-projects 9 --batch=2
|
||||
|
||||
# 处理所有待处理任务
|
||||
/discover-projects all --batch=5
|
||||
```
|
||||
|
||||
## MCP Servers Usage (按需使用)
|
||||
|
||||
1. **context7**: 不确定 API 用法时查阅最新文档
|
||||
@@ -144,7 +219,7 @@ When updating an existing project, the webhook:
|
||||
|
||||
## Git Commits
|
||||
|
||||
提交信息主要使用中文,使用描述性的提交格式。
|
||||
Git 提交信息遵循约定式提交格式(详见上方 Code Quality & Standards → Git Commit Conventions)。
|
||||
|
||||
## Development Workflow
|
||||
|
||||
@@ -153,3 +228,58 @@ When updating an existing project, the webhook:
|
||||
- The middleware handles locale detection and routing automatically - no manual locale configuration needed
|
||||
- When adding new translations, update both `src/messages/zh.json` and `src/messages/en.json`
|
||||
- Database changes require running `pnpm prisma migrate dev` to update the schema
|
||||
|
||||
## Code Quality & Standards
|
||||
|
||||
### TypeScript Configuration
|
||||
- **Strict mode enabled** with additional safety flags: `noUncheckedIndexedAccess`, `noImplicitReturns`, `noFallthroughCasesInSwitch`
|
||||
- Path alias: `@/*` maps to `./src/*`
|
||||
- Target: ES2017 for modern browser support
|
||||
|
||||
### Validation & Security
|
||||
- **API Authentication**: Webhook uses timing-safe comparison (`crypto.timingSafeEqual`) to prevent timing attacks
|
||||
- **Input Validation**: All API inputs use Zod schemas with detailed error messages
|
||||
- **SQL Injection Prevention**: Prisma ORM with parameterized queries
|
||||
- **Data Sanitization**: Markdown content sanitized with `rehype-sanitize` plugin
|
||||
|
||||
### Error Handling Patterns
|
||||
- **Webhook**: Partial success mode - continues processing remaining projects even if individual projects fail
|
||||
- **Database**: Unique constraints use try-catch with fallback logic (e.g., tag slug conflicts in webhook)
|
||||
- **Console**: Use `console.warn()` for operational logs, `console.error()` for errors
|
||||
|
||||
### Git Commit Conventions
|
||||
- **Format**: `<type>: <description>` (type in lowercase Chinese: feat/fix/refactor/chore)
|
||||
- **Types**: `feat` (新功能), `fix` (修复), `refactor` (重构), `chore` (杂项)
|
||||
- **Examples**:
|
||||
- `feat: 新增项目发现任务系统`
|
||||
- `fix: 修复 ESLint 警告`
|
||||
- `refactor: 重构项目内容标准实现职责分离`
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Tests (Vitest)
|
||||
- Location: Test files co-located with source code (e.g., `*.test.ts`)
|
||||
- Run: `pnpm test` for all tests, `pnpm test <pattern>` for specific tests
|
||||
- Configuration: Vitest with `@testing-library/jest-dom` matchers
|
||||
|
||||
### E2E Tests (Playwright)
|
||||
- Location: `tests/e2e/` or co-located with features
|
||||
- Run: `pnpm test:e2e` to execute all E2E tests
|
||||
- Usage: Focus on critical user journeys (project browsing, search, locale switching)
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Database Optimization
|
||||
- **Index Strategy**: Composite indexes on frequently queried fields (status+createdAt, type+url)
|
||||
- **N+1 Prevention**: Batch queries for tags (see webhook route:94-98)
|
||||
- **Connection Pooling**: Prisma client singleton pattern (`src/lib/prisma.ts`)
|
||||
|
||||
### Frontend Performance
|
||||
- **ISR**: Project detail pages revalidated every 5 minutes (`revalidate = 300`)
|
||||
- **Package Optimization**: Lucide-react imports optimized via `experimental.optimizePackageImports`
|
||||
- **Image Domains**: Pre-configured for localhost, *.anthropic.com, img.shields.io
|
||||
|
||||
### API Rate Limiting
|
||||
- Webhook: Max 100 projects per request
|
||||
- Discovery tasks: Max 50 tasks per batch creation
|
||||
- All queries: Max 100 items per page (enforced via Zod schemas)
|
||||
|
||||
Reference in New Issue
Block a user