跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

dev-workflow

The complete development workflow for SkillHub contributors including local dev, staging validation, testing, and PR creation. Ensures agents follow the correct sequence of steps.

iflytek · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add iflytek/skillhub --skill dev-workflow

技能说明


name: dev-workflow description: The complete development workflow for SkillHub contributors including local dev, staging validation, testing, and PR creation. Ensures agents follow the correct sequence of steps. license: Apache-2.0

Development Workflow Skill

Trigger

Use this skill when:

  • Starting local development
  • Running tests or validation
  • Preparing a pull request
  • Setting up the development environment
  • Working with parallel agent worktrees

Prerequisites

  • Java 21+ (java -version)
  • Maven wrapper (./mvnw in server/)
  • Node.js + pnpm
  • Docker + docker compose
  • gh CLI (for PR creation)
  • curl (for smoke tests and health checks)

Workflow Stages

Stage 1: Local Development (fast iteration)

One-command start:

make dev-all          # Start full stack: Postgres, Redis, MinIO, scanner, backend, frontend
make dev-all-down     # Stop everything
make dev-all-reset    # Full reset (clears data volumes)
make dev-status       # Check service status

Access points:

  • Web UI: http://localhost:3000
  • Backend API: http://localhost:8080
  • Scanner: http://localhost:8000

Individual components:

make dev              # Start dependency services only (Postgres, Redis, MinIO, scanner)
make dev-server       # Start backend in foreground (blocking)
make dev-web          # Start Vite dev server (HMR enabled)
make dev-server-restart # Restart backend process
make dev-down         # Stop dependency services
make dev-logs         # View backend logs (use SERVICE=frontend for frontend logs)

Backend development: After editing Java code, run make dev-server-restart.

Frontend development: Vite HMR enabled — save a file for instant browser updates.

Scanner: The security scanner is enabled by default in dev. Health checked at http://localhost:8000/health.

Stage 2: Testing

CommandScopeNotes
make test-backend-appBackend unit testsskillhub-app + dependencies (-am)
make test-backendAll backend modulesAll modules via ./mvnw test
make test-frontendFrontend unit testsVitest (pnpm run test)
make test-e2e-frontendFrontend E2E testsPlaywright
make test-e2e-smoke-frontendFrontend E2E smokePlaywright subset
make typecheck-webTypeScript type checktsc --noEmit
make lint-webESLint checkFrontend linting

Important: Never run ./mvnw -pl skillhub-app clean test directly under server/. Use -am or Makefile targets to include dependent modules.

Stage 3: Staging Regression (pre-PR validation)

make staging          # Build backend Docker image + frontend static + smoke test
make staging-down     # Tear down
make staging-logs     # View backend logs
SERVICE=web make staging-logs  # View Nginx logs

Staging validates the containerized deployment path:

  • Backend: built as Docker image from local source (Dockerfile.dev)
  • Frontend: built as static files (pnpm build), served by Nginx
  • Dependencies: same Postgres/Redis/MinIO as local dev
  • Smoke test runs against staging via scripts/smoke-test.sh

Staging URLs:

  • Web UI: http://localhost
  • Backend API: http://localhost:8080

Staging credentials (for bootstrap admin):

  • Username: admin
  • Password: Admin@staging2026

Stage 4: Pull Request

make pr               # Push branch + create PR (requires gh CLI)

Requirements:

  • gh CLI installed and authenticated
  • Not on main/master branch
  • All changes committed (will prompt if uncommitted changes exist)

Useful Commands

CommandDescription
make generate-apiRegenerate OpenAPI types from running backend
make namespace-smokeNamespace workflow smoke test
make db-resetReset database only (Flyway migrate)
make validate-release-configValidate release env vars (.env.release)
./scripts/smoke-test.shBasic API smoke test (health, auth, labels)
./scripts/namespace-smoke-test.shNamespace CRUD + membership smoke test
./scripts/check-openapi-generated.shVerify OpenAPI types are not stale
make parallel-init TASK=nameCreate parallel worktree for agent

Mock Auth Users

User IDRoleHeader
local-userRegular userX-Mock-User-Id: local-user
local-adminSuper adminX-Mock-User-Id: local-admin

Bootstrap admin (local profile):

  • Username: admin
  • Password: ChangeMe!2026

Smoke Test Coverage

scripts/smoke-test.sh validates:

  1. Health endpoint (/actuator/health → 200)
  2. Prometheus metrics (/actuator/prometheus → 200)
  3. Namespaces API (/api/v1/namespaces → 200)
  4. Auth required (/api/v1/auth/me → 401 without session)
  5. User registration flow (with CSRF)
  6. Auth me with session
  7. Password change
  8. Logout + verify 401 after
  9. Admin login
  10. Label CRUD (admin only)

Additional smoke tests:

  • scripts/namespace-smoke-test.sh — Namespace creation, membership, publishing
  • scripts/governance-smoke-test.sh — Governance and moderation
  • scripts/promotion-smoke-test.sh — Skill promotion between scopes

Parallel Agent Workflow

For parallel agent development with isolated worktrees:

make parallel-init TASK=feature-name           # Create worktree
make parallel-sync SOURCES="feat1 feat2"       # Merge feature branches
make parallel-up SOURCES="feat1 feat2"         # Merge + start dev environment
make parallel-down                             # Stop parallel environment

See docs/13-parallel-workflow.md for full details.

Commit Style

Use conventional commit format:

<type>(<scope>): <description>

Examples:

feat(auth): add local account login
fix(publish): resolve null pointer when skill metadata is missing name
docs(deploy): clarify runtime image usage
test(namespace): add membership service edge case tests
refactor(review): extract query reposi
阅读完整来源 ↗