project_docs/framework_design_v2_1.md

# 螺钿垂直模型子项目方案（模型进阶 V2.1）

> 版本：V2.1（合并 V2 + V2.1修订清单）
> 日期：2026-02-10
> 状态：架构设计定稿，可进入实现阶段
> 变更来源：V2 双引擎/RAG架构 × Codex V2.1修订清单
> 本版新增：双轨训练策略 / 规则优先评估器 / 字段映射层 / 禁忌词库拦截 / 精简brief阶段策略

---

## 1. 文档定位与核心目标

### 1.1 文档定位

本文档是【螺钿垂直模型】进阶子项目的可执行框架，合并了 V2 架构设计与 V2.1 修订内容，
可直接进入实现阶段。

### 1.2 核心目标

> 在"全工艺可理解 + 工厂可落地 + 市场可接受"的前提下，使模型输出的设计方案具备：
> 1. **工厂可执行**：附带尺寸、材质、工序的技术参数卡，师傅看了能直接开工
> 2. **市场高接受度**：通过 AI 推理与规则评估，输出比一般设计工具更高概率在销售环节
>    产生收入与热度的方案

### 1.3 原始提示词（保留）

> "我希望设计款螺钿的产品，这个产品包含上海海派文化元素，并面向欧美市场具有一定
> 吸引力的产品设计风格，提供产品创意以及设计画面的设计图。"

---

## 2. 材质体系与双轨训练策略

### 2.1 全材质体系（模型需要理解的全部范围）

**胎体三大类：**

| 类型 | 材质 | 特点 | 训练轨道 |
|------|------|------|---------|
| 硬木胎 | 紫光檀、黑檀、红木、乌木 | 可量产主力，工厂友好 | **core** |
| 大漆胎 | 传统大漆木胎、脱胎漆器 | 高端传统，工时长 | extended |
| 金属胎 | 铜胎、银胎、混合胎 | 现代感强，适合首饰 | extended |

**镶嵌材料全谱：**

| 材料 | 特征 | 训练轨道 |
|------|------|---------|
| 贝母螺钿（厚/薄/砌） | 虹彩光泽，主力材料 | **core** |
| 银丝螺钿 | 拉丝/编丝/线条感 | **core** |
| 朱砂 | 填色/点缀，传统感 | extended |
| 金属箔片（金/银箔） | 奢华感叠加 | extended |
| 组合工艺 | 多材质混嵌 | extended（core 稳定后） |

### 2.2 双轨训练策略（V2.1 核心修正）

**原则：训练侧全工艺语义覆盖，但 core 必须先于 extended 稳定。**

```
core（当前主线）              extended（扩展域）
──────────────               ──────────────────
硬木胎 + 贝母/银丝            大漆/金属胎/朱砂/组合
商业主力产品                  工艺语义补全
先训练，先评估                core 稳定后按比例注入
```

**分阶段样本比例：**

| 阶段 | 图片总量 | core:extended | 说明 |
|------|---------|---------------|------|
| Phase 1（当前） | < 30张 | **10:0** | 全 core，不引入 extended |
| Phase 2 | 30-100张 | **8:2** | 开始按比例注入 extended |
| Phase 3 | 100张+ | **7:3 或 6:4** | 视 extended 增益评估调整 |

**防回归机制：**
- extended 样本默认进 `reference_only/`，经人工合规审核后才能转 `trainable/`
- 每轮训练固定保留独立的 **core 验证集**，extended 注入前后均需对比 core 指标不退化

---

## 3. 双引擎架构

