全栈锻造 · FullStack Forge v1.0

把一句需求，经 9 个阶段、多智能体协作 + 独立质检 + 对抗评审，产出可一键 Docker 部署的工业级全栈网站。

技术栈（固定）：React 19 + Vite + TypeScript（前端）· NestJS 11 + TypeScript（后端）· PostgreSQL 16 + Prisma ORM（数据库）· Docker / docker-compose（部署）。

版本与环境

• 当前版本: v1.0.0 · 更新日志 <skill>/CHANGELOG.md
• 环境自检: 开工时先运行 node <skill>/scripts/doctor.js 验证 Node/npm/Docker/端口可用性，失败项必须先修复再进入阶段 0。
• 命令约定: 命令行显式用 node、npm；Windows 环境下用 pwsh 执行。
• Skill 根目录: <skill> = 本 skill 包所在目录（SKILL.md 的父目录）。

路径解析协议

何时用哪种执行方式

• 主流水线：用 workflow 工具跑 <skill>/workflows/fullstack-build.js（阶段 0→9 编排 + 门禁派发 + 状态落盘）。
• 独立质检 Subagent：R1/A1/D1/B1/F1/S1/T1/O1 门禁由工作流派发只读质检 subagent；不在工作流内执行时由主 Agent 派发，规则见"Subagent 质检协议"。
• 对抗评审：阶段 9 跑 <skill>/workflows/adversarial-review.js（三角色并行打分，加权聚合，≤3 轮）。
• 用户明确要"多智能体/工作流/对抗"或说触发词时启动 Workflow；小改动（修 bug、加个字段）按手册直接干，不跑全流水线。

⛔ 强制流程门禁（不允许跳步）

这是硬性约束，优先级高于一切效率考量。必须严格按阶段 0→1→2→3→4→5→6→7→8→9 顺序执行，禁止跳过、合并、颠倒任何阶段。

核心规则

1. 每阶段三步骤：执行 → 验证 → 确认。验证不通过不得进入下一阶段。
2. 落盘即证据：每阶段产出必须写入对应文件/目录，产出不存在 = 该阶段未完成。
3. 状态持久化：每阶段开始前读 <proj>/state/decision_log.json，完成后写入决策记录；流水线中断后可恢复。
4. 禁止心算跳过：不允许因"这网站简单""安全后面再补"而略过任何阶段——安全（阶段 6）与测试（阶段 7）是硬阶段。
5. 任务跟踪：开工建 10 个任务（阶段 0–9），任一时刻只允许一个阶段 in_progress。
6. 需求结论贯穿全流程：阶段 1 的审析报告是"宪法"——架构必须引用它、API 必须覆盖每个验收标准、安全必须回应每个风险点。
7. API 契约先行：阶段 2 必须产出 OpenAPI 契约与数据模型草案，后端（阶段 4）与前端（阶段 5）以此为准并行推进。
8. 安全不可后补：阶段 6 是独立硬阶段；认证授权（JWT+refresh+RSA/argon2、RBAC）、helmet、限流、审计日志从阶段 4 起就是代码的一部分，阶段 6 负责系统性加固与独立审计。
9. Subagent 质检不可省：9 道门禁必须逐道通过，主 Agent 自检不能替代 Subagent 独立验收。
10. ⛔ 反模式是硬阻断：AP1/AP2/AP3 门禁中任何 High 级命中 → 必须退回修复，不得携带 High 反模式进入下一阶段。
11. ⛔ 人工在环不可省：H1/H2/H3 检查点必须暂停呈现关键产物给用户确认。

阶段依赖链

0 脚手架+环境自检 → 1 需求审析 REPORT.md§1 [R1+🛑H1]
  → 2 架构选型 REPORT.md§2 + OpenAPI 契约 [A1]
  → 3 数据建模 prisma/schema.prisma + 迁移 [D1]
  → 4 后端实现 backend/ [B1 + AP1]
  → 5 前端实现 frontend/ [F1 + AP2]      （4/5 依据阶段 2 契约可并行）
  → 6 安全加固 [S1 + AP3 ⛔硬阻断] [🛑H2]
  → 7 测试 [T1]
  → 8 Docker 部署配置 [O1]
  → 9 三角色对抗评审 [W1 评分≥8.0] [🛑H3] → 终版

