# ty-chat

**Repository Path**: ty-cloud/ty-chat

## Basic Information

- **Project Name**: ty-chat
- **Description**: ty-chat
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-03
- **Last Updated**: 2026-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DeepSeek 智能对话客户端 (生产版)

一个生产级的 Java 多轮对话客户端，基于 DeepSeek API，支持**初始内容注入 + 多轮问答**场景。

---

## 功能特性

| 特性 | 说明 |
|------|------|
| 🎯 **初始内容上下文** | 启动时批量注入事实内容，所有回答基于此内容 |
| 💬 **多轮对话** | 完整维护对话历史，支持上下文关联问答 |
| 🔄 **自动重试** | 指数退避重试机制（429/5xx 错误） |
| 🛡️ **生产级配置** | 多环境 profile、外部配置文件、环境变量覆盖 |
| 📝 **对话日志** | 自动落盘，含 Token 使用量统计 |
| ⚡ **零额外依赖** | 仅依赖 Gson，使用 JDK 11+ 内置 HttpClient |
| 🔐 **密钥安全** | 支持环境变量注入，不硬编码密钥 |

---

## 快速开始

### 1. 环境要求

- JDK 11 或更高版本
- Maven 3.6+
- DeepSeek API Key（[申请地址](https://platform.deepseek.com/)）

### 2. 设置 API Key（生产环境推荐方式）

**Windows PowerShell:**
```powershell
$env:DEEPSEEK_API_KEY = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

**Windows CMD:**
```cmd
set DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

**Linux / macOS:**
```bash
export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

### 3. 配置初始内容

编辑 `src/main/resources/initial-context.txt`，每行一条事实内容：

```
2026-07-01：完成了考勤打卡采集程序的开发
2026-07-02：完成了考勤打卡范围规则的开发
2026-07-03：完成了考勤每日考勤的计算开发
2026-07-30：完成了考勤系统的开发与测试
```

或者在生产环境指定外部文件路径（通过环境变量）：
```bash
export DEEPSEEK_CONFIG_PATH="/etc/deepseek/application.properties"
```

### 4. 构建 & 运行

#### 方式一：生产启动脚本（推荐）

Windows:
```cmd
# 先编辑 run.bat 设置 API Key，然后：
run.bat
```

Linux/macOS:
```bash
chmod +x run.sh
# 先编辑 run.sh 设置 API Key，然后：
./run.sh
```

#### 方式二：Maven 打包后运行

```bash
# 打包（生产环境）
mvn clean package -DskipTests

# 运行生产版
java -Xms512m -Xmx1024m -XX:+UseG1GC \
     -DDEEPSEEK_PROFILE=production \
     -DDEEPSEEK_API_KEY=sk-xxx \
     -jar target/deepseek-chat-client.jar
```

#### 方式三：Maven 直接运行（开发调试）

```bash
mvn clean compile
mvn exec:java -Dexec.mainClass="com.deepseek.chat.DeepSeekChatApplication"
```

---

## 交互命令

启动后进入交互式对话界面，支持以下命令：

| 命令 | 说明 |
|------|------|
| `/help` 或 `/h` | 显示帮助信息 |
| `/clear` 或 `/cls` | 清空对话历史（初始内容保留） |
| `/status` 或 `/stat` | 查看对话状态（历史消息数等） |
| `/history` 或 `/hist` | 查看对话历史记录 |
| `/exit` 或 `/q` | 退出程序 |
| `\` 或 `"""` | 进入多行输入模式（再次输入结束） |

### 使用示例

```
您> 帮我生成周报
助手> 
根据你提供的初始内容，以下是考勤系统的周报总结：
...

您> 帮我生成月报
助手>
...

您> 帮我总结所有的内容
助手>
...

您> /status
[对话状态]
  已初始化: 是
  历史消息数: 6
```

---

## 项目结构

```
deepseek-chat-client/
├── pom.xml                                    # Maven 构建配置
├── run.bat                                    # Windows 启动脚本
├── run.sh                                     # Linux/macOS 启动脚本
├── .gitignore
└── src/main/
    ├── java/com/deepseek/chat/
    │   ├── DeepSeekChatApplication.java       # 主入口，CLI 交互
    │   ├── config/
    │   │   └── DeepSeekConfig.java            # 配置加载（多环境+优先级机制）
    │   ├── client/
    │   │   └── DeepSeekApiClient.java         # API 客户端 + 重试机制
    │   ├── service/
    │   │   ├── ConversationContext.java       # 上下文管理（系统+初始+历史）
    │   │   └── ConversationService.java       # 对话业务服务
    │   ├── logging/
    │   │   └── FileConversationLogger.java    # 文件日志（含 Token 统计）
    │   └── model/
    │       ├── ChatMessage.java               # 消息模型
    │       ├── ChatRequest.java               # API 请求模型
    │       └── ChatResponse.java              # API 响应模型
    └── resources/
        ├── application.properties             # 默认配置
        ├── application-production.properties  # 生产环境配置
        └── initial-context.txt                # 初始内容（可替换）
```

---

## 配置说明

### 配置优先级（从高到低）

1. **环境变量**：`DEEPSEEK_API_KEY`、`DEEPSEEK_API_BASE_URL`、`DEEPSEEK_PROFILE`
2. **外部配置文件**：通过 `DEEPSEEK_CONFIG_PATH` 指定路径
3. **环境专属配置**：`application-production.properties`（当 profile=production 时）
4. **默认配置**：`application.properties`

### 主要配置项

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|----------|--------|------|
| `deepseek.api.key` | `DEEPSEEK_API_KEY` | (空) | **必填**，API 密钥 |
| `deepseek.api.base-url` | `DEEPSEEK_API_BASE_URL` | `https://api.deepseek.com/v1` | API 地址 |
| `deepseek.model` | - | `deepseek-chat` | 模型名称 |
| `deepseek.temperature` | - | `0.7` | 生成温度（0~2） |
| `deepseek.max-tokens` | - | `4000` | 最大生成 Token |
| `deepseek.connect-timeout-seconds` | - | `30` | 连接超时（秒） |
| `deepseek.read-timeout-seconds` | - | `120` | 读取超时（秒） |
| `deepseek.max-retries` | - | `3` | 最大重试次数 |
| `deepseek.retry-backoff-millis` | - | `1000` | 重试退避基数（毫秒） |
| `deepseek.max-history-messages` | - | `20` | 对话历史上限（超出自动截断） |
| `deepseek.initial-context-file` | - | `initial-context.txt` | 初始内容文件 |
| `deepseek.system-prompt` | - | (中文助手提示) | 系统提示词 |

---

## 生产环境部署建议

### 1. 部署前检查清单

- [ ] **API Key 不硬编码**：使用环境变量或密钥管理服务（Vault/KMS）
- [ ] **外部配置文件**：`DEEPSEEK_CONFIG_PATH` 指向受控目录
- [ ] **JVM 参数调优**：根据负载调整堆内存
- [ ] **日志目录可写**：确保 `./logs/` 或自定义目录有写权限
- [ ] **网络白名单**：生产服务器可访问 `api.deepseek.com:443`

### 2. 推荐 JVM 参数（生产环境）

```bash
java -server \
     -Xms1g -Xmx2g \
     -XX:+UseG1GC \
     -XX:MaxGCPauseMillis=200 \
     -XX:+HeapDumpOnOutOfMemoryError \
     -XX:HeapDumpPath=/var/log/deepseek/ \
     -Dfile.encoding=UTF-8 \
     -DDEEPSEEK_PROFILE=production \
     -DDEEPSEEK_CONFIG_PATH=/etc/deepseek/application.properties \
     -jar target/deepseek-chat-client.jar
```

### 3. 作为系统服务运行

**Linux systemd 示例 `/etc/systemd/system/deepseek-chat.service`:**

```ini
[Unit]
Description=DeepSeek Chat Client Service
After=network.target

[Service]
Type=simple
User=appuser
Group=appuser
WorkingDirectory=/opt/deepseek-chat
Environment=DEEPSEEK_PROFILE=production
Environment=DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx
Environment=DEEPSEEK_CONFIG_PATH=/etc/deepseek/application.properties
ExecStart=/usr/bin/java -Xms1g -Xmx2g -jar /opt/deepseek-chat/deepseek-chat-client.jar
Restart=on-failure
RestartSec=10
StandardOutput=append:/var/log/deepseek/stdout.log
StandardError=append:/var/log/deepseek/stderr.log

[Install]
WantedBy=multi-user.target
```

启动：
```bash
sudo systemctl daemon-reload
sudo systemctl enable deepseek-chat
sudo systemctl start deepseek-chat
```

### 4. 日志管理

- 对话日志自动写入 `logs/conversation-YYYYMMDD.log`
- 包含：用户输入、助手回复、Token 使用量统计
- 建议配合 `logrotate` 进行日志轮转：

```
# /etc/logrotate.d/deepseek-chat
/var/log/deepseek/*.log {
    daily
    rotate 30
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
}
```

---

## 常见问题

### Q1: 报错 "API Key is not configured"

**A:** 确保 `DEEPSEEK_API_KEY` 环境变量已正确设置。生产环境**不要**将密钥写入 `application.properties`（避免提交到 Git）。

### Q2: 对话历史太长导致 Token 超限？

**A:** 系统自动维护 `max-history-messages`（默认20条），超过后自动截断最旧消息。生产环境可根据需要调大此值，或使用 `/clear` 手动清空。

### Q3: 如何自定义初始内容？

**A:** 三种方式任选其一：
1. 编辑 `src/main/resources/initial-context.txt`（打包前）
2. 在应用外部放置文件，配置 `deepseek.initial-context-file` 指向绝对路径
3. 修改 [DeepSeekChatApplication.java](src/main/java/com/deepseek/chat/DeepSeekChatApplication.java) 中 `buildDefaultInitialContext()` 方法硬编码

### Q4: 网络不稳定怎么办？

**A:** 已内置自动重试机制：
- 对 429（限流）和 5xx（服务端错误）自动重试
- 指数退避：第1次等1s，第2次等2s，第3次等4s...
- 重试次数可调：`deepseek.max-retries`

### Q5: 可以作为库嵌入到其他 Java 项目吗？

**A:** 完全可以。核心用法如下：

```java
DeepSeekConfig config = DeepSeekConfig.load("production");
config.validate();

DeepSeekApiClient client = new DeepSeekApiClient(config);
ConversationContext context = new ConversationContext(config);
ConversationService service = new ConversationService(config, client, context);

// 初始化（注入初始内容）
List<String> initialItems = Arrays.asList(
    "2026-07-01：完成了考勤打卡采集程序的开发",
    "2026-07-02：完成了考勤打卡范围规则的开发"
);
service.initialize(initialItems);

// 多轮提问
String answer1 = service.ask("帮我生成周报");
String answer2 = service.ask("月报和周报有什么区别？");
```

---

## License

内部使用