```
┌─────────────────────────────────────────────────────┐
│                   用户输入（自然语言）                  │
└──────────────────────┬──────────────────────────────┘
                       │
        ┌──────────────▼──────────────────┐
        │  [拦截层] 文化禁忌词库            │ ← 硬规则，命中即拒绝
        │  cultural_taboos.yaml            │   不消耗推理 token
        └──────────────┬──────────────────┘
                       │ 通过
        ┌──────────────▼──────────────────┐
        │  理解引擎（LLaVA QLoRA）          │
        │  - 理解用户需求与参考图片          │
        │  - RAG 注入文化知识               │
        │  - 生成 design_brief.json        │
        │  - 工艺可行性评估（规则打分）      │
        └──────────────┬──────────────────┘
                       │ design_brief.json
        ┌──────────────▼──────────────────┐
        │  规则评估器（Evaluator）          │
        │  - 工厂可行性（尺寸/工时/工序）   │
        │  - 市场匹配（客群/价格带/风格）   │
        │  score ≥ 0.6 → 继续              │
        │  score < 0.6 → 返回修改建议      │
        └──────────────┬──────────────────┘
                       │ 评分 ≥ 0.6
        ┌──────────────▼──────────────────┐
        │  生成引擎（SDXL LoRA → ComfyUI） │
        │  - 接收 sdxl_prompt              │
        │  - 螺钿风格 LoRA 控制质量         │
        │  - 输出位图（PNG / WebP）         │
        │  [SVG 为可选后处理，非原生能力]   │
        └──────────────┬──────────────────┘
                       │
        ┌──────────────▼──────────────────┐
        │  输出包（三件套）                 │
        │  1. 设计图（PNG/WebP）            │
        │  2. 工厂参数卡                    │
        │  3. 市场适配建议                  │
        └─────────────────────────────────┘
```

**引擎选型确认：**
- 生成引擎：**SDXL + LoRA**（非 FLUX）
  - SDXL 推理 ~6GB，LoRA 训练 ~7GB，8GB 显存可用
  - FLUX.1-dev 需 ~23GB，FLUX.1-schnell 量化版仍需 ~12GB，均超出限制
  - kohya_ss 已在项目目录内，工具链现成

---

## 4. 子系统设计

### 4.1 子系统 A：采集器

**目标**：持续收集全工艺螺钿 + 时尚参考 + 文化素材

**合规来源优先级**：
1. Unsplash / Pexels / Pixabay（CC0，可商用）
2. 博物馆数字藏品（通常 CC BY）
3. 网络采集（一律进 reference_only，不入训练集）

**输出目录结构：**
```
images/
  ├── trainable/
  │   ├── core/            ← 硬木胎 + 贝母/银丝（经审核）
  │   └── extended/        ← 大漆/金属/朱砂（经合规审核后入）
  └── reference_only/
      └── trend/           ← 时尚趋势参考（版权不明）

annotations/
  ├── core/
  ├── extended/
  └── mapping_logs/        ← design_brief → dataset_schema 转换日志
```

**必存合规字段**：`source_url`、`license`、`crawl_time`、`usage_note`

---

### 4.2 子系统 B：文化知识库

**技术栈（确定）：**

| 组件 | 选型 | 理由 |
|------|------|------|
| 向量数据库 | ChromaDB（本地） | 纯 CPU，不占显存 |
| Embedding 模型 | BGE-M3 | 中英双语，CPU 可运行 |
| 检索方式 | 语义 + 关键词混合 | 文化专业词汇关键词更精确 |

**知识卡片结构：**
- 文化元素词表（上海海派视觉符号、欧美偏好语言）
- 视觉映射（图形、色彩、材质倾向）
- 商业映射（客群、价格带、适配平台）
- 文化禁忌条目（单独提取入 `cultural_taboos.yaml`）

**推理注入链：**
```
用户提示词 → ChromaDB 检索 → 相关语义片段 → LLaVA 生成 design_brief
```

---

### 4.3 文化禁忌拦截层（B 的硬规则前置）

文件：`knowledge/rules/cultural_taboos.yaml`

**拦截时机**：在 brief 生成之前，直接对用户输入做词汇/语义匹配。命中即拒绝，返回具体原因。

