# 中医 AI Agent 系统 v2.0

基于 **Go + MaxKB + 多模型工厂** 的专业领域 AI Agent 脚手架。

## 🆕 v2.0 核心升级：模型工厂模式

**一个系统，多种模型，按场景自动路由，主挂了自动降级。**

```
┌─────────────────────────────────────────────────────────────┐
│                      HTTP API Layer (Gin)                    │
│         /api/v1/emr  /api/v1/prescription  /api/v1/agent   │
├─────────────────────────────────────────────────────────────┤
│                    Handler Layer (业务编排)                   │
│         参数校验 → 调用Agent → 持久化 → 响应封装             │
├─────────────────────────────────────────────────────────────┤
│                   Agent Engine (核心引擎)                     │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  Runner → Planner → LLM → Tool Call → Reflect → Out  │  │
│  └────────────────────────────────────────────────────────┘  │
├──────────────┬──────────────┬───────────────────────────────┤
│  Tool Set    │  Rule Engine │     Memory & Session          │
│  ├ MaxKB检索 │  十八反十九畏 │     短期：Session History     │
│  ├ HIS查询   │  剂量校验    │     长期：向量数据库           │
│  ├ 药典查询  │  孕妇禁忌    │                              │
│  └ 规则校验  │  术语规范    │                              │
├──────────────┴──────────────┴───────────────────────────────┤
│              LLM 模型工厂（v2.0 核心）                      │
│  ┌───────────────────────────────────────────────────────┐   │
│  │  Factory → Router → FallbackChain                    │   │
│  │  ├ deepseek (病历生成主力)                         │   │
│  │  ├ openai/gpt-4o (处方校验)                      │   │
│  │  ├ qwen-max (中文知识问答)                       │   │
│  │  ├ azure (企业合规部署)                          │   │
│  │  └ ollama (本地离线兜底)                         │   │
│  └───────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────┤
│                    External Services                          │
│         MaxKB (RAG)  │  LLM APIs  │  HIS  │  MySQL        │
└─────────────────────────────────────────────────────────────┘
```

## 🏗️ 架构亮点

### 模型工厂三件套

| 组件 | 职责 | 类比 |
|------|------|------|
| **ProviderFactory** | 注册/创建各供应商客户端 | 汽车工厂 |
| **ModelRouter** | 按场景名路由到对应模型 | GPS 导航 |
| **FallbackChain** | 主模型挂了自动切备用 | 备用轮胎 |

### 场景 → 模型映射（config.yaml 配置）

| 业务场景 | 路由到 | 为什么 |
|----------|--------|--------|
| 病历生成 (emr-generator) | DeepSeek V3 | 中文医学知识丰富，推理链清晰 |
| 处方校验 (prescription) | GPT-4o | 推理严谨，工具调用稳定 |
| 知识问答 (knowledge-qa) | 通义千问 Max | 中文检索效果好 |
| 向量化 (embedding) | text-embedding-3-small | 质量行业领先 |
| 降级兜底 (fallback) | Ollama 本地 | 离线可用，零成本 |

**改模型只需改 config.yaml，不改一行代码。**

## 快速开始

### 1. 启动 MaxKB 知识库

```bash
docker run -d --name maxkb -p 8080:8080 1panel/maxkb
```

访问 http://localhost:8080 上传中医典籍、药典、病历模板。

### 2. 配置（多模型）

编辑 `manifest/config/config.yaml`：

```yaml
llm:
  default_provider: "deepseek"
  models:
    deepseek:
      provider: "deepseek"
      api_key: "sk-你的key"
      base_url: "https://api.deepseek.com"
      model: "deepseek-chat"
    openai:
      provider: "openai"
      api_key: "sk-你的key"
      base_url: "https://api.openai.com/v1"
      model: "gpt-4o"
  routes:
    emr-generator: "deepseek"
    prescription:  "openai"
```

### 3. 运行

```bash
go mod tidy
go run main.go
```

### 4. 运行模拟演示

```bash
go run examples/simulation.go
```

将看到：
- 模型工厂创建各供应商客户端
- 路由表展示场景→模型映射
- 降级链工作原理
- 两个完整业务场景的 Agent 生命周期

## API 接口

### 生成病历

```bash
curl -X POST http://localhost:8080/api/v1/emr/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "patient_id": "P001",
    "chief_complaint": "反复头晕3个月，加重1周",
    "history_notes": "患者3个月前无明显诱因出现头晕...",
    "allergies": [],
    "past_illness": ["慢性胃炎"]
  }'
```