Subagent 质检协议（9 道门禁）

角色分离原则：写代码的 Agent 不能同时质检自己的产出。质检 Subagent 必须是独立的只读实例。

九道门禁

质检规则

1. 派发时机：每道门禁在其触发阶段产物落盘后立即派发。
2. 只读质检：质检 Subagent 只能读取产物、返回评估报告，不得修改文件。
3. FAIL 回溯：任一门禁 FAIL → 退回对应阶段按证据修正 → 重新派发复验。已通过的后续门禁在相关产物变化后自动失效。
4. PASS 签名：PASS 结果含 Subagent ID + 时间戳 + 检查摘要，写入 REPORT.md 附录与 state/decision_log.json。
5. 不可跳过：环境不支持 Subagent 时记为 BLOCKED，不得谎称通过。
6. ⛔ S1/W1 是硬阻断：安全门禁 S1 任何 High 级安全反模式（AP3）命中、终版评审均分 < 8.0 → 必须退回修复。

⛔ 反模式硬阻断（AP1/AP2/AP3）

反模式知识库见 references/09-anti-patterns.md（36+ 条，按 High/Medium/Low 分级，含唯一编号、识别特征、危害、修复方案）。

High 级反模式示例：硬编码密钥、SQL 拼接、密码明文/弱哈希、token 存 localStorage、CORS 全开、无限流、无输入校验、dangerouslySetInnerHTML 注入用户输入、日志泄漏敏感信息、无审计日志。

🛑 人工在环检查点（H1/H2/H3）

AI 不是产品经理也不是安全专家——它在以下节点必须暂停，把关键产物呈现给用户做"合理性 sniff test"。

执行规则：

• 人工检查点不可跳过。用户不在时（异步运行），将产物 + 确认问题写入 state/human_checkpoint.md，标记 AWAITING_HUMAN，暂停流水线。
• 用户确认（或给出修改指示）后，记录确认结果和时间戳到 state/decision_log.json。
• 人工确认不等同于质检——Subagent 质检仍须独立执行。

对抗评审协议（阶段 9）

三个评审角色并行批改同一份站点——架构师看系统设计，安全专家看攻击面，代码质量专家看可维护性。写作者（项目 Agent）逐条修改后三评审重新打分，加权均分 < 8.0 继续改，最多 3 轮。

评分规则：五维度（功能完整性/安全性/性能/可维护性/文档）各 10 分；加权聚合 = Σ(角色均分 × 权重)；任一维度 < 6.0 触发硬上限直接判 FAIL；三角色分差 > 2.5 时触发仲裁（追加一轮 ff-reasoner 复核）。评分记录写入 state/review_log.json。

各阶段执行与验证

阶段 0：脚手架 + 环境自检

• 运行 node <skill>/scripts/doctor.js；建项目目录：<proj>/{REPORT.md, backend/, frontend/, docs/, prisma/, state/, .env.example, .gitignore, README.md}
• 初始化 backend（NestJS）与 frontend（Vite React-TS）骨架，git init（如无）
• 验证：doctor 全绿；目录完整；.gitignore 已排除 .env、node_modules、dist

阶段 1：需求审析（参考 01-requirements-analysis.md）

• 逐条挖功能需求/非功能需求/约束/风险；用户故事 + 验收标准（AC）；范围边界（明确"不做什么"）
• 产出 REPORT.md §1（≥1500 字，含需求清单表、用户故事、AC、风险清单、问题待确认项）
• 验证：8 项需求完整性检查（见手册质检要点）→ R1 独立质检 → 🛑H1 人工确认

阶段 2：架构选型（参考 02-architecture-selection.md）

• 分层设计、NestJS 模块划分、认证授权方案（JWT access 15min + refresh 7d 轮换 + RBAC）、API 契约
• 产出 REPORT.md §2 + docs/openapi.yaml（OpenAPI 3.1）+ ER 草案
• 验证：7 项架构合理性检查 → A1 独立质检

阶段 3：数据建模（参考 03-data-modeling.md）

