// docs / blueprint

项目蓝图

ProjectBlueprint 是整个系统的核心数据结构。用户的一句话 prompt 经过analyze_project_requirement 步骤后，被转化为这个结构化的蓝图；风格关键词还可由并行的 infer_design_intent 补强并写入后续规划。后续所有步骤都以归一化后的蓝图为输入。

整体结构

Blueprint 由三个顶层模块组成：

ProjectBlueprint {
  brief       → 产品定义（做什么、给谁用、核心能力）
  experience  → 设计意图（视觉风格、色彩方向、关键词）
  site        → 站点蓝图（信息架构、页面列表、section 规格）
}

Brief 层

定义产品的"是什么"和"给谁用"：

ProjectBrief {
  projectTitle: string          // 项目标题
  projectDescription: string    // 项目描述
  language: "zh" | "en" | ...   // 决定所有生成内容的语言

  productScope: {
    productType: string         // "SaaS landing page"、"e-commerce" 等
    mvpDefinition: string       // MVP 定义
    coreOutcome: string         // 核心交付成果
    businessGoal: string        // 业务目标
    audienceSummary: string     // 目标受众
    inScope: string[]           // 范围内
    outOfScope: string[]        // 范围外
  }

  roles: UserRole[]             // 用户角色（访客、管理员等）
  taskLoops: TaskLoop[]         // 用户任务流程
  capabilities: CapabilitySpec[] // 产品能力（must-have / should-have / nice-to-have）
}

UserRole

每个角色有 roleId、goals、coreActions、permissions 和优先级（primary / secondary / supporting）。如果 LLM 没有输出角色，系统会自动创建一个默认的 "Visitor" 角色。

TaskLoop

描述用户的端到端旅程：入口触发 → 步骤序列 → 成功状态。每个 TaskLoop 关联到一个 Role 和若干 Capability。

Experience 层

定义视觉和情感方向：

ProjectExperience {
  designIntent: {
    mood: string[]           // ["energetic", "professional"]
    colorDirection: string   // "dark with orange accent"
    style: string            // "modern minimalist"
    keywords: string[]       // 传递给后续所有生成步骤
  }
}

keywords 数组特别重要 — 它会被传递给 section 生成阶段的运行时 skill 发现，影响每个 section 的风格技能选择。

Site 层

定义站点的具体结构：

ProjectSiteBlueprint {
  informationArchitecture: {
    navigationModel: string    // 导航模型描述
    pageMap: PageMapEntry[]    // 页面地图
    sharedShells: string[]     // 共享外壳（"全局导航"、"全局页脚"）
    notes: string[]
  }

  pages: PageBlueprint[]         // 每个页面及其 sections（layout chrome 由实现 Agent 决定）
}

SectionSpec

每个 section 的规格：

SectionSpec {
  type: string                    // "hero"、"features"、"pricing" 等
  intent: string                  // 这个 section 要传达什么
  contentHints: string            // 内容提示
  fileName: string                // 输出文件名（如 "HeroSection"）
  primaryRoleIds: string[]        // 主要服务的角色
  supportingCapabilityIds: string[] // 关联的产品能力
  sourceTaskLoopIds: string[]     // 关联的任务流
}

fileName 会被转为 PascalCase 并加上 scope 前缀，最终生成如 home_HeroSection.tsx、layout_NavSection.tsx 的文件。

今日主路径里 analyze_project_requirement 与 infer_design_intent 并行执行：前者保证结构化蓝图，后者补充 mood / 技术关键词；最终在 normalizeBlueprint 之后合并进规划与设计系统输入。

容错 Normalize

LLM 输出 JSON 时经常出现字段缺失、类型错误、结构不一致。asProjectBlueprint() 函数支持三种输出格式并对每个字段做 normalize：

嵌套结构标准的 { brief, experience, site } 三层嵌套

扁平结构所有字段平铺在顶层（projectTitle、designIntent、pages 等）

单页结构只有 title、description、sections — 自动包装为单页项目

每个字段都有合理的 fallback 值。例如 roles 为空时自动创建默认 Visitor 角色，productScope 缺失时从 projectDescription 推导。这比在 prompt 中反复强调"必须输出完整 JSON"更可靠。

AI 生成流水线风格技能