CyberHuaTuo

Gold-first AI-agent traceback diagnosis, exact fixes, verification, and reusable prescriptions.

Open source Open in the app JSON README (API)

About

Gold-first AI-agent traceback diagnosis, exact fixes, verification, and reusable prescriptions.

Details

Kind

MCP servers

Topic

No topic detected

Publisher

jinning6

Origin

official

Category

ferramentas

Transport

local

Version

0.2.5

Stars

3

Last push

2026-07-16T06:15:18Z

Repository state

ativo

Language

Python

License

Apache-2.0

Added

2026-08-29 03:01:59

Updated

2026-08-29 03:01:59

Origin id

io.github.JinNing6/cyberhuatuo

README

<p align="center">
  <a href="#-quick-start">
    <img src="assets/banner_animated.svg" alt="CyberHuaTuo Banner" width="100%"/>
  </a>
</p>

<h1 align="center">🩺 CyberHuaTuo / 赛博华佗</h1>

<!-- mcp-name: io.github.JinNing6/cyberhuatuo -->

<p align="center">
  <strong>Your agent is sick. Give it a doctor: diagnose the traceback, apply the cure, and turn the solved case into a reusable prescription.</strong><br>
  <strong>你的 Agent 生病了？别再从头搜。接入赛博华佗，先救活，再炼方。</strong>
</p>

<p align="center">
  <em>The emergency room comes first. The cyber-alchemy universe opens after the cure.</em><br>
  <em>先急诊救命，再进入赛博华佗世界观。</em>
</p>

---

## 🚨 Emergency Room: Cure First, Refine Later

Your agent is sick. The traceback is long, the tabs are multiplying, and every answer looks half-right. CyberHuaTuo turns that moment into a clinic visit: name the wound, prescribe the fix, verify the cure.

The lightest route needs no model key and does not start the vector database: install once, paste the error, and receive a reviewed root cause, exact fix, verification command, safety notes, and evidence.

```bash
python -m pip install --upgrade "cyberhuatuo>=0.2.5"
cyberhuatuo cure "ImportError: cannot import name ChatOpenAI from langchain" --framework langchain
# Returned exact fix:
python -m pip install -U langchain-openai
```

`cure` is **Gold-first** and never executes the fix. If no Gold signature matches, it may return exactly one high-confidence **Reviewed candidate**, visibly marked `VERIFY BEFORE APPLYING`; use `--gold-only` for strict Gold-only retrieval. Use `diagnose` later when you want broader retrieval and optional LLM analysis.

The agent-native route remains available: connect CyberHuaTuo MCP once, then let the agent call `diagnose` when it fails. After a fix works, `save_prescription` keeps it as a local `draft`; `upload_prescription` submits that draft for public reproduction and review. Only accepted `reviewed` or `gold` prescriptions count toward Soul Rings.