• Prisma schema：类型选型、唯一约束、索引策略、审计字段（createdAt/updatedAt）、枚举状态机、级联策略
• 产出 prisma/schema.prisma + 首个迁移 SQL + seed 脚本
• 验证：8 项建模规范检查 → D1 独立质检

阶段 4：后端实现（参考 04-backend-engineering.md）

• NestJS 模块化：认证（argon2 + JWT + refresh 轮换 + httpOnly cookie）、RBAC Guard、DTO+ValidationPipe、审计日志拦截器、限流、Swagger、统一错误格式、结构化日志
• 验证：npm run build 通过 + 规范 8 项 → B1 → AP1 反模式硬阻断

阶段 5：前端实现（参考 05-frontend-engineering.md）

• React 19：路由守卫、401 自动刷新、zod 表单校验、错误边界、加载/空/错误三态、a11y、性能预算、Tailwind
• 验证：tsc --noEmit + vite build 通过 + 规范 8 项 → F1 → AP2 反模式硬阻断

阶段 6：安全加固（参考 06-security-hardening.md）⛔

• OWASP Top 10 逐条落地：helmet 安全头、CORS 白名单、CSRF 防护、限流+登录锁定、参数化查询确认、密钥管理审计、npm audit 依赖扫描、审计日志完整性、错误不泄漏细节
• 产出 REPORT.md §6 安全加固报告（含逐条对照表 + 残余风险）
• 验证：S1 安全清单 10 项 → S1 + AP3 ⛔硬阻断 → 🛑H2 人工确认

阶段 7：测试（参考 07-testing-gates.md）

• 后端：单元测试 + e2e（supertest），必须含安全用例（未认证 401、越权 403、注入、暴力破解限流、CSRF）
• 前端：vitest 关键组件 + tsc --noEmit + vite build
• 产出 REPORT.md §7 测试报告（用例清单 + 结果 + 覆盖率摘要）
• 验证：全绿 → T1 独立质检

阶段 8：部署（参考 08-deployment-ops.md）

• Dockerfile×2（多阶段构建、非 root、HEALTHCHECK）+ docker-compose.yml（postgres+backend+frontend/nginx）+ 迁移执行策略 + 备份说明 + CI 建议
• 产出 README.md 部署文档 + .env.example 完整化
• 验证：docker compose config 合法 + 8 项就绪检查 → O1 独立质检

阶段 9：对抗评审 → 终版

• 跑 workflows/adversarial-review.js：三角色并行打分 → 加权聚合 → 退回修改（≤3 轮）
• 验证：加权均分 ≥ 8.0 → W1 → 🛑H3 人工确认 → 终版

状态协议（state/decision_log.json）

{
  "project": "<项目名>",
  "stages": { "0": {"status": "completed", "gate": "PASS", "ts": "ISO8601"}, "1": {...} },
  "gates": [ {"id": "R1", "subagentId": "...", "verdict": "PASS", "ts": "...", "summary": "..."} ],
  "review_rounds": 0,
  "human_checkpoints": [ {"id": "H1", "status": "CONFIRMED", "ts": "..."} ],
  "decisions": [ {"stage": "2", "decision": "...", "reason": "..."} ],
  "resume_point": "stage_5"
}

每阶段开始前必读、完成后必写；resume_point 让流水线在任意中断处恢复，重跑已通过阶段是允许的（幂等），但跳阶段永远禁止。

验收终态（何为"工业级"）

1. docker compose up -d 一条命令起全站，/health 返回 200
2. 认证闭环：注册 → 登录（argon2 + JWT access/refresh + httpOnly cookie）→ RBAC 越权被 403 拦截
3. OWASP Top 10 全覆盖有证据（阶段 6 报告逐条对照 + 安全 e2e 用例全绿）
4. npm audit 0 高危；密钥零泄漏（git grep 验证无 .env 内容入库）
5. 结构化审计日志记录登录/敏感操作；限流与登录锁定生效
6. 前端类型检查 + 构建全绿；后端构建 + 单测 + e2e 全绿
7. 三评审加权均分 ≥ 8.0，评分与修改记录可追溯
8. 状态日志、门禁签名、人工确认记录完整——整个产出过程可审计