scaffold-project
Centralized full-stack project scaffold — bootstraps a complete Python/FastAPI backend skeleton (bootstrap) and scaffolds Next.js (web/) or React Chrome Extension (extension/) frontends (setui) with 11 themes and AI design system intelligence.
- License 许可
- MIT
- 最近更新
- 2026-11-11
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- scaffold-project
- description
- Centralized full-stack project scaffold — bootstraps a complete Python/FastAPI backend skeleton (bootstrap) and scaffolds Next.js (web/) or React Chrome Extension (extension/) frontends (setui) with 11 themes and AI design system intelligence.
02 资源文件 135
- 脚本resources/initialize/backend/__init__.py31 B
- 其他resources/initialize/backend/.env.example996 B
- 其他resources/initialize/backend/.gitignore2.2 KB
- 其他resources/initialize/backend/.models.example376 B
- 脚本resources/initialize/backend/bootstrap.py6.6 KB
- 其他resources/initialize/backend/deploy/nginx/nginx.conf961 B
- 其他resources/initialize/backend/deploy/nginx/nginx.conf.template1.0 KB
- 许可证resources/initialize/backend/LICENSE1.0 KB
- 脚本resources/initialize/backend/main.py3.9 KB
- 其他resources/initialize/backend/pyproject.toml1.0 KB
- 参考文档resources/initialize/backend/README.md225 B
- 参考文档resources/initialize/backend/requirements.txt209 B
- 脚本resources/initialize/backend/scripts/generate_nginx_conf.py843 B
- 脚本resources/initialize/backend/src/config/__init__.py1.3 KB
- 脚本resources/initialize/backend/src/config/dotenv.py1.4 KB
- 脚本resources/initialize/backend/src/config/files.py4.5 KB
- 脚本resources/initialize/backend/src/config/logger.py5.4 KB
- 脚本resources/initialize/backend/src/config/paths.py1.6 KB
- 脚本resources/initialize/backend/src/config/settings.py5.9 KB
- 脚本resources/initialize/backend/src/core/__init__.py417 B
- 脚本resources/initialize/backend/src/core/agents/__init__.py246 B
- 脚本resources/initialize/backend/src/core/agents/base.py9.9 KB
- 脚本resources/initialize/backend/src/core/agents/factory.py4.3 KB
- 脚本resources/initialize/backend/src/core/auth.py2.4 KB
- 脚本resources/initialize/backend/src/core/validators/__init__.py127 B
- 脚本resources/initialize/backend/src/core/validators/general_agent.py833 B
- 脚本resources/initialize/backend/src/db/__init__.py1.1 KB
- 脚本resources/initialize/backend/src/db/connection.py3.9 KB
- 脚本resources/initialize/backend/src/db/models.py1.6 KB
- 脚本resources/initialize/backend/src/db/repositories.py1.7 KB
- 脚本resources/initialize/backend/src/db/repository.py2.3 KB
- 脚本resources/initialize/backend/src/helpers/__init__.py1.9 KB
- 脚本resources/initialize/backend/src/helpers/cors.py979 B
- 脚本resources/initialize/backend/src/helpers/date_utils.py2.0 KB
- 脚本resources/initialize/backend/src/helpers/error_handlers.py2.7 KB
- 脚本resources/initialize/backend/src/helpers/exceptions.py2.8 KB
- 脚本resources/initialize/backend/src/helpers/frontend_runner.py3.3 KB
- 脚本resources/initialize/backend/src/helpers/middleware.py3.2 KB
- 脚本resources/initialize/backend/src/helpers/nginx.py1.2 KB
- 脚本resources/initialize/backend/src/helpers/port_utils.py4.4 KB
- 脚本resources/initialize/backend/src/helpers/rate_limit.py1.8 KB
- 脚本resources/initialize/backend/src/helpers/retry.py3.0 KB
- 脚本resources/initialize/backend/src/helpers/tailscale.py6.7 KB
- 脚本resources/initialize/backend/src/providers/__init__.py487 B
- 脚本resources/initialize/backend/src/providers/email.py3.3 KB
- 脚本resources/initialize/backend/src/providers/google.py1.2 KB
- 脚本resources/initialize/backend/src/providers/llm/__init__.py190 B
- 脚本resources/initialize/backend/src/providers/llm/config.py1.4 KB
- 脚本resources/initialize/backend/src/providers/llm/model.py1.8 KB
- 脚本resources/initialize/backend/src/providers/proxy/manager.py4.6 KB
- 脚本resources/initialize/backend/src/routers/__init__.py315 B
- 脚本resources/initialize/backend/src/routers/agent.py1.1 KB
- 脚本resources/initialize/backend/src/routers/auth.py3.9 KB
- 脚本resources/initialize/backend/src/routers/dependencies.py1.3 KB
- 脚本resources/initialize/backend/src/schema/__init__.py1.1 KB
- 脚本resources/initialize/backend/src/schema/agent.py1.7 KB
- 脚本resources/initialize/backend/src/schema/auth.py1.9 KB
- 脚本resources/initialize/backend/src/schema/common.py1.3 KB
- 脚本resources/initialize/backend/src/services/__init__.py187 B
- 脚本resources/initialize/backend/src/services/agent.py1.6 KB
- 脚本resources/initialize/backend/src/services/auth.py6.7 KB
- 脚本resources/initialize/backend/tests/__init__.py29 B
- 脚本resources/initialize/backend/tests/conftest.py1.5 KB
- 脚本resources/initialize/backend/tests/core/__init__.py1 B
- 脚本resources/initialize/backend/tests/core/test_agent.py4.9 KB
- 脚本resources/initialize/backend/tests/core/test_auth.py6.4 KB
- 脚本resources/initialize/backend/tests/core/test_factory.py5.5 KB
- 脚本resources/initialize/backend/tests/helpers/test_tailscale.py3.6 KB
- 脚本resources/initialize/backend/tests/routers/__init__.py—
- 脚本resources/initialize/backend/tests/routers/test_agent.py3.6 KB
- 脚本resources/initialize/backend/tests/routers/test_auth.py14.5 KB
- 脚本resources/initialize/backend/tests/services/__init__.py—
- 脚本resources/initialize/backend/tests/services/test_agent.py2.0 KB
- 脚本resources/initialize/backend/tests/services/test_auth.py13.5 KB
- 脚本resources/initialize/backend/tests/test_health.py634 B
- 脚本resources/initialize/backend/tests/test_llm_provider.py2.3 KB
- 脚本resources/initialize/backend/tests/test_proxy_manager.py1.1 KB
- 参考文档resources/initialize/frontend/templates/chrome-extension/components.json524 B
- 参考文档resources/initialize/frontend/templates/chrome-extension/manifest.json791 B
- 参考文档resources/initialize/frontend/templates/chrome-extension/options.html318 B
- 参考文档resources/initialize/frontend/templates/chrome-extension/package.json875 B
- 参考文档resources/initialize/frontend/templates/chrome-extension/panel.html315 B
- 参考文档resources/initialize/frontend/templates/chrome-extension/popup.html314 B
- 脚本resources/initialize/frontend/templates/chrome-extension/setup.py12.1 KB
- 参考文档resources/initialize/frontend/templates/chrome-extension/sidepanel.html323 B
- 脚本resources/initialize/frontend/templates/chrome-extension/src/background/index.ts2.0 KB
- 其他resources/initialize/frontend/templates/chrome-extension/src/components/layout/theme-provider.tsx581 B
- 其他resources/initialize/frontend/templates/chrome-extension/src/components/layout/user-menu.tsx15.1 KB
- 脚本resources/initialize/frontend/templates/chrome-extension/src/content/index.ts2.5 KB
- 其他resources/initialize/frontend/templates/chrome-extension/src/entry/options/App.tsx5.4 KB
- 其他resources/initialize/frontend/templates/chrome-extension/src/entry/options/main.tsx245 B
- 其他resources/initialize/frontend/templates/chrome-extension/src/entry/panel/App.tsx15.9 KB
- 其他resources/initialize/frontend/templates/chrome-extension/src/entry/panel/main.tsx239 B
- 其他resources/initialize/frontend/templates/chrome-extension/src/entry/popup/App.tsx5.7 KB
- 其他resources/initialize/frontend/templates/chrome-extension/src/entry/popup/main.tsx245 B
- 其他resources/initialize/frontend/templates/chrome-extension/src/entry/sidepanel/App.tsx5.5 KB
- 其他resources/initialize/frontend/templates/chrome-extension/src/entry/sidepanel/main.tsx245 B
- 脚本resources/initialize/frontend/templates/chrome-extension/src/hooks/use-chrome-storage.ts1.8 KB
- 脚本resources/initialize/frontend/templates/chrome-extension/src/lib/utils.ts169 B
- 其他resources/initialize/frontend/templates/chrome-extension/src/styles/globals.css21.6 KB
- 参考文档resources/initialize/frontend/templates/chrome-extension/tsconfig.json624 B
- 脚本resources/initialize/frontend/templates/chrome-extension/vite.config.ts1.2 KB
- 其他resources/initialize/frontend/templates/frontend/.gitignore32 B
- 其他resources/initialize/frontend/templates/frontend/app/(app)/layout.tsx615 B
- 其他resources/initialize/frontend/templates/frontend/app/(auth)/layout.tsx560 B
- 其他resources/initialize/frontend/templates/frontend/app/(auth)/login/page.tsx334 B
- 其他resources/initialize/frontend/templates/frontend/app/(public)/layout.tsx231 B
- 其他resources/initialize/frontend/templates/frontend/app/(public)/page.tsx488 B
- 其他resources/initialize/frontend/templates/frontend/app/layout.tsx3.3 KB
- 其他resources/initialize/frontend/templates/frontend/app/not-found.tsx1.2 KB
- 参考文档resources/initialize/frontend/templates/frontend/components.json520 B
- 其他resources/initialize/frontend/templates/frontend/components/auth/login-form.tsx9.3 KB
- 其他resources/initialize/frontend/templates/frontend/components/layout/app-shell.tsx1.4 KB
- 其他resources/initialize/frontend/templates/frontend/components/layout/header.tsx1.0 KB
- 其他resources/initialize/frontend/templates/frontend/components/layout/login-modal.tsx10.6 KB
- 其他resources/initialize/frontend/templates/frontend/components/layout/navbar.tsx2.8 KB
- 其他resources/initialize/frontend/templates/frontend/components/layout/sidebar.tsx10.4 KB
- 其他resources/initialize/frontend/templates/frontend/components/layout/theme.tsx6.6 KB
- 其他resources/initialize/frontend/templates/frontend/components/layout/toast.tsx4.0 KB
- 其他resources/initialize/frontend/templates/frontend/components/layout/user-menu.tsx22.5 KB
- 其他resources/initialize/frontend/templates/frontend/components/ui/dropdown-menu.tsx8.9 KB
- 其他resources/initialize/frontend/templates/frontend/globals.css20.8 KB
- 脚本resources/initialize/frontend/templates/frontend/hooks/use-auth.ts1.6 KB
- 脚本resources/initialize/frontend/templates/frontend/hooks/use-sidebar.ts1.9 KB
- 脚本resources/initialize/frontend/templates/frontend/lib/api.ts3.6 KB
- 脚本resources/initialize/frontend/templates/frontend/lib/sse.ts1.9 KB
- 脚本resources/initialize/frontend/templates/frontend/lib/utils.ts373 B
- 脚本resources/initialize/frontend/templates/frontend/next.config.ts1.1 KB
- 参考文档resources/initialize/frontend/templates/frontend/package.json454 B
- 脚本resources/initialize/frontend/templates/frontend/scripts/generate-types.sh946 B
- 脚本resources/initialize/frontend/templates/frontend/setup.py21.2 KB
- 参考文档resources/initialize/frontend/templates/frontend/tsconfig.json357 B
- 参考文档resources/scaffold-ui.md20.2 KB
- 脚本scripts/bootstrap.py2.4 KB
- 脚本scripts/setui.py12.5 KB
03 SKILL.md 正文
Scaffold Project
"One command. Full-stack production architecture."
Initializes a complete, production-ready full-stack application from scratch:
- Backend (
bootstraptool): FastAPI entrypoint, configuration layer, helpers, SQLite/SQLAlchemy database layer, auth system with scoped JWTs, intelligent agent lifecycle & validators, and standard agent rules. - Frontend (
setuitool): Complete Next.js + Tailwind + shadcn/ui frontend (web/) or React + Vite Chrome Extension (extension/) with 11 built-in themes and AI design system generation viaui-ux-pro-max.
How to Use
1. Scaffold Backend Skeleton (bootstrap)
Initializes the complete backend architecture into an empty project directory:
human-skills '{
"tool_name": "bootstrap",
"tool_args": {
"destination": "/path/to/new_project"
}
}'
Or via direct curl (no dependencies):
curl -sSL https://raw.githubusercontent.com/mdnaimul22/human-skills/main/skills/storage/my_skills/scaffold-project/resources/initialize/backend/bootstrap.py | python3
2. Scaffold Frontend Client (setui)
Scaffold a Next.js web application (web/) or React Chrome Extension (extension/) inside the project root:
# Basic Next.js frontend (web/)
human-skills '{
"tool_name": "setui",
"tool_args": {
"destination": "/path/to/new_project"
}
}'
# With AI Design System generation (ui-ux-pro-max)
human-skills '{
"tool_name": "setui",
"tool_args": {
"destination": "/path/to/new_project",
"action": "frontend",
"design_query": "beauty spa wellness premium",
"density": 5,
"motion": 6
}
}'
# React + Vite Chrome Extension (extension/)
human-skills '{
"tool_name": "setui",
"tool_args": {
"destination": "/path/to/new_project",
"action": "chrome-extension",
"design_query": "developer productivity dashboard"
}
}'
Full-Stack Project Structure
When both backend and frontend are scaffolded:
project_root/
├── main.py ← FastAPI entry point with auto-kill, health check, lifespan
├── .env ← Environment variables (fill from .env.example)
├── .env.example ← Template for required env vars
├── .models.example ← Template for AI model providers
├── .gitignore ← Pre-configured for Python, Node, and secrets
├── README.md
├── LICENSE ← MIT License
├── docs/ ← Documentation & generated brand guidelines
├── logs/ ← Layer-based rotating logs
├── deploy/nginx/ ← Production Nginx configuration templates
│
├── .agents/rules/ ← Permanent coding standards synced from human-skills
│ ├── coding-standards.md
│ ├── architecture-patterns.md
│ ├── maintenance-testing.md
│ ├── config-path-rules.md
│ ├── config-usage-rules.md
│ ├── helpers-usage-rules.md
│ ├── project-config-example.md
│ ├── project-tree-example.md
│ └── common-git-workflow.md
│
├── src/ ← Backend application core
│ ├── config/ ← Settings, env, sandboxed file I/O, hierarchical dual logger
│ ├── db/ ← SQLAlchemy async engine, OwnershipMixin, models, repositories
│ ├── helpers/ ← Rate limiting, exceptions, date utils, port kill switch, tailscale
│ ├── core/ ← Business logic, password hashing, scoped JWTs, intelligent agents
│ │ ├── agents/ ← BaseAgent, AgentFactory, GeneralAgent lifecycle
│ │ └── validators/ ← Domain invariant pipeline
│ ├── providers/ ← External integrations (Email, Google OAuth, LLM rotator, proxy)
│ ├── schema/ ← Pydantic contracts (auth, common envelopes, agent protocols)
│ ├── services/ ← Fan-in use-case orchestration (AuthService, AgentService)
│ └── routers/ ← HTTP endpoints & auth dependencies (/api/auth, /api/agent)
│
├── tests/ ← Modular test suite (128 passing tests out-of-the-box)
│ ├── core/
│ ├── routers/
│ ├── services/
│ └── helpers/
│
└── web/ ← Next.js frontend (scaffolded via setui)
├── src/
│ ├── app/ ← App router (layout, globals.css with 11 themes, auth pages)
│ ├── components/ ← shadcn/ui components (30+ auto-installed), layout, navbar, sidebar
│ ├── lib/ ← Type-safe FastAPI client (api.ts with JWT Bearer & 422 parsing)
│ └── hooks/ ← State management (use-sidebar, use-auth with Zustand persist)
├── components.json
├── tailwind.config.ts
└── package.json
Built-in Auth System
The scaffold ships with a production-grade authentication system out of the box:
Auth Endpoints
| Method | Endpoint | Auth | Purpose |
|---|---|---|---|
POST |
/api/auth/register |
❌ | Email signup → sends verification email |
GET |
/api/auth/verify-email |
❌ | Verify email via token in query |
POST |
/api/auth/login |
❌ | Email/password login → access + refresh tokens |
POST |
/api/auth/google |
❌ | Google OAuth login/signup |
POST |
/api/auth/refresh |
❌ | Rotate access + refresh tokens |
POST |
/api/auth/forgot-password |
❌ | Request password reset email |
POST |
/api/auth/reset-password |
❌ | Reset password with token |
POST |
/api/auth/change-password |
✅ | Change password (authenticated) |
GET |
/api/auth/me |
✅ | Get current user profile |
PATCH |
/api/auth/me |
✅ | Update profile (name) |
POST |
/api/auth/logout |
✅ | Client-side token clear guidance |
Scoped JWT Tokens
| Purpose | Expiry | Usage |
|---|---|---|
access |
15 minutes | API Authorization header (Bearer <token>) |
refresh |
7 days | POST /api/auth/refresh only |
verify_email |
24 hours | Email verification link |
reset_password |
1 hour | Password reset link |
User ↔ Service Data Ownership
Use OwnershipMixin for any model that belongs to a user:
from src.db import Base, TimestampMixin, OwnershipMixin
class Post(Base, TimestampMixin, OwnershipMixin):
__tablename__ = "posts"
id: Mapped[str] = mapped_column(String(32), primary_key=True, default=_uuid)
title: Mapped[str] = mapped_column(String(200), nullable=False)
BaseRepository provides list_by_owner(user_id) and count_by_owner(user_id) for scoped queries to prevent IDOR attacks.
Intelligent Agent Architecture
The scaffold includes a production agent framework in src/core/agents:
- BaseAgent: Abstract base with streaming, retry, and execution lifecycle.
- AgentFactory: Configuration-driven agent instantiation.
- Domain Validators: Invariant validation pipeline in
src/core/validators. - Agent Router: HTTP interface at
/api/agent/runwith authentication guards.
Frontend Architecture (setui)
- 11 Curated Themes: Default, Dark, Slate, Neon, Ocean, Cyberpunk, Velvet, Sunset, Forest, Luxury, Custom AI.
- shadcn/ui Suite: 30+ pre-configured UI primitives with zero manual initialization needed.
- FastAPI Client (
src/lib/api.ts): Built-in JWT Bearer header injection, timeout protection, and Pydantic 422 error unpacking. - Design Intelligence: Passing
design_queryauto-generates brand guidelines (docs/brand-guidelines.md), design tokens (design-tokens.json), and typography pairings.
For comprehensive UI details, see [scaffold-ui.md](file:///home/naimul/human-skills/skills/storage/my_skills/scaffold-project/resources/scaffold-ui.md).
Post-Bootstrap Checklist
- [ ] Copy
.env.example→.envand fill mandatory fields - [ ] Set
JWT_SECRETto a strong random value for production - [ ] Configure SMTP settings for email verification/password reset
- [ ] (Optional) Set
GOOGLE_CLIENT_IDfor Google OAuth - [ ] Run backend:
python3 main.py(auto-kills orphaned processes on port 8000) - [ ] Run frontend:
cd web && npm run dev(connects to backend athttp://localhost:8000)
04 同仓库更多 Skills
system-lifecycle-designer
Universal architectural methodology for designing granular, atomic, and sub-atomic lifecycles and end-to-end workflows for single functionality integrations across any domain (daemons, batch jobs, request transactions, resource pools). Provides patterns for deterministic identity, pre-commit validation, differential reconciliation, sticky leasing, state machines, transactional persistence, and closed-loop feedback.
style-sampling
Make a new episode in a proven video style - Collage Explainer, Finance Explainer, Animated Science Explainer, 3D Brand Explainer, 3D True Crime - on the person's topic. Use for "an episode of", "in the style of", "sample this style", 「用这个风格做一集」. One video to copy is reverse-any-video.
reverse-any-video
Rebuild any video file as an editable HyperFrames project - motion graphics, talking heads, live action or AI-generated footage - checked against the original frame by frame. Use to reverse, recreate, remake, replicate or copy a video, or 「复刻这个视频」「照着这个视频做一个」.
typescript-patterns
TypeScript patterns for strict, type-safe, maintainable code in modern TypeScript and JavaScript applications. Covers strict compiler configuration, type design, narrowing, discriminated unions, generics, async and error handling, module boundaries, dependency hygiene, and type-level testing. Use when writing or reviewing TypeScript or JavaScript code.
test-collaboration
Inventory and govern a project's test assets. Connect requirements, business rules, risks, bugs, and cross-boundary contracts to stable TEST-IDs and executable evidence in the repository's existing test registry or TESTS.md. Use for test inventory, test gap analysis, unit/integration/contract/E2E/smoke classification, bug-to-test regression protection, consumer/provider contract testing, test-necessity review, and pre-delivery evidence review.
story-lifecycle
Manage a file-based epic → story → sprint development loop without requiring an external project management tool. Creates and tracks epics, breaks them into user stories, assigns them to sprints, and drives implementation story by story. Use when starting a new feature initiative or when the team has no Jira/Linear/Taiga but needs structured delivery tracking.