> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/lyydfys/MuYu-Chat-Agent) · [上游 README](https://github.com/lyydfys/MuYu-Chat-Agent/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 # MCA - MuYu Chat Agent Android 本地优先 AI 工作区：本地 GGUF 聊天、用户自行配置的云端 API、模型管理，以及由用户控制的图像生成引擎。 [](https://github.com/lyydfys/MCA/actions/workflows/android-ci.yml) [](https://github.com/lyydfys/MCA/releases) [](LICENSE) MCA 是一款面向希望直接掌控模型、推理后端与云端 API 连接用户的 Android 原生、本地优先 AI 工作区。 项目当前聚焦于： - 通过 `llama.cpp` 进行本地 GGUF 聊天推理。 - 基于 OpenAI 兼容协议与 Anthropic Messages 协议的云端聊天引擎。 - 用户可配置的网页搜索，附带来源卡片与按轮次上下文注入。 - 本地与云端图像生成引擎管理。 - 面向 ModelScope 的模型发现与可断点续传下载。 - 基于 Compose 的移动端 UI，涵盖聊天、模型管理、图像生成、智能体诊断、设置与本地 API 工具。 MCA 不包含模型权重或 API 密钥。用户需自备本地模型、云端端点及服务商凭证。 ## 截图 来自 Android 应用的真机截图： | 聊天 | 工作区 | 图像 | 模型推荐 | |---|---|---|---| |  |  |  |  |

查看更多截图

| 设置 | 云端引擎 | 本地引擎 | 模型市场 | |---|---|---|---| |  |  |  |  | | 模型选择器 | 本地 API | |---|---| |  |  | 发布前已对本地 API 截图进行脱敏处理。

 上方轻量 GIF 由真机截图生成。更高画质的 MP4 见 [docs/assets/demo/mca-demo.mp4](docs/assets/demo/mca-demo.mp4)。 ## 状态 本仓库是一个活跃的 Android 应用工作区。聊天与模型管理界面已可用，而本地图像生成仍处于实验阶段，需按设备与模型包分别测试。 当前发布状态： - Alpha 版 APK 通过 [GitHub Releases](https://github.com/lyydfys/MCA/releases). - 首个公开发布目标为 `arm64-v8a` Android 设备。 - 本地聊天是主要且稳定的本地路径。 - 用户在设置中配置搜索服务商后即可使用网页搜索。MCA 支持 SearxNG、Brave Search、Tavily、Jina Search 及自定义 JSON 搜索端点的手动、智能自动（smart-auto）与始终开启三种触发模式。 - 本地图像生成处于实验阶段，需要完整的模型包。请勿将手机端图像生成视为已保证稳定的特性。 ## 功能特性 - **本地聊天**：原生 `llama.cpp` 桥接、流式生成、停止支持、 token 速度标签、推理内容过滤，以及本地基准测试支持。 - **云端聊天**：用户自行配置的 OpenAI 兼容或 Anthropic Messages 端点，API 密钥在本地加密存储。 - **智能网页搜索**：用户可配置 SearxNG、Brave Search、Tavily、Jina Search 或自定义 JSON 搜索服务商。MCA 可识别 URL、检测显式搜索意图、扩展时效性或文档类查询、 对来源排序/去重、将结果摘要仅注入当前轮次，并在助手回复下方展示来源卡片。触发模式包括手动、 智能自动与始终开启；设置页面保留近期本地搜索诊断信息，涵盖触发原因、闭环验证证据、服务商错误、 部分扩展查询警告、扩展后的查询、来源数量、延迟、 可点击的来源 URL、服务商标签、来源摘要片段，以及基于可用来源、可读内容长度、独立主机 与安全拦截计算的本地来源质量评分。启用网页搜索后，即使尚未配置搜索 API， 也可直接读取 URL；关键词搜索仍需要 SearxNG、Brave、Tavily、Jina 或 自定义 JSON 端点。自定义 JSON 端点可使用诸如 `/search?q={query}&limit={max_results}` 的 URL 模板， 或常见的 `q/query/max_results` 参数。服务商端点可自托管，但默认可读页面抓取与 直接 URL 读取会出于安全考虑拦截 localhost、私有局域网、链路本地及保留地址。选择带密钥的 Jina Search 时， MCA 可在公开页面的直接可读内容过弱时回退到 Jina Reader，同时保持相同的私有网络防护。MCA 并发读取多个 直接 URL、扩展搜索查询与抓取的页面正文，以在移动网络下保持实时搜索响应。关键词搜索成功结果会在短时窗口内使用 内存本地缓存，避免重复调用同一服务商；直接 URL 读取不缓存，API 密钥也绝不会存入缓存条目。设置中的搜索测试 使用表单中当前填写的字段，用户可在保存前验证端点。 闭环自测会记录 MCA 是否生成了服务商结果、提示词上下文、来源卡片数据、质量评分及本地 诊断信息。设置中还提供无密钥的公开 JSON 自检填充项，用户可在输入自有服务商前验证集成路径。MCA 在应用中将该来源标记为 `公开 JSON 自检源`，因其仅为协议检查、覆盖范围有限，并非通用网页搜索引擎；生产环境应依赖可信或自托管的搜索服务。自定义 JSON 端点可返回顶层数组、包含 `results`、`items`、`data`、`hits` 或 `organic_results` 的对象，或 `data.results` 与 `response.items` 等嵌套变体。它接受常见的 URL/标题字段，如 `url`、`link`、`href`、`html_url`、`story_url`、`canonical_url`、`displayLink`、 `formattedUrl`、`source.url`、`title`、`full_name`、`story_title` 以及 `source.title`，以及摘要/正文字段，如 `summary`、`excerpt` 与 `pageContent`。智能查询扩展产生多次搜索时， MCA 会保留成功的来源，即使某次扩展查询失败。 Tavily 与 Jina 使用 `Authorization: Bearer `；Brave 使用 `X-Subscription-Token`，并同时支持 Web Search 端点与 LLM Context 端点，用于 AI grounding/RAG 风格摘要片段。公开 SearxNG 实例常会限流或禁用 JSON 响应，因此建议使用自托管或明确批准的端点以获得可靠搜索。 Brave 与 Tavily 官方 API 根 URL 会在预检与请求执行期间被接受并规范化为各自的 搜索路径。 - **图像页面**：MCA 图像工作区，支持本地/云端引擎切换、 提示词编辑器、生成状态、模板卡片与图像库。 - **本地图像引擎**：`stable-diffusion.cpp` 桥接，带进度/取消 钩子与感知模型包的模型注册。 - **模型中心**：本地/导入模型、ModelScope 推荐、可断点续传 下载、文件分类与引擎分组。 - **助手与角色卡**：多个本地助手，含系统提示词、 默认模型偏好、生成参数、记忆/搜索开关，以及 JSON 角色卡导入/导出。MCA 导出自身的 `mca.assistant.card` 模式， 并可导入常见嵌套角色卡 `data` 字段为可用的 系统提示词。 - **智能体诊断**：本地设备画像、模型推荐、 基于基准测试的调优，以及可解释的参数方案。 - **本地 API**：面向可信同设备与 同局域网客户端的 OpenAI 兼容本地服务器，包括 `/v1/models`、`/v1/chat/completions`、JSON 回复与 SSE 流式传输。 ## 安装 从 [GitHub Releases](https://github.com/lyydfys/MCA/releases). 下载最新 alpha 版 APK。Android 可能会要求你允许通过浏览器或文件管理器安装。 APK 不包含模型权重或云端凭据。安装后请： 1. 添加本地 GGUF 聊天模型，或配置云端聊天引擎。 2. 如需云端或本地图像生成，请配置图像引擎。 3. 如需实时搜索，请在设置中配置网页搜索。你可以使用自托管 SearxNG 端点、Brave Search、Tavily、Jina Search，或兼容的自定义 JSON 端点；测试当前表单值后，再选择手动、智能自动或始终开启触发模式。Brave 可使用 `/res/v1/web/search` 进行常规搜索，或使用 `/res/v1/llm/context` 获取面向 grounding 的摘要片段；Brave/Tavily 官方根 URL 会自动填入常规搜索路径。直接页面读取会拒绝 localhost、局域网、链路本地和保留地址，除非开发版显式启用私有网络抓取。完整配置、触发模式、来源卡片与故障排除指南见 [docs/WEB_SEARCH.md](docs/WEB_SEARCH.md)。 快速来源指南：需要最快 API 密钥配置时选 Tavily 或 Brave；最看重隐私与控制时选自托管 SearxNG；页面正文提取需要帮助时选 Jina；自行运营搜索网关时选自定义 JSON。 4. 启用网络或本地 API 工作流前，请先查看 [docs/PERMISSIONS.md](docs/PERMISSIONS.md)。 5. 选择本地图像包或云端提供商协议前，请先查看 [docs/MODEL_COMPATIBILITY.md](docs/MODEL_COMPATIBILITY.md)。 Release APK 由项目维护者签名。Debug APK 不面向公众安装。 维护者可选的实时网页搜索冒烟测试： ```powershell $env:MCA_LIVE_WEB_SEARCH_TEST='true' .\gradlew :app:testDebugUnitTest --tests com.muyuchat.mca.WebSearchProviderTest.liveDirectUrlSmokeReadsRealWebPageWhenEnabled $env:MCA_LIVE_SEARXNG_ENDPOINT='https://your-searxng.example' .\gradlew :app:testDebugUnitTest --tests com.muyuchat.mca.WebSearchProviderTest.liveSearxngSmokeUsesConfiguredEndpointWhenProvided $env:MCA_LIVE_BRAVE_API_KEY='' .\gradlew :app:testDebugUnitTest --tests com.muyuchat.mca.WebSearchProviderTest.liveBraveSmokeUsesConfiguredKeyWhenProvided $env:MCA_LIVE_TAVILY_API_KEY='' .\gradlew :app:testDebugUnitTest --tests com.muyuchat.mca.WebSearchProviderTest.liveTavilySmokeUsesConfiguredKeyWhenProvided $env:MCA_LIVE_JINA_API_KEY='' .\gradlew :app:testDebugUnitTest --tests com.muyuchat.mca.WebSearchProviderTest.liveJinaSmokeUsesConfiguredKeyWhenProvided $env:MCA_LIVE_CUSTOM_JSON_ENDPOINT='https://hn.algolia.com/api/v1/search' .\gradlew :app:testDebugUnitTest --tests com.muyuchat.mca.WebSearchProviderTest.liveCustomJsonClosedLoopBuildsPromptSourcesAndDiagnosticsWhenProvided ``` ## 仓库结构 - `:app` - Android 应用、导航、ViewModel、云端/本地提供商。 - `:core:native` - `llama.cpp` 本地聊天的 C++/JNI 桥接。 - `:core:sd-native` - `stable-diffusion.cpp` 本地图像生成的 C++/JNI 桥接。 - `:core:engine` - 单活跃生成推理服务。 - `:core:modelstore` - GGUF 导入、清单、SHA-256、托管模型存储。 - `:core:download` - ModelScope 解析、文件列表与可恢复下载。 - `:core:telemetry` - 运行时指标、SoC 检测与 JSONL 日志。 - `:core:deviceprofile` - 设备能力与热特性分析。 - `:core:tuning` - 参数方案生成。 - `:core:benchmark` - 简短本地基准测试运行器。 - `:core:advisor` - 本地推荐引擎与 agent 日志。 - `:api:local` - AIDL 服务与回环 REST 服务器骨架。 - `:feature:chat` - 聊天与图像生成 UI。 - `:feature:agent` - agent 诊断 UI。 - `:feature:modelhub` - 模型管理 UI。 - `:feature:settings` - 运行时、日志与本地 API UI。 ## 构建要求 - Android Studio 或命令行 Gradle。 - JDK 17。 - Android SDK，包含： - 与 `compileSdk` 匹配的 Android 平台。 - Android 构建工具。 - Gradle 配置的 CMake 3.31.6 或兼容版本。 - 与 `gradle/libs.versions.toml` 匹配的 Android NDK。 创建本地 `local.properties` 文件，或设置 `ANDROID_HOME`： ```properties sdk.dir=/path/to/android-sdk ``` `local.properties` 已被 Git 忽略。 ## 克隆 本仓库使用子模块管理原生推理后端： ```bash git clone --recurse-submodules cd mym ``` 若克隆时未包含子模块： ```bash git submodule update --init --recursive ``` ## 构建 PowerShell： ```powershell $env:JAVA_HOME='' $env:ANDROID_HOME='' .\gradlew.bat :app:assembleDebug ``` Bash： ```bash export JAVA_HOME=/path/to/jdk-17 export ANDROID_HOME=/path/to/android-sdk ./gradlew :app:assembleDebug ``` Debug APK 生成于： ```text app/build/outputs/apk/debug/ ``` ## 原生后端 ### 本地聊天 `core/native` 构建 `libmca_native.so`。存在 `third_party/llama.cpp` 时，该模块会链接 `llama.cpp` Android CPU 后端。项目在 `llama.cpp` 暂时不可用的开发构建中保留桩（stub）回退。 ### 本地图像生成 `core/sd-native` 针对 `third_party/stable-diffusion.cpp` 构建 `libmca_sd_native.so`。MCA 将其 Android 专用补丁存放在： ```text third_party/patches/stable-diffusion.cpp-mca-android.patch ``` Gradle 会在原生 CMake 构建前按需应用此补丁。 本地图像生成对模型包敏感。部分较新的图像模型需要在同一引擎目录中包含扩散模型以及 VAE/AE 与文本编码器/LLM 组件。该能力目前处于实验阶段，在推广为稳定功能前应在每台目标设备上验证。 ## 模型与 API 兼容性 当前兼容性矩阵（涵盖本地 GGUF 聊天、OpenAI 兼容聊天、Anthropic Messages、OpenAI Images、DashScope Image、自定义图像路径与实验性本地图像包）见 [docs/MODEL_COMPATIBILITY.md](docs/MODEL_COMPATIBILITY.md)。 ## 本地 API MCA 可通过 OpenAI 兼容 API 向受信任客户端暴露当前已加载的本地聊天模型。 当你希望其他应用、浏览器、桌面客户端或本地工具与手机上运行的模型对话时，可使用此功能。 推荐客户端设置： | Field | Value | |---|---| | Protocol | OpenAI-compatible | | Same-device Base URL | `http://127.0.0.1:11435/v1` | | Same-LAN Base URL | `http://:11435/v1` | | API key | 在 MCA 设置 -> 本地 API 中生成 | | Model | 从 `/v1/models` 选择，或手动输入返回的模型 `id` | 支持的路径： - `GET /health` - `GET /v1/models` - `POST /v1/chat/completions` - `GET /`（内置网页聊天页） `/v1/chat/completions` 支持标准 JSON 响应，`stream=true` 支持 Server-Sent Events（SSE）。同局域网访问需启用应用内“开放端口”开关，且仅应在受信任网络中使用。 ## 隐私 - 本地聊天与本地图像生成在设备上运行。 - 云端聊天与云端图像生成会将提示词发送至用户配置的提供商端点。 - 云端 API 密钥在本地存储，并由 Android Keystore 加密保护。 - 本仓库不包含 API 密钥、模型权重或私人用户数据。 更多详情见 [PRIVACY.md](PRIVACY.md) 与 [docs/PERMISSIONS.md](docs/PERMISSIONS.md)。 ## 路线图 - **v0.1 alpha**：本地聊天、云端聊天、云端图像引擎、图像工作区、模型管理、面向 ModelScope 的下载与发布打包。 - **v0.2 alpha**：智能网页搜索、来源卡片、角色卡助手、本地 API 兼容性修复、网页搜索诊断与发布级兼容性文档。 - **v0.3**：稳定本地图像包、改进设备兼容性报告，并优化图像生成进度/取消行为。 MCA 有意不捆绑模型权重。模型推荐与下载来源必须遵守各上游模型的许可证。 ## 第三方代码 本仓库通过子模块（submodule）引用上游原生项目： - `llama.cpp` - MIT License. - `stable-diffusion.cpp` - MIT License. 请参阅 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。 ## 贡献 MCA 仍处于早期阶段，更新频繁。在提交 issue 或 pull request 之前，请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 MCA 采用 MIT License 许可证。详见 [LICENSE](LICENSE)。