**禁忌类型举例：**
```yaml
color_taboos:
  - market: EU_NA
    pattern: ["纯白+葬礼语境", "纯黑+特定宗教语境"]
    reason: "特定场景下的文化误用风险"

symbol_taboos:
  - pattern: ["卍", "swastika"]
    market: EU_NA
    reason: "与纳粹符号混淆，欧美市场绝对禁止"
  - pattern: ["倒五角星+特定组合"]
    reason: "撒旦主义联想，欧美部分客群强烈抵触"

cultural_appropriation:
  - pattern: ["印第安头饰", "土著图腾"]
    market: NA
    reason: "北美文化挪用敏感领域"
```

---

### 4.4 子系统 C：Orchestrator（提示词编排）

#### 设计 Brief（分阶段字段策略）

**Phase 1 精简版（当前使用，8个核心字段）：**

```json
{
  "product_type": "handheld_mirror",
  "cultural_theme": {
    "cn_element": "上海海派 Art Deco",
    "market_target": "EU"
  },
  "visual_spec": {
    "motif": "外滩建筑剪影 + 几何线条",
    "style_keywords": ["geometric_silhouette", "iridescent", "minimalist"]
  },
  "material_spec": {
    "substrate": "purple_sandalwood",
    "inlay_primary": "nacre"
  },
  "production_params": {
    "dimensions": "12x8x0.5cm",
    "production_time": "6-8h"
  },
  "generation_params": {
    "sdxl_prompt": ""
  }
}
```

**Phase 2 完整版（管道跑通后扩展，18个字段）：**

完整字段在 Phase 1 基础上新增：
- `material_spec.inlay_secondary`（组合材质）
- `material_spec.surface_finish`
- `production_params.cost_tier`
- `production_params.complexity`
- `production_params.factory_notes`
- `generation_params.negative_prompt`
- `generation_params.style_lora`
- `cultural_theme.cultural_notes`（RAG 召回片段）
- `evaluation`（评分器填入）

---

### 4.5 规则评估器（V2.1 修正：规则优先，不做模型打分）

**评分维度与规则：**

**维度1：工厂可行性（manufacturability）**

| 检查项 | 规则 | 权重 |
|--------|------|------|
| 尺寸合理性 | 长/宽/高在工厂标准加工范围内 | 0.3 |
| 工时范围 | 单品 6-10 小时（超出为 complex，低于为 simple） | 0.25 |
| 材质组合现实性 | substrate × inlay 组合在已知工艺体系内 | 0.25 |
| 工序复杂度 | complexity ≠ "complex"（本阶段不接 complex） | 0.2 |

**维度2：市场匹配（market_fit）—— Phase 1 纯规则版**

| 检查项 | 规则 | 权重 |
|--------|------|------|
| 风格与目标市场匹配 | EU/NA → geometric/minimalist ≥ 1个关键词 | 0.3 |
| 价格带匹配 | 产品类型 × cost_tier 在合理区间 | 0.25 |
| 文化禁忌缺席 | 通过禁忌拦截层则此项满分 | 0.3 |
| 主题可识别性 | motif 非空且可解释 | 0.15 |

> **为何不做模型打分（V2.1 修正理由）**：
> 当前无市场销售反馈数据，模型对自己生成的 brief 打分会形成"自评自证"的伪精确。
> 规则打分透明、可审计、可随销售数据积累后升级为模型打分。

**三档评分行动：**

| 综合分 | 标签 | dataset_schema production_feasibility | 行动 |
|--------|------|--------------------------------------|------|
| ≥ 0.8 | 高可行性 | `"high"` | 自动通过，直接生成 |
| 0.6-0.8 | 中等 | `"medium"` | 带警告生成，标注待人工确认 |
| < 0.6 | 不可行 | 不入数据集 | 返回修改建议，拒绝生成 |

---

### 4.6 字段映射层（V2.1 新增：design_brief → dataset_schema）

> 这一层是数据飞轮的关键：使 brief 生成的设计可以回流为新的训练数据。

