| name | fullstack-forge |
| description | 端到端全栈网站生成系统（DeepSeek Harness 专属）。v1.0：9 阶段强制流水线（需求审析→架构选型→数据建模→NestJS后端→React19前端→安全加固OWASP→测试→Docker部署→三角色对抗评审）+ 9 道独立质检门禁（R1/A1/D1/B1/F1/S1/T1/O1/W1）+ 反模式硬阻断（AP1/AP2/AP3）+ 人工在环检查点（H1/H2/H3）+ 状态持久化。多智能体对抗协作：需求分析师/架构师/后端工程师/前端工程师/安全专家/测试工程师/运维工程师 + 独立质检与三角色评审，产出前后端与安全均达工业级标准的全栈网站。当用户说"搭建网站""建网站""全栈开发""做网站""网站开发"/fullstack-forge，或描述一个网站需求时使用。 |
全栈锻造 · 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 的父目录）。
路径解析协议
| 类型 | 位置 | 示例 |
|---|
| skill 内通用 | <skill>/ 下相对路径 | references/06-security-hardening.md |
| 用户产物 | 项目根目录相对路径 | <proj>/REPORT.md, <proj>/backend/, <proj>/frontend/ |
| 状态持久化 | <proj>/state/decision_log.json | 每阶段必读必写 |
| 工作流脚本 | <skill>/workflows/*.js | 用 workflow 工具执行 |
何时用哪种执行方式
- 主流水线：用
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 顺序执行，禁止跳过、合并、颠倒任何阶段。
核心规则
- 每阶段三步骤：执行 → 验证 → 确认。验证不通过不得进入下一阶段。
- 落盘即证据：每阶段产出必须写入对应文件/目录，产出不存在 = 该阶段未完成。
- 状态持久化：每阶段开始前读
<proj>/state/decision_log.json，完成后写入决策记录；流水线中断后可恢复。
- 禁止心算跳过：不允许因"这网站简单""安全后面再补"而略过任何阶段——安全（阶段 6）与测试（阶段 7）是硬阶段。
- 任务跟踪：开工建 10 个任务（阶段 0–9），任一时刻只允许一个阶段 in_progress。
- 需求结论贯穿全流程：阶段 1 的审析报告是"宪法"——架构必须引用它、API 必须覆盖每个验收标准、安全必须回应每个风险点。
- API 契约先行：阶段 2 必须产出 OpenAPI 契约与数据模型草案，后端（阶段 4）与前端（阶段 5）以此为准并行推进。
- 安全不可后补：阶段 6 是独立硬阶段；认证授权（JWT+refresh+RSA/argon2、RBAC）、helmet、限流、审计日志从阶段 4 起就是代码的一部分，阶段 6 负责系统性加固与独立审计。
- Subagent 质检不可省：9 道门禁必须逐道通过，主 Agent 自检不能替代 Subagent 独立验收。
- ⛔ 反模式是硬阻断：AP1/AP2/AP3 门禁中任何 High 级命中 → 必须退回修复，不得携带 High 反模式进入下一阶段。
- ⛔ 人工在环不可省：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 必须是独立的只读实例。
九道门禁
| 门禁 | 触发时机 | 被审产物 | 质检角色 | 通过标准 |
|---|
| R1 | 阶段 1 后 | REPORT.md §1 | ff-verifier | 需求完整性 8 项全部通过 |
| A1 | 阶段 2 后 | REPORT.md §2 + docs/openapi.yaml | ff-verifier | 架构合理性 7 项全部通过 |
| D1 | 阶段 3 后 | prisma/schema.prisma + 迁移 SQL | ff-verifier | 建模规范 8 项全部通过 |
| B1 | 阶段 4 后 | backend/ 全部代码 | ff-verifier | 代码可构建 + 规范 8 项 + 单测通过 |
| F1 | 阶段 5 后 | frontend/ 全部代码 | ff-verifier | 构建+类型检查通过 + 规范 8 项 |
| S1 | 阶段 6 后 | 全站安全配置 | ff-security-auditor | OWASP 全覆盖 + 安全清单 10 项（⛔） |
| T1 | 阶段 7 后 | 测试报告 | ff-verifier | e2e 全绿 + 安全用例全绿 + 构建全绿 |
| O1 | 阶段 8 后 | docker-compose.yml + Dockerfile×2 + 部署文档 | ff-verifier | 部署就绪 8 项全部通过 |
| W1 | 阶段 9 后 | 终版全站 | ff-reviewer | 三角色加权评分 ≥ 8.0（⛔） |
质检规则
- 派发时机：每道门禁在其触发阶段产物落盘后立即派发。
- 只读质检：质检 Subagent 只能读取产物、返回评估报告，不得修改文件。
- FAIL 回溯：任一门禁 FAIL → 退回对应阶段按证据修正 → 重新派发复验。已通过的后续门禁在相关产物变化后自动失效。
- PASS 签名：PASS 结果含 Subagent ID + 时间戳 + 检查摘要，写入
REPORT.md 附录与 state/decision_log.json。
- 不可跳过：环境不支持 Subagent 时记为 BLOCKED，不得谎称通过。
- ⛔ S1/W1 是硬阻断：安全门禁 S1 任何 High 级安全反模式（AP3）命中、终版评审均分 < 8.0 → 必须退回修复。
⛔ 反模式硬阻断（AP1/AP2/AP3）
反模式知识库见 references/09-anti-patterns.md（36+ 条，按 High/Medium/Low 分级，含唯一编号、识别特征、危害、修复方案）。
| 门禁 | 类别 | 触发时机 | 规则 |
|---|
| AP1 | 后端代码反模式 | 阶段 4 后（B1 通过后） | 任何 High 命中 → ⛔ 退回阶段 4 修复 |
| AP2 | 前端反模式 | 阶段 5 后（F1 通过后） | 任何 High 命中 → ⛔ 退回阶段 5 修复 |
| AP3 | 安全反模式 | 阶段 6 后（S1 中执行） | 任何 High 命中 → ⛔ 退回阶段 6 修复，不得进入阶段 7 |
High 级反模式示例：硬编码密钥、SQL 拼接、密码明文/弱哈希、token 存 localStorage、CORS 全开、无限流、无输入校验、dangerouslySetInnerHTML 注入用户输入、日志泄漏敏感信息、无审计日志。
🛑 人工在环检查点（H1/H2/H3）
AI 不是产品经理也不是安全专家——它在以下节点必须暂停，把关键产物呈现给用户做"合理性 sniff test"。
| 检查点 | 时机 | 暂停产物 | 确认问题 | 不通过处理 |
|---|
| 🛑H1 | 阶段 1 + R1 通过后 | §1 需求清单 + 范围边界 + 风险清单 | "功能范围是否对？有没有漏需求/过度设计？" | 用户纠正 → 更新 §1 → 重新 R1 |
| 🛑H2 | 阶段 6 + S1 通过后 | 安全加固摘要 + 认证流程说明 + 残余风险 | "认证/权限设计符合预期吗？数据敏感级别划分对吗？" | 用户指出问题 → 回阶段 6 修复 |
| 🛑H3 | 阶段 9 评审前 | 完整站点（运行中的 demo） | "整体印象是否达标？有无明显体验缺陷？" | 用户不满意 → 回对应阶段修改 |
执行规则：
- 人工检查点不可跳过。用户不在时（异步运行），将产物 + 确认问题写入
state/human_checkpoint.md，标记 AWAITING_HUMAN，暂停流水线。
- 用户确认（或给出修改指示）后，记录确认结果和时间戳到
state/decision_log.json。
- 人工确认不等同于质检——Subagent 质检仍须独立执行。
对抗评审协议（阶段 9）
三个评审角色并行批改同一份站点——架构师看系统设计，安全专家看攻击面，代码质量专家看可维护性。写作者（项目 Agent）逐条修改后三评审重新打分，加权均分 < 8.0 继续改，最多 3 轮。
| 角色 | 职责 | 权重 |
|---|
ff-arch-reviewer | 架构合理性：分层、模块边界、API 设计、数据模型 | 30% |
ff-security-reviewer | 安全：OWASP 覆盖、认证授权、密钥管理、攻击面 | 40% |
ff-quality-reviewer | 质量：可维护性、可读性、测试覆盖、错误处理、文档 | 30% |
评分规则：五维度（功能完整性/安全性/性能/可维护性/文档）各 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,
每阶段开始前必读、完成后必写；resume_point 让流水线在任意中断处恢复，重跑已通过阶段是允许的（幂等），但跳阶段永远禁止。
验收终态（何为"工业级"）
docker compose up -d 一条命令起全站，/health 返回 200- 认证闭环：注册 → 登录（argon2 + JWT access/refresh + httpOnly cookie）→ RBAC 越权被 403 拦截
- OWASP Top 10 全覆盖有证据（阶段 6 报告逐条对照 + 安全 e2e 用例全绿）
npm audit 0 高危；密钥零泄漏（git grep 验证无 .env 内容入库）- 结构化审计日志记录登录/敏感操作；限流与登录锁定生效
- 前端类型检查 + 构建全绿；后端构建 + 单测 + e2e 全绿
- 三评审加权均分 ≥ 8.0，评分与修改记录可追溯
- 状态日志、门禁签名、人工确认记录完整——整个产出过程可审计
