# 使用指南

## 首次运行

安装完整 APK 后打开应用，完成运行环境初始化，再点击“启动全部”。首页显示 AstrBot、NapCat 的运行状态，服务就绪后可以打开对应后台。

AstrBot 的模型、平台、插件和 QQ 登录沿用原项目的 WebUI。App 管理运行环境和服务，不额外维护一套重复的业务配置。

## 后台登录与缩放

内置浏览器会填写仍有效的初始登录信息，点击登录即可。AstrBot 首次登录要求修改密码；修改用户名或密码后，不再预填初始账号。NapCat 使用当前访问口令。

服务详情的“凭据”页可查看、隐藏和复制初始信息。两套后台默认使用 75% 缩放，可切换 100%、75%、50%、25%，也可从连接页打开外部浏览器。

新装空配置会准备 NapCat WebSocket 客户端 `ws://127.0.0.1:6199/ws`，token 留空，与 AstrBot 本机 OneBot 服务配对。使用明确的 IPv4 回环地址，避免 `localhost` 优先解析到 `::1` 时无法连接仅监听 IPv4 的服务。

旧版生成且仍保持默认参数的 `localhost` 连接，会在下次启动 NapCat 前备份并迁移到上述 IPv4 地址；自定义端口、token、其他目标及已停用的连接保留。原文件位于 `persistent/manager/onebot-ipv4-backup/`。手动配置连接时，请确认 AstrBot 的 OneBot 服务端口、路径和 token 与 NapCat 一致。

## APK 安装问题

完整包要求 Android 8.0 及以上、ARM64 系统。从项目 Release 下载完整 APK，并与同页 `SHA256SUMS` 中的摘要核对；下载未完成、文件被修改或摘要不一致时请重新下载。不要直接解压再重新压缩 APK。

正式构建同时携带 v1、v2、v3 签名，沿用长期证书。若安装器仍提示“安装包没有签名文件”，请提供手机型号、Android 版本和下载文件的 SHA-256，以便区分文件损坏与系统安装器兼容问题；仅凭该提示无法判断实际缺少哪种签名。

## 服务与局域网访问

首页可以启动、停止或重启全部服务，也可以分别控制。进入服务详情后，底栏切换为“概览 / 连接 / 凭据 / 日志”。

在对应服务的“连接”页开启局域网访问后，使用同一网络下的设备访问页面显示的地址。每套后台单独控制，原有登录鉴权保留；App 内仍使用本机地址。网络切换后请使用当前显示的局域网地址。

## 人设

人设页支持搜索、分类、预览和复制，列表可以上下滑动浏览，不显示滚动条。预设可“仅添加”到 AstrBot，也可“设为默认”或“恢复上次”。

内置预设参考玖帕喵市场精选整理：吃白饭的大肥鱼、月见八千代、DeepSeek娘，以及根据《拟人模板Ⅲ》补全的原创朋友“小满”。预览顶部注明发布者和改编范围，“来源”可打开原帖。预设排除破甲内容，移除不适用于 AstrBot 的框架工具与越权要求，保留角色特点并调整为短句聊天。

### 分段回复

人设约定日常使用完整短句、中文句末标点和真实换行；实际分开发送由 AstrBot 控制。在 AstrBot 后台的“分段回复”中开启功能，使用正则模式时可填写：

```regex
.*?[。？！\~…\n]+|.+$
```

此规则按中文句末标点、波浪号、省略号或换行分段，保留匹配的标点；空格和逗号不作为分隔符。英文章节或代码中的 `.?!` 不属于上述中文标点。预设避免在词中拖音和输出零碎旁白；教程、代码、链接等按任务需要保留完整格式。

AstrBot 4.29.3 对整段文本先检查字符长度：默认阈值为 150，超过 150 字符会直接发送，不再执行分段正则；恰好等于阈值仍进入分段处理。字符数包含标点和换行。需要分割更长的回复时，在后台按需提高阈值。App 不自动更改开关、阈值、流式输出或会话配置；模型也可能不完全遵循提示词。

### 自建与切换