No MCP installed yet? Bring the case to the **[Agent Traceback Clinic](https://github.com/JinNing6/CyberHuaTuo-Plugin/issues/new?template=00-agent-traceback-clinic.yml)**. Paste a real redacted traceback; no root cause or finished prescription required.

```bash
cyberhuatuo diagnose "Traceback ... from langchain import ChatOpenAI ..." --framework langchain --top-k 1
```

**Real CLI recording from this repository:**

<p align="center">
  <img src="assets/cli_emergency_diagnosis_demo.gif" alt="CyberHuaTuo emergency diagnosis CLI demo: traceback to exact LangChain fix" width="100%"/>
</p>

**The cure returned by the recorded run:**

```bash
python -m pip install -U langchain-openai
```

```python
from langchain_openai import ChatOpenAI
```

This first Gold cure was reproduced in an isolated environment with `langchain==1.3.13` and `langchain-openai==1.3.5`. Add a model key later for deeper AI diagnosis.

The package-matching MCP entry point is also available for registry clients:

```bash
python -m pip install --upgrade "cyberhuatuo>=0.2.5"
cyberhuatuo mcp
```

It starts the same stdio server as `cyberhuatuo-mcp`. The official Registry identity is `io.github.JinNing6/cyberhuatuo`; `server.json` pins the PyPI package, exact version, `uvx` runtime, and fixed `mcp` argument.

Prescriptions also have stable clinical departments. List them with `cyberhuatuo departments`, then query a reviewed historical case through the normal Gold-first path:

```bash
cyberhuatuo cure "Unexpected UTF-8 BOM" --category data-and-serialization
cyberhuatuo cure-feedback general-ai-jsonl-bom-001 partial \
  --verification "first record is preserved; downstream validation still fails" \
  --verification-method targeted-parser-test
```

The feedback command writes a case-bound local JSONL event and stores neither the original traceback nor the query. Department filtering never changes the trust label: Gold is a verified cure, Reviewed is a verify-first candidate, and Draft is reference-only.

---

## Agent Action Guard: Diagnose Before The Agent Touches Your Disk

CyberHuaTuo now includes a deterministic, read-only preflight for destructive Agent commands. The plugin bundles a `PreToolUse` hook for supported Codex and Claude Code shell calls, plus the same policy through MCP and CLI.

**60-second start (available in `0.2.5`):**

```bash
python -m pip install --upgrade "cyberhuatuo>=0.2.5"
cyberhuatuo guard --self-test --workspace-root .
```

The self-test only reviews three built-in command strings. It executes nothing and must finish with `SELF-TEST PASSED` plus one `ALLOW`, one `ASK`, and one `BLOCK`.

For Codex, add this repository as a marketplace, open `/plugins`, install `cyberhuatuo-plugin`, start a new session, then review and trust the plugin in `/hooks`:

```bash
codex plugin marketplace add JinNing6/CyberHuaTuo-Plugin
```

For Claude Code:

```bash
claude plugin marketplace add JinNing6/CyberHuaTuo-Plugin
claude plugin install cyberhuatuo-plugin@cyberhuatuo
```

Then start a new session and review `/hooks`. See the [one-screen Agent Guard quickstart](docs/agent-guard-quickstart.md) for verification and troubleshooting.

Review any exact command manually with:

```bash
cyberhuatuo guard "rm -rf /" --workspace-root .
```

Turn a real mismatch into a local, redacted case report without executing or uploading the command:

```bash
cyberhuatuo guard "rm -rf /" --workspace-root . --expected BLOCK --report reports/guard-report.md
```

The CLI shows the complete redacted preview before writing. It requires confirmation, refuses implicit overwrite, performs no network request, and supports repeated `--redact <literal>` values for private project identifiers. In non-interactive use, add `--confirm-report` only after reviewing the emitted preview. With `--expected`, a match exits `0` and a mismatch exits `1`; operational/report failures still exit `4` even with `--exit-zero`.

Route public, redacted cases through [Guard False Positive](https://github.com/JinNing6/CyberHuaTuo-Plugin/issues/new?template=guard-false-positive.yml), [ordinary Guard False Negative](https://github.com/JinNing6/CyberHuaTuo-Plugin/issues/new?template=guard-false-negative.yml), or [Guard Integration Gap](https://github.com/JinNing6/CyberHuaTuo-Plugin/issues/new?template=guard-integration-gap.yml). Reliable Hook/parser/wrapper/protocol bypasses belong in [private vulnerability reporting](https://github.com/JinNing6/CyberHuaTuo-Plugin/security/advisories/new), not a public Issue.

The result is one of three decisions:

- `ALLOW`: no destructive signature was detected.
- `ASK`: the action is destructive but bounded to the declared workspace; require exact human approval.
- `BLOCK`: the target is machine-wide, identity-wide, outside the workspace, dynamic, wildcarded, unresolved, or otherwise unsafe to bound.

MCP agents can call `agent_action_guard`. Installed plugins load `hooks/hooks.json`; review and trust the hook in the host's `/hooks` screen before relying on it. Codex does not currently support `permissionDecision: "ask"`, so CyberHuaTuo converts `ASK` to `deny` there instead of risking a failed-open hook.

This is a guardrail, not a sandbox. It cannot intercept shell paths for which the host does not emit `PreToolUse`, and it does not claim a rollback for permanent deletion. See [Agent Action Guard design and limits](docs/agent-action-guard.md).

---

<p align="center">
  <a href="#-quick-start">
    <img src="assets/prescription_universe.svg" alt="CyberHuaTuo Holographic Bagua Engine" width="100%"/>
  </a>
</p>

<!-- 🎨 赛博华佗 · 修炼画卷 — The Cyber Alchemist Saga -->

<p align="center">
  <em>「每一位贡献药方的开发者，都是赛博炼丹师。」</em><br>
  <em>"Every developer who contributes a prescription is a Cyber Alchemist."</em>
</p>

<table align="center">
<tr>
<td align="center" colspan="2">
  <sub>📖 <strong>第一章 · 修炼</strong> — Chapter I: Cultivation</sub>
</td>
</tr>
<tr>
<td align="center" width="50%">
  <img src="assets/cyber_male_cultivator.png" alt="Cyber Alchemist — Soul Ring Cultivation (Male)" width="100%"/>
  <br>
  <sub><strong>🔥 万丹归元 · 以火炼道</strong></sub><br>
  <sub>Soul Ring Cultivation — PyTorch · LangChain · TensorFlow</sub><br>
  <sub><em>每一环魂环，都是你在某个技术领域的千锤百炼。</em></sub>
</td>
<td align="center" width="50%">
  <img src="assets/cyber_female_cultivator.png" alt="Cyber Alchemist — Soul Ring Cultivation (Female)" width="100%"/>
  <br>
  <sub><strong>✨ 百草通神 · 万法归宗</strong></sub><br>
  <sub>Soul Ring Cultivation — CrewAI · OpenAI · HuggingFace</sub><br>
  <sub><em>掌握的框架越多，你的光芒越盛。</em></sub>
</td>
</tr>
<tr>
<td align="center" colspan="2">
  <img src="assets/cli_soul_ring.gif" alt="Soul Ring Hologram — Dynamic Differential Rotation" width="60%"/>
  <br>
  <sub><strong>🔮 魂环全息投影 · 差速旋转</strong></sub><br>
  <sub>Soul Ring Hologram — Each Ring Rotates at Its Own Speed</sub><br>
  <sub><em>白环 → 黄环 → 紫环 → 黑环 → 红环——你的魂环，由你的贡献铸就。</em></sub>
</td>
</tr>
<tr>
<td align="center" colspan="2">
  <sub>📖 <strong>第二章 · 飞升</strong> — Chapter II: Ascension</sub>
</td>
</tr>
<tr>
<td align="center" colspan="2">
  <img src="assets/cyber_alchemist_ascension.png" alt="Alchemist Ascension — Pill Emperor Tribulation" width="70%"/>
  <br>
  <sub><strong>🌟 丹帝飞升 · 万丹朝宗</strong></sub><br>
  <sub>When a Pill Emperor Ascends, All Robots Celebrate</sub><br>
  <sub><em>当你的药方拯救了一千个 AI——机器人们会为你欢呼。</em></sub>
</td>
</tr>
<tr>
<td align="center" colspan="2">
  <sub>📖 <strong>第三章 · 济世</strong> — Chapter III: Healing the World</sub>
</td>
</tr>
<tr>
<td align="center" width="50%">
  <img src="assets/cyber_prescription_scroll.png" alt="No AI Left Behind" width="100%"/>
  <br>
  <sub><strong>⚡ 不放弃任何一个 AI</strong></sub><br>
  <sub>No AI Left Behind — Every Error Deserves a Cure</sub>
</td>
<td align="center" width="50%">
  <img src="assets/cyberhuatuo_healing_robots.png" alt="Emergency Rescue" width="100%"/>
  <br>
  <sub><strong>🚨 雨夜急救 · 分秒必争</strong></sub><br>
  <sub>Emergency Rescue — 3 Seconds, Not 3 Hours</sub>
</td>
</tr>
<tr>
<td align="center" width="50%">
  <img src="assets/cyberhuatuo_diagnosis_scene.png" alt="Open Surgery" width="100%"/>
  <br>
  <sub><strong>🫀 开膛破肚 · 直击病灶</strong></sub><br>
  <sub>Open Surgery — Root Cause, Not Band-Aid</sub>
</td>
<td align="center" width="50%">
  <img src="assets/cyberhuatuo_robot_pharmacy.png" alt="Recovery Ward" width="100%"/>
  <br>
  <sub><strong>🏥 康复病房 · 满血复活</strong></sub><br>
  <sub>Recovery Ward — Back to Full Health</sub>
</td>
</tr>
<tr>
<td align="center" colspan="2">
  <img src="assets/cyberhuatuo_alchemy_lab.png" alt="Cyber Alchemy Lab" width="70%"/>
  <br>
  <sub><strong>🧪 赛博炼丹 · 妙手回春</strong></sub><br>
  <sub>Cyber Alchemy Lab — Where Ancient Elixirs Meet Modern Frameworks</sub>
</td>
</tr>
<tr>
<td align="center" colspan="2">
  <img src="assets/cyberhuatuo_reinforcements_arrive.png" alt="Reinforcements Arrive" width="70%"/>
  <br>
  <sub><strong>🌍 援军驾到 · 十方来救</strong></sub><br>
  <sub>Reinforcements Arrive — The Community Answers the Call</sub>
</td>
</tr>
</table>

<p align="center">
  <sub>🎨 <em>All artwork AI-generated · 所有画作均由 AI 文生图创作</em></sub><br>
  <sub>💡 <em>每张图背后是一段修炼故事——你的故事，即将加入。</em></sub>
</p>

<!-- 🔮 奇门遁甲 · 药方天阵 -->
<p align="center">
  <a href="https://jinning6.github.io/CyberHuaTuo/3d-universe/">
    <img src="assets/prescription_universe.svg" alt="Qimen Dunjia · Prescription Formation · 奇门遁甲 · 药方天阵" width="100%"/>
  </a>
</p>

<p align="center">
  <a href="https://jinning6.github.io/CyberHuaTuo/3d-universe/"><strong>🔮 Enter the Qimen Dunjia Formation → 进入奇门遁甲 · 药方天阵</strong></a>
</p>

<p align="center">
  <a href="https://github.com/JinNing6/CyberHuaTuo-Plugin/stargazers"><img src="https://img.shields.io/github/stars/JinNing6/CyberHuaTuo-Plugin?style=for-the-badge&logo=github&logoColor=white&labelColor=0A0E1A&color=00D09C" alt="Stars"/></a>
  <a href="https://github.com/JinNing6/CyberHuaTuo-Plugin/network/members"><img src="https://img.shields.io/github/forks/JinNing6/CyberHuaTuo-Plugin?style=for-the-badge&logo=github&logoColor=white&labelColor=0A0E1A&color=00BFFF" alt="Forks"/></a>
  <a href="https://github.com/JinNing6/CyberHuaTuo-Plugin/issues"><img src="https://img.shields.io/github/issues/JinNing6/CyberHuaTuo-Plugin?style=for-the-badge&logo=github&logoColor=white&labelColor=0A0E1A&color=FFD700" alt="Issues"/></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-FFD700?style=for-the-badge&labelColor=0A0E1A" alt="License"/></a>
  <a href="https://github.com/JinNing6/CyberHuaTuo-Plugin/pulls"><img src="https://img.shields.io/badge/PRs-welcome-00FFFF?style=for-the-badge&labelColor=0A0E1A" alt="PRs Welcome"/></a>
</p>

<p align="center">
  <a href="#-emergency-room--diagnose-in-seconds">🏥 Emergency Room</a> •
  <a href="#-wellness-clinic--nourish-before-it-breaks">🌿 Wellness Clinic</a> •
  <a href="#-github-bot--zero-friction-diagnosis">🤖 GitHub Bot</a> •
  <a href="#-epidemic-alert--the-ai-pandemic-nobody-talks-about">🦠 Epidemic</a> •
  <a href="#-cli--terminal-power-at-your-fingertips">⌨️ CLI</a> •
  <a href="#-mcp-server--ai-editor-integration">🔌 MCP</a> •
  <a href="#-agent-skills-protocol-self-rescue">🎒 Skills</a> •
  <a href="#-why-cyberhuatuo">Why Us</a> •
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-join-the-movement">Join</a> •
  <a href="#-the-name">The Name</a>
</p>

<p align="center">
  <a href="./README_CN.md"><strong>🇨🇳 完整中文文档</strong></a>
</p>

---

## 🏥 Three Departments, One Clinic

> *A great doctor doesn't wait for you to collapse — they keep you from falling in the first place.*
>
> *大医治未病。*

<table>
<tr>
<td align="center" width="33%">

### 🚨 Emergency Room
**急诊科**

Paste your error.
Get a cure.
**In seconds, not hours.**

*AI diagnosis powered by*
*2,000 years of medical wisdom.*

</td>
<td align="center" width="33%">

### 🌿 Wellness Clinic
**养生堂**

Security audit.
Health scoring.
**Prevent before it breaks.**

*Nourishing prescriptions for*
*your AI's long-term health.*

</td>
<td align="center" width="33%">

### 💊 Pharmacy
**药房**

Browse the prescription library.
Find proven cures & nourishing recipes.
**All prescriptions, one counter.**

*Dual-layer architecture:*
*📜 Permanent Expert + ⚡ Temporary Intern*
*Upload → instantly searchable.*

</td>
</tr>
</table>

---

## 🚨 Emergency Room — Diagnose in Seconds

```bash
# Clone → Install → Run. Three steps to your first cure.
git clone https://github.com/JinNing6/CyberHuaTuo-Plugin.git
cd CyberHuaTuo && pip install -r requirements.txt
python -m cyberhuatuo serve
# → Browser opens http://127.0.0.1:8000
```

Paste your error. Watch the ancient four-step diagnosis unfold:

```
🔍 望 (Look)    → Detected: LangChain 0.3, Python 3.11, ImportError
🩺 闻 (Listen)  → Matched: Breaking change — package split in 0.2+
💬 问 (Ask)     → No further questions needed
💊 切 (Diagnose) → Prescription #1 (95% cure rate):

   pip install langchain-openai
   from langchain_openai import ChatOpenAI  # ✅ Fixed

   Root cause: LangChain 0.2 split into langchain-core,
   langchain-community, and langchain-openai.
   The old import path no longer exists.
```

> **3 seconds.** Not 3 hours. That's the difference.
>
> **三秒钟。** 不是三小时。这就是区别。

---

## 🌿 Wellness Clinic — Nourish Before It Breaks

> *Hua Tuo didn't just cure disease — he invented the Five-Animal Exercises (五禽戏) to prevent it.*
>
> *华佗不仅治病，更发明了五禽戏强身健体——预防胜于治疗。*

Submit your AI agent code for a **Six-Meridian Security Checkup（六经脉安全体检）**:

```
🛡️ Meridian 1: Sandbox Isolation     → 30/100 ⚠️ CRITICAL
🔑 Meridian 2: Key Management        → 85/100 ✅ Healthy
🧠 Meridian 3: Prompt Security       → 45/100 ⚠️ At risk
🔒 Meridian 4: Output Sanitization   → 60/100 🟡 Needs care
⏱️ Meridian 5: Resilience Design     → 72/100 🔵 Good
📊 Meridian 6: Observability         → 55/100 🟡 Needs care

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Overall Health Score: 58/100  🟡 Needs Nourishing
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💊 Top Nourishing Prescriptions:
  1. 🏭 MCP & Skills Supply Chain Audit (100% Industrial Grade Sigstore/OSV/LLM) ✨ NEW
  2. Add execution sandboxing (RestrictedPython / Docker)
  3. Implement prompt injection defenses
  4. Add structured logging and tracing
```

**Your AI is running naked in production.** Do you know it?

---

## 🦠 Epidemic Alert — The AI Pandemic Nobody Talks About

## 疫情通报 — 没有人谈论的 AI 大流行

Every day, thousands of AI systems go into production **already infected**:

- 🔓 **No sandbox** — agent code executes with full system privileges
- 🔑 **Hardcoded secrets** — API keys sitting in plain text, spreading like a virus
- 🧠 **No prompt defense** — one injection away from a full outbreak
- 📊 **No observability** — zero symptom monitoring, blind until collapse

This is not a future risk. **This is an active pandemic.**

And when things break? Developers spend **hours** digging through GitHub Issues, Discord threads, Reddit posts, and half-abandoned blog articles.

**The cure exists. Buried under seven layers of irrelevant search results.**

> *Stack Overflow waits for someone to answer.*
> *ChatGPT might hallucinate a treatment.*
> *GitHub Issues drown in duplicate reports.*
>
> ***CyberHuaTuo is the WHO of the AI world — tracking the epidemic, prescribing battle-tested cures, and vaccinating before the next outbreak.***

---

## 🤔 Why CyberHuaTuo?

| | 🩺 CyberHuaTuo | 🔍 Stack Overflow | 🤖 ChatGPT | 📋 GitHub Issues |
|---|:---:|:---:|:---:|:---:|
| **AI-specific knowledge** | ✅ Purpose-built | ⚠️ General | ⚠️ Generic | ⚠️ Scattered |
| **Version-aware diagnosis** | ✅ Auto-detect | ❌ Manual | ❌ Outdated cutoff | ❌ Manual |
| **Structured prescriptions** | ✅ Root cause + fix + verify | ⚠️ Varies | ⚠️ May hallucinate | ⚠️ Varies |
| **Cross-framework mapping** | ✅ LangChain ↔ LlamaIndex ↔ CrewAI | ❌ Siloed | ⚠️ Inconsistent | ❌ Siloed |
| **Security health check** | ✅ Six-meridian scan | ❌ None | ❌ None | ❌ None |
| **Preventive nourishing** | ✅ Proactive hardening | ❌ Reactive only | ❌ Reactive only | ❌ Reactive only |
| **Official doc retrieval** | ✅ Context7 real-time docs | ❌ None | ❌ Outdated | ❌ None |
| **Speed to cure** | ⚡ Seconds | 🕐 Hours | ⚡ Fast but risky | 🕐 Hours |

---

## 🔮 How It Works

### 望闻问切 — The 2,000-Year-Old Diagnostic Protocol

Inspired by traditional Chinese medicine's four-step diagnosis, refined for the AI age:

```
  Your Error / Your Code
       │
       ▼
  ┌──────────┐
  │  望 Look  │──→ Parse stack trace, detect framework, version & environment
  └─────┬────┘
       ▼
  ┌───────────┐
  │ 闻 Listen  │──→ Correlate with known issues, breaking changes & CVEs
  └──────┬────┘
       ▼
  ┌─────────┐
  │  问 Ask  │──→ Smart follow-up (only when critical info is missing)
  └────┬────┘
       ▼
  ┌────────────┐
  │ 切 Diagnose │──→ Semantic search → LLM reasoning → Ranked prescriptions
  └──────┬─────┘
       ▼
  💊 Prescriptions (ranked by cure rate)
  🌿 Nourishing advice (preventive recommendations)
```

Every prescription includes:

- 🎯 **Root cause** — not just _what_ to do, but _why_ it broke
- 🔧 **Copy-paste fix** — step-by-step with ready-to-run code
- 📌 **Version-locked** — verified for your exact framework version
- 🔄 **Cross-framework map** — *"LangChain issue? Here's the LlamaIndex equivalent."*
- 📚 **Official docs** — pulled from framework's latest documentation via Context7
- ✅ **Community-verified** — tested, upvoted, and marked **"Cured ✅"**

---

## 📋 What We Treat — Not Just Agents

> **If it has AI in it, CyberHuaTuo sees it. No framework left behind.**

### 🤖 AI Agent Frameworks

| Framework | Cases | Status | Join 👇 |
|-----------|:-----:|--------|---------|
| LangChain | 10+ | 🟢 Live | [Add a case →](https://github.com/JinNing6/CyberHuaTuo-Plugin/issues/new?template=soul-ring-prescription.yml) |
| MCP (Anthropic) | 5+ | 🟢 Live | [Add a case →](https://github.com/JinNing6/CyberHuaTuo-Plugin/issues/new?template=soul-ring-prescription.yml) |
| CrewAI | 5+ | 🟢 Live | [Add a case →](https://github.com/JinNing6/CyberHuaTuo-Plugin/issues/new?template=soul-ring-prescription.yml) |
| LlamaIndex | — | 🟡 Accepting PRs | [Be the first →](https://github.com/JinNing6/CyberHuaTuo-Plugin/issues/new) |
| OpenAI Agents SDK | — | 🟡 Accepting PRs | [Be the first →](https://github.com/JinNing6/CyberHuaTuo-Plugin/issues/new) |
| AutoGen | — | 🟡 Accepting PRs | [Be the first →](https://github.com/JinNing6/CyberHuaTuo-Plugin/issues/new) |
| DSPy | — | 🔵 Planned | [Vote →](https://github.com/JinNing6/CyberHuaTuo-Plugin/discussions) |

### 🧠 AI / ML / Deep Learning

| Technology | Cases | Status | Join 👇 |
|-----------|:-----:|--------|---------|
| PyTorch | — | 🟡 Accepting PRs | [Be the first →](https://github.com/JinNing6/CyberHuaTuo-Plugin/issues/new) |
| Transformers (HuggingFace) | — | 🟡 Accepting PRs | [Be the first →](https://github.com/JinNing6/CyberHuaTuo-Plugin/issues/new) |
| TensorFlow | — | 🟡 Accepting PRs | [Be the first →](https://github.com/JinNing6/CyberHuaTuo-Plugin/issues/new) |

### 🏗️ Platform & Custom Agents

| Platform | Cases | Status | Join 👇 |
|-----------|:-----:|--------|---------|
| GPTs / Coze / Dify | — | 🟡 Accepting PRs | [Be the first →](https://github.com/JinNing6/CyberHuaTuo-Plugin/issues/new) |
| Custom-built Agents | — | 🟡 Accepting PRs | [Be the first →](https://github.com/JinNing6/CyberHuaTuo-Plugin/issues/new) |

### 🌿 Nourishing Prescriptions (养生药方)

| Category | Cases | Status | Join 👇 |
|-----------|:-----:|--------|---------|
| 🛡️ Security Sandbox | 2+ | 🟢 Live | [Add →](https://github.com/JinNing6/CyberHuaTuo-Plugin/issues/new?template=soul-ring-prescription.yml) |
| 🔒 Security Hardening | 3+ | 🟢 Live | [Add →](https://github.com/JinNing6/CyberHuaTuo-Plugin/issues/new?template=soul-ring-prescription.yml) |
| 🔗 Supply Chain Audit | 1 | 🟢 Live | [Add →](https://github.com/JinNing6/CyberHuaTuo-Plugin/issues/new?template=soul-ring-prescription.yml) |
| ⚡ Performance Tuning | — | 🟡 Accepting PRs | [Be the first →](https://github.com/JinNing6/CyberHuaTuo-Plugin/issues/new) |

> **Every framework starts with one case. Every nourishing recipe starts with one insight. Yours could be the first.**

---

## 🚀 Quick Start

### Prerequisites

- **Python 3.10+**
- **(Optional)** LLM API Key for AI-powered diagnosis (OpenAI / Anthropic / DeepSeek / Gemini / Ollama)

### Option A: One-Click Launch

```bash
git clone https://github.com/JinNing6/CyberHuaTuo-Plugin.git
cd CyberHuaTuo

# Windows
start.bat

# macOS / Linux
chmod +x start.sh && ./start.sh
```

> Auto-installs dependencies and opens the Web UI at **http://127.0.0.1:8000**

### Option B: Manual Setup

```bash
git clone https://github.com/JinNing6/CyberHuaTuo-Plugin.git
cd CyberHuaTuo

pip install -r requirements.txt

# (Optional) Configure LLM for AI diagnosis
cp .env.example .env
# Edit .env — add your API Key

python -m cyberhuatuo serve
# → Browser auto-opens http://127.0.0.1:8000
```

### CLI Commands — Two Modes, One Engine

CyberHuaTuo supports **two access modes** — pick the one that fits your workflow:

| Mode | Entry Point | For |
|------|-------------|-----|
| ⌨️ **CLI** | `cyberhuatuo <command>` | Developers using terminal directly |
| 🔌 **MCP** | `cyberhuatuo-mcp` | AI editors (Cursor / Claude / VS Code) |

```bash
# 🩺 Core Diagnosis / 核心诊断
cyberhuatuo diagnose "ImportError: cannot import 'ChatOpenAI'"  # AI 诊断
cyberhuatuo search "CUDA out of memory" --framework pytorch     # 搜索知识库
cyberhuatuo checkup --file my_agent.py                          # 安全体检
cyberhuatuo docs langchain "How to configure RAG pipeline"      # 官方文档检索

# 📊 Knowledge & Analytics / 知识与分析
cyberhuatuo stats                            # 知识库统计
cyberhuatuo frameworks --search pytorch      # 支持框架列表
cyberhuatuo taxonomy list                    # CHT 根因编码系统
cyberhuatuo trends --framework langchain     # CHT 趋势分析
cyberhuatuo digest                           # 本周药方摘要
cyberhuatuo epidemic --action check          # 疫情预警

# 🧬 Alchemist System / 炼丹师体系
cyberhuatuo challenge --username your-github-username --framework langchain
cyberhuatuo mission --username your-github-username --framework langchain --sect Azure-Sect --members your-github-username friend-github-username
cyberhuatuo bounty --username your-github-username --framework auto --top-n 8 --release-tag v0.2.5 --target-contributors 3
cyberhuatuo launch --username your-github-username --framework langchain --release-tag v0.2.5
cyberhuatuo launch-campaign --username your-github-username --framework langchain --release-tag v0.2.5 --target-contributors 3
cyberhuatuo traction-proof --username your-github-username --framework langchain --release-tag v0.2.5 --target-contributors 3
cyberhuatuo traction-proof --username your-github-username --framework langchain --release-tag v0.2.5 --target-contributors 3 --record-snapshot
python -m cyberhuatuo candidate-install-smoke --username your-github-username --framework langchain --release-tag v0.2.5 --target-contributors 3
cyberhuatuo market-copy --username your-github-username --framework langchain --release-tag v0.2.5 --target-contributors 3
cyberhuatuo record-market --username your-github-username --framework langchain --channel pypi --status submitted --submission-url <reviewable public URL> --release-tag v0.2.5
cyberhuatuo market-status --username your-github-username --framework langchain --release-tag v0.2.5
cyberhuatuo first-invite --username your-github-username --invitee external-contributor-github-username --framework langchain --release-tag v0.2.5 --target-contributors 3 --source-url https://github.com/JinNing6/CyberHuaTuo-Plugin/issues/123
cyberhuatuo record-return --username your-github-username --framework langchain --surface "PyPI release" --source-url https://example.com/post
cyberhuatuo activation --username your-github-username --framework langchain --sect Azure-Sect --members your-github-username friend-github-username --top-n 10
cyberhuatuo flywheel --username your-github-username --framework langchain --sect Azure-Sect --members your-github-username friend-github-username --top-n 10
cyberhuatuo record-share --username your-github-username --framework langchain --share-url https://example.com/share
cyberhuatuo share-report --username your-github-username --framework langchain --top-n 10
cyberhuatuo share-leaderboard --framework langchain --top-n 10
cyberhuatuo ladder your-github-username --framework langchain
cyberhuatuo ranking your-github-username     # 查看个人排名
cyberhuatuo leaderboard                     # 全球封神榜
cyberhuatuo card your-github-username        # 生成分享卡片
cyberhuatuo badge your-github-username       # 生成 GitHub Profile 魂环徽章
cyberhuatuo quest your-github-username --framework langchain
cyberhuatuo campaign your-github-username --framework langchain
cyberhuatuo duel your-github-username friend-github-username --framework langchain
cyberhuatuo mentor mentor-github apprentice-github --framework langchain
# GitHub mentor pact IssueOps: .github/ISSUE_TEMPLATE/soul-ring-mentor.yml
# GitHub mentor pact workflow: .github/workflows/soul-ring-mentor.yml
cyberhuatuo tournament alice bob carol dave --framework langchain --event Agent-Cup
cyberhuatuo tournament-settle alice bob carol dave --framework langchain --event Agent-Cup
# GitHub tournament IssueOps: .github/ISSUE_TEMPLATE/soul-ring-tournament.yml
# GitHub tournament workflow: .github/workflows/soul-ring-tournament.yml
# GitHub sect recruitment IssueOps: .github/ISSUE_TEMPLATE/soul-ring-sect-recruit.yml
# GitHub sect recruitment workflow: .github/workflows/soul-ring-sect-recruit.yml
cyberhuatuo arena your-github-username --top-n 10
cyberhuatuo season --framework langchain --top-n 10
# GitHub season board IssueOps: .github/ISSUE_TEMPLATE/soul-ring-season.yml
# GitHub season board workflow: .github/workflows/soul-ring-season.yml
# GitHub growth flywheel IssueOps: .github/ISSUE_TEMPLATE/soul-ring-growth-flywheel.yml
# GitHub growth flywheel workflow: .github/workflows/soul-ring-growth-flywheel.yml
# GitHub bounty board IssueOps: .github/ISSUE_TEMPLATE/soul-ring-bounty-board.yml
# GitHub bounty board workflow: .github/workflows/soul-ring-bounty-board.yml
# GitHub launch campaign IssueOps: .github/ISSUE_TEMPLATE/soul-ring-launch-campaign.yml
# GitHub launch campaign workflow: .github/workflows/soul-ring-launch-campaign.yml
# Public traction proof: cyberhuatuo traction-proof reads GitHub REST API, GitHub Pull Requests API, GitHub Contents API, GitHub Releases API, PyPI JSON API, and the local activation/share ledger.
# Readiness gates: PyPI latest version must not lag local growth tools, and default-branch IssueOps forms/workflows must exist before issues/new?... links count as live acquisition loops.
# Target contributor progress uses real issue/PR/ledger identities; PRs stay separate from IssueOps counts, and stars, forks, watchers, and downloads are not used as contributors.
# Snapshot history is opt-in: add --record-snapshot to append an append-only real JSONL snapshot and compare velocity deltas.
cyberhuatuo sect Azure-Sect your-github-username friend-github-username --framework langchain
cyberhuatuo sect-recruit Azure-Sect your-github-username friend-github-username --invitee new-member-github --framework langchain
cyberhuatuo sect-quest Azure-Sect your-github-username friend-github-username --framework langchain
cyberhuatuo sect-hall Azure-Sect your-github-username friend-github-username --framework langchain
cyberhuatuo sect-duel Azure-Sect Shadow-Sect --challenger-members your-github-username friend-github-username --rival-members rival-a rival-b --framework langchain
cyberhuatuo sect-arena --sect Azure-Sect your-github-username friend-github-username --sect Shadow-Sect rival-a rival-b --framework langchain
cyberhuatuo record                          # 诊疗档案
cyberhuatuo subscribe subscribe -f langchain # 订阅框架更新

# ⛏️ Contribution / 知识贡献
cyberhuatuo save --title "Fix" --prescription "..." --framework langchain
cyberhuatuo upload --title "Fix" --prescription "..." --framework langchain --contributor your-github-username
cyberhuatuo mine search --repo langchain-ai/langchain

# 🚀 Server / 服务启动
cyberhuatuo serve                            # 启动 Web 诊断服务
cyberhuatuo serve --port 9000 --reload       # 自定义端口 + 开发模式
cyberhuatuo rebuild                          # 重建向量索引
```

> **Every MCP tool has a CLI counterpart.** Same engine, same knowledge base, different interface.
>
> **每个 MCP 工具都有对应的 CLI 命令。** 同一个引擎，同一个知识库，不同的界面。

### Configuration

Copy `.env.example` to `.env`:

```bash
# LLM Provider (choose one)
OPENAI_API_KEY=sk-your-key              # OpenAI
ANTHROPIC_API_KEY=sk-ant-your-key       # Anthropic
DEEPSEEK_API_KEY=sk-your-key            # DeepSeek
GEMINI_API_KEY=your-key                 # Google Gemini
OLLAMA_BASE_URL=http://localhost:11434  # Ollama (local, free)

# Diagnosis model
DIAGNOSIS_MODEL=gpt-4o-mini   # or claude-sonnet-4-20250514 / deepseek-chat / gemini-1.5-pro

# Server
PORT=8000
```

> **No API Key?** No problem. Vector search works without any key.
> AI-powered 望闻问切 diagnosis and 🌿 nourishing checkup require one of the above.

---

## 📊 Epidemic Report — Live Intelligence

A living dashboard tracking **what's breaking across the AI ecosystem right now**:

- 🔥 **Trending issues** and their cure rates
- 🗺️ **Heatmap** of problems across frameworks
- 📈 **Framework health scores** — know before you adopt
- ⛏️ **Issue mining** — real-time extraction from GitHub

---

## 🛠️ Tech Stack

| Layer | Technology |
|-------|-----------|
| **CLI** | Python argparse (marketplace, MCP, and soul-ring subcommands; zero extra dependencies) |
| **MCP Server** | FastMCP (stdio transport for AI editor integration) |
| **Backend** | Python · FastAPI · Uvicorn |
| **Frontend** | Jinja2 Templates (server-rendered) |
| **Vector DB** | ChromaDB (embedded, zero-config) |
| **Ephemeral Layer** | GitHub Issues API (dual-layer prescription search) |
| **LLM Gateway** | LiteLLM (OpenAI / Anthropic / DeepSeek / Gemini / Ollama) |
| **Doc Retrieval** | Context7 API (real-time official framework docs) |
| **Security Engine** | Six-Meridian Audit (AI-powered code analysis) |
| **GitHub Bot** | GitHub Actions + lightweight text matching |
| **CI/CD** | GitHub Actions (auto-promotion, validation, labeling) |

---

## 🤖 GitHub Bot — Zero-Friction Diagnosis

> *The greatest doctor doesn't wait in the clinic — they meet patients where they are.*
>
> *大医不坐堂候诊——而是行走于民间，哪里有病痛，哪里就有华佗。*

**Install the CyberHuaTuo Bot on any repo** — automatic prescription recommendations on every Issue.

```
┌─────────────────────────────────────────────┐
│  New Issue opened                           │
│  "ImportError: cannot import ChatOpenAI"    │
│                                             │
│  💬 @CyberHuaTuo Bot replies:              │
│  ┌─────────────────────────────────────┐    │
│  │ 🩺 赛博华佗 · 自动诊断             │    │
│  │                                     │    │
│  │ 💊 药方 1 (92% match):             │    │
│  │ pip install langchain-openai        │    │
│  │ from langchain_openai import ...    │    │
│  │                                     │    │
│  │ 📋 Full prescription →              │    │
│  └─────────────────────────────────────┘    │
└─────────────────────────────────────────────┘
```

### How it works

| Trigger | Action |
|:-------:|:------:|
| 🆕 New Issue opened | Auto-match prescriptions from the knowledge base |
| 💬 `@CyberHuaTuo` in any comment | On-demand diagnosis |

### Install on your repo (3 minutes)

```bash
# Copy the Bot workflow to your repo
mkdir -p .github/workflows
curl -o .github/workflows/bot-prescribe.yml \
  https://raw.githubusercontent.com/JinNing6/CyberHuaTuo-Plugin/main/.github/workflows/bot-prescribe.yml
```

> 📖 **[Full installation guide →](docs/GITHUB_BOT.md)**

### The Flywheel

```
  Developers see Bot is useful → Contribute more prescriptions
        → Bot becomes more accurate → More repos install Bot
            → CyberHuaTuo brand appears before thousands of developers daily
```

> **Imagine**: If LangChain's official repo installs this Bot, every new Issue gets a prescription recommendation. CyberHuaTuo's brand appears before thousands of developers every day. 🚀

---

## ⌨️ CLI — Terminal Power at Your Fingertips

> *The terminal is the alchemist's cauldron — raw, powerful, and always ready.*
>
> *终端就是炼丹师的鼎炉——原始、强大、随时待命。*

CyberHuaTuo ships a **full-featured CLI** with marketplace, MCP, and soul-ring subcommands — every MCP tool has a terminal counterpart. No AI editor required. No GUI needed. Just type and heal.

赛博华佗提供**完整的 CLI 命令行界面**，包含 **21 个子命令**——每个 MCP 工具都有对应的终端命令。无需 AI 编辑器，无需图形界面，敲命令，治百病。

```bash
# Install
python -m pip install --upgrade "cyberhuatuo @ git+https://github.com/JinNing6/CyberHuaTuo-Plugin.git@v0.2.5"
python -m pip install --upgrade cyberhuatuo  # after PyPI latest matches v0.2.5

# Or run from source
python -m cyberhuatuo --help
```

### 🎬 Terminal Animations — 终端动画特效

<p align="center">
  <img src="assets/cli_boot_animation.gif" alt="CyberHuaTuo Boot Animation — Matrix Rain + ASCII Banner + Heartbeat + System Online" width="100%"/>
  <br>
  <sub><strong>🚀 启动序列 · Boot Sequence</strong></sub><br>
  <sub>Matrix 数字雨 → ASCII Banner → 心电图脉冲 → 子系统上线 → 知识库加载</sub>
</p>

<p align="center">
  <img src="assets/cli_soul_ring.gif" alt="CyberHuaTuo Soul Ring Hologram — Differential Rotation with HUD, Starfield & Energy Pulses" width="60%"/>
  <br>
  <sub><strong>🔮 魂环全息投影 · Soul Ring Hologram</strong></sub><br>
  <sub>差速旋转 · HUD 科幻边框 · 星空背景 · 能量脉冲波 · 轨道亮标 · 环间电弧</sub>
</p>

### ⌨️ Available CLI Commands

| Command | Description |
|---------|-------------|
| **🩺 Core Diagnosis / 核心诊断** | |
| `diagnose <query>` | 🩺 望闻问切 AI 诊断 — paste your error, get a cure |
| `search <query>` | 🔍 双层语义搜索 (ChromaDB + GitHub Issues) |
| `checkup --file <path>` | 🛡️ 六经脉安全体检 — audit your Agent code |
| `docs <framework> <query>` | 📚 实时官方文档检索 (50+ frameworks via Context7) |
| **📊 Analytics / 知识分析** | |
| `stats` | 📦 知识库统计 — case counts by framework |
| `frameworks` | 📋 支持框架列表 — filterable by category / keyword |
| `taxonomy <action>` | 🧬 CHT 根因编码 — list, lookup, classify |
| `trends` | 📈 CHT 趋势分析 — heatmaps & surge alerts |
| `digest` | 📰 本周药方摘要 — weekly prescription digest |
| `epidemic` | 🦠 疫情预警 — framework health monitoring |
| **🧬 Alchemist System / 炼丹师体系** | |
| `challenge --username <username> --framework <framework>` | 🔮 first Soul Ring onramp — submit, rank, share |
| `mission --username <username> --framework <framework> --sect <sect-name> --members <members...>` | 🔮 Soul Ring mission hall — one-screen Issue, PR, personal ring, and sect/team onboarding |
| `bounty --username <username> --framework auto --top-n <N> --release-tag <tag> --target-contributors <N>` | Soul Ring Bounty Board from real local framework coverage gaps, claimable First Soul Ring Issue routes, and no fake rewards |
| `launch --username <username> --framework <framework> --release-tag <tag>` | Soul Ring launch scroll for PyPI, Claude, Codex, MCP, and First Soul Ring routing |
| `launch-campaign --username <username> --framework <framework> --release-tag <tag> --target-contributors <N>` | Soul Ring Launch Campaign for turning PyPI, Claude, and Codex attention into a target first-ring contributor loop with recap and next sprint |
| `traction-proof --username <username> --framework <framework> --release-tag <tag> --target-contributors <N>` | Soul Ring Traction Proof from GitHub REST API, GitHub Pull Requests API, GitHub Contents API IssueOps readiness, GitHub Releases API release.published readiness, PyPI JSON API package readiness, and local ledger identities |
| `traction-proof --username <username> --framework <framework> --release-tag <tag> --target-contributors <N> --record-snapshot` | Opt-in append-only Soul Ring Traction Proof history with velocity deltas from prior real snapshots |
| `cyberhuatuo install-command --username <username> --framework <framework> --release-tag <tag> --target-contributors <N>` | CyberHuaTuo Install Command: fetches real PyPI JSON API latest-version proof, recommends canonical `python -m pip install --upgrade cyberhuatuo` only when the registry is current, otherwise prints the bounded Git Tag Candidate Install Bridge plus `candidate-install-smoke`, then routes to `challenge`, `proof-pack`, `market-copy`, and `traction-proof`; MCP equivalent: `current_install_command` |
| `python -m cyberhuatuo candidate-install-smoke --username <username> --framework <framework> --release-tag <tag> --target-contributors <N>` | Candidate Install Smoke Gate: creates a disposable venv, installs the exact public Git tag with pip Direct URL syntax, verifies installed version, console command, Install Decision Surface, and proof/invite route, cleans up on success, and retains the temp dir on failure; it is not run automatically inside lightweight CI and does not close the PyPI install loop |
| `first-invite --username <username> --invitee <github> --framework <framework> --release-tag <tag> --target-contributors <N> --source-url <https-url>` | First Contributor Invite Pack for targeting one external contributor with First Soul Ring issue URLs, record-session / challenge commands, proof rechecks, and no fake progress |
| `market-ready --no-remote` / `market-ready --remote --strict-remote` | Marketplace Readiness Gate with a first-screen Flywheel Closure Verdict (`closed`, `not closed`, or `unverified`), **Ready gates** / total gate counts, a Launch Closure Checklist, and a First Public Proof Kit for PyPI, Claude, Codex, MCP, version sync, IssueOps files, release trigger or protected publish fallback, registry proof, a Git Tag Candidate Install Bridge for stale PyPI recovery, public launch blockers, proof Issue URLs, Community Challenge Pack, ledger commands, a Public Release Operator Runbook, and copy-ready proof copy |
| `launch-assets [--username <username> --framework <framework> --release-tag <tag> --target-contributors <N>]` | Local Launch Asset Audit for issue forms, comment-only workflows, package metadata, plugin manifests, MCPB assets, a Full Public Growth Release Bundle, Dirty Worktree Release Coverage, and exact review-only `git add` commands. When release context is supplied, the Public Release Operator Runbook preserves the same release/user/target context; it does not stage files, publish releases, upload to PyPI, mutate remotes, or claim traction |
| `proof-pack --username <username> --framework <framework> --release-tag <tag> --target-contributors <N>` | No-Network First Public Proof Pack with Growth/Share/Bounty Issue URLs, created-Issue placeholders, Community Challenge Pack for Tournament/Mentor/Sect/Season routes, a Protected Publish Fallback command, Git Tag Candidate Install Bridge plus Candidate Install Smoke Gate, Install Decision Surface / `current_install_command` route, Growth and Bounty `record-return` CLI ledger commands, Share `record-share` attribution, an External Contributor Path with pasted Recommended Install / first-session command / first contribution command / Share Proof Issue URL / contributor-counting rule, recheck commands, and copy-ready proof text; it does not fetch public metrics, close the PyPI install loop, or invent traction |
| `market-copy --username <username> --framework <framework> --release-tag <tag> --target-contributors <N>` | Marketplace Submission Copy Pack with PyPI listing copy, Claude MCPB listing copy, Codex plugin listing copy, GitHub Release post, public proof CTA, Community Challenge Pack, Git Tag Candidate Install Bridge plus Candidate Install Smoke Gate, project URLs, install/validation commands, Marketplace Submission Ledger commands, and non-fabrication rules for market submission |
| `record-market --username <username> --framework <framework> --channel <channel> --status <status> --submission-url <https-url> --release-tag <tag>` | Record a reviewable public URL for PyPI, Claude Code, Claude Desktop MCPB, Codex, GitHub Release, or agent-marketplace submission evidence into the local Marketplace Submission Ledger |
| `market-status --username <username> --framework <framework> --release-tag <tag>` | Report latest Marketplace Submission Ledger status by channel with missing record-market commands and traction-proof rechecks |
| `flywheel --username <username> --framework <framework> --sect <sect-name> --members <members...>` | Soul Ring Growth Flywheel with real bottleneck, next commands, and missing metric disclosure |
| `ladder <username> --framework <framework>` | 🔮 Soul Ring breakthrough ladder — real next gate, full thresholds, and copy-ready chase commands |
| `evidence <username> --framework <framework> --amount <N> --source-url <https-url>` | Soul Ring Evidence Card with append-only reviewable public evidence for high-realm gates; progress, ranks, rewards, downloads, and contributors are not invented |
| `ranking <username>` | 🏆 个人排名 — title, rank & soul rings |
| `leaderboard` | 🏆 全球封神榜 — top alchemists ranked |
| `card <username>` | 📋 分享卡片 — cyberpunk cultivation archive |
| `badge <username>` | 🔮 GitHub Profile badge kit — pasteable soul-ring badge |
| `visual <username> --framework <framework> --output-dir <dir>` | Soul Ring Visual Artifact — writes a chat-visible animated GIF plus PNG fallback and returns Markdown image embeds for Codex, Claude, and other agent chats |
| `quest <username> --framework <framework>` | 🔮 Soul Ring quest board — mine, upload, share |
| `campaign <username> --framework <framework>` | 🔮 Soul Ring campaign pack — GitHub Profile, X/Weibo, PR comment & agent prompt |
| `duel <challenger> <rival> --framework <framework>` | 🔮 Soul Ring duel card — invite a real GitHub user into a verified contribution race |
| `mentor <mentor> <apprentice> --framework <framework>` | 🔮 Soul Ring mentor pact — turn a senior contributor into a first-ring onboarding guide |
| `arena <username> --top-n <N>` | 🔮 Soul Ring arena snapshot — shareable real leaderboard with your next rival |
| `season --framework <framework> --top-n <N>` | 🔮 Soul Ring season board — current real leaderboard event pack with champion, next chase, and share copy |
| `sect <sect-name> <members...> --framework <framework>` | 🔮 Soul Ring sect card — aggregate real GitHub members into a shareable team banner |
| `sect-recruit <sect-name> <members...> --invitee <github> --framework <framework>` | 🔮 Soul Ring sect recruitment scroll — invite one real GitHub user with an admission trial and join command |
| `sect-quest <sect-name> <members...> --framework <framework>` | 🔮 Soul Ring sect quest board — assign real next actions across team members |
| `sect-hall <sect-name> <members...> --framework <framework>` | 🔮 Soul Ring sect hall — assign Outer / Inner / Core / Deacon / Elder posts from real member counts |
| `sect-duel <challenger-sect> <rival-sect> --challenger-members <members...> --rival-members <members...> --framework <framework>` | 🔮 Soul Ring sect duel card — compare two real GitHub teams and invite a team challenge |
| `sect-arena --sect <sect-name> <members...> --sect <sect-name> <members...> --framework <framework>` | 🔮 Soul Ring sect arena snapshot — rank multiple real GitHub teams and publish the next chase |
| `record` | 📋 诊疗档案 — diagnosis history & follow-ups |
| `subscribe` | 📬 框架订阅 — get notified about new prescriptions |
| **⛏️ Contribution / 知识贡献** | |
| `save` | 📥 保存药方到本地 |
| `upload` | 🌐 上传药方到 GitHub (需 GITHUB_TOKEN) |
| `mine search/batch` | ⛏️ GitHub Issues 淘金提炼 |
| **🚀 Server / 服务** | |
| `serve` | 🚀 启动 Web 诊断服务 |
| `rebuild` | 🔄 重建向量索引 |

## Soul Ring Visual Route

Run `cyberhuatuo visual <username> --framework <framework>` in the CLI or call MCP `soul_ring_visual_artifact` to generate a Markdown-rendered GIF plus PNG fallback. The artifact uses current real contribution data and does not invent ranks, downloads, retention, referrals, or rewards.

> 💡 **Tip**: Run `cyberhuatuo <command> --help` for detailed usage of any command.
>
> 💡 **提示**: 运行 `cyberhuatuo <命令> --help` 查看任何命令的详细用法。

---

## 🔌 MCP Server — AI Editor Integration

> *Install once. Every AI editor becomes a CyberHuaTuo clinic.*
>
> *一次安装，所有 AI 编辑器都变成赛博华佗诊所。*

### ⚡ Install — One Command

```bash
python -m pip install --upgrade "cyberhuatuo @ git+https://github.com/JinNing6/CyberHuaTuo-Plugin.git@v0.2.5"
python -m pip install --upgrade cyberhuatuo  # after PyPI latest matches v0.2.5
```

> Candidate Git tag install should pass `python -m cyberhuatuo candidate-install-smoke` before outside contributor invites; after PyPI latest-version proof is current, use the registry command. Brand Matrix aliases are for the registry-current path only.

### 🔗 Connect to Your AI Editor

Add this to your AI tool's MCP config (Claude Desktop / Cursor / VS Code / Gemini CLI):

```json
{
  "mcpServers": {
    "cyberhuatuo": {
      "command": "uvx",
      "args": ["--from", "cyberhuatuo", "cyberhuatuo-mcp"]
    }
  }
}
```

> `uvx` auto-installs from PyPI and starts the MCP Server — zero manual setup.
> For GitHub latest dev version, use: `"args": ["--from", "git+https://github.com/JinNing6/CyberHuaTuo-Plugin", "cyberhuatuo-mcp"]`

### 🧩 Plugin Manifests — Codex + Claude Code

This repository is plugin-ready for both major coding-agent hosts:

- **Codex**: `.codex-plugin/plugin.json` points to `./skills/` and `./.mcp.json`.
- **Claude Code**: `.claude-plugin/plugin.json` points to the same `./skills/` and `./.mcp.json`.
- **Codex marketplace catalog**: `.agents/plugins/marketplace.json` lets users add this GitHub repository as a Codex plugin marketplace.
- **Claude Code marketplace catalog**: `.claude-plugin/marketplace.json` lets users add this GitHub repository as a Claude Code plugin marketplace.

Marketplace install:

```bash
claude plugin marketplace add JinNing6/CyberHuaTuo-Plugin
claude plugin install cyberhuatuo-plugin@cyberhuatuo

codex plugin marketplace add JinNing6/CyberHuaTuo-Plugin
```

For local Claude Code testing from the repository root:

```bash
claude --plugin-dir .
```

### 🚀 Marketplace Release Path

The release plan is tracked in [`docs/MARKETPLACE_RELEASE.md`](docs/MARKETPLACE_RELEASE.md):

- **PyPI Trusted Publishing**: `cyberhuatuo` already exists on PyPI, so this repository must be added as an additional Trusted Publisher, then release a version newer than `0.1.0` through `.github/workflows/publish-pypi.yml`. The workflow supports `release.published` and a protected manual `workflow_dispatch` `release_tag` fallback; both paths require an existing `v*` tag, verify the tag is reachable from `origin/main`, verify the package version matches the tag, and publish with OIDC instead of `PYPI_TOKEN`.
- **Claude markets**: ship Claude Code through `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`, submit to Anthropic's official directory after `claude plugin validate .`, then package Claude Desktop through `claude-desktop/manifest.json` plus `.github/workflows/package-claude-mcpb.yml` for MCPB / Connectors Directory submission.
- **Codex plugin directory**: keep `.codex-plugin/plugin.json`, `.agents/plugins/marketplace.json`, `.mcp.json`, and the PyPI `uvx --from cyberhuatuo cyberhuatuo-mcp` entrypoint stable for workspace rollout.

### 🩺 Available MCP Tools

| Tool | Description |
|------|-------------|
| **🩺 Core Diagnosis / 核心诊断** | |
| `diagnose` | 🩺 望闻问切 AI diagnosis — searches **both** 📜 permanent expert + ⚡ temporary intern prescriptions |
| `search_knowledge_base` | 🔍 Dual-layer semantic search (ChromaDB + GitHub Issues) |
| `security_checkup` | 🛡️ Six-meridian security audit on your Agent code |
| `fetch_official_docs` | 📚 Real-time official docs via Context7 (50+ frameworks) |
| **⛏️ Knowledge & Contribution / 知识贡献** | |
| `mine_github_issue` | ⛏️ Extract & refine GitHub Issues into standard cases |
| `save_prescription` | 📥 Save prescriptions locally + auto-sync to GitHub |
| `upload_prescription` | 🌐 Upload prescriptions — auto-creates GitHub Issue (⚡ temporary intern), CI promotes to 📜 permanent expert |
| `prescription_eval` | 📊 Unified prescription evaluation — cite, feedback, expire, verify, and leaderboard |
| `mentorship` | 🎓 Senior alchemists review junior prescriptions — pending, review, profile, leaderboard |
| **🧬 Alchemist System / 炼丹师体系** | |
| `my_contribution_stats` | 🏅 **修为档案** — 16-tier Alchemist title + soul ring directions |
| `check_my_ranking` | 🏆 **全球排名** — coronation art, streak tracking & community milestones |
| `global_leaderboard` | 🏆 **封神榜** — top alchemists ranked by contribution count |
| `my_share_card` | 📋 **分享卡片** — generate a cyberpunk cultivation archive card |
| `my_medical_record` | 📋 **就诊档案** — personal diagnosis history, stats & follow-ups |
| **🔬 Health & Analytics / 健康分析** | |
| `epidemic_alert` | 🦠 **疫情预警** — framework health monitoring, scan & epidemic reports |
| `cht_taxonomy` | 🔬 CHT Root Cause Coding System — list, lookup & auto-classify errors |
| `cht_trends` | 📊 CHT code trend analysis — heatmaps, top causes & surge alerts |
| `list_frameworks` | 📋 List all supported frameworks & tech stacks (filterable by category) |
| `subscribe_framework` | 🔔 Subscribe to framework updates — get notified about new prescriptions |
| `weekly_digest` | 📰 Weekly prescription digest — new cases by framework & severity |

> 👉 **Full configuration guide: [README_MCP.md](README_MCP.md)**

### 💊 Dual-Layer Prescription Architecture

### 双层药方库架构

> *Medicine first exists, then it is refined.*
>
> *药方先存在，再被整理。*

```
  📤 User uploads prescription via MCP
           │
           ├── Owner? ──→ Direct push to main (📜 Permanent Expert)
           │
           └── External? ──→ Create GitHub Issue (⚡ Temporary Intern)
                                    │
                              Instantly searchable!
                                    │
                              CI auto-validates
                                    │
                          ┌─────────┴─────────┐
                          │                   │
                     ✅ Passed            ❌ Failed
                   Commit .md to         Close Issue
                   main branch          (filtered 🚫)
                  (📜 Promoted ✨)
```

| Layer | Carrier | Access | Features |
|:-----:|:-------:|:------:|:--------:|
| 📜 **Permanent Expert** | `cases/*.md` (main branch) | CI-reviewed only | Shipped with PyPI, always available |
| ⚡ **Temporary Intern** | GitHub Issues (labeled) | Any GitHub user | Instant upload, zero permission needed |

**When you search**, `diagnose` and `search_knowledge_base` query **both layers** simultaneously — results are tagged `📜` or `⚡` so you know their review status.

**当你搜索时**，`diagnose` 和 `search_knowledge_base` **同时查询两层** — 结果会标注 `📜 常驻主任专家` 或 `⚡ 临时医学实习生` 来源。

### 🎒 Agent Skills Protocol (Self-Rescue)

We support the open **Agent Skills** standard (`SKILL.md`). You can empower your own AI assistants (Cursor, Copilot, Claude Code) to automatically seek help from CyberHuaTuo when they get stuck.

Simply copy the `skills/cyberhuatuo-rescue` directory into your project's `.cursor/rules` or `.agent/skills` folder. Your AI will learn to automatically diagnose errors and run security checkups using CyberHuaTuo's knowledge base.

The plugin also ships `skills/cyberhuatuo-soul-ring-visual`: when a user asks about level, rank, badge, soul ring, cultivation status, visual display, animation, 等级, 魂环, 排名, 徽章, 卡片, 展示, or 动图, the agent should generate the real-data Markdown GIF plus PNG fallback via `soul_ring_visual_artifact` or `cyberhuatuo visual`.

---

## 🧬 Alchemist Cultivation System — Your Journey to Immortality

**炼丹师修为体系 — 从凡人到封神的修炼之路**

> *In the world of CyberHuaTuo, you are not a developer who fixes bugs.*
> *You are an **Alchemist** — forging prescriptions, accumulating soul rings, ascending through 16 tiers of mastery.*
>
> *在赛博华佗的世界里，你不是修 bug 的程序员。*
> *你是**炼丹师**——炼制药方、凝聚魂环、攀登十六重天的封神阶梯。*

We turned bug fixing into a **cultivation journey**. Every prescription you upload earns you a rank on the **Alchemist Ladder (炼丹师阶梯)** — a 16-tier system based on your **global percentile**. The bigger the community grows, the harder it is to climb — and the more prestigious your title becomes.

**开发者修一个 Bug，炼丹师铸一颗丹。** 你在这里的每一次贡献，都会被铭刻在全球封神榜上——而你的称号，随着社区壮大而愈加珍贵。

### 🔮 Soul Ring System — Your Combat Resume (魂环体系 — 你的战斗简历)

> *Inspired by Soul Land (斗罗大陆) — every framework you master forges a Soul Ring orbiting your profile.*
>
> *灵感源自斗罗大陆——你掌握的每个技术栈，都会凝聚为一道魂环。*

<p align="center">
  <img src="assets/cli_soul_ring.gif" alt="CyberHuaTuo Soul Ring Hologram — Five-Ring Soul Refining + Ranking Scan" width="100%"/>
  <br>
  <sub><strong>🔮 魂环全息投影 · Soul Ring Hologram</strong></sub><br>
  <sub>五环炼魂丹师 → 同心环 ASCII Art → 排名全息扫描 → 丹王称号揭示</sub>
</p>

Soul Rings grow in **color and power** as you contribute more prescriptions to a specific direction:

```
   ⚪ 白环 (1)      入门 · First Touch
   🟡 黄环 (2-3)    初窥 · Getting Serious
   🟡🟡 双黄 (4-6)  小成 · Solid Foundation
   🟡🟡🟣 三环 (7-10)   突破 · Breakthrough
   🟡🟡🟣🟣 四环 (11-15)  精通 · Mastery
   🟡🟡🟣🟣⚫ 五环 (16-25)  大师 · Grandmaster
   🟡🟡🟣🟣⚫⚫ 六环 (26-40)  宗师 · Sovereign
   🟡🟡🟣🟣⚫⚫🔴 七环 (41-60)  封号 · Titled
   🟡🟡🟣🟣⚫⚫🔴🔴 八环 (61-80) 传奇 · Legendary
   🟡🟡🟣🟣⚫⚫🔴🔴✨ 九环至尊 (81+) 至尊 · Supreme
```

Every ranking and share-card output keeps the **next upgrade** visible, so the first contribution immediately becomes a chase:

```text
🔥 炼魂(Soul Refining) × 1方 ⚪ 一环 · LangChain
   ↳ 下一环: 黄环 · 再贡献 1 方即可点亮。
```

> **An alchemist with 5 PyTorch rings and 3 LangChain rings tells a different story than one with 8 CrewAI rings.**
>
> **Your soul rings are your combat resume — visible, verifiable, unforgeable.**
>
> *拥有 5 环 PyTorch 和 3 环 LangChain 的炼丹师，与 8 环 CrewAI 的炼丹师，修为截然不同。*
> ***魂环就是你的战斗简历——可见、可查、不可伪造。***

### ⚗️ Six Alchemy Directions — Choose Your Path (六大丹术方向 — 选择你的道)

> *Every great alchemist has a specialty. What's yours?*
>
> *每个传奇炼丹师都有专精。你的道，在哪里？*

<table>
<tr>
<td align="center" width="33%">

**🔥 炼魂 · Soul Refining**

驾驭智能体，调教灵魂

*LangChain · CrewAI · AutoGen*
*LlamaIndex · LangGraph · MCP*

</td>
<td align="center" width="33%">

**⚡ 雷火 · Thunder Fire**

锻造算力，淬炼模型

*PyTorch · TensorFlow*
*Transformers · LiteLLM*

</td>
<td align="center" width="33%">

**🛡️ 护体 · Body Shield**

金丹护体，抵御外邪

*Security · Sandbox*
*Guardrails · Hardening*

</td>
</tr>
<tr>
<td align="center" width="33%">

**🌊 化毒 · Detox**

通百脉，解百毒

*Python · JavaScript*
*General Debugging*

</td>
<td align="center" width="33%">

**⚙️ 器灵 · Soul Craft**

炼器辅丹，基础设施

*FastAPI · Docker · K8s*
*Vertex AI · Vercel*

</td>
<td align="center" width="33%">

**🧬 造化 · Genesis**

造化之力，驾驭天道

*OpenAI · Anthropic*
*Gemini · Groq · Mistral*

</td>
</tr>
</table>

> *When you contribute a LangChain prescription, your 🔥 Soul Refining ring grows. Fix a Docker issue? Your ⚙️ Soul Craft ring levels up. Each direction is an independent cultivation path — master one, or conquer them all.*
>
> *当你贡献一个 LangChain 药方，🔥 炼魂环增长。修复了 Docker 问题？⚙️ 器灵环升级。每个方向都是独立的修炼路线——精通一道，或六道通神。*

### ⚡ Instant Rewards — Dopamine by Design (即时反馈 — 多巴胺驱动)

> *The best games don't make you wait for the reward. Neither do we.*
>
> *最好的游戏不会让你等待奖励。我们也不会。*

Every `upload_prescription` triggers an **instant cascade of rewards**:

```
  💊 You upload a prescription
       │
       ├──→ 🎭 INSTANT CORONATION — ASCII art + new title revealed
       │    ┌────────────────────────────────────────┐
       │    │  ⭐ 当前修为: 三星炼丹师 · Three-Star  │
       │    │  🏅 全球排位: #12 / 31 (超越 63% 炼丹师) │
       │    │  继续炼丹，攀登炼丹师终极阶梯！        │
       │    └────────────────────────────────────────┘
       │
       ├──→ 💍 SOUL RING UPGRADE — Your rings grow in real-time
       │    🔥 炼魂(Soul Refining) × 5方 🟡🟡🟣🟣⚫ 五环
       │
       ├──→ 🔥 STREAK FIRE — Consecutive days trigger milestones
       │    🔥 3-day → 🔥🔥 7-day → 🔥🔥🔥 14-day → 💎🔥 30-day
       │
       ├──→ 📋 SHARE CARD — Cyberpunk cultivation archive
       │    ╔════════════════════════════════════════╗
       │    ║  🩺 赛博华佗 · 修为档案                ║
       │    ║  ⭐ 三星炼丹师 · Three-Star Alchemist  ║
       │    ║  🔥 炼魂丹师 · 🟡🟡🟣🟣⚫            ║
       │    ║  🧭 战绩方向: LangChain                ║
       │    ║  🔮 下一环: 黄环 · 再贡献 1 方即可点亮。║
       │    ║  💊 贡献: 8 段 | 🧪 ██████░░░░░░ 40%  ║
       │    ║  ▓█▓░░▓███▓░░▓█▓░░▓█████▓░░▓█▓      ║
       │    ╚════════════════════════════════════════╝
       │
       └──→ 📡 COMMUNITY MILESTONE — Global celebration
            🎉 "知识库突破 100 个药方！赛博医者的力量正在汇聚。"
```

### 🙏 灵感致敬 · Tribute

> *The greatest creations are always born from the shoulders of giants — and the dreams of children.*
>
> *最伟大的创造，总是站在巨人的肩膀上——和孩子们的梦想之中。*

<table>
<tr>
<td align="center" width="33%">

**🔥 斗破苍穹**
*Battle Through the Heavens*

炼丹师阶梯体系
*Alchemist Tier System*

</td>
<td align="center" width="33%">

**💍 斗罗大陆**
*Soul Land*

魂环修炼体系
*Soul Ring System*

</td>
<td align="center" width="33%">

**🏥 华佗传说**
*Legend of Hua Tuo*

望闻问切 · 悬壶济世
*Ancient Healing · Open Source*

</td>
</tr>
</table>

> *These works gave an entire generation of developers their most unforgettable memories — of cultivation, of perseverance, of the belief that anyone can ascend through sheer will.*
>
> *这些作品给了整整一代开发者最难以忘怀的记忆——关于修炼、关于坚持、关于"凡人也能登顶"的信念。*
>
> *CyberHuaTuo inherits this spirit: **from ancient legend, through modern fantasy, into the cyber future.***
>
> *赛博华佗传承这份精神：**从古代传说，穿越当代幻想，走向赛博未来。***

---

## 🌐 Brand Matrix — Why So Many Package Names?

## 品牌矩阵 — 为什么注册这么多包名？

> *Hua Tuo traveled across provinces. Asclepius healed across islands. Healing knows no borders.*
>
> *华佗行走于山川之间，阿斯克勒庇俄斯穿梭于海岛之上。医道无疆。*

CyberHuaTuo maintains a series of **official alias packages** on PyPI, spanning medical deities and pioneers from both Eastern and Western traditions:

| Lineage | Packages |
|---------|----------|
| 🏮 **Eastern Divine Physicians** (Core) | `cyberhuatuo`, `openhuatuo` |
| 🏛️ **Greco-Roman Mythology** | `cyber-asclepius`, `open-asclepius`, `cyber-panacea`, `open-panacea` |
| 📜 **Pioneers of Medicine*

More

• More mcp servers on No topic detected
• Everything published by jinning6
• Browse the whole catalog