wehub/lyydfys--muyu-chat-agent
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity
Files
main
lyydfys--muyu-chat-agent/README.md
T
wehub-resource-sync 17c8236d9b docs: make Chinese README the default
2026-07-13 10:27:12 +00:00

16 KiB
Raw Permalink Blame History

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

MCA - MuYu Chat Agent

Android 本地优先 AI 工作区：本地 GGUF 聊天、用户自行配置的云端 API、模型管理，以及由用户控制的图像生成引擎。

Android CI Release License: MIT

MCA 是一款面向希望直接掌控模型、推理后端与云端 API 连接用户的 Android 原生、本地优先 AI 工作区。

项目当前聚焦于：

  • 通过 llama.cpp 进行本地 GGUF 聊天推理。
  • 基于 OpenAI 兼容协议与 Anthropic Messages 协议的云端聊天引擎。
  • 用户可配置的网页搜索，附带来源卡片与按轮次上下文注入。
  • 本地与云端图像生成引擎管理。
  • 面向 ModelScope 的模型发现与可断点续传下载。
  • 基于 Compose 的移动端 UI，涵盖聊天、模型管理、图像生成、智能体诊断、设置与本地 API 工具。

MCA 不包含模型权重或 API 密钥。用户需自备本地模型、云端端点及服务商凭证。

截图

来自 Android 应用的真机截图：

聊天 工作区 图像 模型推荐
Chat screen Workspace navigation Image generation screen Model recommendations
查看更多截图
设置 云端引擎 本地引擎 模型市场
Settings screen Cloud model engines Local model engines Model market
模型选择器 本地 API
Model picker Local API redacted

发布前已对本地 API 截图进行脱敏处理。

MCA demo walkthrough

上方轻量 GIF 由真机截图生成。更高画质的 MP4 见 docs/assets/demo/mca-demo.mp4。

状态

本仓库是一个活跃的 Android 应用工作区。聊天与模型管理界面已可用，而本地图像生成仍处于实验阶段，需按设备与模型包分别测试。

当前发布状态：

  • Alpha 版 APK 通过 GitHub 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 <key>；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. 下载最新 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。 快速来源指南：需要最快 API 密钥配置时选 Tavily 或 Brave；最看重隐私与控制时选自托管 SearxNG；页面正文提取需要帮助时选 Jina；自行运营搜索网关时选自定义 JSON。
  4. 启用网络或本地 API 工作流前，请先查看 docs/PERMISSIONS.md。
  5. 选择本地图像包或云端提供商协议前，请先查看 docs/MODEL_COMPATIBILITY.md。

Release APK 由项目维护者签名。Debug APK 不面向公众安装。

维护者可选的实时网页搜索冒烟测试：

$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='<key>'
.\gradlew :app:testDebugUnitTest --tests com.muyuchat.mca.WebSearchProviderTest.liveBraveSmokeUsesConfiguredKeyWhenProvided

$env:MCA_LIVE_TAVILY_API_KEY='<key>'
.\gradlew :app:testDebugUnitTest --tests com.muyuchat.mca.WebSearchProviderTest.liveTavilySmokeUsesConfiguredKeyWhenProvided

$env:MCA_LIVE_JINA_API_KEY='<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：

sdk.dir=/path/to/android-sdk

local.properties 已被 Git 忽略。

克隆

本仓库使用子模块管理原生推理后端：

git clone --recurse-submodules <repo-url>
cd mym

若克隆时未包含子模块：

git submodule update --init --recursive

构建

PowerShell：

$env:JAVA_HOME='<path-to-jdk-17>'
$env:ANDROID_HOME='<path-to-android-sdk>'
.\gradlew.bat :app:assembleDebug

Bash：

export JAVA_HOME=/path/to/jdk-17
export ANDROID_HOME=/path/to/android-sdk
./gradlew :app:assembleDebug

Debug APK 生成于：

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 专用补丁存放在：

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。

本地 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://<phone-lan-ip>: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 与 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。

贡献

MCA 仍处于早期阶段，更新频繁。在提交 issue 或 pull request 之前，请先阅读 CONTRIBUTING.md。

许可证

MCA 采用 MIT License 许可证。详见 LICENSE。

Reference in New Issue View Git Blame Copy Permalink