<p align="center">
  <h1 align="center">🩺 CyberHuaTuo / 赛博华佗</h1>
  <p align="center">
    <strong>望闻问切，药到病除。</strong><br>
    <strong>Diagnose. Prescribe. Cure.</strong>
  </p>
  <p align="center">
    An open-source knowledge base for diagnosing and curing AI agent issues.<br>
    开源的 AI 问题诊断知识库 — AI 世界的赛博神医
  </p>
  <p align="center">
    <a href="#-the-problem">Problem</a> •
    <a href="#-how-it-works">How It Works</a> •
    <a href="#-quick-start">Quick Start</a> •
    <a href="#-contributing">Contributing</a> •
    <a href="#-supported-frameworks">Frameworks</a> •
    <a href="#-license">License</a>
  </p>
</p>

---

## 🤔 The Problem

You're building with LangChain, LlamaIndex, CrewAI, or any AI agent framework. Something breaks. You copy the error, search everywhere — GitHub Issues, Discord, Stack Overflow, Reddit — wasting hours piecing together a fix from scattered threads.

**CyberHuaTuo** is an open-source knowledge base that aggregates these problems and their battle-tested solutions in one place. Like [OpenClaw](https://github.com/openclaw/openclaw) for agent capabilities, CyberHuaTuo is for agent **problem-solving**.

你在用 AI Agent 框架开发，结果报错了。你复制错误信息到处搜——GitHub Issues、Discord、Stack Overflow、Reddit——花好几个小时才从零散的帖子里拼凑出解决方案。

**赛博华佗** 是一个开放的知识库，将这些问题和经过验证的解决方案聚合在一起。就像 OpenClaw 让大家共享 Agent 能力一样，CyberHuaTuo 让大家共享 **解决 Agent 问题的经验**。

## ✨ How It Works

Every case in CyberHuaTuo follows a structured format — **YAML metadata + Markdown body** — making it both human-readable and machine-parseable:

```yaml
---
id: "langchain-import-chatmodel-001"
title: "LangChain 0.3 升级后 ChatOpenAI 导入失败"
title_en: "ChatOpenAI import error after upgrading to LangChain 0.3"
framework: "langchain"
severity: "medium"
complexity: "simple"        # simple → moderate → complex → extreme
---

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

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

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

### 🏥 望闻问切 — Four Levels of Complexity

| Level | Complexity | What It Covers |
|-------|-----------|---------------|
| 🟢 | **Simple** | Import errors, missing configs, version mismatches |
| 🟡 | **Moderate** | API changes, environment conflicts, dependency chains |
| 🔴 | **Complex** | Memory leaks, async deadlocks, multi-agent coordination |
| ⚫ | **Extreme** | Race conditions, upstream bugs, multi-factor compound issues |

## 🚀 Quick Start

### Browse Cases

Just browse the [`cases/`](./cases/) directory on GitHub! Cases are organized by framework:

```
cases/
├── langchain/          # LangChain issues
├── llamaindex/         # LlamaIndex issues
├── crewai/             # CrewAI issues
├── mcp/                # MCP (Anthropic) issues
├── openai-sdk/         # OpenAI SDK issues
└── _cross-framework/   # Cross-framework issues
```

### Search Locally

```bash
git clone https://github.com/[owner]/CyberHuaTuo.git
cd CyberHuaTuo

# Search for a specific error
python tools/search.py "ChatOpenAI import error"

# Search by framework
python tools/search.py --framework langchain

# Search by tag
python tools/search.py --tag "breaking-change"
```

## 🤝 Contributing

CyberHuaTuo thrives on community contributions. Become a **坐堂医师 (Resident Doctor)**!

### Submit a New Case (挂号)

1. Fork this repo
2. Create a new case file:
   ```bash
   python tools/new-case.py    # Interactive wizard
   ```
   Or manually create a `.md` file following the [Data Format Spec](./设计/数据格式规范.md)
3. Validate locally:
   ```bash
   python tools/validate.py
   ```
4. Submit a Pull Request
5. After review → Merged ✅

### Improve an Existing Case (改良药方)

Found a better fix? Additional context? Just edit the case file and submit a PR.

### Quality Standards

Every case must include:
- ✅ Complete YAML metadata (all required fields)
- ✅ Clear symptom description and error message
- ✅ At least one verified prescription
- ✅ Pass `tools/validate.py` validation

See [CONTRIBUTING.md](./CONTRIBUTING.md) for full guidelines.

## 📋 Supported Frameworks

| Framework | Cases | Status |
|-----------|-------|--------|
| LangChain | 🔴 Building | P0 — Seed data |
| MCP (Anthropic) | 🔴 Building | P0 — Seed data |
| CrewAI | 🔴 Building | P0 — Seed data |
| LlamaIndex | 🟡 Planned | P1 |
| OpenAI SDK | 🟡 Planned | P1 |
| AutoGen | 🟢 Future | P2 |
| DSPy | 🟢 Future | P2 |
| Haystack | 🟢 Future | P2 |

## 📊 疫情通报 / Epidemic Report

<!-- Auto-generated by tools/stats.py -->

| Framework | Total Cases | Simple | Moderate | Complex | Extreme |
|-----------|------------|--------|----------|---------|---------|
| langchain | 1 | 1 | 0 | 0 | 0 |
| mcp | 1 | 0 | 1 | 0 | 0 |
| crewai | 1 | 0 | 0 | 1 | 0 |

*Last updated: 2026-03-10*

## 🛠️ For Tool Developers

CyberHuaTuo data is **structured and machine-parseable**. Build tools on top of it:

- **CLI diagnostic tool**: Search cases from terminal
- **IDE extensions**: Suggest fixes when errors are detected
- **AI Agent RAG**: Use as knowledge base for LLM-based debugging
- **GitHub Bot**: Auto-reply with matching prescriptions

## 📜 License

[Apache License 2.0](LICENSE)

## 🙏 Acknowledgments

Named after [华佗 (Hua Tuo)](https://en.wikipedia.org/wiki/Hua_Tuo), the legendary physician of ancient China who pioneered surgical anesthesia (麻沸散) and the art of diagnosis. In his spirit, CyberHuaTuo brings collective healing wisdom to the modern world of AI agents.

Inspired by [OpenClaw](https://github.com/openclaw/openclaw) — if OpenClaw lets everyone share agent capabilities, CyberHuaTuo lets everyone share the wisdom of fixing agent problems.

---

<p align="center">
  <strong>Your Agent is sick? Walk in. 🩺</strong><br>
  <strong>你的 Agent 病了？华佗来了。</strong>
</p>
