# 📋 CyberHuaTuo 数据格式规范

> 本文档定义了 CyberHuaTuo 开源知识库中「病例」与「药方」的标准数据格式。
> 所有社区贡献均需遵循此规范。

## 设计理念

CyberHuaTuo 是一个 **GitHub 开源共享知识库**，不是 Web 平台。

- 数据以 **YAML + Markdown** 文件存储在仓库中
- 社区成员通过 **Pull Request** 贡献问题与解决方案
- 每个问题一个文件，结构清晰，人类可读，机器可解析
- 从简单问题到复杂疑难杂症，有清晰的分级体系

参考项目：OpenClaw（Markdown 驱动的 Agent 知识共享）、tldr-pages（社区贡献的命令行文档）。

## 数据格式：YAML Front Matter + Markdown Body

采用 `YAML 前置元数据 + Markdown 正文` 的经典格式，兼顾：
- **结构化**：YAML 便于程序解析、索引、搜索
- **可读性**：Markdown 正文便于人类阅读和书写
- **Git 友好**：纯文本，diff 清晰

---

## 文件格式定义

### 病例文件（Case）

```yaml
---
# ===== 基础信息 =====
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"                 # 影响的版本范围
language: "python"                           # 编程语言
tags:
  - "import-error"
  - "breaking-change"
  - "migration"

# ===== 严重性与复杂度 =====
severity: "medium"                           # low | medium | high | critical
complexity: "simple"                         # simple（简单） | moderate（中等） | complex（复杂） | extreme（疑难杂症）

# ===== 环境信息 =====
environment:
  python_version: ">=3.9"                    # 可选，留空表示不限
  os: "any"                                  # any | windows | macos | linux
  dependencies: []                           # 相关依赖

# ===== 元数据 =====
created_at: "2026-03-10"
updated_at: "2026-03-10"
contributors:
  - github: "contributor_username"
source_url: "https://github.com/langchain-ai/langchain/issues/xxxxx"   # 原始问题链接（可选）
related_cases: []                            # 关联病例 ID 列表
---

## 🏥 症状描述
Symptom Description

用户从 LangChain 0.2.x 升级到 0.3.x 后，原有的 `from langchain import ChatOpenAI` 导入语句报错。

## 🔍 错误信息
Error Message

```python
ImportError: cannot import name 'ChatOpenAI' from 'langchain'
```

完整堆栈（可选）：
```
Traceback (most recent call last):
  File "app.py", line 3, in <module>
    from langchain import ChatOpenAI
ImportError: cannot import name 'ChatOpenAI' from 'langchain' (/path/to/langchain/__init__.py)
```

## 🔬 根因分析
Root Cause Analysis

LangChain 0.3 进行了包结构重组，将模型相关的类迁移到了 `langchain-openai` 独立包中。
`ChatOpenAI` 不再从 `langchain` 主包直接导出。

## 💊 药方
Prescriptions

### 药方 1：更新导入路径（推荐）

**适用版本**: `langchain >= 0.3.0`

1. 安装独立的 OpenAI 集成包：
```bash
pip install langchain-openai
```

2. 更新导入语句：
```python
# ❌ 旧写法（0.2.x）
from langchain import ChatOpenAI

# ✅ 新写法（0.3.x）
from langchain_openai import ChatOpenAI
```

### 药方 2：使用兼容层（临时过渡）

**适用版本**: `langchain >= 0.3.0, < 0.4.0`

```python
from langchain_community.chat_models import ChatOpenAI
```

> ⚠️ 注意：`langchain-community` 中的包装器将在未来版本中移除，建议尽早迁移到药方 1。

## 🔗 参考资料
References

- [LangChain 0.3 迁移指南](https://python.langchain.com/docs/versions/v0_3/)
- [GitHub Issue #xxxxx](https://github.com/langchain-ai/langchain/issues/xxxxx)
```

---

## 复杂度分级体系

CyberHuaTuo 覆盖从简单到极端复杂的所有 Agent 问题：

| 级别 | 复杂度 | 中文 | 典型场景 | 预期药方长度 |
|------|--------|------|---------|-------------|
| 🟢 | `simple` | 简单 | 导入错误、版本不兼容、配置缺失 | 1-2 步即可解决 |
| 🟡 | `moderate` | 中等 | API 参数变更、环境冲突、依赖链问题 | 3-5 步，需要上下文理解 |
| 🔴 | `complex` | 复杂 | 内存泄漏、异步死锁、跨框架集成问题 | 需要代码重构或架构调整 |
| ⚫ | `extreme` | 疑难杂症 | 底层 Bug、竞态条件、多因素叠加问题 | 需要深度调试和源码级修复 |

