68 lines
4.7 KiB
Markdown
68 lines
4.7 KiB
Markdown
---
|
||
name: fullstack-start-verify
|
||
description: 启动本地项目的前端和后端服务，并通过进程状态、HTTP 健康检查、接口检查和可用时的浏览器冒烟测试验证整体功能。用于 Codex 需要运行全栈项目、验证前后端联调、排查启动失败，或确认用户流程是否端到端可用的场景。
|
||
---
|
||
|
||
# 全栈启动与验证
|
||
|
||
当用户要求启动前后端、验证整体功能、跑通本地联调或确认项目是否可用时使用本技能。目标是得到可复现的验证结论，而不是只确认某个进程曾经启动过。
|
||
|
||
## 工作流程
|
||
|
||
1. 在启动前检查项目。
|
||
- 阅读适用的 `AGENTS.md`、`README.md`、根目录环境变量示例，以及前后端的项目清单文件。
|
||
- 确认实际使用的包管理器和启动命令。优先使用项目文档和项目自带包装器中的命令，例如 `npm`、`pnpm`、`yarn`、`mvnw`、`gradlew`、`uv` 等。
|
||
- 找到后端健康检查地址、前端地址、API 基础地址、所需的数据库或缓存服务，以及文档中提供的测试账号。
|
||
- 不要为了让检查通过而虚构凭据、覆盖 `.env`、执行迁移或重置数据。
|
||
|
||
2. 执行启动前检查。
|
||
- 确认所需运行时和依赖目录可用。
|
||
- 检查计划使用的端口。只有在进程和健康响应明确属于当前项目时才复用服务，绝不要结束未知进程。
|
||
- 仅在项目文档说明了启动方式且用户已将其纳入范围时，启动 MySQL 或 Redis 等基础设施。
|
||
- 如果缺少必要的密钥、数据库或账号，应报告阻塞原因，不要降低验证标准。
|
||
|
||
3. 使用 `scripts/start_and_verify.py` 启动两个应用服务。
|
||
- 从项目根目录运行脚本。
|
||
- 传入明确的工作目录、启动命令和地址。对于健康检查之外的重要 API 路由，使用 `--check-url label=url` 添加检查。
|
||
- 后端应使用项目专用的健康检查地址，而不是只检查 TCP 端口是否打开；前端应检查开发服务器根路径或已知路由。
|
||
- 脚本只管理和清理自己启动的进程。只有用户明确要求服务继续运行时，才使用 `--keep-running`。
|
||
- 排查失败时使用 `--keep-logs` 保留日志。避免把密钥放在命令行参数中。
|
||
|
||
Example:
|
||
|
||
```powershell
|
||
python skills/fullstack-start-verify/scripts/start_and_verify.py `
|
||
--backend-cmd "mvn -f backend/pom.xml spring-boot:run" `
|
||
--backend-dir . `
|
||
--backend-url http://127.0.0.1:8080/api/health `
|
||
--frontend-cmd "npm run dev -- --host 127.0.0.1" `
|
||
--frontend-dir frontend `
|
||
--frontend-url http://127.0.0.1:5173/ `
|
||
--check-url health=http://127.0.0.1:8080/api/health
|
||
```
|
||
|
||
4. 按递进层级验证应用。
|
||
- 确认两个健康检查地址都返回可接受的 HTTP 状态，并确认对应进程仍在运行。
|
||
- 针对主要用户流程执行聚焦的后端或 API 检查。除非用户明确要求写入流程且测试数据安全，否则优先执行只读检查。
|
||
- 在相关且不会重复更权威检查的情况下，执行前端构建或项目已有测试命令。
|
||
- 如果有 Playwright 或其他浏览器工具，打开前端地址并执行主要用户路径：加载页面、完成最小有意义的操作，同时验证页面可见结果和网络/API 结果。
|
||
- 如果没有浏览器工具，应明确说明未验证 UI 交互；仅凭 HTTP 检查不能声称完成了端到端验证。
|
||
|
||
5. 汇报并清理环境。
|
||
- 汇报具体命令、地址、执行的检查、通过或失败状态，以及第一个可执行的失败原因。
|
||
- 分开汇报基础设施、后端、前端和浏览器结果，明确哪些部分已通过。
|
||
- 失败时给出日志位置或相关日志尾部，同时隐藏密码、令牌和连接字符串。
|
||
- 除非用户要求服务持续运行，否则在结束前确认脚本启动的进程已经停止。
|
||
|
||
## 失败处理
|
||
|
||
- 服务在地址就绪前退出，属于启动失败。重试前先检查捕获的日志。
|
||
- 超时不算通过。检查依赖是否可用、端口是否冲突、环境变量是否加载、代理配置和服务日志。
|
||
- 后端健康但前端 API 调用失败，属于集成失败。检查前端代理或基础地址，以及 CORS 配置。
|
||
- 前端页面能加载但浏览器操作失败，属于用户流程失败。记录准确路由、操作、响应状态和控制台错误。
|
||
- 验证期间不要修复无关代码、修改生产配置或删除数据，除非用户明确扩大任务范围。
|
||
|
||
## 内置脚本
|
||
|
||
`scripts/start_and_verify.py` 是一个不依赖第三方库的进程运行器，负责本流程中的启动和 HTTP 检查。使用不常见选项前先阅读 `--help` 输出。脚本默认创建临时日志并在清理后删除；排查问题时传入 `--keep-logs` 保留日志。
|