# 🏗️ CyberHuaTuo 技术架构

## 设计原则

CyberHuaTuo 是一个 **GitHub 原生的开源知识库**，所有数据以纯文本文件存储在仓库中。技术架构围绕三个核心目标：

1. **人类可读**：Markdown 格式，任何人都能直接阅读和编辑
2. **机器可解析**：YAML 元数据 + JSON Schema 校验，支持自动化工具
3. **Git 友好**：纯文本文件，diff 清晰，合并冲突易解决

## 系统总览

```
┌─────────────────────────────────────────────────────────────────┐
│                    GitHub 仓库 (Single Source of Truth)           │
│                                                                   │
│  cases/                    schema/              tools/            │
│  ├── langchain/            ├── case.schema.json  ├── validate.py  │
│  ├── llamaindex/           └── README.md         ├── search.py    │
│  ├── crewai/                                     ├── stats.py     │
│  ├── mcp/                  .github/workflows/    └── new-case.py  │
│  ├── openai-sdk/           └── validate.yml                      │
│  └── _cross-framework/                                           │
│                                                                   │
└──────────────────────────┬───────────────────────────────────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────────┐
        │ 社区贡献  │ │ CI 校验  │ │ 下游消费者   │
        │ via PR   │ │ via GH   │ │ (工具/网站/  │
        │          │ │ Actions  │ │  IDE 插件)   │
        └──────────┘ └──────────┘ └──────────────┘
```

## 数据层

### 数据格式

所有病例数据采用 **YAML Front Matter + Markdown Body** 格式：

```markdown
---
id: "langchain-import-chatmodel-001"
title: "LangChain 0.3 升级后 ChatOpenAI 导入失败"
title_en: "ChatOpenAI import error after upgrading to LangChain 0.3"
framework: "langchain"
framework_version: ">=0.3.0"
severity: "medium"
complexity: "simple"
tags: ["import-error", "breaking-change"]
created_at: "2026-03-10"
contributors:
  - github: "username"
---

## 🏥 症状描述 / Symptom Description
...

## 🔍 错误信息 / Error Message
...

## 🔬 根因分析 / Root Cause Analysis
...

## 💊 药方 / Prescriptions
...
```

**详细格式定义见 [数据格式规范](./数据格式规范.md)**

### 目录结构

```
cases/
├── langchain/                 # 按框架一级分类
│   ├── _index.md              # 框架概览与统计
│   ├── import-error/          # 按问题类别二级分类
│   │   └── chatmodel-import-001.md
│   ├── memory/
│   ├── breaking-change/
│   └── performance/
├── llamaindex/
├── crewai/
├── mcp/
├── openai-sdk/
└── _cross-framework/          # 跨框架通用问题
```

### 数据校验

通过 JSON Schema 定义 YAML 元数据的合法结构，CI 自动校验每个 PR：

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "title", "title_en", "framework", "severity", "complexity", "created_at", "contributors"],
  "properties": {
    "id": { "type": "string", "pattern": "^[a-z0-9-]+-[0-9]{3}$" },
    "framework": { "enum": ["langchain", "llamaindex", "crewai", "autogen", "openai-sdk", "mcp", "dspy", "haystack", "semantic-kernel", "pydantic-ai", "langgraph", "other"] },
    "severity": { "enum": ["low", "medium", "high", "critical"] },
    "complexity": { "enum": ["simple", "moderate", "complex", "extreme"] }
  }
}
```

## 工具层

### 本地工具（`tools/` 目录）

| 工具 | 功能 | 语言 |
|------|------|------|
| `new-case.py` | 交互式创建新病例文件（脚手架） | Python |
| `validate.py` | 本地校验所有病例文件格式 | Python |
| `search.py` | 在本地仓库中搜索病例（关键词/框架/标签） | Python |
| `stats.py` | 生成统计报告（各框架病例数、复杂度分布等） | Python |

### CI/CD（GitHub Actions）

```yaml
# .github/workflows/validate.yml
name: Validate Cases
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install pyyaml jsonschema
      - run: python tools/validate.py
```

**CI 校验内容：**
1. YAML Front Matter 必填字段完整性
2. 字段值符合 JSON Schema 约束（枚举值、格式等）
3. `id` 全局唯一性
4. 文件路径与 `framework` 字段一致
5. Markdown 正文包含必要的章节标题

## 贡献工作流

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Fork 仓库   │────→│  创建病例文件  │────→│  本地校验     │
│              │     │ (手动/脚手架)  │     │ validate.py  │
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                  │
                                                  ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   合并入库 ✅  │←────│  社区 Review  │←────│  提交 PR     │
│              │     │              │     │ CI 自动校验   │
└──────────────┘     └──────────────┘     └──────────────┘
```

## 下游消费场景

作为一个开源数据仓库，CyberHuaTuo 的数据可被多种方式消费：

| 消费方式 | 说明 |
|---------|------|
| **直接浏览** | 在 GitHub 上直接浏览 Markdown 文件 |
| **本地搜索** | 克隆仓库后使用 `tools/search.py` |
| **静态网站** | 基于仓库数据生成 GitHub Pages 文档站（未来） |
| **CLI 工具** | 基于仓库数据构建命令行诊断工具（未来） |
| **IDE 插件** | 基于仓库数据构建 VS Code / JetBrains 插件（未来） |
| **AI Agent** | 作为 RAG 数据源接入智能体（未来） |

## 技术栈总结

| 层 | 技术 | 说明 |
|----|------|------|
| 数据存储 | YAML + Markdown 文件 | 纯文本，Git 友好 |
| 数据校验 | JSON Schema + Python | CI 自动校验 |
| 版本管理 | Git + GitHub | PR 驱动的协作 |
| 自动化 | GitHub Actions | CI 校验 + 统计生成 |
| 本地工具 | Python 脚本 | 搜索、校验、生成 |

---

*创建日期: 2026-03-10*
*更新日期: 2026-03-10*
