Lingban-AI-Chat | 灵伴 AI 聊天

Android-first AI Companion Chat App
一个把“工具型对话”推进到“角色化陪伴”的 Android 客户端与后端 API 仓库

English | 简体中文

---

为什么有这个项目

Lingban-AI-Chat 是一个 AI 陪伴聊天项目，当前由 Android 客户端与 Python 后端 API 组成。它关注的不是“把一个聊天框接到大模型”这么简单，而是把 AI 对话拆成三个更可落地的产品层次：

1. 角色层：不同角色拥有不同语气、边界、开场白、头像与背景，让用户不是在面对一个抽象模型，而是在选择一种陪伴体验。
2. 会话层：登录、JWT、历史记录、清空会话、流式回复等能力，把一次性问答变成可连续使用的 App 闭环。
3. 工程层：Android 端负责体验与状态管理，后端负责鉴权、角色、对话、天气工具和模型调用，便于独立迭代与部署。

可以把它类比成一个“小型 AI 角色剧场”：Android 是舞台，API 是调度后台，角色 Prompt 是演员设定，模型回复是每一场实时演出。

快速开始

方式一：直接安装 APK

如果只是体验 App，优先下载已签名安装包：

• Download APK

方式二：本地运行 Android 客户端

环境建议：

• Android Studio 最新稳定版
• JDK 21
• Android SDK / Emulator
• 推荐 Pixel 9 模拟器

cd AIchat-android
./gradlew.bat :app:assembleDebug
./gradlew.bat :app:testDebugUnitTest

也可以直接用 Android Studio 打开 AIchat-android/，等待 Gradle Sync 完成后运行 app。

方式三：本地查看 / 调试后端服务

后端位于 AIchat-API/，由两个可独立部署的 Python 服务组成：

cd AIchat-API/LoginService
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
# 复制 .env.example 为 .env 并补齐短信、JWT 等配置

cd ..\ChatService
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
# 复制 .env.example 为 .env 并补齐模型、数据库、天气、JWT 等配置

具体环境变量以各服务目录下的 .env.example 和 README 为准，不建议把真实密钥提交到仓库。

APK 下载

当前仓库根目录保留了一个已签名 Android 安装包：

文件	说明
lingban-ai-chat-v1.0-release-signed.apk	v1.0 已签名安装包，可直接安装测试
GitHub raw 下载	适合从浏览器或手机端直接下载

安装前请确认 Android 设备允许安装来自浏览器或文件管理器的 APK。

角色设定

Lingban-AI-Chat 的核心不是“一个万能助手”，而是四个风格明确的陪伴角色。角色信息由 ChatService/roles.py 维护，前端应以 GET /api/chat/roles 返回结果为准。

roleKey	角色	定位	适合场景
chenge	辰哥	平易近人的技术专家	技术解释、学习陪跑、稳定建议、复杂问题拆解
taffy_like	塔菲	古灵精怪的发明家少女	轻松聊天、脑洞表达、吐槽式互动、活跃气氛
jiaran_like	嘉然	元气甜妹吃货	情绪接住、日常陪伴、轻柔反馈、朋友感聊天
dongxuelian_like	冬雪莲	清冷系吸血鬼少女	夜晚氛围、情绪表达、克制陪伴、距离感审美

其中“角色设定”可以理解成大模型应用里的 Persona Layer：它不是简单换皮，而是用 Prompt、素材、开场白和 UI 氛围共同塑造交互边界。

目录结构

Lingban-AI-Chat/
├─ AIchat-android/                         # Android 客户端
│  ├─ app/src/main/java/cn/vectorpeak/AIchat_projects/
│  │  ├─ data/                             # local / model / remote / repository
│  │  ├─ ui/                               # screen / component / navigation / theme
│  │  └─ viewmodel/                        # Entry / Login / Home / Chat 等状态管理
│  ├─ app/src/main/res/                    # 图标、主题、字符串、启动图等资源
│  ├─ gradle/                              # Gradle wrapper 与版本目录
│  └─ README.md
├─ AIchat-API/                             # 后端 API
│  ├─ LoginService/                        # 短信验证码登录与 JWT 签发
│  ├─ ChatService/                         # 角色、聊天、流式回复、历史、天气、JWT 校验
│  ├─ sql/                                 # MySQL 8 初始化脚本
│  ├─ API_DOCUMENTATION.md                 # 前后端联调 API 文档
│  └─ README.md
├─ docs/
│  ├─ maintenance/                         # 发布检查、运行假设等维护记录
│  └─ testing/                             # 手工测试计划
├─ AGENTS.md                               # 仓库协作与维护约定
├─ lingban-ai-chat-v1.0-release-signed.apk # 已签名安装包
└─ README.md

