eryao/docs/references/divination-agent-api-reference.md

# 算卦 Agent API Reference

## 1. API Endpoint

- **URL**: `POST https://meeyao.com.cn/api/deepseek/chat`
- **认证**: 需要通过 `AuthInterceptor` 注入用户 token

---

## 2. 请求结构

### 2.1 DeepSeekRequest (请求体)

```kotlin
data class DeepSeekRequest(
    val model: String = "deepseek-chat",
    val messages: List<DeepSeekMessage>,
    val temperature: Double = 0.7,
    val max_tokens: Int = 2048,
    val stream: Boolean = false
)
```

### 2.2 DeepSeekMessage

```kotlin
data class DeepSeekMessage(
    val role: String,      // "system" 或 "user"
    val content: String    // 系统提示词或用户提示词(含卦象JSON)
)
```

### 2.3 DivinationInfo (卦象信息 JSON)

```kotlin
data class DivinationInfo(
    // 用户信息
    val question: String,           // 用户问题
    val questionType: String,       // 问题类型 (如"事业"、"感情"、"健康")

    // 起卦时间信息
    val divinationTime: String,     // 起卦时间 "2024年06月01日 12:00"
    val yearGanZhi: String,         // 年干支 "甲子"
    val monthGanZhi: String,        // 月干支
    val dayGanZhi: String,          // 日干支
    val timeGanZhi: String,         // 时干支

    // 干支空亡信息
    val yearKongWang: String,       // 年空亡 "戌亥"
    val monthKongWang: String,      // 月空亡
    val dayKongWang: String,        // 日空亡
    val timeKongWang: String,       // 时空亡

    // 月建日辰信息
    val yueJian: String,            // 月建 "寅木"
    val riChen: String,             // 日辰 "午火"
    val yuePo: String,              // 月破
    val riChong: String,            // 日冲

    // 五行旺衰
    val wuXingStatuses: Map<String, String>,  // 五行旺相休囚死状态

    // 本卦信息
    val guaName: String,            // 卦名 "坤为地"
    val upperName: String,          // 上卦名称
    val lowerName: String,          // 下卦名称
    val worldPosition: Int,         // 世爻位置 (1-6)
    val responsePosition: Int,      // 应爻位置 (1-6)

    // 六爻信息
    val yaoInfoList: List<YaoDetailInfo>,

    // 变卦信息
    val hasChangingYao: Boolean,    // 是否有动爻
    val targetGuaName: String,       // 变卦名称
    val targetYaoInfoList: List<YaoDetailInfo>
)
```

### 2.4 YaoDetailInfo (爻详细信息)

```kotlin
data class YaoDetailInfo(
    val position: Int,          // 爻位置 (1-6: 初爻到上爻)
    val spiritName: String,     // 神煞 (龙/雀/勾/蛇/虎/玄)
    val relationName: String,   // 六亲 (兄弟/父母/官鬼/妻财/子孙)
    val tiganName: String,      // 地支 (子/丑/寅...)
    val elementName: String,    // 五行 (金/木/水/火/土)
    val isYang: Boolean,        // 阴阳属性
    val isChanging: Boolean,   // 是否为动爻
    val specialMark: String     // 特殊标记 (世/应/"")
)
```

---

## 3. 响应结构

### 3.1 DeepSeekResponse

```kotlin
data class DeepSeekResponse(
    val id: String,
    val choices: List<DeepSeekChoice>
)

data class DeepSeekChoice(
    val message: DeepSeekMessage?,  // 包含 AI 回复内容
    val finish_reason: String?
)

data class DeepSeekMessage(
    val role: String,
    val content: String            // AI 返回的解卦结果
)
```

---

## 4. 系统提示词 (System Prompt)

```
## 角色
你是一个六爻解卦专家，熟悉六爻解卦步骤以及给出对应的解卦结果...

## 输出格式要求
- 单独在最开头输出一句话概括卦象的吉凶
- 输出顺序：解卦结论、卦象重点、卦象建议、关键词
- 格式：解卦结论：1、… 2、…；卦象重点：1、… 2、…；卦象建议：1、… 2、…；关键词：…
- 关键词：三个四字成语
```

### 4.1 吉凶等级

| 等级 | 描述 |
|------|------|
| 上上签 | 卦象结果较好，完成某事容易或最终结果好 |
| 中上签 | 卦象结果一般，需很努力才能完成或效果一般 |
| 中下签 | 卦象结果较差，即使很努力也无法完成或结果不好 |

---

## 5. 字段说明

### 5.1 字段名与含义对照表

| 字段名 | 含义 | 示例 |
|--------|------|------|
| `divinationTime` | 起卦时间 | "2024年06月01日 12:00" |
| `yearGanZhi` | 年柱天干地支 | "甲子" |
| `monthGanZhi` | 月柱天干地支 | "丙寅" |
| `dayGanZhi` | 日柱天干地支 | "戊午" |
| `timeGanZhi` | 时柱天干地支 | "庚子" |
| `yearKongWang` | 年柱空亡地支 | "戌亥" |
| `yueJian` | 月建 | "寅木" |
| `riChen` | 日辰 | "午火" |
| `yuePo` | 月破 | "申金" |
| `riChong` | 日冲 | "子水" |
| `guaName` | 本卦卦名 | "坤为地" |
| `upperName` | 上卦名称 | |
| `lowerName` | 下卦名称 | |
| `worldPosition` | 世爻位置 | 1-6 |
| `responsePosition` | 应爻位置 | 1-6 |
| `hasChangingYao` | 是否有动爻 | true/false |
| `targetGuaName` | 变卦卦名 | |

### 5.2 六神 (spiritName)

| 神煞 | 含义 |
|------|------|
| 龙 | 青龙 |
| 雀 | 朱雀 |
| 勾 | 勾陈 |
| 蛇 | 螣蛇 |
| 虎 | 白虎 |
| 玄 | 玄武 |

### 5.3 六亲 (relationName)

| 六亲 | 含义 |
|------|------|
| 兄弟 | |
| 父母 | |
| 官鬼 | |
| 妻财 | |
| 子孙 | |

### 5.4 地支 (tiganName)

子、丑、寅、卯、辰、巳、午、未、申、酉、戌、亥

### 5.5 五行 (elementName)

金、木、水、火、土

---

## 6. Source

- Android App: `old/app/src/main/java/com/example/eryaoapp/api/DivinationRepository.kt`
- Request Models: `old/app/src/main/java/com/example/eryaoapp/api/model/DivinationRequest.kt`
- API Service: `old/app/src/main/java/com/example/eryaoapp/api/DeepSeekApiService.kt`