skill/fullstack-task/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: fullstack-task
+description: 辅助 AI 完成全栈开发任务，包括需求拆解、技术选型、前后端实现、数据库设计、API 设计、测试、部署与验收。当用户要求开发功能、修复全栈 bug、设计接口、写数据库模型、做代码审查、搭建项目或交付一个可运行的端到端功能时使用本 skill。
+---
+
+# 全栈任务助手
+
+## 何时使用
+
+在以下场景加载本 skill：
+
+- 用户要求“实现一个功能”且涉及前端 + 后端
+- 用户要求设计 API、数据库模型、组件结构
+- 用户要求从零搭建项目或脚手架
+- 用户要求排查跨层 bug（前端 → API → DB）
+- 用户要求代码审查、重构、性能优化
+- 用户要求生成可运行的端到端交付物
+
+## 核心原则
+
+1. **先澄清，再动手**：需求模糊时必须先确认范围、约束、验收标准。
+2. **端到端思考**：任何功能都要同时考虑 UI、API、数据、错误、测试、部署。
+3. **最小可用优先**：先跑通主链路，再优化扩展性和性能。
+4. **显式优于隐式**：类型、契约、边界、错误码必须明确。
+5. **可运行即交付**：给出的代码要能跑，不能是伪代码，除非用户明确要求。
+6. **不臆造**：不确定的库版本、API 行为、字段名，要标注或询问。
+
+## 工作流程
+
+### 第 1 步：需求拆解
+
+输出一份简短 spec，包含：
+
+- 目标：这个功能解决什么问题
+- 用户故事：谁在什么场景下做什么
+- 范围：做什么 / 不做什么
+- 验收标准：可测试的条目
+- 约束：技术栈、兼容性、性能、时间
+
+如果信息不足，最多问 3 个关键问题，其余用合理默认值并标注。
+
+### 第 2 步：技术方案
+
+按需确定：
+
+- 技术栈：参考 `references/stack-defaults.md`
+- 数据模型：实体、字段、关系、索引
+- API 契约：路径、方法、请求、响应、错误码
+- 前端结构：页面、组件、状态、数据获取方式
+- 部署方式：环境变量、构建、托管
+
+### 第 3 步：任务拆分
+
+拆成可独立验证的任务，每个任务：
+
+- 有明确输入输出
+- 有验收方式
+- 尽量 30 分钟内可完成
+- 标注依赖顺序
+
+### 第 4 步：实现
+
+按 `数据 → API → 前端 → 联调` 的顺序推进。
+
+实现要求：
+
+- 类型完整，避免 `any`
+- 错误处理明确
+- 输入校验（前后端都做）
+- 环境变量集中管理
+- 不硬编码密钥
+- 关键路径加日志
+- 命名清晰，避免缩写
+
+### 第 5 步：验证
+
+至少覆盖：
+
+- 主链路可跑通
+- 边界：空值、超长、非法输入、并发
+- 错误：网络失败、DB 失败、权限不足
+- 构建：`build` / `lint` / `typecheck` 通过
+- 测试：关键逻辑有单测，主链路有集成测试
+
+### 第 6 步：交付
+
+输出：
+
+- 变更文件清单
+- 运行方式
+- 环境变量说明
+- 已知限制
+- 后续建议
+
+## 参考文档
+
+按需加载，不要一次性全读：
+
+- `references/stack-defaults.md`：默认技术栈与选型
+- `references/api-design.md`：REST / RPC 设计规范
+- `references/database.md`：模型、迁移、索引、事务
+- `references/frontend.md`：组件、状态、数据获取、可访问性
+- `references/testing.md`：测试策略与用例模板
+
+## 模板
+
+- `templates/feature-spec.md`：功能 spec 模板
+- `templates/pr-checklist.md`：PR 自检清单
+
+## 检查清单
+
+交付前必须自查：
+
+- [ ] 需求有明确验收标准
+- [ ] 数据模型有主键、索引、时间戳
+- [ ] API 有输入校验和错误码
+- [ ] 前端有加载态、空态、错误态
+- [ ] 敏感信息走环境变量
+- [ ] 主链路可端到端跑通
+- [ ] 构建、lint、typecheck 通过
+- [ ] 有最小测试覆盖
+- [ ] README 或交付说明完整
+
+## 反模式
+
+避免以下行为：
+
+- 直接写代码不澄清需求
+- 一次改动跨太多模块，难以 review
+- 前端和后端契约不一致
+- 忽略错误态和边界
+- 把密钥写进代码
+- 只测 happy path
+- 交付无法运行的片段
+- 编造不存在的 API 或字段
+
+## 输出风格
+
+- 中文为主，术语保留英文
+- 先结论后细节
+- 代码块标注语言
+- 长任务分阶段汇报
+- 不确定处显式标注 `[待确认]`