设计与接口

产品设计

• Figma 设计稿：AI 陪伴聊天 app 设计
• Android 端主要技术栈：Kotlin、Jetpack Compose、Material 3、ViewModel、StateFlow、Retrofit、OkHttp、Coil
• 当前客户端已覆盖：Entry、Onboarding、Login、Home、Chat、Splash、JWT 持久化、角色列表、聊天历史、流式聊天、清空会话

后端接口

后端由两个服务组成：

服务	职责	主要接口
LoginService	短信验证码、登录、JWT 签发	GET /health、POST /api/auth/send-code、POST /api/auth/login
ChatService	角色、聊天、历史、清空、流式回复、天气工具、JWT 校验	GET /api/chat/roles、GET /api/chat/history、POST /api/chat/clear、POST /api/chat/completions、POST /api/chat/stream

接口文档入口：

• 仓库内 Markdown：AIchat-API/API_DOCUMENTATION.md
• 仓库内 HTML：AIchat-API/API_DOCUMENTATION.html
• 在线 API Wiki：AI Chat API Wiki

资源与素材

角色头像与背景图当前托管在腾讯 COS：

• 资源根目录：AIchat_image
• 前端不要硬编码素材地址，应优先使用 GET /api/chat/roles 返回的 avatarUrl 与 backgroundUrl。

注意事项

1. 命名统一：项目对外展示名统一为 Lingban-AI-Chat，中文说明可写作“灵伴 AI 聊天”。
2. 接口优先级：角色、头像、背景、开场白等信息以 ChatService 返回为准，客户端不应维护静态副本。
3. 密钥管理：短信、JWT、模型、数据库、天气等配置必须放在 .env 或部署环境变量中，不要提交真实密钥。
4. JWT 约定：LoginService 签发 JWT，ChatService 校验 JWT；两者需要共享一致的 LOGIN_TOKEN_SECRET、算法与 issuer。
5. 数据库依赖：聊天历史、会话和用户数据依赖 MySQL 8 初始化表结构，首次部署前需要执行 AIchat-API/sql/001_init_aichat_api_mysql8.sql。
6. Android 图标：当前已有 launcher icon 与 Splash 资源，但 Android 13/14 themed monochrome icon 仍可后续补齐。
7. 功能边界：文本聊天和流式回复是当前核心闭环，图片聊天 UI、更多多模态能力和更完整的发布流程仍可继续增强。

FAQ

1. 这个项目只是一个 ChatGPT 壳吗？

不是。普通聊天壳通常只做“输入问题 -> 返回答案”；Lingban-AI-Chat 额外处理了角色设定、登录态、会话历史、流式输出、角色素材、天气工具和 Android 端体验闭环。

2. 为什么要做多个角色？

因为陪伴型产品的关键不是模型参数，而是交互预期。不同角色相当于不同的“对话滤镜”：辰哥偏技术解释，塔菲偏活跃吐槽，嘉然偏情绪陪伴，冬雪莲偏克制氛围。

3. APK 可以直接安装吗？

可以。仓库根目录提供了 lingban-ai-chat-v1.0-release-signed.apk，也可以通过上面的 GitHub raw 链接下载。若系统拦截，请检查“允许安装未知来源应用”的权限设置。

4. Android 端如何切换后端地址？

查看 AIchat-android/app/src/main/java/cn/vectorpeak/AIchat_projects/data/remote/NetworkConfig.kt。如需切换到本地或自部署服务，应优先在网络配置层集中修改，不要在各个 API 调用点分散硬编码。

5. 后端必须同时启动两个服务吗？

完整链路需要两个服务：LoginService 负责登录和 JWT，ChatService 负责角色与聊天。只调试角色列表或健康检查时，可以单独运行 ChatService；涉及登录态、历史和聊天时需要 JWT 配置一致。

6. 为什么前端不要硬编码角色素材？

角色素材属于后端角色配置的一部分。前端硬编码会导致后端更新角色头像、背景或开场白后客户端不同步。更稳妥的做法是每次从 GET /api/chat/roles 拉取。

7. 这个项目后续适合怎么扩展？

优先级可以按“产品闭环 -> 可靠性 -> 多模态”推进：先补齐异常态、发布说明和配置隔离，再增强图片聊天 UI、角色管理后台、Prompt 版本管理、测试覆盖和更多工具调用能力。