和你的 AI 伙伴，开始一场温柔的对话
原生 Android 客户端 · 服务器 / 本地双模式 · 深色玻璃拟态 UI
应用截图 · 功能特性 · Agent 模式 · 下载安装 · 双模式 · 从源码构建 · 更新日志 · 官方网站
中文 | English
 会话管理 |
 沉浸式聊天 |
 角色卡 |
 负一屏数据概览 |
 Token 用量 |
 更多功能 |
查看更多界面
 世界书 |
 角色记忆 |
 成就系统 |
 状态趋势与差分 |
 关系状态历程 |
 拓展功能 |
截图中的人物与对话均为虚构演示内容。可下载 README 本地演示数据包，在「更多 → 数据库管理」中导入并复现。
- 沉浸式对话 — Socket.IO 流式回复、乐观更新、多候选回复切换（swipes）、回复就地编辑、重新生成 / 停止生成、编辑并重新发送、生成期间消息排队与加急发送、消息分叉与多选操作、生成速度 tok/s
- 角色卡系统 — 完整字段编辑（描述 / 人格 / 首条消息 / 场景 / 规则 / 立绘），支持导入 SillyTavern 酒馆卡（PNG 嵌入式、v2 / v3 JSON）
- 角色运行时 — 六维关系系统、状态评估、记忆抽取、世界书注入、PromptStack 合成
- 世界书 — 条目 CRUD（关键词 / 常驻 / 选择 / 位置 / 优先级）、书信息编辑、多角色绑定、命中调试
- 故事图 — Canvas 树状布局呈现剧情分支，支持分支选择、回滚与重生，本地持久化
- 状态历程 — 角色状态随时间变化的可视化时间线
- 记忆管理 — 角色记忆与 Agent 长期记忆（按数据库档案隔离、检索化注入）的查看与编辑
- Agent 模式 — 多轮工具调用、可展开的实时进度卡片、子代理委派、任务列表与结构化问答、角色能力继承、原生浏览器、Android 设备操作、Linux 沙箱、PTY 终端与文件处理
- AI 配置中心 — 模型 / 温度 / max_tokens / top_p / 惩罚参数与停止字符串编辑、故障转移队列、一键测试连接
- AI 模型管理 — 模型 CRUD、应用 / 启用 / 停用 / 克隆、拉取可用模型列表、本地 AI 模型配置
- Token 用量 — 今日 / 本周 / 本月 / 累计 / 费用统计、CSV 导出、日期分组、会话 / 模型 / 用户排行、性能指标
- 语音与 TTS — 录音转写为文字（服务器模式）、TTS 试听
- Markdown 渲染 — 内独白折叠、全角括号斜体、带语言标签与复制按钮的代码块、横滑表格
- 工作区 — 文件引用、Markdown 预览、真全屏查看、编码自适应（UTF-8 / GBK）与下载
- 插件系统 — 本地模式支持内置模块与 ZIP JavaScript 插件，可在应用内提供插件页面（主题跟随、原生弹窗、多页面切换、宿主 API 与进度卡片），12 项权限按「清单声明 ∧ 用户授权」双条件生效，Agent 可通过
plugin_use工具安装、启停、卸载与自检插件；开发方式见插件开发指南 - 15+ 扩展功能 — API Keys、插件、频道、钩子、知识库、技能、任务中心、工具、工作流、MCP 服务器、消息过滤、登录令牌、成就、TTS / 生图实验室
- 系统设置 — 服务器地址切换、设置 JSON 编辑器、功能开关、数据维护、配置迁移、WebDAV 备份
- 深色玻璃拟态 — 液态玻璃底部导航栏、玻璃卡片、自定义弹窗与状态芯片
- 自定义主题色 — 配合流式占位骨架动画，等待也优雅
Agent 模式运行在本地模式中，让支持 Function Calling / Tool Use 的模型不只生成文字，还能在会话内浏览网页、操作文件、执行 Linux 命令并持续完成多步骤任务。
| 能力 | 说明 |
|---|---|
| 多轮工具执行 | 模型可连续规划和调用工具，同批只读工具并行执行；进度卡片实时显示思考、参数、结果、错误与执行耗时，用户展开状态不会因新工具事件而重置 |
| 子代理 | 独立任务可委派给拥有独立上下文的子代理，支持前台同步与后台异步运行、受限嵌套委派与后台并发上限；进度以独立卡片实时推送，并提供启用开关与嵌套深度 / 工具上限设置 |
| 会话工具集 | 工具按大类归组，可在聊天面板按大类或单工具开关当前会话的工具集并按会话持久化，默认全部启用；内置极简 / 标准 / 角色卡 / 安卓 / 全能模式与自定义模式，并可配置新会话默认工具集 |
| 角色扮演 Agent | 绑定角色的 Agent 会话可开启「继承完整角色能力」，加载角色卡、记忆、世界书与关系状态，注入现实时间连续性与昼夜节律，支持主动聊天与角色生活模拟 |
| 任务与问答 | todo_write 可折叠任务面板、ask_user_question 结构化问答（单选 / 复选 / 自由文本），配合 /goal 持久会话目标与 /spec 规格驱动开发 |
| 等待处理提醒 | 命令授权与结构化提问等待时自动登记，用户不在该会话时发送系统通知，会话列表展示「等待处理」标签，点击直达会话 |
| 原生浏览器 | 支持多标签页、点击、输入、滚动、前进/后退、JavaScript、视口与 User-Agent 切换 |
| 网页读取 | 可读取正文、动态 DOM 源码、交互骨架和结构化 URL，并支持 Cookie 登录态下的网页请求与文件下载 |
| 浏览器预览 | 聊天页可实时查看当前网页，支持全屏放大；AI 可截取当前页或长页面并交给视觉模型理解图片、图表和复杂布局 |
| Android 操作 | 无障碍驱动的点击 / 滑动 / 输入（控件编号定位 + 坐标手势回退）、设备信息 / 日历 / 闹钟 / 媒体控制等原生工具；工具截图可直接交给视觉模型理解 |
| 图片生成 | 可调用已配置的图像生成模型按文本提示词生成图片并内嵌展示，聊天消息长按菜单亦支持多供应商生图与图生图 |
| Linux 沙箱 | 内置 Alpine Linux + PRoot，支持安装软件包、运行脚本、启动后台进程和复用命令行环境，支持 python3 等交互式 REPL 会话与跨会话共享工作区（挂载于 /shared） |
| 会话终端 | Agent 会话右上角菜单可打开全屏 PTY 终端（VT/ANSI、256 色、Ctrl+C、Tab 补全与 vi/top 等全屏程序），直接操作该会话的 /workspace；配套沙箱文件浏览器支持目录浏览、≤16KB 文本文件编辑保存与大文件只读预览 |
| 文件与图片工具 | 支持读取、写入、精确编辑、列出、解析和发送工作区文件，也可调用视觉模型理解本地图片；文件变更以 git 摘要卡片与逐文件 diff 展示 |
| Skills 与 MCP | Agent 可读取已启用的本地 Skills，并调用已连接 MCP 服务提供的工具 |
| 运行保护 | 高风险命令需要确认，命令授权按指纹记忆（批准 git status 不会放行 git push），解释器与安装类命令不可记忆；工具参数会在执行前修复和校验，连续重复且无进展的调用会自动停止，最大工具调用次数可配置（默认 150） |
| Agent 设置 | 工具调用上限、输出与进度预览截断、浏览器 User-Agent / 视口 / JavaScript / 标签页上限、沙箱镜像源与 rootfs 重置、新会话默认工具集、自动长期记忆与自动 Skill 沉淀 |
| 后台执行 | Agent 工作期间启用前台服务和常驻通知，降低切到后台后任务被 Android 提前终止的概率 |
- 所有 Agent 会话共享同一套可写 Linux rootfs，因此通过
apk add安装的软件和/root数据可以复用。 - 每个 Agent 会话拥有独立的
/workspace，文件不会自动混入其他会话；跨会话共享的文件可放入挂载于/shared的共享工作区。 - 正常覆盖安装同签名的新 APK 会保留 rootfs、已安装软件和工作区；卸载应用或清除应用数据仍会删除这些内容。
- 后台进程可以跨同一会话的多次命令继续运行，但强制停止应用、重启手机或系统回收进程后需要重新启动。
Linux 沙箱目前仅支持
arm64-v8a设备。Agent 使用的模型应支持工具调用；网页截图和本地图片理解还需要配置可用的视觉模型。
| 服务器模式 | 本地模式 | |
|---|---|---|
| 后端 | 连接 NekoBot Web 后端 | 无需后端，直连 OpenAI 兼容 API |
| 通信 | REST + Socket.IO 实时流式推送 | 本地直接请求 AI API |
| 数据存储 | 服务器 + 本地缓存 | Room 数据库 + 会话工作区 + 可写 Linux rootfs |
| Agent | 由服务器能力决定 | 内置浏览器、Linux 沙箱、PTY 终端、插件页面、Skills、MCP、子代理与 Android 操作 |
| 适用场景 | 完整功能生态、多端同步 | 隐私优先、本地数据、自有 API Key、移动端 Agent |
要求 Android 8.0（API 26）及以上 · 应用内支持检查更新与下载安装
服务器模式
- 启动应用，在登录页输入服务器地址、用户名、密码
- 登录成功进入会话页，底部导航切换功能
- 聊天页发送消息后，AI 回复通过 Socket.IO 实时流式推送
- 设置页可修改服务器地址（写入后自动重建网络与 Socket 客户端）
本地模式
- 登录页切换至本地模式
- 在「本地 AI 模型」中配置 OpenAI 兼容 API 地址与密钥
- 数据全部存储于本地，支持会话 / 角色 / 世界书 / 记忆等完整功能
- 设置页可查看本地运行日志
Agent 模式
- 按本地模式完成模型配置，并确认聊天模型支持工具调用
- 在会话页新建会话时选择「Agent」
- 直接描述目标；AI 会按需使用浏览器、工作区、Linux、Skills 或 MCP 工具
- 点击进度卡片可查看每一步参数与结果；浏览器运行时可打开实时预览
- 点击聊天页右上角菜单中的「命令行」可直接进入当前会话沙箱
- 在聊天面板的「Agent 工具集」中可按大类或单个工具开关本会话可用工具，也可一键套用极简 / 标准 / 角色卡 / 安卓 / 全能模式，自定义选择按会话持久化
对需要写入或修改系统状态的命令，应用会弹出授权确认。输入
/yolo可为当前会话跳过普通命令确认，但高风险黑名单仍然生效，请仅在可信任务中使用。在会话工作区根目录放置AGENTS.md（不区分大小写），其内容会作为行为指导注入 Agent 每轮对话。
| 类别 | 选型 |
|---|---|
| 语言 | Kotlin 2.0.21 |
| UI | Jetpack Compose（BOM 2024.09.02）+ Material3 |
| 架构 | MVVM（BaseViewModel + StateFlow） |
| 异步 | Kotlin Coroutines 1.9.0 |
| 网络 | Retrofit 2.11 + OkHttp 4.12 + Gson |
| 实时通信 | socket.io-client-java 2.1.0 |
| 数据库 | Room 2.6.1（KSP 注解处理） |
| 图片加载 | Coil 2.7.0（crossfade + 256MB 磁盘缓存） |
| 导航 | Navigation Compose 2.8.2 |
| Agent 运行时 | Android WebView + Alpine Linux + PRoot |
| 构建 | Gradle 8.11.1 + AGP 8.9.1 + KSP |
展开构建指南（JDK 17+ / Android SDK 35）
1. 配置 SDK 路径
在项目根目录创建 local.properties：
sdk.dir=/path/to/Android/Sdk2. 编译
# Windows
gradlew.bat assembleDebug
# Linux / macOS
./gradlew assembleDebug产物：app/build/outputs/apk/debug/app-debug.apk
3. Release 构建
gradlew.bat assembleRelease产物：app/build/outputs/apk/release/app-release.apk
Release 构建复用 debug 签名配置，生成的 APK 可直接安装。
4. 安装到设备
adb install -r app/build/outputs/apk/debug/app-debug.apk项目结构
app/src/main/kotlin/com/nekobot/app/
├── MainActivity.kt # Activity 入口（隐私锁 / 分享与深链）
├── NekobotApp.kt # Application + ServiceContainer + Coil ImageLoader
├── data/
│ ├── local/
│ │ ├── ai/ # Agent Pipeline、工具循环、浏览器、Linux 沙箱与子代理
│ │ ├── automation/ # 本地自动化调度与通知
│ │ ├── db/ # Room 数据库（实体 / DAO / 迁移 / 内置工具）
│ │ ├── knowledge/ # RAG 知识库（检索 / 重排 / MMR）
│ │ ├── oauth/ # OAuth 登录与密钥存储
│ │ ├── plugin/ # ZIP 插件（清单校验 / 权限 / 宿主 API / 插件页面）
│ │ ├── security/ # Keystore 加密与安全存储
│ │ ├── LocalRepository.kt # 本地模式数据仓库（Room + 本地 AI）
│ │ └── PrefsManager.kt # SharedPreferences 封装
│ ├── model/Models.kt # 数据模型
│ ├── remote/
│ │ ├── ApiService.kt # Retrofit 接口
│ │ ├── AuthInterceptor.kt # Token 注入
│ │ ├── NetworkClient.kt # Retrofit 工厂
│ │ └── SocketManager.kt # Socket.IO 客户端
│ └── repository/
│ ├── NekobotRepository.kt # 服务器模式仓库
│ └── UnifiedRepository.kt # 模式统一入口（按 appMode 分发）
├── integration/ # 无障碍 / 通知监听 / 快捷方式 / 分享解析
├── service/
│ └── AgentForegroundService.kt # Agent 后台执行前台服务
├── update/UpdateChecker.kt # 应用内更新检查与安装
├── widget/ # 桌面小组件
└── ui/
├── BaseViewModel.kt # 统一 loading/error 处理
├── adaptive/ # 大屏 / 平板自适应布局
├── components/
│ ├── CommonComponents.kt # GlassCard、NekoDialog、ToggleChip 等
│ └── MarkdownText.kt # Markdown 渲染组件
├── navigation/
│ ├── NavGraph.kt # 路由图
│ ├── Routes.kt # 路由定义
│ └── LiquidGlassBottomBar.kt # 液态玻璃底部导航栏
├── screens/
│ ├── login/ # 登录与本地模式切换
│ ├── onboarding/ # 快速设置
│ ├── sessions/ # 会话列表 + 会话详情
│ ├── chat/ # 对话 + 工作区 + 多媒体内容
│ ├── characters/ # 角色卡列表 + 详情
│ ├── worldbook/ # 世界书列表 + 详情 + 命中调试
│ ├── memory/ # 角色记忆
│ ├── plot/ # 故事图
│ ├── statehistory/ # 状态历程
│ ├── tokens/ # Token 用量
│ ├── aiconfig/ # AI 配置中心 + 模型 + 故障转移 + 本地模型
│ ├── extensions/ # 扩展功能（插件 / 知识库 / 技能 / MCP 等）
│ ├── settings/ # 系统设置 + Agent 设置 + 数据维护 + 配置迁移 + WebDAV
│ ├── search/ # 全局搜索
│ └── more/ # 更多
└── theme/ # 颜色 / 排版 / 主题
| 权限 | 用途 |
|---|---|
INTERNET |
网络通信、Agent 浏览器与沙箱网络访问 |
ACCESS_NETWORK_STATE |
检测网络状态 |
RECORD_AUDIO |
语音输入（服务器模式） |
POST_NOTIFICATIONS |
会话通知与 Agent 后台运行状态 |
FOREGROUND_SERVICE / FOREGROUND_SERVICE_DATA_SYNC |
Agent 长任务在前台服务中继续执行 |
WAKE_LOCK |
Agent 执行期间避免 CPU 过早休眠 |
WRITE_EXTERNAL_STORAGE（Android 9 及以下） |
导出 Token 记录、Skill 等文件到公共下载目录 |
REQUEST_INSTALL_PACKAGES |
应用内检查更新后安装新版 APK |
USE_BIOMETRIC / USE_FINGERPRINT |
隐私锁的生物识别解锁 |
无障碍服务与通知监听服务均为可选开启，用于 Agent 的 Android 操作、通知读取与快捷回复；无障碍设置支持排除指定应用，自更新会校验 APK 包名与签名，插件网络请求禁止访问内网地址。
实时通信日志标签为 NekoSocket：
adb logcat -s NekoSocket:V欢迎提交 Issue 与 Pull Request！版本变更记录见 changelog.md，插件开发请阅读插件开发指南。