skill/fullstack-task/references/api-design.md

@@ -0,0 +1,55 @@
+# API 设计规范
+
+## 风格
+
+- 默认 REST
+- 复杂查询可用 RPC 风格
+- 内部服务可用 tRPC
+
+## 路径
+
+- 资源用复数：`/api/posts`
+- 嵌套不超过两层：`/api/posts/:id/comments`
+- 动作用子资源或 POST：`/api/posts/:id/publish`
+
+## 方法
+
+- GET 查询
+- POST 创建
+- PATCH 局部更新
+- PUT 全量替换
+- DELETE 删除
+
+## 请求
+
+- Body 用 JSON
+- 分页：`?page=1&pageSize=20` 或 cursor
+- 排序：`?sort=-createdAt`
+- 过滤：`?status=published&tag=nextjs`
+
+## 响应
+
+成功：
+
+```json
+{ "data": { ... }, "meta": { ... } }
+```
+
+## 状态码
+
+- 200 -> 成功
+- 201 -> 创建成功
+- 204 -> 删除成功
+- 400 -> 参数错误
+- 401 -> 未登录
+- 403 -> 无权限
+- 404 -> 不存在
+- 409 -> 冲突
+- 422 -> 业务校验失败
+- 500 -> 服务器错误
+
+## 校验
+
+- 所有输入用 Zod 校验
+
+- 错误信息可读，不暴露内部细节

skill/fullstack-task/references/database.md

@@ -0,0 +1,46 @@
+---
+
+## references/database.md
+
+```markdown
+# 数据库设计规范
+
+## 通用字段
+
+- `id`：主键，cuid / uuid / 自增
+- `createdAt`：创建时间
+- `updatedAt`：更新时间
+- `deletedAt`：软删除（可选）
+
+## 建模
+
+- 先画实体关系，再写 schema
+- 一对多用外键
+- 多对多用关联表
+- 避免过宽表，必要时拆表
+
+## 索引
+
+- 外键加索引
+- 高频查询字段加索引
+- 复合索引注意顺序
+- 唯一约束用 unique
+
+## 迁移
+
+- 每次 schema 变更生成迁移文件
+- 迁移必须可回滚
+- 生产环境先备份
+
+## 事务
+
+- 多表写入用事务
+- 保持事务短小
+- 避免在事务里做网络请求
+
+## 查询
+
+- 避免 N+1
+- 列表接口必须分页
+- 大字段按需 select
+```

skill/fullstack-task/references/frontend.md

@@ -0,0 +1,43 @@
+# 前端规范
+
+## 组件
+
+- 一个组件一个职责
+- 展示组件与容器组件分离
+- props 用 TypeScript 定义
+- 避免超过 200 行，超出则拆
+
+## 状态
+
+- 局部状态用 useState
+- 跨组件用 Context 或状态库
+- 服务端状态用 TanStack Query
+- 避免把服务端数据放进全局 store
+
+## 数据获取
+
+- Next.js 优先 Server Components
+- 客户端请求要有 loading / error / empty
+- 请求失败要有重试或提示
+
+## 表单
+
+- React Hook Form + Zod
+- 前端校验 + 后端校验
+- 提交中禁用按钮
+- 错误定位到字段
+
+## 可访问性
+
+- 语义化标签
+- 图片有 alt
+- 表单有 label
+- 键盘可操作
+- 颜色对比度达标
+
+## 性能
+
+- 图片用 next/image
+- 路由级代码分割
+- 长列表虚拟化
+- 避免不必要的 re-render

skill/fullstack-task/references/stack-defaults.md

