Files

2026-07-28 16:09:45 +08:00

6.8 KiB

Raw Blame History

name, description

name	description
fullstack-start-verify	快速启动或复用本地项目的前端和后端服务，并通过进程状态、HTTP 健康检查、接口检查和可用时的浏览器冒烟测试验证整体功能。用于 Codex 需要运行全栈项目、验证前后端联调、排查启动失败，或确认用户流程是否端到端可用的场景。

全栈启动与验证

当用户要求启动前后端、验证整体功能、跑通本地联调或确认项目是否可用时使用本技能。默认走快速只读路径，目标是以最少的启动和检查步骤得到可复现结论，而不是只确认某个进程曾经启动过。

验证层级

先根据任务范围选择最低必要层级，完成后不要自动升级：

启动检查：复用或启动前后端，检查两个健康地址；仅在需要确认数据库联通时增加 1 个已有的只读 API。
联调检查：在启动检查基础上增加 1 至 2 个主要只读 API，确认前端代理、后端路由和基础设施链路。
回归检查：只有用户明确要求、代码发生相关变更或快速检查失败时，才执行构建、测试或浏览器冒烟。

启动检查不执行 npm ci、mvn test、前端构建、数据库迁移或浏览器操作。不要用固定 sleep 等待服务，统一让内置脚本轮询 HTTP 地址。

工作流程

在启动前检查项目。
- 并行阅读适用的 AGENTS.md、README.md、根目录环境变量示例，以及前后端的项目清单文件；同一任务中不要重复读取已确认的配置。
- 确认实际使用的包管理器和启动命令。优先使用项目文档和项目自带包装器中的命令，例如 npm、pnpm、yarn、mvnw、gradlew、uv 等。
- 找到后端健康检查地址、前端地址、API 基础地址、所需的数据库或缓存服务，以及文档中提供的测试账号。
- 不要为了让检查通过而虚构凭据、覆盖 .env、执行迁移或重置数据。
执行启动前检查。
- 确认所需运行时和依赖目录可用。前端已有 node_modules 时直接启动，不要每次重复执行 npm ci；仅在依赖缺失或用户明确要求重装时安装。
- 检查计划使用的端口。健康地址响应必须能确认属于当前项目时，才使用 --reuse-running 复用服务；复用的服务不由脚本结束。无法确认归属时不要复用，也绝不要结束未知进程。
- 仅在项目文档说明了启动方式且用户已将其纳入范围时，启动 MySQL 或 Redis 等基础设施。
- 如果缺少必要的密钥、数据库或账号，应报告阻塞原因，不要降低验证标准。
使用 scripts/start_and_verify.py 复用或启动两个应用服务。脚本默认使用 0.25 秒快速轮询，并行等待服务就绪；使用 --reuse-running 时会并行探测健康地址，只启动未就绪的服务。
- 从项目根目录运行脚本。
- 传入明确的工作目录、启动命令和地址。对于健康检查之外的重要 API 路由，使用 --check-url label=url 添加只读检查；不要重复添加已经作为 --backend-url 的健康地址。
- 后端应使用项目专用的健康检查地址，而不是只检查 TCP 端口是否打开；前端应检查开发服务器根路径或已知路由。
- --check-url 只添加必要的只读 API。后端健康地址就绪后，脚本会立即并行执行这些检查，同时继续等待前端，避免额外 API 检查串行阻塞启动流程。
- 脚本只管理和清理自己启动的进程。只有用户明确要求服务继续运行时，才使用 --keep-running。
- 排查失败时使用 --keep-logs 保留日志。避免把密钥放在命令行参数中。
Example:
```
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/v1/health `
  --frontend-cmd "npm run dev -- --host 127.0.0.1" `
  --frontend-dir frontend `
  --frontend-url http://127.0.0.1:5173/ `
  --reuse-running `
  --check-url summary=http://127.0.0.1:8080/api/v1/users/summary
```
按递进层级验证应用。
- 启动检查先确认两个健康检查地址；仅在数据库或核心联调需要时增加 1 个主要只读 API。联调检查最多增加 2 个主要只读 API，避免重复请求同一资源。
- 只有代码变更、用户明确要求回归，或快速路径暴露问题时，才执行前端构建、后端测试等较慢命令。
- 只有涉及页面或交互变更且有浏览器工具时，才执行浏览器冒烟：加载页面、完成最小有意义的操作，同时验证页面可见结果和网络/API 结果。
- 除非用户明确要求写入流程且测试数据安全，否则不执行新增、修改、删除或数据库迁移。
- 如果没有浏览器工具，应明确说明未验证 UI 交互；仅凭 HTTP 检查不能声称完成了端到端验证。
汇报并清理环境。
- 汇报验证任务 ID、具体命令、地址、执行的检查、通过或失败状态，以及第一个可执行的失败原因。
- 分开汇报基础设施、后端、前端和浏览器结果，明确哪些部分已通过。
- 失败时给出日志位置或相关日志尾部，同时隐藏密码、令牌和连接字符串。
- 除非用户要求服务持续运行，否则在结束前确认脚本启动的进程已经停止。

失败处理

服务在地址就绪前退出，属于启动失败。重试前先检查捕获的日志。
超时不算通过。检查依赖是否可用、端口是否冲突、环境变量是否加载、代理配置和服务日志。
只允许在定位出可修复的瞬时原因后重试一次；重试时复用已确认健康的服务，不重复安装依赖或重复启动基础设施。连续失败应报告第一个可执行的根因。
后端健康但前端 API 调用失败，属于集成失败。检查前端代理或基础地址，以及 CORS 配置。
前端页面能加载但浏览器操作失败，属于用户流程失败。记录准确路由、操作、响应状态和控制台错误。
验证期间不要修复无关代码、修改生产配置或删除数据，除非用户明确扩大任务范围。

内置脚本

scripts/start_and_verify.py 是一个不依赖第三方库的进程运行器，负责本流程中的服务复用、启动和 HTTP 检查。脚本会为检查请求添加 X-Request-Id，输出验证任务 ID，并行探测已运行服务；后端就绪后立即执行额外检查，同时继续等待前端。使用不常见选项前先阅读 --help 输出。脚本默认创建临时日志并在清理后删除；排查问题时传入 --keep-logs 保留日志。错误日志摘要会脱敏，但保留日志前仍需确认服务自身没有输出敏感信息。

6.8 KiB Raw Blame History Unescape Escape