### 不同复杂度的文件模板差异

**🟢 简单问题**：只需 `症状 + 错误信息 + 药方`，无需根因分析
**🟡 中等问题**：完整的四段结构
**🔴 复杂问题**：增加「复现步骤」「调试过程」「性能影响」等章节
**⚫ 疑难杂症**：增加「排查路径」「失败方案记录」「源码分析」等

---

## 仓库目录结构

```
CyberHuaTuo/
├── README.md                          # 项目说明（中英双语）
├── LICENSE                            # Apache 2.0
├── CONTRIBUTING.md                    # 贡献指南
├── .github/
│   ├── ISSUE_TEMPLATE/                # Issue 模板
│   │   ├── new-case.yml               # 提交新病例
│   │   └── improve-prescription.yml   # 改进药方
│   ├── PULL_REQUEST_TEMPLATE.md       # PR 模板
│   └── workflows/
│       └── validate.yml               # CI 自动校验数据格式
│
├── schema/                            # 数据格式定义
│   ├── case.schema.json               # JSON Schema（用于自动校验）
│   └── README.md                      # Schema 说明
│
├── cases/                             # 📦 核心：所有病例数据
│   ├── langchain/                     # 按框架分目录
│   │   ├── _index.md                  # 该框架的概览和统计
│   │   ├── import-error/              # 按问题类别分子目录
│   │   │   ├── chatmodel-import-001.md
│   │   │   └── embeddings-import-002.md
│   │   ├── memory/
│   │   │   └── conversation-leak-001.md
│   │   ├── breaking-change/
│   │   └── performance/
│   │
│   ├── llamaindex/
│   │   ├── _index.md
│   │   ├── vector-store/
│   │   └── retrieval/
│   │
│   ├── crewai/
│   ├── autogen/
│   ├── openai-sdk/
│   ├── mcp/                           # Anthropic MCP
│   ├── dspy/
│   └── _cross-framework/              # 跨框架通用问题
│       ├── _index.md
│       ├── api-key-config-001.md
│       └── rate-limit-handling-001.md
│
├── tools/                             # 工具脚本
│   ├── validate.py                    # 本地格式校验脚本
│   ├── stats.py                       # 生成统计报告
│   ├── search.py                      # 本地搜索工具
│   └── new-case.py                    # 快速创建新病例的脚手架
│
├── docs/                              # 项目文档
│   ├── data-format.md                 # 数据格式规范（本文档）
│   ├── complexity-guide.md            # 复杂度分级指南
│   └── framework-coverage.md          # 框架覆盖情况
│
└── 设计/                              # 设计文档（开发团队用）
    ├── 项目概览.md
    ├── 品牌与视觉设计.md
    └── 路线图.md
```

---

## YAML 字段完整定义

### 必填字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 唯一标识：`{框架}-{关键词}-{序号}` |
| `title` | string | 中文标题 |
| `title_en` | string | 英文标题 |
| `framework` | string | 框架名（小写，枚举值） |
| `severity` | enum | `low` / `medium` / `high` / `critical` |
| `complexity` | enum | `simple` / `moderate` / `complex` / `extreme` |
| `created_at` | date | 创建日期（YYYY-MM-DD） |
| `contributors` | list | 贡献者列表，至少 1 人 |

### 可选字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `framework_version` | string | 影响的版本范围 |
| `language` | string | 编程语言 |
| `tags` | list | 自由标签 |
| `environment` | object | 环境信息 |
| `source_url` | string | 原始问题链接 |
| `related_cases` | list | 关联病例 ID |
| `updated_at` | date | 最后更新日期 |

### Framework 枚举值

```
langchain | llamaindex | crewai | autogen | openai-sdk |
mcp | dspy | haystack | semantic-kernel | pydantic-ai |
langflow | langgraph | agno | strands-agents | other
```

---

## 贡献流程

```
1. Fork 仓库
       │
2. 创建新病例文件
   → 使用 tools/new-case.py 快速生成模板
   → 或手动按格式创建 .md 文件
       │
3. 填写内容
   → YAML 元数据 + Markdown 正文
   → 运行 tools/validate.py 本地校验
       │
4. 提交 Pull Request
   → CI 自动校验格式
   → 社区 Review
       │
5. 合并入库 ✅
```

---

## JSON Schema（用于自动校验）

仓库中提供 `schema/case.schema.json`，用于 CI 和本地工具自动校验每个病例文件的 YAML 前置数据格式是否正确。

---

*创建日期: 2026-03-10*
*格式版本: v1.0*
