# PocketAI

**Repository Path**: pocketAI/PocketAI

## Basic Information

- **Project Name**: PocketAI
- **Description**: 安卓 AI 客户端 · 液态玻璃 · 直连你自己的 API Key · AGPL-3.0
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-10-17
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 随手 AI · PocketAI

> 一个把「打开就能问」做到极致的安卓 AI 客户端 —— 液态玻璃界面，直连你自己的 API Key，聊天记录只存在本机。

<p align="center">
  <img src="docs/shots/chat.png" width="30%" alt="消息" />
  <img src="docs/shots/discover.png" width="30%" alt="发现" />
  <img src="docs/shots/profile.png" width="30%" alt="我的" />
</p>

**当前版本：v0.41.1** · 安装包 23.57 MB · Android 8.0+ (API 26)

---

## 直接下载安装

| 方式 | 地址 |
|---|---|
| **最新版 APK** | [pocketai-0.41.1.apk](https://gitee.com/pocketAI/PocketAI/releases/download/v0.41.1/pocketai-0.41.1.apk) |
| **全部版本** | [Releases](https://gitee.com/pocketAI/PocketAI/releases) |
| **在线更新源** | `https://gitee.com/pocketAI/PocketAI/raw/master/update.json` |

下载 APK 后直接安装，首次安装需要允许「安装未知来源应用」。装好打开 App，
在「我的 → 供应商」里填一次 API Key 就能用，之后有新版本 App 会自动提示更新。

<p align="center">
  <img src="docs/shots/chat-dark.png" width="30%" alt="深色模式" />
  <img src="docs/shots/update.png" width="30%" alt="在线更新" />
</p>

---

## 为什么做这个

市面上的 AI 客户端，要么是网页套壳、每次都要登录；要么界面花哨但一卡一卡；
要么把你输入的每一句话都过一遍它自己的服务器。

随手 AI 只做三件事：**快**、**顺**、**数据只在你手机上**。
界面按 iOS 的液态玻璃材质重做了三轮，动画全部用弹簧物理驱动，
输入框上拉、气泡消散、弹窗进出都是逐帧调过的 —— 这些细节在截图里看不出来，装上就知道了。

---

## 功能

### 对话
- **流式输出** —— 回答逐字出现，可随时点停
- **多轮上下文** —— 可调携带的历史条数，长的自动截断不炸请求
- **重新生成 / 编辑消息** —— 改一句再重跑，不用整段重来
- **长按删除「碎成沙」** —— 气泡拆成 1500 粒沙，从左往右被擦除线吃掉
- **Markdown 渲染** —— 代码块、表格、列表都能看

### 多供应商 · 多模型
- **同时配置多家** —— DeepSeek、OpenAI、任何 OpenAI 兼容接口（自定义 Base URL）
- **上拉面板切模型** —— 不用进设置，聊天中直接换
- **能力标签** —— 聊天 / 视觉 / 推理 / 工具 / 长文，按官方 `/models` 元数据或模型名推断
- **批量勾选模型** —— 拉取列表后「全选 / 取消全选」，只显示你在意的那些
- **余额查询** —— 支持的供应商直接看余额

### 助手
- 内置**通用 / 翻译官 / 写作 / 代码 / 面试教练**，也可以自定义
- 每个助手独立的**系统提示词**与 **Emoji 头像**，可换成自定义图片
- 支持**从文件导入提示词**，一键切换人设

### 回答风格
- **思考预算** 滑杆（离散停靠点 + 触感反馈）
- **随机性** 滑杆，自定义档位
- **系统提示词变量** —— `{{cur_date}}` `{{cur_time}}` `{{model_id}}` `{{battery_level}}` `{{device_info}}` 等 12 个占位符，发送前实时替换

### 指令注入
- 把一条条规则**深度注入**到 system prompt 末尾（带编号 + 优先级声明 + 反幻觉约束）
- 每次请求在最后一条用户消息尾部再提醒一次规则名，靠近生成位置，不容易被忽略
- 不会被「上下文条数」截断

### 数据与统计
- **用量统计** —— 每次请求的 token 数、耗时、按天热力图、按模型占比
- **备份 / 恢复** —— 设置、会话、用量打包成单个 JSON
- **存储管理** —— 看清附件占用，清理未引用附件、删除全部对话
- **全部本地** —— API Key 与聊天记录只在应用私有目录，不经过任何中转服务器

### 外观
- **液态玻璃材质** —— 模糊半径 14/18dp、噪声 3.5%、内阴影 + 高光 + 折射亮边四层边缘
- **浅色 / 深色 / 跟随系统**，即时生效
- **果冻开关** —— 圆点滑动途中按速度拉长成胶囊，到位回弹
- **粒子开屏** —— 3000 颗星从满屏汇聚成 PocketAI 字样，只在首次安装和更新后播放

---

## 快速上手

1. 下载并安装 APK
2. 打开 App → **我的 → 供应商** → 新建一个供应商，填入 Base URL 和 API Key
   - 例如 DeepSeek：`https://api.deepseek.com`，Key 在 [platform.deepseek.com](https://platform.deepseek.com) 申请
3. 点「测试连接」确认能通 → 保存 → 拉取模型列表并勾选
4. 回到 **消息** 页，点输入框上方的手柄上拉选模型，开始聊

---

## 自己编译

需要 **JDK 17+**、**Android SDK 36 (compileSdk 36)**：

```bash
git clone https://gitee.com/pocketAI/PocketAI.git
cd PocketAI

./gradlew assembleDebug      # 输出 app/build/outputs/apk/debug/app-debug.apk
./gradlew assembleRelease    # 输出 app/build/outputs/apk/release/app-release.apk（需自备签名）
```

Release 签名从 `keystore.properties` 读取（不入库）；没有配置时会退化成未签名包，
装上后无法覆盖安装正式版。

---

## 技术栈

| 层 | 使用 |
|---|---|
| 语言 | Kotlin 2.x |
| UI | Jetpack Compose + Material 3 1.4.0 |
| 模糊 / 材质 | Haze 1.6.2、Cloudy 0.6.1 |
| 图标 | Cupertino Icons Extended、Material Icons Extended |
| 网络 | OkHttp 4.12（SSE 流式解析） |
| 文档解析 | PdfBox-Android 2.0.27 |
| 存储 | SharedPreferences + JSON |
| 构建 | AGP 8.13.2 / Gradle 8.14.3 |
| 兼容 | Android 8.0 (API 26) ~ Android 16 (API 36) |

---

## 项目结构

```
app/src/main/java/com/pocketai/
├── MainActivity.kt            # 入口
├── ChatViewModel.kt           # 状态管理、流式收发、用量记账
├── UpdateViewModel.kt         # OTA 检查与下载
├── data/
│   ├── Models.kt              # 数据模型、模型能力推断
│   ├── Storage.kt             # 设置与对话持久化
│   ├── InjectionRule.kt       # 注入规则
│   ├── PromptVars.kt          # 系统提示词变量
│   ├── ImageCompressor.kt     # 图片压缩（最长边 1568px / JPEG 85）
│   ├── FileExtractor.kt       # txt / docx / pdf 取文本
│   ├── UsageTracker.kt        # 用量明细 + 累计总量
│   └── BackupManager.kt       # 整包备份 / 恢复
├── network/                   # OkHttp + SSE 客户端
├── update/                    # update.json 解析与 APK 安装
└── ui/
    ├── AppShell.kt            # 消息 / 发现 / 我的 三页外壳
    ├── ChatScreen.kt          # 聊天主界面
    ├── ProvidersScreen.kt     # 供应商与模型
    ├── AssistantsScreen.kt    # 助手管理
    ├── InjectionScreen.kt     # 指令注入
    ├── StatsScreen.kt         # 用量统计
    ├── DataScreen.kt          # 存储与备份
    ├── components/            # 液态玻璃、果冻开关、粒子 Logo 等
    └── theme/                 # 配色、玻璃配方
```

---

## 版本与更新

版本规则：`主版本.次版本.修订号`，新增功能次版本 +1，修 bug 修订号 +1；`versionCode` 每次发布 +1。
完整的每版变更见 [CHANGELOG.md](CHANGELOG.md)。

App 内置在线更新（检查 → 下载 → 调起安装器），更新源放在本仓库根目录的
[update.json](update.json)，发版流程见 [docs/GITEE-OTA.md](docs/GITEE-OTA.md)。

---

## 隐私

- API Key、聊天记录、附件、用量数据**全部只存在手机本地**（应用私有目录 + SharedPreferences）
- App 只与你自己配置的 API 服务商通信，没有任何自建中转服务器、没有统计上报
- 导出的备份文件里包含 API Key（方便换机恢复），分享前请注意

---

## 许可证

本项目以 **[GNU AGPL-3.0-or-later](LICENSE)** 发布，自 v0.35.0 起生效，此前的历史版本不收许可证授权。

简单说：

- **个人使用、自建、修改、二次开发**：随便用，改完再分发时同样要以 AGPL-3.0 开源（含网络服务形式）。
- **闭源集成 / 商用**（把本项目的代码或衍生版本打包进不开放源码的产品或服务）需要**另行取得商业授权**，
  请联系作者协商。
- **反向代理或修改后再对外提供服务**：AGPL-3.0 第 13 条要求向使用者提供完整源代码。

第三方依赖及其许可证（Apache-2.0 / MIT / BSD 等）见 [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md)。
注意其中的 Haze、Cloudy、Compose-Bubble 等 Apache-2.0 组件保留各自版权，AGPL 仅覆盖本项目原创代码。

---

## 反馈

- 提 Issue：[Gitee Issues](https://gitee.com/pocketAI/PocketAI/issues)
- 仓库：[gitee.com/pocketAI/PocketAI](https://gitee.com/pocketAI/PocketAI)