### 生成处方

```bash
curl -X POST http://localhost:8080/api/v1/prescription/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "patient_id": "P001",
    "emr_text": "主诉：反复头晕3个月...舌暗红苔白腻 脉弦滑...",
    "diagnosis": "痰湿中阻证",
    "age": 45,
    "is_pregnant": false,
    "allergies": []
  }'
```

### 动态切换模型路由（热更新）

```bash
curl -X POST http://localhost:8080/api/v1/models/route \
  -H "Content-Type: application/json" \
  -d '{"scene": "emr-generator", "provider": "gpt-4o"}'
```

### 查看当前路由表

```bash
curl http://localhost:8080/api/v1/models/routes
```

## 项目结构

```
tcm-agent/
├── main.go                          # 入口（初始化链：config→llm→agent→router）
├── go.mod
├── Makefile
├── README.md
│
├── examples/
│   └── simulation.go               # 场景模拟演示（含模型工厂演示）
│
├── docs/
│   └── agent_lifecycle.md         # Agent 生命周期详解
│
├── manifest/
│   ├── config/config.yaml         # 配置文件（多模型+路由+降级）
│   └── docker/
│       ├── Dockerfile
│       └── docker-compose.yml
│
├── test/
│   └── agent_test.go             # 单元测试（工厂/路由/降级/规则引擎）
│
└── internal/
    ├── config/config.go           # 配置加载（多模型支持）
    │
    ├── llm/                       # 🆕 模型工厂层（v2.0 核心）
    │   ├── factory.go             # 工厂+路由+降级（统一接口定义）
    │   ├── deepseek.go           # DeepSeek 客户端
    │   ├── openai.go             # OpenAI 客户端
    │   └── other_providers.go    # Azure/Ollama/Qwen/Mock
    │
    ├── agent/                     # Agent 引擎
    │   ├── runner.go             # 核心调度器（使用 ModelRouter）
    │   ├── emr_agent.go         # 病历生成 Agent
    │   └── prescription_agent.go # 处方生成 Agent
    │
    ├── tool/                      # Agent 工具集
    │   ├── maxkb.go             # MaxKB 知识库客户端
    │   └── agent_tools.go       # 工具注册（知识检索/HIS/药典/规则）
    │
    ├── rule/                     # 规则引擎
    │   └── rule_engine.go       # 配伍禁忌/剂量/质控
    │
    ├── handler/                  # HTTP 处理器
    │   ├── emr_handler.go
    │   ├── prescription_handler.go
    │   ├── knowledge_handler.go
    │   └── agent_handler.go
    │
    ├── router/router.go          # 路由注册（含模型管理接口）
    ├── middleware/middleware.go  # 日志/CORS/鉴权
    ├── dao/dao.go                # 数据访问层
    └── model/entity/entity.go   # 数据模型
```

## 安全设计

### 三层防护

1. **知识防线**：MaxKB 提供权威药典/典籍/指南
2. **规则防线**：代码级硬校验（十八反、十九畏、剂量上限）
3. **人工防线**：医生最终审核（Human-in-the-Loop）

### 审计日志

所有关键操作（生成、修改、审核）全链路记录，满足医疗合规要求。

## 扩展指南

### 接入新模型供应商

只需 3 步：

1. **实现 LLMClient 接口**（`internal/llm/your_provider.go`）：
   ```go
   type YourClient struct{ ... }
   func (c *YourClient) Chat(ctx, messages, tools) (*Message, error) { ... }
   func (c *YourClient) Embed(ctx, texts) ([][]float32, error) { ... }
   // ... 实现其他接口方法
   ```

2. **注册到工厂**（`internal/llm/factory.go` 的 `NewProviderFactory` 中）：
   ```go
   f.Register("your-provider", createYourClient)
   ```

3. **在 config.yaml 中添加配置**：
   ```yaml
   llm:
     models:
       your-model:
         provider: "your-provider"
         api_key: "your-key"
         base_url: "https://api.your-provider.com"
         model: "your-model-name"
     routes:
       emr-generator: "your-model"  # 切换病历生成到新模型
   ```

**无需修改任何业务代码。**

## 测试

```bash
# 运行全部测试
make test

# 运行规则引擎测试
make test-rule

# 运行 Agent 测试
make test-agent
```

## License

MIT