{"owner":"justjavac","repo":"wechat-miniapp-radar","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"files":{"AGENTS.md":"# 小程序雷达开发指南\n\n本文件面向开发者和代码代理。README 面向最终用户，资源列表由 `data/resources.yaml` 生成，不要在 README 里维护开发、部署和运维细节。\n\n## 项目结构\n\n- `app/`：Next.js App Router 页面和 API route。\n- `components/`：共享 UI 组件。\n- `lib/`：业务逻辑、AI、缓存、健康检查、评分、数据库映射和运维辅助模块。\n- `db/`：Drizzle schema 与数据库客户端。\n- `scripts/`：数据生成、验证、导入、运维和测试脚本。\n- `data/resources.yaml`：资源数据源。\n- `public/api/resources.json`：由 `npm run generate` 生成的静态资源快照。\n- `public/api/ai-summaries.json`、`public/api/radar-scores.json`、`public/api/weekly/*`：生成快照。\n- `docs/`：本地实施文档，仅保留在本地，不纳入版本库。\n\n## 本地运行\n\n```bash\nnpm install\nnpm run dev\n```\n\n生产构建：\n\n```bash\nnpm run build\n```\n\n完整校验：\n\n```bash\nnpm run check\n```\n\n## 常用任务\n\n```bash\nnpm run generate\nnpm run generate:check\nnpm run validate\nnpm run typecheck\nnpm run deploy:check\nnpm run integrations:verify\nnpm run db:verify\nnpm run db:import:test\nnpm run advisor:test\nnpm run doctor:test\nnpm run cli:test\nnpm run deployment:verify -- https://your-project.vercel.app\nnpm run mvp:check\nnpm run vercel:preflight -- https://your-project.vercel.app\nnpm run production:bootstrap -- https://your-project.vercel.app\n```\n\nCLI examples:\n\n```bash\nnpx miniprogram-radar health --out=health.md\nnpx miniprogram-radar resources --type=framework --status=adopt --format=csv --out=resources.csv\nnpx miniprogram-radar compare --ids=github-com-nervjstaro,github-com-dcloudiouni-app --out=compare.md\nnpx miniprogram-radar advisor \"React 团队做电商小程序，应该选 Taro 还是原生？\"\nnpx miniprogram-radar advisor \"React 团队做电商小程序，应该选 Taro 还是原生？\" --prompt --out=advisor-prompt.json\nnpx miniprogram-radar doctor ./my-weapp\n```\n\n## 生成文件\n\n- 修改 `data/resources.yaml` 后运行 `npm run generate`。\n- README 和 `public/api/resources.json` 都由 `scripts/generate.ts` 生成。\n- CI 会运行 `npm run generate:check`，生成源和生成产物必须一致。\n\n## 环境变量\n\n参考 `.env.example`。\n\n- `DATABASE_URL`：可选，配置后资源导入、采集信号、Advisor 会话和周报会写入 Postgres。\n- `SITE_URL` / `NEXT_PUBLIC_SITE_URL`：可选，配置生产站点根地址，用于 canonical sitemap 和 robots 地址。\n- `CRON_SECRET`：建议配置，用于保护 `/api/cron/*`。\n- `ADMIN_TOKEN`：建议配置，用于保护 `/admin` 和 `/api/admin/*`。\n- `GITHUB_TOKEN`：可选，提高 GitHub 采集额度。\n- `OPENAI_API_KEY`：可选，用于真实 AI Advisor；未配置、超时或校验失败时使用规则建议。可使用 OpenRouter API key。\n- `OPENAI_API_URL`：可选，OpenAI-compatible endpoint；OpenRouter 使用 `https://openrouter.ai/api/v1`。\n- `OPENAI_MODEL`：可选，主模型，默认 `openai/gpt-oss-20b:free`。\n- `OPENAI_FALLBACK_MODEL`：可选，备用模型，默认 `nvidia/nemotron-nano-9b-v2:free`。\n- `BLOB_READ_WRITE_TOKEN`：可选，用于上传周报快照、资源导出快照和 Doctor 报告。\n- `UPSTASH_REDIS_REST_URL`、`UPSTASH_REDIS_REST_TOKEN` 或 Vercel Marketplace 注入的 `KV_REST_API_URL`、`KV_REST_API_TOKEN`：可选，用于 Advisor 缓存和分布式限流；未配置时使用内存兜底。\n- `OPERATION_LOG_RETENTION_DAYS`：可选，运行日志保留天数，默认 30 天。\n- `VERCEL_TOKEN`、`VERCEL_PROJECT_ID`、`VERCEL_ORG_ID`：可选，用于非交互 Vercel CLI 部署或 preflight。\n\n## 部署检查\n\n- 健康检查：`GET /api/health`，包含资源快照、数据库、集成配置和最近一次 AI Advisor 运行状态。\n- 数据库验证：`EXPECT_DATABASE=1 npm run db:verify`\n- GitHub/Blob/Redis 验证：`EXPECT_GITHUB=1 EXPECT_BLOB=1 EXPECT_UPSTASH_REDIS=1 npm run integrations:verify`\n- 生产就绪 API：`GET /api/admin/readiness`，需 `ADMIN_TOKEN`。\n- Vercel 部署前置检查：`npm run vercel:preflight -- <production-url>`\n- MVP 收口检查：`npm run mvp:check`；严格上线模式：`EXPECT_MVP=1 EXPECT_SITE_URL=1 EXPECT_OPENAI=1 npm run mvp:check -- <production-url>`\n- 生产初始化计划：`npm run production:bootstrap -- <production-url>`；执行迁移、导入和线上验证时追加 `execute`。\n- 生产验证：`VERIFY_CRON_SECRET=<CRON_SECRET> VERIFY_ADMIN_TOKEN=<ADMIN_TOKEN> npm run deployment:verify -- <production-url>`\n\n## Git 与发布流程\n\n- 不直接推送到 `main`。\n- 按逻辑分步提交：文档、代码、清理、测试规则等不同类型变更尽量拆成独立 commit。\n- 功能和修复使用独立分支，创建 PR 后通过 Vercel Preview 验证。\n- Preview 和 GitHub checks 通过后再合并。\n- 合并后等待 Vercel Production 部署完成，并确认 `Verify Vercel Production` workflow 通过。\n"}}