点击列表上方的“人设市场”会在外部浏览器打开[玖帕喵人设市场](https://jiupamiao.asia/market)。选择喜欢的提示词后，回到 App 点击“新增人设”，填写名称、分类和提示词保存，简介和开场示例可以选填。

自建人设和内置预设都可在预览中删除。新增内容和删除记录保存在本地，更新 App 后保留；列表可以全部删除，也可以重新添加。删除仅影响本地列表，已导入 AstrBot 的副本和当前默认人设保留，在 AstrBot 后台中管理。

切换时会短暂停止 AstrBot 并恢复原启停状态，NapCat 保持运行。已在 AstrBot 中独立指定人设的会话继续使用原设置；预设内容可以在原后台继续编辑。

更新 App 不会覆盖已经导入 AstrBot 的同名人设。如果之前导入过同名旧稿并希望换成新版提示词，请在预览中复制提示词，在 AstrBot 后台编辑对应人设；旧版预设从本地目录替换后，其已导入副本仍会保留。开场白仅供预览，不会自动向会话发送。

## 后台运行

在“设置 → 后台运行”中，每项右侧显示当前状态。通知和电池优化读取系统状态，从系统设置返回后自动刷新；后台耗电、自启动、最近任务锁定没有可靠的通用检测接口，需要按说明完成设置后勾选“我已按说明检查并完成设置”，显示“已手动确认”。确认记录可随时取消，点击设置按钮不会自动标记完成。

每项详情只提供一个主要操作按钮，优先打开本机对应设置，无法直达时自动尝试备用入口。顶部将“系统检查”和“手动确认”分开计数。

不同厂商的设置名称和行为可能不同。允许自启动权限不等于 App 会在开机后自动启动服务；当前应用没有开机自动运行功能。手机系统终止应用后，可重新打开 App，按保存的运行意图恢复服务。

## QQ 掉线排查

QQ 若提示“已登录设备风险提醒”，并说明已将 Linux QQ 设备强制下线，属于 QQ 平台的账号风险处置。请先在官方 QQ 中按提示检查登录设备和账号安全，避免短时间内反复扫码、切换设备或重启重登。管理器的后台权限、自动重启以及更换接入组件都不能保证消除这类风控。

如果没有风险提示，可先看 NapCat 后台的 QQ 登录状态和服务日志：QQ 仍在线但 AstrBot 收不到消息时，检查 OneBot WebSocket 连接；服务进程已退出时，检查退出日志和安卓后台权限。更新组件前先备份，使用上游发布的兼容版本，并逐项观察变化。

## NapCat 开启反检测后崩溃或反复返回登录页

在当前 ARM64 PRoot 环境、NapCat 4.18.41 / Linux QQ 3.2.34-53644 组合中，**Module**、**Container** 已复现启动时 Worker 以代码 `11` 退出；仅关闭这两项、开启其余四项，也已复现登录后 `SIGSEGV` 和 Worker 退出，随后重新显示二维码。**JS 单独开启也已复现登录后崩溃**。主进程仍在运行时，内部 Worker 也可能已经重启。它与 QQ 平台提示账号登录失效是不同的问题。

当前组合建议将 **Hook、Window、Module、Process、Container、JS 六项全部关闭**。[NapCat 维护者的相关说明](https://github.com/NapNeko/NapCatQQ/issues/1813#issuecomment-4519412623)也指出不应使用 O3 拦截之外的反检测。**O3 Hook 模式是独立选项**，扫码和 WebSocket 配对不要求开启；保持原设置，出现问题时单独对比，不因“反检测”名称而全开。

管理器在下次启动 NapCat 前检查 `napcat.json`：若上述反检测已开启，会先保留修改前的完整文件，再关闭六项。O3 及其他选项保持原值，不清除 QQ 登录资料、OneBot 网络或业务配置；NapCat 日志会记录兼容调整。在 WebUI 再次开启后，下次启动时仍会应用此兼容处理。“设置 → 日志与诊断 → 环境检查与修复”可只读检查当前状态。

原配置保留在 Ubuntu 环境中的 `/persistent/manager/napcat-startup-compat/napcat.before-compat.json`，仅保留最近一次修改前的文件，可能含敏感信息。此处理仅针对上述已确认的组件组合，不改写其他版本配置，也不保证账号不掉线或反检测有效。

仍使用 v1.0.0 时，可先关闭上述六项后再重启；如果后台已经打不开，可覆盖安装包含此修复的新版后重新启动 NapCat，无需卸载应用或重装环境。

## Ubuntu 终端

在“设置 → 扩展组件 → Ubuntu 终端”打开。首次使用前先在首页准备 Ubuntu 环境；终端直接进入现有环境，无需启动 SSH 或额外下载终端组件。

点击标签栏右侧的 + 新建终端，点击标签在不同会话间切换，最多保留 8 个会话。程序正在一个终端输出日志时，可以另开终端执行其他命令，原会话继续运行。顶部键盘按钮左侧的 − / + 可快速调整字号。Ctrl 为单次组合键，下方提供 Esc、Tab 和方向键；多行粘贴前会要求确认。

长按输出可选择文字，拖动两端手柄调整选区，点击“复制”；也可全选，或在右上角菜单复制终端内容。滑动查看历史支持惯性滚动，不显示滚动条；查看历史时保留当前位置，点击“最新输出”回到底部并继续跟随日志。

返回页面、切换标签或打开其他应用不会主动停止终端；关闭标签只结束该会话和由此启动的进程。通知中的“结束全部终端”关闭所有终端进程。App 被系统终止、手机重启或运行环境维护会结束全部会话，命令不会自动重放。近期输出仅保存在内存中，每个会话最多 512 KiB，界面显示最多 2,000 行；命令与输出不写入管理器日志。

这里提供的是 PRoot Ubuntu 用户态环境，Ubuntu 的 root 不代表手机 Root。手动部署的软件需自行维护和备份，并遵守各自许可；不会自动加入首页服务管理。终端会话与 SSH 会话互相独立。

## SSH

“设置 → 扩展组件 → SSH 终端”默认已安装，按需启动。默认账号 `root`、端口 `8022`，密码随机生成，仅监听本机。

可以查看或修改密码、调整端口、单独开启局域网访问，也可卸载和重新安装 SSH 扩展。这里的 `root` 属于 Ubuntu 运行环境，不赋予手机 Root 权限。SSH 提供交互终端和命令执行，不包含 SFTP。

## 语言

在“设置 → 语言”选择跟随系统、简体中文或 English。语言选择保存在本机，切换时页面会重新创建，服务继续运行。Android 13 及以上也支持系统的应用语言设置。

这里只切换管理器界面、通知和自身提示。AstrBot、NapCat 的 WebUI 语言由各自项目控制；已有人设正文、用户输入和历史日志不翻译，不更改数据库标识或备份格式。

## cpolar 内网穿透

在“设置 → 扩展组件 → cpolar 内网穿透”安装。需先初始化 Ubuntu 环境；目前支持 ARM64 手机，按需从 [cpolar 官网](https://www.cpolar.com/download)下载 Linux ARM64 客户端 3.3.12，校验摘要并检查运行能力后安装，客户端不打入 APK。

安装后启动本机官方 WebUI，点击“打开后台”即可使用 cpolar 账号登录。官方页面会自动取得并保存 Authtoken，无需在 App 中单独复制令牌。默认提供 `ssh`、`astrbot`、`napcat` 三个隧道，分别使用创建时 SSH 扩展、AstrBot WebUI、NapCat WebUI 的实际端口（默认 8022、6185、6099）。随后在官方后台创建、编辑、删除、启停隧道和查看公网地址。已有自建隧道的配置保留；首次准备空配置时添加默认隧道，之后手动删除的预设不会反复生成。启动 cpolar 会恢复你在后台启用的隧道，停止 cpolar 会同时停止其后台及全部隧道。目标服务仍由 App 独立启停，例如使用 SSH 隧道前需启动 SSH 扩展。之后若修改服务端口，请同步修改官方后台中的隧道目标。

后台地址为 `http://127.0.0.1:9200`，默认只监听本机。内嵌页面默认 75% 缩放，可在右上角切换固定比例或打开外部浏览器。客户端状态和后台就绪状态分别检查；“后台已就绪”表示管理页可访问，隧道在线情况以官方后台为准。免费临时地址可能变化，域名、地区与带宽能力以 cpolar 账号套餐为准。请为需要开放的目标服务设置登录认证。

登录与隧道配置保存在应用私有目录的 `cpolar.yml`，WebUI 修改后继续使用同一份配置，不包含在 AstrBot 本机快照或便携备份中。日志隐藏已知令牌，支持实时跟随、暂停、复制和导出。运行环境维护时暂停并在维护结束后恢复。卸载扩展会清除客户端、配置与已保存的登录信息，保留两个项目及 SSH 的数据。

## Ubuntu 桌面与独立原版 QQ

在“设置 → 扩展组件 → Ubuntu 桌面”中点击“安装桌面”。App 已包含安装器与运行管理，首次安装联网获取 Ubuntu 软件源中的 Xvfb、Fluxbox、noVNC、中文字体等组件；无需在终端复制安装命令。安装期间会暂时停止机器人服务、SSH、cpolar 和终端会话，完成后恢复原来运行的服务，终端需手动重新打开。若安装中断，可恢复网络和存储空间后重试，日志页实时显示安装输出。

安装后点击“启动桌面 → 打开桌面”，直接在 App 内操作图形界面。桌面仅监听本机 `127.0.0.1:6081`，内嵌页面自动填写桌面访问密码；“连接”页可查看、隐藏或复制密码。离开页面不停止桌面，停止桌面会同时停止 App 管理的独立原版 QQ。

“原版 QQ”页可按需从腾讯官方下载独立 Linux ARM64 QQ，当前固定版本、地址、大小及 SHA-256 见 `app/src/main/assets/runtime/desktop/sources.json`。下载包约 196 MiB，解压后约 640 MiB；这份 QQ 不包含 NapCat，不修改现有 `/opt/qq`，数据独立保存在 `/manager/extensions/desktop/qq-home`。启动它会提示停止 NapCat；首页重新启动 NapCat 会停止这份独立 QQ。两边的数据均保留，App 不替用户扫码登录。

手动部署其他图形程序时，先在 App 启动桌面，然后从“连接”页复制图形环境配置，进入内置终端粘贴并执行，再按目标程序的官方教程操作。原版 QQ 程序位于 `/manager/extensions/desktop/qq/opt/QQ/qq`。安装完成后也提供 `desktop-start`、`qq-desktop` 命令；这些命令手动启动的进程由所在终端管理，不会重复接管 App 已启动的桌面。第三方程序的原生注入、权限及消息接入兼容性需单独确认。

桌面依赖与独立 QQ 均按需下载，不增加默认 APK 中的运行环境镜像体积。卸载扩展会停止相关进程、移除独立 QQ 程序与安装标记，保留独立 QQ 数据及 Ubuntu 共享依赖。此扩展的数据不在现有机器人快照或便携备份范围内；清除应用数据或重建运行环境前应自行备份重要文件。

## 内存与存储

首页的“本应用内存”按同一应用 UID 下可读取进程的 PSS 汇总，包含托管的服务进程；隔离的 WebView 渲染进程不在该统计内。“手机总内存”是设备物理内存，“应用占比”以它为分母。无法完整读取时会提示部分数据。

NapCat 中的系统 CPU/内存统计可能受到 Android 权限限制；无法取得有效数据时显示不可读取。存储使用在“设置 → 日志与诊断 → 存储使用”中独立查看，不与内存混合展示。

首次初始化或准备升级、修复环境时，若 App 可用空间低于保守预估，会显示实际可用量、建议预留量以及“仍然继续”按钮。这个估算只作提醒；环境已初始化后的日常启动不会再次按完整解包大小拦截。系统设置显示的剩余空间与 App 实际可写空间可能不同；空间耗尽仍会导致操作失败并影响手机使用，建议先清理存储。备份、恢复及更新中的其他空间检查仍按各自操作执行。

## 日志、备份与恢复

服务日志默认跟随最新输出，可以暂停、选择复制和脱敏导出。设置中的诊断入口用于环境检查、日志汇总和诊断包导出。

本机快照用于当前环境恢复，包含对应配置、数据库和 QQ 会话。自动快照默认最多 10 份、合计 2 GiB，可在设置中调整；超限时清理最旧且未受保护的自动快照，手动备份和回退依赖保留。

便携备份通过系统文件选择器导入/导出，包含配置、数据库和业务密钥，不包含 QQ 会话目录，当前要求运行组合匹配。卸载应用或清除数据也会删除本机备份；需要保留的数据应先导出到应用外。

## 更新

“设置 → 关于 → 检查更新”用于管理器 APK，AstrBot 与 NapCat 程序各有独立入口。检查与下载不自动安装；确认更新后创建一致性快照，系统安装器完成 APK 替换，随后重新打开 App。

AstrBot 程序更新会同时更新匹配的 WebUI，并要求适配现有 Python 和依赖。NapCat 可独立下载上游正式程序包并安装，保留配置、插件和 QQ 会话。更新后恢复原启停状态；QQ 原本停止时保持停止，不为检查更新而登录。若需要不同版本的 Linux QQ 或底层依赖，会提示先升级匹配的运行环境。

“应用与组件版本”中的“组件版本匹配”表示安装的组件版本与配套记录一致。它用于检查版本组合，QQ 登录和消息连接状态仍在服务概览中查看。

默认构建已接入 GitHub 签名通道。已是最新兼容版本时仍可查看说明并重新下载；下载完成后点击待安装更新，再确认备份与安装。管理器尚无已发布新版时会如实提示。发布者接入方式见[更新与分发](更新与分发.md)。