Caret 使用文档

此指南适用于所有人，其中对部分复杂内容有完整讲解，可放心使用

目录

1. 安装与首次启动
2. AI 收纳（悬浮托盘）怎么用
3. AI 对话：API 调用完整说明
   • 4.1 先搞懂：API、API Key、Provider 都是什么
   • 4.2 Caret 里 Provider 怎么配
   • 4.3 主流厂商 API Key 申请指南
   • 4.4 自己部署的模型（Ollama / LM Studio）
   • 4.5 常见报错与解决
4. HTTP 请求：完整原理与使用
   • 5.1 HTTP 到底是什么
   • 5.2 一个请求长什么样
   • 5.3 Caret 里怎么填
   • 5.4 变量模板（让请求动态起来）
   • 5.5 真实例子：调用一个公开 API
5. 设置面板详解
6. 常见问题

1. 安装与首次启动

1. 从官网 下载页面 拿到 APK（两种方式任选）。
2. 安装。如果系统提示"未知来源"，在设置里允许一下（不同手机位置不一样，一般在「安全」或「应用管理」里）。
3. 打开 Caret：
4. 进入主界面。先别急着用对话——第 4 节会教你怎么配 API Key。

3. AI 收纳（悬浮托盘）怎么用

3.1 打开悬浮窗权限

首次开启前需要获取"悬浮窗"权限：

• 华为/小米/OPPO/vivo：设置 → 应用管理 → Caret → 显示在其他应用上层 → 允许
• 原生 Android：设置 → 应用 → Caret → 高级 → 显示在其他应用上层
• 找不到？打开 Caret 设置页 → 找"悬浮窗权限"那一行，点它会直接跳到系统设置

3.2 球的手势

3.3 托盘里有什么

展开后你会看到一排图标，默认包含：

• AI 对话：打开 Chat 界面
• HTTP 请求：打开 API 测试器
• 你的应用：从本机已安装列表选进来的常用 App

3.4 添加/删除收纳项

设置 → 应用收纳 → 手动添加应用（或取消勾选已收纳的）。提示：手动添加的应用不受"过滤系统应用"开关影响，放心加。

4. AI 对话：API 调用完整说明

这一节是全指南最核心的部分。如果你之前从没听过"API Key"，别跳过。

4.1 先搞懂三个词

API（Application Programming Interface）就是"AI 厂商给你的一个程序入口"。你发一段文字过去，它返回一段文字回来。就像你给客服发消息，客服给你回消息——只不过客服是 AI。

API Key 就是"你给 AI 厂商的身份证 + 银行卡"。厂商需要知道你是谁（防止别人乱刷），以及你账户里有没有钱（大多数厂商按 token 计费）。Key 长这样：

sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️ Key 不要给任何人。丢了立刻去厂商后台撤销再新建。

Provider 就是"AI 服务提供商"。Caret 支持的 Provider 种类：

4.2 Caret 里 Provider 怎么配

打开 Caret → 主界面 → AI 对话 → 右上角 Provider 编辑：

Provider 名称：随便起，比如"我的智谱"
Base URL：    https://open.bigmodel.cn/api/paas/v4
API Key：     粘贴你拿到的 Key
模型名：      glm-4-flash （厂商后台会写支持哪些）

Base URL 一定注意：每个厂商的 URL 不一样，有的是 /v1，有的是 /api/paas/v4。抄厂商文档里的，别自己猜。

支持多个 Provider：你可以配好几个，对话里随时切换。比如一个用 GPT-4o 写文案，一个用本地 qwen2.5 跑长文。

4.3 主流厂商 API Key 申请指南

下面列几个常用的：

智谱 AI

• 官网：https://open.bigmodel.cn
• 申请流程：
  1. 手机号注册登录
  2. 进入「控制台」→「API Key 管理」
  3. 创建新 Key，复制保存（只显示一次！）
• 费用：新用户有免费额度；glm-4-flash 很便宜，跑几十万 token 才几块钱
• Caret 配置：

  Base URL：https://open.bigmodel.cn/api/paas/v4
  模型名：glm-4-flash

阿里百炼 / 通义千问

• 官网：https://bailian.console.aliyun.com
• 申请流程：
  1. 阿里云账号登录（淘宝账号通）
  2. 开通百炼服务 → 进入控制台
  3. 「API 密钥管理」→ 创建 AccessKey 和 SecretKey，或者直接创建 API-KEY
• 费用：有免费额度；qwen-turbo 便宜，qwen-plus 中等
• Caret 配置：

  Base URL：https://dashscope.aliyuncs.com/compatible-mode/v1
  模型名：qwen-plus

（注意百炼用的是 DashScope，但是支持 OpenAI 兼容模式，URL 一定带 /compatible-mode/v1）

