# openilink-java

**Repository Path**: AngLong/openilink-java

## Basic Information

- **Project Name**: openilink-java
- **Description**: openilink-java 是一个基于 Spring Boot 的本地 Bot 控制台服务，用于连接微信 iLink 与 OpenAI Responses API，提供扫码登录、运行控制、模型配置、浏览器内调试问答等能力。
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-27
- **Last Updated**: 2026-03-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# openilink-java

`openilink-java` 是一个基于 Spring Boot 的本地 Bot 控制台服务，用于连接微信 iLink 与 OpenAI Responses API，提供扫码登录、运行控制、模型配置、浏览器内调试问答等能力。

## 功能概览

- 本地 Web 控制台（状态查看、启动/停止、二维码登录）
- OpenAI 参数配置（API Key、模型、Base URL、推理强度、系统提示词）
- 浏览器内调试问答接口（不经过微信）
- 微信命令支持（如 `/help`、`/status`、`/model`）

## 环境要求

- JDK 8 或更高版本
- Maven 3.8 或更高版本
- 可访问 OpenAI API 的网络环境

## 快速开始

### 1) 打包

在项目根目录执行：

```bash
mvn -DskipTests package
```

打包成功后会生成：

- `target/openilink-java-1.0.0-SNAPSHOT-exec.jar`

### 2) 配置环境变量

#### macOS / Linux

```bash
export OPENILINK_AUTOSTART=true
export OPENILINK_TOKEN=
export OPENILINK_SYNC_BUF_PATH=.springbot/bot-sync-buf.dat
export OPENILINK_AI_MODEL=gpt-5.4
export OPENILINK_AI_BASE_URL=https://api.openai.com
export OPENILINK_AI_REASONING_EFFORT=low
export SERVER_PORT=8080
```

#### Windows PowerShell

```powershell
$env:OPENILINK_AUTOSTART="true"
$env:OPENILINK_TOKEN=""
$env:OPENILINK_SYNC_BUF_PATH=".springbot/bot-sync-buf.dat"
$env:OPENILINK_AI_MODEL="gpt-5.4"
$env:OPENILINK_AI_BASE_URL="https://api.openai.com"
$env:OPENILINK_AI_REASONING_EFFORT="low"
$env:SERVER_PORT="8080"
```

> 兼容性说明：当前版本优先读取 `OPENILINK_*`，同时兼容旧前缀 `SPRINGBOT_*` 和旧 OpenAI 变量（如 `OPENAI_DEFAULT_MODEL`、`OPENAI_BASE_URL`、`OPENAI_REASONING_EFFORT`）。

> `OPENAI_API_KEY` 建议在服务启动后，通过控制台页面的“OpenAI 设置”填写并保存到本地。

### 3) 启动

```bash
java -jar target/openilink-java-1.0.0-SNAPSHOT-exec.jar
```

## 访问地址

- 控制台页面：`http://127.0.0.1:8080/`
- 状态接口：`http://127.0.0.1:8080/api/bot/status`

## 项目目录

```text
openilink-java/
├─ src/
│  ├─ main/
│  │  ├─ java/com/openilink/
│  │  │  ├─ ai/client/                 OpenAI Responses API 客户端
│  │  │  ├─ bot/                       Bot 运行控制、GUI、配置与上下文管理
│  │  │  ├─ common/
│  │  │  │  ├─ exception/              通用异常定义
│  │  │  │  └─ util/                   HTTP、URL、消息、休眠等工具类
│  │  │  ├─ config/                    SpringDoc 等 Spring 配置
│  │  │  ├─ web/                       REST API、请求/响应模型、异常处理
│  │  │  ├─ weixin/ilink/
│  │  │  │  ├─ auth/                   登录回调接口
│  │  │  │  ├─ client/                 iLink 主客户端
│  │  │  │  ├─ http/                   HTTP 抽象与默认实现
│  │  │  │  ├─ model/                  iLink 消息与数据模型
│  │  │  │  │  ├─ request/             请求模型
│  │  │  │  │  └─ response/            响应模型
│  │  │  │  └─ monitor/                长轮询监听配置与消息处理接口
│  │  │  └─ SpringBotApplication.java  应用入口
│  │  └─ resources/
│  │     ├─ static/index.html          浏览器控制台页面
│  │     ├─ application.yml            应用配置
│  │     └─ logback.xml                日志配置
│  └─ test/
│     └─ java/com/openilink/
│        ├─ ai/client/                 OpenAI 客户端测试
│        ├─ bot/                       配置存储测试
│        └─ web/                       请求校验测试
├─ pom.xml                             Maven 构建配置
├─ README.md                           项目说明文档
└─ LICENSE                             许可证
```

### 目录说明

- `src/main/java/com/openilink/bot` 是项目核心，负责 Bot 生命周期、桌面控制台和配置管理。
- `src/main/java/com/openilink/weixin/ilink` 封装了微信 iLink 协议交互与消息模型。
- `src/main/java/com/openilink/web` 提供浏览器控制台依赖的 REST API。
- `src/main/resources/static/index.html` 是内置的 Web 控制台页面。
- `src/test/java` 目前放的是 OpenAI 客户端、配置存储和请求校验的回归测试。

## 常用接口

- `GET /api/bot/status`：查询运行状态
- `POST /api/bot/start`：启动 Bot
- `POST /api/bot/stop`：停止 Bot
- `GET /api/bot/settings`：读取设置
- `PUT /api/bot/settings`：保存设置
- `POST /api/bot/ask`：调试问答

## 微信命令

- `/help`：查看命令列表
- `/status`：查看运行状态
- `/reset`：清空当前用户上下文
- `/model`：查看当前模型
- `/model gpt-5.4`：切换模型
- `/model reset`：恢复默认模型

## 验证服务

### macOS / Linux

```bash
curl http://127.0.0.1:8080/api/bot/status
```

### Windows PowerShell

```powershell
curl http://127.0.0.1:8080/api/bot/status
```

若返回 JSON 状态信息，说明服务运行正常。

## 常见问题

- 端口占用：修改 `SERVER_PORT` 后重启服务
- 模型调用失败：检查 API Key、`OPENILINK_AI_BASE_URL` 与网络代理
- 二维码不显示：先确认服务已启动，再点击页面“刷新”

## 许可证

MIT