| design_brief 字段 | dataset_schema 字段 | 映射规则 |
|---|---|---|
| `product_type` | `product_type` | 直接映射 |
| `cultural_theme.cn_element` | `visual_subject` | 主题抽取为可视对象 |
| `visual_spec.style_keywords` | `design_style` | 关键词归并 |
| `visual_spec.motif` | `visual_description_cn` | 中文视觉主描述 |
| `material_spec.substrate` | `base_material` | 术语标准化（purple_sandalwood→紫光檀） |
| `material_spec.inlay_primary` + `inlay_secondary` | `inlay_material` | 组合拼接 |
| `production_params.complexity` | `complexity_level` | simple/medium 直接映射 |
| `production_params.factory_notes` | `technical_specs.inlay_technique` | 提取工艺关键词 |
| `production_params.dimensions` | `technical_specs.dimensions` | 直接映射 |
| `production_params.production_time` | `technical_specs.production_time` | 直接映射 |
| `production_params.cost_tier` | `technical_specs.cost_level` | low/mid/high → 经济/中等/高端 |
| `cultural_theme.market_target` | `market_orientation` | EU/NA/CN → 欧美/中国/全球 |
| `generation_params.sdxl_prompt` | `prompt_template` | 存模板或实例文本 |
| `evaluation.manufacturability_score` | `production_feasibility` | 按三档阈值映射 |
| `user_prompt_raw` | `visual_description_cn`（附注） | 保留用户原文 |

**自动生成字段：**
- `visual_description_en`：由 `tags_mapping.json` 规则标准化
- `reference_tags`：由 `style_keywords + cultural_notes` 自动提取

---

## 5. 完整脚手架目录

```text
模型进阶V1/
├── README.md
├── docs/
│   ├── 子项目执行计划-V2.1.md
│   ├── 数据合规与授权规范.md
│   ├── design_brief字段说明.md          ← Phase1精简版 + Phase2完整版
│   └── 评估规则说明.md
│
├── collector/
│   ├── configs/
│   │   ├── keyword_pools.yaml           ← 全工艺中英关键词（core/extended分类）
│   │   └── source_whitelist.yaml        ← 合规来源白名单
│   └── scripts/
│       ├── crawl_images.py
│       ├── deduplicate_images.py         ← pHash 感知哈希去重
│       └── build_source_meta.py
│
├── knowledge/
│   ├── corpus/                          ← 文化资料原文（PDF/MD/TXT）
│   ├── rules/
│   │   ├── cultural_taboos.yaml         ← 硬规则拦截词库（V2.1 新增）
│   │   ├── manufacturability_rules.yaml
│   │   └── market_fit_rules.yaml
│   ├── scripts/
│   │   ├── ingest_texts.py
│   │   ├── build_vector_index.py        ← ChromaDB + BGE-M3
│   │   └── query_knowledge.py
│   └── index/                           ← ChromaDB 本地索引
│
├── orchestrator/
│   ├── templates/
│   │   ├── design_brief_phase1.json     ← 精简版（8字段）
│   │   └── design_brief_phase2.json     ← 完整版（18字段）
│   └── scripts/
│       ├── generate_design_brief.py
│       └── brief_to_schema_mapping.py   ← 字段映射层（V2.1 新增）
│
├── evaluator/
│   └── scripts/
│       └── score_design.py              ← 规则打分（三档：high/medium/reject）
│
└── generation/
    ├── comfyui_workflows/
    │   └── luodian_sdxl.json            ← ComfyUI SDXL workflow 模板
    └── scripts/
        └── run_generation.py            ← 调用 ComfyUI API，输出 PNG/WebP
```

---

## 6. 执行节奏（V2.1 版）

| 阶段 | 时长 | 内容 | 优先理由 |
|------|------|------|---------|
| **第1阶段** | 1周 | 锁定 core 数据定义 + 字段映射层建立 | 保证数据闭环可跑 |
| **第2阶段** | 1周 | 文化知识库（ChromaDB+BGE-M3 最小可用）+ 禁忌词库初版 | RAG 上线，brief 生成有内容 |
| **第3阶段** | 1周 | 编排器（Phase1精简brief + 规则评估器） | 最快路径出第一个可验证结果 |
| **第4阶段** | 2周 | SDXL 螺钿风格 LoRA 训练（kohya_ss + ComfyUI） | 独立于LLaVA，可并行推进 |
| **第5阶段** | 2-3周 | 采集链路打通 + core 数据扩充至30张 | 合规审查需要时间，后置 |
| **第6阶段** | 持续 | extended 按比例注入 + LLaVA 新一轮 LoRA 迭代 | core 稳定后启动 |