硅基流动（聚合平台）

• 官网：https://siliconflow.cn
• 申请流程：
  1. 注册 → 实名认证（必须）
  2. 控制台 → API Keys → 创建
• 特点：一家聚合了几十种模型（包括 DeepSeek、Llama、Gemma 等），一个 Key 到处用
• Caret 配置：

  Base URL：https://api.siliconflow.cn/v1
  模型名：deepseek-ai/DeepSeek-V3  （或者选别的）

DeepSeek（本人觉得这个最简单）

• 官网：https://platform.deepseek.com
• 申请流程：注册 → 充值（最低 5 元）→ API Keys → 创建
• 费用：非常便宜，V3 模型性价比极高
• Caret 配置：

  Base URL：https://api.deepseek.com/v1
  模型名：deepseek-chat

OpenAI

• 官网：https://platform.openai.com
• 申请流程：注册 → 绑信用卡（非中国大陆卡）→ API keys → Create new secret key
• 费用：按 token 计费，GPT-4o 较贵
• Caret 配置：

  Base URL：https://api.openai.com/v1
  模型名：gpt-4o-mini （便宜够用）或 gpt-4o

腾讯混元

• 官网：https://console.cloud.tencent.com/hunyuan
• 申请流程：腾讯云账号 → 开通混元 → API 密钥管理
• Caret 配置：

  Base URL：https://hunyuan.tencentcloudapi.com （这个比较特殊，用的是腾讯云 API 签名模式，可能不完全兼容 OpenAI 格式，建议先测）

月之暗面 Moonshot AI（Kimi）

• 官网：https://platform.moonshot.cn
• 申请流程：注册 → 充值 → API Key
• Caret 配置：

  Base URL：https://api.moonshot.cn/v1
  模型名：moonshot-v1-8k 或 moonshot-v1-32k

4.4 自己部署的模型（Ollama / LM Studio）

如果你有一台还不错的电脑（有显卡更好，没有也能跑小模型），可以本地跑 AI，完全免费，不花一分钱，也不上传任何数据。

Ollama（Windows，写这个的原因是用的人多，但是还是更推荐LM Studio）

1. 官网 https://ollama.com/download 下载 Windows 版安装
2. 打开 PowerShell：

   ollama run qwen2.5:3b

1. 等它下载完模型（qwen2.5:3b 约 1.9GB）就能对话了
2. Caret 里配置：

   Base URL：http://localhost:11434/v1
   API Key：随便填一个（Ollama 不校验），比如 ollama
   模型名：qwen2.5:3b

⚠️ 重要：Android 手机要访问电脑上的 Ollama，需要：

• 手机和电脑连同一个 WiFi
• 查电脑 IP（cmd 里 ipconfig，找 IPv4 地址，比如 192.168.1.100）
• Caret Base URL 填 http://192.168.1.100:11434/v1
• 电脑 Ollama 要允许局域网访问：设置环境变量 OLLAMA_HOST=0.0.0.0:11434 再启动

LM Studio

类似 Ollama，界面更友好，操作大同小异。默认端口 1234，Base URL：http://localhost:1234/v1。

别忘了开 Cleartext

Caret 在 AndroidManifest 里已经允许 HTTP 明文请求（usesCleartextTraffic=true），所以 http:// 开头的本地地址可以直接用。如果你用别的 App 不行，检查一下这个开关。

4.5 常见报错与解决

5. HTTP 请求：完整原理与使用

5.1 HTTP 到底是什么

HTTP（HyperText Transfer Protocol）就是"浏览器和服务器之间说话的规矩"。你打开网页、点按钮、刷新——本质都是发一个 HTTP 请求，服务器回一个 HTTP 响应。

不仅网页，所有 App 背后基本都用 HTTP。微博下拉刷新是 HTTP，微信发消息底层也是 HTTP（或其变体）。

5.2 一个请求长什么样

一个 HTTP 请求由三部分组成：

1. 方法 + URL        GET https://api.example.com/weather?city=beijing
2. Header（头）       Authorization: Bearer xxx
                     Content-Type: application/json
3. Body（体，可选）   {"text": "你好"}

方法（Method） 最常见的 5 种：

URL 就是地址，问号后面的是查询参数（Query）。

Header 是附在请求上的元信息，比如身份认证、数据格式。

Body 是实际要发给服务器的数据，通常是 JSON 格式。

5.3 Caret 里怎么填

打开 HTTP 请求页面，按从上到下填：

名称：      给这个请求起个名字，比如"查今日天气"
方法：      GET / POST / ...
URL：       https://api.openweathermap.org/data/2.5/weather
Query：     city → beijing
            appid → YOUR_KEY
Header：    Accept → application/json
Body：      （GET 就不用填）

点「发送」，下方会显示服务器返回的状态码、响应头、响应体。

