docs: 完善 CLAUDE.md 开发指南和项目发现工作流文档

- 添加常见开发模式指南（API 端点、数据库字段、自定义 Agent、多语言内容）
- 新增故障排除部分，涵盖常见问题和调试技巧
- 改进 GET /api/discovery/tasks 端点，支持通过查询参数传递 API key
- 更新环境变量示例，使用更安全的 API key 格式

CLAUDE.md

@@ -228,6 +228,36 @@ Git 提交信息遵循约定式提交格式（详见上方 Code Quality & Standa
 - 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
+- **Always verify API responses** with `WEBHOOK_API_KEY` when testing webhook or discovery endpoints
+- **Use `pnpm prisma studio`** to inspect database state during development
+
+## Common Development Patterns
+
+### Adding a New API Endpoint
+1. Create route file in `src/app/api/` (e.g., `src/app/api/your-endpoint/route.ts`)
+2. Import validation schemas from `@/lib/validations`
+3. Use `crypto.timingSafeEqual()` for API key authentication (see webhook route:36-43)
+4. Implement partial success mode for batch operations (see webhook route:55-67)
+5. Return structured errors with `NextResponse.json()`
+
+### Adding New Database Fields
+1. Update `prisma/schema.prisma` with new fields
+2. Run `pnpm prisma migrate dev --name your_migration_name`
+3. Update Zod schemas in `src/lib/validations.ts`
+4. Update TypeScript types in `src/hooks/useProjects.ts` if needed
+5. Regenerate Prisma client: `pnpm prisma generate`
+
+### Creating Custom Agents
+1. Create agent file in `.claude/agents/your-agent.md`
+2. Define agent role, capabilities, and task instructions
+3. Reference existing agents (`content-explorer-agent`, `api-submitter-agent`) as templates
+4. Test via corresponding Claude Command in `.claude/commands/`
+
+### Working with Multilingual Content
+- All user-facing content should have both Chinese (`name`, `description`) and English (`nameEn`, `descriptionEn`) versions
+- Use `src/messages/zh.json` and `src/messages/en.json` for UI translations
+- For project data, prefer Chinese as primary language with English as optional
+- When creating content, avoid mechanical translation - write naturally for each locale
 
 ## Code Quality & Standards
 
@@ -283,3 +313,79 @@ Git 提交信息遵循约定式提交格式（详见上方 Code Quality & Standa
 - 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)
+
+## Troubleshooting
+
+### Common Issues
+
+**Database Connection Errors**
+- Verify `DATABASE_URL` is set in `.env.local`
+- Check Neon dashboard for database status
+- Run `pnpm prisma db push` to sync schema if needed
+
+**Webhook Authentication Failures**
+- Ensure `WEBHOOK_API_KEY` is set and matches (32+ characters)
+- Check that API key is sent in request body
+- Verify timing-safe comparison is used (never log raw API keys)
+
+**Missing Translations**
+- All new UI text must be added to both `src/messages/zh.json` and `src/messages/en.json`
+- Missing keys will display as `missing_key_name` in the UI
+- Test both locales (switch via URL path `/zh/` or `/en/`)
+
+**Build Errors After Schema Changes**
+- Run `pnpm prisma generate` to regenerate Prisma client
+- Restart dev server after schema changes
+- Check for TypeScript errors in generated types
+
+**Discovery Task Failures**
+- Check `src/app/api/discovery/lib/discovery-service.ts:16-80` for deduplication logic
+- Verify `WEBHOOK_API_KEY` is set for api-submitter-agent
+- Use `pnpm prisma studio` to inspect task status and error messages
+- Check browser console for agent-browser errors (requires chrome-devtools-mcp)
+
+### Debugging Tips
+
+1. **Enable Prisma Query Logging**:
+   ```typescript
+   // In src/lib/prisma.ts
+   export const prisma = new PrismaClient({
+     log: ['query', 'error', 'warn'],
+   })
+   ```
+
+2. **Check Database State**:
+   ```bash
+   pnpm prisma studio
+   # Opens at http://localhost:5555
+   ```
+
+3. **Test API Endpoints**:
+   ```bash
+   # Create discovery task
+   curl -X POST http://localhost:3000/api/discovery/tasks \
+     -H "Content-Type: application/json" \
+     -d '{"apiKey":"YOUR_KEY","tasks":[{"sourceUrl":"https://github.com/user/repo"}]}'
+   ```
+
+4. **Validate Request Payloads**:
+   - All schemas are in `src/lib/validations.ts`
+   - Check schema errors in API response `details` field
+   - Ensure all required fields are present
+
+### Environment Variables Checklist
+
+For local development, ensure these are set in `.env.local`:
+```bash
+# Database (Neon PostgreSQL)
+DATABASE_URL="postgres://[user]:[password]@[host]/[database]?sslmode=require"
+
+# Webhook API Key (32+ characters)
+WEBHOOK_API_KEY="your-secret-api-key-min-32-chars"
+```
+
+For production deployment (Vercel):
+- Set `DATABASE_URL` in Vercel Dashboard (Environment Variables)
+- Set `WEBHOOK_API_KEY` in Vercel Dashboard
+- Run `pnpm prisma db push` after first deployment to create tables
+- Do NOT use `vercel.json` for environment variables

docs/discovery-workflow.md

@@ -372,11 +372,11 @@ ExternalLink (外部链接表)
 
 ```env
 # .env.local (本地开发)
-WEBHOOK_API_KEY=your-production-api-key-here  # 用于调用完成 API
+WEBHOOK_API_KEY=sk_live_your_secure_api_key_min_32_chars  # 用于调用完成 API
 
 # 生产环境 (Vercel Dashboard 配置)
 DATABASE_URL=postgres://...
-WEBHOOK_API_KEY=your-production-api-key-here
+WEBHOOK_API_KEY=sk_live_your_secure_api_key_min_32_chars
 ```
 
 ### 依赖服务

src/app/api/discovery/tasks/route.ts

@@ -96,8 +96,11 @@ export async function POST(request: NextRequest) {
  */
 export async function GET(request: NextRequest) {
   try {
+    const { searchParams } = new URL(request.url)
+
     // 验证 API Key（只读权限）
-    const apiKey = request.headers.get('x-api-key')
+    // 支持两种方式：1. 请求头 x-api-key  2. 查询参数 apiKey
+    const apiKey = request.headers.get('x-api-key') || searchParams.get('apiKey')
     const validApiKey = process.env.WEBHOOK_API_KEY
     if (
       !validApiKey ||
@@ -109,8 +112,6 @@ export async function GET(request: NextRequest) {
         { status: 401 }
       )
     }
-
-    const { searchParams } = new URL(request.url)
     const validation = GetDiscoveryTasksQuerySchema.safeParse({
       status: searchParams.get('status') || undefined,
       limit: searchParams.get('limit') || '10',