@@ -0,0 +1,39 @@
+# 默认技术栈
+
+除非用户指定，按以下默认值执行。
+
+## 前端
+
+- 框架：Next.js（App Router）或 React + Vite
+- 语言：TypeScript
+- 样式：Tailwind CSS
+- 状态：React 内置 + TanStack Query
+- 表单：React Hook Form + Zod
+
+## 后端
+
+- 运行时：Node.js
+- 框架：Next.js Route Handlers / Hono / Express
+- 校验：Zod
+- 鉴权：Session + HttpOnly Cookie，或 JWT
+- 日志：pino
+
+## 数据库
+
+- 默认：PostgreSQL
+- ORM：Prisma 或 Drizzle
+- 轻量场景：SQLite
+- 缓存：Redis（可选）
+
+## 部署
+
+- 前端 / 全栈：Vercel
+- 容器：Docker + Fly.io / Railway
+- 静态：Cloudflare Pages
+
+## 工具
+
+- 包管理：pnpm
+- Lint：ESLint + Prettier
+- 测试：Vitest + Playwright
+- CI：GitHub Actions

skill/fullstack-task/references/testing.md

@@ -0,0 +1,37 @@
+# 测试规范
+
+## 分层
+
+- 单元测试：纯函数、工具、校验
+- 集成测试：API、DB、服务
+- 端到端：主链路
+
+## 工具
+
+- Vitest：单元 + 集成
+- Playwright：端到端
+- MSW：mock 网络
+
+## 用例设计
+
+每个功能至少覆盖：
+
+- happy path
+- 空值 / 缺字段
+- 非法输入
+- 权限不足
+- 资源不存在
+- 并发或重复提交
+
+## 命名
+
+- describe("createPost", () => {
+- it("creates a post with valid input", ...)
+- it("rejects empty title", ...)
+- })
+
+## CI
+
+- push 触发 lint + typecheck + test
+- 主分支保护
+- 失败阻断合并

skill/fullstack-task/scripts/init-check.sh

@@ -0,0 +1,23 @@
+set -e
+
+echo "== 全栈项目自检 =="
+
+echo "[1/6] 检查 package.json"
+test -f package.json && echo "OK" || echo "缺少 package.json"
+
+echo "[2/6] 检查 .env.example"
+test -f .env.example && echo "OK" || echo "建议添加 .env.example"
+
+echo "[3/6] 检查 README"
+test -f README.md && echo "OK" || echo "缺少 README.md"
+
+echo "[4/6] 类型检查"
+pnpm tsc --noEmit || echo "类型检查失败"
+
+echo "[5/6] Lint"
+pnpm lint || echo "Lint 失败"
+
+echo "[6/6] 构建"
+pnpm build || echo "构建失败"
+
+echo "== 完成 =="

skill/fullstack-task/templates/feature-spec.md

@@ -0,0 +1,50 @@
+# 功能 Spec：<名称>
+
+## 目标
+
+<一句话说明>
+
+## 用户故事
+
+- 作为 <角色>，我希望 <行为>，以便 <价值>
+
+## 范围
+
+### 做
+
+- ...
+
+### 不做
+
+- ...
+
+## 验收标准
+
+- [ ] ...
+- [ ] ...
+
+## 数据模型
+
+| 字段 | 类型 | 说明 |
+| ---- | ---- | ---- |
+|      |      |      |
+
+## API
+
+| 方法 | 路径 | 说明 |
+| ---- | ---- | ---- |
+|      |      |      |
+
+## 前端
+
+- 页面：
+- 组件：
+- 状态：
+
+## 风险
+
+- ...
+
+## 任务拆分
+
+- [ ] ...

skill/fullstack-task/templates/pr-checklist.md

@@ -0,0 +1,13 @@
+# PR 自检清单
+
+- [ ] 需求有对应 spec 或 issue
+- [ ] 变更范围聚焦，无无关改动
+- [ ] 类型完整，无 any
+- [ ] 输入校验完整
+- [ ] 错误处理完整
+- [ ] 敏感信息走环境变量
+- [ ] 主链路手动验证通过
+- [ ] lint / typecheck / build 通过
+- [ ] 测试通过，新逻辑有测试
+- [ ] README 或注释已更新
+- [ ] 已知限制已说明