5.4 变量模板（让请求动态起来）

Caret 的特色功能：用 {{变量名}} 写模板，运行时替换。

比如你做了一个"翻译"请求：

URL：    https://api.deepseek.com/v1/chat/completions
Header： Authorization → Bearer {{API_KEY}}
Body：   {"model":"deepseek-chat","messages":[{"role":"user","content":"翻译为英文：{{INPUT}}"}]}

然后在「变量」面板里定义：

• API_KEY = sk-xxxxxx
• INPUT = 你好，世界

点发送前 Caret 会自动把 {{API_KEY}} 和 {{INPUT}} 替换成实际值。

正则语法：\{\{\s*([^{}\s]+)\s*\}\} —— 双花括号里可以有空格，变量名不能有空格和花括号。

5.5 真实例子：调用一个公开 API

目标：用免费的 JSONPlaceholder API 新建一篇假文章。

方法：  POST
URL：   https://jsonplaceholder.typicode.com/posts
Header：Content-Type → application/json
Body：  {"title":"你好 Caret","body":"这是一篇测试","userId":1}

点发送，你会看到服务器返回：

{
  "title": "你好 Caret",
  "body": "这是一篇测试",
  "userId": 1,
  "id": 101
}

id: 101 是服务器分配的。这个 API 不会真的保存数据，只是模拟，很适合测试。

6. 设置面板详解

这里其实各位可以直接在软件内探索，只不过官方教程，就写全一点吧。

按从上到下的顺序：

外观

• 主题：跟随系统 / 浅色 / 深色
• 动态取色：Android 12+ 用壁纸颜色当强调色
• 强调色：10 种预设色，也可开动态取色让系统来
• 背景图开关 + 遮罩透明度：关闭背景后是纯色，纯色系用户可以关掉
• 字体缩放：0.8x - 1.4x
• 圆角：0-32dp
• 强调色作用范围：主色+次色 还是 仅主色

悬浮托盘

• 球闲置自动折叠时间：默认 10 秒（之前是 20 秒，改了）
• 球透明度
• 球大小

对话

• 渲染 Markdown：开关。关掉后 AI 回复只显示纯文本。建议开着，这样代码块、加粗、列表、链接都会自动美化
• Markdown 样式：（后续版本加更多选项）

网络

• HTTP 超时：慢网可以调大
• 重试次数：失败自动重试

应用收纳

• 手动添加 / 移除
• 系统应用过滤开关（开了之后手动加的不受影响）

数据

• 清除所有聊天记录
• 重置所有设置

其他

• 反馈：点了弹出"可通过 devynhub@outlook.com 联系"，同时打开邮箱 App 发邮件
• 教程、作者、探索：分别打开官网对应页面（官网还在完善中，先留空）

7. 常见问题

Q：悬浮球拉不出来？

A：检查悬浮窗权限；检查你是不是在某些全屏游戏里（少数 App 会屏蔽悬浮层）。

Q：AI 回复特别慢？

A：换个更快的模型（比如 glm-4-flash、qwen-turbo）；检查网络；本地模型看电脑资源。

Q：API Key 填了但对话还是报错？

A：90% 是 URL 填错了。去厂商文档里抄完整 URL，别自己拼。另外确认模型名存在。

Q：Markdown 不渲染？

A：设置 → 对话 → 确认"渲染 Markdown"开着。只有 AI 消息会渲染，你发的用户消息不会。

Q：背景图左上角有东西被挡住？

A：不用担心，Caret 的 TopBar 已经加了状态栏安全区 padding。但如果还是有问题，去设置调强调色或关背景图。

Q：本地 Ollama 手机连不上？

A：三件套确认：手机电脑同一 WiFi + 电脑防火墙放行 Ollama + Ollama 监听 0.0.0.0（不是 localhost）。

Q：开屏页显示的不是 Logo+短语，而是一个网页？

A：这是管理员在官网后台设置了"开屏页"，客户端会优先显示那个网页。如果管理员删除了，就恢复默认。

Q：公告卡片一直显示"暂无公告"？

A：还没在官网后台发布公告；或者 AnnouncementClient.BASE_URL 还没填。等官网完全上线后会填。

Q：我想换 API Key 怎么办？

A：设置 → Provider 编辑 → 找到那个 Provider → 编辑 → 粘贴新 Key 保存。

Q：支持多模态（图片）吗？

A：当前版本对话里可以上传图片，支持带图像输入的模型（比如 gpt-4o、glm-4v、qwen-vl-plus）。HTTP 请求里也可以发 multipart/form-data。

联系我们

有问题？官网 /feedback 里有两种联系方式：

• 邮箱：devynhub@outlook.com
• QQ：3869213454

祝使用愉快。

备注：QQ群：934473432