---

## 7. 多 Agent 扩展开口（预留，不入核心架构）

> **当前决策**：基于 Token 成本与项目盈利预期，Swarms 多 Agent 协同暂不纳入核心架构。
> 所有模块按"单 Agent 顺序执行"模式实现。

**开口条件（满足任一可评估升级）：**
1. 项目产生稳定收入，Token 成本可被商业化抵消
2. Claude Code Swarms 官方正式发布且成本结构明确
3. 单 Agent 模式出现明显瓶颈（如数据采集与知识库更新串行太慢）

**接口规范（现在即按此编写，升级零成本）：**
```python
# 每个子系统统一接口 → 未来改为 Agent 委托时，逻辑不变，调用方式变

def run_taboo_check(user_input: str) -> TabooResult: ...
def run_knowledge_query(query: str) -> KnowledgeResult: ...
def run_brief_generator(user_input: str, knowledge: KnowledgeResult) -> DesignBrief: ...
def run_evaluator(brief: DesignBrief) -> EvaluationResult: ...
def run_generator(brief: DesignBrief) -> GenerationResult: ...
def map_brief_to_schema(brief: DesignBrief) -> DatasetRecord: ...

# 当前：顺序执行
taboo  = run_taboo_check(user_input)
if taboo.blocked: return taboo.reason
knowledge = run_knowledge_query(user_input)
brief     = run_brief_generator(user_input, knowledge)
eval_     = run_evaluator(brief)
if eval_.score < 0.6: return eval_.suggestions
result    = run_generator(brief)
record    = map_brief_to_schema(brief)   # 回流训练数据

# 未来 Swarms：并发委托（接口签名不变）
```

---

## 8. 验收标准

### 8.1 架构验收
- [ ] 双引擎分工清晰，design_brief.json 是唯一跨引擎接口
- [ ] 禁忌拦截层在 brief 生成之前执行
- [ ] 规则评估器独立于生成引擎（不存在"自评自证"）

### 8.2 数据验收
- [ ] `core/trainable` 与 `extended/reference_only` 边界明确
- [ ] 所有图片有 `source_url/license/crawl_time` 合规追踪
- [ ] 字段映射层可将 brief 自动转换为 dataset_schema 格式

### 8.3 训练验收
- [ ] Phase 2 注入 extended 前后，core 验证集指标不退化
- [ ] 生成结果包含可执行的工厂参数卡（不只是视觉概念图）

### 8.4 商业验收
- [ ] 输出包含：客群、价格带、平台建议
- [ ] score < 0.6 的方案返回具体修改建议（闭环）
- [ ] 输出设计的市场适配分高于无垂直训练的通用模型基准

---

## 9. 当前决议

**已落版：**
- 全工艺双轨训练策略（core 先行，extended 按比例注入）
- 双引擎结构（LLaVA 理解 + SDXL 生成，ComfyUI 管道）
- 禁忌拦截层（YAML 硬规则，brief 生成前执行）
- 规则优先评估器（三档阈值，不做模型打分）
- 字段映射层（design_brief → dataset_schema，数据飞轮闭环）
- Phase 1 精简 brief（8 字段），Phase 2 完整 brief（18 字段）
- Swarms 预留接口（开口但不入核心）

**暂不执行：**
- 脚手架代码开发
- 爬取脚本开发
- 知识库服务化部署

**下一步决策点：**
- [ ] 确认第1阶段启动时间（锁定 core 定义 + 字段映射）
- [ ] 提供文化资料文本（上海海派、欧美偏好）供知识库构建
- [ ] 提供 SDXL 螺钿风格参考图（10-20张，供 LoRA 训练）